npm - @mehmoodqureshi/chrome-mcp - Versions diffs - 0.1.0 → 0.2.0 - Mend

@mehmoodqureshi/chrome-mcp 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/README.md +38 -5
package/dist/shared/protocol.d.ts +1 -1
package/dist/shared/protocol.js +4 -0
package/dist/shared/snapshot.d.ts +26 -0
package/dist/shared/snapshot.js +92 -0
package/dist/src/bridge/auth.d.ts +23 -1
package/dist/src/bridge/auth.js +68 -1
package/dist/src/cli.js +7 -1
package/dist/src/config.d.ts +2 -0
package/dist/src/config.js +8 -0
package/dist/src/executor/cdp-executor.d.ts +24 -1
package/dist/src/executor/cdp-executor.js +72 -1
package/dist/src/executor/extension-executor.d.ts +24 -1
package/dist/src/executor/extension-executor.js +14 -2
package/dist/src/executor/stub-executor.d.ts +10 -1
package/dist/src/executor/stub-executor.js +19 -0
package/dist/src/executor/types.d.ts +60 -0
package/dist/src/mcp/tools.js +43 -2
package/extension-dist/background.js +307 -25
package/extension-dist/manifest.json +2 -2
package/extension-dist/options.js +6 -3
package/package.json +2 -2

package/dist/src/executor/stub-executor.d.ts CHANGED Viewed

@@ -7,7 +7,7 @@
  *   2. Drives the dispatch/policy/envelope tests with deterministic, canned
  *      values (and a couple of forced-failure switches).
  */
