@vibebrowser/chrome-devtools-mcp 0.26.0

package/build/src/Mutex.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class Mutex {
+    static Guard = class Guard {
+        #mutex;
+        constructor(mutex) {
+            this.#mutex = mutex;
+        }
+        dispose() {
+            return this.#mutex.release();
+        }
+    };
+    #locked = false;
+    #acquirers = [];
+    // This is FIFO.
+    async acquire() {
+        if (!this.#locked) {
+            this.#locked = true;
+            return new Mutex.Guard(this);
+        }
+        const { resolve, promise } = Promise.withResolvers();
+        this.#acquirers.push(resolve);
+        await promise;
+        return new Mutex.Guard(this);
+    }
+    release() {
+        const resolve = this.#acquirers.shift();
+        if (!resolve) {
+            this.#locked = false;
+            return;
+        }
+        resolve();
+    }
+}
+//# sourceMappingURL=Mutex.js.map

package/build/src/PageCollector.js

@@ -0,0 +1,297 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FakeIssuesManager } from './DevtoolsUtils.js';
+import { logger } from './logger.js';
+import { DevTools } from './third_party/index.js';
+import { createIdGenerator, stableIdSymbol, } from './utils/id.js';
+export class UncaughtError {
+    details;
+    targetId;
+    constructor(details, targetId) {
+        this.details = details;
+        this.targetId = targetId;
+    }
+}
+export class PageCollector {
+    #browser;
+    #listenersInitializer;
+    #listeners = new WeakMap();
+    maxNavigationSaved = 3;
+    /**
+     * This maps a Page to a list of navigations with a sub-list
+     * of all collected resources.
+     * The newer navigations come first.
+     */
+    storage = new WeakMap();
+    constructor(browser, listeners) {
+        this.#browser = browser;
+        this.#listenersInitializer = listeners;
+    }
+    async init(pages) {
+        for (const page of pages) {
+            this.addPage(page);
+        }
+        this.#browser.on('targetcreated', this.#onTargetCreated);
+        this.#browser.on('targetdestroyed', this.#onTargetDestroyed);
+    }
+    dispose() {
+        this.#browser.off('targetcreated', this.#onTargetCreated);
+        this.#browser.off('targetdestroyed', this.#onTargetDestroyed);
+    }
+    #onTargetCreated = async (target) => {
+        try {
+            const page = await target.page();
+            if (!page) {
+                return;
+            }
+            this.addPage(page);
+        }
+        catch (err) {
+            logger('Error getting a page for a target onTargetCreated', err);
+        }
+    };
+    #onTargetDestroyed = async (target) => {
+        try {
+            const page = await target.page();
+            if (!page) {
+                return;
+            }
+            this.cleanupPageDestroyed(page);
+        }
+        catch (err) {
+            logger('Error getting a page for a target onTargetDestroyed', err);
+        }
+    };
+    addPage(page) {
+        this.#initializePage(page);
+    }
+    #initializePage(page) {
+        if (this.storage.has(page)) {
+            return;
+        }
+        const idGenerator = createIdGenerator();
+        const storedLists = [[]];
+        this.storage.set(page, storedLists);
+        const listeners = this.#listenersInitializer(value => {
+            const withId = value;
+            withId[stableIdSymbol] = idGenerator();
+            const navigations = this.storage.get(page) ?? [[]];
+            navigations[0].push(withId);
+        });
+        listeners['framenavigated'] = (frame) => {
+            // Only split the storage on main frame navigation
+            if (frame !== page.mainFrame()) {
+                return;
+            }
+            this.splitAfterNavigation(page);
+        };
+        for (const [name, listener] of Object.entries(listeners)) {
+            page.on(name, listener);
+        }
+        this.#listeners.set(page, listeners);
+    }
+    splitAfterNavigation(page) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            return;
+        }
+        // Add the latest navigation first
+        navigations.unshift([]);
+        navigations.splice(this.maxNavigationSaved);
+    }
+    cleanupPageDestroyed(page) {
+        const listeners = this.#listeners.get(page);
+        if (listeners) {
+            for (const [name, listener] of Object.entries(listeners)) {
+                page.off(name, listener);
+            }
+        }
+        this.storage.delete(page);
+    }
+    getData(page, includePreservedData) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            return [];
+        }
+        if (!includePreservedData) {
+            return navigations[0];
+        }
+        const data = [];
+        for (let index = this.maxNavigationSaved; index >= 0; index--) {
+            if (navigations[index]) {
+                data.push(...navigations[index]);
+            }
+        }
+        return data;
+    }
+    getIdForResource(resource) {
+        return resource[stableIdSymbol] ?? -1;
+    }
+    getById(page, stableId) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            throw new Error('No requests found for selected page');
+        }
+        const item = this.find(page, item => item[stableIdSymbol] === stableId);
+        if (item) {
+            return item;
+        }
+        throw new Error('Request not found for selected page');
+    }
+    find(page, filter) {
+        const navigations = this.storage.get(page);
+        if (!navigations) {
+            return;
+        }
+        for (const navigation of navigations) {
+            const item = navigation.find(filter);
+            if (item) {
+                return item;
+            }
+        }
+        return;
+    }
+}
+export class ConsoleCollector extends PageCollector {
+    #subscribedPages = new WeakMap();
+    addPage(page) {
+        super.addPage(page);
+        if (!this.#subscribedPages.has(page)) {
+            const subscriber = new PageEventSubscriber(page);
+            this.#subscribedPages.set(page, subscriber);
+            void subscriber.subscribe();
+        }
+    }
+    cleanupPageDestroyed(page) {
+        super.cleanupPageDestroyed(page);
+        this.#subscribedPages.get(page)?.unsubscribe();
+        this.#subscribedPages.delete(page);
+    }
+}
+class PageEventSubscriber {
+    #issueManager = new FakeIssuesManager();
+    #issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
+    #seenKeys = new Set();
+    #seenIssues = new Set();
+    #page;
+    #session;
+    #targetId;
+    constructor(page) {
+        this.#page = page;
+        // @ts-expect-error use existing CDP client (internal Puppeteer API).
+        this.#session = this.#page._client();
+        // @ts-expect-error use internal Puppeteer API to get target ID
+        this.#targetId = this.#session.target()._targetId;
+    }
+    #resetIssueAggregator() {
+        this.#issueManager = new FakeIssuesManager();
+        if (this.#issueAggregator) {
+            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
+        }
+        this.#issueAggregator = new DevTools.IssueAggregator(this.#issueManager);
+        this.#issueAggregator.addEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
+    }
+    async subscribe() {
+        this.#resetIssueAggregator();
+        this.#page.on('framenavigated', this.#onFrameNavigated);
+        this.#page.on('issue', this.#onIssueAdded);
+        this.#session.on('Runtime.exceptionThrown', this.#onExceptionThrown);
+    }
+    unsubscribe() {
+        this.#seenKeys.clear();
+        this.#seenIssues.clear();
+        this.#page.off('framenavigated', this.#onFrameNavigated);
+        this.#page.off('issue', this.#onIssueAdded);
+        this.#session.off('Runtime.exceptionThrown', this.#onExceptionThrown);
+        if (this.#issueAggregator) {
+            this.#issueAggregator.removeEventListener("AggregatedIssueUpdated" /* DevTools.IssueAggregatorEvents.AGGREGATED_ISSUE_UPDATED */, this.#onAggregatedIssue);
+        }
+    }
+    #onAggregatedIssue = (event) => {
+        if (this.#seenIssues.has(event.data)) {
+            return;
+        }
+        this.#seenIssues.add(event.data);
+        this.#page.emit('devtoolsAggregatedIssue', event.data);
+    };
+    #onExceptionThrown = (event) => {
+        this.#page.emit('uncaughtError', new UncaughtError(event.exceptionDetails, this.#targetId));
+    };
+    // On navigation, we reset issue aggregation.
+    #onFrameNavigated = (frame) => {
+        // Only split the storage on main frame navigation
+        if (frame !== frame.page().mainFrame()) {
+            return;
+        }
+        this.#seenKeys.clear();
+        this.#seenIssues.clear();
+        this.#resetIssueAggregator();
+    };
+    #onIssueAdded = (inspectorIssue) => {
+        try {
+            // DevTools currently defines this protocol issue code but has no
+            // IssuesManager handler for it, so calling into the mapper only warns.
+            if (String(inspectorIssue.code) === 'PerformanceIssue') {
+                return;
+            }
+            const issue = DevTools.createIssuesFromProtocolIssue(null, 
+            // @ts-expect-error Protocol types diverge.
+            inspectorIssue)[0];
+            if (!issue) {
+                logger('No issue mapping for for the issue: ', inspectorIssue.code);
+                return;
+            }
+            const primaryKey = issue.primaryKey();
+            if (this.#seenKeys.has(primaryKey)) {
+                return;
+            }
+            this.#seenKeys.add(primaryKey);
+            this.#issueManager.dispatchEventToListeners("IssueAdded" /* DevTools.IssuesManagerEvents.ISSUE_ADDED */, {
+                issue,
+                // @ts-expect-error We don't care that issues model is null
+                issuesModel: null,
+            });
+        }
+        catch (error) {
+            logger('Error creating a new issue', error);
+        }
+    };
+}
+export class NetworkCollector extends PageCollector {
+    constructor(browser, listeners = collect => {
+        return {
+            request: req => {
+                collect(req);
+            },
+        };
+    }) {
+        super(browser, listeners);
+    }
+    splitAfterNavigation(page) {
+        const navigations = this.storage.get(page) ?? [];
+        if (!navigations) {
+            return;
+        }
+        const requests = navigations[0];
+        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.
+        // Keep the reference
+        if (lastRequestIdx !== -1) {
+            const fromCurrentNavigation = requests.splice(lastRequestIdx);
+            navigations.unshift(fromCurrentNavigation);
+        }
+        else {
+            navigations.unshift([]);
+        }
+        navigations.splice(this.maxNavigationSaved);
+    }
+}
+//# sourceMappingURL=PageCollector.js.map

