@jobshimo/browser-link 0.15.0 → 0.17.0

package/dist/agent-instructions/content.js

@@ -77,6 +77,16 @@ function body() {
         '`browser.evaluate` is the escape hatch. Every dedicated tool below is',
         'cheaper in tokens AND more reliable than a hand-rolled expression.',
         '',
+        '- Any multi-step interaction (find a target → act on it → wait → act',
+        '  again) → `browser.flow({ steps: [...] })` is now the DEFAULT, not a',
+        '  fallback. find → click → wait_for → type → press used to cost 5+',
+        '  separate MCP round trips — each one a full LLM inference — and now',
+        '  costs ONE `browser.flow` call (two if a step fails and you need a',
+        "  corrective follow-up). A `find` step's selector becomes the implicit",
+        '  target for the very next click/type/press step that omits',
+        '  `selector`. Flow is strictly sequential and fails fast — reach for',
+        '  individual click/type/press/find/wait_for calls only when you need',
+        '  to branch on an intermediate result.',
         '- Finding an element by visible text → `browser.find({ text, role? })`,',
         '  NOT `browser.evaluate` with a `textContent` grep. `find` covers',
         '  `<div onclick>` (which a naive `querySelectorAll("button")` MISSES',
@@ -103,11 +113,23 @@ function body() {
         '  Never N separate evaluates for N reads.',
         '- Scrolling → `browser.evaluate` with `pane.scrollTop = N` or',
         '  `el.scrollIntoView({ block: "center" })`. No dedicated tool needed.',
-        '- Special keys (Enter/Tab/Escape/arrows) → `browser.evaluate` with',
-        '  `el.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }))`.',
-        '  Vanilla AND React-delegated handlers (React 17+ root delegation)',
-        '  pick up bubbled dispatched events. For TYPING text → `browser.type`',
-        '  (native setter; controlled components update their state).',
+        '- Special keys (Enter/Tab/Escape/arrows/shortcuts) → `browser.press`,',
+        '  NOT `browser.evaluate` with a synthetic `KeyboardEvent`. Synthetic',
+        '  `dispatchEvent` produces `isTrusted:false` events — rich editors,',
+        '  autocompletes, and non-DOM runtimes (Qt-WASM, WebGL) silently ignore',
+        '  them. `browser.press` dispatches a real CDP `Input.dispatchKeyEvent`',
+        '  sequence (`isTrusted:true`). For TYPING text → `browser.type` (native',
+        '  setter; controlled components update their state).',
+        '- After `click`/`type`/`press`, a separate `browser.wait_for` is',
+        '  usually unnecessary — all three accept `settle_ms` (default 150) and',
+        '  return a `settle` object (`{ settled, duration_ms, mutation_count,',
+        '  url_changed?, focus_moved? }`) once the page goes quiet. Settle',
+        '  proves QUIET, not EFFECT: mutations completing before the observer',
+        '  installs (right after dispatch) and async reactions starting after',
+        '  the quiet window are both invisible — `mutation_count: 0` does NOT',
+        '  mean the action did nothing. Reach for `wait_for` when you need a',
+        '  SPECIFIC condition (a particular selector, network request, or',
+        '  expression), not just "did anything change".',
         '- Paging `browser.events` → keep `lastId = result.latest_id` in your',
         '  working notes and pass as `since_id` next call. One variable. The',
         '  server does not maintain per-agent cursors.',

package/dist/agent-instructions/content.js.map

@@ -1 +1 @@
-{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/agent-instructions/content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/agent-instructions/content.ts"],"names":[],"mappings":"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"}

package/dist/commands/about.js

@@ -45,6 +45,8 @@ export const I18N_ABOUT = {
             '  browser.navigate         change the tab URL',
             '  browser.click            click an element by CSS selector',
             '  browser.type             type into an input',
+            '  browser.press            press a key (trusted CDP input, not synthetic)',
+            '  browser.flow             run a find/click/type/press/wait_for sequence in one call',
             '  browser.evaluate         run JavaScript in the page context',
             '  browser.console          recent console messages (rolling 200)',
             '  browser.network          recent network requests (rolling 200)',
@@ -141,6 +143,8 @@ export const I18N_ABOUT = {
             '  browser.navigate         cambiar la URL de la pestaña',
             '  browser.click            hacer click en un elemento por CSS selector',
             '  browser.type             escribir en un input',
+            '  browser.press            presionar una tecla (input CDP confiable, no sintético)',
+            '  browser.flow             encadenar find/click/type/press/wait_for en una sola llamada',
             '  browser.evaluate         ejecutar JavaScript en el contexto de la página',
             '  browser.console          mensajes recientes de consola (200 últimos)',
             '  browser.network          peticiones de red recientes (200 últimas)',

package/dist/commands/about.js.map

@@ -1 +1 @@
-{"version":3,"file":"about.js","sourceRoot":"","sources":["../../src/commands/about.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"about.js","sourceRoot":"","sources":["../../src/commands/about.ts"],"names":[],"mappings":"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"}

package/dist/extension/background.js

@@ -1,4 +1,7 @@
-import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs, } from './inpage/builders.js';
+import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs, buildFocusJs, } from './inpage/builders.js';
+import { buildKeyEventSequence, resolveKey, modifiersToBitmask, MODIFIER_BITS, } from './keymap.js';
+import { resolveSettleParams, settleSafely } from './settle.js';
+import { runFlow, } from './flow.js';
 const WS_URL = 'ws://127.0.0.1:17529';
 const CDP_VERSION = '1.3';
 const CONSOLE_BUFFER_MAX = 200;
@@ -106,6 +109,28 @@ function sleep(ms) {
         }
     });
 }
+/** Run the shared post-action settle wait for a tab. Thin closure binder
+ * over `settleSafely` (see settle.ts) — which is guaranteed not to throw,
+ * so an action that navigated the page (destroying the settle expression's
+ * execution context) still returns ok:true with a degraded settle object
+ * instead of flipping the whole response to ok:false. */
+function runSettle(tabId, settle) {
+    return settleSafely((expression) => evaluateInTab(tabId, expression), settle);
+}
+/**
+ * Dispatch the CDP `Input.dispatchKeyEvent` sequence for one resolved key.
+ * The event shapes come from `buildKeyEventSequence` (keymap.ts) — pure and
+ * unit-tested there; this wrapper only feeds them to chrome.debugger. This
+ * is the ONLY path in this extension that produces `isTrusted: true`
+ * keyboard events — see browser.press's doc block for why that matters
+ * (Qt-WASM and similar runtimes discard synthetic KeyboardEvents dispatched
+ * via browser.evaluate).
+ */
+async function dispatchKeyEvent(tabId, def, modifiers) {
+    for (const event of buildKeyEventSequence(def, modifiers)) {
+        await cdp(tabId, 'Input.dispatchKeyEvent', event);
+    }
+}
 /**
  * Wait for ONE CDP event of a given method on a given tab. Adds a temporary
  * chrome.debugger.onEvent listener for the duration of the wait. Resolves
@@ -504,6 +529,233 @@ async function waitForLoad(tabId, timeoutMs = 20_000) {
         chrome.tabs.onUpdated.addListener(handler);
     });
 }
+/**
+ * `performFind` / `performClick` / `performType` / `performPress` /
+ * `performWaitFor` — the extracted bodies of the standalone `find` /
+ * `click` / `type` / `press` / `wait_for` cases in `handleTool` below.
+ *
+ * Both the standalone `case` handlers AND `browser.flow`'s step executor
+ * (`runFlow` in `./flow.js`) call these exact functions — there is one
+ * implementation of each action, never a copy that can drift. Each
+ * returns an `ActionOutcome<T>` (`{ok:true,result} | {ok:false,error}`)
+ * instead of a wire-level `tool.response`, so the two call sites can
+ * unwrap it however they need to (the standalone case wraps it straight
+ * into a `tool.response`; `runFlow` inspects `result` for its own
+ * fail-fast rules — e.g. `wait_for`'s `matched:false` is `ok:true` here,
+ * matching the standalone tool's contract, and it is `runFlow`, not this
+ * function, that decides a non-match should stop the flow).
+ *
+ * `performType`'s `selector` is optional here (the standalone tool's JSON
+ * schema still requires it, so that path never changes): when omitted,
+ * this skips element resolution entirely and types into whatever
+ * currently has focus, mirroring how `performPress` already behaves with
+ * no `selector`. That is what lets a `browser.flow` step continue typing
+ * into a freshly-appeared, auto-focused input (e.g. a search box that
+ * opened after a preceding click) without a selector for it.
+ */
+async function performFind(tabId, params) {
+    try {
+        const { text } = params;
+        if (!text)
+            return { ok: false, error: 'find: text required' };
+        const value = await evaluateInTab(tabId, buildFindJs({ text, role: params.role, exact: params.exact === true }));
+        return { ok: true, result: value };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function performClick(tabId, params) {
+    try {
+        const { selector, force = false } = params;
+        const settle = resolveSettleParams({
+            settle_ms: params.settle_ms,
+            settle_timeout_ms: params.settle_timeout_ms,
+        });
+        const resolved = await evaluateInTab(tabId, buildClickResolveJs({ selector, force }));
+        if (!resolved.ok) {
+            if (resolved.reason === 'occluded') {
+                return {
+                    ok: false,
+                    error: `Element covered by ${resolved.blocker} — click the covering element or dismiss it first`,
+                };
+            }
+            return { ok: false, error: `Element not found: ${selector}` };
+        }
+        await cdp(tabId, 'Input.dispatchMouseEvent', {
+            type: 'mouseMoved',
+            x: resolved.x,
+            y: resolved.y,
+        });
+        await cdp(tabId, 'Input.dispatchMouseEvent', {
+            type: 'mousePressed',
+            x: resolved.x,
+            y: resolved.y,
+            button: 'left',
+            clickCount: 1,
+        });
+        await cdp(tabId, 'Input.dispatchMouseEvent', {
+            type: 'mouseReleased',
+            x: resolved.x,
+            y: resolved.y,
+            button: 'left',
+            clickCount: 1,
+        });
+        const settleResult = await runSettle(tabId, settle);
+        const result = { clicked: selector, tag: resolved.tag };
+        if (settleResult)
+            result.settle = settleResult;
+        return { ok: true, result };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function performType(tabId, params) {
+    try {
+        const { selector, text, clear = false } = params;
+        const settle = resolveSettleParams({
+            settle_ms: params.settle_ms,
+            settle_timeout_ms: params.settle_timeout_ms,
+        });
+        if (selector !== undefined) {
+            const focused = await evaluateInTab(tabId, buildTypeResolveJs({ selector, clear }));
+            if (!focused) {
+                return { ok: false, error: `Element not found: ${selector}` };
+            }
+        }
+        await cdp(tabId, 'Input.insertText', { text });
+        const settleResult = await runSettle(tabId, settle);
+        const result = { typed: text.length };
+        if (selector !== undefined)
+            result.selector = selector;
+        if (settleResult)
+            result.settle = settleResult;
+        return { ok: true, result };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function performPress(tabId, params) {
+    try {
+        const key = params.key;
+        if (!key)
+            return { ok: false, error: 'press: key required' };
+        const def = resolveKey(key);
+        if (!def)
+            return { ok: false, error: `press: unrecognized key "${key}"` };
+        const modifierNames = params.modifiers ?? [];
+        const modifiers = modifiersToBitmask(modifierNames) | (def.needsShift ? MODIFIER_BITS.Shift : 0);
+        const settle = resolveSettleParams({
+            settle_ms: params.settle_ms,
+            settle_timeout_ms: params.settle_timeout_ms,
+        });
+        if (params.selector) {
+            const focused = await evaluateInTab(tabId, buildFocusJs({ selector: params.selector }));
+            if (!focused) {
+                return { ok: false, error: `Element not found: ${params.selector}` };
+            }
+        }
+        await dispatchKeyEvent(tabId, def, modifiers);
+        const settleResult = await runSettle(tabId, settle);
+        const result = { key, modifiers: modifierNames };
+        if (settleResult)
+            result.settle = settleResult;
+        return { ok: true, result };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+async function performWaitFor(tabId, state, params) {
+    try {
+        const waitSelector = params.selector;
+        const waitExpression = params.expression;
+        const waitNetworkUrl = params.network_url;
+        const waitCondition = params.condition ?? 'visible';
+        // Defensive caps mirror the dispatcher's contract and keep CodeQL
+        // happy about setTimeout durations driven by request params.
+        const MAX_WAIT_TIMEOUT_MS = 30_000;
+        const MIN_POLL_MS = 50;
+        const MAX_POLL_MS = 1_000;
+        const requestedTimeout = params.timeout_ms ?? 5_000;
+        const timeoutMs = requestedTimeout < MAX_WAIT_TIMEOUT_MS ? requestedTimeout : MAX_WAIT_TIMEOUT_MS;
+        const requestedPoll = params.poll_interval_ms ?? 100;
+        const pollIntervalMs = requestedPoll < MIN_POLL_MS
+            ? MIN_POLL_MS
+            : requestedPoll > MAX_POLL_MS
+                ? MAX_POLL_MS
+                : requestedPoll;
+        // Build the check function based on which mode the caller picked. The
+        // dispatcher already enforced "exactly one of selector / expression /
+        // network_url" so we just pick the first defined one. If none are
+        // defined (shouldn't happen from a well-formed call), the check stays
+        // null and we return matched=false immediately.
+        let check = null;
+        if (waitSelector !== undefined) {
+            const expr = buildWaitSelectorExpr(waitSelector, waitCondition);
+            check = async () => {
+                try {
+                    const result = await evaluateInTab(tabId, expr);
+                    return Boolean(result);
+                }
+                catch {
+                    // If the page is unreachable mid-poll, count as "not yet matched".
+                    return false;
+                }
+            };
+        }
+        else if (waitExpression !== undefined) {
+            const wrapped = `Boolean(${waitExpression})`;
+            check = async () => {
+                try {
+                    const result = await evaluateInTab(tabId, wrapped);
+                    return Boolean(result);
+                }
+                catch {
+                    return false;
+                }
+            };
+        }
+        else if (waitNetworkUrl !== undefined) {
+            const needle = waitNetworkUrl.toLowerCase();
+            check = () => {
+                for (const id of state.networkOrder) {
+                    const r = state.networkBuffer.get(id);
+                    if (!r)
+                        continue;
+                    if (r.finished_at === undefined)
+                        continue;
+                    if (r.url.toLowerCase().includes(needle))
+                        return Promise.resolve(true);
+                }
+                return Promise.resolve(false);
+            };
+        }
+        const startedAt = Date.now();
+        let checks = 0;
+        let matched = false;
+        while (check) {
+            checks++;
+            if (await check()) {
+                matched = true;
+                break;
+            }
+            if (Date.now() - startedAt >= timeoutMs)
+                break;
+            await sleep(pollIntervalMs);
+        }
+        const elapsedMs = Date.now() - startedAt;
+        const result = matched
+            ? { matched: true, elapsed_ms: elapsedMs, checks }
+            : { matched: false, elapsed_ms: elapsedMs, checks, reason: 'timeout' };
+        return { ok: true, result };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
 async function handleTool(state, msg) {
     const tabId = state.tabId;
     // Params come over the wire as JSON: each field is unknown until we
@@ -549,21 +801,15 @@ async function handleTool(state, msg) {
                 return { kind: 'tool.response', id: msg.id, ok: true, result: value };
             }
             case 'find': {
-                const text = str('text');
-                if (!text) {
-                    return {
-                        kind: 'tool.response',
-                        id: msg.id,
-                        ok: false,
-                        error: 'find: text required',
-                    };
-                }
-                const value = await evaluateInTab(tabId, buildFindJs({
-                    text,
+                const outcome = await performFind(tabId, {
+                    text: str('text'),
                     role: optStr('role'),
                     exact: p.exact === true,
-                }));
-                return { kind: 'tool.response', id: msg.id, ok: true, result: value };
+                });
+                if (!outcome.ok) {
+                    return { kind: 'tool.response', id: msg.id, ok: false, error: outcome.error };
+                }
+                return { kind: 'tool.response', id: msg.id, ok: true, result: outcome.result };
             }
             case 'canvas_screenshot': {
                 const selector = optStr('selector');
@@ -605,71 +851,67 @@ async function handleTool(state, msg) {
                 return { kind: 'tool.response', id: msg.id, ok: true, result: body };
             }
             case 'click': {
-                const selector = str('selector');
-                const force = p.force === true;
-                const resolved = await evaluateInTab(tabId, buildClickResolveJs({ selector, force }));
-                if (!resolved.ok) {
-                    if (resolved.reason === 'occluded') {
-                        return {
-                            kind: 'tool.response',
-                            id: msg.id,
-                            ok: false,
-                            error: `Element covered by ${resolved.blocker} — click the covering element or dismiss it first`,
-                        };
-                    }
-                    return {
-                        kind: 'tool.response',
-                        id: msg.id,
-                        ok: false,
-                        error: `Element not found: ${selector}`,
-                    };
-                }
-                await cdp(tabId, 'Input.dispatchMouseEvent', {
-                    type: 'mouseMoved',
-                    x: resolved.x,
-                    y: resolved.y,
+                const outcome = await performClick(tabId, {
+                    selector: str('selector'),
+                    force: p.force === true,
+                    settle_ms: typeof p.settle_ms === 'number' ? p.settle_ms : undefined,
+                    settle_timeout_ms: typeof p.settle_timeout_ms === 'number' ? p.settle_timeout_ms : undefined,
                 });
-                await cdp(tabId, 'Input.dispatchMouseEvent', {
-                    type: 'mousePressed',
-                    x: resolved.x,
-                    y: resolved.y,
-                    button: 'left',
-                    clickCount: 1,
-                });
-                await cdp(tabId, 'Input.dispatchMouseEvent', {
-                    type: 'mouseReleased',
-                    x: resolved.x,
-                    y: resolved.y,
-                    button: 'left',
-                    clickCount: 1,
-                });
-                return {
-                    kind: 'tool.response',
-                    id: msg.id,
-                    ok: true,
-                    result: { clicked: selector, tag: resolved.tag },
-                };
+                if (!outcome.ok) {
+                    return { kind: 'tool.response', id: msg.id, ok: false, error: outcome.error };
+                }
+                return { kind: 'tool.response', id: msg.id, ok: true, result: outcome.result };
             }
             case 'type': {
-                const selector = str('selector');
-                const text = str('text');
-                const clear = p.clear === true;
-                const focused = await evaluateInTab(tabId, buildTypeResolveJs({ selector, clear }));
-                if (!focused) {
-                    return {
-                        kind: 'tool.response',
-                        id: msg.id,
-                        ok: false,
-                        error: `Element not found: ${selector}`,
-                    };
+                const outcome = await performType(tabId, {
+                    selector: str('selector'),
+                    text: str('text'),
+                    clear: p.clear === true,
+                    settle_ms: typeof p.settle_ms === 'number' ? p.settle_ms : undefined,
+                    settle_timeout_ms: typeof p.settle_timeout_ms === 'number' ? p.settle_timeout_ms : undefined,
+                });
+                if (!outcome.ok) {
+                    return { kind: 'tool.response', id: msg.id, ok: false, error: outcome.error };
                 }
-                await cdp(tabId, 'Input.insertText', { text });
-                return {
-                    kind: 'tool.response',
-                    id: msg.id,
-                    ok: true,
-                    result: { typed: text.length, selector },
-                };
+                return { kind: 'tool.response', id: msg.id, ok: true, result: outcome.result };
+            }
+            case 'press': {
+                const modifierNames = Array.isArray(p.modifiers)
+                    ? p.modifiers.filter((m) => typeof m === 'string')
+                    : [];
+                const outcome = await performPress(tabId, {
+                    key: optStr('key'),
+                    modifiers: modifierNames,
+                    selector: optStr('selector'),
+                    settle_ms: typeof p.settle_ms === 'number' ? p.settle_ms : undefined,
+                    settle_timeout_ms: typeof p.settle_timeout_ms === 'number' ? p.settle_timeout_ms : undefined,
+                });
+                if (!outcome.ok) {
+                    return { kind: 'tool.response', id: msg.id, ok: false, error: outcome.error };
+                }
+                return { kind: 'tool.response', id: msg.id, ok: true, result: outcome.result };
+            }
+            case 'flow': {
+                // Wire-boundary narrowing: `p.steps` is untrusted JSON. Keep only
+                // object-shaped entries here — `runFlow`'s own `stepKind()` guard
+                // re-validates each one at runtime regardless, so a malformed
+                // entry fails the flow cleanly instead of throwing.
+                const rawSteps = Array.isArray(p.steps)
+                    ? p.steps.filter((s) => typeof s === 'object' && s !== null)
+                    : [];
+                const flowResult = await runFlow(rawSteps, {
+                    performFind: (params) => performFind(tabId, params),
+                    performClick: (params) => performClick(tabId, params),
+                    performType: (params) => performType(tabId, params),
+                    performPress: (params) => performPress(tabId, params),
+                    performWaitFor: (params) => performWaitFor(tabId, state, params),
+                    buildRecoverySnapshot: () => evaluateInTab(tabId, buildSnapshotJs({ only_interactive: true, max_interactive: 40 })),
+                });
+                // The wire-level response is ok:true whenever the flow RAN (even a
+                // failed step is a legitimate business outcome, same pattern as
+                // wait_for's matched:false) — flowResult itself carries the
+                // ok:true/false the agent reads.
+                return { kind: 'tool.response', id: msg.id, ok: true, result: flowResult };
             }
             case 'drag': {
                 const optNum = (key) => {
@@ -957,95 +1199,18 @@ async function handleTool(state, msg) {
                 return { kind: 'tool.response', id: msg.id, ok: true, result: value };
             }
             case 'wait_for': {
-                const optNum = (key) => {
-                    const v = p[key];
-                    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
-                };
-                const waitSelector = optStr('selector');
-                const waitExpression = optStr('expression');
-                const waitNetworkUrl = optStr('network_url');
-                const waitCondition = optStr('condition') ?? 'visible';
-                // Defensive caps mirror the dispatcher's contract and keep CodeQL
-                // happy about setTimeout durations driven by request params.
-                const MAX_WAIT_TIMEOUT_MS = 30_000;
-                const MIN_POLL_MS = 50;
-                const MAX_POLL_MS = 1_000;
-                const requestedTimeout = optNum('timeout_ms') ?? 5_000;
-                const timeoutMs = requestedTimeout < MAX_WAIT_TIMEOUT_MS ? requestedTimeout : MAX_WAIT_TIMEOUT_MS;
-                const requestedPoll = optNum('poll_interval_ms') ?? 100;
-                const pollIntervalMs = requestedPoll < MIN_POLL_MS
-                    ? MIN_POLL_MS
-                    : requestedPoll > MAX_POLL_MS
-                        ? MAX_POLL_MS
-                        : requestedPoll;
-                // Build the check function based on which mode the caller picked.
-                // The dispatcher already enforced "exactly one of selector / expression
-                // / network_url" so we just pick the first defined one. If none are
-                // defined (shouldn't happen from a well-formed call), the check stays
-                // null and we return matched=false immediately.
-                let check = null;
-                if (waitSelector !== undefined) {
-                    const expr = buildWaitSelectorExpr(waitSelector, waitCondition);
-                    check = async () => {
-                        try {
-                            const result = await evaluateInTab(tabId, expr);
-                            return Boolean(result);
-                        }
-                        catch {
-                            // If the page is unreachable mid-poll, count as "not yet matched".
-                            return false;
-                        }
-                    };
-                }
-                else if (waitExpression !== undefined) {
-                    const wrapped = `Boolean(${waitExpression})`;
-                    check = async () => {
-                        try {
-                            const result = await evaluateInTab(tabId, wrapped);
-                            return Boolean(result);
-                        }
-                        catch {
-                            return false;
-                        }
-                    };
-                }
-                else if (waitNetworkUrl !== undefined) {
-                    const needle = waitNetworkUrl.toLowerCase();
-                    check = () => {
-                        for (const id of state.networkOrder) {
-                            const r = state.networkBuffer.get(id);
-                            if (!r)
-                                continue;
-                            if (r.finished_at === undefined)
-                                continue;
-                            if (r.url.toLowerCase().includes(needle))
-                                return Promise.resolve(true);
-                        }
-                        return Promise.resolve(false);
-                    };
-                }
-                const startedAt = Date.now();
-                let checks = 0;
-                let matched = false;
-                while (check) {
-                    checks++;
-                    if (await check()) {
-                        matched = true;
-                        break;
-                    }
-                    if (Date.now() - startedAt >= timeoutMs)
-                        break;
-                    await sleep(pollIntervalMs);
+                const outcome = await performWaitFor(tabId, state, {
+                    selector: optStr('selector'),
+                    expression: optStr('expression'),
+                    network_url: optStr('network_url'),
+                    condition: optStr('condition'),
+                    timeout_ms: typeof p.timeout_ms === 'number' ? p.timeout_ms : undefined,
+                    poll_interval_ms: typeof p.poll_interval_ms === 'number' ? p.poll_interval_ms : undefined,
+                });
+                if (!outcome.ok) {
+                    return { kind: 'tool.response', id: msg.id, ok: false, error: outcome.error };
                 }
-                const elapsedMs = Date.now() - startedAt;
-                return {
-                    kind: 'tool.response',
-                    id: msg.id,
-                    ok: true,
-                    result: matched
-                        ? { matched: true, elapsed_ms: elapsedMs, checks }
-                        : { matched: false, elapsed_ms: elapsedMs, checks, reason: 'timeout' },
-                };
+                return { kind: 'tool.response', id: msg.id, ok: true, result: outcome.result };
             }
             case 'dialog_respond': {
                 const accept = p.accept === true;