refactor: centralize pageId routing via pageScoped annotation and McpPage wrapper

- Add pageScoped annotation to ToolDefinition; registerTool() auto-injects
  pageIdSchema and resolves the page centrally via resolvePageById()
- defineTool() wrapper guarantees request.page is always populated,
  falling back to getSelectedPage() when pageId is omitted
- Remove manual ...pageIdSchema spread and resolvePageById() calls from
  all 15 page-scoped tool handlers
- Introduce McpPage class consolidating per-page state (dialog, snapshot,
  emulation settings, metadata) that was previously scattered across 8
  Maps/WeakMaps in McpContext
- Store text snapshots per-page on McpPage so parallel agents taking
  snapshots on different pages no longer clobber each other
- Cross-page uid lookup in getElementByUid()/getAXNodeByUid() searches
  all McpPage instances, enabling uid resolution from any page's snapshot
- Update page_id_routing eval to test per-page snapshot isolation and
  cross-page uid click resolution

Author: passtas

docs/tool-reference.md

@@ -1,15 +1,16 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
 
-# Chrome DevTools MCP Tool Reference (~7267 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~7472 cl100k_base tokens)
 
-- **[Input automation](#input-automation)** (8 tools)
+- **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)
   - [`drag`](#drag)
   - [`fill`](#fill)
   - [`fill_form`](#fill_form)
   - [`handle_dialog`](#handle_dialog)
   - [`hover`](#hover)
   - [`press_key`](#press_key)
+  - [`type_text`](#type_text)
   - [`upload_file`](#upload_file)
 - **[Navigation automation](#navigation-automation)** (6 tools)
   - [`close_page`](#close_page)
@@ -71,7 +72,6 @@
 - **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot
 - **value** (string) **(required)**: The value to [`fill`](#fill) in
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -83,7 +83,6 @@
 
 - **elements** (array) **(required)**: Elements from snapshot to [`fill`](#fill) out.
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -117,7 +116,17 @@
 
 - **key** (string) **(required)**: A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
+
+---
+
+### `type_text`
+
+**Description:** Type text using keyboard into a previously focused input
+
+**Parameters:**
+
+- **text** (string) **(required)**: The text to type
+- **submitKey** (string) _(optional)_: Optional key to press after typing. E.g., "Enter", "Tab", "Escape"
 
 ---
 
@@ -130,7 +139,6 @@
 - **filePath** (string) **(required)**: The local path of the file to upload
 - **uid** (string) **(required)**: The uid of the file input element or an element that will open file chooser on the page from the page content snapshot
 - **includeSnapshot** (boolean) _(optional)_: Whether to include a snapshot in the response. Default is false.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -163,7 +171,6 @@
 - **handleBeforeUnload** (enum: "accept", "decline") _(optional)_: Whether to auto accept or beforeunload dialogs triggered by this navigation. Default is accept.
 - **ignoreCache** (boolean) _(optional)_: Whether to ignore cache on reload.
 - **initScript** (string) _(optional)_: A JavaScript script to be executed on each new document before any other scripts for the next navigation.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 - **type** (enum: "url", "back", "forward", "reload") _(optional)_: Navigate the page by URL, back or forward in history, or reload.
 - **url** (string) _(optional)_: Target URL (only type=url)
@@ -201,7 +208,6 @@
 **Parameters:**
 
 - **text** (array) **(required)**: Non-empty list of texts. Resolves when any value appears on the page.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 
 ---
@@ -218,7 +224,6 @@
 - **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.
 - **geolocation** (unknown) _(optional)_: Geolocation to [`emulate`](#emulate). Set to null to clear the geolocation override.
 - **networkConditions** (enum: "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **userAgent** (unknown) _(optional)_: User agent to [`emulate`](#emulate). Set to null to clear the user agent override.
 - **viewport** (unknown) _(optional)_: Viewport to [`emulate`](#emulate). Set to null to reset to the default viewport.
 
@@ -232,7 +237,6 @@
 
 - **height** (number) **(required)**: Page height
 - **width** (number) **(required)**: Page width
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -258,7 +262,6 @@
 - **autoStop** (boolean) **(required)**: Determines if the trace recording should be automatically stopped.
 - **reload** (boolean) **(required)**: Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the [`navigate_page`](#navigate_page) tool BEFORE starting the trace if reload or autoStop is set to true.
 - **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -269,7 +272,6 @@
 **Parameters:**
 
 - **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -330,7 +332,6 @@ so returned values have to be JSON-serializable.
 }`
 
 - **args** (array) _(optional)_: An optional list of arguments to pass to the function.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 
 ---
 
@@ -366,7 +367,6 @@ so returned values have to be JSON-serializable.
 - **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.
 - **format** (enum: "png", "jpeg", "webp") _(optional)_: Type of format to save the screenshot as. Default is "png"
 - **fullPage** (boolean) _(optional)_: If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **quality** (number) _(optional)_: Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.
 - **uid** (string) _(optional)_: The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.
 
@@ -381,7 +381,6 @@ in the DevTools Elements panel (if any).
 **Parameters:**
 
 - **filePath** (string) _(optional)_: The absolute path, or a path relative to the current working directory, to save the snapshot to instead of attaching it to the response.
-- **pageId** (number) _(optional)_: Targets a specific page by ID.
 - **verbose** (boolean) _(optional)_: Whether to include all possible information available in the full a11y tree. Default is false.
 
 ---

scripts/eval_scenarios/page_id_routing_test.ts

@@ -9,32 +9,31 @@ import assert from 'node:assert';
 import type {TestScenario} from '../eval_gemini.ts';
 
 export const scenario: TestScenario = {
-  prompt: `Open three new pages in isolated contexts:
-- Page A at data:text/html,<h1>Page A</h1>
-- Page B at data:text/html,<h1>Page B</h1>
-- Page C at data:text/html,<h1>Page C</h1>
-Then take screenshots of all three pages in parallel.`,
-  maxTurns: 8,
+  prompt: `Open two new pages in isolated contexts:
+- Page A (isolatedContext "contextA") at data:text/html,<button>Click A</button>
+- Page B (isolatedContext "contextB") at data:text/html,<button>Click B</button>
+Then take a snapshot of Page A, take a snapshot of Page B, and then click the button on Page A.`,
+  maxTurns: 12,
   expectations: calls => {
-    // Exactly 3 screenshot calls.
-    const screenshots = calls.filter(c => c.name === 'take_screenshot');
-    assert.strictEqual(screenshots.length, 3, 'Should take 3 screenshots');
-
-    // Each screenshot must carry a numeric pageId.
-    for (const ss of screenshots) {
+    // Should have 2 new_page calls with isolatedContext.
+    const newPages = calls.filter(c => c.name === 'new_page');
+    assert.strictEqual(newPages.length, 2, 'Should open 2 pages');
+    for (const np of newPages) {
       assert.strictEqual(
-        typeof ss.args.pageId,
-        'number',
-        'Screenshot should use pageId',
+        typeof np.args.isolatedContext,
+        'string',
+        'new_page should use isolatedContext',
       );
     }
 
-    // All pageIds should be distinct (one per page).
-    const pageIds = new Set(screenshots.map(s => s.args.pageId));
-    assert.strictEqual(
-      pageIds.size,
-      3,
-      'Each screenshot should target a different page',
-    );
+    // Should have at least 2 take_snapshot calls (one per page).
+    // The model may use pageId directly or select_page before each snapshot.
+    const snapshots = calls.filter(c => c.name === 'take_snapshot');
+    assert.ok(snapshots.length >= 2, 'Should take at least 2 snapshots');
+
+    // Should have a click call (resolving uid from Page A's snapshot
+    // even though Page B was snapshotted after).
+    const clicks = calls.filter(c => c.name === 'click');
+    assert.ok(clicks.length >= 1, 'Should click the button on Page A');
   },
 };