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

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);
@@ -449,6 +464,7 @@ class CdpConnectedBrowserSession {
     pageConsoleStates = new Map();
     pageNetworkStates = new Map();
     pageDialogStates = new Map();
+    dialogWaiters = new Map();
     activeTabId;
     versionString = "Chromium/unknown";
     constructor(browserClient, connection) {
@@ -469,10 +485,7 @@ class CdpConnectedBrowserSession {
         });
         const session = new CdpConnectedBrowserSession(browserClient, connection);
         session.versionString = version.Browser;
-        const tabs = await session.refreshTabs();
-        if (tabs.length === 0) {
-            await session.newTab();
-        }
+        await session.refreshTabs();
         await session.getActivePageClient().catch(() => undefined);
         return session;
     }
@@ -536,6 +549,7 @@ class CdpConnectedBrowserSession {
     async click(target, options) {
         const pageClient = await this.getActivePageClient();
         const contextId = await this.getActiveUtilityContextId(pageClient);
+        const tabId = await this.getActiveTabId();
         const source = "nodeToken" in target ? ACTION_POINT_EVALUATE_SOURCE : ACTION_POINT_BY_SELECTOR_SOURCE;
         const arg = "nodeToken" in target ? { nodeToken: target.nodeToken } : { selector: target.selector };
         const point = await evaluateCdp(pageClient, source, arg, contextId);
@@ -569,7 +583,7 @@ class CdpConnectedBrowserSession {
                 modifiers: modifiersMask
             });
             await delay(options.clickHoldMs);
-            await pageClient.Input.dispatchMouseEvent({
+            const releasePromise = pageClient.Input.dispatchMouseEvent({
                 type: "mouseReleased",
                 x: point.x,
                 y: point.y,
@@ -577,6 +591,10 @@ class CdpConnectedBrowserSession {
                 clickCount,
                 modifiers: modifiersMask
             });
+            await Promise.race([
+                releasePromise,
+                this.waitForDialog(tabId, options.clickHoldMs + 1000)
+            ]);
         }
     }
     async drag(start, end, options) {
@@ -833,26 +851,105 @@ class CdpConnectedBrowserSession {
         }
     }
     async handleDialog(accept, promptText) {
-        const tabId = await this.getActiveTabId();
+        const tabId = this.dialogTabId();
         if (!this.pageDialogStates.has(tabId)) {
             throw new McpToolError("no_dialog", "No dialog visible.");
         }
-        const pageClient = await this.getActivePageClient();
+        const pageClient = this.pageClients.get(tabId) ?? await this.getActivePageClient();
         this.pageDialogStates.delete(tabId);
         await pageClient.Page.handleJavaScriptDialog({
             accept,
             ...(promptText !== undefined ? { promptText } : {})
         });
     }
+    async hasDialog() {
+        return this.pageDialogStates.size > 0;
+    }
+    waitForDialog(tabId, timeoutMs) {
+        if (this.pageDialogStates.has(tabId)) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            const waiter = {
+                resolve: () => {
+                    if (waiter.timer) {
+                        clearTimeout(waiter.timer);
+                    }
+                    this.removeDialogWaiter(tabId, waiter);
+                    resolve();
+                }
+            };
+            waiter.timer = setTimeout(() => waiter.resolve(), timeoutMs);
+            const waiters = this.dialogWaiters.get(tabId) ?? new Set();
+            waiters.add(waiter);
+            this.dialogWaiters.set(tabId, waiters);
+        });
+    }
+    resolveDialogWaiters(tabId) {
+        const waiters = this.dialogWaiters.get(tabId);
+        if (!waiters) {
+            return;
+        }
+        this.dialogWaiters.delete(tabId);
+        for (const waiter of waiters) {
+            waiter.resolve();
+        }
+    }
+    removeDialogWaiter(tabId, waiter) {
+        const waiters = this.dialogWaiters.get(tabId);
+        if (!waiters) {
+            return;
+        }
+        waiters.delete(waiter);
+        if (waiters.size === 0) {
+            this.dialogWaiters.delete(tabId);
+        }
+    }
     async networkRequests() {
         const tabId = await this.getActiveTabId();
+        await this.hydratePerformanceResourceRequests(tabId);
         return this.ensureNetworkState(tabId).requests.map(cloneNetworkRequest);
     }
     async networkRequest(index) {
         const tabId = await this.getActiveTabId();
+        await this.hydratePerformanceResourceRequests(tabId);
         const request = this.ensureNetworkState(tabId).requests[index - 1];
         return request ? cloneNetworkRequest(request) : undefined;
     }
