@mehmoodqureshi/chrome-mcp 0.9.2 → 0.9.4

package/extension-dist/background.js

@@ -285,29 +285,31 @@
   }
 
   // shared/snapshot.ts
-  function collectSnapshot(interactiveOnly = true, max = 200) {
+  function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
     const INTERACTIVE = "a[href],button,input,select,textarea,[role=button],[role=link],[role=tab],[role=checkbox],[role=radio],[role=menuitem],[role=option],[role=switch],[contenteditable=true],[onclick]";
     const LANDMARK = "h1,h2,h3,[role=heading],nav,main,header,footer,[role=navigation]";
     const sel = interactiveOnly ? INTERACTIVE : `${INTERACTIVE},${LANDMARK}`;
     const visible = (el) => {
-      const r = el.getBoundingClientRect();
-      if (r.width === 0 && r.height === 0) return false;
-      const s = window.getComputedStyle(el);
-      if (s.visibility === "hidden" || s.display === "none") return false;
-      const cv = el.checkVisibility;
-      if (typeof cv === "function") {
+      const h = el;
+      if (typeof h.checkVisibility === "function") {
         try {
-          return cv.call(el, { checkOpacity: false, checkVisibilityCSS: true });
+          if (!h.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true })) return false;
+          const r2 = h.getBoundingClientRect();
+          return r2.width !== 0 || r2.height !== 0;
         } catch {
         }
       }
+      const r = h.getBoundingClientRect();
+      if (r.width === 0 && r.height === 0) return false;
+      const s = window.getComputedStyle(h);
+      if (s.visibility === "hidden" || s.display === "none") return false;
       let p = el.parentElement;
       while (p) {
         const ps = window.getComputedStyle(p);
         if (ps.display === "none" || ps.visibility === "hidden") return false;
         p = p.parentElement;
       }
-      if (el.offsetParent === null && s.position !== "fixed") return false;
+      if (h.offsetParent === null && s.position !== "fixed") return false;
       return true;
     };
     const accName = (el) => {
@@ -350,46 +352,98 @@
       if (candidates.length >= max) return;
       let matched;
       try {
-        matched = Array.from(root.querySelectorAll(sel));
+        matched = root.querySelectorAll(sel);
       } catch {
         matched = [];
       }
-      for (const el of matched) {
+      for (let i = 0; i < matched.length; i++) {
         if (candidates.length >= max) break;
+        const el = matched[i];
         if (seen.has(el)) continue;
         seen.add(el);
         candidates.push(el);
       }
       let hosts;
       try {
-        hosts = Array.from(root.querySelectorAll("*"));
+        hosts = root.querySelectorAll("*");
       } catch {
         hosts = [];
       }
-      for (const host of hosts) {
+      for (let i = 0; i < hosts.length; i++) {
         if (candidates.length >= max) break;
-        const sr = host.shadowRoot;
+        const sr = hosts[i].shadowRoot;
         if (sr) collect(sr);
       }
     };
     collect(document);
-    const els = candidates.filter(visible);
-    const nodes = [];
-    let n = 0;
-    for (const el of els) {
-      if (nodes.length >= max) break;
-      const ref = `e${++n}`;
-      el.setAttribute("data-mcp-ref", ref);
-      const node = { ref, role: roleOf(el), name: accName(el), tag: el.tagName.toLowerCase() };
+    const read = (el) => {
+      const node = { role: roleOf(el), name: accName(el), tag: el.tagName.toLowerCase() };
       const isSecret = el.tagName === "INPUT" && el.type === "password";
       if (isSecret) node.secret = true;
       const v = el.value;
       if (!isSecret && typeof v === "string" && v) node.value = v.slice(0, 200);
       if (el.disabled) node.disabled = true;
       if (el.checked) node.checked = true;
-      nodes.push(node);
+      return { el, node };
+    };
+    const els = candidates.filter(visible);
+    let picked;
+    let truncated = false;
+    let nearby;
+    let refPrefix = "e";
+    if (locator && (locator.role !== void 0 || locator.name !== void 0)) {
+      const norm = (x) => x.replace(/\s+/g, " ").trim().toLowerCase();
+      const wantRole = locator.role !== void 0 ? norm(locator.role) : null;
+      const wantName = locator.name;
+      const score = (role, name) => {
+        if (wantRole !== null && norm(role) !== wantRole) return 0;
+        if (!wantName) return 1;
+        const have = norm(name);
+        const need = norm(wantName);
+        if (!have) return 0;
+        if (name.trim() === wantName.trim()) return 4;
+        if (have === need) return 3;
+        if (have.startsWith(need)) return 2;
+        if (have.includes(need)) return 1;
+        return 0;
+      };
+      let best = 0;
+      picked = [];
+      const sameRole = [];
+      for (const el of els) {
+        const s = read(el);
+        const sc = score(s.node.role, s.node.name);
+        if (sc === 0) {
+          if ((wantRole === null || norm(s.node.role) === wantRole) && sameRole.length < 8) {
+            sameRole.push(`${s.node.role} "${s.node.name}"`);
+          }
+          continue;
+        }
+        if (sc > best) {
+          best = sc;
+          picked = [s];
+        } else if (sc === best) {
+          picked.push(s);
+        }
+      }
+      if (picked.length === 0) nearby = sameRole;
+      refPrefix = `l${Date.now().toString(36).slice(-4)}-`;
+    } else {
+      picked = [];
+      for (const el of els) {
+        if (picked.length >= max) break;
+        picked.push(read(el));
+      }
+      truncated = els.length > picked.length;
     }
-    return { url: location.href, title: document.title, nodes, truncated: els.length > nodes.length };
+    const nodes = [];
+    let n = 0;
+    for (const { el, node } of picked) {
+      const ref = `${refPrefix}${++n}`;
+      el.setAttribute("data-mcp-ref", ref);
+      nodes.push({ ref, ...node });
+    }
+    return { url: location.href, title: document.title, nodes, truncated, ...nearby ? { nearby } : {} };
   }
 
   // shared/page-fns.ts
@@ -440,177 +494,197 @@
       return { dx, dy, exact: true, scrollX: win.scrollX, scrollY: win.scrollY };
     };
     const sel = typeof a.selector === "string" && a.selector.length > 0 ? a.selector : null;
-    const el = sel ? deepQuery(sel) : null;
-    const missing = sel !== null && el === null;
     const setValue = (node, next) => {
       const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(node), "value")?.set;
       if (setter) setter.call(node, next);
       else node.value = next;
       node.dispatchEvent(new Event("input", { bubbles: true }));
     };
