@mehmoodqureshi/chrome-mcp 0.9.1 → 0.9.3

package/dist/shared/screenshot.d.ts

@@ -14,7 +14,20 @@ export interface PageDims {
     /** Full content box (document) width/height. */
     fullW: number;
     fullH: number;
+    /** window.devicePixelRatio (default 1). Output pixels = CSS px * dpr * clip.scale. */
+    dpr?: number;
+    /** Current scroll offset of the top document (default 0,0); a viewport clip starts here. */
+    scrollX?: number;
+    scrollY?: number;
 }
+export type ScreenshotFormat = 'png' | 'jpeg';
+/** Default encoding: JPEG at this quality is ~5-10x smaller than PNG on a
+ *  typical page and still perfectly legible to a vision model. */
+export declare const DEFAULT_SCREENSHOT_FORMAT: ScreenshotFormat;
+export declare const DEFAULT_JPEG_QUALITY = 70;
+/** Output size multiplier relative to CSS pixels. 1 = CSS px (so a Retina
+ *  viewport is NOT captured at 2x); 2 = device px on a 2x display. */
+export declare const DEFAULT_SCREENSHOT_SCALE = 1;
 /** An element's box in DOCUMENT coordinates (viewport rect + scroll offset), CSS px. */
 export interface ElementRect {
     x: number;
@@ -55,4 +68,5 @@ export declare const MAX_CAPTURE_PX = 16384;
 export declare function planScreenshot(dims: PageDims, opts?: {
     fullPage?: boolean;
     element?: ElementRect | null;
+    scale?: number;
 }): ScreenshotPlan;

package/dist/shared/screenshot.js

@@ -8,8 +8,15 @@
  * `ScreenshotResult` reports. No chrome.* calls — just arithmetic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_CAPTURE_PX = void 0;
+exports.MAX_CAPTURE_PX = exports.DEFAULT_SCREENSHOT_SCALE = exports.DEFAULT_JPEG_QUALITY = exports.DEFAULT_SCREENSHOT_FORMAT = void 0;
 exports.planScreenshot = planScreenshot;
+/** Default encoding: JPEG at this quality is ~5-10x smaller than PNG on a
+ *  typical page and still perfectly legible to a vision model. */
+exports.DEFAULT_SCREENSHOT_FORMAT = 'jpeg';
+exports.DEFAULT_JPEG_QUALITY = 70;
+/** Output size multiplier relative to CSS pixels. 1 = CSS px (so a Retina
+ *  viewport is NOT captured at 2x); 2 = device px on a 2x display. */
+exports.DEFAULT_SCREENSHOT_SCALE = 1;
 /**
  * Practical single-capture height ceiling. Skia/CDP cannot encode arbitrarily
  * tall images; beyond this we clamp the clip and flag `truncated`.
@@ -20,11 +27,15 @@ exports.MAX_CAPTURE_PX = 16384;
  * viewport capture. Heights are clamped to MAX_CAPTURE_PX with `truncated` set.
  */
 function planScreenshot(dims, opts = {}) {
+    // CDP's clip.scale multiplies on top of the device scale factor, so dividing
+    // by the DPR yields exactly `opts.scale` output pixels per CSS pixel.
+    const dpr = dims.dpr && dims.dpr > 0 ? dims.dpr : 1;
+    const scale = (opts.scale && opts.scale > 0 ? opts.scale : exports.DEFAULT_SCREENSHOT_SCALE) / dpr;
     if (opts.element) {
         const realH = Math.max(1, Math.round(opts.element.h));
         const clipH = Math.min(opts.element.h, exports.MAX_CAPTURE_PX);
         return {
-            clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale: 1 },
+            clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale },
             captureBeyondViewport: true,
             width: Math.max(1, Math.round(opts.element.w)),
             height: Math.min(realH, exports.MAX_CAPTURE_PX),
@@ -35,7 +46,7 @@ function planScreenshot(dims, opts = {}) {
     if (opts.fullPage) {
         const clipH = Math.min(dims.fullH, exports.MAX_CAPTURE_PX);
         return {
-            clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale: 1 },
+            clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale },
             captureBeyondViewport: true,
             width: dims.fullW,
             height: clipH,
@@ -43,8 +54,12 @@ function planScreenshot(dims, opts = {}) {
             fullHeight: dims.fullH,
         };
     }
-    // Plain viewport: no clip, capture what's visible.
+    // Plain viewport: capture what's visible. A clip is only needed to apply a
+    // scale; at scale 1 on a 1x display the bare capture is identical and cheaper.
     return {
+        ...(scale !== 1
+            ? { clip: { x: dims.scrollX ?? 0, y: dims.scrollY ?? 0, width: dims.w, height: dims.h, scale } }
+            : {}),
         captureBeyondViewport: false,
         width: dims.w,
         height: dims.h,

package/dist/shared/snapshot.d.ts

@@ -23,6 +23,28 @@ export interface RawSnapshot {
     title: string;
     nodes: RawSnapshotNode[];
     truncated: boolean;
+    /** Locator mode, nothing matched: up to 8 "role \"name\"" strings of the
+     *  same role, so the caller can say what WAS there without a second read. */
+    nearby?: string[];
 }
-/** Runs IN THE PAGE. Returns interactive (and optionally landmark) elements with fresh refs. */
-export declare function collectSnapshot(interactiveOnly?: boolean, max?: number): RawSnapshot;
+/** A role/name query resolved IN the page (see `collectSnapshot`). */
+export interface SnapshotLocator {
+    role?: string;
+    name?: string;
+}
+/**
+ * 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.
+ */
+export declare function collectSnapshot(interactiveOnly?: boolean, max?: number, locator?: SnapshotLocator | null): RawSnapshot;

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/config.js

@@ -150,6 +150,9 @@ function parseArgs(argv) {
                 policyFlags.redact = true;
                 (policyFlags.redactPatterns ??= []).push(requireValue(argv[++i], '--redact-pattern'));
                 break;
+            case '--fail-on-auth-wall':
+                policyFlags.failOnAuthWall = true;
+                break;
             case '--cdp-fallback':
                 cdpFallback = true;
                 break;
@@ -310,6 +313,10 @@ Security (default: deny-all safe mode):
                          tokens, private keys) out of page reads. Password field
                          values are always suppressed, with or without this.
   --redact-pattern <re>  Add a redaction regex (repeatable; implies --redact)
+  --fail-on-auth-wall    Fail any navigate/click/type/press/back/reload/wait_for
+                         with [AUTH_REQUIRED] when the page it lands on is a
+                         high-confidence sign-in wall (expired session), so an
+                         eval harness never scores it as some other failure.
 
 Misc:
   --log-level <lvl>      silent | info | debug (default info)

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;