@mehmoodqureshi/chrome-mcp 0.9.2 → 0.9.4

package/dist/shared/snapshot.js

@@ -10,30 +10,47 @@
  */
 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) {
+/**
+ * Runs IN THE PAGE. Returns interactive (and optionally landmark) elements with
+ * fresh refs.
+ *
+ * With a `locator`, the walk is the same but the SCORING happens here: only the
+ * strongest-tier matches come back (and only they get a ref), so resolving
+ * "the Sign in button" ships a handful of nodes instead of the whole tree and
+ * touches one or two DOM attributes instead of hundreds. The tiers mirror
+ * `src/mcp/locate.ts` exactly (exact, case-insensitive, prefix, contains), and
+ * the server re-scores what it receives, so both ends always agree.
+ *
+ * Reads (visibility, names, values) all happen BEFORE the ref attributes are
+ * written: interleaving them made every `innerText` after a `setAttribute`
+ * re-run style, which on a big page is most of the snapshot's cost.
+ */
+function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
     const INTERACTIVE = 'a[href],button,input,select,textarea,[role=button],[role=link],[role=tab],[role=checkbox],[role=radio],[role=menuitem],[role=option],[role=switch],[contenteditable=true],[onclick]';
     const LANDMARK = 'h1,h2,h3,[role=heading],nav,main,header,footer,[role=navigation]';
     const sel = interactiveOnly ? INTERACTIVE : `${INTERACTIVE},${LANDMARK}`;
     const visible = (el) => {
-        const r = el.getBoundingClientRect();
-        if (r.width === 0 && r.height === 0)
-            return false;
-        const s = window.getComputedStyle(el);
-        if (s.visibility === 'hidden' || s.display === 'none')
-            return false;
-        // Prefer the native check (accounts for ancestors, content-visibility, etc.).
-        const cv = el.checkVisibility;
-        if (typeof cv === 'function') {
+        const h = el;
+        // The native check covers display:none / visibility:hidden on the element
+        // AND its ancestors plus content-visibility, in one call and without a
+        // getComputedStyle. Only a zero-size box needs the (cheap) rect on top.
+        if (typeof h.checkVisibility === 'function') {
             try {
-                return cv.call(el, { checkOpacity: false, checkVisibilityCSS: true });
+                if (!h.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true }))
+                    return false;
+                const r = h.getBoundingClientRect();
+                return r.width !== 0 || r.height !== 0;
             }
             catch {
-                /* fall through to manual ancestor walk */
+                /* fall through to the manual walk */
             }
         }
-        // Fallback: walk ancestors for display:none / visibility:hidden. An element
-        // with no offsetParent (and not position:fixed) is detached/hidden.
+        const r = h.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0)
+            return false;
+        const s = window.getComputedStyle(h);
+        if (s.visibility === 'hidden' || s.display === 'none')
+            return false;
         let p = el.parentElement;
         while (p) {
             const ps = window.getComputedStyle(p);
@@ -41,7 +58,7 @@ function collectSnapshot(interactiveOnly = true, max = 200) {
                 return false;
             p = p.parentElement;
         }
-        if (el.offsetParent === null && s.position !== 'fixed')
+        if (h.offsetParent === null && s.position !== 'fixed')
             return false;
         return true;
     };