package/build/src/SlimMcpResponse.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { McpResponse } from './McpResponse.js';
+export class SlimMcpResponse extends McpResponse {
+    async handle(_toolName, _context) {
+        const text = {
+            type: 'text',
+            text: this.responseLines.join('\n'),
+        };
+        return {
+            content: [text],
+            structuredContent: text,
+        };
+    }
+}
+//# sourceMappingURL=SlimMcpResponse.js.map

package/build/src/TextSnapshot.js

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from './logger.js';
+export class TextSnapshot {
+    static nextSnapshotId = 1;
+    static resetCounter() {
+        TextSnapshot.nextSnapshotId = 1;
+    }
+    root;
+    idToNode;
+    snapshotId;
+    selectedElementUid;
+    hasSelectedElement;
+    verbose;
+    constructor(data) {
+        this.root = data.root;
+        this.idToNode = data.idToNode;
+        this.snapshotId = data.snapshotId;
+        this.selectedElementUid = data.selectedElementUid;
+        this.hasSelectedElement = data.hasSelectedElement;
+        this.verbose = data.verbose;
+    }
+    static async create(page, options = {}) {
+        const verbose = options.verbose ?? false;
+        const rootNode = await page.pptrPage.accessibility.snapshot({
+            includeIframes: true,
+            interestingOnly: !verbose,
+        });
+        if (!rootNode) {
+            throw new Error('Failed to create accessibility snapshot');
+        }
+        const { uniqueBackendNodeIdToMcpId } = page;
+        const snapshotId = TextSnapshot.nextSnapshotId++;
+        // Iterate through the whole accessibility node tree and assign node ids that
+        // will be used for the tree serialization and mapping ids back to nodes.
+        let idCounter = 0;
+        const idToNode = new Map();
+        const seenUniqueIds = new Set();
+        const seenBackendNodeIds = new Set();
+        const assignIds = (node) => {
+            let id = '';
+            // @ts-expect-error untyped backendNodeId.
+            const backendNodeId = node.backendNodeId;
+            // @ts-expect-error untyped loaderId.
+            const uniqueBackendId = `${node.loaderId}_${backendNodeId}`;
+            const existingMcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+            if (existingMcpId !== undefined) {
+                // Re-use MCP exposed ID if the uniqueId is the same.
+                id = existingMcpId;
+            }
+            else {
+                // Only generate a new ID if we have not seen the node before.
+                id = `${snapshotId}_${idCounter++}`;
+                uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+            }
+            seenUniqueIds.add(uniqueBackendId);
+            seenBackendNodeIds.add(backendNodeId);
+            const nodeWithId = {
+                ...node,
+                id,
+                children: node.children
+                    ? node.children.map(child => assignIds(child))
+                    : [],
+            };
+            // The AXNode for an option doesn't contain its `value`.
+            // Therefore, set text content of the option as value.
+            if (node.role === 'option') {
+                const optionText = node.name;
+                if (optionText) {
+                    nodeWithId.value = optionText.toString();
+                }
+            }
+            idToNode.set(nodeWithId.id, nodeWithId);
+            return nodeWithId;
+        };
+        const rootNodeWithId = assignIds(rootNode);
+        await TextSnapshot.insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, options.extraHandles ?? []);
+        const snapshot = new TextSnapshot({
+            root: rootNodeWithId,
+            snapshotId: String(snapshotId),
+            idToNode,
+            hasSelectedElement: false,
+            verbose,
+        });
+        const data = options.devtoolsData ?? (await page.getDevToolsData());
+        if (data?.cdpBackendNodeId) {
+            snapshot.hasSelectedElement = true;
+            snapshot.selectedElementUid = page.resolveCdpElementId(data.cdpBackendNodeId);
+        }
+        // Clean up unique IDs that we did not see anymore.
+        for (const key of uniqueBackendNodeIdToMcpId.keys()) {
+            if (!seenUniqueIds.has(key)) {
+                uniqueBackendNodeIdToMcpId.delete(key);
+            }
+        }
+        return snapshot;
+    }
+    // ExtraHandles represent DOM nodes which might not be part of the accessibility tree, e.g. DOM nodes
+    // returned by third-party developer tools. We insert them into the tree by finding the closest ancestor
+    // in the tree and inserting the node as a child. The ancestor's child nodes are re-parented if necessary.
+    static async insertExtraNodes(page, idToNode, seenUniqueIds, snapshotId, idCounter, rootNodeWithId, seenBackendNodeIds, extraHandles) {
+        const { uniqueBackendNodeIdToMcpId } = page;
+        const createExtraNode = async (handle) => {
+            const backendNodeId = await handle.backendNodeId();
+            if (!backendNodeId || seenBackendNodeIds.has(backendNodeId)) {
+                return null;
+            }
+            const uniqueBackendId = `custom_${backendNodeId}`;
+            if (seenUniqueIds.has(uniqueBackendId)) {
+                return null;
+            }
+            seenBackendNodeIds.add(backendNodeId);
+            let id = '';
+            const mcpId = uniqueBackendNodeIdToMcpId.get(uniqueBackendId);
+            if (mcpId !== undefined) {
+                id = mcpId;
+            }
+            else {
+                id = `${snapshotId}_${idCounter++}`;
+                uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);
+            }
+            seenUniqueIds.add(uniqueBackendId);
+            const tagHandle = await handle.getProperty('localName');
+            const tagValue = await tagHandle.jsonValue();
+            const extraNode = {
+                role: tagValue,
+                id,
+                backendNodeId,
+                children: [],
+                elementHandle: async () => handle,
+            };
+            return extraNode;
+        };
+        const findAncestorNode = async (handle) => {
+            let ancestorHandle = await handle.evaluateHandle(el => el.parentElement);
+            while (ancestorHandle) {
+                const ancestorElement = ancestorHandle.asElement();
+                if (!ancestorElement) {
+                    await ancestorHandle.dispose();
+                    return null;
+                }
+                const ancestorBackendId = await ancestorElement.backendNodeId();
+                if (ancestorBackendId) {
+                    const ancestorNode = idToNode
+                        .values()
+                        .find(node => node.backendNodeId === ancestorBackendId);
+                    if (ancestorNode) {
+                        await ancestorHandle.dispose();
+                        return ancestorNode;
+                    }
+                }
+                const nextHandle = await ancestorElement.evaluateHandle(el => el.parentElement);
+                await ancestorHandle.dispose();
+                ancestorHandle = nextHandle;
+            }
+            return null;
+        };
+        const findDescendantNodes = async (backendNodeId) => {
+            const descendantIds = new Set();
+            if (!backendNodeId) {
+                return descendantIds;
+            }
+            try {
+                // @ts-expect-error internal API
+                const client = page.pptrPage._client();
+                if (client) {
+                    const { node } = await client.send('DOM.describeNode', {
+                        backendNodeId,
+                        depth: -1,
+                        pierce: true,
+                    });
+                    const collect = (node) => {
+                        if (node.backendNodeId && node.backendNodeId !== backendNodeId) {
+                            descendantIds.add(node.backendNodeId);
+                        }
+                        if (node.children) {
+                            for (const child of node.children) {
+                                collect(child);
+                            }
+                        }
+                    };
+                    collect(node);
+                }
+            }
+            catch (e) {
+                logger(`Failed to collect descendants for backend node ${backendNodeId}`, e);
+            }
+            return descendantIds;
+        };
+        const moveChildNodes = (attachTarget, extraNode, descendantIds) => {
+            let firstMovedIndex = -1;
+            if (descendantIds.size > 0 && attachTarget.children) {
+                const remainingChildren = [];
+                for (const child of attachTarget.children) {
+                    if (child.backendNodeId && descendantIds.has(child.backendNodeId)) {
+                        if (firstMovedIndex === -1) {
+                            firstMovedIndex = remainingChildren.length;
+                        }
+                        extraNode.children.push(child);
+                    }
+                    else {
+                        remainingChildren.push(child);
+                    }
+                }
+                attachTarget.children = remainingChildren;
+            }
+            return firstMovedIndex !== -1
+                ? firstMovedIndex
+                : attachTarget.children
+                    ? attachTarget.children.length
+                    : 0;
+        };
+        if (extraHandles.length) {
+            page.extraHandles = extraHandles;
+        }
+        const reorgInfo = [];
+        for (const handle of page.extraHandles) {
+            const extraNode = await createExtraNode(handle);
+            if (!extraNode) {
+                continue;
+            }
+            idToNode.set(extraNode.id, extraNode);
+            const attachTarget = (await findAncestorNode(handle)) || rootNodeWithId;
+            const descendantIds = await findDescendantNodes(extraNode.backendNodeId);
+            reorgInfo.push({ extraNode, attachTarget, descendantIds });
+        }
+        for (const { extraNode, attachTarget, descendantIds } of reorgInfo) {
+            const index = moveChildNodes(attachTarget, extraNode, descendantIds);
+            attachTarget.children.splice(index, 0, extraNode);
+        }
+    }
+}
+//# sourceMappingURL=TextSnapshot.js.map