@mehmoodqureshi/chrome-mcp 0.9.1 → 0.9.3

package/README.md

@@ -333,6 +333,46 @@ type  { "role": "textbox", "name": "Email", "text": "a@b.com" }
 Resolution is server-side and refuses to guess: an ambiguous locator fails with
 the candidates listed rather than acting on the first one (pass `nth` to pick).
 
+### Did the session expire? — `auth_check` and `failOnAuthWall`
+
+Reusing a signed-in Chrome removes the login step, but a session cookie can
+still expire mid-run. Without a distinct signal the next step fails as
+`SELECTOR_NOT_FOUND` or `TIMEOUT`, and an eval harness scores the run as an
+agent failure when it was an auth failure. Every `snapshot` now carries an
+`authWall` verdict when the page looks like a sign-in wall, and there is a
+dedicated probe:
+
+```jsonc
+auth_check {}                                   // { authRequired, confidence, signals }
+auth_check { "failOnAuthWall": true }           // [AUTH_REQUIRED] error instead
+navigate  { "url": "https://app.example.com/dashboard", "failOnAuthWall": true }
+snapshot  { "failOnAuthWall": true }
+```
+
+For a harness, set it once instead of per call:
+
+```
+npx -y @mehmoodqureshi/chrome-mcp --allow-domain app.example.com --enable-mutations --fail-on-auth-wall
+```
+
+With the flag on, every step that can move the tab (`navigate`, `click`, `type`,
+`select_option`, `press`, `fill_form`, `back`, `forward`, `reload`) checks the
+page it landed on and fails with `[AUTH_REQUIRED]` if that page is a sign-in
+wall, and a `wait_for` that times out on such a page reports `[AUTH_REQUIRED]`
+instead of `[TIMEOUT]`. Each guarded step costs one extra snapshot round-trip;
+with the flag off the cost is zero. `[AUTH_REQUIRED]` is where a harness pauses
+for a human to sign in again in the same Chrome, then retries the step. chrome-mcp
+never re-authenticates on its own: it holds no credentials, by design.
+
+Detection reads only what the snapshot already has: the URL (sign-in routes,
+identity-provider hosts such as `accounts.google.com`, `login.microsoftonline.com`,
+Okta, Auth0), the title, password fields, and sign-in controls. `high`
+confidence needs two independent cues (a password field plus a sign-in button,
+say); a lone password field or a bare `/auth/...` URL is `medium`. A header
+"Sign in" link on an ordinary page never counts. `failOnAuthWall` fires only on
+`high`, so a harness can bucket `[AUTH_REQUIRED]` separately from every other
+failure while a settings page with a "current password" field carries on.
+
 ### Printing — `print_pdf`
 
 ```jsonc
@@ -462,5 +502,7 @@ the fallback.
 > `chrome.debugger` is used only where it's needed and worth it: `trusted: true`
 > input (real OS-level events on React/Vue inputs) and `screenshot` (captures a
 > specific tab **without** activating it — safe under parallel `batch` — with
-> true full-page and element capture). Those ops briefly show the debug banner
-> while attached.
+> true full-page and element capture). Those ops show the debug banner while
+> attached; the session lingers 1.5s after the last op so a burst of them
+> attaches once. Screenshots are JPEG (quality 70) at CSS-pixel size by
+> default — pass `format: "png"`, `quality`, or `scale` to change that.

package/dist/shared/auth-wall.d.ts

@@ -0,0 +1,51 @@
+/**
+ * shared/auth-wall.ts — decide whether a page is a login wall.
+ *
+ * A browser agent that reuses a signed-in Chrome profile still hits the moment
+ * the session cookie expires mid-run: the next page is a sign-in form, and
+ * every later step fails for a reason that has nothing to do with the task.
+ * Without a distinct signal, an eval harness buckets that as SELECTOR_NOT_FOUND
+ * or TIMEOUT and the run is scored as an agent failure instead of an auth
+ * failure.
+ *
+ * This module is the pure decision. It reads only what an accessibility
+ * snapshot already carries (URL, title, password fields, button/link names), so
+ * it works identically on both backends and needs nothing new from the
+ * extension. Server-side callers attach the verdict to snapshot results, expose
+ * it as `auth_check`, and can turn it into an `AUTH_REQUIRED` error.
+ */
+export type AuthWallConfidence = 'high' | 'medium';
+export type AuthWallSignal = 'password-field' | 'login-url' | 'identity-provider' | 'login-title' | 'login-button' | 'username-field';
+export interface AuthWall {
+    detected: true;
+    confidence: AuthWallConfidence;
+    signals: AuthWallSignal[];
+}
+/** The subset of a snapshot the detector reads. */
+export interface AuthWallPage {
+    url: string;
+    title: string;
+    nodes: Array<{
+        role: string;
+        name: string;
+        tag: string;
+        secret?: boolean;
+    }>;
+}
+/**
+ * Inspect a page and return a verdict, or `null` when it does not look like a
+ * login wall.
+ *
+ * Confidence:
+ * - `high`: a password field plus a sign-in control, title, or URL; or a
+ *   sign-in URL plus a sign-in control or title; or an identity-provider host.
+ * - `medium`: exactly one weaker cue on its own (a password field, or a
+ *   sign-in URL) with nothing to corroborate it. Callers that fail a run on a
+ *   wall should usually require `high`.
+ *
+ * A lone "Sign in" link or a title mention never counts: most public pages have
+ * one in the header.
+ */
+export declare function detectAuthWall(page: AuthWallPage): AuthWall | null;
+/** A one-line, human-readable explanation for error messages and logs. */
+export declare function describeAuthWall(wall: AuthWall, url: string): string;

package/dist/shared/auth-wall.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * shared/auth-wall.ts — decide whether a page is a login wall.
+ *
+ * A browser agent that reuses a signed-in Chrome profile still hits the moment
+ * the session cookie expires mid-run: the next page is a sign-in form, and
+ * every later step fails for a reason that has nothing to do with the task.
+ * Without a distinct signal, an eval harness buckets that as SELECTOR_NOT_FOUND
+ * or TIMEOUT and the run is scored as an agent failure instead of an auth
+ * failure.
+ *
+ * This module is the pure decision. It reads only what an accessibility
+ * snapshot already carries (URL, title, password fields, button/link names), so
+ * it works identically on both backends and needs nothing new from the
+ * extension. Server-side callers attach the verdict to snapshot results, expose
+ * it as `auth_check`, and can turn it into an `AUTH_REQUIRED` error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAuthWall = detectAuthWall;
+exports.describeAuthWall = describeAuthWall;
+/** Path segments that mark a sign-in route on most stacks. */
+const LOGIN_PATH = /(^|[\/._-])(login|log-in|logon|log-on|signin|sign-in|sign_in|authenticate|auth|sso|oauth2?|saml|sessions?\/new|users\/sign_in|account\/login|idp)([\/?#._-]|$)/i;
+/** Hosts (or host suffixes) that are identity providers, whatever the path. */
+const IDP_HOSTS = [
+    'accounts.google.com',
+    'login.microsoftonline.com',
+    'login.live.com',
+    'login.microsoft.com',
+    'appleid.apple.com',
+    'login.yahoo.com',
+    'auth0.com',
+    'okta.com',
+    'oktapreview.com',
+    'onelogin.com',
+    'pingidentity.com',
+    'duosecurity.com',
+    'github.com/login',
+    'login.salesforce.com',
+    'signin.aws.amazon.com',
+    'auth.atlassian.com',
+    'id.atlassian.com',
+    'login.linkedin.com',
+];
+const LOGIN_TITLE = /\b(sign in|sign-in|signin|log in|log-in|login|log on|logon|authenticate|authentication required|session (has )?expired|session timed out|please sign in|please log in|verify it'?s you)\b/i;
+/** Button/link labels that submit or start a sign-in. Anchored so a header "Sign in" link with extra copy still matches only when the label is the action. */
+const LOGIN_BUTTON = /^(sign in|sign-in|signin|log in|log-in|login|log on|logon|continue|next|submit|authenticate|(sign|log) ?in (with|via|using) .{1,40}|continue with .{1,40}|use (your )?password|sign in to continue|log in to continue)$/i;
+/** Labels that mark a credential's username half; only a booster, never a wall on its own. */
+const USERNAME_FIELD = /\b(email|e-mail|username|user name|user id|userid|phone|account|login id)\b/i;
+/** The action-shaped labels that, next to a password field, make this a form and not a "change password" settings page. */
+const STRONG_BUTTON = /^(sign in|sign-in|signin|log in|log-in|login|log on|logon|authenticate|sign in to continue|log in to continue|(sign|log) ?in (with|via|using) .{1,40}|continue with .{1,40})$/i;
+function parseUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+function isIdpHost(u) {
+    const host = u.hostname.toLowerCase();
+    const hostAndPath = `${host}${u.pathname}`.toLowerCase();
+    return IDP_HOSTS.some((h) => {
+        if (h.includes('/'))
+            return hostAndPath === h || hostAndPath.startsWith(`${h}/`);
+        return host === h || host.endsWith(`.${h}`);
+    });
+}
+/**
+ * Inspect a page and return a verdict, or `null` when it does not look like a
+ * login wall.
+ *
+ * Confidence:
+ * - `high`: a password field plus a sign-in control, title, or URL; or a
+ *   sign-in URL plus a sign-in control or title; or an identity-provider host.
+ * - `medium`: exactly one weaker cue on its own (a password field, or a
+ *   sign-in URL) with nothing to corroborate it. Callers that fail a run on a
+ *   wall should usually require `high`.
+ *
+ * A lone "Sign in" link or a title mention never counts: most public pages have
+ * one in the header.
+ */
+function detectAuthWall(page) {
+    const signals = new Set();
+    const u = parseUrl(page.url);
+    if (u && LOGIN_PATH.test(u.pathname))
+        signals.add('login-url');
+    if (u && isIdpHost(u))
+        signals.add('identity-provider');
+    if (LOGIN_TITLE.test(page.title || ''))
+        signals.add('login-title');
+    let strongButton = false;
+    for (const n of page.nodes) {
+        if (n.secret === true || (n.tag === 'input' && n.role === 'textbox' && /password/i.test(n.name))) {
+            signals.add('password-field');
+            continue;
+        }
+        const label = (n.name || '').trim();
+        if (!label)
+            continue;
+        const clickable = n.role === 'button' || n.role === 'link' || n.tag === 'button';
+        if (clickable && LOGIN_BUTTON.test(label)) {
+            signals.add('login-button');
+            if (STRONG_BUTTON.test(label))
+                strongButton = true;
+        }
+        else if ((n.role === 'textbox' || n.role === 'combobox') && USERNAME_FIELD.test(label)) {
+            signals.add('username-field');
+        }
+    }
+    const has = (s) => signals.has(s);
+    const password = has('password-field');
+    const loginUrl = has('login-url');
+    const idp = has('identity-provider');
+    const title = has('login-title');
+    let confidence = null;
+    if (idp)
+        confidence = 'high';
+    else if (password && (strongButton || title || loginUrl || has('username-field')))
+        confidence = 'high';
+    else if (loginUrl && (strongButton || title || has('username-field')))
+        confidence = 'high';
+    else if (password || loginUrl)
+        confidence = 'medium';
+    if (!confidence)
+        return null;
+    const order = [
+        'password-field',
+        'identity-provider',
+        'login-url',
+        'login-title',
+        'login-button',
+        'username-field',
+    ];
+    return { detected: true, confidence, signals: order.filter(has) };
+}
+/** A one-line, human-readable explanation for error messages and logs. */
+function describeAuthWall(wall, url) {
+    return `the page at ${url} looks like a sign-in wall (${wall.confidence} confidence: ${wall.signals.join(', ')}); the session has probably expired`;
+}
+//# sourceMappingURL=auth-wall.js.map

package/dist/shared/page-fns.js

@@ -87,8 +87,6 @@ function pageOp(a) {
         return { dx, dy, exact: true, scrollX: win.scrollX, scrollY: win.scrollY };
     };
     const sel = typeof a.selector === 'string' && a.selector.length > 0 ? a.selector : null;
-    const el = sel ? deepQuery(sel) : null;
-    const missing = sel !== null && el === null;
     /** Set a value the way React/Vue see it (they patch the instance setter). */
     const setValue = (node, next) => {
         const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(node), 'value')?.set;
@@ -98,195 +96,223 @@ function pageOp(a) {
             node.value = next;
         node.dispatchEvent(new Event('input', { bubbles: true }));
     };
-    switch (a.op) {
-        case 'probe':
-            return { found: true, url: location.href, title: document.title };
-        case 'text': {
-            if (missing)
-                return { found: false };
-            const root = el ?? document.body;
-            return { found: true, text: root ? root.innerText ?? '' : '' };
-        }
-        case 'html': {
-            if (missing)
-                return { found: false };
-            const root = el ?? document.documentElement;
-            if (!root)
-                return { found: true, html: '' };
-            const outer = a.outer === true || !sel;
-            return { found: true, html: outer ? root.outerHTML : root.innerHTML };
-        }
-        case 'click': {
-            if (!el)
-                return { found: false };
-            el.scrollIntoView({ block: 'center' });
-            el.click();
-            return { found: true };
-        }
-        case 'type': {
-            const node = el;
-            if (!node)
-                return { found: false };
-            node.focus();
-            const next = (a.clear ? '' : node.value ?? '') + (a.text ?? '');
-            setValue(node, next);
-            node.dispatchEvent(new Event('change', { bubbles: true }));
-            return { found: true };
-        }
-        case 'focus': {
-            const node = el;
-            if (!node)
-                return { found: false };
-            node.focus();
-            if (a.clear)
-                setValue(node, '');
-            return { found: true };
-        }
-        case 'point': {
-            if (!el)
-                return { found: false };
-            el.scrollIntoView({ block: 'center', inline: 'center' });
-            const r = el.getBoundingClientRect();
-            const off = frameOffset();
-            return {
-                found: true,
-                x: r.left + r.width / 2 + off.dx,
-                y: r.top + r.height / 2 + off.dy,
-                // false => this frame's coordinates cannot be mapped to the top viewport.
-                exact: off.exact,
-            };
-        }
-        case 'hover': {
-            if (!el)
-                return { found: false };
-            el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
-            el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
-            return { found: true };
-        }
-        case 'select': {
-            const node = el;
-            if (!node || !node.options)
-                return { found: false };
-            const want = new Set(a.values ?? []);
-            let matched = false;
-            for (const opt of Array.from(node.options)) {
-                const on = want.has(opt.value) || want.has(opt.label) || want.has(opt.text);
-                opt.selected = on;
-                if (on)
-                    matched = true;
+    /** The op proper, against an element already resolved (or null). */
+    const perform = (el) => {
+        const missing = sel !== null && el === null;
+        switch (a.op) {
+            case 'probe':
+                return { found: true, url: location.href, title: document.title };
+            case 'text': {
+                if (missing)
+                    return { found: false };
+                const root = el ?? document.body;
+                return { found: true, text: root ? root.innerText ?? '' : '' };
             }
-            node.dispatchEvent(new Event('input', { bubbles: true }));
-            node.dispatchEvent(new Event('change', { bubbles: true }));
-            return { found: true, matched };
-        }
-        case 'measure': {
-            const d = document.documentElement;
-            const dims = {
-                w: window.innerWidth,
-                h: window.innerHeight,
-                fullW: Math.max(d.scrollWidth, d.clientWidth),
-                fullH: Math.max(d.scrollHeight, d.clientHeight),
-            };
-            if (!sel)
-                return { found: true, dims, element: null, missing: false };
-            if (!el)
-                return { found: true, dims, element: null, missing: true };
-            el.scrollIntoView({ block: 'center', inline: 'center' });
-            const r = el.getBoundingClientRect();
-            const off = frameOffset();
-            // viewport rect + this frame's offset + the TOP document's scroll ->
-            // document coordinates of the page the screenshot actually captures.
-            return {
-                found: true,
-                dims,
-                element: {
-                    x: r.left + off.dx + off.scrollX,
-                    y: r.top + off.dy + off.scrollY,
-                    w: r.width,
-                    h: r.height,
-                },
-                missing: false,
-                exact: off.exact,
-            };
-        }
-        case 'scroll': {
-            if (el)
-                el.scrollIntoView({ block: 'center' });
-            else if (a.x != null || a.y != null)
-                window.scrollTo(a.x ?? 0, a.y ?? 0);
-            else
-                window.scrollBy(a.deltaX ?? 0, a.deltaY ?? 0);
-            return { found: !missing };
-        }
-        case 'storage': {
-            const store = a.session ? window.sessionStorage : window.localStorage;
-            const op = a.storageOp;
-            if (op === 'set') {
-                store.setItem(String(a.key), String(a.value ?? ''));
-                return { found: true, ok: true };
+            case 'html': {
+                if (missing)
+                    return { found: false };
+                const root = el ?? document.documentElement;
+                if (!root)
+                    return { found: true, html: '' };
+                const outer = a.outer === true || !sel;
+                return { found: true, html: outer ? root.outerHTML : root.innerHTML };
             }
-            if (op === 'remove') {
-                store.removeItem(String(a.key));
-                return { found: true, ok: true };
+            case 'click': {
+                if (!el)
+                    return { found: false };
+                el.scrollIntoView({ block: 'center' });
+                el.click();
+                return { found: true };
             }
-            if (op === 'clear') {
-                store.clear();
-                return { found: true, ok: true };
+            case 'type': {
+                const node = el;
+                if (!node)
+                    return { found: false };
+                node.focus();
+                const next = (a.clear ? '' : node.value ?? '') + (a.text ?? '');
+                setValue(node, next);
+                node.dispatchEvent(new Event('change', { bubbles: true }));
+                return { found: true };
             }
-            if (a.key)
-                return { found: true, ok: true, value: store.getItem(a.key) };
-            const entries = {};
-            for (let i = 0; i < store.length; i++) {
-                const k = store.key(i);
-                if (k)
-                    entries[k] = store.getItem(k) ?? '';
+            case 'focus': {
+                const node = el;
+                if (!node)
+                    return { found: false };
+                node.focus();
+                if (a.clear)
+                    setValue(node, '');
+                return { found: true };
             }
-            return { found: true, ok: true, entries };
-        }
-        // -- the two polling ops: one injection that resolves in-page, rather than
-        //    one executeScript round-trip per tick --
-        case 'waitSelector': {
-            const deadline = Date.now() + (a.timeoutMs ?? 5_000);
-            const every = a.interval ?? 120;
-            return new Promise((resolve) => {
-                const tick = () => {
-                    if (sel && deepQuery(sel))
-                        return resolve({ found: true });
-                    if (Date.now() > deadline)
-                        return resolve({ found: false });
-                    setTimeout(tick, every);
+            case 'point': {
+                if (!el)
+                    return { found: false };
+                el.scrollIntoView({ block: 'center', inline: 'center' });
+                const r = el.getBoundingClientRect();
+                const off = frameOffset();
+                return {
+                    found: true,
+                    x: r.left + r.width / 2 + off.dx,
+                    y: r.top + r.height / 2 + off.dy,
+                    // false => this frame's coordinates cannot be mapped to the top viewport.
+                    exact: off.exact,
                 };
-                tick();
-            });
-        }
-        case 'waitFor': {
-            const deadline = Date.now() + (a.timeoutMs ?? 30_000);
-            const every = a.interval ?? 150;
-            const want = typeof a.textContains === 'string' && a.textContains.length > 0 ? a.textContains : null;
-            const gone = a.gone === true;
-            return new Promise((resolve) => {
-                const hit = () => {
-                    let present;
-                    if (sel)
-                        present = !!deepQuery(sel);
-                    else if (want)
-                        present = (document.body?.innerText ?? '').includes(want);
-                    else
-                        present = true;
-                    return gone ? !present : present;
+            }
+            case 'hover': {
+                if (!el)
+                    return { found: false };
+                el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+                el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+                return { found: true };
+            }
+            case 'select': {
+                const node = el;
+                if (!node || !node.options)
+                    return { found: false };
+                const want = new Set(a.values ?? []);
+                let matched = false;
+                for (const opt of Array.from(node.options)) {
+                    const on = want.has(opt.value) || want.has(opt.label) || want.has(opt.text);
+                    opt.selected = on;
+                    if (on)
+                        matched = true;
+                }
+                node.dispatchEvent(new Event('input', { bubbles: true }));
+                node.dispatchEvent(new Event('change', { bubbles: true }));
+                return { found: true, matched };
+            }
+            case 'measure': {
+                const d = document.documentElement;
+                const dims = {
+                    w: window.innerWidth,
+                    h: window.innerHeight,
+                    fullW: Math.max(d.scrollWidth, d.clientWidth),
+                    fullH: Math.max(d.scrollHeight, d.clientHeight),
+                    dpr: window.devicePixelRatio || 1,
+                    scrollX: window.scrollX,
+                    scrollY: window.scrollY,
                 };
-                const tick = () => {
-                    if (hit())
-                        return resolve({ found: true, matched: true });
-                    if (Date.now() > deadline)
-                        return resolve({ found: true, matched: false });
-                    setTimeout(tick, every);
+                if (!sel)
+                    return { found: true, dims, element: null, missing: false };
+                if (!el)
+                    return { found: true, dims, element: null, missing: true };
+                el.scrollIntoView({ block: 'center', inline: 'center' });
+                const r = el.getBoundingClientRect();
+                const off = frameOffset();
+                // viewport rect + this frame's offset + the TOP document's scroll ->
+                // document coordinates of the page the screenshot actually captures.
+                return {
+                    found: true,
+                    dims,
+                    element: {
+                        x: r.left + off.dx + off.scrollX,
+                        y: r.top + off.dy + off.scrollY,
+                        w: r.width,
+                        h: r.height,
+                    },
+                    missing: false,
+                    exact: off.exact,
                 };
-                tick();
-            });
+            }
+            case 'scroll': {
+                if (el)
+                    el.scrollIntoView({ block: 'center' });
+                else if (a.x != null || a.y != null)
+                    window.scrollTo(a.x ?? 0, a.y ?? 0);
+                else
+                    window.scrollBy(a.deltaX ?? 0, a.deltaY ?? 0);
+                return { found: !missing };
+            }
+            case 'storage': {
+                const store = a.session ? window.sessionStorage : window.localStorage;
+                const op = a.storageOp;
+                if (op === 'set') {
+                    store.setItem(String(a.key), String(a.value ?? ''));
+                    return { found: true, ok: true };
+                }
+                if (op === 'remove') {
+                    store.removeItem(String(a.key));
+                    return { found: true, ok: true };
+                }
+                if (op === 'clear') {
+                    store.clear();
+                    return { found: true, ok: true };
+                }
+                if (a.key)
+                    return { found: true, ok: true, value: store.getItem(a.key) };
+                const entries = {};
+                for (let i = 0; i < store.length; i++) {
+                    const k = store.key(i);
+                    if (k)
+                        entries[k] = store.getItem(k) ?? '';
+                }
+                return { found: true, ok: true, entries };
+            }
+            // -- the two polling ops: one injection that resolves in-page, rather than
+            //    one executeScript round-trip per tick --
+            case 'waitSelector': {
+                const deadline = Date.now() + (a.timeoutMs ?? 5_000);
+                const every = a.interval ?? 120;
+                return new Promise((resolve) => {
+                    const tick = () => {
+                        if (sel && deepQuery(sel))
+                            return resolve({ found: true });
+                        if (Date.now() > deadline)
+                            return resolve({ found: false });
+                        setTimeout(tick, every);
+                    };
+                    tick();
+                });
+            }
+            case 'waitFor': {
+                const deadline = Date.now() + (a.timeoutMs ?? 30_000);
+                const every = a.interval ?? 150;
+                const want = typeof a.textContains === 'string' && a.textContains.length > 0 ? a.textContains : null;
+                const gone = a.gone === true;
+                return new Promise((resolve) => {
+                    const hit = () => {
+                        let present;
+                        if (sel)
+                            present = !!deepQuery(sel);
+                        else if (want)
+                            present = (document.body?.innerText ?? '').includes(want);
+                        else
+                            present = true;
+                        return gone ? !present : present;
+                    };
+                    const tick = () => {
+                        if (hit())
+                            return resolve({ found: true, matched: true });
+                        if (Date.now() > deadline)
+                            return resolve({ found: true, matched: false });
+                        setTimeout(tick, every);
+                    };
+                    tick();
+                });
+            }
+            default:
+                return { found: false, error: `unknown page op: ${String(a.op)}` };
         }
-        default:
-            return { found: false, error: `unknown page op: ${String(a.op)}` };
+    };
+    const el = sel ? deepQuery(sel) : null;
+    // Element ops wait for their target IN THIS SAME injection when `timeoutMs`
+    // is set: a not-yet-rendered button costs a few in-page ticks, not a second
+    // executeScript round-trip (the old waitSelector-then-act pair).
+    const waits = a.op === 'click' || a.op === 'type' || a.op === 'focus' || a.op === 'point' || a.op === 'hover' || a.op === 'select';
+    if (waits && sel && !el && a.timeoutMs && a.timeoutMs > 0) {
+        const deadline = Date.now() + a.timeoutMs;
+        const every = a.interval ?? 120;
+        return new Promise((resolve) => {
+            const tick = () => {
+                const hit = deepQuery(sel);
+                if (hit)
+                    return resolve(perform(hit));
+                if (Date.now() > deadline)
+                    return resolve({ found: false });
+                setTimeout(tick, every);
+            };
+            setTimeout(tick, every);
+        });
     }
+    return perform(el);
 }
 //# sourceMappingURL=page-fns.js.map