refactor: address review feedback on navigation reporting

- Rename WaitForEventsResult.navigated to navigatedToUrl, returning the
  URL directly instead of a boolean.
- Move appendNavigationIfAny into WaitForHelper as appendWaitForResult so
  it can be reused by other callers and matches the result interface.
- Update input.ts and script.ts to use the shared helper.
- Drop the misleading doc comment about same-document navigations.

Author: rogeroliveira84

src/WaitForHelper.ts

@@ -162,16 +162,27 @@ export class WaitForHelper {
       this.#abortController.abort();
     }
 
-    return {navigated};
+    return {
+      ...(navigated ? {navigatedToUrl: this.#page.url()} : {}),
+    };
   }
 }
 
 export interface WaitForEventsResult {
   /**
-   * Whether a cross-document navigation started and finished during the
-   * action. Same-document (history API) navigations are not reported.
+   * The URL the page navigated to during the action, if a navigation
+   * occurred.
    */
-  navigated: boolean;
+  navigatedToUrl?: string;
+}
+
+export function appendWaitForResult(
+  response: {appendResponseLine(value: string): void},
+  result: WaitForEventsResult,
+): void {
+  if (result.navigatedToUrl) {
+    response.appendResponseLine(`Page navigated to ${result.navigatedToUrl}.`);
+  }
 }
 
 export function getNetworkMultiplierFromString(

src/tools/input.ts

@@ -10,10 +10,13 @@ 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 type {WaitForEventsResult} from '../WaitForHelper.js';
+import {
+  appendWaitForResult,
+  type WaitForEventsResult,
+} from '../WaitForHelper.js';
 
 import {ToolCategory} from './categories.js';
-import type {ContextPage, Response} from './ToolDefinition.js';
+import type {ContextPage} from './ToolDefinition.js';
 import {definePageTool} from './ToolDefinition.js';
 
 const dblClickSchema = zod
@@ -43,16 +46,6 @@ function handleActionError(error: unknown, uid: string) {
   );
 }
 
-function appendNavigationIfAny(
-  page: ContextPage,
-  response: Response,
-  result: WaitForEventsResult,
-) {
-  if (result.navigated) {
-    response.appendResponseLine(`Page navigated to ${page.pptrPage.url()}.`);
-  }
-}
-
 export const click = definePageTool({
   name: 'click',
   description: `Clicks on the provided element`,
@@ -83,7 +76,7 @@ export const click = definePageTool({
           ? `Successfully double clicked on the element`
           : `Successfully clicked on the element`,
       );
-      appendNavigationIfAny(request.page, response, result);
+      appendWaitForResult(response, result);
       if (request.params.includeSnapshot) {
         response.includeSnapshot();
       }
@@ -121,7 +114,7 @@ export const clickAt = definePageTool({
         ? `Successfully double clicked at the coordinates`
         : `Successfully clicked at the coordinates`,
     );
-    appendNavigationIfAny(page, response, result);
+    appendWaitForResult(response, result);
     if (request.params.includeSnapshot) {
       response.includeSnapshot();
     }
@@ -151,7 +144,7 @@ export const hover = definePageTool({
         await handle.asLocator().hover();
       });
       response.appendResponseLine(`Successfully hovered over the element`);
-      appendNavigationIfAny(request.page, response, result);
+      appendWaitForResult(response, result);
       if (request.params.includeSnapshot) {
         response.includeSnapshot();
       }
@@ -258,7 +251,7 @@ export const fill = definePageTool({
       );
     });
     response.appendResponseLine(`Successfully filled out the element`);
-    appendNavigationIfAny(page, response, result);
+    appendWaitForResult(response, result);
     if (request.params.includeSnapshot) {
       response.includeSnapshot();
     }
@@ -289,7 +282,7 @@ export const typeText = definePageTool({
     response.appendResponseLine(
       `Typed text "${request.params.text}${request.params.submitKey ? ` + ${request.params.submitKey}` : ''}"`,
     );
-    appendNavigationIfAny(page, response, result);
+    appendWaitForResult(response, result);
   },
 });
 
@@ -317,7 +310,7 @@ export const drag = definePageTool({
         await toHandle.drop(fromHandle);
       });
       response.appendResponseLine(`Successfully dragged an element`);
-      appendNavigationIfAny(request.page, response, result);
+      appendWaitForResult(response, result);
       if (request.params.includeSnapshot) {
         response.includeSnapshot();
       }
@@ -349,7 +342,7 @@ export const fillForm = definePageTool({
   },
   handler: async (request, response, context) => {
     const page = request.page;
-    let lastResult: WaitForEventsResult = {navigated: false};
+    let lastResult: WaitForEventsResult = {};
     for (const element of request.params.elements) {
       lastResult = await page.waitForEventsAfterAction(async () => {
         await fillFormElement(
@@ -361,7 +354,7 @@ export const fillForm = definePageTool({
       });
     }
     response.appendResponseLine(`Successfully filled out the form`);
-    appendNavigationIfAny(page, response, lastResult);
+    appendWaitForResult(response, lastResult);
     if (request.params.includeSnapshot) {
       response.includeSnapshot();
     }
@@ -451,7 +444,7 @@ export const pressKey = definePageTool({
     response.appendResponseLine(
       `Successfully pressed key: ${request.params.key}`,
     );
-    appendNavigationIfAny(page, response, result);
+    appendWaitForResult(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 {appendWaitForResult} from '../WaitForHelper.js';
 
 import {ToolCategory} from './categories.js';
 import type {Context, Response} from './ToolDefinition.js';
@@ -77,15 +78,12 @@ Example with arguments: \`(el) => {
         }
 
         const worker = await getWebWorker(context, serviceWorkerId);
-        const selectedPage = context.getSelectedMcpPage();
-        const result = await selectedPage.waitForEventsAfterAction(async () => {
-          await performEvaluation(worker, fnString, [], response);
-        });
-        if (result.navigated) {
-          response.appendResponseLine(
-            `Page navigated to ${selectedPage.pptrPage.url()}.`,
-          );
-        }
+        const result = await context
+          .getSelectedMcpPage()
+          .waitForEventsAfterAction(async () => {
+            await performEvaluation(worker, fnString, [], response);
+          });
+        appendWaitForResult(response, result);
         return;
       }
 
@@ -108,9 +106,7 @@ Example with arguments: \`(el) => {
         const result = await mcpPage.waitForEventsAfterAction(async () => {
           await performEvaluation(evaluatable, fnString, args, response);
         });
-        if (result.navigated) {
-          response.appendResponseLine(`Page navigated to ${page.url()}.`);
-        }
+        appendWaitForResult(response, result);
       } finally {
         void Promise.allSettled(args.map(arg => arg.dispose()));
       }