feat: let evaluate_script skip stable DOM wait

docs/tool-reference.md

@@ -358,6 +358,7 @@
 - **args** (array) _(optional)_: An optional list of arguments to pass to the function.
 - **dialogAction** (string) _(optional)_: Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.
 - **filePath** (string) _(optional)_: The absolute or relative path to a file to save the script output to. If omitted, the output is returned inline.
+- **waitForStableDom** (boolean) _(optional)_: Whether to wait for the DOM to become stable after the script runs. Set to false for read-only scripts on pages with continuous DOM mutations. Defaults to true.
 
 ---
 

src/McpPage.ts

@@ -261,6 +261,7 @@ export class McpPage implements ContextPage {
     action: () => Promise<unknown>,
     options?: {
       timeout?: number;
+      waitForStableDom?: boolean;
       handleDialog?:
         DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;
     },

src/WaitForHelper.ts

@@ -134,6 +134,7 @@ export class WaitForHelper {
     action: () => Promise<unknown>,
     options?: {
       timeout?: number;
+      waitForStableDom?: boolean;
       handleDialog?:
         DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;
     },
@@ -199,7 +200,9 @@ export class WaitForHelper {
 
       // Wait for stable dom after navigation so we execute in
       // the correct context
-      await this.waitForStableDom();
+      if (options?.waitForStableDom !== false) {
+        await this.waitForStableDom();
+      }
     } catch (error) {
       logger?.(error);
     } finally {

src/bin/chrome-devtools-cli-options.ts

@@ -249,6 +249,13 @@ export const commands: Commands = {
           'Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.',
         required: false,
       },
+      waitForStableDom: {
+        name: 'waitForStableDom',
+        type: 'boolean',
+        description:
+          'Whether to wait for the DOM to become stable after the script runs. Set to false for read-only scripts on pages with continuous DOM mutations. Defaults to true.',
+        required: false,
+      },
     },
   },
   execute_3p_developer_tool: {

src/telemetry/tool_call_metrics.json

@@ -119,6 +119,10 @@
       {
         "name": "file_path_length",
         "argType": "number"
+      },
+      {
+        "name": "wait_for_stable_dom",
+        "argType": "boolean"
       }
     ]
   },

src/tools/ToolDefinition.ts

@@ -301,6 +301,7 @@ export type ContextPage = Readonly<{
     action: () => Promise<unknown>,
     options?: {
       timeout?: number;
+      waitForStableDom?: boolean;
       handleDialog?:
         DialogAction | Partial<Record<Protocol.Page.DialogType, DialogAction>>;
     },

src/tools/script.ts

@@ -52,6 +52,12 @@ Example with arguments: \`(el) => el.innerText\`
         .describe(
           'Handle dialogs while execution. "accept", "dismiss", or string for response of window.prompt. Defaults to accept.',
         ),
+      waitForStableDom: zod
+        .boolean()
+        .optional()
+        .describe(
+          'Whether to wait for the DOM to become stable after the script runs. Set to false for read-only scripts on pages with continuous DOM mutations. Defaults to true.',
+        ),
       ...(cliArgs?.categoryExtensions
         ? {
             serviceWorkerId: zod
@@ -73,6 +79,7 @@ Example with arguments: \`(el) => el.innerText\`
         pageId,
         dialogAction,
         filePath,
+        waitForStableDom,
       } = request.params;
 
       if (cliArgs?.categoryExtensions && serviceWorkerId) {
@@ -95,7 +102,10 @@ Example with arguments: \`(el) => el.innerText\`
                 context,
               });
             },
-            {handleDialog: dialogAction ?? 'accept'},
+            {
+              handleDialog: dialogAction ?? 'accept',
+              waitForStableDom,
+            },
           );
         if (result.dialogHandled) {
           context.getSelectedMcpPage().clearDialog();
@@ -127,7 +137,10 @@ Example with arguments: \`(el) => el.innerText\`
               context,
             });
           },
-          {handleDialog: dialogAction ?? 'accept'},
+          {
+            handleDialog: dialogAction ?? 'accept',
+            waitForStableDom,
+          },
         );
         response.attachWaitForResult(result);
       } finally {

tests/tools/script.test.ts

@@ -8,6 +8,8 @@ import assert from 'node:assert';
 import path from 'node:path';
 import {describe, it} from 'node:test';
 
+import sinon from 'sinon';
+
 import type {ParsedArguments} from '../../src/bin/chrome-devtools-mcp-cli-options.js';
 import {TextSnapshot} from '../../src/TextSnapshot.js';
 import {installExtension} from '../../src/tools/extensions.js';
@@ -196,6 +198,40 @@ describe('script', () => {
       });
     });
 
+    it('can skip waiting for a stable DOM', async () => {
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedMcpPage();
+        const waitForEventsAfterAction = sinon
+          .stub(page, 'waitForEventsAfterAction')
+          .callsFake(async action => {
+            await action();
+            return {};
+          });
+
+        try {
+          await evaluateScript().handler(
+            {
+              params: {
+                function: String(() => document.title),
+                waitForStableDom: false,
+              },
+            },
+            response,
+            context,
+          );
+        } finally {
+          waitForEventsAfterAction.restore();
+        }
+
+        assert.strictEqual(
+          waitForEventsAfterAction.firstCall.args[1]?.waitForStableDom,
+          false,
+        );
+        const lineEvaluation = response.responseLines.at(2)!;
+        assert.strictEqual(JSON.parse(lineEvaluation), '');
+      });
+    });
+
     it('work with one argument', async () => {
       await withMcpContext(async (response, context) => {
         const page = context.getSelectedMcpPage().pptrPage;