-import { type ActionOk, type BackendKind, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type NavResult, type ScreenshotResult, type TabId, type TabInfo, type Target, type WaitResult } from './types';
+import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type NavResult, type ScreenshotResult, type SnapshotResult, type StorageOp, type StorageResult, type TabId, type TabInfo, type Target, type WaitResult } from './types';
 export interface StubOptions {
     /** URL of the (single) active tab — used to exercise the domain policy gate. */
     activeUrl?: string;
@@ -43,6 +43,7 @@ export declare class StubExecutor implements Executor {
     fill(): Promise<ActionOk>;
     press(): Promise<ActionOk>;
     hover(): Promise<ActionOk>;
+    selectOption(): Promise<ActionOk>;
     scroll(): Promise<ActionOk>;
     getText(_t?: Target): Promise<{
         text: string;
@@ -51,6 +52,14 @@ export declare class StubExecutor implements Executor {
     getHtml(): Promise<{
         html: string;
     }>;
+    snapshot(): Promise<SnapshotResult>;
+    getCookies(): Promise<{
+        cookies: CookieItem[];
+    }>;
+    storage(args: {
+        op: StorageOp;
+        key?: string;
+    }): Promise<StorageResult>;
     screenshot(): Promise<ScreenshotResult>;
     eval(expression: string): Promise<EvalResult>;
     waitFor(): Promise<WaitResult>;

package/dist/src/executor/stub-executor.js CHANGED Viewed

@@ -85,6 +85,9 @@ class StubExecutor {
     async hover() {
         return ok;
     }
+    async selectOption() {
+        return ok;
+    }
     async scroll() {
         return ok;
     }
@@ -94,6 +97,22 @@ class StubExecutor {
     async getHtml() {
         return { html: '<html><body><a href="https://example.com">Example</a></body></html>' };
     }
+    async snapshot() {
+        return {
+            url: this.url,
+            title: 'Stub Page',
+            nodes: [{ ref: 'e1', role: 'link', name: 'Example', tag: 'a' }],
+            truncated: false,
+        };
+    }
+    async getCookies() {
+        return { cookies: [{ name: 'stub', value: '1', domain: 'example.com', path: '/', secure: true, httpOnly: false }] };
+    }
+    async storage(args) {
+        if (args.op === 'get')
+            return { ok: true, value: args.key ? 'stub-value' : null, entries: args.key ? undefined : { k: 'stub-value' } };
+        return { ok: true };
+    }
     async screenshot() {
         return { dataBase64: TINY_PNG, mimeType: 'image/png', width: 1, height: 1, truncated: false };
     }

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

@@ -75,6 +75,39 @@ export interface DownloadResult {
     mimeType?: string;
     suggestedName?: string;
 }
+/** One interactive/landmark element in an accessibility snapshot. `ref` is stable until the tab navigates. */
+export interface SnapshotNode {
+    ref: string;
+    role: string;
+    name: string;
+    tag: string;
+    value?: string;
+    disabled?: boolean;
+    checked?: boolean;
+}
+export interface SnapshotResult {
+    url: string;
+    title: string;
+    nodes: SnapshotNode[];
+    truncated: boolean;
+}
+export interface CookieItem {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    secure: boolean;
+    httpOnly: boolean;
+    expires?: number;
+}
+export type StorageOp = 'get' | 'set' | 'remove' | 'clear';
+export interface StorageResult {
+    ok: boolean;
+    /** For `get`: the value (or null if absent). For others: omitted. */
+    value?: string | null;
+    /** For a keyless `get`: the whole store as a flat object. */
+    entries?: Record<string, string>;
+}
 export interface ExecutorStatus {
     ready: boolean;
     backend: BackendKind | null;
@@ -119,12 +152,18 @@ export interface Executor {
         tabId?: TabId;
         button?: MouseButton;
         clickCount?: number;
+        trusted?: boolean;
     }): Promise<ActionOk>;
     type(t: Target, text: string, opts?: {
         tabId?: TabId;
         clear?: boolean;
         pressEnter?: boolean;
         keyEvents?: boolean;
+        trusted?: boolean;
+    }): Promise<ActionOk>;
+    /** Choose option(s) of a <select> by value or visible label. */
+    selectOption(t: Target, values: string[], opts?: {
+        tabId?: TabId;
     }): Promise<ActionOk>;
     /** Value-set + input/change events (used by fill_form). */
     fill(t: Target, value: string, opts?: {
@@ -157,6 +196,27 @@ export interface Executor {
     }): Promise<{
         html: string;
     }>;
+    /** Accessibility snapshot: interactive/landmark elements with stable refs the model can target. */
+    snapshot(opts?: {
+        tabId?: TabId;
+        interactiveOnly?: boolean;
+        max?: number;
+    }): Promise<SnapshotResult>;
+    /** Read cookies visible to the active tab's URL (or a given url). */
+    getCookies(opts?: {
+        tabId?: TabId;
+        url?: string;
+    }): Promise<{
+        cookies: CookieItem[];
+    }>;
+    /** localStorage/sessionStorage get/set/remove/clear for the active tab. */
+    storage(args: {
+        op: StorageOp;
+        key?: string;
+        value?: string;
+        session?: boolean;
+        tabId?: TabId;
+    }): Promise<StorageResult>;
     screenshot(opts?: {
         tabId?: TabId;
         fullPage?: boolean;

package/dist/src/mcp/tools.js CHANGED Viewed

@@ -41,14 +41,18 @@ exports.TOOL_DEFINITIONS = [
     { name: 'back', description: 'Go back in history.', inputSchema: obj({ tabId: { type: 'string' } }) },
     { name: 'forward', description: 'Go forward in history.', inputSchema: obj({ tabId: { type: 'string' } }) },
     { name: 'reload', description: 'Reload the active (or given) tab.', inputSchema: obj({ tabId: { type: 'string' }, waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] } }) },
-    { name: 'click', description: 'Click an element.', inputSchema: obj({ ...TARGET_PROPS, tabId: { type: 'string' }, button: { type: 'string', enum: ['left', 'right', 'middle'] }, clickCount: { type: 'number' } }) },
-    { name: 'type', description: 'Type text into an element.', inputSchema: obj({ ...TARGET_PROPS, text: { type: 'string' }, tabId: { type: 'string' }, clear: { type: 'boolean' }, pressEnter: { type: 'boolean' }, keyEvents: { type: 'boolean' } }, ['text']) },
+    { name: 'click', description: 'Click an element (target by selector or a snapshot ref). trusted=true uses real OS-level input.', inputSchema: obj({ ...TARGET_PROPS, tabId: { type: 'string' }, button: { type: 'string', enum: ['left', 'right', 'middle'] }, clickCount: { type: 'number' }, trusted: { type: 'boolean' } }) },
+    { name: 'type', description: 'Type text into an element. trusted=true sends real keystrokes (works on React/Vue controlled inputs).', inputSchema: obj({ ...TARGET_PROPS, text: { type: 'string' }, tabId: { type: 'string' }, clear: { type: 'boolean' }, pressEnter: { type: 'boolean' }, keyEvents: { type: 'boolean' }, trusted: { type: 'boolean' } }, ['text']) },
+    { name: 'select_option', description: 'Select option(s) of a <select> by value or visible label.', inputSchema: obj({ ...TARGET_PROPS, values: { type: 'array', items: { type: 'string' } }, tabId: { type: 'string' } }, ['values']) },
     { name: 'press', description: 'Press a key (with optional modifiers).', inputSchema: obj({ key: { type: 'string' }, modifiers: { type: 'array', items: { type: 'string' } }, tabId: { type: 'string' } }, ['key']) },
     { name: 'hover', description: 'Hover over an element.', inputSchema: obj({ ...TARGET_PROPS, tabId: { type: 'string' } }) },
     { name: 'scroll', description: 'Scroll the page or to an element.', inputSchema: obj({ ...TARGET_PROPS, x: { type: 'number' }, y: { type: 'number' }, deltaX: { type: 'number' }, deltaY: { type: 'number' }, tabId: { type: 'string' } }) },
     { name: 'screenshot', description: 'Capture a PNG screenshot (page or element).', inputSchema: obj({ ...TARGET_PROPS, fullPage: { type: 'boolean' }, tabId: { type: 'string' } }) },
     { name: 'get_text', description: 'Get visible text of the page or an element.', inputSchema: obj({ ...TARGET_PROPS, tabId: { type: 'string' } }) },
     { name: 'get_html', description: 'Get HTML of the page or an element.', inputSchema: obj({ ...TARGET_PROPS, outer: { type: 'boolean' }, tabId: { type: 'string' } }) },
+    { name: 'snapshot', description: 'Accessibility snapshot: interactive elements with stable refs to target by `ref` (more reliable than guessing CSS selectors).', inputSchema: obj({ interactiveOnly: { type: 'boolean' }, max: { type: 'number' }, tabId: { type: 'string' } }) },
+    { name: 'get_cookies', description: "Read cookies visible to the tab's URL (or a given url).", inputSchema: obj({ url: { type: 'string' }, tabId: { type: 'string' } }) },
+    { name: 'storage', description: 'Read/write localStorage (or sessionStorage). op: get|set|remove|clear.', inputSchema: obj({ op: { type: 'string', enum: ['get', 'set', 'remove', 'clear'] }, key: { type: 'string' }, value: { type: 'string' }, session: { type: 'boolean' }, tabId: { type: 'string' } }, ['op']) },
     { name: 'eval', description: 'Evaluate JavaScript in the page (disabled in safe-mode).', inputSchema: obj({ expression: { type: 'string' }, awaitPromise: { type: 'boolean' }, tabId: { type: 'string' } }, ['expression']) },
     { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: obj({ selector: { type: 'string' }, textContains: { type: 'string' }, gone: { type: 'boolean' }, timeoutMs: { type: 'number' }, tabId: { type: 'string' } }) },
     { name: 'extract_links', description: 'Extract anchors from the page or a subtree.', inputSchema: obj({ selector: { type: 'string' }, sameOriginOnly: { type: 'boolean' }, tabId: { type: 'string' } }) },
@@ -112,6 +116,7 @@ exports.TOOL_HANDLERS = {
             tabId: tabId(a),
             button: (0, validators_1.optionalString)(a, 'button'),
             clickCount: (0, validators_1.optionalNumber)(a, 'clickCount', { min: 1, max: 3 }),
+            trusted: (0, validators_1.optionalBoolean)(a, 'trusted'),
         }));
     },
     type: async (a, ctx) => {
@@ -122,8 +127,17 @@ exports.TOOL_HANDLERS = {
             clear: (0, validators_1.optionalBoolean)(a, 'clear'),
             pressEnter: (0, validators_1.optionalBoolean)(a, 'pressEnter'),
             keyEvents: (0, validators_1.optionalBoolean)(a, 'keyEvents'),
+            trusted: (0, validators_1.optionalBoolean)(a, 'trusted'),
         }));
     },
+    select_option: async (a, ctx) => {
+        const t = (0, validators_1.requireTarget)(a);
+        await gate(ctx, 'type'); // mutating
+        const values = (0, validators_1.optionalStringArray)(a, 'values');
+        if (!values || values.length === 0)
+            throw new validators_1.McpToolError('"values" must be a non-empty array of strings');
+        return (0, envelopes_1.jsonResult)(await ctx.ex.selectOption(t, values, { tabId: tabId(a) }));
+    },
     press: async (a, ctx) => {
         await gate(ctx, 'press');
         return (0, envelopes_1.jsonResult)(await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
@@ -165,6 +179,33 @@ exports.TOOL_HANDLERS = {
         await gate(ctx, 'get_html');
         return (0, envelopes_1.jsonResult)(await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), { tabId: tabId(a), outer: (0, validators_1.optionalBoolean)(a, 'outer') }));
     },
+    snapshot: async (a, ctx) => {
+        await gate(ctx, 'get_text'); // read of page structure
+        return (0, envelopes_1.jsonResult)(await ctx.ex.snapshot({
+            tabId: tabId(a),
+            interactiveOnly: (0, validators_1.optionalBoolean)(a, 'interactiveOnly'),
+            max: (0, validators_1.optionalNumber)(a, 'max', { min: 1, max: 1000 }),
+        }));
+    },
+    get_cookies: async (a, ctx) => {
+        await gate(ctx, 'get_text'); // reads tab-scoped secrets; same domain gate as content reads
+        return (0, envelopes_1.jsonResult)(await ctx.ex.getCookies({ tabId: tabId(a), url: (0, validators_1.optionalString)(a, 'url') }));
+    },
+    storage: async (a, ctx) => {
+        const op = (0, validators_1.requireString)(a, 'op');
+        // get is a read; set/remove/clear mutate.
+        await gate(ctx, op === 'get' ? 'get_text' : 'type');
+        if ((op === 'set' || op === 'remove') && !(0, validators_1.optionalString)(a, 'key')) {
+            throw new validators_1.McpToolError(`storage "${op}" requires a "key"`);
+        }
+        return (0, envelopes_1.jsonResult)(await ctx.ex.storage({
+            op,
+            key: (0, validators_1.optionalString)(a, 'key'),
+            value: (0, validators_1.optionalString)(a, 'value'),
+            session: (0, validators_1.optionalBoolean)(a, 'session'),
+            tabId: tabId(a),
+        }));
+    },
     eval: async (a, ctx) => {
         await gate(ctx, 'eval');
         return (0, envelopes_1.jsonResult)(await ctx.ex.eval((0, validators_1.requireString)(a, 'expression'), {

package/extension-dist/background.js CHANGED Viewed

@@ -19,6 +19,10 @@
     "screenshot",
     "get_text",
     "get_html",
+    "snapshot",
+    "select_option",
+    "get_cookies",
+    "storage",
     "eval",
     "wait_for",
     "download_file",
@@ -161,6 +165,68 @@
     return n;
   }
+  // shared/snapshot.ts
+  function collectSnapshot(interactiveOnly = true, max = 200) {
+    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);
+      return s.visibility !== "hidden" && s.display !== "none";
+    };
+    const accName = (el) => {
+      const aria = el.getAttribute("aria-label");
+      if (aria) return aria.trim();
+      const labelledby = el.getAttribute("aria-labelledby");
+      if (labelledby) {
+        const t = labelledby.split(/\s+/).map((id) => document.getElementById(id)?.innerText ?? "").join(" ").trim();
+        if (t) return t;
+      }
+      const ph = el.getAttribute("placeholder");
+      if (ph) return ph.trim();
+      const title = el.getAttribute("title");
+      if (title) return title.trim();
+      const text = el.innerText ?? "";
+      if (text) return text.replace(/\s+/g, " ").trim().slice(0, 120);
+      const alt = el.querySelector("img[alt]")?.getAttribute("alt");
+      return (alt ?? "").trim();
+    };
+    const roleOf = (el) => {
+      const explicit = el.getAttribute("role");
+      if (explicit) return explicit;
+      const tag = el.tagName.toLowerCase();
+      if (tag === "a") return "link";
+      if (tag === "button") return "button";
+      if (tag === "select") return "combobox";
+      if (tag === "textarea") return "textbox";
+      if (tag === "input") {
+        const t = el.type;
+        if (t === "checkbox") return "checkbox";
+        if (t === "radio") return "radio";
+        if (t === "button" || t === "submit") return "button";
+        return "textbox";
+      }
+      return tag;
+    };
+    const els = Array.from(document.querySelectorAll(sel)).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 v = el.value;
+      if (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 { url: location.href, title: document.title, nodes, truncated: els.length > nodes.length };
+  }
   // extension/src/sw/executor.ts
   var CmdError = class extends Error {
     constructor(code, message) {
@@ -210,9 +276,73 @@
       await delay(100);
     }
   }
-  function selectorOf(cmd) {
+  function resolveSelector(cmd) {
     const s = cmd.params.selector;
-    return typeof s === "string" ? s : void 0;
+    if (typeof s === "string" && s.length > 0) return s;
+    const ref = cmd.params.ref;
+    if (typeof ref === "string" && ref.length > 0) return `[data-mcp-ref="${ref.replace(/["\\]/g, "\\$&")}"]`;
+    return void 0;
+  }
+  function selectorOf(cmd) {
+    return resolveSelector(cmd);
+  }
+  async function waitForSelector(tabId, selector, timeoutMs = 5e3) {
+    const start = Date.now();
+    for (; ; ) {
+      const present = await execInTab(tabId, (s) => !!document.querySelector(s), [selector]);
+      if (present) return true;
+      if (Date.now() - start > timeoutMs) return false;
+      await delay(120);
+    }
+  }
+  async function withDebugger(tabId, fn) {
+    const target = { tabId };
+    await chrome.debugger.attach(target, "1.3");
+    try {
+      return await fn(target);
+    } finally {
+      await chrome.debugger.detach(target).catch(() => void 0);
+    }
+  }
+  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;
+    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;
+    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;
   }
   async function tabInfo(tab, index = 0) {
     return {
@@ -240,6 +370,10 @@
     "screenshot",
     "get_text",
     "get_html",
+    "snapshot",
+    "select_option",
+    "get_cookies",
+    "storage",
     "eval",
     "wait_for",
     "download_file",
@@ -325,42 +459,155 @@
           );
           return { html: html ?? "" };
         }
+        // -- 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 raw = await execInTab(
+            id,
+            collectSnapshot,
+            [interactiveOnly, max]
+          );
+          return raw ?? { url: "", title: "", nodes: [], truncated: false };
+        }
+        // -- <select> option(s) by value or visible label --
+        case "select_option": {
+          const id = await targetTab(cmd);
+          const sel = requireSelector(cmd);
+          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 };
+        }
+        // -- cookies for the tab's URL (chrome.cookies; needs "cookies" permission) --
+        case "get_cookies": {
+          const id = await targetTab(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");
+          const cookies = await chrome.cookies.getAll({ url });
+          return {
+            cookies: cookies.map((c) => ({
+              name: c.name,
+              value: c.value,
+              domain: c.domain,
+              path: c.path,
+              secure: c.secure,
+              httpOnly: c.httpOnly,
+              expires: c.expirationDate
+            }))
+          };
+        }
+        // -- localStorage / sessionStorage (isolated world) --
+        case "storage": {
+          const id = await targetTab(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;
+          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 };
+        }
         // -- 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}`);
+          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 found = await execInTab(
             id,
-            (sel) => {
-              const el = document.querySelector(sel);
+            (s) => {
+              const el = document.querySelector(s);
               if (!el) return false;
               el.scrollIntoView({ block: "center" });
               el.click();
               return true;
             },
-            [requireSelector(cmd)]
+            [sel]
           );
-          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${requireSelector(cmd)}`);
+          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true };
         }
         case "type": {
           const id = await targetTab(cmd);
+          const sel = requireSelector(cmd);
           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 (cmd.params.trusted === true) {
+            if (!await trustedType(id, sel, text, clear)) 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 found = await execInTab(
             id,
-            (sel, value, doClear) => {
-              const el = document.querySelector(sel);
+            (s, value, doClear) => {
+              const el = document.querySelector(s);
               if (!el) return false;
               el.focus();
-              if (doClear) el.value = "";
-              el.value = (el.value ?? "") + value;
+              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;
             },
-            [requireSelector(cmd), text, clear]
+            [sel, text, clear]
           );
-          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${requireSelector(cmd)}`);
+          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true };
         }
         case "press": {
@@ -380,13 +627,16 @@
         }
         case "hover": {
           const id = await targetTab(cmd);
+          const sel = requireSelector(cmd);
+          await waitForSelector(id, sel);
           await execInTab(
             id,
-            (sel) => {
-              const el = document.querySelector(sel);
+            (s) => {
+              const el = document.querySelector(s);
               el?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+              el?.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
             },
-            [requireSelector(cmd)]
+            [sel]
           );
           return { ok: true };
         }
@@ -402,17 +652,33 @@
           );
           return { ok: true };
         }
