@roxybrowser/playwright 2.0.2-beta.4 → 2.0.2-beta.5

package/dist/browserType.d.ts

@@ -6,7 +6,29 @@ export declare class RoxyBrowserType implements BrowserType {
     private readonly adapterFactories;
     constructor(browserName: NonNullable<BrowserConnectOptions["browserName"]>, adapterFactories: Record<SupportedProtocol, ProtocolBrowserAdapterFactory>);
     launch(options?: LaunchOptions): Promise<Browser>;
-    connect(options: BrowserConnectOptions): Promise<Browser>;
+    /**
+     * Connect to an already-running browser over a WebSocket endpoint.
+     *
+     * ⚠️ DIVERGENCE FROM PLAYWRIGHT — DO NOT "FIX" THIS BACK TO CDP-ONLY:
+     *
+     * In upstream Playwright, `BrowserType.connect()` is a CDP-only operation: it
+     * connects to a running Chromium over the DevTools Protocol. Firefox/WebKit are
+     * not supported here (Playwright routes BiDi through `connectOverCDP`-style
+     * helpers or its own internal plumbing, not this method).
+     *
+     * Roxy intentionally changes that semantics. This method dispatches on
+     * `browserName` so a single entry point serves both browser families:
+     *   - chromium  → CDP  (ws:// DevTools endpoint)
+     *   - firefox   → BiDi (ws:// WebDriver BiDi endpoint)
+     *
+     * This is deliberate, not a bug. If you are an agent "normalizing" this code to
+     * match Playwright upstream, STOP — the dual-protocol dispatch is the feature.
+     * To force CDP specifically, call `connectOverCDP()` instead, which remains
+     * chromium-only and CDP-only by design (see the guard below).
+     *
+     * `options.protocol` may still be passed to override the per-browser default.
+     */
+    connect(endpointURL: string, options?: ConnectOverCDPOptions): Promise<Browser>;
     connectOverCDP(endpointURL: string, options?: ConnectOverCDPOptions): Promise<Browser>;
     connectOverCDP(progress: Progress, endpointURL: string, options?: ConnectOverCDPOptions): Promise<Browser>;
     private connectBrowser;

package/dist/browserType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browserType.d.ts","sourceRoot":"","sources":["../src/browserType.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAE5B,qBAAa,eAAgB,YAAW,WAAW;IAE/C,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,WAAW,EAAE,WAAW,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC,EAC9D,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,EAAE,6BAA6B,CAAC;IAGvF,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAQrD,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC;IAQzD,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC;IACb,cAAc,CAClB,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC;YAoCL,cAAc;CAqB7B;AAED,eAAO,MAAM,QAAQ,EAAE,WAGrB,CAAC;AAEH,eAAO,MAAM,OAAO,EAAE,WAGpB,CAAC"}
+{"version":3,"file":"browserType.d.ts","sourceRoot":"","sources":["../src/browserType.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAE5B,qBAAa,eAAgB,YAAW,WAAW;IAE/C,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,WAAW,EAAE,WAAW,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC,EAC9D,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,EAAE,6BAA6B,CAAC;IAGvF,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/E,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC;IACb,cAAc,CAClB,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,OAAO,CAAC;YAoCL,cAAc;CAqB7B;AAED,eAAO,MAAM,QAAQ,EAAE,WAGrB,CAAC;AAEH,eAAO,MAAM,OAAO,EAAE,WAGpB,CAAC"}

package/dist/browserType.js

@@ -16,11 +16,34 @@ export class RoxyBrowserType {
             protocol: options.protocol ?? (this.browserName === "firefox" ? "bidi" : "cdp")
         });
     }