+    async fetchResponseBody(index) {
+        const tabId = await this.getActiveTabId();
+        const state = this.ensureNetworkState(tabId);
+        const request = state.requests[index - 1];
+        if (!request || !request.requestId) {
+            return request?.responseBody;
+        }
+        if (!canReadResponseBody(request)) {
+            return undefined;
+        }
+        if (request.responseBody !== undefined) {
+            return request.responseBody;
+        }
+        await waitForLoadingDone(state, request.requestId, 5_000).catch(() => undefined);
+        if (request.responseBody !== undefined) {
+            return request.responseBody;
+        }
+        if (state.bodyRead.has(request.requestId)) {
+            return undefined;
+        }
+        state.bodyRead.add(request.requestId);
+        const pageClient = this.pageClients.get(tabId) ?? await this.getActivePageClient();
+        const clientNetwork = pageClient.Network;
+        if (!clientNetwork) {
+            return undefined;
+        }
+        const body = await clientNetwork.getResponseBody({ requestId: request.requestId }).catch(() => undefined);
+        if (body) {
+            request.responseBody = body.base64Encoded
+                ? Buffer.from(body.body, "base64").toString("utf8")
+                : body.body;
+        }
+        return request.responseBody;
+    }
     async runCodeUnsafe(code) {
         const pageClient = await this.getActivePageClient();
         const contextId = await this.getActiveUtilityContextId(pageClient);
@@ -922,6 +1019,16 @@ class CdpConnectedBrowserSession {
         }
         return activeTab.id;
     }
+    dialogTabId() {
+        if (this.activeTabId && this.pageDialogStates.has(this.activeTabId)) {
+            return this.activeTabId;
+        }
+        const tabId = this.pageDialogStates.keys().next().value;
+        if (!tabId) {
+            throw new McpToolError("no_dialog", "No dialog visible.");
+        }
+        return tabId;
+    }
     async getActivePageClient() {
         const tabs = await this.refreshTabs();
         const activeTab = tabs.find((tab) => tab.active);
@@ -1016,6 +1123,7 @@ class CdpConnectedBrowserSession {
                 ...(event.defaultPrompt !== undefined ? { defaultPrompt: event.defaultPrompt } : {}),
                 ...(event.url !== undefined ? { url: event.url } : {})
             });
+            this.resolveDialogWaiters(tabId);
         });
         this.installNetworkCollection(tabId, client);
     }
