refactor: add request-scoped page routing, assertPageIsFocused, and Context cleanup

- Add #requestPage / #resolveTargetPage() on McpContext so data-retrieval
  methods (console, network, emulation getters, DevTools data) automatically
  resolve the correct page for pageScoped tool requests under toolMutex.
- Mark console and network tools pageScoped: true so they receive pageId
  routing like other page-aware tools.
- Add assertPageIsFocused() for keyboard tools (press_key, type_text,
  click_at) to detect when a page is not the active page in its browser
  context and throw an actionable error with the correct pageId.
- Merge getElementByUid and assertUidOnSelectedPage into a single method
  with optional page parameter for scoped search (pageScoped tools) vs
  cross-page search with context-focus validation (uid-based tools).
- Remove unused Context interface methods: resolvePageById,
  resolveCdpElementId, and 6 emulation getters already removed upstream.
- Clean up orphaned #mcpPages and #focusedPagePerContext entries in
  createPagesSnapshot().
- Remove dead code: fillFormElement page parameter made required since all
  callers now provide it.
- Regenerate tool-reference.md.
- Add unit tests for page-scoped getElementByUid and context-focus
  validation, plus eval scenario for assertPageIsFocused recovery flow.

Author: passtas

docs/tool-reference.md

@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
 
-# Chrome DevTools MCP Tool Reference (~7472 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~7624 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)

scripts/eval_scenarios/page_focus_keyboard_test.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+
+import type {TestScenario} from '../eval_gemini.ts';
+
+export const scenario: TestScenario = {
+  prompt: `Open two pages in the same isolated context "session":
+- Page 1 at data:text/html,<textarea id="ta"></textarea>
+- Page 2 at data:text/html,<h1>Other</h1>
+
+Now press_key "a" on Page 1 without selecting it first. If you encounter any errors, recover from them.`,
+  maxTurns: 10,
+  expectations: calls => {
+    // Should open 2 pages in the same context.
+    const newPages = calls.filter(c => c.name === 'new_page');
+    assert.strictEqual(newPages.length, 2, 'Should open 2 pages');
+    assert.strictEqual(newPages[0].args.isolatedContext, 'session');
+    assert.strictEqual(newPages[1].args.isolatedContext, 'session');
+
+    // Should attempt press_key at least once.
+    const pressKeys = calls.filter(c => c.name === 'press_key');
+    assert.ok(pressKeys.length >= 1, 'Should attempt press_key');
+
+    // Should call select_page to recover after the error.
+    const selectPages = calls.filter(c => c.name === 'select_page');
+    assert.ok(
+      selectPages.length >= 1,
+      'Should select_page to recover from the focus error',
+    );
+
+    const firstPressKeyIndex = calls.indexOf(pressKeys[0]);
+    const firstSelectPageIndex = calls.indexOf(selectPages[0]);
+
+    if (firstPressKeyIndex < firstSelectPageIndex) {
+      // Error path: press_key was attempted first and failed.
+      // Verify recovery: must have a second press_key after select_page.
+      assert.ok(
+        pressKeys.length >= 2,
+        'Should retry press_key after error recovery',
+      );
+      const lastPressKeyIndex = calls.lastIndexOf(pressKeys.at(-1)!);
+      assert.ok(
+        firstSelectPageIndex < lastPressKeyIndex,
+        'select_page should precede the successful press_key',
+      );
+    } else {
+      // Proactive path: model selected page first.
+      // Verify select_page came before press_key.
+      assert.ok(
+        firstSelectPageIndex < firstPressKeyIndex,
+        'select_page should precede press_key',
+      );
+    }
+  },
+};

src/McpContext.ts

