@mehmoodqureshi/chrome-mcp 0.6.7 → 0.7.0

package/extension-dist/background.js

@@ -28,6 +28,9 @@
     "wait_for",
     "download_file",
     "upload_file",
+    "frames_list",
+    "observers",
+    "print_pdf",
     "ping_probe"
   ];
 
@@ -128,7 +131,13 @@
     "get_text",
     "get_html",
     "screenshot",
-    "wait_for"
+    "wait_for",
+    // A frame list leaks the URLs a page embeds; console/network buffers are the
+    // page's own traffic and error text; a PDF is a screenshot by another name.
+    // All three are page CONTENT and gate exactly like the reads above.
+    "frames_list",
+    "observers",
+    "print_pdf"
   ]);
   var MUTATE_CONTENT = /* @__PURE__ */ new Set([
     "click",
@@ -193,6 +202,12 @@
     if (method === "download_file" && !policy.allowDownloads) {
       return { ok: false, reason: "downloads are disabled. Pass --enable-downloads or set allowDownloads." };
     }
+    if (method === "observers" && !policy.allowObservers) {
+      return {
+        ok: false,
+        reason: "the in-page observers (console_logs / network_log / dialogs) are disabled. They patch console, fetch, XMLHttpRequest and the dialog functions on every allowlisted page in your real browser, so they are opt-in: pass --enable-observers or set allowObservers."
+      };
+    }
     if (method === "upload_file" && !policy.allowUploads) {
       return {
         ok: false,
@@ -366,8 +381,10 @@
       const ref = `e${++n}`;
       el.setAttribute("data-mcp-ref", ref);
       const node = { ref, 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 (typeof v === "string" && v) node.value = v.slice(0, 200);
+      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);
@@ -375,6 +392,289 @@
     return { url: location.href, title: document.title, nodes, truncated: els.length > nodes.length };
   }
 
+  // shared/page-fns.ts
+  function pageOp(a) {
+    const deepQuery = (sel2) => {
+      const roots = [document];
+      const seen = /* @__PURE__ */ new Set();
+      while (roots.length > 0) {
+        const root = roots.shift();
+        if (seen.has(root)) continue;
+        seen.add(root);
+        let hit = null;
+        try {
+          hit = root.querySelector(sel2);
+        } catch {
+          return null;
+        }
+        if (hit) return hit;
+        let hosts = [];
+        try {
+          hosts = Array.from(root.querySelectorAll("*"));
+        } catch {
+          hosts = [];
+        }
+        for (const host of hosts) {
+          const sr = host.shadowRoot;
+          if (sr && !seen.has(sr)) roots.push(sr);
+        }
+      }
+      return null;
+    };
+    const frameOffset = () => {
+      let dx = 0;
+      let dy = 0;
+      let win = window;
+      try {
+        while (win.parent && win.parent !== win) {
+          const fe = win.frameElement;
+          if (!fe) return { dx, dy, exact: false, scrollX: window.scrollX, scrollY: window.scrollY };
+          const r = fe.getBoundingClientRect();
+          dx += r.left;
+          dy += r.top;
+          win = win.parent;
+        }
+      } catch {
+        return { dx, dy, exact: false, scrollX: window.scrollX, scrollY: window.scrollY };
+      }
+      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;
+        }
+        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 };
+        }
+        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)}` };
+    }
+  }
+
+  // shared/observers.ts
+  var OBSERVER_GLOBAL = "__chromeMcpObservers";
+  function readObservers(globalName, opts) {
+    const state = window[globalName];
+    if (!state) return { installed: false };
+    if (opts.setPolicy === "dismiss" || opts.setPolicy === "accept") state.dialogPolicy = opts.setPolicy;
+    if (typeof opts.promptText === "string") state.promptText = opts.promptText;
+    const since = typeof opts.sinceSeq === "number" ? opts.sinceSeq : 0;
+    const limit = typeof opts.limit === "number" && opts.limit > 0 ? opts.limit : 200;
+    const take = (buf) => {
+      const picked = buf.filter((e) => e.seq > since);
+      return picked.length > limit ? picked.slice(picked.length - limit) : picked;
+    };
+    if (opts.network && opts.includeResources) {
+      try {
+        const entries = performance.getEntriesByType("resource");
+        for (let i = state.resourceCursor; i < entries.length; i++) {
+          const r = entries[i];
+          state.network.push({
+            seq: ++state.seq,
+            ts: Math.round(performance.timeOrigin + r.startTime),
+            via: "resource",
+            method: "GET",
+            url: r.name.length > 2e3 ? `${r.name.slice(0, 2e3)}\u2026` : r.name,
+            durationMs: Math.round(r.duration),
+            initiator: r.initiatorType,
+            bytes: r.transferSize || void 0
+          });
+        }
+        state.resourceCursor = entries.length;
+      } catch {
+      }
+    }
+    const out = {
+      installed: true,
+      hookVersion: state.v,
+      dialogPolicy: state.dialogPolicy,
+      dropped: state.dropped
+    };
+    if (opts.console) out.console = take(state.console);
+    if (opts.network) out.network = take(state.network);
+    if (opts.dialogs) out.dialogs = take(state.dialogs);
+    if (opts.clear) {
+      if (opts.console) state.console.length = 0;
+      if (opts.network) state.network.length = 0;
+      if (opts.dialogs) state.dialogs.length = 0;
+      state.dropped = false;
+    }
+    return out;
+  }
+  function observerMatches(policy) {
+    if (policy.allowObservers !== true) return [];
+    const out = /* @__PURE__ */ new Set();
+    for (const raw of policy.allowDomains ?? []) {
+      const p = normalizeDomainPattern(raw);
+      if (!p) continue;
+      if (p === "*") return ["<all_urls>"];
+      out.add(`*://${p}/*`);
+    }
+    return [...out];
+  }
+
   // shared/screenshot.ts
   var MAX_CAPTURE_PX = 16384;
   function planScreenshot(dims, opts = {}) {
@@ -510,15 +810,32 @@
       return "";
     }
   }
