@mehmoodqureshi/chrome-mcp 0.1.0 → 0.3.0

package/README.md

@@ -34,6 +34,30 @@ By default everything is **deny-all** (no domains, no eval, no mutations). Grant
 exactly what you need with `--allow-domain <glob>` (repeatable), `--enable-mutations`,
 `--enable-downloads`, `--unsafe-enable-eval`, or `--unsafe-all-domains`.
 
+**Drive only your real Chrome (recommended for the extension).** Add
+`--no-cdp-fallback` so the server never launches a separate Chromium, and
+`--persist-token` so the pairing token survives restarts — **pair once, never
+again**:
+
+```jsonc
+{
+  "mcpServers": {
+    "chrome-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mehmoodqureshi/chrome-mcp",
+               "--allow-domain", "example.com", "--enable-mutations",
+               "--no-cdp-fallback", "--persist-token"]
+    }
+  }
+}
+```
+
+Without `--persist-token` a fresh token is minted every boot (the secure
+default), which means re-pairing the extension on each restart. With it, the
+token is stored 0600 at `~/.chrome-mcp/token` and reused; the extension's
+keepalive auto-reconnects with no manual step. `CHROME_MCP_TOKEN` pins the token
+explicitly (and is never written to disk).
+
 **2. Load the extension** (to drive your *real* Chrome): build it, then
 `chrome://extensions` → enable Developer mode → **Load unpacked** → select
 `extension-dist/`.
@@ -43,15 +67,24 @@ print its path, open the extension's **Options** page, and paste the `port` +
 `token` from `~/.chrome-mcp/handshake.json`. (Without the extension, the CLI
 falls back to a Playwright-driven Chromium automatically.)
 
-The 26 tools cover tabs, navigation, interaction (`click`/`type`/`press`/`hover`/
-`scroll`), reads (`get_text`/`get_html`/`screenshot`/`eval`/`wait_for`), helpers
-(`extract_links`/`read_as_markdown`/`fill_form`/`download_file`), and `chrome_status`.
+The tools cover tabs, navigation, interaction (`click`/`type`/`press`/`hover`/
+`scroll`/`select_option`), reads (`get_text`/`get_html`/`screenshot`/`eval`/`wait_for`),
+an accessibility `snapshot` (interactive elements with stable `ref`s the model can
+target instead of guessing CSS selectors), session access (`get_cookies`/`storage`),
+helpers (`extract_links`/`read_as_markdown`/`fill_form`/`download_file`), and
+`chrome_status`.
+
+`click`/`type` accept `trusted: true` for real OS-level input (works on
+React/Vue controlled inputs); interactions auto-wait for the target to appear.
 
 ## Status
 
