@mehmoodqureshi/chrome-mcp 0.9.2 → 0.9.3

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/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;

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

@@ -18,10 +18,11 @@ const workspace_1 = require("../bridge/workspace");
  * Deliberately short. It exists to cover back-to-back calls (a `batch`, or an
  * agent's read → click → read), where the tab demonstrably has not changed
  * between them. Past that, pay the round-trip. Note the extension re-gates every
- * command against the tab's live URL regardless, so this window trades a little
- * pre-check precision for half the traffic — never enforcement itself.
+ * command against the tab's live URL regardless (fail-closed, authoritative), so
+ * this window trades a little pre-check precision for half the traffic — never
+ * enforcement itself.
  */
-const ACTIVE_URL_TTL_MS = 1_000;
+const ACTIVE_URL_TTL_MS = 2_000;
 /** Flatten frame options into the params a wire command carries. */
 function frameParams(o) {
     if (!o)
@@ -88,6 +89,11 @@ class ExtensionExecutor {
     cachedActiveUrl() {
         return this.bridge.lastActiveUrl(this.activeProfile(), ACTIVE_URL_TTL_MS);
     }
+    /** 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) {
+        return this.bridge.lastTabUrl(this.activeProfile(), tabId, ACTIVE_URL_TTL_MS);
+    }
     // -- tabs ---------------------------------------------------------------
     async tabsList() {
         return (await this.send('tabs_list', {}));
@@ -145,7 +151,7 @@ class ExtensionExecutor {
         return (await this.send('get_html', { ...targetParams(t), ...frameParams(opts), outer: opts?.outer }, { tabId: opts?.tabId }));
     }
     async snapshot(opts) {
-        return (await this.send('snapshot', { interactiveOnly: opts?.interactiveOnly, max: opts?.max, ...frameParams(opts) }, { tabId: opts?.tabId }));
+        return (await this.send('snapshot', { interactiveOnly: opts?.interactiveOnly, max: opts?.max, locator: opts?.locator, ...frameParams(opts) }, { tabId: opts?.tabId }));
     }
     async getCookies(opts) {
         return (await this.send('get_cookies', { url: opts?.url }, { tabId: opts?.tabId }));
@@ -154,7 +160,14 @@ class ExtensionExecutor {
         return (await this.send('storage', { op: args.op, key: args.key, value: args.value, session: args.session }, { tabId: args.tabId }));
     }
     async screenshot(opts) {
-        return (await this.send('screenshot', { fullPage: opts?.fullPage, ...targetParams(opts?.target), ...frameParams(opts) }, { tabId: opts?.tabId }));
+        return (await this.send('screenshot', {
+            fullPage: opts?.fullPage,
+            format: opts?.format,
+            quality: opts?.quality,
+            scale: opts?.scale,
+            ...targetParams(opts?.target),
+            ...frameParams(opts),
+        }, { tabId: opts?.tabId }));
     }
     async eval(expression, opts) {
         const result = (await this.send('eval', { expression, awaitPromise: opts?.awaitPromise, ...frameParams(opts) }, { tabId: opts?.tabId }));

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

@@ -111,9 +111,18 @@ export interface WaitResult {
 export interface ActionOk {
     ok: true;
 }
+export type ScreenshotFormat = 'png' | 'jpeg';
+/** Encoding knobs every backend accepts. All optional; see shared/screenshot.ts for defaults. */
+export interface ScreenshotEncoding {
+    format?: ScreenshotFormat;
+    /** JPEG only, 1-100. */
+    quality?: number;
+    /** Output pixels per CSS pixel (1 = CSS size, 2 = device pixels on a Retina display). */
+    scale?: number;
+}
 export interface ScreenshotResult {
     dataBase64: string;
-    mimeType: 'image/png';
+    mimeType: 'image/png' | 'image/jpeg';
     width: number;
     height: number;
     /** fullPage capture exceeded the height cap; `fullHeight` reports the real size. */
@@ -153,6 +162,13 @@ export interface SnapshotResult {
     title: string;
     nodes: SnapshotNode[];
     truncated: boolean;
+    /** Locator mode, no match: what the page had of that role (for the error message). */
+    nearby?: string[];
+}
+/** A role/name query the page resolves itself (see shared/snapshot.ts). */
+export interface SnapshotLocator {
+    role?: string;
+    name?: string;
 }
 export interface CookieItem {
     name: string;
@@ -205,6 +221,12 @@ export interface Executor {
      * report cheaply simply omit it.
      */
     cachedActiveUrl?(): string | null;
+    /**
+     * Same idea for an explicitly-targeted tab: its URL if the backend already
+     * knows it recently enough (the extension reports it on every result for that
+     * tab, and a `tabsList` reports it for every tab). Null → resolve properly.
+     */
+    cachedTabUrl?(tabId: TabId): string | null;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     /** Open a tab. `active` (default true) focuses it; pass false to open in the background. */
@@ -279,6 +301,7 @@ export interface Executor {
         tabId?: TabId;
         interactiveOnly?: boolean;
         max?: number;
+        locator?: SnapshotLocator;
     } & FrameOpts): Promise<SnapshotResult>;
     /** Read cookies visible to the active tab's URL (or a given url). */
     getCookies(opts?: {
@@ -299,7 +322,7 @@ export interface Executor {
         tabId?: TabId;
         fullPage?: boolean;
         target?: Target;
-    } & FrameOpts): Promise<ScreenshotResult>;
+    } & ScreenshotEncoding & FrameOpts): Promise<ScreenshotResult>;
     eval(expression: string, opts?: {
         tabId?: TabId;
         awaitPromise?: boolean;

package/dist/src/mcp/locate.d.ts

@@ -9,10 +9,13 @@
  * redeploy.
  *
  * A locator closes that: `{ role: 'button', name: 'Sign in' }` resolves through
- * one snapshot, server-side, and the caller never sees the tree. Matching runs
- * strongest-first (exact, then case-insensitive, then contains) so an
- * unambiguous name wins outright, and an ambiguous one fails loudly with the
- * candidates rather than silently clicking the first row.
+ * one snapshot and the caller never sees the tree. The page does the matching
+ * itself (`collectSnapshot` with a locator returns only the strongest-tier
+ * hits, and stamps refs on those alone), so what crosses the bridge is a
+ * handful of nodes rather than 400; this module re-scores them — same tiers:
+ * exact, then case-insensitive, then prefix, then contains — so an unambiguous
+ * name wins outright and an ambiguous one fails loudly with the candidates
+ * rather than silently clicking the first row.
  */
 import type { Executor, SnapshotNode, Target } from '../executor/types';
 export interface Locator {