@@ -101,45 +118,40 @@ function collectSnapshot(interactiveOnly = true, max = 200) {
             return;
         let matched;
         try {
-            matched = Array.from(root.querySelectorAll(sel));
+            matched = root.querySelectorAll(sel);
         }
         catch {
             matched = [];
         }
-        for (const el of matched) {
+        for (let i = 0; i < matched.length; i++) {
             if (candidates.length >= max)
                 break;
+            const el = matched[i];
             if (seen.has(el))
                 continue;
             seen.add(el);
             candidates.push(el);
         }
-        // Descend into any open shadow roots hosted under this root.
+        // Descend into any open shadow roots hosted under this root. A plain index
+        // loop over the live NodeList: no Array.from copy of every element on the page.
         let hosts;
         try {
-            hosts = Array.from(root.querySelectorAll('*'));
+            hosts = root.querySelectorAll('*');
         }
         catch {
             hosts = [];
         }
-        for (const host of hosts) {
+        for (let i = 0; i < hosts.length; i++) {
             if (candidates.length >= max)
                 break;
-            const sr = host.shadowRoot;
+            const sr = hosts[i].shadowRoot;
             if (sr)
                 collect(sr);
         }
     };
     collect(document);
-    const els = candidates.filter(visible);
-    const nodes = [];
-    let n = 0;
-    for (const el of els) {
-        if (nodes.length >= max)
-            break;
-        const ref = `e${++n}`;
-        el.setAttribute('data-mcp-ref', ref);
-        const node = { ref, role: roleOf(el), name: accName(el), tag: el.tagName.toLowerCase() };
+    const read = (el) => {
+        const node = { role: roleOf(el), name: accName(el), tag: el.tagName.toLowerCase() };
         // A password field's characters never leave the page. The node still
         // appears (so the model can target it) and is flagged `secret`, but the
         // value is not something a caller has a use for and every caller would
@@ -154,8 +166,80 @@ function collectSnapshot(interactiveOnly = true, max = 200) {
             node.disabled = true;
         if (el.checked)
             node.checked = true;
-        nodes.push(node);
+        return { el, node };
+    };
+    const els = candidates.filter(visible);
+    let picked;
+    let truncated = false;
+    let nearby;
+    let refPrefix = 'e';
+    if (locator && (locator.role !== undefined || locator.name !== undefined)) {
+        // Locator mode: score every visible candidate, keep the strongest tier.
+        const norm = (x) => x.replace(/\s+/g, ' ').trim().toLowerCase();
+        const wantRole = locator.role !== undefined ? norm(locator.role) : null;
+        const wantName = locator.name;
+        const score = (role, name) => {
+            if (wantRole !== null && norm(role) !== wantRole)
+                return 0;
+            if (!wantName)
+                return 1;
+            const have = norm(name);
+            const need = norm(wantName);
+            if (!have)
+                return 0;
+            if (name.trim() === wantName.trim())
+                return 4;
+            if (have === need)
+                return 3;
+            if (have.startsWith(need))
+                return 2;
+            if (have.includes(need))
+                return 1;
+            return 0;
+        };
+        let best = 0;
+        picked = [];
+        const sameRole = [];
+        for (const el of els) {
+            const s = read(el);
+            const sc = score(s.node.role, s.node.name);
+            if (sc === 0) {
+                if ((wantRole === null || norm(s.node.role) === wantRole) && sameRole.length < 8) {
+                    sameRole.push(`${s.node.role} "${s.node.name}"`);
+                }
+                continue;
+            }
+            if (sc > best) {
+                best = sc;
+                picked = [s];
+            }
+            else if (sc === best) {
+                picked.push(s);
+            }
+        }
+        if (picked.length === 0)
+            nearby = sameRole;
+        // Refs from a locate must not collide with a prior snapshot's e1..eN, which
+        // may still be stamped on OTHER elements: use a distinct, per-call prefix.
+        refPrefix = `l${Date.now().toString(36).slice(-4)}-`;
+    }
+    else {
+        picked = [];
+        for (const el of els) {
+            if (picked.length >= max)
+                break;
+            picked.push(read(el));
+        }
+        truncated = els.length > picked.length;
+    }
+    // -- phase 2: writes (one attribute per returned node) ----------------------
+    const nodes = [];
+    let n = 0;
+    for (const { el, node } of picked) {
+        const ref = `${refPrefix}${++n}`;
+        el.setAttribute('data-mcp-ref', ref);
+        nodes.push({ ref, ...node });
     }
-    return { url: location.href, title: document.title, nodes, truncated: els.length > nodes.length };
+    return { url: location.href, title: document.title, nodes, truncated, ...(nearby ? { nearby } : {}) };
 }
 //# sourceMappingURL=snapshot.js.map

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

@@ -36,6 +36,10 @@ export declare class ExtensionConnection {
     private readonly reportsTabUrl;
     /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
     private activeUrl;
+    /** Last URL each explicitly-targeted tab reported, keyed by wire tab id. A
+     *  `tabs_list` result fills this for EVERY tab at once, which is what lets a
+     *  parallel batch over N tabs gate on one round-trip instead of N. */
+    private readonly tabUrls;
     private readonly onEvent?;
     private readonly onClose?;
     private readonly onLog?;
@@ -49,6 +53,15 @@ export declare class ExtensionConnection {
     isOpen(): boolean;
     private handleMessage;
     private settle;
+    /**
+     * Per-tab cache. Two feeds: a result for an explicitly-targeted tab carries
+     * that tab's landing URL; a `tabs_list` result carries every tab's URL, so one
+     * listing primes the gate for every op of a batch that follows it. A closed
+     * tab is forgotten; a blank URL (Chrome hiding it) is forgotten too, never kept.
+     */
+    private rememberTabUrls;
+    /** A specific tab's last reported URL if younger than `maxAgeMs`, else null. */
+    lastTabUrl(tabId: string, maxAgeMs: number): string | null;
     /**
      * Cache the URL a result rode home with — but ONLY when it describes the active
      * tab (no explicit tabId) and actually resolved. A blank `tabUrl` means the

package/dist/src/bridge/connection.js

@@ -38,6 +38,8 @@ function mapWireErrorCode(code) {
 }
 /** Commands that can change WHICH tab is active, invalidating a cached URL. */
 const ACTIVE_TAB_CHANGERS = new Set(['tab_select', 'tab_new', 'tab_close']);
+/** Bound on the per-tab URL cache; entries beyond it are evicted oldest-first. */
+const MAX_TAB_URL_ENTRIES = 256;
 class ExtensionConnection {
     extId;
     sessionId;
@@ -51,6 +53,10 @@ class ExtensionConnection {
     reportsTabUrl;
     /** Last URL the ACTIVE tab reported, with the wall-clock it arrived. */
     activeUrl = null;
+    /** Last URL each explicitly-targeted tab reported, keyed by wire tab id. A
+     *  `tabs_list` result fills this for EVERY tab at once, which is what lets a
+     *  parallel batch over N tabs gate on one round-trip instead of N. */
+    tabUrls = new Map();
     onEvent;
     onClose;
     onLog;
@@ -98,7 +104,7 @@ class ExtensionConnection {
                 reject(new types_1.ExecutorError('TIMEOUT', `"${method}" timed out after ${timeoutMs}ms`));
             }, timeoutMs);
             timer.unref?.();
-            this.pending.set(id, { resolve, reject, timer, method, activeTab: opts?.tabId === undefined });
+            this.pending.set(id, { resolve, reject, timer, method, activeTab: opts?.tabId === undefined, tabId: opts?.tabId });
             try {
                 this.ws.send(JSON.stringify(frame));
             }
@@ -161,15 +167,63 @@ class ExtensionConnection {
         this.pending.delete(id);
         if (frame.type === 'result') {
             this.rememberActiveUrl(p, frame);
+            this.rememberTabUrls(p, frame);
             p.resolve(frame.data);
         }
         else {
             // A failed command tells us nothing reliable about where the tab ended up.
             if (p.activeTab)
                 this.activeUrl = null;
+            if (p.tabId)
+                this.tabUrls.delete(p.tabId);
             p.reject(new types_1.ExecutorError(mapWireErrorCode(frame.error.code), frame.error.message));
         }
     }
+    /**
+     * Per-tab cache. Two feeds: a result for an explicitly-targeted tab carries
+     * that tab's landing URL; a `tabs_list` result carries every tab's URL, so one
+     * listing primes the gate for every op of a batch that follows it. A closed
+     * tab is forgotten; a blank URL (Chrome hiding it) is forgotten too, never kept.
+     */
+    rememberTabUrls(p, frame) {
+        if (!this.reportsTabUrl)
+            return;
+        const now = Date.now();
+        if (p.method === 'tab_close' && p.tabId) {
+            this.tabUrls.delete(p.tabId);
+            return;
+        }
+        if (p.method === 'tabs_list' && Array.isArray(frame.data)) {
+            for (const t of frame.data) {
+                if (typeof t.tabId !== 'string')
+                    continue;
+                if (typeof t.url === 'string' && t.url)
+                    this.tabUrls.set(t.tabId, { url: t.url, at: now });
+                else
+                    this.tabUrls.delete(t.tabId);
+            }
+        }
+        else if (p.tabId) {
+            if (frame.tabUrl)
+                this.tabUrls.set(p.tabId, { url: frame.tabUrl, at: now });
+            else
+                this.tabUrls.delete(p.tabId);
+        }
+        // Map iteration is insertion-ordered; drop the oldest until bounded.
+        while (this.tabUrls.size > MAX_TAB_URL_ENTRIES) {
+            const oldest = this.tabUrls.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.tabUrls.delete(oldest);
+        }
+    }
+    /** A specific tab's last reported URL if younger than `maxAgeMs`, else null. */
+    lastTabUrl(tabId, maxAgeMs) {
+        const hit = this.tabUrls.get(tabId);
+        if (!hit)
+            return null;
+        return Date.now() - hit.at <= maxAgeMs ? hit.url : null;
+    }
     /**
      * Cache the URL a result rode home with — but ONLY when it describes the active
      * tab (no explicit tabId) and actually resolved. A blank `tabUrl` means the

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

@@ -71,6 +71,8 @@ export declare class BridgeServer {
      * to report URLs, a tab shuffle since, or simply nothing recent enough.
      */
     lastActiveUrl(profile: string | undefined, maxAgeMs: number): string | null;
+    /** Same, for an explicitly-targeted tab (wire id) — see ExtensionConnection.lastTabUrl. */
+    lastTabUrl(profile: string | undefined, tabId: string, maxAgeMs: number): string | null;
     private noPairMessage;
     status(): {
         extensionConnected: boolean;

package/dist/src/bridge/server.js

@@ -187,6 +187,11 @@ class BridgeServer {
         const conn = this.conns.get(routeKey(profile));
         return conn?.isOpen() ? conn.lastActiveUrl(maxAgeMs) : null;
     }
+    /** Same, for an explicitly-targeted tab (wire id) — see ExtensionConnection.lastTabUrl. */
+    lastTabUrl(profile, tabId, maxAgeMs) {
+        const conn = this.conns.get(routeKey(profile));
+        return conn?.isOpen() ? conn.lastTabUrl(tabId, maxAgeMs) : null;
+    }
     noPairMessage(profile) {
         return (`No browser is paired for profile "${profile}". In that Chrome's chrome-mcp ` +
             `extension Options, set Port ${this.boundPort}, paste the token, set Profile to ` +

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

@@ -44,7 +44,7 @@ export declare function saveResult(tool: string, ext: string, body: string): str
  */
 export declare function saveBinary(tool: string, ext: string, bytes: Buffer): string | null;
 /** Save a screenshot PNG (base64) into the active task's `screenshots/`. */
-export declare function saveScreenshot(dataBase64: string): string | null;
+export declare function saveScreenshot(dataBase64: string, ext?: 'png' | 'jpg'): string | null;
 /**
  * Move a file Chrome saved to the user's Downloads dir into the active task's
  * `downloads/`. The name is re-hardened via {@link sanitizeDownloadName} and the

package/dist/src/bridge/workspace.js

@@ -123,12 +123,12 @@ function saveBinary(tool, ext, bytes) {
     }
 }
 /** Save a screenshot PNG (base64) into the active task's `screenshots/`. */
-function saveScreenshot(dataBase64) {
+function saveScreenshot(dataBase64, ext = 'png') {
     const w = peekActiveWorkspace();
     if (!w)
         return null;
     try {
-        const path = (0, node_path_1.join)(w.screenshotsDir, `${stem('screenshot')}.png`);
+        const path = (0, node_path_1.join)(w.screenshotsDir, `${stem('screenshot')}.${ext}`);
         (0, node_fs_1.writeFileSync)(path, Buffer.from(dataBase64, 'base64'), { mode: 0o600 });
         return path;
     }

package/dist/src/cli.js

@@ -21,6 +21,7 @@ const datadir_1 = require("./bridge/datadir");
 const workspace_1 = require("./bridge/workspace");
 const auth_1 = require("./bridge/auth");
 const server_2 = require("./mcp/server");
+const tools_1 = require("./mcp/tools");
 const extension_install_1 = require("./extension-install");
 /** Hard deadline for clean shutdown before we force-exit (a stuck socket must not hang us). */
 const SHUTDOWN_DEADLINE_MS = 3000;
@@ -158,6 +159,21 @@ function runTasksCommand(argv) {
     process.stdout.write(TASKS_HELP);
     return true;
 }
+/** The tool names, wrapped into indented lines for `--help`. */
+function toolList() {
+    const lines = [];
+    let line = ' ';
+    for (const name of tools_1.TOOL_NAMES) {
+        if (line.length + name.length + 2 > 78) {
+            lines.push(line);
+            line = ' ';
+        }
+        line += ` ${name}`;
+    }
+    if (line.trim())
+        lines.push(line);
+    return lines.join('\n');
+}
 async function main() {
     if (runTasksCommand(process.argv.slice(2)))
         return;
@@ -168,6 +184,8 @@ async function main() {
     (0, server_2.setLogLevel)(cfg.logLevel);
     if (cfg.showHelp) {
         process.stdout.write(config_1.HELP_TEXT);
+        // The catalog is what `--tools` takes, so `--help` has to name it.
+        process.stdout.write(`\nTools (${tools_1.TOOL_NAMES.length}) — any of these for --tools:\n${toolList()}\n`);
         return;
     }
     if (cfg.showVersion) {
@@ -178,6 +196,9 @@ async function main() {
         process.stdout.write(`${installExtension()}\n`);
         return;
     }
+    // Before the bridge binds a port or writes a handshake: a typo'd `--tools`
+    // name should fail as a plain startup error, not leave a half-started server.
+    (0, tools_1.setToolAllowlist)(cfg.tools);
     const dataDir = (0, datadir_1.ensureDataDir)(cfg.dataDir);
     const token = (0, auth_1.resolveToken)(dataDir, { persist: cfg.persistToken });
     const { allowDomains, allowEval, allowDownloads, allowUploads, allowAllTabs, enableMutations } = cfg.policy;
@@ -285,9 +306,9 @@ async function main() {
     await (0, server_2.startMcpServer)(version());
 }
 main().catch((err) => {
-    // Port-busy and similar startup failures carry a plain-English message already;
-    // show that to the user without a noisy stack trace.
-    const friendly = err instanceof Error && /Couldn't start:/.test(err.message);
+    // Port-busy and bad-flag failures carry a plain-English message already
+    // (a flag error starts with the flag); show it without a noisy stack trace.
+    const friendly = err instanceof Error && /^(Couldn't start:|--|unknown argument:)/.test(err.message);
     (0, server_2.logErr)(friendly ? err.message : `fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
     process.exit(1);
 });

package/dist/src/config.d.ts

@@ -34,6 +34,12 @@ export interface CliConfig {
     showExtensionPath: boolean;
     /** `--persist-token`: reuse a stable on-disk token so the extension never re-pairs. */
     persistToken: boolean;
+    /**
+     * `--tools`: advertise only these tools. `undefined` = the whole catalog.
+     * Names are validated against the catalog by `setToolAllowlist` at startup —
+     * config.ts deliberately does not import the tool surface.
+     */
+    tools?: string[];
     showHelp: boolean;
     showVersion: boolean;
     logLevel: LogLevel;

package/dist/src/config.js

@@ -82,6 +82,10 @@ function parseArgs(argv) {
     let showVersion = false;
     let showExtensionPath = false;
     let logLevel = 'info';
+    // Insertion-ordered so `--tools` keeps the order the operator wrote, and a
+    // name repeated across two flags is listed once.
+    const tools = new Set();
+    let toolsFlagSeen = false;
     // Policy assembled from flags, layered over an optional file.
     let policyFile;
     const policyFlags = {};
@@ -174,6 +178,11 @@ function parseArgs(argv) {
             case '--persist-token':
                 persistToken = true;
                 break;
+            case '--tools':
+                toolsFlagSeen = true;
+                for (const name of splitList(requireValue(argv[++i], '--tools')))
+                    tools.add(name);
+                break;
             case '--log-level':
                 logLevel = requireLogLevel(argv[++i]);
                 break;
@@ -196,6 +205,12 @@ function parseArgs(argv) {
     if (policy.allowUploads && !policy.uploadsDir) {
         throw new Error('--enable-uploads requires --uploads-dir <path> (uploads must be confined to a directory)');
     }
+    // `--tools ""` (or `--tools ,,`) means the operator asked for a restriction and
+    // got none — an empty surface is never what they wanted, and silently serving
+    // all 39 tools is the opposite of what they asked for.
+    if (toolsFlagSeen && tools.size === 0) {
+        throw new Error('--tools requires at least one tool name (comma-separated, e.g. --tools navigate,get_text)');
+    }
     // Fail at startup, not on the first read, if a redaction pattern is malformed:
     // a pattern the user believes is scrubbing secrets but that never compiled is
     // the worst of both worlds.
@@ -223,6 +238,7 @@ function parseArgs(argv) {
         showVersion,
         showExtensionPath,
         logLevel,
+        tools: tools.size > 0 ? [...tools] : undefined,
     };
 }
 // ---------------------------------------------------------------------------
@@ -248,6 +264,13 @@ function requireInt(value, flag) {
         throw new Error(`${flag} must be a non-negative integer`);
     return n;
 }
+/** Split a repeatable comma/space-separated list flag, dropping empty entries. */
+function splitList(value) {
+    return value
+        .split(/[,\s]+/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
 function requirePreference(value) {
     if (value === 'extension' || value === 'cdp')
         return value;
@@ -318,6 +341,15 @@ Security (default: deny-all safe mode):
                          high-confidence sign-in wall (expired session), so an
                          eval harness never scores it as some other failure.
 
+Tool surface:
+  --tools <list>         Advertise ONLY these tools (comma-separated, repeatable).
+                         Everything else is hidden from tools/list and refused if
+                         called — including from inside a batch op. The catalog is
+                         re-sent to the model on every turn, so trimming it to the
+                         tools a run actually needs is the cheapest context saving
+                         there is. Unknown names fail at startup.
+                         e.g. --tools tabs_list,navigate,get_text,click,type
+
 Misc:
   --log-level <lvl>      silent | info | debug (default info)
   -h, --help             Show this help

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 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';
+import { type ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type KeyModifier, type NavResult, type ScreenshotEncoding, type ScreenshotResult, type SnapshotLocator, 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;
@@ -124,6 +124,7 @@ export declare class CdpExecutor implements Executor {
         tabId?: TabId;
         interactiveOnly?: boolean;
         max?: number;
+        locator?: SnapshotLocator;
     }): Promise<SnapshotResult>;
     getCookies(opts?: {
         tabId?: TabId;
@@ -142,7 +143,7 @@ export declare class CdpExecutor implements Executor {
         tabId?: TabId;
         fullPage?: boolean;
         target?: Target;
-    }): Promise<ScreenshotResult>;
+    } & ScreenshotEncoding): Promise<ScreenshotResult>;
     eval(expression: string, opts?: {
         tabId?: TabId;
         awaitPromise?: boolean;

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

@@ -22,6 +22,7 @@ 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 screenshot_1 = require("../../shared/screenshot");
 const types_1 = require("./types");
 const SINGLETON_FILES = ['SingletonLock', 'SingletonSocket', 'SingletonCookie'];
 const STEALTH = `Object.defineProperty(navigator,'webdriver',{get:()=>undefined});`;
@@ -436,11 +437,11 @@ class CdpExecutor {
         return this.guard(async () => {
             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]) => {
+            const raw = await p.evaluate(([fnSrc, interactiveOnly, max, locator]) => {
                 // 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 fn(interactiveOnly, max, locator ?? null);
+            }, [snapshot_1.collectSnapshot.toString(), opts?.interactiveOnly ?? true, opts?.max ?? 200, opts?.locator ?? null]);
             return raw;
         });
     }
@@ -488,11 +489,25 @@ class CdpExecutor {
     async screenshot(opts) {
         return this.guard(async () => {
             const p = await this.resolveTab(opts?.tabId);
+            const type = opts?.format ?? screenshot_1.DEFAULT_SCREENSHOT_FORMAT;
+            // Playwright's `scale: 'css'` = one output pixel per CSS pixel (the same
+            // default the extension path uses); 'device' = the display's native DPR.
+            const enc = {
+                type,
+                ...(type === 'jpeg' ? { quality: opts?.quality ?? screenshot_1.DEFAULT_JPEG_QUALITY } : {}),
+                scale: (opts?.scale ?? screenshot_1.DEFAULT_SCREENSHOT_SCALE) >= 2 ? 'device' : 'css',
+            };
             const buf = opts?.target
-                ? await this.locator(p, opts.target).screenshot()
-                : await p.screenshot({ fullPage: opts?.fullPage });
+                ? await this.locator(p, opts.target).screenshot(enc)
+                : await p.screenshot({ fullPage: opts?.fullPage, ...enc });
             const size = p.viewportSize() ?? { width: 0, height: 0 };
-            return { dataBase64: buf.toString('base64'), mimeType: 'image/png', width: size.width, height: size.height, truncated: false };
+            return {
+                dataBase64: buf.toString('base64'),
+                mimeType: type === 'jpeg' ? 'image/jpeg' : 'image/png',
+                width: size.width,
+                height: size.height,
+                truncated: false,
+            };
         });
     }
     async eval(expression, opts) {

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 CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type FrameInfo, type FrameOpts, type ObserverArgs, type ObserverReadResult, type PdfResult, 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 ActionOk, type BackendKind, type CookieItem, type DownloadResult, type EvalResult, type Executor, type ExecutorStatus, type FrameInfo, type FrameOpts, type ObserverArgs, type ObserverReadResult, type PdfResult, type KeyModifier, type MouseButton, type NavResult, type ScreenshotEncoding, type ScreenshotResult, type SnapshotLocator, 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;
@@ -24,6 +24,9 @@ export declare class ExtensionExecutor implements Executor {
     /** The active tab's URL as reported by the last command on this profile, if it
      *  is fresh enough to gate against. See `ACTIVE_URL_TTL_MS`. */
     cachedActiveUrl(): string | null;
+    /** A specific tab's URL as last reported (by a result for that tab, or by a
+     *  `tabs_list`), if fresh enough to gate against. */
+    cachedTabUrl(tabId: TabId): string | null;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     tabNew(url?: string, opts?: {
@@ -94,6 +97,7 @@ export declare class ExtensionExecutor implements Executor {
         tabId?: TabId;
         interactiveOnly?: boolean;
         max?: number;
+        locator?: SnapshotLocator;
     } & FrameOpts): Promise<SnapshotResult>;
     getCookies(opts?: {
         tabId?: TabId;
@@ -112,7 +116,7 @@ export declare class ExtensionExecutor implements Executor {
         tabId?: TabId;
         fullPage?: boolean;
         target?: Target;
-    } & FrameOpts): Promise<ScreenshotResult>;
+    } & ScreenshotEncoding & FrameOpts): Promise<ScreenshotResult>;
     eval(expression: string, opts?: {
         tabId?: TabId;
         awaitPromise?: boolean;