-    switch (a.op) {
-      case "probe":
-        return { found: true, url: location.href, title: document.title };
-      case "text": {
-        if (missing) return { found: false };
-        const root = el ?? document.body;
-        return { found: true, text: root ? root.innerText ?? "" : "" };
-      }
-      case "html": {
-        if (missing) return { found: false };
-        const root = el ?? document.documentElement;
-        if (!root) return { found: true, html: "" };
-        const outer = a.outer === true || !sel;
-        return { found: true, html: outer ? root.outerHTML : root.innerHTML };
-      }
-      case "click": {
-        if (!el) return { found: false };
-        el.scrollIntoView({ block: "center" });
-        el.click();
-        return { found: true };
-      }
-      case "type": {
-        const node = el;
-        if (!node) return { found: false };
-        node.focus();
-        const next = (a.clear ? "" : node.value ?? "") + (a.text ?? "");
-        setValue(node, next);
-        node.dispatchEvent(new Event("change", { bubbles: true }));
-        return { found: true };
-      }
-      case "focus": {
-        const node = el;
-        if (!node) return { found: false };
-        node.focus();
-        if (a.clear) setValue(node, "");
-        return { found: true };
-      }
-      case "point": {
-        if (!el) return { found: false };
-        el.scrollIntoView({ block: "center", inline: "center" });
-        const r = el.getBoundingClientRect();
-        const off = frameOffset();
-        return {
-          found: true,
-          x: r.left + r.width / 2 + off.dx,
-          y: r.top + r.height / 2 + off.dy,
-          // false => this frame's coordinates cannot be mapped to the top viewport.
-          exact: off.exact
-        };
-      }
-      case "hover": {
-        if (!el) return { found: false };
-        el.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
-        el.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
-        return { found: true };
-      }
-      case "select": {
-        const node = el;
-        if (!node || !node.options) return { found: false };
-        const want = new Set(a.values ?? []);
-        let matched = false;
-        for (const opt of Array.from(node.options)) {
-          const on = want.has(opt.value) || want.has(opt.label) || want.has(opt.text);
-          opt.selected = on;
-          if (on) matched = true;
+    const perform = (el2) => {
+      const missing = sel !== null && el2 === null;
+      switch (a.op) {
+        case "probe":
+          return { found: true, url: location.href, title: document.title };
+        case "text": {
+          if (missing) return { found: false };
+          const root = el2 ?? document.body;
+          return { found: true, text: root ? root.innerText ?? "" : "" };
         }
-        node.dispatchEvent(new Event("input", { bubbles: true }));
-        node.dispatchEvent(new Event("change", { bubbles: true }));
-        return { found: true, matched };
-      }
-      case "measure": {
-        const d = document.documentElement;
-        const dims = {
-          w: window.innerWidth,
-          h: window.innerHeight,
-          fullW: Math.max(d.scrollWidth, d.clientWidth),
-          fullH: Math.max(d.scrollHeight, d.clientHeight)
-        };
-        if (!sel) return { found: true, dims, element: null, missing: false };
-        if (!el) return { found: true, dims, element: null, missing: true };
-        el.scrollIntoView({ block: "center", inline: "center" });
-        const r = el.getBoundingClientRect();
-        const off = frameOffset();
-        return {
-          found: true,
-          dims,
-          element: {
-            x: r.left + off.dx + off.scrollX,
-            y: r.top + off.dy + off.scrollY,
-            w: r.width,
-            h: r.height
-          },
-          missing: false,
-          exact: off.exact
-        };
-      }
-      case "scroll": {
-        if (el) el.scrollIntoView({ block: "center" });
-        else if (a.x != null || a.y != null) window.scrollTo(a.x ?? 0, a.y ?? 0);
-        else window.scrollBy(a.deltaX ?? 0, a.deltaY ?? 0);
-        return { found: !missing };
-      }
-      case "storage": {
-        const store = a.session ? window.sessionStorage : window.localStorage;
-        const op = a.storageOp;
-        if (op === "set") {
-          store.setItem(String(a.key), String(a.value ?? ""));
-          return { found: true, ok: true };
+        case "html": {
+          if (missing) return { found: false };
+          const root = el2 ?? document.documentElement;
+          if (!root) return { found: true, html: "" };
+          const outer = a.outer === true || !sel;
+          return { found: true, html: outer ? root.outerHTML : root.innerHTML };
         }
-        if (op === "remove") {
-          store.removeItem(String(a.key));
-          return { found: true, ok: true };
+        case "click": {
+          if (!el2) return { found: false };
+          el2.scrollIntoView({ block: "center" });
+          el2.click();
+          return { found: true };
         }
-        if (op === "clear") {
-          store.clear();
-          return { found: true, ok: true };
+        case "type": {
+          const node = el2;
+          if (!node) return { found: false };
+          node.focus();
+          const next = (a.clear ? "" : node.value ?? "") + (a.text ?? "");
+          setValue(node, next);
+          node.dispatchEvent(new Event("change", { bubbles: true }));
+          return { found: true };
         }
-        if (a.key) return { found: true, ok: true, value: store.getItem(a.key) };
-        const entries = {};
-        for (let i = 0; i < store.length; i++) {
-          const k = store.key(i);
-          if (k) entries[k] = store.getItem(k) ?? "";
+        case "focus": {
+          const node = el2;
+          if (!node) return { found: false };
+          node.focus();
+          if (a.clear) setValue(node, "");
+          return { found: true };
         }
-        return { found: true, ok: true, entries };
-      }
-      // -- the two polling ops: one injection that resolves in-page, rather than
-      //    one executeScript round-trip per tick --
-      case "waitSelector": {
-        const deadline = Date.now() + (a.timeoutMs ?? 5e3);
-        const every = a.interval ?? 120;
-        return new Promise((resolve) => {
-          const tick = () => {
-            if (sel && deepQuery(sel)) return resolve({ found: true });
-            if (Date.now() > deadline) return resolve({ found: false });
-            setTimeout(tick, every);
+        case "point": {
+          if (!el2) return { found: false };
+          el2.scrollIntoView({ block: "center", inline: "center" });
+          const r = el2.getBoundingClientRect();
+          const off = frameOffset();
+          return {
+            found: true,
+            x: r.left + r.width / 2 + off.dx,
+            y: r.top + r.height / 2 + off.dy,
+            // false => this frame's coordinates cannot be mapped to the top viewport.
+            exact: off.exact
           };
-          tick();
-        });
-      }
-      case "waitFor": {
-        const deadline = Date.now() + (a.timeoutMs ?? 3e4);
-        const every = a.interval ?? 150;
-        const want = typeof a.textContains === "string" && a.textContains.length > 0 ? a.textContains : null;
-        const gone = a.gone === true;
-        return new Promise((resolve) => {
-          const hit = () => {
-            let present;
-            if (sel) present = !!deepQuery(sel);
-            else if (want) present = (document.body?.innerText ?? "").includes(want);
-            else present = true;
-            return gone ? !present : present;
+        }
+        case "hover": {
+          if (!el2) return { found: false };
+          el2.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+          el2.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
+          return { found: true };
+        }
+        case "select": {
+          const node = el2;
+          if (!node || !node.options) return { found: false };
+          const want = new Set(a.values ?? []);
+          let matched = false;
+          for (const opt of Array.from(node.options)) {
+            const on = want.has(opt.value) || want.has(opt.label) || want.has(opt.text);
+            opt.selected = on;
+            if (on) matched = true;
+          }
+          node.dispatchEvent(new Event("input", { bubbles: true }));
+          node.dispatchEvent(new Event("change", { bubbles: true }));
+          return { found: true, matched };
+        }
+        case "measure": {
+          const d = document.documentElement;
+          const dims = {
+            w: window.innerWidth,
+            h: window.innerHeight,
+            fullW: Math.max(d.scrollWidth, d.clientWidth),
+            fullH: Math.max(d.scrollHeight, d.clientHeight),
+            dpr: window.devicePixelRatio || 1,
+            scrollX: window.scrollX,
+            scrollY: window.scrollY
           };
-          const tick = () => {
-            if (hit()) return resolve({ found: true, matched: true });
-            if (Date.now() > deadline) return resolve({ found: true, matched: false });
-            setTimeout(tick, every);
+          if (!sel) return { found: true, dims, element: null, missing: false };
+          if (!el2) return { found: true, dims, element: null, missing: true };
+          el2.scrollIntoView({ block: "center", inline: "center" });
+          const r = el2.getBoundingClientRect();
+          const off = frameOffset();
+          return {
+            found: true,
+            dims,
+            element: {
+              x: r.left + off.dx + off.scrollX,
+              y: r.top + off.dy + off.scrollY,
+              w: r.width,
+              h: r.height
+            },
+            missing: false,
+            exact: off.exact
           };
-          tick();
-        });
+        }
+        case "scroll": {
+          if (el2) el2.scrollIntoView({ block: "center" });
+          else if (a.x != null || a.y != null) window.scrollTo(a.x ?? 0, a.y ?? 0);
+          else window.scrollBy(a.deltaX ?? 0, a.deltaY ?? 0);
+          return { found: !missing };
+        }
+        case "storage": {
+          const store = a.session ? window.sessionStorage : window.localStorage;
+          const op = a.storageOp;
+          if (op === "set") {
+            store.setItem(String(a.key), String(a.value ?? ""));
+            return { found: true, ok: true };
+          }
+          if (op === "remove") {
+            store.removeItem(String(a.key));
+            return { found: true, ok: true };
+          }
+          if (op === "clear") {
+            store.clear();
+            return { found: true, ok: true };
+          }
+          if (a.key) return { found: true, ok: true, value: store.getItem(a.key) };
+          const entries = {};
+          for (let i = 0; i < store.length; i++) {
+            const k = store.key(i);
+            if (k) entries[k] = store.getItem(k) ?? "";
+          }
+          return { found: true, ok: true, entries };
+        }
+        // -- the two polling ops: one injection that resolves in-page, rather than
+        //    one executeScript round-trip per tick --
+        case "waitSelector": {
+          const deadline = Date.now() + (a.timeoutMs ?? 5e3);
+          const every = a.interval ?? 120;
+          return new Promise((resolve) => {
+            const tick = () => {
+              if (sel && deepQuery(sel)) return resolve({ found: true });
+              if (Date.now() > deadline) return resolve({ found: false });
+              setTimeout(tick, every);
+            };
+            tick();
+          });
+        }
+        case "waitFor": {
+          const deadline = Date.now() + (a.timeoutMs ?? 3e4);
+          const every = a.interval ?? 150;
+          const want = typeof a.textContains === "string" && a.textContains.length > 0 ? a.textContains : null;
+          const gone = a.gone === true;
+          return new Promise((resolve) => {
+            const hit = () => {
+              let present;
+              if (sel) present = !!deepQuery(sel);
+              else if (want) present = (document.body?.innerText ?? "").includes(want);
+              else present = true;
+              return gone ? !present : present;
+            };
+            const tick = () => {
+              if (hit()) return resolve({ found: true, matched: true });
+              if (Date.now() > deadline) return resolve({ found: true, matched: false });
+              setTimeout(tick, every);
+            };
+            tick();
+          });
+        }
+        default:
+          return { found: false, error: `unknown page op: ${String(a.op)}` };
       }
-      default:
-        return { found: false, error: `unknown page op: ${String(a.op)}` };
+    };
+    const el = sel ? deepQuery(sel) : null;
+    const waits = a.op === "click" || a.op === "type" || a.op === "focus" || a.op === "point" || a.op === "hover" || a.op === "select";
+    if (waits && sel && !el && a.timeoutMs && a.timeoutMs > 0) {
+      const deadline = Date.now() + a.timeoutMs;
+      const every = a.interval ?? 120;
+      return new Promise((resolve) => {
+        const tick = () => {
+          const hit = deepQuery(sel);
+          if (hit) return resolve(perform(hit));
+          if (Date.now() > deadline) return resolve({ found: false });
+          setTimeout(tick, every);
+        };
+        setTimeout(tick, every);
+      });
     }
+    return perform(el);
   }
 
   // shared/observers.ts
@@ -676,13 +750,18 @@
   }
 
   // shared/screenshot.ts
+  var DEFAULT_SCREENSHOT_FORMAT = "jpeg";
+  var DEFAULT_JPEG_QUALITY = 70;
+  var DEFAULT_SCREENSHOT_SCALE = 1;
   var MAX_CAPTURE_PX = 16384;
   function planScreenshot(dims, opts = {}) {
+    const dpr = dims.dpr && dims.dpr > 0 ? dims.dpr : 1;
+    const scale = (opts.scale && opts.scale > 0 ? opts.scale : DEFAULT_SCREENSHOT_SCALE) / dpr;
     if (opts.element) {
       const realH = Math.max(1, Math.round(opts.element.h));
       const clipH = Math.min(opts.element.h, MAX_CAPTURE_PX);
       return {
-        clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale: 1 },
+        clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale },
         captureBeyondViewport: true,
         width: Math.max(1, Math.round(opts.element.w)),
         height: Math.min(realH, MAX_CAPTURE_PX),
@@ -693,7 +772,7 @@
     if (opts.fullPage) {
       const clipH = Math.min(dims.fullH, MAX_CAPTURE_PX);
       return {
-        clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale: 1 },
+        clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale },
         captureBeyondViewport: true,
         width: dims.fullW,
         height: clipH,
@@ -702,6 +781,7 @@
       };
     }
     return {
+      ...scale !== 1 ? { clip: { x: dims.scrollX ?? 0, y: dims.scrollY ?? 0, width: dims.w, height: dims.h, scale } } : {},
       captureBeyondViewport: false,
       width: dims.w,
       height: dims.h,
@@ -794,16 +874,21 @@
   async function targetTab(cmd) {
     return cmd.tabId ? parseTabId(cmd.tabId) : currentTabId();
   }
-  async function urlForCommand(cmd) {
+  var TABLESS = /* @__PURE__ */ new Set(["tabs_list", "tab_new", "ping_probe", "download_file"]);
+  async function resolveTab(cmd) {
+    if (TABLESS.has(cmd.method)) return null;
+    return targetTab(cmd);
+  }
+  async function urlForCommand(cmd, tab) {
     if (cmd.method === "navigate") {
       const u = cmd.params.url;
       return typeof u === "string" ? u : "";
     }
-    return observedTabUrl(cmd);
+    return observedTabUrl(cmd, tab);
   }
-  async function observedTabUrl(cmd) {
+  async function observedTabUrl(cmd, tab) {
     try {
-      const tabId = await targetTab(cmd);
+      const tabId = tab ?? await targetTab(cmd);
       const t = await chrome.tabs.get(tabId);
       return t.url ?? "";
     } catch {
@@ -836,14 +921,61 @@
     if (outcomes.length === 0) throw new CmdError("TARGET_GONE", "the page returned no result for this command");
     return outcomes.find((o) => o.found === true) ?? outcomes[0];
   }
-  async function waitComplete(tabId, timeoutMs = 3e4) {
+  function waitUntilOf(cmd) {
+    const w = cmd.params.waitUntil;
+    return w === "domcontentloaded" || w === "networkidle" ? w : "load";
+  }
+  function armNavigationWait(tabId, waitUntil, timeoutMs = 3e4) {
     const start = Date.now();
-    for (; ; ) {
-      const t = await chrome.tabs.get(tabId);
-      if (t.status === "complete") return;
-      if (Date.now() - start > timeoutMs) return;
-      await delay(100);
-    }
+    const NETWORK_QUIET_MS = 500;
+    let done = () => void 0;
+    const finished = new Promise((resolve) => {
+      done = resolve;
+    });
+    const isTop = (d) => d.tabId === tabId && d.frameId === 0 && d.timeStamp >= start - 1;
+    const onDom = (d) => {
+      if (isTop(d) && waitUntil === "domcontentloaded") done();
+    };
+    const onCompleted = (d) => {
+      if (!isTop(d)) return;
+      if (waitUntil === "networkidle") setTimeout(done, NETWORK_QUIET_MS);
+      else done();
+    };
+    const onSameDoc = (d) => {
+      if (isTop(d)) done();
+    };
+    const onError = (d) => {
+      if (isTop(d)) done();
+    };
+    const onUpdated = (id, info) => {
+      if (id === tabId && info.status === "complete") done();
+    };
+    chrome.webNavigation.onDOMContentLoaded.addListener(onDom);
+    chrome.webNavigation.onCompleted.addListener(onCompleted);
+    chrome.webNavigation.onHistoryStateUpdated.addListener(onSameDoc);
+    chrome.webNavigation.onReferenceFragmentUpdated.addListener(onSameDoc);
+    chrome.webNavigation.onErrorOccurred.addListener(onError);
+    chrome.tabs.onUpdated.addListener(onUpdated);
+    const cleanup = () => {
+      chrome.webNavigation.onDOMContentLoaded.removeListener(onDom);
+      chrome.webNavigation.onCompleted.removeListener(onCompleted);
+      chrome.webNavigation.onHistoryStateUpdated.removeListener(onSameDoc);
+      chrome.webNavigation.onReferenceFragmentUpdated.removeListener(onSameDoc);
+      chrome.webNavigation.onErrorOccurred.removeListener(onError);
+      chrome.tabs.onUpdated.removeListener(onUpdated);
+    };
+    return {
+      async wait() {
+        const timer = setTimeout(done, timeoutMs);
+        try {
+          await finished;
+        } finally {
+          clearTimeout(timer);
+          cleanup();
+        }
+      },
+      cancel: cleanup
+    };
   }
   function resolveSelector(cmd) {
     const s = cmd.params.selector;
@@ -855,29 +987,73 @@
   function selectorOf(cmd) {
     return resolveSelector(cmd);
   }
-  async function waitForSelector(tabId, selector, frameIds, timeoutMs = 5e3) {
+  var ACTION_WAIT_MS = 5e3;
+  var withWait = (a) => ({ ...a, timeoutMs: ACTION_WAIT_MS, interval: 120 });
+  async function waitForSelector(tabId, selector, frameIds, timeoutMs = ACTION_WAIT_MS) {
     const out = await execOp(tabId, { op: "waitSelector", selector, timeoutMs, interval: 120 }, frameIds);
     return out.found === true;
   }
+  var DEBUGGER_GRACE_MS = 1500;
+  var dbgSessions = /* @__PURE__ */ new Map();
+  function forgetDebugger(tabId) {
+    const s = dbgSessions.get(tabId);
+    if (s?.detachTimer) clearTimeout(s.detachTimer);
+    dbgSessions.delete(tabId);
+  }
+  chrome.debugger.onDetach.addListener((source) => {
+    if (source.tabId !== void 0) forgetDebugger(source.tabId);
+  });
+  chrome.tabs.onRemoved.addListener((tabId) => forgetDebugger(tabId));
+  function scheduleDetach(tabId) {
+    const s = dbgSessions.get(tabId);
+    if (!s) return;
+    if (s.detachTimer) clearTimeout(s.detachTimer);
+    s.detachTimer = setTimeout(() => {
+      dbgSessions.delete(tabId);
+      chrome.debugger.detach({ tabId }).catch(() => void 0);
+    }, DEBUGGER_GRACE_MS);
+  }
+  async function ensureAttached(tabId) {
+    const s = dbgSessions.get(tabId);
+    if (s) {
+      if (s.detachTimer) clearTimeout(s.detachTimer);
+      s.detachTimer = null;
+      return;
+    }
+    await chrome.debugger.attach({ tabId }, "1.3");
+    dbgSessions.set(tabId, { detachTimer: null });
+  }
+  var DETACHED_RE = /not attached|no target with given id|detached/i;
   async function withDebugger(tabId, fn) {
     return locks.run(`dbg:${tabId}`, async () => {
       const target = { tabId };
-      await chrome.debugger.attach(target, "1.3");
+      await ensureAttached(tabId);
       try {
         return await fn(target);
+      } catch (err) {
+        if (!DETACHED_RE.test(String(err?.message ?? err))) throw err;
+        forgetDebugger(tabId);
+        await ensureAttached(tabId);
+        return await fn(target);
       } finally {
-        await chrome.debugger.detach(target).catch(() => void 0);
+        scheduleDetach(tabId);
       }
     });
   }
-  async function trustedType(tabId, selector, text, clear, frameIds) {
-    const focused = await execOp(tabId, { op: "focus", selector, clear }, frameIds);
+  async function trustedType(tabId, selector, text, clear, frameIds, pressEnter = false) {
+    const focused = await execOp(tabId, withWait({ op: "focus", selector, clear }), frameIds);
     if (!focused.found) return false;
-    await withDebugger(tabId, (t) => chrome.debugger.sendCommand(t, "Input.insertText", { text }));
+    await withDebugger(tabId, async (t) => {
+      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 });
+      }
+    });
     return true;
   }
   async function trustedClick(tabId, selector, frameIds) {
-    const pt = await execOp(tabId, { op: "point", selector }, frameIds);
+    const pt = await execOp(tabId, withWait({ op: "point", selector }), frameIds);
     if (!pt.found) return "missing";
     if (pt.exact === false) return "inexact";
     await withDebugger(tabId, async (t) => {
@@ -896,12 +1072,28 @@
       missing: found.missing === true
     };
   }
-  async function screenshotViaDebugger(tabId, fullPage, selector, frameIds) {
+  function encodingOf(cmd) {
+    const f = cmd.params.format;
+    const q = cmd.params.quality;
+    const sc = cmd.params.scale;
+    return {
+      format: f === "png" || f === "jpeg" ? f : DEFAULT_SCREENSHOT_FORMAT,
+      quality: typeof q === "number" && q >= 1 && q <= 100 ? Math.round(q) : DEFAULT_JPEG_QUALITY,
+      scale: typeof sc === "number" && sc > 0 ? sc : void 0
+    };
+  }
+  async function screenshotViaDebugger(tabId, fullPage, enc, selector, frameIds) {
     const measured = await measurePage(tabId, selector, frameIds);
     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 });
-    const params = { format: "png", captureBeyondViewport: plan.captureBeyondViewport };
+    const plan = planScreenshot(measured.dims, { fullPage, element: measured.element, scale: enc.scale });
+    const params = {
+      format: enc.format,
+      captureBeyondViewport: plan.captureBeyondViewport,
+      // Skip the slow PNG compression pass; bytes-on-the-wire matter less than latency here.
+      optimizeForSpeed: true
+    };
+    if (enc.format === "jpeg") params.quality = enc.quality;
     if (plan.clip) params.clip = plan.clip;
     const data = await withDebugger(tabId, async (target) => {
       const res = await chrome.debugger.sendCommand(target, "Page.captureScreenshot", params);
@@ -909,14 +1101,14 @@
     });
     return {
       dataBase64: data,
-      mimeType: "image/png",
+      mimeType: enc.format === "jpeg" ? "image/jpeg" : "image/png",
       width: plan.width,
       height: plan.height,
       truncated: plan.truncated,
       fullHeight: plan.fullHeight
     };
   }
-  async function screenshotViaVisibleTab(tabId, fullPage) {
+  async function screenshotViaVisibleTab(tabId, fullPage, enc) {
     let t = await chrome.tabs.get(tabId);
     if (!t.active) {
       await chrome.tabs.update(tabId, { active: true });
@@ -929,12 +1121,15 @@
       () => ({ w: window.innerWidth, h: window.innerHeight, full: document.documentElement.scrollHeight }),
       []
     );
-    const dataUrl = await chrome.tabs.captureVisibleTab(t.windowId, { format: "png" });
+    const dataUrl = await chrome.tabs.captureVisibleTab(
+      t.windowId,
+      enc.format === "jpeg" ? { format: "jpeg", quality: enc.quality } : { format: "png" }
+    );
     const viewportH = dims?.h ?? 0;
     const fullH = dims?.full ?? viewportH;
     return {
       dataBase64: dataUrl.split(",")[1] ?? "",
-      mimeType: "image/png",
+      mimeType: enc.format === "jpeg" ? "image/jpeg" : "image/png",
       width: dims?.w ?? 0,
       height: viewportH,
       truncated: fullPage && fullH > viewportH,
@@ -1036,7 +1231,12 @@
       }
       return allowed;
     }
-    async run(cmd) {
+    /**
+     * Execute one command. `tab` is the id `resolveTab` already produced for it
+     * (the router resolves once and shares it); omitted → resolve here.
+     */
+    async run(cmd, tab = null) {
+      const targetTab2 = async (c) => tab ?? (c.tabId ? parseTabId(c.tabId) : currentTabId());
       switch (cmd.method) {
         case "ping_probe":
           return {};
@@ -1071,8 +1271,12 @@
             return { id: created.id, reused: false, needsNav: false };
           });
           if (claim.needsNav) {
-            await chrome.tabs.update(claim.id, { url });
-            await waitComplete(claim.id);
+            const nav = armNavigationWait(claim.id, "load");
+            await chrome.tabs.update(claim.id, { url }).catch((err) => {
+              nav.cancel();
+              throw err;
+            });
+            await nav.wait();
           }
           if (active) {
             const t = await chrome.tabs.get(claim.id);
@@ -1088,42 +1292,56 @@
         }
         // -- navigation --
         case "navigate": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const url = String(cmd.params.url);
-          await chrome.tabs.update(id, { url });
-          await waitComplete(id);
+          const nav = armNavigationWait(id, waitUntilOf(cmd));
+          await chrome.tabs.update(id, { url }).catch((err) => {
+            nav.cancel();
+            throw err;
+          });
+          await nav.wait();
           const t = await chrome.tabs.get(id);
           return { url: t.url ?? url, title: t.title ?? "" };
         }
         case "back": {
-          const id = await targetTab(cmd);
-          await chrome.tabs.goBack(id).catch(() => void 0);
+          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 ?? "" };
         }
         case "forward": {
-          const id = await targetTab(cmd);
-          await chrome.tabs.goForward(id).catch(() => void 0);
+          const id = await targetTab2(cmd);
+          const nav = armNavigationWait(id, "load", 15e3);
+          const moved = await chrome.tabs.goForward(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 ?? "" };
         }
         case "reload": {
-          const id = await targetTab(cmd);
-          await chrome.tabs.reload(id);
-          await waitComplete(id);
+          const id = await targetTab2(cmd);
+          const nav = armNavigationWait(id, waitUntilOf(cmd));
+          await chrome.tabs.reload(id).catch((err) => {
+            nav.cancel();
+            throw err;
+          });
+          await nav.wait();
           const t = await chrome.tabs.get(id);
           return { url: t.url ?? "", title: t.title ?? "" };
         }
         // -- reads (isolated world; CSP-safe) --
         case "get_text": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const frameIds = await this.frames(cmd, id);
           const out = await execOp(id, { op: "text", selector: selectorOf(cmd) ?? null }, frameIds);
           if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${selectorOf(cmd)}`);
           return { text: String(out.text ?? ""), frameId: out.frameId };
         }
         case "get_html": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const frameIds = await this.frames(cmd, id);
           const out = await execOp(
             id,
@@ -1135,14 +1353,19 @@
         }
         // -- accessibility snapshot (tags elements with data-mcp-ref so refs work) --
         case "snapshot": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const interactiveOnly = cmd.params.interactiveOnly !== false;
           const max = typeof cmd.params.max === "number" ? cmd.params.max : 200;
+          const loc = cmd.params.locator;
+          const locator = loc && typeof loc === "object" ? {
+            role: typeof loc.role === "string" ? loc.role : void 0,
+            name: typeof loc.name === "string" ? loc.name : void 0
+          } : null;
           const frameIds = await this.frames(cmd, id);
           const raw = await execInTab(
             id,
             collectSnapshot,
-            [interactiveOnly, max],
+            [interactiveOnly, max, locator],
             void 0,
             frameIds
           );
@@ -1150,19 +1373,18 @@
         }
         // -- <select> option(s) by value or visible label --
         case "select_option": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const sel = requireSelector(cmd);
           const frameIds = await this.frames(cmd, id);
           const values = Array.isArray(cmd.params.values) ? cmd.params.values.map(String) : [];
-          await waitForSelector(id, sel, frameIds);
-          const out = await execOp(id, { op: "select", selector: sel, values }, frameIds);
+          const out = await execOp(id, withWait({ op: "select", selector: sel, values }), frameIds);
           if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           if (out.matched !== true) throw new CmdError("SELECTOR_NOT_FOUND", `no <select> option matched for ${sel}`);
           return { ok: true, frameId: out.frameId };
         }
         // -- cookies for the tab's URL (chrome.cookies; needs "cookies" permission) --
         case "get_cookies": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           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");
@@ -1181,7 +1403,7 @@
         }
         // -- localStorage / sessionStorage (isolated world) --
         case "storage": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const op = String(cmd.params.op);
           const key = typeof cmd.params.key === "string" ? cmd.params.key : null;
           const value = typeof cmd.params.value === "string" ? cmd.params.value : null;
@@ -1193,49 +1415,36 @@
         }
         // -- interaction (synthetic events in the isolated world) --
         case "click": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(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}`);
-          }
           if (cmd.params.trusted === true) {
             const verdict = await trustedClick(id, sel, frameIds);
             if (verdict === "missing") throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
             if (verdict === "ok") return { ok: true };
           }
-          const out = await execOp(id, { op: "click", selector: sel }, frameIds);
+          const out = await execOp(id, withWait({ op: "click", selector: sel }), frameIds);
           if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true, frameId: out.frameId, ...cmd.params.trusted === true ? { trusted: false } : {} };
         }
         case "type": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const sel = requireSelector(cmd);
           const frameIds = await this.frames(cmd, id);
           const text = String(cmd.params.text ?? "");
           const clear = cmd.params.clear === true;
-          if (!await waitForSelector(id, sel, frameIds)) {
-            throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
-          }
           if (cmd.params.trusted === true) {
-            if (!await trustedType(id, sel, text, clear, frameIds)) {
+            if (!await trustedType(id, sel, text, clear, frameIds, cmd.params.pressEnter === true)) {
               throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
             }
-            if (cmd.params.pressEnter === true) {
-              await withDebugger(id, async (t) => {
-                for (const type of ["keyDown", "keyUp"]) {
-                  await chrome.debugger.sendCommand(t, "Input.dispatchKeyEvent", { type, key: "Enter", code: "Enter", windowsVirtualKeyCode: 13 });
-                }
-              });
-            }
             return { ok: true };
           }
-          const out = await execOp(id, { op: "type", selector: sel, text, clear }, frameIds);
+          const out = await execOp(id, withWait({ op: "type", selector: sel, text, clear }), frameIds);
           if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true, frameId: out.frameId };
         }
         case "press": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const key = String(cmd.params.key ?? "");
           await execInTab(
             id,
@@ -1250,16 +1459,15 @@
           return { ok: true };
         }
         case "hover": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const sel = requireSelector(cmd);
           const frameIds = await this.frames(cmd, id);
-          await waitForSelector(id, sel, frameIds);
-          const out = await execOp(id, { op: "hover", selector: sel }, frameIds);
+          const out = await execOp(id, withWait({ op: "hover", selector: sel }), frameIds);
           if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true, frameId: out.frameId };
         }
         case "scroll": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const frameIds = await this.frames(cmd, id);
           await execOp(
             id,
@@ -1281,20 +1489,21 @@
         // concurrent batches) and supports true full-page + element capture.
         // Falls back to captureVisibleTab only if the debugger can't attach.
         case "screenshot": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const fullPage = cmd.params.fullPage === true;
           const selector = selectorOf(cmd);
+          const enc = encodingOf(cmd);
           const frameIds = await this.frames(cmd, id);
           try {
-            return await screenshotViaDebugger(id, fullPage, selector, frameIds);
+            return await screenshotViaDebugger(id, fullPage, enc, selector, frameIds);
           } catch (err) {
             if (err instanceof CmdError && err.code === "SELECTOR_NOT_FOUND") throw err;
-            return await screenshotViaVisibleTab(id, fullPage);
+            return await screenshotViaVisibleTab(id, fullPage, enc);
           }
         }
         // -- eval (MAIN world; may be blocked by strict page CSP) --
         case "eval": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const expr = String(cmd.params.expression ?? "");
           const result = await execInTab(
             id,
@@ -1316,7 +1525,7 @@
         // One injection that polls IN-PAGE until the condition holds or the deadline
         // passes, rather than one executeScript round-trip per tick.
         case "wait_for": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const frameIds = await this.frames(cmd, id);
           const timeout = typeof cmd.params.timeoutMs === "number" ? cmd.params.timeoutMs : 3e4;
           const start = Date.now();
@@ -1357,7 +1566,7 @@
         }
         // -- upload: set local file(s) on a file <input> via CDP DOM.setFileInputFiles --
         case "upload_file": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const sel = requireSelector(cmd);
           const files = Array.isArray(cmd.params.files) ? cmd.params.files.map(String) : [];
           if (files.length === 0) throw new CmdError("BAD_ARGS", 'upload_file requires a non-empty "files" array');
@@ -1378,7 +1587,7 @@
         //    Read via a probe injection rather than chrome.webNavigation so no
         //    extra host-level permission is needed to see them. --
         case "frames_list": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const probes = await chrome.scripting.executeScript({
             target: { tabId: id, allFrames: true },
             func: pageOp,
@@ -1400,7 +1609,7 @@
         //    that loaded before registration gets it injected here, and the caller
         //    is told capture only starts from that moment. --
         case "observers": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const frameIds = await this.frames(cmd, id);
           const opts = {
             console: cmd.params.console === true,
@@ -1462,7 +1671,7 @@
         // -- print_pdf: Page.printToPDF over the same one-op debugger attach the
         //    screenshot path uses. Returns base64; the server writes the file. --
         case "print_pdf": {
-          const id = await targetTab(cmd);
+          const id = await targetTab2(cmd);
           const params = {
             printBackground: cmd.params.printBackground !== false,
             landscape: cmd.params.landscape === true,
@@ -1510,14 +1719,15 @@
             "no policy has arrived from the chrome-mcp server yet, so this extension is refusing every command"
           );
         }
+        const tab = await resolveTab(cmd);
         if (policy) {
-          const url = isUrlGated(cmd.method) ? await urlForCommand(cmd) : "";
+          const url = isUrlGated(cmd.method) ? await urlForCommand(cmd, tab) : "";
           const verdict = evaluatePolicy(url, cmd.method, policy);
           if (!verdict.ok) throw new CmdError("POLICY_DENIED", verdict.reason);
         }
-        const data = await this.deps.exec.run(cmd);
+        const data = await this.deps.exec.run(cmd, tab);
         const frame = { type: "result", v: PROTOCOL_VERSION, id: cmd.id, ok: true, data };
-        const tabUrl = await observedTabUrl(cmd);
+        const tabUrl = await observedTabUrl(cmd, tab);
         if (tabUrl) frame.tabUrl = tabUrl;
         this.deps.send(frame);
       } catch (err) {
@@ -1570,10 +1780,29 @@
   var KEEPALIVE_ALARM = "chrome-mcp-keepalive";
   var currentPolicy = null;
   var executor = new ChromeExecutor(() => currentPolicy);
+  var RECONNECT_DELAYS_MS = [1e3, 2e3, 4e3, 8e3, 1e4];
+  var reconnectAttempt = 0;
+  var reconnectTimer = null;
+  function scheduleReconnect() {
+    if (reconnectTimer) return;
+    const delay2 = RECONNECT_DELAYS_MS[Math.min(reconnectAttempt, RECONNECT_DELAYS_MS.length - 1)];
+    reconnectAttempt++;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      void ensureConnected();
+    }, delay2);
+  }
+  function clearReconnect() {
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+    reconnectAttempt = 0;
+  }
   var ws = new WsClient({
     onCommand: (cmd) => void router.dispatch(cmd),
     onState: (state) => {
       void persistState(state);
+      if (state === "connected") clearReconnect();
+      else if (state === "idle") scheduleReconnect();
       if (state === "unauthorized") void adoptBundledPairing();
     },
     onPolicy: (policy) => {
@@ -1672,11 +1901,13 @@
     if (area === "local" && (changes.wsPort || changes.token || changes.profile)) {
       if (ws.state === "unauthorized") ws.state = "idle";
       if (changes.profile) ws.close();
+      clearReconnect();
       void ensureConnected();
     }
   });
   chrome.runtime.onMessage.addListener((msg) => {
     if (msg?.type === "reconnect") {
+      clearReconnect();
       ws.close();
       ws.state = "idle";
       void ensureConnected();