-        // -- screenshot (visible tab) --
+        // -- screenshot (captureVisibleTab grabs the ACTIVE visible tab, so activate the target first) --
         case "screenshot": {
           const id = await targetTab(cmd);
-          const t = await chrome.tabs.get(id);
+          let t = await chrome.tabs.get(id);
+          if (!t.active) {
+            await chrome.tabs.update(id, { active: true });
+            await chrome.windows.update(t.windowId, { focused: true }).catch(() => void 0);
+            await delay(150);
+            t = await chrome.tabs.get(id);
+          }
+          const dims = await execInTab(
+            id,
+            () => ({ w: window.innerWidth, h: window.innerHeight, full: document.documentElement.scrollHeight }),
+            []
+          );
           const dataUrl = await chrome.tabs.captureVisibleTab(t.windowId, { format: "png" });
+          const fullPage = cmd.params.fullPage === true;
+          const viewportH = dims?.h ?? 0;
+          const fullH = dims?.full ?? viewportH;
           return {
             dataBase64: dataUrl.split(",")[1] ?? "",
             mimeType: "image/png",
-            width: 0,
-            height: 0,
-            truncated: false
+            width: dims?.w ?? 0,
+            height: viewportH,
+            // The scripting backend can only capture the viewport; flag when a fullPage was asked but clipped.
+            truncated: fullPage && fullH > viewportH,
+            fullHeight: fullPage ? fullH : void 0
           };
         }
         // -- eval (MAIN world; may be blocked by strict page CSP) --