@@ -1063,13 +1171,15 @@ class CdpConnectedBrowserSession {
         client.Network.loadingFinished(async (event) => {
             const request = state.byRequestId.get(event.requestId);
             if (!request) {
+                resolveLoadingDone(state, event.requestId, true);
                 return;
             }
             const startedAt = state.startedAt.get(event.requestId);
             if (startedAt !== undefined && event.timestamp !== undefined) {
                 request.durationMs = Math.round(event.timestamp * 1000 - startedAt);
             }
-            if (canReadResponseBody(request)) {
+            if (canReadResponseBody(request) && !state.bodyRead.has(event.requestId)) {
+                state.bodyRead.add(event.requestId);
                 const clientNetwork = client.Network;
                 const body = await clientNetwork?.getResponseBody({ requestId: event.requestId }).catch(() => undefined);
                 if (body) {
@@ -1078,10 +1188,12 @@ class CdpConnectedBrowserSession {
                         : body.body;
                 }
             }
+            resolveLoadingDone(state, event.requestId, true);
         });
         client.Network.loadingFailed((event) => {
             const request = state.byRequestId.get(event.requestId);
             if (!request) {
+                resolveLoadingDone(state, event.requestId, false);
                 return;
             }
             request.failureText = event.errorText ?? "Unknown error";
@@ -1089,6 +1201,7 @@ class CdpConnectedBrowserSession {
             if (startedAt !== undefined && event.timestamp !== undefined) {
                 request.durationMs = Math.round(event.timestamp * 1000 - startedAt);
             }
+            resolveLoadingDone(state, event.requestId, false);
         });
     }
     ensureConsoleState(tabId) {
@@ -1110,7 +1223,10 @@ class CdpConnectedBrowserSession {
             state = {
                 requests: [],
                 byRequestId: new Map(),
-                startedAt: new Map()
+                startedAt: new Map(),
+                hydratedPerformanceResources: false,
+                loadingDone: new Map(),
+                bodyRead: new Set()
             };
             this.pageNetworkStates.set(tabId, state);
         }
@@ -1126,10 +1242,82 @@ class CdpConnectedBrowserSession {
         this.pageNetworkStates.set(tabId, {
             requests: [],
             byRequestId: new Map(),
-            startedAt: new Map()
+            startedAt: new Map(),
+            hydratedPerformanceResources: false,
+            loadingDone: new Map(),
+            bodyRead: new Set()
         });
         this.pageDialogStates.delete(tabId);
     }
+    async hydratePerformanceResourceRequests(tabId) {
+        const state = this.ensureNetworkState(tabId);
+        if (state.hydratedPerformanceResources) {
+            return;
+        }
+        state.hydratedPerformanceResources = true;
+        const pageClient = await this.getActivePageClient();
+        const contextId = await this.getActiveUtilityContextId(pageClient);
+        const documentRequest = await evaluateCdp(pageClient, String.raw `() => {
+        const navigation = performance.getEntriesByType("navigation")[0];
+        return {
+          url: String(location.href || ""),
+          duration: navigation ? Math.round(Number(navigation.duration || 0)) : undefined
+        };
+      }`, undefined, contextId).catch(() => undefined);
+        if (documentRequest?.url && !Array.from(state.byRequestId.values()).some((request) => request.url === documentRequest.url)) {
+            const requestId = `performance:navigation:${documentRequest.url}`;
+            const request = {
+                index: state.requests.length + 1,
+                requestId,
+                method: "GET",
+                url: documentRequest.url,
+                resourceType: "document",
+                requestHeaders: {},
+                status: 200,
+                statusText: "OK",
+                ...(documentRequest.duration !== undefined ? { durationMs: documentRequest.duration } : {})
+            };
+            state.requests.push(request);
+            state.byRequestId.set(requestId, request);
+        }
+        const resources = await evaluateCdp(pageClient, String.raw `() => performance.getEntriesByType("resource").map((entry) => ({
+        name: String(entry.name || ""),
+        initiatorType: String(entry.initiatorType || "other"),
+        duration: Math.round(Number(entry.duration || 0)),
+        responseStatus: typeof entry.responseStatus === "number" ? entry.responseStatus : undefined
+      }))`, undefined, contextId).catch(() => []);
+        for (const resource of resources) {
+            if (!resource.name || Array.from(state.byRequestId.values()).some((request) => request.url === resource.name)) {
+                continue;
+            }
+            const status = resource.responseStatus && resource.responseStatus > 0
+                ? resource.responseStatus
+                : await this.probeResourceStatus(pageClient, contextId, resource.name);
+            const requestId = `performance:${resource.name}`;
+            const request = {
+                index: state.requests.length + 1,
+                requestId,
+                method: "GET",
+                url: resource.name,
+                resourceType: normalizeResourceType(resource.initiatorType),
+                requestHeaders: {},
+                ...(status !== undefined ? { status, statusText: statusTextForStatus(status) } : {}),
+                ...(resource.duration !== undefined ? { durationMs: resource.duration } : {})
+            };
+            state.requests.push(request);
+            state.byRequestId.set(requestId, request);
+        }
+    }
+    async probeResourceStatus(pageClient, contextId, url) {
+        return evaluateCdp(pageClient, String.raw `async (url) => {
+        try {
+          const response = await fetch(url, { method: "HEAD", cache: "no-store" });
+          return response.status;
+        } catch {
+          return undefined;
+        }
+      }`, url, contextId).catch(() => undefined);
+    }
     addConsoleMessage(tabId, message) {
         const state = this.ensureConsoleState(tabId);
         if (!shouldIncludeConsoleMessage(message.type)) {
@@ -1299,6 +1487,59 @@ function canReadResponseBody(request) {
     }
     return request.status !== 204 && request.status !== 304 && !(request.status >= 100 && request.status < 200);
 }
+function loadingDoneEntry(state, requestId) {
+    let entry = state.loadingDone.get(requestId);
+    if (!entry) {
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        entry = { promise, resolve, reject };
+        state.loadingDone.set(requestId, entry);
+    }
+    return entry;
+}
+function resolveLoadingDone(state, requestId, success) {
+    const entry = state.loadingDone.get(requestId);
+    if (!entry) {
+        return;
+    }
+    state.loadingDone.delete(requestId);
+    if (success) {
+        entry.resolve();
+    }
+    else {
+        entry.reject(new Error("Request failed before the response body was available."));
+    }
+}
+async function waitForLoadingDone(state, requestId, timeoutMs) {
+    const entry = loadingDoneEntry(state, requestId);
+    await Promise.race([
+        entry.promise,
+        new Promise((resolve) => setTimeout(resolve, timeoutMs))
+    ]);
+}
+function statusTextForStatus(status) {
+    if (status === 200)
+        return "OK";
+    if (status === 204)
+        return "No Content";
+    if (status === 304)
+        return "Not Modified";
+    if (status === 400)
+        return "Bad Request";
+    if (status === 401)
+        return "Unauthorized";
+    if (status === 403)
+        return "Forbidden";
+    if (status === 404)
+        return "Not Found";
+    if (status === 500)
+        return "Internal Server Error";
+    return "";
+}
 function cloneNetworkRequest(request) {
     return {
         ...request,
@@ -1398,6 +1639,7 @@ class BidiConnectedBrowserSession {
     pageConsoleStates = new Map();
     pageNetworkStates = new Map();
     pageDialogStates = new Map();
+    dialogWaiters = new Map();
     bidiListeners = new Map();
     responseDataCollector;
     activeTabId;
@@ -1420,10 +1662,7 @@ class BidiConnectedBrowserSession {
         const session = new BidiConnectedBrowserSession(client);
         session.ownsSession = await ensureMcpBiDiSession(client, args.endpoint, args.sessionId);
         await session.initialize();
-        const tabs = await session.refreshTabs();
-        if (tabs.length === 0) {
-            await session.newTab();
-        }
+        await session.refreshTabs();
         return session;
     }
     async version() {
@@ -1482,10 +1721,14 @@ class BidiConnectedBrowserSession {
     async snapshot(request = {}) {
         const tabId = await this.getActiveTabId();
         const result = await retryUntilReady(() => evaluateBiDi(this.client, tabId, ARIA_SNAPSHOT_EVALUATE_SOURCE, toAriaSnapshotPayload(request)));
-        return toBrowserSnapshot(result, request, {
+        const snapshot = toBrowserSnapshot(result, request, {
             console: this.consoleSummary(tabId),
             consoleLink: await this.takeConsoleLink(tabId)
         });
+        return {
+            ...snapshot,
+            retryable: true
+        };
     }
     async consoleMessages(level = "info", all = false) {
         const activeTabId = await this.getActiveTabId();
@@ -1575,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) {
@@ -1829,16 +2090,27 @@ class BidiConnectedBrowserSession {
         }
     }
     async handleDialog(accept, promptText) {
-        const tabId = await this.getActiveTabId();
+        const tabId = this.dialogTabId();
         if (!this.pageDialogStates.has(tabId)) {
             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;
     }
     async networkRequests() {
         const tabId = await this.getActiveTabId();
@@ -1849,6 +2121,21 @@ class BidiConnectedBrowserSession {
         const request = this.ensureNetworkState(tabId).requests[index - 1];
         return request ? cloneNetworkRequest(request) : undefined;
     }
+    async fetchResponseBody(index) {
+        const tabId = await this.getActiveTabId();
+        const request = this.ensureNetworkState(tabId).requests[index - 1];
+        if (!request || !request.requestId) {
+            return request?.responseBody;
+        }
+        if (request.responseBody !== undefined) {
+            return request.responseBody;
+        }
+        const body = await this.getResponseBody(request.requestId).catch(() => undefined);
+        if (body !== undefined) {
+            request.responseBody = body;
+        }
+        return request.responseBody;
+    }
     async runCodeUnsafe(code) {
         return this.evaluate(`async () => {
       const fn = eval(${JSON.stringify(`(${code})`)});
@@ -1864,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",
@@ -1879,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));
@@ -1921,6 +2216,63 @@ class BidiConnectedBrowserSession {
     targetArg(target) {
         return "nodeToken" in target ? { nodeToken: target.nodeToken } : { selector: target.selector };
     }
+    dialogTabId() {
+        if (this.activeTabId && this.pageDialogStates.has(this.activeTabId)) {
+            return this.activeTabId;
+        }
+        const tabId = this.pageDialogStates.keys().next().value;
+        if (!tabId) {
+            throw new McpToolError("no_dialog", "No dialog visible.");
+        }
+        return tabId;
+    }
+    waitForDialog(tabId, timeoutMs) {
+        if (this.pageDialogStates.has(tabId)) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve: () => {
+                    if (waiter.timer) {
+                        clearTimeout(waiter.timer);
+                    }
+                    this.removeDialogWaiter(tabId, waiter);
+                    resolve();
+                },
+                reject: (error) => {
+                    if (waiter.timer) {
+                        clearTimeout(waiter.timer);
+                    }
+                    this.removeDialogWaiter(tabId, waiter);
+                    reject(error);
+                }
+            };
+            waiter.timer = setTimeout(() => waiter.reject?.(new Error("Timed out waiting for dialog.")), timeoutMs);
+            const waiters = this.dialogWaiters.get(tabId) ?? new Set();
+            waiters.add(waiter);
+            this.dialogWaiters.set(tabId, waiters);
+        });
+    }
+    resolveDialogWaiters(tabId) {
+        const waiters = this.dialogWaiters.get(tabId);
+        if (!waiters) {
+            return;
+        }
+        this.dialogWaiters.delete(tabId);
+        for (const waiter of waiters) {
+            waiter.resolve();
+        }
+    }
+    removeDialogWaiter(tabId, waiter) {
+        const waiters = this.dialogWaiters.get(tabId);
+        if (!waiters) {
+            return;
+        }
+        waiters.delete(waiter);
+        if (waiters.size === 0) {
+            this.dialogWaiters.delete(tabId);
+        }
+    }
     async actionPoint(tabId, target) {
         const source = "nodeToken" in target ? ACTION_POINT_EVALUATE_SOURCE : ACTION_POINT_BY_SELECTOR_SOURCE;
         const point = await evaluateBiDi(this.client, tabId, source, this.targetArg(target));
@@ -1981,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);
@@ -2001,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 ??= "";
         }
@@ -2037,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) {
@@ -2103,7 +2477,10 @@ class BidiConnectedBrowserSession {
             state = {
                 requests: [],
                 byRequestId: new Map(),
-                startedAt: new Map()
+                startedAt: new Map(),
+                hydratedPerformanceResources: false,
+                loadingDone: new Map(),
+                bodyRead: new Set()
             };
             this.pageNetworkStates.set(tabId, state);
         }
@@ -2119,7 +2496,10 @@ class BidiConnectedBrowserSession {
         this.pageNetworkStates.set(tabId, {
             requests: [],
             byRequestId: new Map(),
-            startedAt: new Map()
+            startedAt: new Map(),
+            hydratedPerformanceResources: false,
+            loadingDone: new Map(),
+            bodyRead: new Set()
         });
         this.pageDialogStates.delete(tabId);
     }