Skip to content

Chrome DevTools for coding agents

chore: resolve DevTools comment nodes to snapshot uids (#2860)

Alex Rudenkod55bb9fe2f1b
diff --git a/src/McpPage.ts b/src/McpPage.ts
index 21a7dafb..b60ccda0 100644
--- a/src/McpPage.ts
+++ b/src/McpPage.ts
@@ -841,12 +841,18 @@ export class McpPage implements ContextPage {
async resolveBackendNodeId(
backendNodeId: number,
): Promise<string | undefined> {
- if (!this.textSnapshot) {
- this.textSnapshot = await TextSnapshot.create(this);
+ let id = this.textSnapshot?.resolveCdpElementId(backendNodeId);
+ if (id) {
+ return id;
}
- let id = this.textSnapshot.resolveCdpElementId(backendNodeId);
- if (!id) {
- this.textSnapshot = await TextSnapshot.create(this);
+ this.textSnapshot = await TextSnapshot.create(this, {
+ verbose: this.textSnapshot?.verbose ?? false,
+ });
+ id = this.textSnapshot.resolveCdpElementId(backendNodeId);
+ if (!id && !this.textSnapshot.verbose) {
+ this.textSnapshot = await TextSnapshot.create(this, {
+ verbose: true,
+ });
id = this.textSnapshot.resolveCdpElementId(backendNodeId);
}
return id;
diff --git a/src/devtools/DevToolsCommentBridge.ts b/src/devtools/DevToolsCommentBridge.ts
index 41e390d6..02004b20 100644
--- a/src/devtools/DevToolsCommentBridge.ts
+++ b/src/devtools/DevToolsCommentBridge.ts
@@ -92,7 +92,7 @@ export class DevToolsCommentBridge {
try {
const result = page.evaluate(() => {
if (window.__onDevToolsCommentListener) {
- window.universe?.cd4aBridge?.removeEventListener?.(
+ window.universe?.cd4aBridge?.removeEventListener(
'CommentThreadsChanged',
window.__onDevToolsCommentListener,
);
diff --git a/src/formatters/CommentFormatter.ts b/src/formatters/CommentFormatter.ts
index 3b9e61a9..0d6e9863 100644
--- a/src/formatters/CommentFormatter.ts
+++ b/src/formatters/CommentFormatter.ts
@@ -60,8 +60,8 @@ export class CommentFormatter {
for (const thread of threads) {
let elementUid: string | undefined;
const resolveBackendNodeId = options?.resolveBackendNodeId;
- if (thread.backendNodeId !== undefined && resolveBackendNodeId) {
- elementUid = await resolveBackendNodeId(thread.backendNodeId);
+ if (thread.node?.backendNodeId !== undefined && resolveBackendNodeId) {
+ elementUid = await resolveBackendNodeId(thread.node.backendNodeId);
}
let reqid: number | undefined;
diff --git a/src/tools/comments.ts b/src/tools/comments.ts
index 4937add8..04981570 100644
--- a/src/tools/comments.ts
+++ b/src/tools/comments.ts
@@ -6,17 +6,12 @@
import {zod} from '../third_party/index.js';
-import type {
- CD4ACommentThread,
- CD4AEditorAnchorSignature,
- CD4ARevealTarget,
-} from '../types.js';
+import type {CD4ACommentThread, CD4ARevealTarget} from '../types.js';
import {ToolCategory} from './categories.js';
import {definePageTool} from './ToolDefinition.js';
export type CommentThreadPayload = CD4ACommentThread;
-export type CommentEditorPayload = CD4AEditorAnchorSignature;
export type RevealTargetPayload = CD4ARevealTarget;
export const openDevtools = definePageTool(() => ({
@@ -198,12 +193,19 @@ export const revealInDevtools = definePageTool(() => ({
}
}
+ const revealTarget: CD4ARevealTarget = {
+ networkRequestId,
+ ...(backendNodeId !== undefined
+ ? {node: {backendNodeId, targetId: targetId ?? ''}}
+ : {}),
+ };
+
await devtoolsPage.evaluate(
- async (panel: string | undefined, target: CD4ARevealTarget) => {
+ async (panel: string, target: CD4ARevealTarget) => {
await window.universe?.cd4aBridge?.reveal(panel, target);
},
- panelName,
- {backendNodeId, targetId, networkRequestId},
+ panelName ?? '',
+ revealTarget,
);
let targetDesc = '';
diff --git a/src/types.ts b/src/types.ts
index 8ded1ee5..8e0d0600 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -4,7 +4,12 @@
* SPDX-License-Identifier: Apache-2.0
*/
-import type {SerializedAXNode, Viewport, Target} from './third_party/index.js';
+import type {
+ SerializedAXNode,
+ Viewport,
+ Target,
+ DevTools,
+} from './third_party/index.js';
export interface ExtensionServiceWorker {
url: string;
@@ -41,51 +46,29 @@ export interface PaginationOptions {
pageIdx?: number;
}
-export interface CD4AEditorAnchorSignature {
- /** 1-based line number for CodeMirror text editor anchors */
- lineNumber: number;
- /** File path associated with the editor */
- filePath?: string;
-}
-
-export interface CD4ACommentThread {
- id: string;
- text: string;
- networkRequestId?: string;
- backendNodeId?: number;
- editor?: CD4AEditorAnchorSignature;
-}
-
-export interface CD4ARevealTarget {
- networkRequestId?: string;
- backendNodeId?: number;
- targetId?: string;
-}
+export type CD4ACommentThread = DevTools.CD4ABridge.CommentThread;
+export type CD4ARevealTarget = DevTools.CD4ABridge.RevealTarget;
export enum CD4ABridgeEvents {
COMMENT_THREADS_CHANGED = 'CommentThreadsChanged',
}
-export interface CD4ABridge {
- dispose?(): void;
- setAgentAttached(value: boolean): void;
- getCommentThreads(): CD4ACommentThread[];
- takeComments(): CD4ACommentThread[];
- resolveCommentThread(threadId: string, replyText?: string): boolean;
- reveal(panelName?: string, target?: CD4ARevealTarget): Promise<void>;
- addEventListener(
- event: CD4ABridgeEvents | 'CommentThreadsChanged' | string,
- listener: () => void,
- ): void;
- removeEventListener?(
- event: CD4ABridgeEvents | 'CommentThreadsChanged' | string,
- listener: () => void,
- ): void;
-}
+/**
+ * Functions evaluated in the DevTools page cannot reference `CD4ABridgeEvents`
+ * at runtime, so they pass the string value instead.
+ */
+export type CD4ABridgeEventName = `${CD4ABridgeEvents}`;
+
+export type CD4ABridge = Omit<
+ DevTools.CD4ABridge.CD4ABridge,
+ 'addEventListener' | 'removeEventListener'
+> & {
+ addEventListener(event: CD4ABridgeEventName, listener: () => void): void;
+ removeEventListener(event: CD4ABridgeEventName, listener: () => void): void;
+};
export type CommentThread = CD4ACommentThread;
export type RevealTarget = CD4ARevealTarget;
-export type EditorAnchorSignature = CD4AEditorAnchorSignature;
declare global {
interface Window {
diff --git a/tests/McpPage.test.ts b/tests/McpPage.test.ts
index d1d2f6b9..59709ca2 100644
--- a/tests/McpPage.test.ts
+++ b/tests/McpPage.test.ts
@@ -898,6 +898,117 @@ describe('McpPage', () => {
});
});
+ describe('resolveBackendNodeId()', () => {
+ afterEach(() => {
+ sinon.restore();
+ });
+
+ function createSnapshotWithNodes(
+ nodes: Array<{id: string; backendNodeId?: number}>,
+ verbose = false,
+ ): TextSnapshot {
+ const idToNode = new Map<string, TextSnapshotNode>();
+ const children: TextSnapshotNode[] = [];
+ for (const n of nodes) {
+ const node: TextSnapshotNode = {
+ id: n.id,
+ role: 'generic',
+ backendNodeId: n.backendNodeId,
+ children: [],
+ elementHandle: async () => null,
+ };
+ idToNode.set(n.id, node);
+ children.push(node);
+ }
+ const rootNode: TextSnapshotNode = {
+ id: '1_0',
+ role: 'root',
+ children,
+ elementHandle: async () => null,
+ };
+ return new TextSnapshot({
+ root: rootNode,
+ idToNode,
+ snapshotId: '1',
+ hasSelectedElement: false,
+ verbose,
+ });
+ }
+
+ it('returns uid from existing textSnapshot without regenerating', async () => {
+ const {mcpPage} = await createMcpPage();
+ mcpPage.textSnapshot = createSnapshotWithNodes([
+ {id: '1_1', backendNodeId: 42},
+ ]);
+ const createStub = sinon.stub(TextSnapshot, 'create');
+
+ const uid = await mcpPage.resolveBackendNodeId(42);
+
+ assert.strictEqual(uid, '1_1');
+ sinon.assert.notCalled(createStub);
+ });
+
+ it('creates textSnapshot when textSnapshot is null', async () => {
+ const {mcpPage} = await createMcpPage();
+ const snapshot = createSnapshotWithNodes([
+ {id: '1_1', backendNodeId: 42},
+ ]);
+ const createStub = sinon.stub(TextSnapshot, 'create').resolves(snapshot);
+
+ const uid = await mcpPage.resolveBackendNodeId(42);
+
+ assert.strictEqual(uid, '1_1');
+ sinon.assert.calledOnceWithExactly(createStub, mcpPage, {verbose: false});
+ assert.strictEqual(mcpPage.textSnapshot, snapshot);
+ });
+
+ it('regenerates textSnapshot when backendNodeId is not in existing snapshot', async () => {
+ const {mcpPage} = await createMcpPage();
+ mcpPage.textSnapshot = createSnapshotWithNodes([
+ {id: '1_1', backendNodeId: 10},
+ ]);
+ const updatedSnapshot = createSnapshotWithNodes([
+ {id: '2_1', backendNodeId: 42},
+ ]);
+ const createStub = sinon
+ .stub(TextSnapshot, 'create')
+ .resolves(updatedSnapshot);
+
+ const uid = await mcpPage.resolveBackendNodeId(42);
+
+ assert.strictEqual(uid, '2_1');
+ sinon.assert.calledOnceWithExactly(createStub, mcpPage, {verbose: false});
+ assert.strictEqual(mcpPage.textSnapshot, updatedSnapshot);
+ });
+
+ it('falls back to verbose textSnapshot when backendNodeId is not in non-verbose snapshot', async () => {
+ const {mcpPage} = await createMcpPage();
+ const nonVerboseSnapshot = createSnapshotWithNodes(
+ [{id: '1_1', backendNodeId: 10}],
+ false,
+ );
+ const verboseSnapshot = createSnapshotWithNodes(
+ [{id: '2_5', backendNodeId: 30}],
+ true,
+ );
+ const createStub = sinon.stub(TextSnapshot, 'create');
+ createStub.onFirstCall().resolves(nonVerboseSnapshot);
+ createStub.onSecondCall().resolves(verboseSnapshot);
+
+ const uid = await mcpPage.resolveBackendNodeId(30);
+
+ assert.strictEqual(uid, '2_5');
+ sinon.assert.calledTwice(createStub);
+ sinon.assert.calledWithExactly(createStub.firstCall, mcpPage, {
+ verbose: false,
+ });
+ sinon.assert.calledWithExactly(createStub.secondCall, mcpPage, {
+ verbose: true,
+ });
+ assert.strictEqual(mcpPage.textSnapshot, verboseSnapshot);
+ });
+ });
+
describe('getMatchedStylesForUid()', () => {
const server = serverHooks();
diff --git a/tests/formatters/CommentFormatter.test.ts b/tests/formatters/CommentFormatter.test.ts
index 8035cd24..120ac8cd 100644
--- a/tests/formatters/CommentFormatter.test.ts
+++ b/tests/formatters/CommentFormatter.test.ts
@@ -60,12 +60,11 @@ describe('CommentFormatter', () => {
const rawThread: CD4ACommentThread = {
id: 'comment-1',
text: 'Fix the color contrast here',
- backendNodeId: 42,
- networkRequestId: 'req-99',
- editor: {
- filePath: 'src/style.css',
- lineNumber: 10,
+ node: {
+ backendNodeId: 42,
+ targetId: 'target-1',
},
+ networkRequestId: 'req-99',
};
const resolveBackendNodeId = sinon.stub().resolves('element-uid-42');
@@ -88,7 +87,10 @@ describe('CommentFormatter', () => {
const rawThread: CD4ACommentThread = {
id: 'comment-2',
text: 'Fix heading font size',
- backendNodeId: 42,
+ node: {
+ backendNodeId: 42,
+ targetId: 'target-1',
+ },
networkRequestId: 'req-99',
};
diff --git a/tests/tools/comments.test.ts b/tests/tools/comments.test.ts
index d0ec362c..6033bfc4 100644
--- a/tests/tools/comments.test.ts
+++ b/tests/tools/comments.test.ts
@@ -64,12 +64,11 @@ describe('comments tools', () => {
const mockThread: CommentThreadPayload = {
id: 'comment-1',
text: 'Fix the color contrast here',
- backendNodeId: 42,
- networkRequestId: 'req-99',
- editor: {
- filePath: 'src/style.css',
- lineNumber: 10,
+ node: {
+ backendNodeId: 42,
+ targetId: 'target-1',
},
+ networkRequestId: 'req-99',
};
bridge.getComments.resolves([mockThread]);