-  async function execInTab(tabId, func, args = [], world) {
+  function scriptTarget(tabId, frameIds) {
+    return frameIds && frameIds.length > 0 ? { tabId, frameIds } : { tabId };
+  }
+  async function execInTab(tabId, func, args = [], world, frameIds) {
     const [res] = await chrome.scripting.executeScript({
-      target: { tabId },
+      target: scriptTarget(tabId, frameIds),
       func,
       args,
       world
     });
     return res?.result;
   }
+  async function execOp(tabId, args, frameIds, world) {
+    const results = await chrome.scripting.executeScript({
+      target: scriptTarget(tabId, frameIds),
+      func: pageOp,
+      args: [args],
+      world
+    });
+    const outcomes = results.map((r) => ({
+      ...r.result ?? { found: false },
+      frameId: r.frameId ?? 0
+    }));
+    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) {
     const start = Date.now();
     for (; ; ) {
@@ -538,21 +855,9 @@
   function selectorOf(cmd) {
     return resolveSelector(cmd);
   }
-  async function waitForSelector(tabId, selector, timeoutMs = 5e3) {
-    const found = await execInTab(
-      tabId,
-      (s, timeout, interval) => new Promise((resolve) => {
-        const deadline = Date.now() + timeout;
-        const tick = () => {
-          if (document.querySelector(s)) return resolve(true);
-          if (Date.now() > deadline) return resolve(false);
-          setTimeout(tick, interval);
-        };
-        tick();
-      }),
-      [selector, timeoutMs, 120]
-    );
-    return found === true;
+  async function waitForSelector(tabId, selector, frameIds, timeoutMs = 5e3) {
+    const out = await execOp(tabId, { op: "waitSelector", selector, timeoutMs, interval: 120 }, frameIds);
+    return out.found === true;
   }
   async function withDebugger(tabId, fn) {
     return locks.run(`dbg:${tabId}`, async () => {
@@ -565,69 +870,34 @@
       }
     });
   }
-  async function trustedType(tabId, selector, text, clear) {
-    const focused = await execInTab(
-      tabId,
-      (s, doClear) => {
-        const el = document.querySelector(s);
-        if (!el) return false;
-        el.focus();
-        if (doClear) {
-          const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), "value")?.set;
-          setter ? setter.call(el, "") : el.value = "";
-          el.dispatchEvent(new Event("input", { bubbles: true }));
-        }
-        return true;
-      },
-      [selector, clear]
-    );
-    if (!focused) return false;
+  async function trustedType(tabId, selector, text, clear, frameIds) {
+    const focused = await execOp(tabId, { op: "focus", selector, clear }, frameIds);
+    if (!focused.found) return false;
     await withDebugger(tabId, (t) => chrome.debugger.sendCommand(t, "Input.insertText", { text }));
     return true;
   }
-  async function trustedClick(tabId, selector) {
-    const pt = await execInTab(
-      tabId,
-      (s) => {
-        const el = document.querySelector(s);
-        if (!el) return null;
-        el.scrollIntoView({ block: "center", inline: "center" });
-        const r = el.getBoundingClientRect();
-        return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
-      },
-      [selector]
-    );
-    if (!pt) return false;
+  async function trustedClick(tabId, selector, frameIds) {
+    const pt = await execOp(tabId, { op: "point", selector }, frameIds);
+    if (!pt.found) return "missing";
+    if (pt.exact === false) return "inexact";
     await withDebugger(tabId, async (t) => {
       const base = { x: pt.x, y: pt.y, button: "left", clickCount: 1 };
       await chrome.debugger.sendCommand(t, "Input.dispatchMouseEvent", { type: "mousePressed", buttons: 1, ...base });
       await chrome.debugger.sendCommand(t, "Input.dispatchMouseEvent", { type: "mouseReleased", buttons: 0, ...base });
     });
-    return true;
+    return "ok";
   }
-  async function measurePage(tabId, selector) {
-    return execInTab(
-      tabId,
-      (sel) => {
-        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 { dims, element: null, missing: false };
-        const el = document.querySelector(sel);
-        if (!el) return { dims, element: null, missing: true };
-        el.scrollIntoView({ block: "center", inline: "center" });
-        const r = el.getBoundingClientRect();
-        return { dims, element: { x: r.left + window.scrollX, y: r.top + window.scrollY, w: r.width, h: r.height }, missing: false };
-      },
-      [selector ?? null]
-    );
+  async function measurePage(tabId, selector, frameIds) {
+    const found = await execOp(tabId, { op: "measure", selector: selector ?? null }, frameIds);
+    const top = selector && frameIds && frameIds.length > 0 ? await execOp(tabId, { op: "measure", selector: null }) : found;
+    return {
+      dims: top.dims,
+      element: found.element ?? null,
+      missing: found.missing === true
+    };
   }
-  async function screenshotViaDebugger(tabId, fullPage, selector) {
-    const measured = await measurePage(tabId, selector);
+  async function screenshotViaDebugger(tabId, fullPage, 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 });
@@ -705,9 +975,67 @@
     "wait_for",
     "download_file",
     "upload_file",
-    "ping_probe"
+    "ping_probe",
+    "frames_list",
+    "observers",
+    "print_pdf"
   ]);
   var ChromeExecutor = class {
+    /**
+     * The live wire policy, so frame-scoped commands can be gated against the
+     * FRAME's origin rather than the tab's. The router gates the tab; only this
+     * side knows which frames an injection would actually reach, and an
+     * allowlisted page embedding a third-party iframe is the ordinary case, not an
+     * exotic one.
+     */
+    constructor(getPolicy = () => null) {
+      this.getPolicy = getPolicy;
+    }
+    /**
+     * 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.
+     * `undefined` means the top frame only (the default, and every call that
+     * predates frame support).
+     *
+     * The URL probe is a separate round-trip on purpose: filtering AFTER running
+     * the command would mean a mutation had already fired inside a frame nobody
+     * authorized.
+     */
+    async frames(cmd, tabId) {
+      const explicit = typeof cmd.params.frameId === "number" ? cmd.params.frameId : void 0;
+      const all = cmd.params.allFrames === true;
+      if (explicit === void 0 && !all) return void 0;
+      const probes = await chrome.scripting.executeScript({
+        target: explicit !== void 0 ? { tabId, frameIds: [explicit] } : { tabId, allFrames: true },
+        func: pageOp,
+        args: [{ op: "probe" }]
+      }).catch(() => []);
+      const seen = probes.map((r) => ({
+        frameId: r.frameId ?? 0,
+        url: String(r.result?.url ?? "")
+      }));
+      if (seen.length === 0) {
+        throw new CmdError(
+          "FRAME_NOT_FOUND",
+          explicit !== void 0 ? `frame ${explicit} is not in this tab (or the extension cannot inject into it) \u2014 call frames_list` : "no injectable frames in this tab"
+        );
+      }
+      const policy = this.getPolicy();
+      if (!policy) throw new CmdError("POLICY_DENIED", "no policy has arrived yet, so no frame is authorized");
+      const allowed = [];
+      const denied = [];
+      for (const f of seen) {
+        if (evaluatePolicy(f.url, cmd.method, policy).ok) allowed.push(f.frameId);
+        else denied.push(f.url || `frame ${f.frameId}`);
+      }
+      if (allowed.length === 0) {
+        throw new CmdError(
+          "POLICY_DENIED",
+          `no targeted frame is on the allowed-sites list (skipped: ${denied.slice(0, 5).join(", ")})`
+        );
+      }
+      return allowed;
+    }
     async run(cmd) {
       switch (cmd.method) {
         case "ping_probe":
@@ -789,39 +1117,34 @@
         // -- reads (isolated world; CSP-safe) --
         case "get_text": {
           const id = await targetTab(cmd);
-          const text = await execInTab(
-            id,
-            (sel) => {
-              const el = sel ? document.querySelector(sel) : document.body;
-              return el ? el.innerText : "";
-            },
-            [selectorOf(cmd) ?? null]
-          );
-          return { text: text ?? "" };
+          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 outer = cmd.params.outer === true;
-          const html = await execInTab(
+          const frameIds = await this.frames(cmd, id);
+          const out = await execOp(
             id,
-            (sel, isOuter) => {
-              const el = sel ? document.querySelector(sel) : document.documentElement;
-              if (!el) return "";
-              return isOuter || !sel ? el.outerHTML : el.innerHTML;
-            },
-            [selectorOf(cmd) ?? null, outer]
+            { op: "html", selector: selectorOf(cmd) ?? null, outer: cmd.params.outer === true },
+            frameIds
           );
-          return { html: html ?? "" };
+          if (!out.found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${selectorOf(cmd)}`);
+          return { html: String(out.html ?? ""), frameId: out.frameId };
         }
         // -- accessibility snapshot (tags elements with data-mcp-ref so refs work) --
         case "snapshot": {
           const id = await targetTab(cmd);
           const interactiveOnly = cmd.params.interactiveOnly !== false;
           const max = typeof cmd.params.max === "number" ? cmd.params.max : 200;
+          const frameIds = await this.frames(cmd, id);
           const raw = await execInTab(
             id,
             collectSnapshot,
-            [interactiveOnly, max]
+            [interactiveOnly, max],
+            void 0,
+            frameIds
           );
           return raw ?? { url: "", title: "", nodes: [], truncated: false };
         }
@@ -829,28 +1152,13 @@
         case "select_option": {
           const id = await targetTab(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);
-          const matched = await execInTab(
-            id,
-            (s, vals) => {
-              const el = document.querySelector(s);
-              if (!el || !el.options) return false;
-              const set = new Set(vals);
-              let hit = false;
-              for (const opt of Array.from(el.options)) {
-                const on = set.has(opt.value) || set.has(opt.label) || set.has(opt.text);
-                opt.selected = on;
-                if (on) hit = true;
-              }
-              el.dispatchEvent(new Event("input", { bubbles: true }));
-              el.dispatchEvent(new Event("change", { bubbles: true }));
-              return hit;
-            },
-            [sel, values]
-          );
-          if (!matched) throw new CmdError("SELECTOR_NOT_FOUND", `no <select> option matched for ${sel}`);
-          return { ok: true };
+          await waitForSelector(id, sel, frameIds);
+          const out = await execOp(id, { 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": {
@@ -878,65 +1186,41 @@
           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;
-          const res = await execInTab(
-            id,
-            (o, k, v, s) => {
-              const store = s ? window.sessionStorage : window.localStorage;
-              if (o === "set") {
-                store.setItem(String(k), String(v ?? ""));
-                return { ok: true };
-              }
-              if (o === "remove") {
-                store.removeItem(String(k));
-                return { ok: true };
-              }
-              if (o === "clear") {
-                store.clear();
-                return { ok: true };
-              }
-              if (k) return { ok: true, value: store.getItem(k) };
-              const entries = {};
-              for (let i = 0; i < store.length; i++) {
-                const kk = store.key(i);
-                if (kk) entries[kk] = store.getItem(kk) ?? "";
-              }
-              return { ok: true, entries };
-            },
-            [op, key, value, session]
-          );
-          return res ?? { ok: false };
+          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;
+          return Object.keys(rest).length > 0 ? rest : { ok: false };
         }
         // -- interaction (synthetic events in the isolated world) --
         case "click": {
           const id = await targetTab(cmd);
           const sel = requireSelector(cmd);
-          if (!await waitForSelector(id, sel)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+          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) {
-            if (!await trustedClick(id, sel)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
-            return { ok: 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 found = await execInTab(
-            id,
-            (s) => {
-              const el = document.querySelector(s);
-              if (!el) return false;
-              el.scrollIntoView({ block: "center" });
-              el.click();
-              return true;
-            },
-            [sel]
-          );
-          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
-          return { ok: true };
+          const out = await execOp(id, { 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 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)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+          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)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+            if (!await trustedType(id, sel, text, clear, frameIds)) {
+              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"]) {
@@ -946,23 +1230,9 @@
             }
             return { ok: true };
           }
-          const found = await execInTab(
-            id,
-            (s, value, doClear) => {
-              const el = document.querySelector(s);
-              if (!el) return false;
-              el.focus();
-              const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), "value")?.set;
-              const next = (doClear ? "" : el.value ?? "") + value;
-              setter ? setter.call(el, next) : el.value = next;
-              el.dispatchEvent(new Event("input", { bubbles: true }));
-              el.dispatchEvent(new Event("change", { bubbles: true }));
-              return true;
-            },
-            [sel, text, clear]
-          );
-          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
-          return { ok: true };
+          const out = await execOp(id, { 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);
@@ -982,27 +1252,26 @@
         case "hover": {
           const id = await targetTab(cmd);
           const sel = requireSelector(cmd);
-          await waitForSelector(id, sel);
-          await execInTab(
-            id,
-            (s) => {
-              const el = document.querySelector(s);
-              el?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
-              el?.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
-            },
-            [sel]
-          );
-          return { ok: true };
+          const frameIds = await this.frames(cmd, id);
+          await waitForSelector(id, sel, frameIds);
+          const out = await execOp(id, { 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);
-          await execInTab(
+          const frameIds = await this.frames(cmd, id);
+          await execOp(
             id,
-            (x, y, dx, dy) => {
-              if (x != null || y != null) window.scrollTo(x ?? 0, y ?? 0);
-              else window.scrollBy(dx ?? 0, dy ?? 0);
+            {
+              op: "scroll",
+              selector: selectorOf(cmd) ?? null,
+              x: cmd.params.x ?? null,
+              y: cmd.params.y ?? null,
+              deltaX: cmd.params.deltaX ?? null,
+              deltaY: cmd.params.deltaY ?? null
             },
-            [cmd.params.x ?? null, cmd.params.y ?? null, cmd.params.deltaX ?? null, cmd.params.deltaY ?? null]
+            frameIds
           );
           return { ok: true };
         }
@@ -1015,8 +1284,9 @@
           const id = await targetTab(cmd);
           const fullPage = cmd.params.fullPage === true;
           const selector = selectorOf(cmd);
+          const frameIds = await this.frames(cmd, id);
           try {
-            return await screenshotViaDebugger(id, fullPage, selector);
+            return await screenshotViaDebugger(id, fullPage, selector, frameIds);
           } catch (err) {
             if (err instanceof CmdError && err.code === "SELECTOR_NOT_FOUND") throw err;
             return await screenshotViaVisibleTab(id, fullPage);
@@ -1037,7 +1307,8 @@
               }
             },
             [expr],
-            "MAIN"
+            "MAIN",
+            await this.frames(cmd, id)
           );
           return result ?? { ok: false, error: "no result" };
         }
@@ -1046,29 +1317,22 @@
         // passes, rather than one executeScript round-trip per tick.
         case "wait_for": {
           const id = await targetTab(cmd);
+          const frameIds = await this.frames(cmd, id);
           const timeout = typeof cmd.params.timeoutMs === "number" ? cmd.params.timeoutMs : 3e4;
           const start = Date.now();
-          const matched = await execInTab(
+          const out = await execOp(
             id,
-            (sel, text, gone, timeoutMs, interval) => new Promise((resolve) => {
-              const deadline = Date.now() + timeoutMs;
-              const hit = () => {
-                let present;
-                if (sel) present = !!document.querySelector(sel);
-                else if (text) present = (document.body?.innerText ?? "").includes(text);
-                else present = true;
-                return gone ? !present : present;
-              };
-              const tick = () => {
-                if (hit()) return resolve(true);
-                if (Date.now() > deadline) return resolve(false);
-                setTimeout(tick, interval);
-              };
-              tick();
-            }),
-            [cmd.params.selector ?? null, cmd.params.textContains ?? null, cmd.params.gone === true, timeout, 150]
+            {
+              op: "waitFor",
+              selector: cmd.params.selector ?? null,
+              textContains: cmd.params.textContains ?? null,
+              gone: cmd.params.gone === true,
+              timeoutMs: timeout,
+              interval: 150
+            },
+            frameIds
           );
-          return { matched: matched === true, waitedMs: Date.now() - start };
+          return { matched: out.matched === true, waitedMs: Date.now() - start };
         }
         // -- download (saved to the user's Downloads dir; the server then moves it
         //    into the active task's downloads/). We wait for completion and report
@@ -1097,7 +1361,9 @@
           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');
-          if (!await waitForSelector(id, sel)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+          if (!await waitForSelector(id, sel, void 0)) {
+            throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+          }
           await withDebugger(id, async (t) => {
             const doc = await chrome.debugger.sendCommand(t, "DOM.getDocument", { depth: 0 });
             const rootId = doc.root?.nodeId;
@@ -1108,6 +1374,112 @@
           });
           return { ok: true };
         }
+        // -- frames: the ids an injection can target, plus each frame's URL.
+        //    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 probes = await chrome.scripting.executeScript({
+            target: { tabId: id, allFrames: true },
+            func: pageOp,
+            args: [{ op: "probe" }]
+          }).catch(() => []);
+          const frames = probes.map((r) => {
+            const res = r.result ?? {};
+            return {
+              frameId: r.frameId ?? 0,
+              top: (r.frameId ?? 0) === 0,
+              url: res.url ?? "",
+              title: res.title ?? ""
+            };
+          });
+          return { frames, count: frames.length };
+        }
+        // -- observers: read (and configure) the in-page console/network/dialog
+        //    buffers. The hook is normally registered at document_start; a page
+        //    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 frameIds = await this.frames(cmd, id);
+          const opts = {
+            console: cmd.params.console === true,
+            network: cmd.params.network === true,
+            dialogs: cmd.params.dialogs === true,
+            sinceSeq: typeof cmd.params.sinceSeq === "number" ? cmd.params.sinceSeq : 0,
+            limit: typeof cmd.params.limit === "number" ? cmd.params.limit : 200,
+            clear: cmd.params.clear === true,
+            setPolicy: typeof cmd.params.setPolicy === "string" ? cmd.params.setPolicy : null,
+            promptText: typeof cmd.params.promptText === "string" ? cmd.params.promptText : null,
+            includeResources: cmd.params.includeResources === true
+          };
+          const read = async () => {
+            const results = await chrome.scripting.executeScript({
+              target: scriptTarget(id, frameIds),
+              func: readObservers,
+              args: [OBSERVER_GLOBAL, opts],
+              world: "MAIN"
+            });
+            return results.map((r) => ({
+              frameId: r.frameId ?? 0,
+              out: r.result ?? { installed: false }
+            }));
+          };
+          let frames = await read();
+          let justInstalled = false;
+          if (!frames.some((f) => f.out.installed === true)) {
+            await chrome.scripting.executeScript({ target: scriptTarget(id, frameIds), files: ["page-hook.js"], world: "MAIN" }).catch(() => void 0);
+            frames = await read();
+            justInstalled = frames.some((f) => f.out.installed === true);
+          }
+          const live = frames.filter((f) => f.out.installed === true);
+          if (live.length === 0) return { installed: false };
+          const merge = (key) => {
+            const all = [];
+            for (const f of live) {
+              for (const e of f.out[key] ?? []) {
+                all.push(f.frameId === 0 ? e : { ...e, frameId: f.frameId });
+              }
+            }
+            return all.sort((a, b) => Number(a.ts ?? 0) - Number(b.ts ?? 0));
+          };
+          const top = live.find((f) => f.frameId === 0) ?? live[0];
+          return {
+            installed: true,
+            hookVersion: top.out.hookVersion,
+            dialogPolicy: top.out.dialogPolicy,
+            dropped: live.some((f) => f.out.dropped === true),
+            ...opts.console ? { console: merge("console") } : {},
+            ...opts.network ? { network: merge("network") } : {},
+            ...opts.dialogs ? { dialogs: merge("dialogs") } : {},
+            ...live.length > 1 ? { frames: live.length } : {},
+            ...justInstalled ? {
+              justInstalled: true,
+              note: "the observer hook was installed just now, so these buffers start empty - reload the page to capture what happens during load"
+            } : {}
+          };
+        }
+        // -- 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 params = {
+            printBackground: cmd.params.printBackground !== false,
+            landscape: cmd.params.landscape === true,
+            preferCSSPageSize: cmd.params.preferCSSPageSize === true
+          };
+          if (typeof cmd.params.scale === "number") params.scale = cmd.params.scale;
+          if (typeof cmd.params.paperWidth === "number") params.paperWidth = cmd.params.paperWidth;
+          if (typeof cmd.params.paperHeight === "number") params.paperHeight = cmd.params.paperHeight;
+          if (typeof cmd.params.pageRanges === "string") params.pageRanges = cmd.params.pageRanges;
+          const data = await withDebugger(id, async (t2) => {
+            const res = await chrome.debugger.sendCommand(t2, "Page.printToPDF", params);
+            return res.data ?? "";
+          });
+          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 ?? "" };
+        }
         default:
           throw new CmdError("UNKNOWN_METHOD", `unhandled method: ${cmd.method}`);
       }
@@ -1164,15 +1536,46 @@
     }
   };
 
+  // extension/src/sw/observers.ts
+  var SCRIPT_ID = "chrome-mcp-observers";
+  async function syncObserverScript(policy, log) {
+    try {
+      const existing = await chrome.scripting.getRegisteredContentScripts({ ids: [SCRIPT_ID] }).catch(() => []);
+      const wanted = policy ? observerMatches(policy) : [];
+      if (wanted.length === 0) {
+        if (existing.length > 0) {
+          await chrome.scripting.unregisterContentScripts({ ids: [SCRIPT_ID] });
+          log("observers: unregistered (disabled by policy)");
+        }
+        return;
+      }
+      const spec = {
+        id: SCRIPT_ID,
+        js: ["page-hook.js"],
+        matches: wanted,
+        runAt: "document_start",
+        allFrames: true,
+        world: "MAIN",
+        persistAcrossSessions: false
+      };
+      if (existing.length > 0) await chrome.scripting.updateContentScripts([spec]);
+      else await chrome.scripting.registerContentScripts([spec]);
+      log(`observers: registered for ${wanted.join(", ")}`);
+    } catch (err) {
+      log(`observers: registration failed (${err instanceof Error ? err.message : String(err)})`);
+    }
+  }
+
   // extension/src/sw/background.ts
   var KEEPALIVE_ALARM = "chrome-mcp-keepalive";
   var currentPolicy = null;
-  var executor = new ChromeExecutor();
+  var executor = new ChromeExecutor(() => currentPolicy);
   var ws = new WsClient({
     onCommand: (cmd) => void router.dispatch(cmd),
     onState: (state) => void persistState(state),
     onPolicy: (policy) => {
       currentPolicy = policy;
+      void syncObserverScript(policy, (m) => console.debug("[chrome-mcp]", m));
     },
     log: (m) => console.debug("[chrome-mcp]", m)
   });