@@ -472,11 +738,11 @@
     }
   };
   function requireSelector(cmd) {
-    const s = cmd.params.selector;
-    if (typeof s !== "string" || s.length === 0) {
-      throw new CmdError("BAD_ARGS", "this command needs a CSS selector (the scripting backend does not support refs)");
+    const sel = resolveSelector(cmd);
+    if (!sel) {
+      throw new CmdError("BAD_ARGS", 'this command needs a "selector" or a "ref" from snapshot()');
     }
-    return s;
+    return sel;
   }
   // extension/src/sw/router.ts
@@ -523,12 +789,28 @@
   });
   async function getConfig() {
     const { wsPort, token } = await chrome.storage.local.get(["wsPort", "token"]);
-    if (typeof wsPort === "number" && typeof token === "string" && token.length > 0) {
+    if (typeof wsPort === "number" && wsPort > 0 && typeof token === "string" && token.length > 0) {
       return { wsPort, token };
     }
     return null;
   }
+  var BADGE = {
+    connected: { text: "\u25CF", color: "#16a34a", title: "Chrome MCP \u2014 connected" },
+    connecting: { text: "\u2026", color: "#ca8a04", title: "Chrome MCP \u2014 connecting" },
+    unauthorized: { text: "!", color: "#dc2626", title: "Chrome MCP \u2014 rejected (bad/stale token; re-pair)" },
+    idle: { text: "\u25CB", color: "#6b7280", title: "Chrome MCP \u2014 not connected (open options to pair)" }
+  };
+  function reflectBadge(state) {
+    const b = BADGE[state] ?? BADGE.idle;
+    try {
+      void chrome.action.setBadgeText({ text: b.text });
+      void chrome.action.setBadgeBackgroundColor({ color: b.color });
+      void chrome.action.setTitle({ title: b.title });
+    } catch {
+    }
+  }
   async function persistState(state) {
+    reflectBadge(state);
     await chrome.storage.local.set({ connState: state });
   }
   async function ensureConnected() {