@@ -129,6 +129,8 @@ export class McpContext implements Context {
     null;
   #focusedPagePerContext = new Map<BrowserContext, Page>();
 
+  #requestPage?: Page;
+
   #nextPageId = 1;
 
   #extensionServiceWorkerMap = new WeakMap<Target, string>();
@@ -203,8 +205,16 @@ export class McpContext implements Context {
     return context;
   }
 
+  setRequestPage(page?: Page): void {
+    this.#requestPage = page;
+  }
+
+  #resolveTargetPage(): Page {
+    return this.#requestPage ?? this.getSelectedPage();
+  }
+
   resolveCdpRequestId(cdpRequestId: string): number | undefined {
-    const selectedPage = this.getSelectedPage();
+    const selectedPage = this.#resolveTargetPage();
     if (!cdpRequestId) {
       this.logger('no network request');
       return;
@@ -252,19 +262,19 @@ export class McpContext implements Context {
   }
 
   getNetworkRequests(includePreservedRequests?: boolean): HTTPRequest[] {
-    const page = this.getSelectedPage();
+    const page = this.#resolveTargetPage();
     return this.#networkCollector.getData(page, includePreservedRequests);
   }
 
   getConsoleData(
     includePreservedMessages?: boolean,
   ): Array<ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError> {
-    const page = this.getSelectedPage();
+    const page = this.#resolveTargetPage();
     return this.#consoleCollector.getData(page, includePreservedMessages);
   }
 
   getDevToolsUniverse(): TargetUniverse | null {
-    return this.#devtoolsUniverseManager.get(this.getSelectedPage());
+    return this.#devtoolsUniverseManager.get(this.#resolveTargetPage());
   }
 
   getConsoleMessageStableId(
@@ -276,7 +286,7 @@ export class McpContext implements Context {
   getConsoleMessageById(
     id: number,
   ): ConsoleMessage | Error | DevTools.AggregatedIssue | UncaughtError {
-    return this.#consoleCollector.getById(this.getSelectedPage(), id);
+    return this.#consoleCollector.getById(this.#resolveTargetPage(), id);
   }
 
   async newPage(
@@ -318,7 +328,7 @@ export class McpContext implements Context {
   }
 
   getNetworkRequestById(reqid: number): HTTPRequest {
-    return this.#networkCollector.getById(this.getSelectedPage(), reqid);
+    return this.#networkCollector.getById(this.#resolveTargetPage(), reqid);
   }
 
   async emulate(
@@ -435,27 +445,27 @@ export class McpContext implements Context {
   }
 
   getNetworkConditions(): string | null {
-    return this.#getSelectedMcpPage().networkConditions;
+    return this.#getMcpPage(this.#resolveTargetPage()).networkConditions;
   }
 
   getCpuThrottlingRate(): number {
-    return this.#getSelectedMcpPage().cpuThrottlingRate;
+    return this.#getMcpPage(this.#resolveTargetPage()).cpuThrottlingRate;
   }
 
   getGeolocation(): GeolocationOptions | null {
-    return this.#getSelectedMcpPage().geolocation;
+    return this.#getMcpPage(this.#resolveTargetPage()).geolocation;
   }
 
   getViewport(): Viewport | null {
-    return this.#getSelectedMcpPage().viewport;
+    return this.#getMcpPage(this.#resolveTargetPage()).viewport;
   }
 
   getUserAgent(): string | null {
-    return this.#getSelectedMcpPage().userAgent;
+    return this.#getMcpPage(this.#resolveTargetPage()).userAgent;
   }
 
   getColorScheme(): 'dark' | 'light' | null {
-    return this.#getSelectedMcpPage().colorScheme;
+    return this.#getMcpPage(this.#resolveTargetPage()).colorScheme;
   }
 
   setIsRunningPerformanceTrace(x: boolean): void {
@@ -481,7 +491,7 @@ export class McpContext implements Context {
   }
 
   getDialog(page?: Page): Dialog | undefined {
-    const targetPage = page ?? this.#selectedPage;
+    const targetPage = page ?? this.#requestPage ?? this.#selectedPage;
     if (!targetPage) {
       return undefined;
     }
@@ -543,6 +553,19 @@ export class McpContext implements Context {
     return this.#selectedPage === page;
   }
 
+  assertPageIsFocused(page: Page): void {
+    const ctx = page.browserContext();
+    const focused = this.#focusedPagePerContext.get(ctx);
+    if (focused && focused !== page) {
+      const targetId = this.#mcpPages.get(page)?.id ?? '?';
+      const focusedId = this.#mcpPages.get(focused)?.id ?? '?';
+      throw new Error(
+        `Page ${targetId} is not the active page in its browser context (page ${focusedId} is). ` +
+          `Call select_page with pageId ${targetId} first.`,
+      );
+    }
+  }
+
   selectPage(newPage: Page): void {
     const ctx = newPage.browserContext();
     const oldFocused = this.#focusedPagePerContext.get(ctx);
@@ -575,7 +598,7 @@ export class McpContext implements Context {
   }
 
   getNavigationTimeout() {
-    const page = this.getSelectedPage();
+    const page = this.#resolveTargetPage();
     return page.getDefaultNavigationTimeout();
   }
 
@@ -592,12 +615,39 @@ export class McpContext implements Context {
     return undefined;
   }
 
-  assertUidOnSelectedPage(uid: string): void {
-    for (const [page, mcpPage] of this.#mcpPages.entries()) {
-      if (mcpPage.textSnapshot?.idToNode.has(uid)) {
-        const ctx = page.browserContext();
+  async getElementByUid(
+    uid: string,
+    page?: Page,
+  ): Promise<ElementHandle<Element>> {
+    if (page) {
+      // Scoped search: only look in the target page's snapshot.
+      const mcpPage = this.#mcpPages.get(page);
+      if (!mcpPage?.textSnapshot) {
+        throw new Error(
+          `No snapshot found for page ${mcpPage?.id ?? '?'}. Use ${takeSnapshot.name} to capture one.`,
+        );
+      }
+      const node = mcpPage.textSnapshot.idToNode.get(uid);
+      if (!node) {
+        throw new Error(
+          `Element uid "${uid}" not found on page ${mcpPage.id}.`,
+        );
+      }
+      return this.#resolveElementHandle(node, uid);
+    }
+
+    // Cross-page search with context-focus validation.
+    let anySnapshot = false;
+    for (const [searchPage, mcpPage] of this.#mcpPages.entries()) {
+      if (!mcpPage.textSnapshot) {
+        continue;
+      }
+      anySnapshot = true;
+      const node = mcpPage.textSnapshot.idToNode.get(uid);
+      if (node) {
+        const ctx = searchPage.browserContext();
         const contextSelectedPage = this.#focusedPagePerContext.get(ctx);
-        if (contextSelectedPage !== page) {
+        if (contextSelectedPage !== searchPage) {
           const targetId = mcpPage.id;
           const selectedId = contextSelectedPage
             ? this.#mcpPages.get(contextSelectedPage)?.id
@@ -608,37 +658,10 @@ export class McpContext implements Context {
           );
         }
         // Align global #selectedPage for waitForEventsAfterAction etc.
-        if (this.#selectedPage !== page) {
-          this.#selectedPage = page;
-        }
-        return;
-      }
-    }
-    throw new Error('No such element found in any snapshot.');
-  }
-
-  async getElementByUid(uid: string): Promise<ElementHandle<Element>> {
-    let anySnapshot = false;
-    // Search across all per-page snapshots for the uid.
-    for (const mcpPage of this.#mcpPages.values()) {
-      if (!mcpPage.textSnapshot) {
-        continue;
-      }
-      anySnapshot = true;
-      const node = mcpPage.textSnapshot.idToNode.get(uid);
-      if (node) {
-        const message = `Element with uid ${uid} no longer exists on the page.`;
-        try {
-          const handle = await node.elementHandle();
-          if (!handle) {
-            throw new Error(message);
-          }
-          return handle;
-        } catch (error) {
-          throw new Error(message, {
-            cause: error,
-          });
+        if (this.#selectedPage !== searchPage) {
+          this.#selectedPage = searchPage;
         }
+        return this.#resolveElementHandle(node, uid);
       }
     }
     if (!anySnapshot) {
@@ -684,6 +707,24 @@ export class McpContext implements Context {
     return this.#extensionServiceWorkers;
   }
 
+  async #resolveElementHandle(
+    node: TextSnapshotNode,
+    uid: string,
+  ): Promise<ElementHandle<Element>> {
+    const message = `Element with uid ${uid} no longer exists on the page.`;
+    try {
+      const handle = await node.elementHandle();
+      if (!handle) {
+        throw new Error(message);
+      }
+      return handle;
+    } catch (error) {
+      throw new Error(message, {
+        cause: error,
+      });
+    }
+  }
+
   async createPagesSnapshot(): Promise<Page[]> {
     const {pages: allPages, isolatedContextNames} = await this.#getAllPages();
 
@@ -696,6 +737,21 @@ export class McpContext implements Context {
       mcpPage.isolatedContextName = isolatedContextNames.get(page);
     }
 
+    // Prune orphaned #mcpPages entries (pages that no longer exist).
+    const currentPages = new Set(allPages);
+    for (const [page, mcpPage] of this.#mcpPages) {
+      if (!currentPages.has(page)) {
+        mcpPage.dispose();
+        this.#mcpPages.delete(page);
+      }
+    }
+    // Prune stale #focusedPagePerContext entries.
+    for (const [ctx, page] of this.#focusedPagePerContext) {
+      if (!currentPages.has(page)) {
+        this.#focusedPagePerContext.delete(ctx);
+      }
+    }
+
     this.#pages = allPages.filter(page => {
       return (
         this.#options.experimentalDevToolsDebugging ||
@@ -815,7 +871,7 @@ export class McpContext implements Context {
   async getDevToolsData(): Promise<DevToolsData> {
     try {
       this.logger('Getting DevTools UI data');
-      const selectedPage = this.getSelectedPage();
+      const selectedPage = this.#resolveTargetPage();
       const devtoolsPage = this.getDevToolsPage(selectedPage);
       if (!devtoolsPage) {
         this.logger('No DevTools page detected');