@pyrokine/mcp-chrome 1.0.0

package/dist/cdp/launcher.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 浏览器启动器
+ *
+ * 负责启动 Chrome 浏览器进程并获取 CDP 端点
+ */
+import type { LaunchOptions } from '../core/types.js';
+/**
+ * 查找 Chrome 可执行文件
+ */
+export declare function findChrome(): string | null;
+/**
+ * 浏览器启动器
+ */
+export declare class BrowserLauncher {
+    private process;
+    private _port;
+    get port(): number;
+    private _endpoint;
+    get endpoint(): string;
+    get isRunning(): boolean;
+    /**
+     * 启动浏览器
+     */
+    launch(options?: LaunchOptions): Promise<string>;
+    /**
+     * 关闭浏览器
+     */
+    close(): void;
+    /**
+     * 强制关闭浏览器
+     */
+    forceClose(): void;
+    /**
+     * 构建启动参数
+     */
+    private buildArgs;
+    /**
+     * 等待 CDP 端点就绪
+     */
+    private waitForEndpoint;
+}
+//# sourceMappingURL=launcher.d.ts.map

package/dist/cdp/launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/cdp/launcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAA;AAwBnD;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAU1C;AAED;;GAEG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,KAAK,CAA2B;IAExC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,CAAC,SAAS,CAAa;IAE9B,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACG,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IA8B1D;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;OAEG;IACH,UAAU,IAAI,IAAI;IAOlB;;OAEG;IACH,OAAO,CAAC,SAAS;IAmDjB;;OAEG;IACH,OAAO,CAAC,eAAe;CA0C1B"}

package/dist/cdp/launcher.js

