mcp-browser-extension 0.9.29 → 0.9.30

package/dist/shared/page-fns.d.ts

@@ -16,12 +16,18 @@
  * One resolver, used by every op, is what closes it.
  */
 /** Ops the page-side dispatcher understands. */
-export type PageOpName = 'probe' | 'text' | 'html' | 'click' | 'type' | 'focus' | 'point' | 'hover' | 'select' | 'measure' | 'scroll' | 'storage' | 'waitSelector' | 'waitFor';
+export type PageOpName = 'probe' | 'text' | 'html' | 'click' | 'check' | 'type' | 'focus' | 'point' | 'hover' | 'select' | 'measure' | 'scroll' | 'storage' | 'waitSelector' | 'waitFor';
 export interface PageOpArgs {
     op: PageOpName;
     selector?: string | null;
     text?: string;
     clear?: boolean;
+    /** type: send keydown/keypress/keyup around each character. */
+    keyEvents?: boolean;
+    /** type: press Enter after the text (submits the field's form like a person would). */
+    pressEnter?: boolean;
+    /** check: the state a checkbox/radio should end up in. */
+    checked?: boolean;
     outer?: boolean;
     values?: string[];
     x?: number | null;

package/dist/shared/page-fns.js

@@ -208,6 +208,18 @@ function pageOp(a) {
                 el.click();
                 return { found: true };
             }
+            case 'check': {
+                if (!el)
+                    return { found: false };
+                // Click only when the state differs: a click toggles, so clicking an
+                // already-checked box to "check" it would clear it.
+                const box = el;
+                if (box.checked !== (a.checked !== false)) {
+                    el.scrollIntoView({ block: 'center' });
+                    el.click();
+                }
+                return { found: true, checked: box.checked };
+            }
             case 'type': {
                 if (!el)
                     return { found: false };
@@ -226,9 +238,32 @@ function pageOp(a) {
                 if (!node)
                     return { found: false };
                 node.focus();
-                const next = (a.clear ? '' : node.value ?? '') + (a.text ?? '');
-                setValue(node, next);
+                if (a.keyEvents) {
+                    // One character at a time, each inside its own key events, for pages
+                    // that react to keystrokes rather than to the value.
+                    if (a.clear)
+                        setValue(node, '');
+                    for (const ch of a.text ?? '') {
+                        const ev = { key: ch, bubbles: true, cancelable: true };
+                        const go = node.dispatchEvent(new KeyboardEvent('keydown', ev));
+                        if (go && node.dispatchEvent(new KeyboardEvent('keypress', ev)))
+                            setValue(node, (node.value ?? '') + ch);
+                        node.dispatchEvent(new KeyboardEvent('keyup', ev));
+                    }
+                }
+                else {
+                    setValue(node, (a.clear ? '' : node.value ?? '') + (a.text ?? ''));
+                }
                 node.dispatchEvent(new Event('change', { bubbles: true }));
+                if (a.pressEnter) {
+                    const ev = { key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true, cancelable: true };
+                    const go = node.dispatchEvent(new KeyboardEvent('keydown', ev)) && node.dispatchEvent(new KeyboardEvent('keypress', ev));
+                    node.dispatchEvent(new KeyboardEvent('keyup', ev));
+                    // Synthetic key events never trigger implicit submission; do what the
+                    // browser would for Enter in a single-line field of a form.
+                    if (go && node instanceof HTMLInputElement && node.form)
+                        node.form.requestSubmit();
+                }
                 return { found: true };
             }
             case 'focus': {

package/dist/shared/policy.js

@@ -34,6 +34,12 @@ const READ_CONTENT = new Set([
     'frames_list',
     'observers',
     'print_pdf',
+    // The page's accessibility tree, its cookies (session secrets), and its
+    // web storage are content too. A storage write is refused in safe mode by
+    // the extension's storage handler; the domain gate here covers every op.
+    'snapshot',
+    'get_cookies',
+    'storage',
 ]);
 /** Content-mutating actions — URL-gated AND mutation-gated. */
 const MUTATE_CONTENT = new Set([
@@ -44,6 +50,7 @@ const MUTATE_CONTENT = new Set([
     'hover',
     'scroll',
     'fill_form',
+    'select_option',
 ]);
 /** Navigation — URL-gated by the DESTINATION url, and mutation-gated. */
 const NAVIGATION = new Set([
@@ -72,7 +79,9 @@ function isUrlGated(method) {
         MUTATE_CONTENT.has(method) ||
         NAVIGATION.has(method) ||
         method === 'eval' ||
-        method === 'upload_file');
+        method === 'upload_file' ||
+        // Gated on where the bytes come from: the URL when one is given, else the tab.
+        method === 'download_file');
 }
 // ---------------------------------------------------------------------------
 // Domain matching

package/dist/shared/snapshot.js

@@ -72,6 +72,13 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             if (t)
                 return t;
         }
+        // <label for> or a wrapping <label>: how ordinary forms name their fields.
+        const labels = el.labels;
+        if (labels && labels.length > 0) {
+            const t = Array.from(labels).map((l) => l.innerText).join(' ').replace(/\s+/g, ' ').trim();
+            if (t)
+                return t;
+        }
         const ph = el.getAttribute('placeholder');
         if (ph)
             return ph.trim();
@@ -113,8 +120,11 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
     // recursively. Defensive against null/closed shadow roots and re-visits.
     const seen = new Set();
     const candidates = [];
+    // Gather past `max` so hidden candidates dropped below still leave enough to
+    // fill it, and so a page with more than `max` can be reported as truncated.
+    const cap = Math.max(max * 2, max + 50);
     const collect = (root) => {
-        if (candidates.length >= max)
+        if (candidates.length >= cap)
             return;
         let matched;
         try {
@@ -124,7 +134,7 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             matched = [];
         }
         for (let i = 0; i < matched.length; i++) {
-            if (candidates.length >= max)
+            if (candidates.length >= cap)
                 break;
             const el = matched[i];
             if (seen.has(el))
@@ -142,7 +152,7 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             hosts = [];
         }
         for (let i = 0; i < hosts.length; i++) {
-            if (candidates.length >= max)
+            if (candidates.length >= cap)
                 break;
             const sr = hosts[i].shadowRoot;
             if (sr)
@@ -230,7 +240,8 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
                 break;
             picked.push(read(el));
         }
-        truncated = els.length > picked.length;
+        // At the cap there may be more on the page than were even looked at.
+        truncated = els.length > picked.length || candidates.length >= cap;
     }
     // -- phase 2: writes (one attribute per returned node) ----------------------
     const nodes = [];

package/dist/src/executor/cdp-executor.d.ts

@@ -97,6 +97,9 @@ export declare class CdpExecutor implements Executor {
     selectOption(t: Target, values: string[], opts?: {
         tabId?: TabId;
     }): Promise<ActionOk>;
+    setChecked(t: Target, checked: boolean, opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
     fill(t: Target, value: string, opts?: {
         tabId?: TabId;
     }): Promise<ActionOk>;

package/dist/src/executor/cdp-executor.js

@@ -272,8 +272,15 @@ class CdpExecutor {
         catch (err) {
             const msg = err.message ?? '';
             if (CLOSED_TARGET.test(msg)) {
+                const stale = this.context;
                 this.context = null;
                 this.tabs.clear();
+                // A browser we launched is ours to close; otherwise the relaunch on the
+                // next call leaves this one running. Never close the user's Chrome.
+                if (this.opts.mode !== 'connect' && this.launched) {
+                    this.launched = false;
+                    void stale?.close().catch(() => undefined);
+                }
                 throw new types_1.ExecutorError('DETACHED', 'browser target closed or crashed; reconnect and retry');
             }
             throw err;
@@ -397,6 +404,13 @@ class CdpExecutor {
             return this.ok;
         });
     }
+    async setChecked(t, checked, opts) {
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            await this.locator(p, t).setChecked(checked);
+            return this.ok;
+        });
+    }
     async fill(t, value, opts) {
         return this.guard(async () => {
             const p = await this.resolveTab(opts?.tabId);

package/dist/src/executor/extension-executor.js

@@ -168,10 +168,20 @@ class ExtensionExecutor {
         return (await this.send('type', { ...targetParams(t), ...frameParams(opts), text: value, clear: true, keyEvents: false }, { tabId: opts?.tabId }));
     }
     async fillFields(fields, opts) {
-        // An extension that predates the op never advertised it: let the caller go field by field.
-        if (!this.bridge.hasCap(this.activeProfile(), protocol_1.WIRE_CAP_FILL_FORM))
-            return null;
-        const res = (await this.send('fill_form', { ops: fields, ...frameParams(opts) }, { tabId: opts?.tabId, timeoutMs: (0, protocol_1.fillFormTimeoutMs)(fields.length) }));
+        // No capability pre-check alone: a server relaying through another one (a
+        // second AI session) cannot see the extension's caps, so ask and read the
+        // answer. An extension that predates the op says it has no such method:
+        // then let the caller go field by field.
+        let res;
+        try {
+            res = (await this.send('fill_form', { ops: fields, ...frameParams(opts) }, { tabId: opts?.tabId, timeoutMs: (0, protocol_1.fillFormTimeoutMs)(fields.length) }));
+        }
+        catch (err) {
+            if (!this.bridge.hasCap(this.activeProfile(), protocol_1.WIRE_CAP_FILL_FORM) && err instanceof types_1.ExecutorError && /unhandled method/.test(err.message)) {
+                return null;
+            }
+            throw err;
+        }
         if (res.error) {
             // Say how far the batch got: the fields before this one DID land, and a
             // blind retry of the whole form would write them a second time.

package/dist/src/executor/types.d.ts

@@ -361,6 +361,10 @@ export interface Executor {
     } & FrameOpts): Promise<{
         filled: number;
     } | null>;
+    /** Put a checkbox/radio into `checked` (no-op when it already is). */
+    setChecked?(t: Target, checked: boolean, opts?: {
+        tabId?: TabId;
+    } & FrameOpts): Promise<ActionOk>;
     /** Every frame of a tab that the extension can inject into, with its URL. */
     framesList?(opts?: {
         tabId?: TabId;

package/dist/src/mcp/helpers.js

@@ -166,8 +166,17 @@ async function fillForm(ex, args) {
         for (const { selector, value } of ops) {
             const target = { selector };
             if (typeof value === 'boolean') {
-                // Checkbox/radio: a click toggles it.
-                await ex.click(target, opts);
+                // Checkbox/radio: set the state. A bare click toggles, so it is only
+                // right for a backend that cannot set it, and only to turn it on.
+                if (ex.setChecked)
+                    await ex.setChecked(target, value, opts);
+                else if (value)
+                    await ex.click(target, opts);
+                else {
+                    // Unticking needs the current state, which this backend cannot read;
+                    // a silent no-op would report a field as filled that was not.
+                    throw new types_1.ExecutorError('UNSUPPORTED', `cannot set ${selector} to unchecked with this browser backend; update the MCP Browser Extension`);
+                }
             }
             else {
                 await ex.fill(target, value, opts);

package/dist/src/mcp/tools.js

@@ -105,7 +105,7 @@ const maxBytesField = zod_1.z
 const waitUntilField = zod_1.z.enum(['load', 'domcontentloaded', 'networkidle']).describe('When to consider navigation done').optional();
 exports.TOOL_DEFINITIONS = [
     { name: 'tabs_list', description: 'List open browser tabs.', inputSchema: {} },
-    { name: 'tab_select', description: 'Make a tab active by tabId.', inputSchema: { tabId: zod_1.z.string() } },
+    { name: 'tab_select', description: "Make a tab the agent's tab by tabId, in the background: calls without tabId go to it and the user stays on their own tab. Pass show:true only to bring it to the front for the user.", inputSchema: { tabId: zod_1.z.string(), show: zod_1.z.boolean().optional() } },
     { name: 'tab_new', description: "Open a NEW tab (optionally at a URL) in the background, leaving the user's tab alone; it becomes the agent's tab, where calls without tabId go. Pass active:true to show it to the user.", inputSchema: { url: zod_1.z.string().optional(), active: zod_1.z.boolean().optional() } },
     { name: 'tab_close', description: 'Close a tab by tabId.', inputSchema: { tabId: zod_1.z.string() } },
     { name: 'navigate', description: "Navigate the agent's tab to a URL, replacing its page. With no agent's tab yet it opens one in the background: the user's own tab is only navigated when you pass its tabId.", inputSchema: { url: zod_1.z.string(), tabId: tabIdField, waitUntil: waitUntilField, failOnAuthWall: authWallField } },
@@ -707,14 +707,27 @@ exports.TOOL_HANDLERS = {
     tabs_list: async (_a, ctx) => (0, envelopes_1.jsonResult)(await ctx.ex.tabsList()),
     tab_select: async (a, ctx) => {
         await gate(ctx, 'tab_select');
-        const tab = await ctx.ex.tabSelect((0, validators_1.requireString)(a, 'tabId'));
+        const id = (0, validators_1.requireString)(a, 'tabId');
+        // Showing the tab pulls the person off whatever they are doing, so only on request.
+        if ((0, validators_1.optionalBoolean)(a, 'show') === true) {
+            const tab = await ctx.ex.tabSelect(id);
+            workTab = tab.tabId; // an explicit pick: later calls follow it
+            return (0, envelopes_1.jsonResult)(tab);
+        }
+        const tab = (await ctx.ex.tabsList()).find((t) => t.tabId === id);
+        if (!tab)
+            throw new validators_1.McpToolError(`no open tab with tabId ${id}; call tabs_list for the current ids`);
         workTab = tab.tabId; // an explicit pick: later calls follow it
-        return (0, envelopes_1.jsonResult)(tab);
+        return (0, envelopes_1.jsonResult)({ ...tab, shown: false });
     },
     tab_new: async (a, ctx) => {
         await gate(ctx, 'tab_new');
+        // Opening a tab at a URL loads it like navigate does, so gate it the same way.
+        const url = (0, validators_1.optionalString)(a, 'url');
+        if (url !== undefined)
+            await gate(ctx, 'navigate', { url });
         // Background unless asked: focusing it would pull the person off their tab.
-        const tab = await ctx.ex.tabNew((0, validators_1.optionalString)(a, 'url'), { active: (0, validators_1.optionalBoolean)(a, 'active') ?? false });
+        const tab = await ctx.ex.tabNew(url, { active: (0, validators_1.optionalBoolean)(a, 'active') ?? false });
         workTab = tab.tabId;
         return (0, envelopes_1.jsonResult)(tab);
     },
@@ -948,7 +961,11 @@ exports.TOOL_HANDLERS = {
     },
     get_cookies: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) }); // reads tab-scoped secrets; same domain gate as content reads
-        return (0, envelopes_1.jsonResult)(await ctx.ex.getCookies({ tabId: tabId(a), url: (0, validators_1.optionalString)(a, 'url') }));
+        // Cookies for another URL are that site's secrets: it must be allowed too.
+        const url = (0, validators_1.optionalString)(a, 'url');
+        if (url !== undefined)
+            await gate(ctx, 'get_text', { url });
+        return (0, envelopes_1.jsonResult)(await ctx.ex.getCookies({ tabId: tabId(a), url }));
     },
     storage: async (a, ctx) => {
         const op = (0, validators_1.requireString)(a, 'op');
@@ -1054,11 +1071,14 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.jsonResult)(res);
     },
     download_file: async (a, ctx) => {
-        await gate(ctx, 'download_file');
         const url = (0, validators_1.optionalString)(a, 'url');
         const target = (0, validators_1.optionalTarget)(a);
         if (!url && !target)
             throw new validators_1.McpToolError('provide "url" or a target (selector|ref)');
+        // By URL, the bytes come from that URL with the person's cookies: gate the
+        // URL, not whichever tab the agent is on. By element, gate the tab it is in
+        // (the extension then gates where the link leads).
+        await gate(ctx, 'download_file', url ? { url } : { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.download({ url, target, tabId: tabId(a), suggestedName: (0, validators_1.optionalString)(a, 'suggestedName') }));
     },
     upload_file: async (a, ctx) => {
@@ -1074,9 +1094,20 @@ exports.TOOL_HANDLERS = {
         if (!ctx.policy.uploadsDir) {
             throw new validators_1.McpToolError('upload denied: uploads require an --uploads-dir to be configured (refusing unrestricted local-file access)');
         }
-        const dir = (0, node_path_1.resolve)(ctx.policy.uploadsDir);
+        // Compare real paths: Chrome reads a symlink's target, so a link inside the
+        // dir pointing outside it must be judged by where it points.
+        const real = (p) => {
+            try {
+                return (0, node_fs_1.realpathSync)(p);
+            }
+            catch {
+                // Not there (yet): resolve its folder, so /tmp vs /private/tmp still compare.
+                return p === (0, node_path_1.dirname)(p) ? p : (0, node_path_1.join)(real((0, node_path_1.dirname)(p)), (0, node_path_1.basename)(p));
+            }
+        };
+        const dir = real((0, node_path_1.resolve)(ctx.policy.uploadsDir));
         for (const f of files) {
-            const abs = (0, node_path_1.resolve)(f);
+            const abs = real((0, node_path_1.resolve)(f));
             if (abs !== dir && !abs.startsWith(dir + node_path_1.sep)) {
                 throw new validators_1.McpToolError(`upload denied: "${f}" is outside the allowed uploads dir (${dir})`);
             }

package/extension-dist/background.js

@@ -162,7 +162,13 @@
     // All three are page CONTENT and gate exactly like the reads above.
     "frames_list",
     "observers",
-    "print_pdf"
+    "print_pdf",
+    // The page's accessibility tree, its cookies (session secrets), and its
+    // web storage are content too. A storage write is refused in safe mode by
+    // the extension's storage handler; the domain gate here covers every op.
+    "snapshot",
+    "get_cookies",
+    "storage"
   ]);
   var MUTATE_CONTENT = /* @__PURE__ */ new Set([
     "click",
@@ -171,7 +177,8 @@
     "press",
     "hover",
     "scroll",
-    "fill_form"
+    "fill_form",
+    "select_option"
   ]);
   var NAVIGATION = /* @__PURE__ */ new Set([
     "navigate",
@@ -188,7 +195,8 @@
     return MUTATE_CONTENT.has(method) || NAVIGATION.has(method) || TAB_MUTATE.has(method);
   }
   function isUrlGated(method) {
-    return READ_CONTENT.has(method) || MUTATE_CONTENT.has(method) || NAVIGATION.has(method) || method === "eval" || method === "upload_file";
+    return READ_CONTENT.has(method) || MUTATE_CONTENT.has(method) || NAVIGATION.has(method) || method === "eval" || method === "upload_file" || // Gated on where the bytes come from: the URL when one is given, else the tab.
+    method === "download_file";
   }
   function hostOf(url) {
     try {
@@ -377,6 +385,11 @@
         const t = labelledby.split(/\s+/).map((id) => document.getElementById(id)?.innerText ?? "").join(" ").trim();
         if (t) return t;
       }
+      const labels = el.labels;
+      if (labels && labels.length > 0) {
+        const t = Array.from(labels).map((l) => l.innerText).join(" ").replace(/\s+/g, " ").trim();
+        if (t) return t;
+      }
       const ph = el.getAttribute("placeholder");
       if (ph) return ph.trim();
       const title = el.getAttribute("title");
@@ -405,8 +418,9 @@
     };
     const seen = /* @__PURE__ */ new Set();
     const candidates = [];
+    const cap = Math.max(max * 2, max + 50);
     const collect = (root) => {
-      if (candidates.length >= max) return;
+      if (candidates.length >= cap) return;
       let matched;
       try {
         matched = root.querySelectorAll(sel);
@@ -414,7 +428,7 @@
         matched = [];
       }
       for (let i = 0; i < matched.length; i++) {
-        if (candidates.length >= max) break;
+        if (candidates.length >= cap) break;
         const el = matched[i];
         if (seen.has(el)) continue;
         seen.add(el);
@@ -427,7 +441,7 @@
         hosts = [];
       }
       for (let i = 0; i < hosts.length; i++) {
-        if (candidates.length >= max) break;
+        if (candidates.length >= cap) break;
         const sr = hosts[i].shadowRoot;
         if (sr) collect(sr);
       }
@@ -491,7 +505,7 @@
         if (picked.length >= max) break;
         picked.push(read(el));
       }
-      truncated = els.length > picked.length;
+      truncated = els.length > picked.length || candidates.length >= cap;
     }
     const nodes = [];
     let n = 0;
@@ -632,6 +646,15 @@
           el2.click();
           return { found: true };
         }
+        case "check": {
+          if (!el2) return { found: false };
+          const box = el2;
+          if (box.checked !== (a.checked !== false)) {
+            el2.scrollIntoView({ block: "center" });
+            el2.click();
+          }
+          return { found: true, checked: box.checked };
+        }
         case "type": {
           if (!el2) return { found: false };
           if (el2.isContentEditable) {
@@ -644,9 +667,24 @@
           const node = el2;
           if (!node) return { found: false };
           node.focus();
-          const next = (a.clear ? "" : node.value ?? "") + (a.text ?? "");
-          setValue(node, next);
+          if (a.keyEvents) {
+            if (a.clear) setValue(node, "");
+            for (const ch of a.text ?? "") {
+              const ev = { key: ch, bubbles: true, cancelable: true };
+              const go = node.dispatchEvent(new KeyboardEvent("keydown", ev));
+              if (go && node.dispatchEvent(new KeyboardEvent("keypress", ev))) setValue(node, (node.value ?? "") + ch);
+              node.dispatchEvent(new KeyboardEvent("keyup", ev));
+            }
+          } else {
+            setValue(node, (a.clear ? "" : node.value ?? "") + (a.text ?? ""));
+          }
           node.dispatchEvent(new Event("change", { bubbles: true }));
+          if (a.pressEnter) {
+            const ev = { key: "Enter", code: "Enter", keyCode: 13, which: 13, bubbles: true, cancelable: true };
+            const go = node.dispatchEvent(new KeyboardEvent("keydown", ev)) && node.dispatchEvent(new KeyboardEvent("keypress", ev));
+            node.dispatchEvent(new KeyboardEvent("keyup", ev));
+            if (go && node instanceof HTMLInputElement && node.form) node.form.requestSubmit();
+          }
           return { found: true };
         }
         case "focus": {
@@ -1153,6 +1191,7 @@
       const u = cmd.params.url;
       return typeof u === "string" ? u : "";
     }
+    if (cmd.method === "download_file" && typeof cmd.params.url === "string") return cmd.params.url;
     return observedTabUrl(cmd, tab);
   }
   async function observedTabUrl(cmd, tab) {
@@ -1202,23 +1241,41 @@
       done = resolve;
     });
     const isTop = (d) => d.tabId === tabId && d.frameId === 0 && d.timeStamp >= start - 1;
+    let started = false;
+    let startUrl = "";
+    let committed = false;
+    const reached = () => {
+      if (waitUntil === "networkidle") setTimeout(done, NETWORK_QUIET_MS);
+      else done();
+    };
+    const onBefore = (d) => {
+      if (!isTop(d)) return;
+      started = true;
+      startUrl = d.url;
+      committed = false;
+    };
+    const onCommitted = (d) => {
+      if (isTop(d)) committed = true;
+    };
     const onDom = (d) => {
-      if (isTop(d) && waitUntil === "domcontentloaded") done();
+      if (isTop(d) && committed && waitUntil === "domcontentloaded") done();
     };
     const onCompleted = (d) => {
-      if (!isTop(d)) return;
-      if (waitUntil === "networkidle") setTimeout(done, NETWORK_QUIET_MS);
-      else done();
+      if (isTop(d) && committed) reached();
     };
     const onSameDoc = (d) => {
       if (isTop(d)) done();
     };
     const onError = (d) => {
-      if (isTop(d)) done();
+      if (!isTop(d) || !started) return;
+      if (/ERR_ABORTED/.test(d.error) && d.url !== startUrl) return;
+      done();
     };
     const onUpdated = (id, info) => {
-      if (id === tabId && info.status === "complete") done();
+      if (id === tabId && info.status === "complete" && committed) reached();
     };
+    chrome.webNavigation.onBeforeNavigate.addListener(onBefore);
+    chrome.webNavigation.onCommitted.addListener(onCommitted);
     chrome.webNavigation.onDOMContentLoaded.addListener(onDom);
     chrome.webNavigation.onCompleted.addListener(onCompleted);
     chrome.webNavigation.onHistoryStateUpdated.addListener(onSameDoc);
@@ -1226,6 +1283,8 @@
     chrome.webNavigation.onErrorOccurred.addListener(onError);
     chrome.tabs.onUpdated.addListener(onUpdated);
     const cleanup = () => {
+      chrome.webNavigation.onBeforeNavigate.removeListener(onBefore);
+      chrome.webNavigation.onCommitted.removeListener(onCommitted);
       chrome.webNavigation.onDOMContentLoaded.removeListener(onDom);
       chrome.webNavigation.onCompleted.removeListener(onCompleted);
       chrome.webNavigation.onHistoryStateUpdated.removeListener(onSameDoc);
@@ -1246,6 +1305,20 @@
       cancel: cleanup
     };
   }
+  async function historyStep(tabId, step) {
+    const went = await execInTab(
+      tabId,
+      (d) => {
+        const nav = window.navigation;
+        const can = nav ? d < 0 ? nav.canGoBack : nav.canGoForward : d < 0 && history.length > 1;
+        if (can) history.go(d);
+        return can;
+      },
+      [step],
+      "MAIN"
+    ).catch(() => false);
+    return went === true;
+  }
   function resolveSelector(cmd) {
     const s = cmd.params.selector;
     if (typeof s === "string" && s.length > 0) return s;
@@ -1299,17 +1372,41 @@
     dbgSessions.set(tabId, { detachTimer: null });
   }
   var DETACHED_RE = /not attached|no target with given id|detached/i;
-  async function withDebugger(tabId, fn) {
+  var DEBUGGER_OP_MS = 2e4;
+  async function withinMs(work, ms, what, onExpire) {
+    let timer;
+    const expired = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        onExpire?.();
+        reject(new CmdError("TIMEOUT", `${what} within ${ms / 1e3}s; it may be showing a dialog (alert/confirm), busy, or not painting`));
+      }, ms);
+    });
+    try {
+      return await Promise.race([work, expired]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  function withDeadline(tabId, work, ms) {
+    return withinMs(work, ms, "Chrome did not answer for the page", () => {
+      forgetDebugger(tabId);
+      chrome.debugger.detach({ tabId }).catch(() => void 0);
+    });
+  }
+  async function withDebugger(tabId, fn, timeoutMs = DEBUGGER_OP_MS) {
     return locks.run(`dbg:${tabId}`, async () => {
       const target = { tabId };
-      await ensureAttached(tabId);
+      const once = async () => {
+        await ensureAttached(tabId);
+        return fn(target);
+      };
       try {
-        return await fn(target);
+        return await withDeadline(tabId, once(), timeoutMs);
       } catch (err) {
+        if (err instanceof CmdError && err.code === "TIMEOUT") throw err;
         if (!DETACHED_RE.test(String(err?.message ?? err))) throw err;
         forgetDebugger(tabId);
-        await ensureAttached(tabId);
-        return await fn(target);
+        return await withDeadline(tabId, once(), timeoutMs);
       } finally {
         scheduleDetach(tabId);
       }
@@ -1334,9 +1431,15 @@
       }
       await chrome.debugger.sendCommand(t, "Input.insertText", { text });
       if (!pressEnter) return;
-      for (const type of ["keyDown", "keyUp"]) {
-        await chrome.debugger.sendCommand(t, "Input.dispatchKeyEvent", { type, key: "Enter", code: "Enter", windowsVirtualKeyCode: 13 });
-      }
+      await chrome.debugger.sendCommand(t, "Input.dispatchKeyEvent", {
+        type: "keyDown",
+        key: "Enter",
+        code: "Enter",
+        windowsVirtualKeyCode: 13,
+        text: "\r",
+        unmodifiedText: "\r"
+      });
+      await chrome.debugger.sendCommand(t, "Input.dispatchKeyEvent", { type: "keyUp", key: "Enter", code: "Enter", windowsVirtualKeyCode: 13 });
     });
     return true;
   }
@@ -1371,7 +1474,7 @@
     };
   }
   async function screenshotViaDebugger(tabId, fullPage, enc, selector, frameIds) {
-    const measured = await measurePage(tabId, selector, frameIds);
+    const measured = await withinMs(measurePage(tabId, selector, frameIds), DEBUGGER_OP_MS, "the page did not answer");
     if (!measured) throw new CmdError("CDP_ERROR", "could not read page dimensions");
     if (selector && measured.missing) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${selector}`);
     const plan = planScreenshot(measured.dims, { fullPage, element: measured.element, scale: enc.scale });
@@ -1403,19 +1506,28 @@
   }
   async function screenshotViaVisibleTab(tabId, fullPage, enc) {
     let t = await chrome.tabs.get(tabId);
+    let restore;
     if (!t.active) {
+      const [previous] = await chrome.tabs.query({ active: true, windowId: t.windowId });
+      restore = previous?.id;
       await chrome.tabs.update(tabId, { active: true });
-      await chrome.windows.update(t.windowId, { focused: true }).catch(() => void 0);
       await delay(150);
       t = await chrome.tabs.get(tabId);
     }
+    try {
+      return await captureActiveTab(tabId, t.windowId, fullPage, enc);
+    } finally {
+      if (restore !== void 0) await chrome.tabs.update(restore, { active: true }).catch(() => void 0);
+    }
+  }
+  async function captureActiveTab(tabId, windowId, fullPage, enc) {
     const dims = await execInTab(
       tabId,
       () => ({ w: window.innerWidth, h: window.innerHeight, full: document.documentElement.scrollHeight }),
       []
     );
     const dataUrl = await chrome.tabs.captureVisibleTab(
-      t.windowId,
+      windowId,
       enc.format === "jpeg" ? { format: "jpeg", quality: enc.quality } : { format: "png" }
     );
     const viewportH = dims?.h ?? 0;
@@ -1483,6 +1595,43 @@
       this.getPolicy = getPolicy;
     }
     getPolicy;
+    /** The absolute URL a link (or img/source) element points at, for a download
+     *  by element. Gated like a download by URL: the router only checked the tab
+     *  the link sits in, and the link can lead to any site. */
+    async linkTarget(cmd) {
+      const id = await targetTab(cmd);
+      const sel = requireSelector(cmd);
+      const frameIds = await this.frames(cmd, id);
+      if (!await waitForSelector(id, sel, frameIds)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+      const url = await execInTab(
+        id,
+        (s) => {
+          const el = document.querySelector(s);
+          const raw = el?.getAttribute("href") ?? el?.getAttribute("src");
+          try {
+            return raw ? new URL(raw, document.baseURI).href : "";
+          } catch {
+            return "";
+          }
+        },
+        [sel],
+        void 0,
+        frameIds
+      );
+      if (!url) throw new CmdError("DOWNLOAD_FAILED", `the element ${sel} has no href or src to download`);
+      this.assertAllowed(url, "download_file");
+      return url;
+    }
+    allowed(url, method) {
+      const policy = this.getPolicy();
+      return !!policy && evaluatePolicy(url, method, policy).ok;
+    }
+    /** Gate a URL the router could not see (it gates the tab, not arguments). */
+    assertAllowed(url, method) {
+      const policy = this.getPolicy();
+      const verdict = policy ? evaluatePolicy(url, method, policy) : { ok: false, reason: "no policy has arrived yet" };
+      if (!verdict.ok) throw new CmdError("POLICY_DENIED", verdict.reason);
+    }
     /**
      * Resolve `frameId` / `allFrames` params into the frame ids an injection may
      * touch, dropping any whose own URL the policy does not allow for this method.
@@ -1551,6 +1700,7 @@
         }
         case "tab_new": {
           const url = typeof cmd.params.url === "string" ? cmd.params.url : void 0;
+          if (url !== void 0) this.assertAllowed(url, "navigate");
           const active = cmd.params.active !== false;
           const BLANK = /^(about:blank|chrome:\/\/newtab|chrome:\/\/new-tab-page|edge:\/\/newtab)/i;
           const claim = await locks.run("tab_new", async () => {
@@ -1565,14 +1715,14 @@
               claimedTabs.add(blank.id);
               return { id: blank.id, reused: true, needsNav: url !== void 0 };
             }
-            const created = await chrome.tabs.create({ url, active: false });
+            const created = await chrome.tabs.create({ url: url === void 0 ? void 0 : "about:blank", active: false });
             if (created.id === void 0) throw new CmdError("TARGET_GONE", "failed to create a tab");
             claimedTabs.add(created.id);
             await rememberOpenedByUs(created.id, present);
-            return { id: created.id, reused: false, needsNav: false };
+            return { id: created.id, reused: false, needsNav: url !== void 0 };
           });
           if (claim.needsNav) {
-            const nav = armNavigationWait(claim.id, "load");
+            const nav = armNavigationWait(claim.id, "load", 25e3);
             await chrome.tabs.update(claim.id, { url }).catch((err) => {
               nav.cancel();
               throw err;
@@ -1602,25 +1752,19 @@
           });
           await nav.wait();
           const t = await chrome.tabs.get(id);
-          return { url: t.url ?? url, title: t.title ?? "" };
-        }
-        case "back": {
-          const id = await targetTab2(cmd);
-          const nav = armNavigationWait(id, "load", 15e3);
-          const moved = await chrome.tabs.goBack(id).then(() => true, () => false);
-          if (moved) await nav.wait();
-          else nav.cancel();
-          const t = await chrome.tabs.get(id);
-          return { url: t.url ?? "", title: t.title ?? "" };
+          const landed = t.url ?? url;
+          return { url: landed, title: this.allowed(landed, "get_text") ? t.title ?? "" : "" };
         }
+        case "back":
         case "forward": {
           const id = await targetTab2(cmd);
+          const step = cmd.method === "back" ? -1 : 1;
           const nav = armNavigationWait(id, "load", 15e3);
-          const moved = await chrome.tabs.goForward(id).then(() => true, () => false);
+          const moved = await (step < 0 ? chrome.tabs.goBack(id) : chrome.tabs.goForward(id)).then(() => true, () => false) || await historyStep(id, step);
           if (moved) await nav.wait();
           else nav.cancel();
           const t = await chrome.tabs.get(id);
-          return { url: t.url ?? "", title: t.title ?? "" };
+          return { url: t.url ?? "", title: t.title ?? "", moved };
         }
         case "reload": {
           const id = await targetTab2(cmd);
@@ -1699,6 +1843,7 @@
           const t = await chrome.tabs.get(id);
           const url = typeof cmd.params.url === "string" ? cmd.params.url : t.url;
           if (!url) throw new CmdError("BAD_ARGS", "no url to read cookies for");
+          if (url !== t.url) this.assertAllowed(url, "get_cookies");
           const cookies = await chrome.cookies.getAll({ url });
           return {
             cookies: cookies.map((c) => ({
@@ -1719,6 +1864,9 @@
           const key = typeof cmd.params.key === "string" ? cmd.params.key : null;
           const value = typeof cmd.params.value === "string" ? cmd.params.value : null;
           const session = cmd.params.session === true;
+          if (op !== "get" && !this.getPolicy()?.enableMutations) {
+            throw new CmdError("POLICY_DENIED", `storage "${op}" changes the page and is disabled (safe-mode). Pass --enable-mutations to allow it.`);
+          }
           const frameIds = await this.frames(cmd, id);
           const out = await execOp(id, { op: "storage", storageOp: op, key, value, session }, frameIds);
           const { found: _found, frameId: _frameId, ...rest } = out;
@@ -1812,7 +1960,11 @@
             }
             return { ok: true };
           }
-          const out = await execOp(id, withWait({ op: "type", selector: sel, text, clear }), frameIds);
+          const out = await execOp(
+            id,
+            withWait({ op: "type", selector: sel, text, clear, keyEvents: cmd.params.keyEvents === true, pressEnter: cmd.params.pressEnter === true }),
+            frameIds
+          );
           if (!out.found) throw notFound(sel, out);
           return { ok: true, frameId: out.frameId };
         }
@@ -1834,7 +1986,7 @@
               const out = await execOp(
                 id,
                 withWait(
-                  typeof op.value === "boolean" ? { op: "click", selector: op.selector } : { op: "type", selector: op.selector, text: op.value, clear: true }
+                  typeof op.value === "boolean" ? { op: "check", selector: op.selector, checked: op.value } : { op: "type", selector: op.selector, text: op.value, clear: true }
                 ),
                 await this.frames(cmd, id)
               );
@@ -1849,15 +2001,25 @@
         case "press": {
           const id = await targetTab2(cmd);
           const key = String(cmd.params.key ?? "");
+          const modifiers = Array.isArray(cmd.params.modifiers) ? cmd.params.modifiers.map((m) => String(m).toLowerCase()) : [];
           await execInTab(
             id,
-            (k) => {
+            (k, mods) => {
+              const m = mods;
+              const has = (...names) => names.some((n) => m.includes(n));
+              const init = {
+                key: k,
+                bubbles: true,
+                cancelable: true,
+                ctrlKey: has("control", "ctrl"),
+                shiftKey: has("shift"),
+                altKey: has("alt", "option"),
+                metaKey: has("meta", "cmd", "command")
+              };
               const el = document.activeElement ?? document.body;
-              for (const type of ["keydown", "keypress", "keyup"]) {
-                el.dispatchEvent(new KeyboardEvent(type, { key: k, bubbles: true }));
-              }
+              for (const type of ["keydown", "keypress", "keyup"]) el.dispatchEvent(new KeyboardEvent(type, init));
             },
-            [key]
+            [key, modifiers]
           );
           return { ok: true };
         }
@@ -1903,7 +2065,7 @@
           try {
             return await screenshotViaDebugger(id, fullPage, enc, selector, frameIds);
           } catch (err) {
-            if (err instanceof CmdError && err.code === "SELECTOR_NOT_FOUND") throw err;
+            if (err instanceof CmdError && (err.code === "SELECTOR_NOT_FOUND" || err.code === "TIMEOUT")) throw err;
             return await screenshotViaVisibleTab(id, fullPage, enc);
           }
         }
@@ -1913,15 +2075,16 @@
           const expr = String(cmd.params.expression ?? "");
           const result = await execInTab(
             id,
-            (e) => {
+            async (e, wait) => {
               try {
-                const v = (0, eval)(e);
+                let v = (0, eval)(e);
+                if (wait && v && typeof v.then === "function") v = await v;
                 return { ok: true, value: v, type: typeof v };
               } catch (err) {
                 return { ok: false, error: String(err) };
               }
             },
-            [expr],
+            [expr, cmd.params.awaitPromise === true],
             "MAIN",
             await this.frames(cmd, id)
           );
@@ -1953,8 +2116,7 @@
         //    into the active task's downloads/). We wait for completion and report
         //    the absolute on-disk path so the server can relocate it. --
         case "download_file": {
-          const url = typeof cmd.params.url === "string" ? cmd.params.url : void 0;
-          if (!url) throw new CmdError("DOWNLOAD_FAILED", "the extension download path requires a url");
+          const url = typeof cmd.params.url === "string" ? cmd.params.url : await this.linkTarget(cmd);
           const name = sanitizeDownloadName(
             typeof cmd.params.suggestedName === "string" ? cmd.params.suggestedName : void 0
           );
@@ -2090,7 +2252,7 @@
           const data = await withDebugger(id, async (t2) => {
             const res = await chrome.debugger.sendCommand(t2, "Page.printToPDF", params);
             return res.data ?? "";
-          });
+          }, 25e3);
           if (!data) throw new CmdError("CDP_ERROR", "Chrome returned an empty PDF");
           const t = await chrome.tabs.get(id);
           return { dataBase64: data, mimeType: "application/pdf", url: t.url ?? "", title: t.title ?? "" };
@@ -2305,18 +2467,30 @@
     const tab = await chrome.tabs.get(tabId).catch(() => null);
     return !!tab?.url && evaluatePolicy(tab.url, "get_text", policy).ok;
   }
-  async function paint(tabId) {
+  var PAGE_WAIT_MS = 2e3;
+  async function bounded(work, fallback) {
+    let timer;
+    const late = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(fallback), PAGE_WAIT_MS);
+    });
     try {
-      const [res] = await chrome.scripting.executeScript({ target: { tabId }, func: readPageTheme });
-      const css = borderCss(pickBorderColor(res?.result ?? { themeColor: "", background: "", prefersDark: false }));
-      await chrome.scripting.insertCSS({ target: { tabId }, css, origin: "USER" });
-      return css;
-    } catch {
-      return "";
+      return await Promise.race([work.catch(() => fallback), late]);
+    } finally {
+      clearTimeout(timer);
     }
   }
+  async function paint(tabId) {
+    const theme = await bounded(
+      chrome.scripting.executeScript({ target: { tabId }, func: readPageTheme }).then(([res]) => res?.result),
+      null
+    );
+    if (theme === null) return "";
+    const css = borderCss(pickBorderColor(theme ?? { themeColor: "", background: "", prefersDark: false }));
+    const ok = await bounded(chrome.scripting.insertCSS({ target: { tabId }, css, origin: "USER" }).then(() => true), false);
+    return ok ? css : "";
+  }
   async function unpaint(tabId, css) {
-    if (css) await chrome.scripting.removeCSS({ target: { tabId }, css, origin: "USER" }).catch(() => void 0);
+    if (css) await bounded(chrome.scripting.removeCSS({ target: { tabId }, css, origin: "USER" }), void 0);
   }
   var TabBorder = class {
     constructor(getPolicy) {
@@ -2393,7 +2567,7 @@
           if (left > 0) return void this.capturing.set(tabId, left);
           this.capturing.delete(tabId);
           if ((await loadMarked())[tabId] !== css) return;
-          await chrome.scripting.insertCSS({ target: { tabId }, css, origin: "USER" }).catch(() => void 0);
+          await bounded(chrome.scripting.insertCSS({ target: { tabId }, css, origin: "USER" }), void 0);
         });
       }
     }

package/extension-dist/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
-  "name": "MCP Browser Extension",
-  "version": "0.9.29",
-  "description": "Lets your AI agent (Claude, Cursor, Codex) use the Chrome you are signed into, through a local MCP server. Deny-all by default.",
+  "name": "MCP Browser Extension – AI agent in your logged-in Chrome",
+  "version": "0.9.30",
+  "description": "Lets your AI agent use the Chrome you are signed into, through a local MCP server. Deny-all by default.",
   "homepage_url": "https://mcp-browser-extension.com",
   "minimum_chrome_version": "116",
   "icons": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-browser-extension",
   "mcpName": "io.github.Mehmoodqureshi/mcp-browser-extension",
-  "version": "0.9.29",
+  "version": "0.9.30",
   "description": "Drive your real Chrome browser over MCP — real logins, real cookies. A stdio MCP server (CLI) plus an MV3 extension, driving Chrome via chrome.scripting/chrome.tabs. Multi-tab batch automation, accessibility snapshots, deny-all security by default.",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",
@@ -57,6 +57,7 @@
     "typecheck:ext": "tsc -p tsconfig.ext.json",
     "clean": "rimraf dist",
     "test": "npm run clean && npm run build && npm run build:ext && node --test dist/test/*.test.js",
+    "test:e2e": "npm run build && npm run build:ext && RUN_E2E=1 node --test --test-concurrency=1 dist/test/e2e/*.test.js",
     "test:hitl": "npm run build && node dist/hitl/index.js",
     "prepack": "npm run clean && npm run build && npm run build:ext"
   },