@pyrokine/mcp-chrome 1.0.0 → 1.3.0

package/dist/core/session.js

@@ -12,6 +12,7 @@ import { BrowserLauncher, CDPClient, getBrowserWSEndpoint, getTargets } from '..
 import { AutoWait } from './auto-wait.js';
 import { NavigationTimeoutError, SessionNotFoundError, TargetNotFoundError } from './errors.js';
 import { Locator } from './locator.js';
+import { DEFAULT_TIMEOUT, MODIFIER_KEYS, } from './types.js';
 /**
  * 会话管理器（单例）
  */
@@ -21,11 +22,14 @@ class SessionManager {
     static MAX_LOG_ENTRIES = 1000;
     launcher = null;
     cdp = null;
+    connectedPort = 0;
     sessionId = null;
     currentTargetId = null;
     state = null;
     behaviorSimulator = new BehaviorSimulator();
     stealthMode = 'safe';
+    /** 当前按下的修饰键位掩码 */
+    modifiers = 0;
     // 操作锁（防止并发竞态）
     operationLock = Promise.resolve();
     consoleLogs = [];
@@ -35,6 +39,12 @@ class SessionManager {
     listenersInstalled = false;
     constructor() {
     }
+    /**
+     * 获取当前调试端口
+     */
+    get port() {
+        return this.launcher?.port ?? (this.connectedPort || null);
+    }
     static getInstance() {
         if (!SessionManager.instance) {
             SessionManager.instance = new SessionManager();
@@ -43,11 +53,59 @@ class SessionManager {
     }
     /**
      * 启动浏览器
+     *
+     * 如果指定了端口，会先尝试连接该端口上已运行的浏览器。
+     * 只有连接失败时才启动新浏览器。
      */
     async launch(options = {}) {
         return this.withLock(async () => {
+            const port = options.port ?? 0;
+            // 如果指定了端口，先尝试连接已运行的浏览器
+            if (port > 0) {
+                try {
+                    const endpoint = await getBrowserWSEndpoint('127.0.0.1', port);
+                    // 连接成功，复用已有浏览器
+                    this.resetState();
+                    this.stealthMode = options.stealth ?? 'safe';
+                    this.cdp = new CDPClient();
+                    await this.cdp.connect(endpoint, options.timeout);
+                    // 记录端口（connect 模式没有 launcher）
+                    this.connectedPort = port;
+                    // 获取现有页面
+                    const targets = await getTargets('127.0.0.1', port);
+                    let pageTarget = targets.find((t) => t.type === 'page');
+                    // 如果没有页面或 attach 失败，创建新 tab
+                    if (pageTarget) {
+                        try {
+                            await this.attachToTargetInternal(pageTarget.id);
+                        }
+                        catch {
+                            // attach 失败，创建新 tab
+                            pageTarget = undefined;
+                        }
+                    }
+                    if (!pageTarget) {
+                        // 创建新 tab（在已有窗口）
+                        const newTarget = await this.newPageInternal();
+                        return {
+                            ...newTarget,
+                            reused: true,
+                        };
+                    }
+                    return {
+                        targetId: pageTarget.id,
+                        type: pageTarget.type,
+                        url: pageTarget.url,
+                        title: pageTarget.title,
+                        reused: true,
+                    };
+                }
+                catch {
+                    // 连接失败，继续启动新浏览器
+                }
+            }
             // 关闭现有会话
-            await this.close();
+            this.resetState();
             // 保存 stealth 模式
             this.stealthMode = options.stealth ?? 'safe';
             // 启动浏览器
@@ -63,7 +121,7 @@ class SessionManager {
                 throw new Error('未找到页面');
             }
             // 附加到页面
-            await this.attachToTarget(pageTarget.id);
+            await this.attachToTargetInternal(pageTarget.id);
             return {
                 targetId: pageTarget.id,
                 type: pageTarget.type,
@@ -77,9 +135,9 @@ class SessionManager {
      */
     async connect(options) {
         return this.withLock(async () => {
-            const { host = '127.0.0.1', port, timeout = 30000, stealth = 'safe' } = options;
+            const { host = '127.0.0.1', port, timeout = DEFAULT_TIMEOUT, stealth = 'safe' } = options;
             // 关闭现有会话
-            await this.close();
+            this.resetState();
             // 保存 stealth 模式
             this.stealthMode = stealth;
             // 获取 WebSocket 端点
@@ -87,6 +145,7 @@ class SessionManager {
             // 连接 CDP
             this.cdp = new CDPClient();
             await this.cdp.connect(endpoint, timeout);
+            this.connectedPort = port;
             // 获取第一个页面
             const targets = await getTargets(host, port);
             const pageTarget = targets.find((t) => t.type === 'page');
@@ -94,7 +153,7 @@ class SessionManager {
                 throw new Error('未找到页面');
             }
             // 附加到页面
-            await this.attachToTarget(pageTarget.id);
+            await this.attachToTargetInternal(pageTarget.id);
             return {
                 targetId: pageTarget.id,
                 type: pageTarget.type,
@@ -120,34 +179,10 @@ class SessionManager {
         }));
     }
     /**
-     * 附加到指定页面
+     * 附加到指定页面（外部入口，加锁）
      */
     async attachToTarget(targetId) {
-        this.ensureConnected();
-        // 如果已经附加到同一个 target，跳过
-        if (this.currentTargetId === targetId && this.sessionId) {
-            return;
-        }
-        // 如果有之前的 session，先分离
-        if (this.sessionId) {
-            try {
-                await this.cdp.send('Target.detachFromTarget', {
-                    sessionId: this.sessionId,
-                });
-            }
-            catch {
-                // 忽略分离错误
-            }
-        }
-        // 附加到目标
-        const { sessionId } = (await this.cdp.send('Target.attachToTarget', {
-            targetId,
-            flatten: true,
-        }));
-        this.sessionId = sessionId;
-        this.currentTargetId = targetId;
-        // 初始化会话
-        await this.initSession();
+        return this.withLock(async () => this.attachToTargetInternal(targetId));
     }
     /**
      * 导航到 URL
@@ -155,9 +190,9 @@ class SessionManager {
     async navigate(url, options = {}) {
         return this.withLock(async () => {
             this.ensureSession();
-            const { wait = 'load', timeout = 30000 } = options;
-            // 导航
-            const { errorText } = (await this.send('Page.navigate', { url }));
+            const { wait = 'load', timeout = DEFAULT_TIMEOUT } = options;
+            // 导航（传 timeout 防止 CDP 默认 30s 截断用户预算）
+            const { errorText } = (await this.send('Page.navigate', { url }, timeout));
             if (errorText) {
                 throw new NavigationTimeoutError(url, timeout);
             }
@@ -177,9 +212,13 @@ class SessionManager {
     }
     /**
      * 等待网络空闲（无进行中的请求且持续指定时间）
+     *
+     * close() 时通过 'disconnected' 信号立即 reject，不必等 timer 超时。
      */
     async waitForNetworkIdle(timeout, idleTime = 500) {
         this.ensureSession();
+        // 捕获当前 cdp 引用，防止 close() 并发置 null 导致回调崩溃
+        const cdp = this.cdp;
         // 使用局部 Set 追踪本次等待的请求，避免污染成员变量
         const localPendingRequests = new Set();
         return new Promise((resolve, reject) => {
@@ -218,56 +257,92 @@ class SessionManager {
                 if (timeoutTimer !== null) {
                     clearTimeout(timeoutTimer);
                 }
-                this.cdp.offEvent('Network.requestWillBeSent', onRequestStart);
-                this.cdp.offEvent('Network.loadingFinished', onRequestEnd);
-                this.cdp.offEvent('Network.loadingFailed', onRequestEnd);
+                cdp.offEvent('Network.requestWillBeSent', onRequestStart);
+                cdp.offEvent('Network.loadingFinished', onRequestEnd);
+                cdp.offEvent('Network.loadingFailed', onRequestEnd);
+                cdp.removeListener('disconnected', onDisconnected);
             };
             // 超时处理
             timeoutTimer = setTimeout(() => {
                 cleanup();
                 reject(new NavigationTimeoutError('networkidle', timeout));
             }, timeout);
+            const onDisconnected = () => {
+                cleanup();
+                reject(new Error('CDP 连接已关闭'));
+            };
+            cdp.once('disconnected', onDisconnected);
             // 监听网络事件
-            this.cdp.onEvent('Network.requestWillBeSent', onRequestStart);
-            this.cdp.onEvent('Network.loadingFinished', onRequestEnd);
-            this.cdp.onEvent('Network.loadingFailed', onRequestEnd);
+            cdp.onEvent('Network.requestWillBeSent', onRequestStart);
+            cdp.onEvent('Network.loadingFinished', onRequestEnd);
+            cdp.onEvent('Network.loadingFailed', onRequestEnd);
             // 初始检查
             checkIdle();
         });
     }
     /**
-     * 等待导航完成（Page.loadEventFired 事件）
+     * 等待导航完成（跨文档导航或同文档导航）
      */
-    async waitForNavigation(timeout = 30000) {
+    async waitForNavigation(timeout = DEFAULT_TIMEOUT) {
         this.ensureSession();
-        await this.cdp.waitForEvent('Page.loadEventFired', undefined, timeout);
+        await this.waitForAnyEvent(['Page.loadEventFired', 'Page.navigatedWithinDocument'], timeout);
     }
     /**
      * 后退
      */
-    async goBack() {
-        this.ensureSession();
-        await this.send('Page.goBack');
-        await this.updateState();
+    async goBack(timeout = DEFAULT_TIMEOUT) {
+        return this.withLock(async () => {
+            this.ensureSession();
+            const { currentIndex, entries } = await this.send('Page.getNavigationHistory', undefined, timeout);
+            if (currentIndex <= 0) {
+                return { navigated: false };
+            }
+            // 跨文档导航触发 loadEventFired，同文档导航（hash/pushState）触发 navigatedWithinDocument
+            const waitPromise = this.waitForAnyEvent(['Page.loadEventFired', 'Page.navigatedWithinDocument'], timeout);
+            // 预注册 rejection handler：若 send() 抛错导致 waitPromise 永远不被 await，
+            // 其 timer reject 不会成为 unhandled rejection（Node 20 默认会退出进程）
+            waitPromise.catch(() => {
+            });
+            await this.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex - 1].id }, timeout);
+            await waitPromise;
+            await this.updateState();
+            return { navigated: true };
+        });
     }
     /**
      * 前进
      */
-    async goForward() {
-        this.ensureSession();
-        await this.send('Page.goForward');
-        await this.updateState();
+    async goForward(timeout = DEFAULT_TIMEOUT) {
+        return this.withLock(async () => {
+            this.ensureSession();
+            const { currentIndex, entries } = await this.send('Page.getNavigationHistory', undefined, timeout);
+            if (currentIndex >= entries.length - 1) {
+                return { navigated: false };
+            }
+            // 跨文档导航触发 loadEventFired，同文档导航（hash/pushState）触发 navigatedWithinDocument
+            const waitPromise = this.waitForAnyEvent(['Page.loadEventFired', 'Page.navigatedWithinDocument'], timeout);
+            waitPromise.catch(() => {
+            });
+            await this.send('Page.navigateToHistoryEntry', { entryId: entries[currentIndex + 1].id }, timeout);
+            await waitPromise;
+            await this.updateState();
+            return { navigated: true };
+        });
     }
     /**
      * 刷新
      */
     async reload(options = {}) {
-        this.ensureSession();
-        const { ignoreCache = false, timeout = 30000 } = options;
-        const waitPromise = this.cdp.waitForEvent('Page.loadEventFired', undefined, timeout);
-        await this.send('Page.reload', { ignoreCache });
-        await waitPromise;
-        await this.updateState();
+        return this.withLock(async () => {
+            this.ensureSession();
+            const { ignoreCache = false, timeout = DEFAULT_TIMEOUT } = options;
+            const waitPromise = this.cdp.waitForEvent('Page.loadEventFired', undefined, timeout);
+            waitPromise.catch(() => {
+            });
+            await this.send('Page.reload', { ignoreCache }, timeout);
+            await waitPromise;
+            await this.updateState();
+        });
     }
     /**
      * 创建定位器
@@ -276,6 +351,7 @@ class SessionManager {
         this.ensureSession();
         return new Locator(this.cdp, target, this.sessionId, {
             ...options,
+            nth: options?.nth ?? target.nth,
             getUrl: () => this.state?.url,
         });
     }
@@ -301,6 +377,7 @@ class SessionManager {
             type: 'mouseMoved',
             x,
             y,
+            modifiers: this.modifiers,
         });
         this.behaviorSimulator.setCurrentPosition({ x, y });
     }
@@ -315,6 +392,7 @@ class SessionManager {
             clickCount: 1,
             x: this.behaviorSimulator.getCurrentPosition().x,
             y: this.behaviorSimulator.getCurrentPosition().y,
+            modifiers: this.modifiers,
         });
     }
     /**
@@ -328,6 +406,7 @@ class SessionManager {
             clickCount: 1,
             x: this.behaviorSimulator.getCurrentPosition().x,
             y: this.behaviorSimulator.getCurrentPosition().y,
+            modifiers: this.modifiers,
         });
     }
     /**
@@ -342,6 +421,7 @@ class SessionManager {
             y: pos.y,
             deltaX,
             deltaY,
+            modifiers: this.modifiers,
         });
     }
     /**
@@ -349,9 +429,13 @@ class SessionManager {
      */
     async keyDown(key) {
         this.ensureSession();
+        if (MODIFIER_KEYS[key]) {
+            this.modifiers |= MODIFIER_KEYS[key];
+        }
         const keyDefinition = getKeyDefinition(key);
         await this.send('Input.dispatchKeyEvent', {
             type: 'keyDown',
+            modifiers: this.modifiers,
             ...keyDefinition,
         });
     }
@@ -363,8 +447,12 @@ class SessionManager {
         const keyDefinition = getKeyDefinition(key);
         await this.send('Input.dispatchKeyEvent', {
             type: 'keyUp',
+            modifiers: this.modifiers,
             ...keyDefinition,
         });
+        if (MODIFIER_KEYS[key]) {
+            this.modifiers &= ~MODIFIER_KEYS[key];
+        }
     }
     /**
      * 输入文本
@@ -374,10 +462,12 @@ class SessionManager {
         for (const char of text) {
             await this.send('Input.dispatchKeyEvent', {
                 type: 'keyDown',
+                modifiers: this.modifiers,
                 text: char,
             });
             await this.send('Input.dispatchKeyEvent', {
                 type: 'keyUp',
+                modifiers: this.modifiers,
                 text: char,
             });
             if (delay > 0) {
@@ -418,8 +508,12 @@ class SessionManager {
     /**
      * 截图
      */
-    async screenshot(fullPage = false) {
+    async screenshot(fullPage = false, scale, format, quality) {
         this.ensureSession();
+        const captureParams = { format: format ?? 'png' };
+        if (quality !== undefined) {
+            captureParams.quality = quality;
+        }
         if (fullPage) {
             // 获取页面完整高度
             const { result } = (await this.send('Runtime.evaluate', {
@@ -431,17 +525,18 @@ class SessionManager {
             await this.send('Emulation.setDeviceMetricsOverride', {
                 width,
                 height,
-                deviceScaleFactor: 1,
+                deviceScaleFactor: scale ?? 1,
                 mobile: false,
             });
+            try {
+                const { data } = (await this.send('Page.captureScreenshot', captureParams));
+                return data;
+            }
+            finally {
+                await this.send('Emulation.clearDeviceMetricsOverride');
+            }
         }
-        const { data } = (await this.send('Page.captureScreenshot', {
-            format: 'png',
-        }));
-        if (fullPage) {
-            // 恢复视口
-            await this.send('Emulation.clearDeviceMetricsOverride');
-        }
+        const { data } = (await this.send('Page.captureScreenshot', captureParams));
         return data;
     }
     /**
@@ -497,10 +592,12 @@ class SessionManager {
     }
     /**
      * 获取 Cookies
+     * @param urls 可选，限制返回指定 URL 的 cookies
      */
-    async getCookies() {
+    async getCookies(urls) {
         this.ensureSession();
-        const { cookies } = (await this.send('Network.getCookies'));
+        const params = urls?.length ? { urls } : {};
+        const { cookies } = (await this.send('Network.getCookies', params));
         return cookies;
     }
     /**
@@ -520,10 +617,10 @@ class SessionManager {
     /**
      * 删除 Cookie
      */
-    async deleteCookie(name) {
+    async deleteCookie(name, url) {
         this.ensureSession();
-        const url = this.state?.url ?? 'http://localhost';
-        await this.send('Network.deleteCookies', { name, url });
+        const effectiveUrl = url ?? this.state?.url ?? 'http://localhost';
+        await this.send('Network.deleteCookies', { name, url: effectiveUrl });
     }
     /**
      * 清除所有 Cookies
@@ -566,17 +663,46 @@ class SessionManager {
      */
     async evaluate(script, args, timeout) {
         this.ensureSession();
-        let expression = script;
+        // CDP 命令超时需大于脚本执行超时，给 WebSocket 通信留余量
+        const CDP_MARGIN = 5000;
+        const sendTimeout = timeout !== undefined ? timeout + CDP_MARGIN : undefined;
+        // 有参数时使用 callFunctionOn：避免大 payload 字符串拼接，参数通过协议结构化传递
         if (args && args.length > 0) {
-            // 将参数序列化并注入
-            const argsStr = args.map((a) => JSON.stringify(a)).join(', ');
-            expression = `(${script})(${argsStr})`;
+            const { result: globalResult } = (await this.send('Runtime.evaluate', {
+                expression: 'globalThis',
+                returnByValue: false,
+            }));
+            try {
+                const callParams = {
+                    functionDeclaration: script,
+                    objectId: globalResult.objectId,
+                    arguments: args.map(a => ({ value: a })),
+                    returnByValue: true,
+                    awaitPromise: true,
+                };
+                if (timeout !== undefined) {
+                    callParams.timeout = timeout;
+                }
+                const { result, exceptionDetails } = (await this.send('Runtime.callFunctionOn', callParams, sendTimeout));
+                if (exceptionDetails) {
+                    throw new Error(exceptionDetails.exception.description);
+                }
+                return result.value;
+            }
+            finally {
+                this.send('Runtime.releaseObject', { objectId: globalResult.objectId }).catch(() => {
+                });
+            }
         }
-        const { result, exceptionDetails } = (await this.send('Runtime.evaluate', {
-            expression,
+        const evalParams = {
+            expression: script,
             returnByValue: true,
             awaitPromise: true,
-        }, timeout));
+        };
+        if (timeout !== undefined) {
+            evalParams.timeout = timeout;
+        }
+        const { result, exceptionDetails } = (await this.send('Runtime.evaluate', evalParams, sendTimeout));
         if (exceptionDetails) {
             throw new Error(exceptionDetails.exception.description);
         }
@@ -622,58 +748,55 @@ class SessionManager {
         }
     }
     /**
-     * 新建页面
+     * 新建页面（外部入口，加锁）
      */
     async newPage() {
+        return this.withLock(async () => this.newPageInternal());
+    }
+    /**
+     * 激活页面（切到前台）
+     */
+    async activateTarget(targetId) {
         this.ensureConnected();
-        const { targetId } = (await this.cdp.send('Target.createTarget', {
-            url: 'about:blank',
-        }));
-        await this.attachToTarget(targetId);
-        return {
-            targetId,
-            type: 'page',
-            url: 'about:blank',
-            title: '',
-        };
+        // Target 域命令是 browser-level，不携带 sessionId
+        await this.cdp.send('Target.activateTarget', { targetId });
     }
     /**
      * 关闭页面
      */
     async closePage(targetId) {
-        this.ensureConnected();
-        const id = targetId ?? this.currentTargetId;
-        if (!id) {
-            throw new TargetNotFoundError('unknown');
-        }
-        await this.cdp.send('Target.closeTarget', { targetId: id });
-        // 如果关闭的是当前页面，清除会话状态
-        if (id === this.currentTargetId) {
-            this.sessionId = null;
-            this.currentTargetId = null;
-            this.state = null;
-        }
+        return this.withLock(async () => {
+            this.ensureConnected();
+            const id = targetId ?? this.currentTargetId;
+            if (!id) {
+                throw new TargetNotFoundError('unknown');
+            }
+            await this.cdp.send('Target.closeTarget', { targetId: id });
+            // 如果关闭的是当前页面，清除会话状态
+            if (id === this.currentTargetId) {
+                this.sessionId = null;
+                this.currentTargetId = null;
+                this.state = null;
+            }
+        });
     }
     /**
-     * 关闭浏览器
+     * 关闭浏览器（外部接口）
+     *
+     * 两阶段关闭：
+     * 1. 立即关闭 CDP 连接：reject 所有 pending callbacks 和 waitForEvent，
+     *    发出 'disconnected' 信号通知 waitForAnyEvent/waitForNetworkIdle 等外部等待者
+     * 2. 通过 withLock 串行化状态清理：等 withLock 中的操作处理完错误后再置空引用
      */
     async close() {
-        // 清除日志
-        this.clearLogs();
-        // 关闭 CDP 连接
+        // Phase 1: 立即关闭 CDP 连接（reject pending callbacks，清除 event listeners）
         if (this.cdp) {
             this.cdp.close();
-            this.cdp = null;
-        }
-        // 关闭浏览器进程
-        if (this.launcher) {
-            this.launcher.close();
-            this.launcher = null;
         }
-        this.sessionId = null;
-        this.currentTargetId = null;
-        this.state = null;
-        this.listenersInstalled = false;
+        // Phase 2: 串行化状态清理（等 withLock 中的操作释放后再执行）
+        await this.withLock(async () => {
+            this.resetState();
+        });
     }
     /**
      * 获取当前状态
@@ -688,10 +811,93 @@ class SessionManager {
         return this.cdp !== null && this.cdp.isConnected;
     }
     /**
-     * 是否有活跃会话
+     * 发送 CDP 命令（page-level，携带 sessionId）
+     *
+     * 每次调用都检查连接状态，防止 close() 并发置空 this.cdp 后崩溃。
+     * 多步操作（type 循环、fullPage 截图等）的 await 间隙可能被 close() 打断，
+     * ensureSession() 确保在当前 tick 内 this.cdp 非空。
      */
-    hasSession() {
-        return this.sessionId !== null;
+    send(method, params, timeout) {
+        this.ensureSession();
+        return this.cdp.send(method, params, this.sessionId ?? undefined, timeout);
+    }
+    /**
+     * 发送 browser-level CDP 命令（不携带 sessionId）
+     * 用于 Target.*、Browser.* 等浏览器级命令
+     */
+    sendBrowserCommand(method, params) {
+        this.ensureConnected();
+        return this.cdp.send(method, params);
+    }
+    /**
+     * 附加到指定页面（内部版本，不加锁，供 launch/connect 等已持锁方法调用）
+     */
+    async attachToTargetInternal(targetId) {
+        this.ensureConnected();
+        // 如果已经附加到同一个 target，跳过
+        if (this.currentTargetId === targetId && this.sessionId) {
+            return;
+        }
+        // 如果有之前的 session，先分离
+        if (this.sessionId) {
+            try {
+                await this.cdp.send('Target.detachFromTarget', {
+                    sessionId: this.sessionId,
+                });
+            }
+            catch {
+                // 忽略分离错误
+            }
+        }
+        // 附加到目标
+        const { sessionId } = (await this.cdp.send('Target.attachToTarget', {
+            targetId,
+            flatten: true,
+        }));
+        this.sessionId = sessionId;
+        this.currentTargetId = targetId;
+        // 初始化会话
+        await this.initSession();
+    }
+    /**
+     * 新建页面（内部版本，不加锁，供 launch 等已持锁方法调用）
+     */
+    async newPageInternal() {
+        this.ensureConnected();
+        const { targetId } = (await this.cdp.send('Target.createTarget', {
+            url: 'about:blank',
+        }));
+        await this.attachToTargetInternal(targetId);
+        return {
+            targetId,
+            type: 'page',
+            url: 'about:blank',
+            title: '',
+        };
+    }
+    /**
+     * 重置所有状态（同步，不加锁）
+     *
+     * 供已持有 withLock 的方法调用（launch/connect），避免 close() 的 withLock 重入死锁。
+     * 外部调用请使用 close()。
+     */
+    resetState() {
+        if (this.cdp) {
+            this.cdp.close();
+            this.cdp = null;
+        }
+        if (this.launcher) {
+            this.launcher.close();
+            this.launcher = null;
+        }
+        this.clearLogs();
+        this.modifiers = 0;
+        this.behaviorSimulator.setCurrentPosition({ x: 0, y: 0 });
+        this.sessionId = null;
+        this.currentTargetId = null;
+        this.state = null;
+        this.listenersInstalled = false;
+        this.connectedPort = 0;
     }
     /**
      * 串行执行操作（防止并发竞态）
@@ -710,6 +916,47 @@ class SessionManager {
             releaseLock();
         }
     }
+    /**
+     * 等待多个事件中的任一个触发
+     *
+     * 用于同时监听跨文档导航 (loadEventFired) 和同文档导航 (navigatedWithinDocument)，
+     * 任一事件触发后清理所有监听器和超时定时器。
+     * close() 时通过 'disconnected' 信号立即 reject，不必等 timer 超时。
+     */
+    waitForAnyEvent(events, timeout) {
+        // 捕获当前 cdp 引用，防止 close() 并发置 null 导致回调崩溃
+        const cdp = this.cdp;
+        if (!cdp) {
+            return Promise.reject(new Error('CDP 连接已关闭'));
+        }
+        return new Promise((resolve, reject) => {
+            const listeners = [];
+            const cleanup = () => {
+                clearTimeout(timer);
+                for (const { event, listener } of listeners) {
+                    cdp.offEvent(event, listener);
+                }
+                cdp.removeListener('disconnected', onDisconnected);
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new NavigationTimeoutError('navigation', timeout));
+            }, timeout);
+            const onDisconnected = () => {
+                cleanup();
+                reject(new Error('CDP 连接已关闭'));
+            };
+            cdp.once('disconnected', onDisconnected);
+            for (const event of events) {
+                const listener = () => {
+                    cleanup();
+                    resolve();
+                };
+                listeners.push({ event, listener });
+                cdp.onEvent(event, listener);
+            }
+        });
+    }
     /**
      * 初始化会话
      */
@@ -808,12 +1055,6 @@ class SessionManager {
             targetId: this.currentTargetId,
         };
     }
-    /**
-     * 发送 CDP 命令
-     */
-    send(method, params, timeout) {
-        return this.cdp.send(method, params, this.sessionId ?? undefined, timeout);
-    }
     /**
      * 确保已连接
      */