@@ -0,0 +1,181 @@
+/**
+ * 浏览器启动器
+ *
+ * 负责启动 Chrome 浏览器进程并获取 CDP 端点
+ */
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { platform } from 'os';
+import { BrowserNotFoundError, TimeoutError } from '../core/errors.js';
+/**
+ * Chrome 可执行文件的常见路径
+ */
+const CHROME_PATHS = {
+    linux: [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+    ],
+    darwin: [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ],
+    win32: [
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+    ],
+};
+/**
+ * 查找 Chrome 可执行文件
+ */
+export function findChrome() {
+    const paths = CHROME_PATHS[platform()] ?? [];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            return p;
+        }
+    }
+    return null;
+}
+/**
+ * 浏览器启动器
+ */
+export class BrowserLauncher {
+    process = null;
+    _port = 0;
+    get port() {
+        return this._port;
+    }
+    _endpoint = '';
+    get endpoint() {
+        return this._endpoint;
+    }
+    get isRunning() {
+        return this.process !== null && !this.process.killed;
+    }
+    /**
+     * 启动浏览器
+     */
+    async launch(options = {}) {
+        const { executablePath, port = 0, incognito = false, headless = false, userDataDir, timeout = 30000, } = options;
+        // 查找 Chrome
+        const chromePath = executablePath ?? findChrome();
+        if (!chromePath) {
+            throw new BrowserNotFoundError();
+        }
+        // 构建启动参数
+        const args = this.buildArgs({ port, incognito, headless, userDataDir });
+        // 启动进程
+        this.process = spawn(chromePath, args, {
+            detached: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // 等待 CDP 端点就绪
+        this._endpoint = await this.waitForEndpoint(timeout);
+        return this._endpoint;
+    }
+    /**
+     * 关闭浏览器
+     */
+    close() {
+        if (this.process && !this.process.killed) {
+            this.process.kill('SIGTERM');
+            this.process = null;
+        }
+    }
+    /**
+     * 强制关闭浏览器
+     */
+    forceClose() {
+        if (this.process && !this.process.killed) {
+            this.process.kill('SIGKILL');
+            this.process = null;
+        }
+    }
+    /**
+     * 构建启动参数
+     */
+    buildArgs(options) {
+        const args = [
+            `--remote-debugging-port=${options.port}`,
+            '--no-first-run',
+            '--no-default-browser-check',
+            '--disable-background-networking',
+            '--disable-background-timer-throttling',
+            '--disable-backgrounding-occluded-windows',
+            '--disable-breakpad',
+            '--disable-component-extensions-with-background-pages',
+            '--disable-component-update',
+            '--disable-default-apps',
+            '--disable-dev-shm-usage',
+            '--disable-extensions',
+            '--disable-features=TranslateUI',
+            '--disable-hang-monitor',
+            '--disable-ipc-flooding-protection',
+            '--disable-popup-blocking',
+            '--disable-prompt-on-repost',
+            '--disable-renderer-backgrounding',
+            '--disable-sync',
+            '--enable-features=NetworkService,NetworkServiceInProcess',
+            '--force-color-profile=srgb',
+            '--metrics-recording-only',
+            '--password-store=basic',
+            '--use-mock-keychain',
+        ];
+        if (options.incognito) {
+            args.push('--incognito');
+        }
+        if (options.headless) {
+            args.push('--headless=new');
+        }
+        if (options.userDataDir) {
+            args.push(`--user-data-dir=${options.userDataDir}`);
+        }
+        // 打开一个空白页
+        args.push('about:blank');
+        return args;
+    }
+    /**
+     * 等待 CDP 端点就绪
+     */
+    waitForEndpoint(timeout) {
+        return new Promise((resolve, reject) => {
+            if (!this.process) {
+                reject(new Error('浏览器进程未启动'));
+                return;
+            }
+            const timer = setTimeout(() => {
+                reject(new TimeoutError(`等待浏览器启动超时 (${timeout}ms)`));
+            }, timeout);
+            let stderr = '';
+            this.process.stderr?.on('data', (data) => {
+                stderr += data.toString();
+                // 解析 DevTools listening on ws://...
+                const match = stderr.match(/DevTools listening on (ws:\/\/[^\s]+)/);
+                if (match) {
+                    clearTimeout(timer);
+                    // 解析端口
+                    const portMatch = match[1].match(/:(\d+)\//);
+                    if (portMatch) {
+                        this._port = parseInt(portMatch[1], 10);
+                    }
+                    resolve(match[1]);
+                }
+            });
+            this.process.on('error', (error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+            this.process.on('exit', (code) => {
+                clearTimeout(timer);
+                if (code !== 0 && code !== null) {
+                    reject(new Error(`浏览器进程退出，代码: ${code}\n${stderr}`));
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=launcher.js.map

package/dist/cdp/launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.js","sourceRoot":"","sources":["../../src/cdp/launcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAe,KAAK,EAAC,MAAM,eAAe,CAAA;AACjD,OAAO,EAAC,UAAU,EAAC,MAAM,IAAI,CAAA;AAC7B,OAAO,EAAC,QAAQ,EAAC,MAAM,IAAI,CAAA;AAC3B,OAAO,EAAC,oBAAoB,EAAE,YAAY,EAAC,MAAM,mBAAmB,CAAA;AAGpE;;GAEG;AACH,MAAM,YAAY,GAA6B;IAC3C,KAAK,EAAE;QACH,wBAAwB;QACxB,+BAA+B;QAC/B,mBAAmB;QACnB,2BAA2B;QAC3B,oBAAoB;KACvB;IACD,MAAM,EAAE;QACJ,8DAA8D;QAC9D,oDAAoD;KACvD;IACD,KAAK,EAAE;QACH,4DAA4D;QAC5D,kEAAkE;QAClE,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,2CAA2C;KACzE;CACJ,CAAA;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACtB,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAA;IAE5C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACpB,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YAChB,OAAO,CAAC,CAAA;QACZ,CAAC;IACL,CAAC;IAED,OAAO,IAAI,CAAA;AACf,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,eAAe;IAChB,OAAO,GAAwB,IAAI,CAAA;IACnC,KAAK,GAA0B,CAAC,CAAA;IAExC,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,KAAK,CAAA;IACrB,CAAC;IAEO,SAAS,GAAW,EAAE,CAAA;IAE9B,IAAI,QAAQ;QACR,OAAO,IAAI,CAAC,SAAS,CAAA;IACzB,CAAC;IAED,IAAI,SAAS;QACT,OAAO,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAA;IACxD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,UAAyB,EAAE;QACpC,MAAM,EACI,cAAc,EACd,IAAI,GAAQ,CAAC,EACb,SAAS,GAAG,KAAK,EACjB,QAAQ,GAAI,KAAK,EACjB,WAAW,EACX,OAAO,GAAK,KAAK,GACpB,GAAG,OAAO,CAAA;QAEjB,YAAY;QACZ,MAAM,UAAU,GAAG,cAAc,IAAI,UAAU,EAAE,CAAA;QACjD,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,MAAM,IAAI,oBAAoB,EAAE,CAAA;QACpC,CAAC;QAED,SAAS;QACT,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAC,CAAC,CAAA;QAErE,OAAO;QACP,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE;YACnC,QAAQ,EAAE,KAAK;YACf,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SACpC,CAAC,CAAA;QAEF,cAAc;QACd,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAA;QACpD,OAAO,IAAI,CAAC,SAAS,CAAA;IACzB,CAAC;IAED;;OAEG;IACH,KAAK;QACD,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACvC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACvB,CAAC;IACL,CAAC;IAED;;OAEG;IACH,UAAU;QACN,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACvC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;YAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACvB,CAAC;IACL,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,OAKjB;QACG,MAAM,IAAI,GAAG;YACT,2BAA2B,OAAO,CAAC,IAAI,EAAE;YACzC,gBAAgB;YAChB,4BAA4B;YAC5B,iCAAiC;YACjC,uCAAuC;YACvC,0CAA0C;YAC1C,oBAAoB;YACpB,sDAAsD;YACtD,4BAA4B;YAC5B,wBAAwB;YACxB,yBAAyB;YACzB,sBAAsB;YACtB,gCAAgC;YAChC,wBAAwB;YACxB,mCAAmC;YACnC,0BAA0B;YAC1B,4BAA4B;YAC5B,kCAAkC;YAClC,gBAAgB;YAChB,0DAA0D;YAC1D,4BAA4B;YAC5B,0BAA0B;YAC1B,wBAAwB;YACxB,qBAAqB;SACxB,CAAA;QAED,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;QAC5B,CAAC;QAED,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;QAC/B,CAAC;QAED,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,IAAI,CAAC,mBAAmB,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;QACvD,CAAC;QAED,UAAU;QACV,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;QAExB,OAAO,IAAI,CAAA;IACf,CAAC;IAED;;OAEG;IACK,eAAe,CAAC,OAAe;QACnC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAA;gBAC7B,OAAM;YACV,CAAC;YAED,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC1B,MAAM,CAAC,IAAI,YAAY,CAAC,cAAc,OAAO,KAAK,CAAC,CAAC,CAAA;YACxD,CAAC,EAAE,OAAO,CAAC,CAAA;YAEX,IAAI,MAAM,GAAG,EAAE,CAAA;YAEf,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;gBAC7C,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAA;gBAEzB,oCAAoC;gBACpC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAA;gBACnE,IAAI,KAAK,EAAE,CAAC;oBACR,YAAY,CAAC,KAAK,CAAC,CAAA;oBACnB,OAAO;oBACP,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;oBAC5C,IAAI,SAAS,EAAE,CAAC;wBACZ,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;oBAC3C,CAAC;oBACD,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;gBACrB,CAAC;YACL,CAAC,CAAC,CAAA;YAEF,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;gBACtC,YAAY,CAAC,KAAK,CAAC,CAAA;gBACnB,MAAM,CAAC,KAAK,CAAC,CAAA;YACjB,CAAC,CAAC,CAAA;YAEF,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC7B,YAAY,CAAC,KAAK,CAAC,CAAA;gBACnB,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;oBAC9B,MAAM,CAAC,IAAI,KAAK,CAAC,eAAe,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC,CAAA;gBACvD,CAAC;YACL,CAAC,CAAC,CAAA;QACN,CAAC,CAAC,CAAA;IACN,CAAC;CACJ"}

package/dist/core/auto-wait.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 自动等待机制
+ *
+ * 参考 Puppeteer Locator 的自动等待：
+ * - waitForEnabled: 等待元素可用
+ * - waitForStableBoundingBox: 等待位置稳定
+ * - ensureInViewport: 确保元素在视口内
+ *
+ * 核心思想：操作前自动检查元素状态，失败则重试，而非立即报错。
+ */
+import type { CDPClient } from '../cdp/client.js';
+/**
+ * AutoWait 选项
+ */
+export interface AutoWaitOptions {
+    /** 超时时间（毫秒），默认 30000 */
+    timeout?: number;
+}
+/**
+ * 自动等待类
+ */
+export declare class AutoWait {
+    private cdp;
+    private sessionId;
+    private timeout;
+    constructor(cdp: CDPClient, sessionId: string, options?: AutoWaitOptions);
+    /**
+     * 等待元素可用（非禁用状态）
+     *
+     * 参考：Puppeteer #waitForEnabledIfNeeded
+     * 对于表单控件（BUTTON, INPUT, SELECT, TEXTAREA），检查是否有 disabled 属性
+     */
+    waitForEnabled(nodeId: number): Promise<void>;
+    /**
+     * 等待元素位置稳定（两帧对比）
+     *
+     * 参考：Puppeteer #waitForStableBoundingBoxIfNeeded
+     * 在两个连续的动画帧中，元素的边界框必须相同
+     */
+    waitForStableBoundingBox(nodeId: number): Promise<void>;
+    /**
+     * 确保元素在视口内
+     *
+     * 参考：Puppeteer #ensureElementIsInTheViewportIfNeeded
+     * 如果元素不在视口内，自动滚动到视口中
+     */
+    ensureInViewport(nodeId: number): Promise<void>;
+    /**
+     * 等待元素可见
+     *
+     * 检查元素的 visibility 不为 hidden，且有非空边界框
+     */
+    waitForVisible(nodeId: number): Promise<void>;
+    /**
+     * 执行点击前的所有等待检查
+     *
+     * 包括：enabled + stableBoundingBox + inViewport
+     */
+    waitForClickable(nodeId: number): Promise<void>;
+    /**
+     * 执行输入前的所有等待检查
+     *
+     * 包括：enabled + stableBoundingBox
+     */
+    waitForInputReady(nodeId: number): Promise<void>;
+    /**
+     * 发送 CDP 命令
+     */
+    private send;
+}
+//# sourceMappingURL=auto-wait.d.ts.map

package/dist/core/auto-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-wait.d.ts","sourceRoot":"","sources":["../../src/core/auto-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,kBAAkB,CAAA;AAG/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;GAEG;AACH,qBAAa,QAAQ;IAIb,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,SAAS;IAJrB,OAAO,CAAC,OAAO,CAAQ;gBAGX,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACzB,OAAO,GAAE,eAAoB;IAKjC;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnD;;;;;OAKG;IACG,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC7D;;;;;OAKG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BrD;;;;OAIG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BnD;;;;OAIG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrD;;;;OAIG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMtD;;OAEG;IACH,OAAO,CAAC,IAAI;CAGf"}

package/dist/core/auto-wait.js

@@ -0,0 +1,165 @@
+/**
+ * 自动等待机制
+ *
+ * 参考 Puppeteer Locator 的自动等待：
+ * - waitForEnabled: 等待元素可用
+ * - waitForStableBoundingBox: 等待位置稳定
+ * - ensureInViewport: 确保元素在视口内
+ *
+ * 核心思想：操作前自动检查元素状态，失败则重试，而非立即报错。
+ */
+import { withRetry } from './retry.js';
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * 自动等待类
+ */
+export class AutoWait {
+    cdp;
+    sessionId;
+    timeout;
+    constructor(cdp, sessionId, options = {}) {
+        this.cdp = cdp;
+        this.sessionId = sessionId;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    }
+    /**
+     * 等待元素可用（非禁用状态）
+     *
+     * 参考：Puppeteer #waitForEnabledIfNeeded
+     * 对于表单控件（BUTTON, INPUT, SELECT, TEXTAREA），检查是否有 disabled 属性
+     */
+    async waitForEnabled(nodeId) {
+        await withRetry(async () => {
+            const { object } = (await this.send('DOM.resolveNode', { nodeId }));
+            const { result } = (await this.send('Runtime.callFunctionOn', {
+                objectId: object.objectId,
+                functionDeclaration: `function() {
+            if (!(this instanceof HTMLElement)) return true;
+            const formControls = ['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
+            if (!formControls.includes(this.nodeName)) return true;
+            return !this.hasAttribute('disabled');
+          }`,
+                returnByValue: true,
+            }));
+            if (!result.value) {
+                throw new Error('元素处于禁用状态');
+            }
+        }, { timeout: this.timeout });
+    }
+    /**
+     * 等待元素位置稳定（两帧对比）
+     *
+     * 参考：Puppeteer #waitForStableBoundingBoxIfNeeded
+     * 在两个连续的动画帧中，元素的边界框必须相同
+     */
+    async waitForStableBoundingBox(nodeId) {
+        await withRetry(async () => {
+            const { object } = (await this.send('DOM.resolveNode', { nodeId }));
+            const { result } = (await this.send('Runtime.callFunctionOn', {
+                objectId: object.objectId,
+                functionDeclaration: `function() {
+            return new Promise((resolve) => {
+              let rect1;
+              requestAnimationFrame(() => {
+                rect1 = this.getBoundingClientRect();
+                requestAnimationFrame(() => {
+                  const rect2 = this.getBoundingClientRect();
+                  const stable = rect1.x === rect2.x && rect1.y === rect2.y &&
+                                 rect1.width === rect2.width && rect1.height === rect2.height;
+                  resolve(stable);
+                });
+              });
+            });
+          }`,
+                returnByValue: true,
+                awaitPromise: true,
+            }));
+            if (!result.value) {
+                throw new Error('元素位置不稳定');
+            }
+        }, { timeout: this.timeout });
+    }
+    /**
+     * 确保元素在视口内
+     *
+     * 参考：Puppeteer #ensureElementIsInTheViewportIfNeeded
+     * 如果元素不在视口内，自动滚动到视口中
+     */
+    async ensureInViewport(nodeId) {
+        const { object } = (await this.send('DOM.resolveNode', { nodeId }));
+        // 检查是否在视口内
+        const { result: isInViewport } = (await this.send('Runtime.callFunctionOn', {
+            objectId: object.objectId,
+            functionDeclaration: `function() {
+        const rect = this.getBoundingClientRect();
+        return rect.top >= 0 && rect.left >= 0 &&
+               rect.bottom <= window.innerHeight &&
+               rect.right <= window.innerWidth;
+      }`,
+            returnByValue: true,
+        }));
+        // 如果不在视口内，滚动到视口中
+        if (!isInViewport.value) {
+            await this.send('Runtime.callFunctionOn', {
+                objectId: object.objectId,
+                functionDeclaration: `function() {
+          this.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
+        }`,
+            });
+            // 等待滚动完成
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    /**
+     * 等待元素可见
+     *
+     * 检查元素的 visibility 不为 hidden，且有非空边界框
+     */
+    async waitForVisible(nodeId) {
+        await withRetry(async () => {
+            const { object } = (await this.send('DOM.resolveNode', { nodeId }));
+            const { result } = (await this.send('Runtime.callFunctionOn', {
+                objectId: object.objectId,
+                functionDeclaration: `function() {
+            const style = window.getComputedStyle(this);
+            if (style.visibility === 'hidden') return false;
+            if (style.display === 'none') return false;
+            const rect = this.getBoundingClientRect();
+            return rect.width > 0 && rect.height > 0;
+          }`,
+                returnByValue: true,
+            }));
+            if (!result.value) {
+                throw new Error('元素不可见');
+            }
+        }, { timeout: this.timeout });
+    }
+    /**
+     * 执行点击前的所有等待检查
+     *
+     * 包括：enabled + stableBoundingBox + inViewport
+     */
+    async waitForClickable(nodeId) {
+        await this.waitForVisible(nodeId);
+        await this.waitForEnabled(nodeId);
+        await this.waitForStableBoundingBox(nodeId);
+        await this.ensureInViewport(nodeId);
+    }
+    /**
+     * 执行输入前的所有等待检查
+     *
+     * 包括：enabled + stableBoundingBox
+     */
+    async waitForInputReady(nodeId) {
+        await this.waitForVisible(nodeId);
+        await this.waitForEnabled(nodeId);
+        await this.waitForStableBoundingBox(nodeId);
+    }
+    /**
+     * 发送 CDP 命令
+     */
+    send(method, params) {
+        return this.cdp.send(method, params, this.sessionId);
+    }
+}
+//# sourceMappingURL=auto-wait.js.map

package/dist/core/auto-wait.js.map

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

package/dist/core/errors.d.ts

@@ -0,0 +1,123 @@
+/**
+ * mcp-chrome 错误类型定义
+ *
+ * 设计原则：
+ * - 每个错误都有明确的 code（便于程序处理）
+ * - 每个错误都有 suggestion（便于用户理解如何修复）
+ * - 每个错误都有 context（便于调试）
+ * - 参考《代码整洁之道》§7.4：给出异常发生的环境说明
+ */
+import type { Target } from './types.js';
+/**
+ * 错误上下文
+ */
+export interface ErrorContext {
+    [key: string]: unknown;
+}
+/**
+ * 浏览器错误基类
+ */
+export declare abstract class BrowserError extends Error {
+    abstract readonly code: string;
+    abstract readonly suggestion: string;
+    readonly context: ErrorContext;
+    constructor(message: string);
+    /**
+     * 转换为 JSON 格式，用于 MCP 响应
+     */
+    toJSON(): object;
+}
+/**
+ * 连接被拒绝错误
+ */
+export declare class ConnectionRefusedError extends BrowserError {
+    readonly code = "CONNECTION_REFUSED";
+    readonly suggestion: string;
+    readonly context: ErrorContext;
+    constructor(host: string, port: number);
+}
+/**
+ * 浏览器未找到错误
+ */
+export declare class BrowserNotFoundError extends BrowserError {
+    readonly code = "BROWSER_NOT_FOUND";
+    readonly suggestion = "\u672A\u627E\u5230 Chrome \u6D4F\u89C8\u5668\u3002\u8BF7\u6307\u5B9A executablePath \u53C2\u6570\uFF1A\n  browse(action=\"launch\", executablePath=\"/path/to/chrome\")";
+    constructor();
+}
+/**
+ * 会话不存在错误
+ */
+export declare class SessionNotFoundError extends BrowserError {
+    readonly code = "SESSION_NOT_FOUND";
+    readonly suggestion = "\u8BF7\u5148\u4F7F\u7528 browse(action=\"launch\") \u6216 browse(action=\"connect\") \u8FDE\u63A5\u6D4F\u89C8\u5668";
+    constructor();
+}
+/**
+ * 页面/Target 不存在错误
+ */
+export declare class TargetNotFoundError extends BrowserError {
+    readonly code = "TARGET_NOT_FOUND";
+    readonly suggestion = "\u8BF7\u4F7F\u7528 browse(action=\"list\") \u67E5\u770B\u53EF\u7528\u9875\u9762";
+    readonly context: ErrorContext;
+    constructor(targetId: string);
+}
+/**
+ * 元素未找到错误
+ */
+export declare class ElementNotFoundError extends BrowserError {
+    readonly code = "ELEMENT_NOT_FOUND";
+    readonly suggestion: string;
+    readonly logs: string[];
+    readonly context: ErrorContext;
+    constructor(target: Target, timeout: number, logs?: string[], url?: string);
+    toJSON(): object;
+}
+/**
+ * 导航超时错误
+ */
+export declare class NavigationTimeoutError extends BrowserError {
+    readonly code = "NAVIGATION_TIMEOUT";
+    readonly suggestion = "\u8BF7\u68C0\u67E5\u7F51\u7EDC\u8FDE\u63A5\uFF0C\u6216\u589E\u52A0\u8D85\u65F6\u65F6\u95F4";
+    readonly context: ErrorContext;
+    constructor(url: string, timeout: number);
+}
+/**
+ * 操作超时错误
+ */
+export declare class TimeoutError extends BrowserError {
+    readonly code = "TIMEOUT";
+    readonly suggestion = "\u8BF7\u589E\u52A0\u8D85\u65F6\u65F6\u95F4\uFF0C\u6216\u68C0\u67E5\u64CD\u4F5C\u6761\u4EF6\u662F\u5426\u80FD\u6EE1\u8DB3";
+    constructor(message: string);
+}
+/**
+ * 无效参数错误
+ */
+export declare class InvalidArgumentError extends BrowserError {
+    readonly code = "INVALID_ARGUMENT";
+    readonly suggestion: string;
+    constructor(message: string, suggestion?: string);
+}
+/**
+ * CDP 协议错误
+ */
+export declare class CDPError extends BrowserError {
+    readonly code = "CDP_ERROR";
+    readonly suggestion = "\u8FD9\u662F\u4E00\u4E2A CDP \u534F\u8BAE\u9519\u8BEF\uFF0C\u8BF7\u68C0\u67E5\u64CD\u4F5C\u662F\u5426\u6B63\u786E";
+    constructor(message: string);
+}
+/**
+ * 格式化日志记录（参考 Playwright Waiter）
+ */
+export declare function formatLogRecording(logs: string[]): string;
+/**
+ * 格式化错误为 MCP 工具响应
+ * 特别处理 ZodError，转换为结构化的 INVALID_ARGUMENT 错误
+ */
+export declare function formatErrorResponse(error: unknown): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError: boolean;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

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