feat: report navigated URL in action responses

Report the new page URL when an action (click, fill, press_key, etc.)
triggers a navigation. The URL is detected by comparing the page URL
before and after waitForEventsAfterAction.

Fixes #243

Author: masamaru0513

src/McpPage.ts

@@ -129,15 +129,18 @@ export class McpPage implements ContextPage {
     return new WaitForHelper(this.pptrPage, cpuMultiplier, networkMultiplier);
   }
 
-  waitForEventsAfterAction(
+  async waitForEventsAfterAction(
     action: () => Promise<unknown>,
     options?: {timeout?: number; handleDialog?: 'accept' | 'dismiss' | string},
-  ): Promise<void> {
+  ): Promise<{navigatedToUrl?: string}> {
+    const urlBefore = this.pptrPage.url();
     const helper = this.createWaitForHelper(
       this.cpuThrottlingRate,
       getNetworkMultiplierFromString(this.networkConditions),
     );
-    return helper.waitForEventsAfterAction(action, options);
+    await helper.waitForEventsAfterAction(action, options);
+    const urlAfter = this.pptrPage.url();
+    return urlAfter === urlBefore ? {} : {navigatedToUrl: urlAfter};
   }
 
   dispose(): void {

src/WaitForHelper.ts

@@ -202,3 +202,12 @@ export function getNetworkMultiplierFromString(
   }
   return 1;
 }
+
+export function appendNavigatedToUrl(
+  response: {appendResponseLine(value: string): void},
+  result: {navigatedToUrl?: string},
+): void {
+  if (result.navigatedToUrl) {
+    response.appendResponseLine(`Navigated to ${result.navigatedToUrl}`);
+  }
+}

src/tools/ToolDefinition.ts

@@ -260,7 +260,7 @@ export type ContextPage = Readonly<{
   waitForEventsAfterAction(
     action: () => Promise<unknown>,
     options?: {timeout?: number; handleDialog?: 'accept' | 'dismiss' | string},
-  ): Promise<void>;
+  ): Promise<{navigatedToUrl?: string}>;
   getInPageTools(): ToolGroup<InPageToolDefinition> | undefined;
   executeInPageTool(
     toolName: string,

src/tools/input.ts

@@ -10,6 +10,7 @@ import {zod} from '../third_party/index.js';
 import type {ElementHandle, KeyInput} from '../third_party/index.js';
 import type {TextSnapshotNode} from '../types.js';
 import {parseKey} from '../utils/keyboard.js';
+import {appendNavigatedToUrl} from '../WaitForHelper.js';
 
 import {ToolCategory} from './categories.js';
 import type {ContextPage} from './ToolDefinition.js';
@@ -109,7 +110,7 @@ export const click = definePageTool({
     const shouldSelectNativeOption =
       !request.params.dblClick && aXNode?.role === 'option';
     try {
-      await request.page.waitForEventsAfterAction(async () => {
+      const result = await request.page.waitForEventsAfterAction(async () => {
         if (
           shouldSelectNativeOption &&
           (await selectNativeSelectOption(handle))
@@ -126,6 +127,7 @@ export const click = definePageTool({
           ? `Successfully double clicked on the element`
           : `Successfully clicked on the element`,
       );
+      appendNavigatedToUrl(response, result);
       if (request.params.includeSnapshot) {
         response.includeSnapshot();
       }
@@ -154,7 +156,7 @@ export const clickAt = definePageTool({
   blockedByDialog: true,
   handler: async (request, response) => {
     const page = request.page;
-    await page.waitForEventsAfterAction(async () => {
+    const result = await page.waitForEventsAfterAction(async () => {
       await page.pptrPage.mouse.click(request.params.x, request.params.y, {
         clickCount: request.params.dblClick ? 2 : 1,
       });
@@ -164,6 +166,7 @@ export const clickAt = definePageTool({
         ? `Successfully double clicked at the coordinates`
         : `Successfully clicked at the coordinates`,
     );
+    appendNavigatedToUrl(response, result);
     if (request.params.includeSnapshot) {
       response.includeSnapshot();
     }
@@ -190,10 +193,11 @@ export const hover = definePageTool({
     const uid = request.params.uid;
     const handle = await request.page.getElementByUid(uid);
     try {
-      await request.page.waitForEventsAfterAction(async () => {
+      const result = await request.page.waitForEventsAfterAction(async () => {
         await handle.asLocator().hover();
       });
       response.appendResponseLine(`Successfully hovered over the element`);
+      appendNavigatedToUrl(response, result);
       if (request.params.includeSnapshot) {
         response.includeSnapshot();
       }
@@ -292,7 +296,7 @@ export const fill = definePageTool({
   blockedByDialog: true,
   handler: async (request, response, context) => {
     const page = request.page;
-    await page.waitForEventsAfterAction(async () => {
+    const result = await page.waitForEventsAfterAction(async () => {
       await fillFormElement(
         request.params.uid,
         request.params.value,
@@ -301,6 +305,7 @@ export const fill = definePageTool({
       );
     });
     response.appendResponseLine(`Successfully filled out the element`);
+    appendNavigatedToUrl(response, result);
     if (request.params.includeSnapshot) {
       response.includeSnapshot();
     }
@@ -321,7 +326,7 @@ export const typeText = definePageTool({
   blockedByDialog: true,
   handler: async (request, response) => {
     const page = request.page;
-    await page.waitForEventsAfterAction(async () => {
+    const result = await page.waitForEventsAfterAction(async () => {
       await page.pptrPage.keyboard.type(request.params.text);
       if (request.params.submitKey) {
         await page.pptrPage.keyboard.press(
@@ -332,6 +337,7 @@ export const typeText = definePageTool({
     response.appendResponseLine(
       `Typed text "${request.params.text}${request.params.submitKey ? ` + ${request.params.submitKey}` : ''}"`,
     );
+    appendNavigatedToUrl(response, result);
   },
 });
 
@@ -354,12 +360,13 @@ export const drag = definePageTool({
     );
     const toHandle = await request.page.getElementByUid(request.params.to_uid);
     try {
-      await request.page.waitForEventsAfterAction(async () => {
+      const result = await request.page.waitForEventsAfterAction(async () => {
         await fromHandle.drag(toHandle);
         await new Promise(resolve => setTimeout(resolve, 50));
         await toHandle.drop(fromHandle);
       });
       response.appendResponseLine(`Successfully dragged an element`);
+      appendNavigatedToUrl(response, result);
       if (request.params.includeSnapshot) {
         response.includeSnapshot();
       }
@@ -392,17 +399,22 @@ export const fillForm = definePageTool({
   blockedByDialog: true,
   handler: async (request, response, context) => {
     const page = request.page;
+    let lastResult: {navigatedToUrl?: string} = {};
     for (const element of request.params.elements) {
-      await page.waitForEventsAfterAction(async () => {
+      const result = await page.waitForEventsAfterAction(async () => {
         await fillFormElement(
           element.uid,
           element.value,
           context as McpContext,
           page,
         );
       });
+      if (result.navigatedToUrl) {
+        lastResult = result;
+      }
     }
     response.appendResponseLine(`Successfully filled out the form`);
+    appendNavigatedToUrl(response, lastResult);
     if (request.params.includeSnapshot) {
       response.includeSnapshot();
     }
@@ -482,7 +494,7 @@ export const pressKey = definePageTool({
     const tokens = parseKey(request.params.key);
     const [key, ...modifiers] = tokens;
 
-    await page.waitForEventsAfterAction(async () => {
+    const result = await page.waitForEventsAfterAction(async () => {
       for (const modifier of modifiers) {
         await page.pptrPage.keyboard.down(modifier);
       }
@@ -495,6 +507,7 @@ export const pressKey = definePageTool({
     response.appendResponseLine(
       `Successfully pressed key: ${request.params.key}`,
     );
+    appendNavigatedToUrl(response, result);
     if (request.params.includeSnapshot) {
       response.includeSnapshot();
     }

src/tools/script.ts

@@ -7,6 +7,7 @@
 import {zod} from '../third_party/index.js';
 import type {Frame, JSHandle, Page, WebWorker} from '../third_party/index.js';
 import type {ExtensionServiceWorker} from '../types.js';
+import {appendNavigatedToUrl} from '../WaitForHelper.js';
 
 import {ToolCategory} from './categories.js';
 import type {Context, Response} from './ToolDefinition.js';
@@ -85,12 +86,15 @@ Example with arguments: \`(el) => {
         }
 
         const worker = await getWebWorker(context, serviceWorkerId);
-        await context.getSelectedMcpPage().waitForEventsAfterAction(
-          async () => {
-            await performEvaluation(worker, fnString, [], response);
-          },
-          {handleDialog: dialogAction ?? 'accept'},
-        );
+        const result = await context
+          .getSelectedMcpPage()
+          .waitForEventsAfterAction(
+            async () => {
+              await performEvaluation(worker, fnString, [], response);
+            },
+            {handleDialog: dialogAction ?? 'accept'},
+          );
+        appendNavigatedToUrl(response, result);
         return;
       }
 
@@ -110,12 +114,13 @@ Example with arguments: \`(el) => {
 
         const evaluatable = await getPageOrFrame(page, frames);
 
-        await mcpPage.waitForEventsAfterAction(
+        const result = await mcpPage.waitForEventsAfterAction(
           async () => {
             await performEvaluation(evaluatable, fnString, args, response);
           },
           {handleDialog: dialogAction ?? 'accept'},
         );
+        appendNavigatedToUrl(response, result);
       } finally {
         void Promise.allSettled(args.map(arg => arg.dispose()));
       }

tests/tools/input.test.ts

@@ -130,6 +130,60 @@ describe('input', () => {
       });
     });
 
+    it('reports navigated URL after click', async () => {
+      server.addHtmlRoute('/nav-link', html`<a href="/nav-target">Go</a>`);
+      server.addHtmlRoute('/nav-target', html`<main>Target</main>`);
+
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPptrPage();
+        await page.goto(server.getRoute('/nav-link'));
+        context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+          context.getSelectedMcpPage(),
+        );
+        await click.handler(
+          {
+            params: {uid: '1_1'},
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+        assert.strictEqual(
+          response.responseLines[0],
+          'Successfully clicked on the element',
+        );
+        assert.strictEqual(
+          response.responseLines[1],
+          `Navigated to ${server.getRoute('/nav-target')}`,
+        );
+      });
+    });
+
+    it('does not report navigated URL when no navigation occurs', async () => {
+      await withMcpContext(async (response, context) => {
+        const page = context.getSelectedPptrPage();
+        await page.setContent(
+          html`<button onclick="this.innerText = 'clicked';">test</button>`,
+        );
+        context.getSelectedMcpPage().textSnapshot = await TextSnapshot.create(
+          context.getSelectedMcpPage(),
+        );
+        await click.handler(
+          {
+            params: {uid: '1_1'},
+            page: context.getSelectedMcpPage(),
+          },
+          response,
+          context,
+        );
+        assert.strictEqual(response.responseLines.length, 1);
+        assert.strictEqual(
+          response.responseLines[0],
+          'Successfully clicked on the element',
+        );
+      });
+    });
+
     it('waits for stable DOM', async () => {
       server.addHtmlRoute(
         '/unstable',