@melra/browser-runtime 0.3.0-alpha.11 → 0.3.0-alpha.13

package/dist/index.js

@@ -4,6 +4,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { access, mkdir, readFile, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { outcomeUnknown } from "@melra/protocol";
+import { bounded, BrowserCallTimeoutError } from "./bounded.js";
 import { connectBrowser, } from "./browser-connection.js";
 import { assertSafeUrl, } from "@melra/policy-core";
 import { startPinningProxy } from "./pinning-proxy.js";
@@ -33,6 +35,24 @@ const MAX_DIALOGS = 20;
 const MAX_POPUPS = 20;
 /** How often `waitForTarget` re-resolves the target across the frame list. */
 const WAIT_POLL_MS = 100;
+/**
+ * How often `awaitOpenedWindows` rechecks while a window it knows about is
+ * still unreported. Only ever spent when a window is actually pending.
+ */
+const WINDOW_POLL_MS = 25;
+/**
+ * Bound on the one-time wiring of a fresh context: the destination guard, HAR
+ * replay, and the target-tracking session. Not the action's `timeoutMs`,
+ * because loading a large replay archive is legitimately slower than a 100ms
+ * action deadline, and this runs once per context rather than per action.
+ */
+const SETUP_TIMEOUT_MS = 30_000;
+/**
+ * Bound on each teardown call in `close()`. Shutdown has no action to take a
+ * deadline from, and a browser that stopped answering must not keep the server
+ * from exiting.
+ */
+const CLOSE_TIMEOUT_MS = 10_000;
 /**
  * Frame URLs of the widgets that gate a page behind a human check.
  *
@@ -71,6 +91,48 @@ export function captchaReport(frameUrls) {
         },
     };
 }
+/**
+ * Whether a Playwright action failed after its input had already been sent.
+ *
+ * A click's own timeout covers more than waiting for the element: after the
+ * mouse events go out, Playwright still asks the page to stop its hit-target
+ * check. When the click handler stalls the page, that request is what times
+ * out — with the click already delivered. Playwright logs `performing <name>
+ * action` immediately before dispatching, and the call log is part of the
+ * error, so that line is Playwright's own record that the input left. Keyboard,
+ * fill, select, and upload calls log no such line; their timeouts stay plain
+ * failures, which for them is overwhelmingly a field that never became ready.
+ *
+ * Playwright paints the call log dim when colour is on (a TTY, FORCE_COLOR),
+ * so each line can end in an escape code; those are stripped first. Without
+ * that, a click delivered under colour read as never sent: a plain failure
+ * where the outcome was unknown, seen first on the Windows CI runners.
+ */
+export function inputSent(error) {
+    return error instanceof Error && /^\s*- performing .+ action$/m.test(withoutColour(error.message));
+}
+/**
+ * A URL as policy names a browser target, without query or fragment. Chrome
+ * escapes two path characters Node's URL can keep raw: `|` on every Node, `^`
+ * on Node 22. Both are escaped on both sides. Nothing is decoded: no two paths
+ * a server tells apart compare equal, and no escape becomes a raw character in
+ * a message. Exported for unit testing.
+ */
+export function pageAddress(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString().replaceAll("|", "%7C").replaceAll("^", "%5E");
+    }
+    catch {
+        return url;
+    }
+}
+/** Playwright's terminal colour codes, which mean nothing in a stored record. */
+function withoutColour(text) {
+    return text.replace(/\u001b\[[0-9;]*m/g, "");
+}
 /**
  * Collect the readable text and addressable elements of one frame.
  *
@@ -156,13 +218,20 @@ export class BrowserRuntime {
     proxy;
     routeHandler;
     /**
-     * Dialogs raised by the action currently running, cleared by `execute`.
+     * Dialogs raised since the last action reported, emptied when one does.
      *
      * One buffer on the runtime rather than one per page because the handler is
-     * registered on the context, and because operations execute one at a time —
-     * a task owns its runtime for the length of one action.
+     * registered on the context, and because operations execute one at a time:
+     * `execute` queues them, so a task owns its runtime for one action. A dialog
+     * a page raised between actions is reported by the next one, marked
+     * `betweenActions`, rather than dropped: the transfer a late `confirm()`
+     * gated still went ahead, and the caller has to hear that it was asked.
      */
     dialogs = [];
+    /** Whether an action is running, so a dialog or popup can say when it came. */
+    acting = false;
+    /** The tail of the action queue; see `execute`. */
+    queue = Promise.resolve();
     /**
      * Windows the page opened during the action currently running, same lifetime
      * as `dialogs` and reported the same way.
@@ -172,9 +241,47 @@ export class BrowserRuntime {
     closing = [];
     /** True only while `tab_new` is opening the tab the caller asked for. */
     openingTab = false;
+    /**
+     * Browser-level session that hears about a new window the moment Chromium
+     * creates it, which is what lets an action wait for a popup it knows exists
+     * instead of guessing how long one might take. Absent if the browser would
+     * not grant one; popups are then reported on Playwright's timing alone.
+     */
+    targets;
+    /** Windows Chromium has created since tracking began, by browser context. */
+    windowsCreated = new Map();
+    /** Windows Playwright has handed to the `page` handler, popup or not. */
+    windowsAdopted = 0;
+    /** This context's id in CDP, resolved on first use and then fixed. */
+    contextId;
+    /**
+     * The running action's cancel signal and `timeoutMs`, read by `call`. Same
+     * per-action lifetime as `dialogs`, set by `execute`.
+     */
+    signal;
+    callMs = 30_000;
+    /**
+     * Set once the running action's effect call has returned. From then on the
+     * page may have acted on it, so a failure is no longer evidence that nothing
+     * happened — see `execute`.
+     */
+    dispatched = false;
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Bound a Playwright call that takes no timeout of its own by the running
+     * action's `timeoutMs` and cancel signal.
+     *
+     * `title()`, `evaluate()`, `count()`, `isVisible()`, `close()` and CDP
+     * `send` all wait for the renderer or the browser to answer, and one that
+     * stopped answering held the action until the task budget ran out — or
+     * forever, where nothing armed one. Failing with `browser_call_timeout:<what>`
+     * instead spends the budget on something that can still answer.
+     */
+    call(promise, what, ms = this.callMs) {
+        return bounded(promise, ms, what, this.signal);
+    }
     async uploadPaths(paths) {
         const root = await realpath(this.options.workspaceRoot);
         const resolved = [];
@@ -232,6 +339,10 @@ export class BrowserRuntime {
         // start proxying, so the rebinding window stays open there and the option is
         // documented as the weaker path rather than silently equivalent. A replay
         // opens no sockets at all, so there is nothing to pin.
+        // A context that closed (a crash, a closed window) or failed to start left
+        // its proxy listening; a relaunch must not start a second one beside it.
+        await this.proxy?.close().catch(() => undefined);
+        this.proxy = undefined;
         const proxy = this.options.unhinged === true ||
             this.options.cdpEndpoint !== undefined ||
             this.options.replayHarPath !== undefined
@@ -276,16 +387,39 @@ export class BrowserRuntime {
                 await route.abort("blockedbyclient");
             }
         };
-        await this.context.route("**/*", this.routeHandler);
-        if (this.options.replayHarPath !== undefined) {
-            // Registered after the destination guard so it runs first: a replayed
-            // request is served from the file and never becomes a socket, and
-            // `notFound: "abort"` means a request the archive is missing fails
-            // visibly rather than falling through to the network the guard would
-            // have allowed.
-            await this.context.routeFromHAR(this.options.replayHarPath, {
-                notFound: "abort",
-            });
+        try {
+            await this.call(this.context.route("**/*", this.routeHandler), "route", SETUP_TIMEOUT_MS);
+            if (this.options.cdpEndpoint !== undefined && this.options.unhinged !== true) {
+                // `route` never sees a WebSocket, so page script could open one to
+                // any address. With a pinning proxy the proxy refuses it; an attached
+                // browser has none, so the guard runs here.
+                await this.call(this.context.routeWebSocket(() => true, async (socket) => {
+                    try {
+                        await assertSafeUrl(socket.url().replace(/^ws/i, "http"), this.options);
+                        socket.connectToServer();
+                    }
+                    catch {
+                        await socket.close({ code: 1008, reason: "destination blocked" });
+                    }
+                }), "route_websocket", SETUP_TIMEOUT_MS);
+            }
+            if (this.options.replayHarPath !== undefined) {
+                // Registered after the destination guard so it runs first: a replayed
+                // request is served from the file and never becomes a socket, and
+                // `notFound: "abort"` means a request the archive is missing fails
+                // visibly rather than falling through to the network the guard would
+                // have allowed.
+                await this.call(this.context.routeFromHAR(this.options.replayHarPath, {
+                    notFound: "abort",
+                }), "route_from_har", SETUP_TIMEOUT_MS);
+            }
+        }
+        catch (error) {
+            // `this.context` is already set, so the next action would skip straight
+            // past this method onto a context whose destination guard may never
+            // have been installed. Tearing it down makes the next action start over.
+            await this.close();
+            throw error;
         }
         /**
          * Answer dialogs instead of letting Playwright discard them.
@@ -316,6 +450,7 @@ export class BrowserRuntime {
                     ...(dialog.type() === "prompt"
                         ? { defaultValue: dialog.defaultValue() }
                         : {}),
+                    ...(this.acting ? {} : { betweenActions: true }),
                 });
             }
             // The page stays blocked until this settles, and a dialog belonging to a
@@ -338,6 +473,10 @@ export class BrowserRuntime {
          * this governs whether it stays.
          */
         this.context.on("page", (opened) => {
+            // Counted before the early return: every window Chromium creates raises
+            // exactly one of these, including tabs MELRA opened and windows that
+            // closed before Playwright finished with them.
+            this.windowsAdopted += 1;
             if (opened === this.activePage || this.openingTab)
                 return;
             // Closing a window the page opened is MELRA's judgement about what the
@@ -345,7 +484,11 @@ export class BrowserRuntime {
             // not a judgement — that stays on, like every other receipt.
             const allowed = this.options.popups === "allow" || this.options.unhinged === true;
             if (this.popups.length < MAX_POPUPS) {
-                this.popups.push({ url: opened.url(), blocked: !allowed });
+                this.popups.push({
+                    url: opened.url(),
+                    blocked: !allowed,
+                    ...(this.acting ? {} : { betweenActions: true }),
+                });
             }
             if (allowed)
                 return;
@@ -353,8 +496,98 @@ export class BrowserRuntime {
             // must not turn into the action's error.
             this.closing.push(opened.close().catch(() => undefined));
         });
+        /**
+         * Hear about new windows when Chromium creates them, not when Playwright
+         * announces them.
+         *
+         * Playwright raises `page` for a popup only once the popup's first response
+         * has committed, so a click whose window loaded slowly returned with no
+         * `popups` field and the report — and, in block mode, the close — landed in
+         * whatever ran next. Chromium creates the target synchronously inside
+         * `window.open` or the `target=_blank` click, so this count is already
+         * right when the action finishes and `awaitOpenedWindows` knows how many
+         * reports are still owed. It sees every way of opening a window, and the
+         * page cannot see or tamper with it, which an injected `window.open` hook
+         * could not promise.
+         *
+         * Registered after the `page` handler, so any miscount during setup is a
+         * window adopted but never counted — at worst one later wait ends early —
+         * rather than one counted and never adopted, which no wait could satisfy.
+         */
+        this.windowsCreated = new Map();
+        this.windowsAdopted = 0;
+        this.contextId = undefined;
+        // A session left from a context that closed under us would count into the
+        // fresh map below and make every action wait for windows that never come.
+        if (this.targets !== undefined) {
+            await this.call(this.targets.detach(), "cdp_detach", SETUP_TIMEOUT_MS).catch(() => undefined);
+        }
+        try {
+            const targets = await this.call(connection.browser.newBrowserCDPSession(), "cdp_session", SETUP_TIMEOUT_MS);
+            targets.on("Target.targetCreated", ({ targetInfo }) => {
+                // `browser_ui`, workers, and prerenders never become Playwright pages.
+                if (targetInfo.type !== "page" || targetInfo.subtype !== undefined)
+                    return;
+                const id = targetInfo.browserContextId ?? "";
+                this.windowsCreated.set(id, (this.windowsCreated.get(id) ?? 0) + 1);
+            });
+            await this.call(targets.send("Target.setDiscoverTargets", { discover: true }), "cdp:Target.setDiscoverTargets", SETUP_TIMEOUT_MS);
+            // Chromium announces the windows that already exist before it replies.
+            // Playwright had them before the `page` handler did, so they are owed no
+            // event here.
+            this.windowsCreated.clear();
+            this.targets = targets;
+        }
+        catch {
+            this.targets = undefined;
+        }
         return this.context;
     }
+    /**
+     * Hold the action's result until Playwright has handed over every window
+     * Chromium created, so the action that opened a window is the one that
+     * reports it.
+     *
+     * Costs one round trip when nothing was opened. Waits only while a window is
+     * known to exist and is still unreported, bounded by the action's own
+     * timeout: the window is part of what the action did. A window still pending
+     * after that is reported by the action running when Playwright delivers it.
+     */
+    async awaitOpenedWindows(timeoutMs) {
+        const targets = this.targets;
+        const context = this.context;
+        if (targets === undefined || context === undefined)
+            return;
+        try {
+            if (this.contextId === undefined) {
+                const page = context.pages()[0];
+                if (page === undefined)
+                    return;
+                const session = await this.call(context.newCDPSession(page), "cdp_session");
+                try {
+                    const { targetInfo } = await this.call(session.send("Target.getTargetInfo"), "cdp:Target.getTargetInfo");
+                    this.contextId = targetInfo.browserContextId ?? "";
+                }
+                finally {
+                    await this.call(session.detach(), "cdp_detach").catch(() => undefined);
+                }
+            }
+            // Events arrive ahead of the reply on the same session, so after this
+            // every window created before now has been counted.
+            await this.call(targets.send("Browser.getVersion"), "cdp:Browser.getVersion");
+            const deadline = Date.now() + timeoutMs;
+            while (this.windowsAdopted < (this.windowsCreated.get(this.contextId) ?? 0) &&
+                Date.now() < deadline) {
+                await new Promise((done) => setTimeout(done, WINDOW_POLL_MS));
+            }
+        }
+        catch {
+            // The browser went away mid-action, or stopped answering within the
+            // action's bound; either way nothing more will be delivered in time, and
+            // this wait only ever decides which action reports a window, so it is
+            // not worth failing an action over.
+        }
+    }
     /**
      * Opens a page MELRA asked for, not one the site opened by itself.
      *
@@ -365,7 +598,7 @@ export class BrowserRuntime {
     async openPage(context) {
         this.openingTab = true;
         try {
-            return await context.newPage();
+            return await this.call(context.newPage(), "new_page");
         }
         finally {
             this.openingTab = false;
@@ -390,7 +623,7 @@ export class BrowserRuntime {
         return await Promise.all(context.pages().map(async (item, index) => ({
             index,
             url: item.url(),
-            title: await item.title(),
+            title: await this.call(item.title(), "title"),
             active: item === this.activePage,
         })));
     }
@@ -444,12 +677,16 @@ export class BrowserRuntime {
      *
      * A target that matches nothing is reported as such instead of being handed to
      * Playwright to fail as an opaque action timeout thirty seconds later.
+     *
+     * Resolution only reads the page and always runs before an action's effect,
+     * so a `count` that times out here fails a click or a fill cleanly: nothing
+     * was sent, and `execute` does not report it as an unknown outcome.
      */
     async locator(page, target) {
         if (target === undefined)
             throw new Error("browser_action_requires_target");
         for (const candidate of this.candidates(page, target)) {
-            if ((await candidate.count()) > 0)
+            if ((await this.call(candidate.count(), "count")) > 0)
                 return candidate;
         }
         throw new Error(`browser_target_not_found:${JSON.stringify(target)}`);
@@ -479,8 +716,8 @@ export class BrowserRuntime {
                 // `isVisible`/`count` report on a missing element rather than throwing,
                 // so absence is an answer here: it satisfies `hidden` and `detached`.
                 const present = state === "attached" || state === "detached"
-                    ? (await element.count()) > 0
-                    : await element.isVisible();
+                    ? (await this.call(element.count(), "count")) > 0
+                    : await this.call(element.isVisible(), "is_visible");
                 if (negated) {
                     if (present) {
                         reached = false;
@@ -515,21 +752,65 @@ export class BrowserRuntime {
         const field = locator.first();
         if (operation.clearFirst) {
             await field.fill("", { timeout: operation.timeoutMs });
+            this.dispatched = true;
         }
+        // Found first, then counted as sent before the first key: typing is one
+        // key per round trip, so a deadline can land after some keys (an Enter
+        // among them) reached the page, and that is not "nothing happened".
+        await field.waitFor({ state: "visible", timeout: operation.timeoutMs });
+        this.dispatched = true;
         await field.pressSequentially(value, {
             delay: operation.delayMs,
             timeout: operation.timeoutMs,
         });
+        this.dispatched = true;
+    }
+    /**
+     * An attached CDP browser has no pinning proxy, and Chromium follows a
+     * redirect without showing the hop to the route guard, so an allowed page
+     * that redirects to 169.254.169.254 or a LAN address loads there. The request
+     * cannot be stopped from here; what can be is reading it back. A page whose
+     * address the guard refuses is blanked and the action fails, and a frame
+     * the guard refuses is left out.
+     */
+    async refusedFrames(page, frames) {
+        const refused = new Set();
+        if (this.options.cdpEndpoint === undefined || this.options.unhinged === true)
+            return refused;
+        for (const frame of frames) {
+            const url = frame.url();
+            if (!/^https?:/i.test(url))
+                continue;
+            try {
+                await assertSafeUrl(url, this.options);
+            }
+            catch (error) {
+                if (frame !== page.mainFrame()) {
+                    refused.add(frame);
+                    continue;
+                }
+                await page.goto("about:blank").catch(() => undefined);
+                throw error;
+            }
+        }
+        return refused;
     }
     async snapshot(page, maxChars) {
-        const frames = this.frames(page);
-        const collected = await Promise.all(frames.map(async (frame) => {
+        const all = this.frames(page);
+        const refused = await this.refusedFrames(page, all);
+        const frames = all.filter((frame) => !refused.has(frame));
+        const collected = await Promise.all(frames.map(async (frame, index) => {
             try {
-                return await frame.evaluate(collectFrame, maxChars);
+                return await this.call(frame.evaluate(collectFrame, maxChars), "evaluate");
             }
-            catch {
+            catch (error) {
+                // The main document not answering is a failed inspect: reporting it
+                // as empty would hand back a plausible snapshot of nothing.
+                if (index === 0 && error instanceof BrowserCallTimeoutError)
+                    throw error;
                 // A frame that navigated or detached mid-evaluate is not a failed
-                // inspect. Losing an ad frame should not lose the page.
+                // inspect. Losing an ad frame should not lose the page, and neither
+                // should one whose out-of-process renderer stopped answering.
                 return undefined;
             }
         }));
@@ -549,7 +830,7 @@ export class BrowserRuntime {
             .map((element, index) => ({ index, ...element }));
         return {
             url: page.url(),
-            title: await page.title(),
+            title: await this.call(page.title(), "title"),
             text: main?.text ?? "",
             truncated: main?.truncated ?? false,
             elements,
@@ -573,7 +854,7 @@ export class BrowserRuntime {
         ]);
         return {
             url: page.url(),
-            title: await page.title(),
+            title: await this.call(page.title(), "title"),
             target: operation.target,
             text: text.slice(0, operation.maxChars),
             html: html.slice(0, operation.maxChars),
@@ -582,39 +863,99 @@ export class BrowserRuntime {
         };
     }
     async settledSnapshot(page, operation) {
+        // Bounded by its own `settleTimeoutMs` plus a grace, not by `timeoutMs`:
+        // the settle window is a deliberate wait and must not be cut short.
         const settle = await waitForStableDom(page, {
             quietWindowMs: operation.settleQuietMs,
             timeoutMs: operation.settleTimeoutMs,
-        });
+        }, this.signal);
         return {
             settle,
             ...(await this.snapshot(page, operation.maxChars)),
         };
     }
-    async execute(operation) {
+    /**
+     * One action at a time, in arrival order. A single runtime serves every task,
+     * and a parallel workflow node or two concurrent MCP calls used to run here
+     * at once: the second reset the first's cancel signal, timeout and
+     * `dispatched` flag mid-flight, so a click that landed was reported as a
+     * plain failure, and one task's cancel stopped another's action.
+     */
+    async execute(operation, signal) {
+        const turn = this.queue.then(() => this.executeOne(operation, signal));
+        this.queue = turn.catch(() => undefined);
+        return await turn;
+    }
+    async executeOne(operation, signal) {
+        if (signal?.aborted === true)
+            throw new Error("task_cancelled");
         // Every branch reports `success: true` on the way out, because a caller who
         // declared no evidence is held to exactly that field: policy derives
         // `result_equals success true` for browser mutations, and a result without
         // it verified as `partial` no matter how well the action went. Failures
         // throw, so reaching a return is what success means here.
-        this.dialogs = [];
-        this.popups = [];
-        const ran = await this.run(operation);
-        // A blocked popup is closed from an event handler, which has no way to join
-        // the action that provoked it. Waiting here is what stops the next action
-        // from seeing a tab this one already reported as closed.
-        await Promise.all(this.closing.splice(0));
-        const result = { success: true, ...ran };
-        // Only present when the page actually asked something, so a caller can test
-        // for the field rather than for an empty array.
-        return {
-            ...result,
-            ...(this.dialogs.length === 0 ? {} : { dialogs: this.dialogs }),
-            ...(this.popups.length === 0 ? {} : { popups: this.popups }),
-        };
+        this.signal = signal;
+        this.callMs = operation.timeoutMs;
+        this.dispatched = false;
+        this.acting = true;
+        try {
+            const ran = await this.run(operation);
+            await this.awaitOpenedWindows(operation.timeoutMs);
+            // A blocked popup is closed from an event handler, which has no way to
+            // join the action that provoked it. Waiting here is what stops the next
+            // action from seeing a tab this one already reported as closed.
+            await this.call(Promise.all(this.closing.splice(0)), "close_popup");
+            const result = { success: true, ...ran };
+            const dialogs = this.dialogs.splice(0);
+            const popups = this.popups.splice(0);
+            // Only present when the page actually asked something, so a caller can
+            // test for the field rather than for an empty array.
+            return {
+                ...result,
+                ...(dialogs.length === 0 ? {} : { dialogs }),
+                ...(popups.length === 0 ? {} : { popups }),
+            };
+        }
+        catch (error) {
+            // Only mutations ever set `dispatched`, and only once their effect call
+            // has returned. Anything that fails after that — the settle, the
+            // snapshot, the popup close, a bound or the task budget running out —
+            // fails after the page may have acted, so it is reported as an unknown
+            // outcome for the controller to park rather than as a failure it would
+            // read as "nothing happened". So is a pointer action that Playwright
+            // itself timed out after it had sent the input. A failure before either,
+            // including a timeout resolving the target, is an ordinary failure:
+            // nothing was sent, and for a read the controller may simply retry.
+            // The message is stored on the task record and shown in the console.
+            if (error instanceof Error)
+                error.message = withoutColour(error.message);
+            if (!this.dispatched && !inputSent(error))
+                throw error;
+            throw outcomeUnknown(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            this.acting = false;
+        }
     }
     async run(operation) {
         const page = await this.page();
+        // Anywhere but on the way to it, a url names the page the action acts on:
+        // the active page, or for `close` and `tab_switch` the tab they name.
+        // Policy shows it to the approver as the target and matches grants against
+        // it, so the action is refused, before anything is sent, when that page is
+        // elsewhere. Compared as policy shows it, without query or fragment.
+        //
+        // ponytail: checked when the action starts. A page that navigates itself
+        // while the action waits for its target can still receive it; pinning
+        // each action to the checked document would close that.
+        if (operation.url !== undefined && operation.action !== "navigate" && operation.action !== "tab_new") {
+            const acted = (operation.action === "close" || operation.action === "tab_switch") && operation.tabIndex !== undefined
+                ? (await this.ensureContext()).pages()[operation.tabIndex]
+                : page;
+            const at = acted === undefined ? "no such tab" : pageAddress(acted.url());
+            if (at !== pageAddress(operation.url))
+                throw new Error(`browser_page_not_at_url: the page is at ${at}`);
+        }
         switch (operation.action) {
             case "navigate": {
                 if (operation.url === undefined)
@@ -707,6 +1048,12 @@ export class BrowserRuntime {
                 await (await this.locator(page, operation.target)).first().click({
                     timeout: operation.timeoutMs,
                 });
+                // Set after the click returns, not before: Playwright's own timeout
+                // mostly fires while it waits for the element to become clickable,
+                // and reporting that as "may have clicked" would park every covered
+                // button for reconciliation. A timeout after the input went out is
+                // caught by `inputSent` instead. See `execute` for what this changes.
+                this.dispatched = true;
                 return {
                     clicked: true,
                     ...(await this.settledSnapshot(page, operation)),
@@ -742,6 +1089,7 @@ export class BrowserRuntime {
                     await (await this.locator(page, operation.target)).first().click({
                         timeout: operation.timeoutMs,
                     });
+                    this.dispatched = true;
                 }
                 return {
                     filled: operation.fields.length,
@@ -755,6 +1103,7 @@ export class BrowserRuntime {
                 const selected = await (await this.locator(page, operation.target))
                     .first()
                     .selectOption(operation.values, { timeout: operation.timeoutMs });
+                this.dispatched = true;
                 return {
                     selected,
                     ...(await this.settledSnapshot(page, operation)),
@@ -767,6 +1116,7 @@ export class BrowserRuntime {
                     ? page.locator("body")
                     : await this.locator(page, operation.target);
                 await locator.first().press(operation.key, { timeout: operation.timeoutMs });
+                this.dispatched = true;
                 return {
                     pressed: operation.key,
                     ...(await this.settledSnapshot(page, operation)),
@@ -782,26 +1132,31 @@ export class BrowserRuntime {
                 else {
                     // A fixed ±600 was too small for a long article and too large for a
                     // short scroll container, and nothing could change it.
-                    await page.evaluate(({ value, pixels }) => {
+                    await this.call(page.evaluate(({ value, pixels }) => {
                         if (value === "top")
                             window.scrollTo(0, 0);
                         else if (value === "bottom")
                             window.scrollTo(0, document.body.scrollHeight);
                         else
                             window.scrollBy(0, value === "up" ? -pixels : pixels);
-                    }, { value: direction, pixels: operation.pixels });
+                    }, { value: direction, pixels: operation.pixels }), "evaluate");
                 }
                 return {
                     scrolled: direction,
                     // Where we ended up, so a caller paging through a document can tell
                     // it has hit the bottom rather than scrolling forever.
-                    scrollY: await page.evaluate(() => window.scrollY),
+                    scrollY: await this.call(page.evaluate(() => window.scrollY), "evaluate"),
                     ...(await this.settledSnapshot(page, operation)),
                 };
             }
             case "screenshot": {
                 const path = join(this.options.artifactDirectory, `browser-${randomUUID()}.png`);
-                await page.screenshot({ path, fullPage: operation.fullPage, type: "png" });
+                await page.screenshot({
+                    path,
+                    fullPage: operation.fullPage,
+                    type: "png",
+                    timeout: operation.timeoutMs,
+                });
                 const bytes = await readFile(path);
                 return {
                     captured: true,
@@ -809,7 +1164,7 @@ export class BrowserRuntime {
                     size: bytes.byteLength,
                     sha256: createHash("sha256").update(bytes).digest("hex"),
                     url: page.url(),
-                    title: await page.title(),
+                    title: await this.call(page.title(), "title"),
                 };
             }
             case "upload": {
@@ -820,6 +1175,7 @@ export class BrowserRuntime {
                 await (await this.locator(page, operation.target)).first().setInputFiles(files, {
                     timeout: operation.timeoutMs,
                 });
+                this.dispatched = true;
                 return {
                     uploaded: files.length,
                     ...(await this.settledSnapshot(page, operation)),
@@ -829,13 +1185,21 @@ export class BrowserRuntime {
                 const downloadPromise = page.waitForEvent("download", {
                     timeout: operation.timeoutMs,
                 });
+                // If resolving or clicking the target throws first, nobody awaits the
+                // download wait, and its own timeout would surface as an unhandled
+                // rejection long after this action failed.
+                downloadPromise.catch(() => undefined);
                 await (await this.locator(page, operation.target)).first().click({
                     timeout: operation.timeoutMs,
                 });
+                this.dispatched = true;
                 const download = await downloadPromise;
                 const suggested = download.suggestedFilename().replaceAll(/[^A-Za-z0-9._-]/g, "_");
                 const path = join(this.options.artifactDirectory, `${randomUUID()}-${suggested || "download"}`);
-                await download.saveAs(path);
+                // Bounded by the task budget only. Saving waits for the whole file to
+                // arrive, and how long that legitimately takes depends on the file, not
+                // on the per-call `timeoutMs`.
+                await this.call(download.saveAs(path), "save_download", Infinity);
                 const bytes = await readFile(path);
                 return {
                     downloaded: true,
@@ -847,7 +1211,7 @@ export class BrowserRuntime {
                     settle: await waitForStableDom(page, {
                         quietWindowMs: operation.settleQuietMs,
                         timeoutMs: operation.settleTimeoutMs,
-                    }),
+                    }, this.signal),
                 };
             }
             case "tabs": {
@@ -882,7 +1246,7 @@ export class BrowserRuntime {
                 // Bring the tab to the front so a screenshot of it is what the user
                 // would actually see; a background page still renders, but modal and
                 // focus behaviour differ.
-                await target.bringToFront();
+                await this.call(target.bringToFront(), "bring_to_front");
                 this.activePage = target;
                 return {
                     switched: true,
@@ -900,7 +1264,11 @@ export class BrowserRuntime {
                 if (target === undefined)
                     throw new Error("browser_tab_not_found");
                 const url = target.url();
-                await target.close();
+                // Set before the close, unlike the other mutations: this call is the
+                // effect and has no wait-for-ready phase, so once it is in flight a
+                // bound running out cannot say whether the tab went away.
+                this.dispatched = true;
+                await this.call(target.close(), "close");
                 this.activePage = context.pages().at(-1);
                 return { closed: true, url, tabs: await this.describeTabs(context) };
             }
@@ -908,18 +1276,21 @@ export class BrowserRuntime {
     }
     async close() {
         const connection = this.connection;
+        const quietly = (call, what) => bounded(call, CLOSE_TIMEOUT_MS, what).catch(() => undefined);
+        // An attached browser outlives us; stop asking it to narrate its targets.
+        if (this.targets !== undefined)
+            await quietly(this.targets.detach(), "cdp_detach");
+        this.targets = undefined;
         if (connection !== undefined &&
             !connection.ownsContext &&
             this.routeHandler !== undefined) {
-            await connection.context
-                .unroute("**/*", this.routeHandler)
-                .catch(() => undefined);
+            await quietly(connection.context.unroute("**/*", this.routeHandler), "unroute");
         }
         if (connection?.ownsContext === true) {
-            await connection.context.close().catch(() => undefined);
+            await quietly(connection.context.close(), "close_context");
         }
         if (connection?.ownsBrowser === true) {
-            await connection.browser.close().catch(() => undefined);
+            await quietly(connection.browser.close(), "close_browser");
         }
         // After the browser, so a request in flight is not left without a proxy.
         await this.proxy?.close().catch(() => undefined);
@@ -939,4 +1310,5 @@ export * from "./pinning-proxy.js";
 export * from "./selector.js";
 export * from "./stable-dom.js";
 export * from "./browser-connection.js";
+export * from "./bounded.js";
 //# sourceMappingURL=index.js.map