-v0.1.0 — all six build phases complete and green (50 automated tests + a gated
+v0.2.0 — all six build phases complete and green (57 automated tests + a gated
 headed extension smoke). End-to-end working: `npx chrome-mcp` ⇄ bridge ⇄
-extension ⇄ your real Chrome, with a Playwright CDP fallback.
+extension ⇄ your real Chrome, with a Playwright CDP fallback. v0.2 adds the
+accessibility `snapshot` + element refs, auto-wait, cookies/storage/`select_option`,
+trusted input (`chrome.debugger`), a toolbar status badge, and a stable pairing
+token (`--persist-token`).
 
 - [x] **Phase 0 — Contracts & skeleton:** `shared/protocol.ts` (wire contract),
       `src/executor/types.ts` (Executor interface), `src/security/policy.ts`

package/dist/shared/protocol.d.ts

@@ -32,7 +32,7 @@ export declare const CLOSE_SUPERSEDED: 4000;
  * `download_file` (privileged, executor-owned) and `ping_probe` (a short-deadline
  * responsiveness check used to detect a dead-but-not-yet-reconnected worker).
  */
-export type WireMethod = 'tabs_list' | 'tab_select' | 'tab_new' | 'tab_close' | 'navigate' | 'back' | 'forward' | 'reload' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'screenshot' | 'get_text' | 'get_html' | 'eval' | 'wait_for' | 'download_file' | 'ping_probe';
+export type WireMethod = 'tabs_list' | 'tab_select' | 'tab_new' | 'tab_close' | 'navigate' | 'back' | 'forward' | 'reload' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'screenshot' | 'get_text' | 'get_html' | 'snapshot' | 'select_option' | 'get_cookies' | 'storage' | 'eval' | 'wait_for' | 'download_file' | 'ping_probe';
 /** Runtime list of every WireMethod, for boot-time drift assertions on both ends. */
 export declare const WIRE_METHODS: readonly WireMethod[];
 export type ExecutorErrorCode = 'NO_TARGET' | 'TARGET_GONE' | 'DETACHED' | 'DEVTOOLS_OPEN' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_THREW' | 'TIMEOUT' | 'BAD_ARGS' | 'CDP_ERROR' | 'POLICY_DENIED' | 'DOWNLOAD_FAILED' | 'UNKNOWN_METHOD';

package/dist/shared/protocol.js

@@ -47,6 +47,10 @@ exports.WIRE_METHODS = [
     'screenshot',
     'get_text',
     'get_html',
+    'snapshot',
+    'select_option',
+    'get_cookies',
+    'storage',
     'eval',
     'wait_for',
     'download_file',

package/dist/shared/snapshot.d.ts

@@ -0,0 +1,26 @@
+/**
+ * shared/snapshot.ts — the page-injected accessibility walk, shared VERBATIM by
+ * both backends (CDP `page.evaluate` and the extension's `chrome.scripting`).
+ *
+ * MUST be self-contained: it is serialized to source and runs in the PAGE
+ * context, so it may not close over anything from this module. It tags each
+ * returned element with a stable `data-mcp-ref` so a later click/type can target
+ * it by `ref` (resolved to `[data-mcp-ref="..."]`). Refs live until navigation.
+ */
+export interface RawSnapshotNode {
+    ref: string;
+    role: string;
+    name: string;
+    tag: string;
+    value?: string;
+    disabled?: boolean;
+    checked?: boolean;
+}
+export interface RawSnapshot {
+    url: string;
+    title: string;
+    nodes: RawSnapshotNode[];
+    truncated: boolean;
+}
+/** Runs IN THE PAGE. Returns interactive (and optionally landmark) elements with fresh refs. */
+export declare function collectSnapshot(interactiveOnly?: boolean, max?: number): RawSnapshot;

package/dist/shared/snapshot.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * shared/snapshot.ts — the page-injected accessibility walk, shared VERBATIM by
+ * both backends (CDP `page.evaluate` and the extension's `chrome.scripting`).
+ *
+ * MUST be self-contained: it is serialized to source and runs in the PAGE
+ * context, so it may not close over anything from this module. It tags each
+ * returned element with a stable `data-mcp-ref` so a later click/type can target
+ * it by `ref` (resolved to `[data-mcp-ref="..."]`). Refs live until navigation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSnapshot = collectSnapshot;
+/** Runs IN THE PAGE. Returns interactive (and optionally landmark) elements with fresh refs. */
+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 };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/src/bridge/auth.d.ts

@@ -2,7 +2,9 @@
  * src/bridge/auth.ts — the ONE auth model (every other variant in the design
  * drafts was deleted on purpose).
  *
- *   - Fresh 256-bit token EVERY boot, never persisted across restarts.
+ *   - Fresh 256-bit token EVERY boot by default, never persisted across restarts.
+ *     Persistence is OPT-IN (`--persist-token` / `CHROME_MCP_TOKEN`) for hosts
+ *     that want a stable token so the extension never has to re-pair.
  *   - Written atomically (tmp + rename) to `handshake.json` at mode 0600; the
  *     mode is re-verified after write and we FAIL CLOSED if it can't be set.
  *   - Compared by hashing both sides to SHA-256 and `timingSafeEqual`-ing the
@@ -12,6 +14,26 @@
 import { type HandshakeFile } from '../../shared/protocol';
 /** A fresh 256-bit token, base64url. Generated once per server boot. */
 export declare function generateToken(): string;
+/** Path of the optional persisted-token file (only used when persistence is on). */
+export declare function tokenPath(dir: string): string;
+/**
+ * Read the persisted token (trimmed) if present and non-empty; else null.
+ * FAILS CLOSED if the file is group/other-readable — same trust boundary as the
+ * handshake, so a loose permission is a hard error rather than a silent reuse.
+ */
+export declare function readPersistedToken(dir: string): string | null;
+/** Atomically write the persisted token at 0600 and verify the mode (fail closed). */
+export declare function writePersistedToken(dir: string, token: string): string;
+/**
+ * Resolve the token for this boot:
+ *   1. `CHROME_MCP_TOKEN` env — an explicit pin; used verbatim, never written to disk.
+ *   2. `persist` on — reuse the on-disk token (creating + saving one on first run),
+ *      so the extension stays paired across restarts.
+ *   3. otherwise — a fresh per-boot token (the secure default; never persisted).
+ */
+export declare function resolveToken(dir: string, opts: {
+    persist: boolean;
+}): string;
 /** Constant-time token compare via fixed-length SHA-256 digests. */
 export declare function tokensMatch(a: string, b: string): boolean;
 export interface WriteHandshakeFields {

package/dist/src/bridge/auth.js

@@ -3,7 +3,9 @@
  * src/bridge/auth.ts — the ONE auth model (every other variant in the design
  * drafts was deleted on purpose).
  *
- *   - Fresh 256-bit token EVERY boot, never persisted across restarts.
+ *   - Fresh 256-bit token EVERY boot by default, never persisted across restarts.
+ *     Persistence is OPT-IN (`--persist-token` / `CHROME_MCP_TOKEN`) for hosts
+ *     that want a stable token so the extension never has to re-pair.
  *   - Written atomically (tmp + rename) to `handshake.json` at mode 0600; the
  *     mode is re-verified after write and we FAIL CLOSED if it can't be set.
  *   - Compared by hashing both sides to SHA-256 and `timingSafeEqual`-ing the
@@ -12,12 +14,17 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateToken = generateToken;
+exports.tokenPath = tokenPath;
+exports.readPersistedToken = readPersistedToken;
+exports.writePersistedToken = writePersistedToken;
+exports.resolveToken = resolveToken;
 exports.tokensMatch = tokensMatch;
 exports.writeHandshake = writeHandshake;
 exports.readHandshake = readHandshake;
 exports.removeHandshake = removeHandshake;
 exports.redactToken = redactToken;
 const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const node_crypto_1 = require("node:crypto");
 const protocol_1 = require("../../shared/protocol");
 const datadir_1 = require("./datadir");
@@ -25,6 +32,66 @@ const datadir_1 = require("./datadir");
 function generateToken() {
     return (0, node_crypto_1.randomBytes)(32).toString('base64url');
 }
+/** Path of the optional persisted-token file (only used when persistence is on). */
+function tokenPath(dir) {
+    return (0, node_path_1.join)(dir, 'token');
+}
+/**
+ * Read the persisted token (trimmed) if present and non-empty; else null.
+ * FAILS CLOSED if the file is group/other-readable — same trust boundary as the
+ * handshake, so a loose permission is a hard error rather than a silent reuse.
+ */
+function readPersistedToken(dir) {
+    const path = tokenPath(dir);
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new Error(`persisted token ${path} is group/other-accessible (mode ${mode.toString(8)}); refusing to reuse it`);
+    }
+    const token = raw.trim();
+    return token.length > 0 ? token : null;
+}
+/** Atomically write the persisted token at 0600 and verify the mode (fail closed). */
+function writePersistedToken(dir, token) {
+    const path = tokenPath(dir);
+    const tmp = `${path}.tmp.${process.pid}`;
+    (0, node_fs_1.writeFileSync)(tmp, token, { mode: 0o600 });
+    (0, node_fs_1.chmodSync)(tmp, 0o600);
+    (0, node_fs_1.renameSync)(tmp, path);
+    (0, node_fs_1.chmodSync)(path, 0o600);
+    const mode = (0, node_fs_1.statSync)(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+        throw new Error(`persisted token ${path} is group/other-accessible (mode ${mode.toString(8)}); refusing to expose it`);
+    }
+    return path;
+}
+/**
+ * Resolve the token for this boot:
+ *   1. `CHROME_MCP_TOKEN` env — an explicit pin; used verbatim, never written to disk.
+ *   2. `persist` on — reuse the on-disk token (creating + saving one on first run),
+ *      so the extension stays paired across restarts.
+ *   3. otherwise — a fresh per-boot token (the secure default; never persisted).
+ */
+function resolveToken(dir, opts) {
+    const fromEnv = process.env.CHROME_MCP_TOKEN?.trim();
+    if (fromEnv)
+        return fromEnv;
+    if (opts.persist) {
+        const existing = readPersistedToken(dir);
+        if (existing)
+            return existing;
+        const fresh = generateToken();
+        writePersistedToken(dir, fresh);
+        return fresh;
+    }
+    return generateToken();
+}
 /** Constant-time token compare via fixed-length SHA-256 digests. */
 function tokensMatch(a, b) {
     const ha = (0, node_crypto_1.createHash)('sha256').update(a, 'utf8').digest();

package/dist/src/cli.js

@@ -39,7 +39,7 @@ async function main() {
         return;
     }
     const dataDir = (0, datadir_1.ensureDataDir)(cfg.dataDir);
-    const token = (0, auth_1.generateToken)();
+    const token = (0, auth_1.resolveToken)(dataDir, { persist: cfg.persistToken });
     const bridge = new server_1.BridgeServer({
         token,
         serverVersion: version(),
@@ -50,6 +50,12 @@ async function main() {
     const port = await bridge.start();
     const handshakePath = (0, auth_1.writeHandshake)(dataDir, { port, token });
     (0, server_2.logErr)(`pairing handshake written to ${handshakePath} (mode 0600; token not logged)`);
+    if (process.env.CHROME_MCP_TOKEN) {
+        (0, server_2.logErr)('token: pinned from CHROME_MCP_TOKEN (stable; pair once, never again).');
+    }
+    else if (cfg.persistToken) {
+        (0, server_2.logErr)('token: persisted across restarts (--persist-token; pair once, never again).');
+    }
     const cleanup = () => {
         (0, auth_1.removeHandshake)(dataDir);
     };

package/dist/src/config.d.ts

@@ -26,6 +26,8 @@ export interface CliConfig {
     headless: boolean;
     /** `--print-pairing`: write the handshake and print its path (never the token). */
     printPairing: boolean;
+    /** `--persist-token`: reuse a stable on-disk token so the extension never re-pairs. */
+    persistToken: boolean;
     showHelp: boolean;
     showVersion: boolean;
     logLevel: LogLevel;

package/dist/src/config.js

@@ -35,11 +35,14 @@ function readPolicyFile(path) {
  */
 function parseArgs(argv) {
     let wsPort = envInt('CHROME_MCP_WS_PORT') ?? protocol_1.DEFAULT_WS_PORT;
-    let cdpFallback = true;
+    // Extension-only by default: never launch/attach a Chromium of our own unless
+    // the operator explicitly opts in with --cdp-fallback (or --prefer cdp / --cdp-endpoint).
+    let cdpFallback = false;
     let cdpEndpoint;
     let prefer = 'extension';
     let headless = false;
     let printPairing = false;
+    let persistToken = false;
     let showHelp = false;
     let showVersion = false;
     let logLevel = 'info';
@@ -84,7 +87,10 @@ function parseArgs(argv) {
             case '--allow-all-tabs':
                 policyFlags.allowAllTabs = true;
                 break;
-            case '--no-cdp-fallback':
+            case '--cdp-fallback':
+                cdpFallback = true;
+                break;
+            case '--no-cdp-fallback': // still accepted; fallback is already off by default
                 cdpFallback = false;
                 break;
             case '--cdp-endpoint':
@@ -99,6 +105,9 @@ function parseArgs(argv) {
             case '--print-pairing':
                 printPairing = true;
                 break;
+            case '--persist-token':
+                persistToken = true;
+                break;
             case '--log-level':
                 logLevel = requireLogLevel(argv[++i]);
                 break;
@@ -117,6 +126,7 @@ function parseArgs(argv) {
         prefer,
         headless,
         printPairing,
+        persistToken,
         showHelp,
         showVersion,
         logLevel,
@@ -164,9 +174,15 @@ Connection:
   --port <n>             WebSocket bridge port (default ${protocol_1.DEFAULT_WS_PORT}; 0 = ephemeral)
   --data-dir <path>      Override the data dir (default ~/.chrome-mcp)
   --print-pairing        Write the handshake and print its path, then exit
+  --persist-token        Reuse a stable on-disk token across restarts so the
+                         extension never has to re-pair (default: fresh per boot).
+                         CHROME_MCP_TOKEN env, if set, pins the token explicitly.
 
 Backend:
-  --no-cdp-fallback      Do not launch/attach Chromium when no extension is paired
+  --cdp-fallback         Opt in to launching/attaching Chromium when no extension
+                         is paired. OFF by default — extension-only, never opens
+                         a browser of its own.
+  --no-cdp-fallback      Explicitly disable the fallback (already the default).
   --cdp-endpoint <url>   Attach to an existing Chrome (e.g. http://127.0.0.1:9222)
   --prefer <which>       "extension" (default) or "cdp"
   --headless             Run the CDP-fallback Chromium headless

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

@@ -12,7 +12,7 @@
  * stealth init on the launch path only, and tab resolution. `tabId`s are stamped
  * `cdp:<sessionId>:<n>` so a handle never mis-routes across a backend switch.
  */
-import { type ActionOk, type BackendKind, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type KeyModifier, type NavResult, type ScreenshotResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
+import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type KeyModifier, type NavResult, type ScreenshotResult, type SnapshotResult, type StorageOp, type StorageResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
 export interface CdpOptions {
     mode: 'connect' | 'launch';
     cdpEndpoint?: string;
@@ -69,12 +69,17 @@ export declare class CdpExecutor implements Executor {
         tabId?: TabId;
         button?: 'left' | 'right' | 'middle';
         clickCount?: number;
+        trusted?: boolean;
     }): Promise<ActionOk>;
     type(t: Target, text: string, opts?: {
         tabId?: TabId;
         clear?: boolean;
         pressEnter?: boolean;
         keyEvents?: boolean;
+        trusted?: boolean;
+    }): Promise<ActionOk>;
+    selectOption(t: Target, values: string[], opts?: {
+        tabId?: TabId;
     }): Promise<ActionOk>;
     fill(t: Target, value: string, opts?: {
         tabId?: TabId;
@@ -106,6 +111,24 @@ export declare class CdpExecutor implements Executor {
     }): Promise<{
         html: string;
     }>;
+    snapshot(opts?: {
+        tabId?: TabId;
+        interactiveOnly?: boolean;
+        max?: number;
+    }): Promise<SnapshotResult>;
+    getCookies(opts?: {
+        tabId?: TabId;
+        url?: string;
+    }): Promise<{
+        cookies: CookieItem[];
+    }>;
+    storage(args: {
+        op: StorageOp;
+        key?: string;
+        value?: string;
+        session?: boolean;
+        tabId?: TabId;
+    }): Promise<StorageResult>;
     screenshot(opts?: {
         tabId?: TabId;
         fullPage?: boolean;

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

@@ -21,10 +21,15 @@ const node_path_1 = require("node:path");
 const node_crypto_1 = require("node:crypto");
 const playwright_1 = require("playwright");
 const download_1 = require("../../shared/download");
+const snapshot_1 = require("../../shared/snapshot");
 const types_1 = require("./types");
 const SINGLETON_FILES = ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
 const STEALTH = `Object.defineProperty(navigator,'webdriver',{get:()=>undefined});`;
 const NON_CONTENT = /^(file|data|devtools|chrome|about):/i;
+/** Minimal CSS attribute-value escape for ref selectors (refs are `e\d+`, but be safe). */
+function cssEscape(s) {
+    return s.replace(/["\\]/g, '\\$&');
+}
 // --- lock recovery helpers (ported) ---------------------------------------
 function inspectProfileLock(profileDir) {
     try {
@@ -239,7 +244,11 @@ class CdpExecutor {
     locator(page, t) {
         if ('selector' in t && t.selector !== undefined)
             return page.locator(t.selector).first();
-        throw new types_1.ExecutorError('SELECTOR_NOT_FOUND', 'the CDP fallback supports selectors, not refs (use the extension backend)');
+        if ('ref' in t && t.ref !== undefined) {
+            // Refs are minted by snapshot() as data-mcp-ref attributes on the page.
+            return page.locator(`[data-mcp-ref="${cssEscape(t.ref)}"]`).first();
+        }
+        throw new types_1.ExecutorError('SELECTOR_NOT_FOUND', 'provide a selector or a ref from snapshot()');
     }
     // -- tabs ---------------------------------------------------------------
     async tabsList() {
@@ -298,6 +307,7 @@ class CdpExecutor {
     ok = { ok: true };
     async click(t, opts) {
         const p = await this.resolveTab(opts?.tabId);
+        // Playwright already drives real (trusted) input, so `trusted` is a no-op here.
         await this.locator(p, t).click({ button: opts?.button, clickCount: opts?.clickCount });
         return this.ok;
     }
@@ -314,6 +324,18 @@ class CdpExecutor {
             await loc.press('Enter');
         return this.ok;
     }
+    async selectOption(t, values, opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        // Try by value, then fall back to visible label.
+        const loc = this.locator(p, t);
+        try {
+            await loc.selectOption(values);
+        }
+        catch {
+            await loc.selectOption(values.map((label) => ({ label })));
+        }
+        return this.ok;
+    }
     async fill(t, value, opts) {
         const p = await this.resolveTab(opts?.tabId);
         await this.locator(p, t).fill(value);
@@ -354,6 +376,55 @@ class CdpExecutor {
         const html = opts?.outer ? await loc.evaluate((el) => el.outerHTML) : await loc.innerHTML();
         return { html };
     }
+    async snapshot(opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        // Inject collectSnapshot's source and run it in the page (it can't close over module scope).
+        const raw = await p.evaluate(([fnSrc, interactiveOnly, max]) => {
+            // eslint-disable-next-line no-eval
+            const fn = (0, eval)(`(${fnSrc})`);
+            return fn(interactiveOnly, max);
+        }, [snapshot_1.collectSnapshot.toString(), opts?.interactiveOnly ?? true, opts?.max ?? 200]);
+        return raw;
+    }
+    async getCookies(opts) {
+        const p = await this.resolveTab(opts?.tabId);
+        const url = opts?.url ?? p.url();
+        const ctx = await this.getContext();
+        const raw = await ctx.cookies(url);
+        return {
+            cookies: raw.map((c) => ({
+                name: c.name, value: c.value, domain: c.domain, path: c.path,
+                secure: c.secure, httpOnly: c.httpOnly, expires: c.expires >= 0 ? c.expires : undefined,
+            })),
+        };
+    }
+    async storage(args) {
+        const p = await this.resolveTab(args.tabId);
+        return p.evaluate((a) => {
+            const store = a.session ? window.sessionStorage : window.localStorage;
+            if (a.op === 'set') {
+                store.setItem(String(a.key), String(a.value ?? ''));
+                return { ok: true };
+            }
+            if (a.op === 'remove') {
+                store.removeItem(String(a.key));
+                return { ok: true };
+            }
+            if (a.op === 'clear') {
+                store.clear();
+                return { ok: true };
+            }
+            if (a.key)
+                return { 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 { ok: true, entries };
+        }, args);
+    }
     async screenshot(opts) {
         const p = await this.resolveTab(opts?.tabId);
         const buf = opts?.target

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

@@ -7,7 +7,7 @@
  * method-specific arguments travel in `params`. Results are trusted shapes
  * produced by the extension router (validated there).
  */
-import { type ActionOk, type BackendKind, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type KeyModifier, type MouseButton, type NavResult, type ScreenshotResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
+import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type KeyModifier, type MouseButton, type NavResult, type ScreenshotResult, type SnapshotResult, type StorageOp, type StorageResult, type TabId, type TabInfo, type Target, type WaitResult, type WaitUntil } from './types';
 import type { BridgeServer } from '../bridge/server';
 export declare class ExtensionExecutor implements Executor {
     private readonly bridge;
@@ -40,12 +40,17 @@ export declare class ExtensionExecutor implements 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>;
+    selectOption(t: Target, values: string[], opts?: {
+        tabId?: TabId;
     }): Promise<ActionOk>;
     fill(t: Target, value: string, opts?: {
         tabId?: TabId;
@@ -77,6 +82,24 @@ export declare class ExtensionExecutor implements Executor {
     }): Promise<{
         html: string;
     }>;
+    snapshot(opts?: {
+        tabId?: TabId;
+        interactiveOnly?: boolean;
+        max?: number;
+    }): Promise<SnapshotResult>;
+    getCookies(opts?: {
+        tabId?: TabId;
+        url?: string;
+    }): Promise<{
+        cookies: CookieItem[];
+    }>;
+    storage(args: {
+        op: StorageOp;
+        key?: string;
+        value?: string;
+        session?: boolean;
+        tabId?: TabId;
+    }): Promise<StorageResult>;
     screenshot(opts?: {
         tabId?: TabId;
         fullPage?: boolean;