chrome-ai-bridge 1.0.0

package/build/src/PageCollector.js

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class PageCollector {
+    #browser;
+    #initializer;
+    storage = new WeakMap();
+    constructor(browser, initializer) {
+        this.#browser = browser;
+        this.#initializer = initializer;
+    }
+    async init() {
+        const pages = await this.#browser.pages();
+        for (const page of pages) {
+            this.#initializePage(page);
+        }
+        this.#browser.on('targetcreated', async (target) => {
+            const page = await target.page();
+            if (!page) {
+                return;
+            }
+            this.#initializePage(page);
+        });
+    }
+    addPage(page) {
+        this.#initializePage(page);
+    }
+    #initializePage(page) {
+        if (this.storage.has(page)) {
+            return;
+        }
+        page.on('framenavigated', frame => {
+            // Only reset the storage on main frame navigation
+            if (frame !== page.mainFrame()) {
+                return;
+            }
+            this.cleanup(page);
+        });
+        this.#initializer(page, value => {
+            const stored = this.storage.get(page) ?? [];
+            stored.push(value);
+            this.storage.set(page, stored);
+        });
+    }
+    cleanup(page) {
+        const collection = this.storage.get(page) ?? [];
+        // Keep the reference alive
+        collection.length = 0;
+    }
+    getData(page) {
+        return this.storage.get(page) ?? [];
+    }
+}
+export class NetworkCollector extends PageCollector {
+    cleanup(page) {
+        const requests = this.storage.get(page) ?? [];
+        const lastRequestIdx = requests.findLastIndex(request => {
+            return request.frame() === page.mainFrame()
+                ? request.isNavigationRequest()
+                : false;
+        });
+        // Keep all requests since the last navigation request including that
+        // navigation request itself.
+        this.storage.set(page, requests.slice(Math.max(lastRequestIdx, 0)));
+    }
+}

package/build/src/WaitForHelper.js

@@ -0,0 +1,134 @@
+import { logger } from './logger.js';
+export class WaitForHelper {
+    #abortController = new AbortController();
+    #page;
+    #stableDomTimeout;
+    #stableDomFor;
+    #expectNavigationIn;
+    #navigationTimeout;
+    constructor(page, cpuTimeoutMultiplier, networkTimeoutMultiplier) {
+        this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier;
+        this.#stableDomFor = 500 * cpuTimeoutMultiplier;
+        this.#expectNavigationIn = 100 * cpuTimeoutMultiplier;
+        this.#navigationTimeout = 3000 * networkTimeoutMultiplier;
+        this.#page = page;
+    }
+    /**
+     * A wrapper that executes a action and waits for
+     * a potential navigation, after which it waits
+     * for the DOM to be stable before returning.
+     */
+    async waitForStableDom() {
+        const stableDomObserver = await this.#page.evaluateHandle(timeout => {
+            let timeoutId;
+            function callback() {
+                clearTimeout(timeoutId);
+                timeoutId = setTimeout(() => {
+                    domObserver.resolver.resolve();
+                    domObserver.observer.disconnect();
+                }, timeout);
+            }
+            const domObserver = {
+                resolver: Promise.withResolvers(),
+                observer: new MutationObserver(callback),
+            };
+            // It's possible that the DOM is not gonna change so we
+            // need to start the timeout initially.
+            callback();
+            domObserver.observer.observe(document.body, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+            });
+            return domObserver;
+        }, this.#stableDomFor);
+        this.#abortController.signal.addEventListener('abort', async () => {
+            try {
+                await stableDomObserver.evaluate(observer => {
+                    observer.observer.disconnect();
+                    observer.resolver.resolve();
+                });
+                await stableDomObserver.dispose();
+            }
+            catch {
+                // Ignored cleanup errors
+            }
+        });
+        return Promise.race([
+            stableDomObserver.evaluate(async (observer) => {
+                return await observer.resolver.promise;
+            }),
+            this.timeout(this.#stableDomTimeout).then(() => {
+                throw new Error('Timeout');
+            }),
+        ]);
+    }
+    async waitForNavigationStarted() {
+        // Currently Puppeteer does not have API
+        // For when a navigation is about to start
+        const navigationStartedPromise = new Promise(resolve => {
+            const listener = (event) => {
+                if ([
+                    'historySameDocument',
+                    'historyDifferentDocument',
+                    'sameDocument',
+                ].includes(event.navigationType)) {
+                    resolve(false);
+                    return;
+                }
+                resolve(true);
+            };
+            this.#page._client().on('Page.frameStartedNavigating', listener);
+            this.#abortController.signal.addEventListener('abort', () => {
+                resolve(false);
+                this.#page._client().off('Page.frameStartedNavigating', listener);
+            });
+        });
+        return await Promise.race([
+            navigationStartedPromise,
+            this.timeout(this.#expectNavigationIn).then(() => false),
+        ]);
+    }
+    timeout(time) {
+        return new Promise(res => {
+            const id = setTimeout(res, time);
+            this.#abortController.signal.addEventListener('abort', () => {
+                res();
+                clearTimeout(id);
+            });
+        });
+    }
+    async waitForEventsAfterAction(action) {
+        const navigationFinished = this.waitForNavigationStarted()
+            .then(navigationStated => {
+            if (navigationStated) {
+                return this.#page.waitForNavigation({
+                    timeout: this.#navigationTimeout,
+                    signal: this.#abortController.signal,
+                });
+            }
+            return;
+        })
+            .catch(error => logger(error));
+        try {
+            await action();
+        }
+        catch (error) {
+            // Clear up pending promises
+            this.#abortController.abort();
+            throw error;
+        }
+        try {
+            await navigationFinished;
+            // Wait for stable dom after navigation so we execute in
+            // the correct context
+            await this.waitForStableDom();
+        }
+        catch (error) {
+            logger(error);
+        }
+        finally {
+            this.#abortController.abort();
+        }
+    }
+}