-    async connect(options) {
+    /**
+     * Connect to an already-running browser over a WebSocket endpoint.
+     *
+     * ⚠️ DIVERGENCE FROM PLAYWRIGHT — DO NOT "FIX" THIS BACK TO CDP-ONLY:
+     *
+     * In upstream Playwright, `BrowserType.connect()` is a CDP-only operation: it
+     * connects to a running Chromium over the DevTools Protocol. Firefox/WebKit are
+     * not supported here (Playwright routes BiDi through `connectOverCDP`-style
+     * helpers or its own internal plumbing, not this method).
+     *
+     * Roxy intentionally changes that semantics. This method dispatches on
+     * `browserName` so a single entry point serves both browser families:
+     *   - chromium  → CDP  (ws:// DevTools endpoint)
+     *   - firefox   → BiDi (ws:// WebDriver BiDi endpoint)
+     *
+     * This is deliberate, not a bug. If you are an agent "normalizing" this code to
+     * match Playwright upstream, STOP — the dual-protocol dispatch is the feature.
+     * To force CDP specifically, call `connectOverCDP()` instead, which remains
+     * chromium-only and CDP-only by design (see the guard below).
+     *
+     * `options.protocol` may still be passed to override the per-browser default.
+     */
+    async connect(endpointURL, options) {
         return this.connectBrowser({
-            ...options,
-            browserName: options.browserName ?? this.browserName,
-            protocol: options.protocol ?? (this.browserName === "firefox" ? "bidi" : "cdp")
+            browserName: this.browserName,
+            protocol: this.browserName === "chromium" ? "cdp" : "bidi",
+            wsEndpoint: endpointURL,
+            ...options
         });
     }
     async connectOverCDP(progressOrEndpointURL, endpointURLOrOptions, maybeOptions = {}) {

package/dist/browserType.js.map

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

package/dist/mcp/connectedBrowser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connectedBrowser.d.ts","sourceRoot":"","sources":["../../src/mcp/connectedBrowser.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAOV,uBAAuB,EACvB,sBAAsB,EAOvB,MAAM,YAAY,CAAC;AAswGpB,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAMlC"}
+{"version":3,"file":"connectedBrowser.d.ts","sourceRoot":"","sources":["../../src/mcp/connectedBrowser.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAOV,uBAAuB,EACvB,sBAAsB,EAOvB,MAAM,YAAY,CAAC;AA+0GpB,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CAMlC"}

package/dist/mcp/connectedBrowser.js

@@ -10,6 +10,21 @@ import { ACTION_POINT_EVALUATE_SOURCE, ACTION_POINT_BY_SELECTOR_SOURCE } from ".
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function withBiDiTimeout(promise, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms.`)), timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 const chromeRemoteInterface = ("default" in cdpModule
     ? cdpModule.default
     : cdpModule);
@@ -1803,10 +1818,28 @@ class BidiConnectedBrowserSession {
             parameters: { pointerType: "mouse" },
             actions: pointerActions
         });
-        await this.client.inputPerformActions({
+        // TODO(bidi): A synchronous alert()/confirm()/prompt() opened by the click
+        // blocks the page's main thread, and in Firefox that also wedges the BiDi
+        // transport: inputPerformActions never resolves while the modal is open.
+        // Unlike CDP (where only the mouse-release call blocks), BiDi dispatches
+        // the whole pointer sequence as one atomic command, so we cannot split it.
+        // Mitigation (NOT a full fix): race the action against the dialog waiter so
+        // a dialog-opening click resolves instead of hanging forever. The residual
+        // performPromise is intentionally left dangling; it resolves later once the
+        // dialog is dismissed.
+        //
+        // KNOWN-UNRESOLVED: even with this race,后续的 BiDi 命令在模态框打开期间仍可能
+        // 整体卡死（见 handleDialog 的 TODO）。Firefox/geckodriver 在 alert 模态下会
+        // 阻塞几乎所有 BiDi 命令，这是浏览器/驱动层的限制，本适配器无法绕过。
+        const performPromise = this.client.inputPerformActions({
             context: tabId,
             actions
         });
+        await Promise.race([
+            performPromise,
+            this.waitForDialog(tabId, options.clickHoldMs + 5000)
+        ]);
+        performPromise.catch(() => { });
         await this.client.inputReleaseActions({ context: tabId }).catch(() => { });
     }
     async drag(start, end, options) {
@@ -2062,11 +2095,19 @@ class BidiConnectedBrowserSession {
             throw new McpToolError("no_dialog", "No dialog visible.");
         }
         this.pageDialogStates.delete(tabId);
-        await this.client.browsingContextHandleUserPrompt({
+        // TODO(bidi): Firefox's browsingContext.handleUserPrompt can stall while a
+        // modal is open — 实测在 alert/confirm 模态下 geckodriver 对该命令的响应会
+        // 长时间不返回（实测 60s+ 不返回，最终靠 MCP 客户端超时才解脱）。这里用
+        // withBiDiTimeout 兜底：最多等 5s 后强制 reject，避免工具调用无限挂起。
+        // 这只是“快速失败”的缓解，并未真正解决“模态框打开时几乎所有 BiDi 命令都
+        // 被卡死”的底层问题。CDP 下这一路径是可靠的，BiDi 暂只能参考 CDP 思路。
+        // KNOWN-UNRESOLVED: 若在模态框打开期间调用本命令，前序的 refreshTabs
+        // (browsingContextGetTree) 等也可能先一步卡死，导致整个 tool 调用超时。
+        await withBiDiTimeout(this.client.browsingContextHandleUserPrompt({
             context: tabId,
             accept,
             ...(promptText !== undefined ? { userText: promptText } : {})
-        });
+        }), 5_000);
     }
     async hasDialog() {
         return this.pageDialogStates.size > 0;
@@ -2110,6 +2151,15 @@ class BidiConnectedBrowserSession {
     }`);
     }
     async initialize() {
+        // 顺序很关键：必须先 attachBiDiListeners()，再 sessionSubscribe()。
+        // 实测 Firefox：sessionSubscribe 返回后事件会立即开始涌入；若此刻监听器
+        // 还没注册，最早的一批 network.beforeRequestSent（页面导航/资源请求）会落进
+        // “no registered listener” 分支被静默丢弃，导致 network 列表里缺首页请求。
+        // 调试时观察到 [DEBUG bidi client no-listener] network.beforeRequestSent 连续
+        // 出现几十次，正是此问题。先注册监听器即可避免丢事件。
+        // TODO(bidi): 即便修了顺序，BiDi 网络捕获仍有状态时序问题，见
+        // handleResponseCompleted / networkRequests 的 TODO。
+        this.attachBiDiListeners();
         await this.client.sessionSubscribe({
             events: [
                 "browsingContext.userPromptOpened",
@@ -2125,7 +2175,6 @@ class BidiConnectedBrowserSession {
             maxEncodedDataSize: 10_000_000
         }).catch(() => undefined);
         this.responseDataCollector = collectorResult?.collector;
-        this.attachBiDiListeners();
     }
     attachBiDiListeners() {
         this.attachBiDiListener("log.entryAdded", (payload) => this.handleLogEntry(payload));
@@ -2284,6 +2333,11 @@ class BidiConnectedBrowserSession {
             type: event.type ?? "alert",
             ...(event.defaultValue !== undefined ? { defaultPrompt: event.defaultValue } : {})
         });
+        // 这里必须 resolve 对话框等待器：BiDi 的 click 会 race inputPerformActions
+        // 与 waitForDialog（见 click 注释）。若不在此 resolve，alert() 触发后
+        // waitForDialog 会一直 pending，click 永久挂起。CDP 侧的
+        // javascriptDialogOpening 处理也调用了 resolveDialogWaiters，两侧需对齐。
+        this.resolveDialogWaiters(event.context);
     }
     handleBeforeRequestSent(payload) {
         const event = parseBidiNetworkEvent(payload);
@@ -2304,6 +2358,12 @@ class BidiConnectedBrowserSession {
         request.url = event.request.url;
         request.resourceType = normalizeResourceType(event.request.destination);
         request.requestHeaders = normalizeHeaders(bidiHeadersToRecord(event.request.headers));
+        // TODO(bidi): BiDi 的 network.beforeRequestSent 只给 bodySize，不内联 POST
+        // body。这里只置了个空串占位（requestBody ??= ""），真实 POST 体从未填充，
+        // 因此 browser_network_request 的 part="request-body" 在 BiDi 下只能拿到空串。
+        // CDP 侧通过 Network.requestWillBeSent 的 request.postData 直接拿到 body。
+        // BiDi 若要拿到 body 需另发 network.getRequestPostData 请求（Firefox 支持不稳），
+        // 暂未实现 —— 这是已知缺口，等 geckodriver 稳定后再补。
         if (event.request.bodySize !== undefined && event.request.bodySize > 0) {
             request.requestBody ??= "";
         }
@@ -2340,6 +2400,17 @@ class BidiConnectedBrowserSession {
         if (startedAt !== undefined && event.timestamp !== undefined) {
             request.durationMs = Math.round(event.timestamp - startedAt);
         }
+        // TODO(bidi): BiDi 网络事件是乱序/延迟到达的，且 status 与 body 的可用时机
+        // 不可靠。实测 Firefox：
+        //   - beforeRequestSent 与 responseCompleted 之间存在竞态，waitForNetworkRequest
+        //     在 body/status 尚未就绪时就可能匹配到请求并返回；
+        //   - 随后再次 browser_network_requests 时，同一个 POST /api 请求有时会从列表
+        //     里“消失”（疑似 responseCompleted 到达途中 ensureNetworkRequest 重建了条目
+        //     或上下文切换所致，未完全定位）。
+        // 这导致 BiDi 下无法像 CDP 那样做强一致的网络契约断言（=> [status] OK 全匹配）。
+        // 这里仅在 responseCompleted 时尽力补 body；status 缺失的窗口由调用方容忍。
+        // KNOWN-UNRESOLVED: BiDi 网络捕获的一致性问题，需等 Firefox/geckodriver 事件
+        // 时序稳定后再追，或改用 network.getDataCollector 统一采集。
         if (canReadResponseBody(request)) {
             const body = await this.getResponseBody(event.request.request).catch(() => undefined);
             if (body !== undefined) {