package/build/src/browser-connection-manager.js

@@ -0,0 +1,373 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ProtocolError, TimeoutError } from 'puppeteer';
+/**
+ * Default connection manager options
+ */
+const DEFAULT_OPTIONS = {
+    maxReconnectAttempts: 3,
+    initialRetryDelay: 1000, // 1 second
+    maxRetryDelay: 10000, // 10 seconds
+    reconnectOverallTimeoutMs: 30000, // 30 seconds
+    enableLogging: true,
+    onReconnect: undefined,
+};
+/**
+ * Connection state enum
+ */
+var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["CONNECTED"] = "CONNECTED";
+    ConnectionState["RECONNECTING"] = "RECONNECTING";
+    ConnectionState["CLOSED"] = "CLOSED";
+})(ConnectionState || (ConnectionState = {}));
+/**
+ * Browser Connection Manager
+ *
+ * Provides automatic reconnection for CDP operations with:
+ * - Single-flight pattern to prevent concurrent reconnections
+ * - Event-driven detection via browser 'disconnected' event
+ * - State machine tracking (CONNECTED | RECONNECTING | CLOSED)
+ * - Exponential backoff with jitter to prevent thundering herd
+ */
+export class BrowserConnectionManager {
+    reconnectAttempts = 0;
+    options;
+    browser = null;
+    browserFactory = null;
+    /** Single-flight pattern: prevents concurrent reconnection attempts */
+    reconnectInFlight = null;
+    /** Shared reconnection sequence for multiple operations */
+    reconnectSequenceInFlight = null;
+    /** Current connection state */
+    state = ConnectionState.CLOSED;
+    /** Disconnected event handler (arrow function to preserve 'this') */
+    onDisconnected = () => {
+        this.log('Browser disconnected');
+        this.setState(ConnectionState.CLOSED);
+        // Auto-reconnection disabled: reconnect only when MCP operation requires it
+    };
+    constructor(options = {}) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Set browser instance and factory for reconnection
+     *
+     * @param browser - Browser instance to manage
+     * @param factory - Factory function to create new browser instances on reconnection
+     */
+    setBrowser(browser, factory) {
+        // Remove old listener to prevent memory leak
+        if (this.browser) {
+            this.browser.off('disconnected', this.onDisconnected);
+        }
+        this.browser = browser;
+        this.browserFactory = factory;
+        this.state = ConnectionState.CONNECTED;
+        // Event-driven detection: hook into browser 'disconnected' event
+        this.browser.on('disconnected', this.onDisconnected);
+        this.log('Browser instance set, state: CONNECTED');
+    }
+    /**
+     * Execute an operation with automatic retry on CDP connection errors
+     */
+    async executeWithRetry(operation, operationName) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (this.isCDPConnectionError(error)) {
+                this.log(`CDP connection error in ${operationName}, attempting reconnect...`);
+                return await this.retryWithReconnect(operation, operationName);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Trigger reconnection sequence
+     *
+     * Can be called from events (disconnected) or operations (executeWithRetry).
+     * Uses single-flight pattern to prevent duplicate reconnections.
+     *
+     * @param reason - Reason for triggering reconnection
+     * @returns Promise that resolves when reconnection completes
+     */
+    async triggerReconnect(reason) {
+        // Single-flight: return existing sequence if already running
+        if (this.reconnectSequenceInFlight) {
+            this.log(`Reconnection already in progress (${reason}), waiting...`);
+            return this.reconnectSequenceInFlight;
+        }
+        this.log(`Triggering reconnection: ${reason}`);
+        // Overall timeout with AbortController
+        const abortController = new AbortController();
+        const overallTimeout = this.options.reconnectOverallTimeoutMs ?? 30000;
+        const timeoutId = setTimeout(() => {
+            abortController.abort();
+            this.log(`Reconnection overall timeout (${overallTimeout}ms) exceeded`);
+        }, overallTimeout);
+        // Start reconnection sequence
+        this.reconnectSequenceInFlight = this._runReconnectionSequence(abortController.signal).finally(() => {
+            clearTimeout(timeoutId);
+            this.reconnectSequenceInFlight = null;
+        });
+        return this.reconnectSequenceInFlight;
+    }
+    /**
+     * Retry operation with automatic reconnection
+     *
+     * @param operation - Operation to retry
+     * @param operationName - Name of operation for logging
+     * @returns Result of operation
+     */
+    async retryWithReconnect(operation, operationName) {
+        // Use triggerReconnect for unified reconnection logic
+        await this.triggerReconnect(`operation:${operationName}`);
+        this.log(`${operationName}: Reconnection completed, retrying operation...`);
+        return await operation();
+    }
+    /**
+     * Run a full reconnection sequence with exponential backoff
+     *
+     * This is the actual retry loop that multiple operations can share.
+     *
+     * @param signal - AbortSignal to cancel reconnection
+     * @private
+     */
+    async _runReconnectionSequence(signal) {
+        const maxAttempts = this.options.maxReconnectAttempts ?? 3;
+        const initialDelay = this.options.initialRetryDelay ?? 1000;
+        const maxDelay = this.options.maxRetryDelay ?? 10000;
+        const random = this.options.rng ?? Math.random;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            // Check abort signal
+            if (signal?.aborted) {
+                throw new Error('Reconnection aborted: overall timeout exceeded');
+            }
+            this.reconnectAttempts++;
+            const attemptNum = attempt + 1;
+            this.log(`Reconnect attempt ${attemptNum}/${maxAttempts}...`);
+            // Exponential backoff with max delay
+            const baseDelay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
+            // Add jitter: ±20% randomness to prevent thundering herd
+            const jitter = baseDelay * 0.2 * (random() * 2 - 1);
+            const delay = Math.max(0, baseDelay + jitter);
+            this.log(`Waiting ${delay.toFixed(0)}ms before reconnect attempt...`);
+            await this.sleep(delay);
+            // Check abort signal after sleep
+            if (signal?.aborted) {
+                throw new Error('Reconnection aborted: overall timeout exceeded');
+            }
+            try {
+                await this.reconnectBrowser();
+                this.log(`Reconnection successful`);
+                return; // Success!
+            }
+            catch (error) {
+                if (attempt === maxAttempts - 1) {
+                    // Last attempt failed
+                    throw this.createReconnectionFailedError(attemptNum, error);
+                }
+                this.log(`Reconnect attempt ${attemptNum} failed: ${error}`);
+            }
+        }
+        throw new Error('Reconnection logic error'); // Should never reach here
+    }
+    /**
+     * Check if error is a CDP connection error
+     *
+     * Uses type-safe error detection with instanceof checks and falls back
+     * to string matching for compatibility. Also checks method hints.
+     *
+     * @param error - Error to check
+     * @returns true if error is a CDP connection error
+     */
+    isCDPConnectionError(error) {
+        // Type-safe detection using instanceof
+        if (error instanceof ProtocolError || error instanceof TimeoutError) {
+            return true;
+        }
+        const msg = String(error?.message ?? '').toLowerCase();
+        const method = error?.method?.toString?.().toLowerCase?.() ?? '';
+        // Message hints
+        if (/connection closed|session closed|target closed|websocket is not open/.test(msg)) {
+            return true;
+        }
+        // Method hints (CDP methods like 'Target.*')
+        if (/^target\./.test(method)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Reconnect browser instance with single-flight pattern
+     *
+     * Ensures only one reconnection attempt happens at a time.
+     * Multiple concurrent calls will wait for the same reconnection promise.
+     *
+     * @returns Promise that resolves when reconnection is complete
+     */
+    async reconnectBrowser() {
+        // Single-flight pattern: return existing promise if reconnection is already in progress
+        if (this.reconnectInFlight) {
+            this.log('Reconnection already in progress, waiting...');
+            return this.reconnectInFlight;
+        }
+        // Create new reconnection promise
+        this.reconnectInFlight = this._doReconnect();
+        try {
+            await this.reconnectInFlight;
+        }
+        finally {
+            // Clear in-flight promise when complete
+            this.reconnectInFlight = null;
+        }
+    }
+    /**
+     * Internal reconnection logic
+     *
+     * @private
+     */
+    async _doReconnect() {
+        if (!this.browserFactory) {
+            throw new Error('Browser factory not set. Cannot reconnect.');
+        }
+        this.setState(ConnectionState.RECONNECTING);
+        try {
+            // Close old browser if still connected
+            if (this.browser?.isConnected()) {
+                await this.browser.close().catch(() => {
+                    // Ignore errors during close
+                });
+            }
+        }
+        catch (error) {
+            // Ignore errors during cleanup
+        }
+        // Create new browser instance
+        const newBrowser = await this.browserFactory();
+        this.browser = newBrowser;
+        // Re-attach disconnected event handler
+        this.browser.on('disconnected', this.onDisconnected);
+        this.setState(ConnectionState.CONNECTED);
+        this.log('Browser reconnected successfully');
+        // Notify callback if provided
+        if (this.options.onReconnect) {
+            await this.options.onReconnect(newBrowser);
+        }
+    }
+    /**
+     * Create user-friendly error for reconnection failure
+     */
+    createReconnectionFailedError(attempts, lastError) {
+        const message = `
+❌ Chrome DevTools接続エラー
+
+${attempts}回の再接続を試みましたが、Chrome DevToolsとの接続を回復できませんでした。
+
+📋 最後のエラー:
+${lastError?.message || 'Unknown error'}
+
+🔧 解決方法:
+1. Claude Codeを再起動してください
+2. Chromeブラウザを完全に終了して再起動してください
+3. chrome://extensions でChrome DevTools拡張機能を確認してください
+
+詳細: docs/troubleshooting.md#cdp-connection-error
+    `.trim();
+        const error = new Error(message);
+        error.name = 'CDPReconnectionError';
+        return error;
+    }
+    /**
+     * Set connection state and log transition
+     *
+     * @param newState - New connection state
+     */
+    setState(newState) {
+        if (this.state !== newState) {
+            this.log(`State transition: ${this.state} -> ${newState}`);
+            this.state = newState;
+        }
+    }
+    /**
+     * Log message if logging is enabled
+     *
+     * @param message - Message to log
+     */
+    log(message) {
+        if (this.options.enableLogging !== false) {
+            console.log(`[ConnectionManager] ${message}`);
+        }
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Get current browser instance
+     */
+    getBrowser() {
+        return this.browser;
+    }
+    /**
+     * Get total reconnection attempts made
+     */
+    getReconnectAttempts() {
+        return this.reconnectAttempts;
+    }
+    /**
+     * Reset reconnection attempt counter
+     */
+    resetReconnectAttempts() {
+        this.reconnectAttempts = 0;
+    }
+    /**
+     * Check if browser is currently connected
+     *
+     * @returns true if browser is connected
+     */
+    isConnected() {
+        return this.browser?.isConnected() ?? false;
+    }
+    /**
+     * Get current connection state
+     *
+     * @returns Current connection state (CONNECTED | RECONNECTING | CLOSED)
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Check if reconnection is currently in progress
+     *
+     * @returns true if reconnection is in progress
+     */
+    isReconnecting() {
+        return this.state === ConnectionState.RECONNECTING;
+    }
+}
+/**
+ * Global connection manager instance
+ */
+let globalConnectionManager = null;
+/**
+ * Get or create global connection manager
+ */
+export function getConnectionManager(options) {
+    if (!globalConnectionManager) {
+        globalConnectionManager = new BrowserConnectionManager(options);
+    }
+    return globalConnectionManager;
+}
+/**
+ * Reset global connection manager (for testing)
+ */
+export function resetConnectionManager() {
+    globalConnectionManager = null;
+}