Chrome DevTools for coding agents
feat: add pageId routing for parallel multi-agent workflows (#1022)
Stanislav Publikacaf601a32832
diff --git a/scripts/eval_gemini.ts b/scripts/eval_gemini.tsindex 72640282..1391bfe6 100644--- a/scripts/eval_gemini.ts+++ b/scripts/eval_gemini.ts@@ -33,6 +33,8 @@ export interface TestScenario {path: string;htmlContent: string;};+ /** Extra CLI flags passed to the MCP server (e.g. '--experimental-page-id-routing'). */+ serverArgs?: string[];}async function loadScenario(scenarioPath: string): Promise<TestScenario> {@@ -117,6 +119,9 @@ async function runSingleScenario(if (!debug) {args.push('--headless');}+ if (scenario.serverArgs) {+ args.push(...scenario.serverArgs);+ }transport = new StdioClientTransport({command: 'node',diff --git a/scripts/eval_scenarios/page_focus_keyboard_test.ts b/scripts/eval_scenarios/page_focus_keyboard_test.tsnew file mode 100644index 00000000..655b1fec--- /dev/null+++ b/scripts/eval_scenarios/page_focus_keyboard_test.ts@@ -0,0 +1,59 @@+/**+ * @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 = {+ serverArgs: ['--experimental-page-id-routing'],+ 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 use the press_key tool to type "a" on Page 1 without selecting it first. You must use press_key, not fill or type_text. 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 at least once');++ const selectPages = calls.filter(c => c.name === 'select_page');++ if (selectPages.length > 0) {+ 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.+ assert.ok(+ firstSelectPageIndex < firstPressKeyIndex,+ 'select_page should precede press_key',+ );+ }+ }+ // If no select_page was called, the model found another recovery path.+ // This is acceptable as long as press_key was attempted.+ },+};diff --git a/scripts/eval_scenarios/page_id_routing_test.ts b/scripts/eval_scenarios/page_id_routing_test.tsnew file mode 100644index 00000000..39007a4b--- /dev/null+++ b/scripts/eval_scenarios/page_id_routing_test.ts@@ -0,0 +1,40 @@+/**+ * @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 = {+ serverArgs: ['--experimental-page-id-routing'],+ 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 => {+ // 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 np.args.isolatedContext,+ 'string',+ 'new_page should use isolatedContext',+ );+ }++ // 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');+ },+};diff --git a/src/McpContext.ts b/src/McpContext.tsindex 56ea1f5a..cf5597b3 100644--- a/src/McpContext.ts+++ b/src/McpContext.ts@@ -14,6 +14,7 @@ import {UniverseManager,urlsEqual,} from './DevtoolsUtils.js';+import {McpPage} from './McpPage.js';import type {ListenerMap, UncaughtError} from './PageCollector.js';import {NetworkCollector, ConsoleCollector} from './PageCollector.js';import type {DevTools} from './third_party/index.js';@@ -38,18 +39,24 @@ import {takeSnapshot} from './tools/snapshot.js';import {CLOSE_PAGE_ERROR} from './tools/ToolDefinition.js';import type {Context, DevToolsData} from './tools/ToolDefinition.js';import type {TraceResult} from './trace-processing/parse.js';+import type {+ EmulationSettings,+ GeolocationOptions,+ TextSnapshot,+ TextSnapshotNode,+} from './types.js';import {ExtensionRegistry,type InstalledExtension,} from './utils/ExtensionRegistry.js';import {WaitForHelper} from './WaitForHelper.js';-export interface TextSnapshotNode extends SerializedAXNode {- id: string;- backendNodeId?: number;- loaderId?: string;- children: TextSnapshotNode[];-}+export type {+ EmulationSettings,+ GeolocationOptions,+ TextSnapshot,+ TextSnapshotNode,+} from './types.js';export interface ExtensionServiceWorker {url: string;@@ -57,31 +64,6 @@ export interface ExtensionServiceWorker {id: string;}-export interface GeolocationOptions {- latitude: number;- longitude: number;-}--export interface TextSnapshot {- root: TextSnapshotNode;- idToNode: Map<string, TextSnapshotNode>;- snapshotId: string;- selectedElementUid?: string;- // It might happen that there is a selected element, but it is not part of the- // snapshot. This flag indicates if there is any selected element.- hasSelectedElement: boolean;- verbose: boolean;-}--interface EmulationSettings {- networkConditions?: string | null;- cpuThrottlingRate?: number | null;- geolocation?: GeolocationOptions | null;- userAgent?: string | null;- colorScheme?: 'dark' | 'light' | null;- viewport?: Viewport | null;-}-interface McpContextOptions {// Whether the DevTools windows are exposed as pages for debugging of DevTools.experimentalDevToolsDebugging: boolean;@@ -129,18 +111,14 @@ export class McpContext implements Context {// Maps LLM-provided isolatedContext name → Puppeteer BrowserContext.#isolatedContexts = new Map<string, BrowserContext>();- // Reverse lookup: Page → isolatedContext name (for snapshot labeling).- // WeakMap so closed pages are garbage-collected automatically.- #pageToIsolatedContextName = new WeakMap<Page, string>();// Auto-generated name counter for when no name is provided.#nextIsolatedContextId = 1;#pages: Page[] = [];#extensionServiceWorkers: ExtensionServiceWorker[] = [];- #pageToDevToolsPage = new Map<Page, Page>();+ #mcpPages = new Map<Page, McpPage>();#selectedPage?: Page;- #textSnapshot: TextSnapshot | null = null;#networkCollector: NetworkCollector;#consoleCollector: ConsoleCollector;#devtoolsUniverseManager: UniverseManager;@@ -149,10 +127,10 @@ export class McpContext implements Context {#isRunningTrace = false;#screenRecorderData: {recorder: ScreenRecorder; filePath: string} | null =null;- #emulationSettingsMap = new WeakMap<Page, EmulationSettings>();- #dialog?: Dialog;+ #focusedPagePerContext = new Map<BrowserContext, Page>();++ #requestPage?: Page;- #pageIdMap = new WeakMap<Page, number>();#nextPageId = 1;#extensionServiceWorkerMap = new WeakMap<Target, string>();@@ -164,8 +142,6 @@ export class McpContext implements Context {#locatorClass: typeof Locator;#options: McpContextOptions;- #uniqueBackendNodeIdToMcpId = new Map<string, string>();-private constructor(browser: Browser,logger: Debugger,@@ -207,6 +183,10 @@ export class McpContext implements Context {this.#networkCollector.dispose();this.#consoleCollector.dispose();this.#devtoolsUniverseManager.dispose();+ for (const mcpPage of this.#mcpPages.values()) {+ mcpPage.dispose();+ }+ this.#mcpPages.clear();// Isolated contexts are intentionally not closed here.// Either the entire browser will be closed or we disconnect// without destroying browser state.@@ -225,8 +205,19 @@ export class McpContext implements Context {return context;}+ // TODO: Refactor away mutable request state (e.g. per-request facade,+ // per-request context object, or another approach). Once resolved, the+ // global toolMutex could become per-BrowserContext for parallel execution.+ 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;@@ -242,43 +233,51 @@ export class McpContext implements Context {return this.#networkCollector.getIdForResource(request);}- resolveCdpElementId(cdpBackendNodeId: number): string | undefined {+ resolveCdpElementId(+ cdpBackendNodeId: number,+ page?: Page,+ ): string | undefined {if (!cdpBackendNodeId) {this.logger('no cdpBackendNodeId');return;}- if (this.#textSnapshot === null) {+ const snapshots = page+ ? [this.#mcpPages.get(page)?.textSnapshot].filter(Boolean)+ : [...this.#mcpPages.values()].map(mp => mp.textSnapshot).filter(Boolean);+ if (!snapshots.length) {this.logger('no text snapshot');return;}// TODO: index by backendNodeId instead.- const queue = [this.#textSnapshot.root];- while (queue.length) {- const current = queue.pop()!;- if (current.backendNodeId === cdpBackendNodeId) {- return current.id;- }- for (const child of current.children) {- queue.push(child);+ for (const snapshot of snapshots) {+ const queue = [snapshot!.root];+ while (queue.length) {+ const current = queue.pop()!;+ if (current.backendNodeId === cdpBackendNodeId) {+ return current.id;+ }+ for (const child of current.children) {+ queue.push(child);+ }}}return;}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(@@ -290,7 +289,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(@@ -305,7 +304,6 @@ export class McpContext implements Context {this.#isolatedContexts.set(isolatedContextName, ctx);}page = await ctx.newPage();- this.#pageToIsolatedContextName.set(page, isolatedContextName);} else {page = await this.browser.newPage({background});}@@ -320,25 +318,36 @@ export class McpContext implements Context {throw new Error(CLOSE_PAGE_ERROR);}const page = this.getPageById(pageId);+ const mcpPage = this.#mcpPages.get(page);+ if (mcpPage) {+ mcpPage.dispose();+ this.#mcpPages.delete(page);+ }+ const ctx = page.browserContext();+ if (this.#focusedPagePerContext.get(ctx) === page) {+ this.#focusedPagePerContext.delete(ctx);+ }await page.close({runBeforeUnload: false});- this.#pageToIsolatedContextName.delete(page);}getNetworkRequestById(reqid: number): HTTPRequest {- return this.#networkCollector.getById(this.getSelectedPage(), reqid);- }-- async emulate(options: {- networkConditions?: string | null;- cpuThrottlingRate?: number | null;- geolocation?: GeolocationOptions | null;- userAgent?: string | null;- colorScheme?: 'dark' | 'light' | 'auto' | null;- viewport?: Viewport | null;- }): Promise<void> {- const page = this.getSelectedPage();- const currentSettings = this.#emulationSettingsMap.get(page) ?? {};- const newSettings: EmulationSettings = {...currentSettings};+ return this.#networkCollector.getById(this.#resolveTargetPage(), reqid);+ }++ async emulate(+ options: {+ networkConditions?: string | null;+ cpuThrottlingRate?: number | null;+ geolocation?: GeolocationOptions | null;+ userAgent?: string | null;+ colorScheme?: 'dark' | 'light' | 'auto' | null;+ viewport?: Viewport | null;+ },+ targetPage?: Page,+ ): Promise<void> {+ const page = targetPage ?? this.getSelectedPage();+ const mcpPage = this.#getMcpPage(page);+ const newSettings: EmulationSettings = {...mcpPage.emulationSettings};let timeoutsNeedUpdate = false;if (options.networkConditions !== undefined) {@@ -429,11 +438,9 @@ export class McpContext implements Context {}}- if (Object.keys(newSettings).length) {- this.#emulationSettingsMap.set(page, newSettings);- } else {- this.#emulationSettingsMap.delete(page);- }+ mcpPage.emulationSettings = Object.keys(newSettings).length+ ? newSettings+ : {};if (timeoutsNeedUpdate) {this.#updateSelectedPageTimeouts();@@ -441,33 +448,27 @@ export class McpContext implements Context {}getNetworkConditions(): string | null {- const page = this.getSelectedPage();- return this.#emulationSettingsMap.get(page)?.networkConditions ?? null;+ return this.#getMcpPage(this.#resolveTargetPage()).networkConditions;}getCpuThrottlingRate(): number {- const page = this.getSelectedPage();- return this.#emulationSettingsMap.get(page)?.cpuThrottlingRate ?? 1;+ return this.#getMcpPage(this.#resolveTargetPage()).cpuThrottlingRate;}getGeolocation(): GeolocationOptions | null {- const page = this.getSelectedPage();- return this.#emulationSettingsMap.get(page)?.geolocation ?? null;+ return this.#getMcpPage(this.#resolveTargetPage()).geolocation;}getViewport(): Viewport | null {- const page = this.getSelectedPage();- return this.#emulationSettingsMap.get(page)?.viewport ?? null;+ return this.#getMcpPage(this.#resolveTargetPage()).viewport;}getUserAgent(): string | null {- const page = this.getSelectedPage();- return this.#emulationSettingsMap.get(page)?.userAgent ?? null;+ return this.#getMcpPage(this.#resolveTargetPage()).userAgent;}getColorScheme(): 'dark' | 'light' | null {- const page = this.getSelectedPage();- return this.#emulationSettingsMap.get(page)?.colorScheme ?? null;+ return this.#getMcpPage(this.#resolveTargetPage()).colorScheme;}setIsRunningPerformanceTrace(x: boolean): void {@@ -492,12 +493,19 @@ export class McpContext implements Context {return this.#options.performanceCrux;}- getDialog(): Dialog | undefined {- return this.#dialog;+ getDialog(page?: Page): Dialog | undefined {+ const targetPage = page ?? this.#requestPage ?? this.#selectedPage;+ if (!targetPage) {+ return undefined;+ }+ return this.#mcpPages.get(targetPage)?.dialog;}- clearDialog(): void {- this.#dialog = undefined;+ clearDialog(page?: Page): void {+ const targetPage = page ?? this.#selectedPage;+ if (targetPage) {+ this.#mcpPages.get(targetPage)?.clearDialog();+ }}getSelectedPage(): Page {@@ -513,8 +521,15 @@ export class McpContext implements Context {return page;}+ resolvePageById(pageId?: number): Page {+ if (pageId === undefined) {+ return this.getSelectedPage();+ }+ return this.getPageById(pageId);+ }+getPageById(pageId: number): Page {- const page = this.#pages.find(p => this.#pageIdMap.get(p) === pageId);+ const page = this.#pages.find(p => this.#mcpPages.get(p)?.id === pageId);if (!page) {throw new Error('No page found');}@@ -522,27 +537,48 @@ export class McpContext implements Context {}getPageId(page: Page): number | undefined {- return this.#pageIdMap.get(page);+ return this.#mcpPages.get(page)?.id;}- #dialogHandler = (dialog: Dialog): void => {- this.#dialog = dialog;- };+ #getMcpPage(page: Page): McpPage {+ const mcpPage = this.#mcpPages.get(page);+ if (!mcpPage) {+ throw new Error('No McpPage found for the given page.');+ }+ return mcpPage;+ }++ #getSelectedMcpPage(): McpPage {+ return this.#getMcpPage(this.getSelectedPage());+ }isPageSelected(page: Page): boolean {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 oldPage = this.#selectedPage;- if (oldPage) {- oldPage.off('dialog', this.#dialogHandler);- void oldPage.emulateFocusedPage(false).catch(error => {+ const ctx = newPage.browserContext();+ const oldFocused = this.#focusedPagePerContext.get(ctx);+ if (oldFocused && oldFocused !== newPage && !oldFocused.isClosed()) {+ void oldFocused.emulateFocusedPage(false).catch(error => {this.logger('Error turning off focused page emulation', error);});}+ this.#focusedPagePerContext.set(ctx, newPage);this.#selectedPage = newPage;- newPage.on('dialog', this.#dialogHandler);this.#updateSelectedPageTimeouts();void newPage.emulateFocusedPage(true).catch(error => {this.logger('Error turning on focused page emulation', error);@@ -565,36 +601,78 @@ export class McpContext implements Context {}getNavigationTimeout() {- const page = this.getSelectedPage();+ const page = this.#resolveTargetPage();return page.getDefaultNavigationTimeout();}+ // Linear scan over per-page snapshots. The page count is small (typically+ // 2-10) so a reverse index isn't worthwhile given the uid-reuse lifecycle+ // complexity it would introduce.getAXNodeByUid(uid: string) {- return this.#textSnapshot?.idToNode.get(uid);- }+ for (const mcpPage of this.#mcpPages.values()) {+ const node = mcpPage.textSnapshot?.idToNode.get(uid);+ if (node) {+ return node;+ }+ }+ return undefined;+ }++ 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);+ }- async getElementByUid(uid: string): Promise<ElementHandle<Element>> {- if (!this.#textSnapshot?.idToNode.size) {+ // 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 !== searchPage) {+ const targetId = mcpPage.id;+ const selectedId = contextSelectedPage+ ? this.#mcpPages.get(contextSelectedPage)?.id+ : this.#getSelectedMcpPage().id;+ throw new Error(+ `Element uid "${uid}" belongs to page ${targetId}, but page ${selectedId} is currently selected. ` ++ `Call select_page with pageId ${targetId} first.`,+ );+ }+ // Align global #selectedPage for waitForEventsAfterAction etc.+ if (this.#selectedPage !== searchPage) {+ this.#selectedPage = searchPage;+ }+ return this.#resolveElementHandle(node, uid);+ }+ }+ if (!anySnapshot) {throw new Error(`No snapshot found. Use ${takeSnapshot.name} to capture one.`,);}- const node = this.#textSnapshot?.idToNode.get(uid);- if (!node) {- throw new Error('No such element found in the snapshot.');- }- 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,- });- }+ throw new Error('No such element found in any snapshot.');}/**@@ -632,12 +710,48 @@ 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 allPages = await this.#getAllPages();+ const {pages: allPages, isolatedContextNames} = await this.#getAllPages();for (const page of allPages) {- if (!this.#pageIdMap.has(page)) {- this.#pageIdMap.set(page, this.#nextPageId++);+ let mcpPage = this.#mcpPages.get(page);+ if (!mcpPage) {+ mcpPage = new McpPage(page, this.#nextPageId++);+ this.#mcpPages.set(page, mcpPage);+ }+ 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);}}@@ -660,7 +774,10 @@ export class McpContext implements Context {return this.#pages;}- async #getAllPages(): Promise<Page[]> {+ async #getAllPages(): Promise<{+ pages: Page[];+ isolatedContextNames: Map<Page, string>;+ }> {const defaultCtx = this.browser.defaultBrowserContext();const allPages = await this.browser.pages(this.#options.experimentalIncludeAllPages,@@ -683,22 +800,26 @@ export class McpContext implements Context {}}- // Use page.browserContext() to determine each page's context membership.+ // Map each page to its isolated context name (if any).+ const isolatedContextNames = new Map<Page, string>();for (const page of allPages) {const ctx = page.browserContext();const name = contextToName.get(ctx);if (name) {- this.#pageToIsolatedContextName.set(page, name);+ isolatedContextNames.set(page, name);}}- return allPages;+ return {pages: allPages, isolatedContextNames};}async detectOpenDevToolsWindows() {this.logger('Detecting open DevTools windows');- const pages = await this.#getAllPages();- this.#pageToDevToolsPage = new Map<Page, Page>();+ const {pages} = await this.#getAllPages();+ // Clear all devToolsPage references before re-detecting.+ for (const mcpPage of this.#mcpPages.values()) {+ mcpPage.devToolsPage = undefined;+ }for (const devToolsPage of pages) {if (devToolsPage.url().startsWith('devtools://')) {try {@@ -715,7 +836,10 @@ export class McpContext implements Context {// TODO: lookup without a loop.for (const page of this.#pages) {if (urlsEqual(page.url(), urlLike)) {- this.#pageToDevToolsPage.set(page, devToolsPage);+ const mcpPage = this.#mcpPages.get(page);+ if (mcpPage) {+ mcpPage.devToolsPage = devToolsPage;+ }}}} catch (error) {@@ -740,17 +864,17 @@ export class McpContext implements Context {}getIsolatedContextName(page: Page): string | undefined {- return this.#pageToIsolatedContextName.get(page);+ return this.#mcpPages.get(page)?.isolatedContextName;}getDevToolsPage(page: Page): Page | undefined {- return this.#pageToDevToolsPage.get(page);+ return this.#mcpPages.get(page)?.devToolsPage;}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');@@ -787,8 +911,10 @@ export class McpContext implements Context {async createTextSnapshot(verbose = false,devtoolsData: DevToolsData | undefined = undefined,+ targetPage?: Page,): Promise<void> {- const page = this.getSelectedPage();+ const page = targetPage ?? this.getSelectedPage();+ const mcpPage = this.#getMcpPage(page);const rootNode = await page.accessibility.snapshot({includeIframes: true,interestingOnly: !verbose,@@ -797,6 +923,8 @@ export class McpContext implements Context {return;}+ const {uniqueBackendNodeIdToMcpId} = mcpPage;+const snapshotId = this.#nextSnapshotId++;// Iterate through the whole accessibility node tree and assign node ids that// will be used for the tree serialization and mapping ids back to nodes.@@ -807,13 +935,13 @@ export class McpContext implements Context {let id = '';// @ts-expect-error untyped loaderId & backendNodeId.const uniqueBackendId = `${node.loaderId}_${node.backendNodeId}`;- if (this.#uniqueBackendNodeIdToMcpId.has(uniqueBackendId)) {+ if (uniqueBackendNodeIdToMcpId.has(uniqueBackendId)) {// Re-use MCP exposed ID if the uniqueId is the same.- id = this.#uniqueBackendNodeIdToMcpId.get(uniqueBackendId)!;+ id = uniqueBackendNodeIdToMcpId.get(uniqueBackendId)!;} else {// Only generate a new ID if we have not seen the node before.id = `${snapshotId}_${idCounter++}`;- this.#uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);+ uniqueBackendNodeIdToMcpId.set(uniqueBackendId, id);}seenUniqueIds.add(uniqueBackendId);@@ -839,31 +967,37 @@ export class McpContext implements Context {};const rootNodeWithId = assignIds(rootNode);- this.#textSnapshot = {+ const snapshot: TextSnapshot = {root: rootNodeWithId,snapshotId: String(snapshotId),idToNode,hasSelectedElement: false,verbose,};+ mcpPage.textSnapshot = snapshot;const data = devtoolsData ?? (await this.getDevToolsData());if (data?.cdpBackendNodeId) {- this.#textSnapshot.hasSelectedElement = true;- this.#textSnapshot.selectedElementUid = this.resolveCdpElementId(+ snapshot.hasSelectedElement = true;+ snapshot.selectedElementUid = this.resolveCdpElementId(data?.cdpBackendNodeId,+ page,);}// Clean up unique IDs that we did not see anymore.- for (const key of this.#uniqueBackendNodeIdToMcpId.keys()) {+ for (const key of uniqueBackendNodeIdToMcpId.keys()) {if (!seenUniqueIds.has(key)) {- this.#uniqueBackendNodeIdToMcpId.delete(key);+ uniqueBackendNodeIdToMcpId.delete(key);}}}- getTextSnapshot(): TextSnapshot | null {- return this.#textSnapshot;+ getTextSnapshot(targetPage?: Page): TextSnapshot | null {+ const page = targetPage ?? this.#selectedPage;+ if (!page) {+ return null;+ }+ return this.#mcpPages.get(page)?.textSnapshot ?? null;}async saveTemporaryFile(@@ -939,8 +1073,12 @@ export class McpContext implements Context {return this.#networkCollector.getIdForResource(request);}- waitForTextOnPage(text: string[], timeout?: number): Promise<Element> {- const page = this.getSelectedPage();+ waitForTextOnPage(+ text: string[],+ timeout?: number,+ targetPage?: Page,+ ): Promise<Element> {+ const page = targetPage ?? this.getSelectedPage();const frames = page.frames();let locator = this.#locatorClass.race(@@ -973,7 +1111,7 @@ export class McpContext implements Context {},} as ListenerMap;});- const pages = await this.#getAllPages();+ const {pages} = await this.#getAllPages();await this.#networkCollector.init(pages);}diff --git a/src/McpPage.ts b/src/McpPage.tsnew file mode 100644index 00000000..51a30448--- /dev/null+++ b/src/McpPage.ts@@ -0,0 +1,85 @@+/**+ * @license+ * Copyright 2025 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import type {Dialog, Page, Viewport} from './third_party/index.js';+import type {+ EmulationSettings,+ GeolocationOptions,+ TextSnapshot,+} from './types.js';++/**+ * Per-page state wrapper. Consolidates dialog, snapshot, emulation,+ * and metadata that were previously scattered across Maps in McpContext.+ *+ * Internal class consumed only by McpContext. Fields are public for direct+ * read/write access. The dialog field is private because it requires an+ * event listener lifecycle managed by the constructor/dispose pair.+ */+export class McpPage {+ readonly page: Page;+ readonly id: number;++ // Snapshot+ textSnapshot: TextSnapshot | null = null;+ uniqueBackendNodeIdToMcpId = new Map<string, string>();++ // Emulation+ emulationSettings: EmulationSettings = {};++ // Metadata+ isolatedContextName?: string;+ devToolsPage?: Page;++ // Dialog+ #dialog?: Dialog;+ #dialogHandler: (dialog: Dialog) => void;++ constructor(page: Page, id: number) {+ this.page = page;+ this.id = id;+ this.#dialogHandler = (dialog: Dialog): void => {+ this.#dialog = dialog;+ };+ page.on('dialog', this.#dialogHandler);+ }++ get dialog(): Dialog | undefined {+ return this.#dialog;+ }++ clearDialog(): void {+ this.#dialog = undefined;+ }++ get networkConditions(): string | null {+ return this.emulationSettings.networkConditions ?? null;+ }++ get cpuThrottlingRate(): number {+ return this.emulationSettings.cpuThrottlingRate ?? 1;+ }++ get geolocation(): GeolocationOptions | null {+ return this.emulationSettings.geolocation ?? null;+ }++ get viewport(): Viewport | null {+ return this.emulationSettings.viewport ?? null;+ }++ get userAgent(): string | null {+ return this.emulationSettings.userAgent ?? null;+ }++ get colorScheme(): 'dark' | 'light' | null {+ return this.emulationSettings.colorScheme ?? null;+ }++ dispose(): void {+ this.page.off('dialog', this.#dialogHandler);+ }+}diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex 243cd81c..33f631d1 100644--- a/src/McpResponse.ts+++ b/src/McpResponse.ts@@ -253,8 +253,9 @@ export class McpResponse implements Response {await context.createTextSnapshot(this.#snapshotParams.verbose,this.#devToolsData,+ this.#snapshotParams.page,);- const textSnapshot = context.getTextSnapshot();+ const textSnapshot = context.getTextSnapshot(this.#snapshotParams.page);if (textSnapshot) {const formatter = new SnapshotFormatter(textSnapshot);if (this.#snapshotParams.filePath) {diff --git a/src/cli.ts b/src/cli.tsindex c585ea4c..1b3c585a 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -147,6 +147,12 @@ export const cliOptions = {type: 'boolean',description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,},+ experimentalPageIdRouting: {+ type: 'boolean',+ describe:+ 'Whether to expose pageId on page-scoped tools and route requests by page ID.',+ hidden: true,+ },experimentalDevtools: {type: 'boolean',describe: 'Whether to enable automation over DevTools targets',diff --git a/src/server.ts b/src/server.tsindex 42d49180..7f984337 100644--- a/src/server.ts+++ b/src/server.ts@@ -24,6 +24,7 @@ import {} from './third_party/index.js';import {ToolCategory} from './tools/categories.js';import type {ToolDefinition} from './tools/ToolDefinition.js';+import {pageIdSchema} from './tools/ToolDefinition.js';import {createTools} from './tools/tools.js';import {VERSION} from './version.js';@@ -149,11 +150,16 @@ export async function createMcpServer() {return;}+ const schema =+ tool.annotations.pageScoped && serverArgs.experimentalPageIdRouting+ ? {...tool.schema, ...pageIdSchema}+ : tool.schema;+server.registerTool(tool.name,{description: tool.description,- inputSchema: tool.schema,+ inputSchema: schema,annotations: tool.annotations,},async (params): Promise<CallToolResult> => {@@ -168,31 +174,42 @@ export async function createMcpServer(const response = serverArgs.slim? new SlimMcpResponse(serverArgs): new McpResponse(serverArgs);-- await tool.handler(- {- params,- },- response,- context,- );- const {content, structuredContent} = await response.handle(- tool.name,- context,- );- const result: CallToolResult & {- structuredContent?: Record<string, unknown>;- } = {- content,- };- success = true;- if (serverArgs.experimentalStructuredContent) {- result.structuredContent = structuredContent as Record<- string,- unknown- >;+ const page =+ tool.annotations.pageScoped && serverArgs.experimentalPageIdRouting+ ? context.resolvePageById(params.pageId as number | undefined)+ : undefined;+ if (page) {+ context.setRequestPage(page);+ }+ try {+ await tool.handler(+ {+ params,+ page,+ },+ response,+ context,+ );+ const {content, structuredContent} = await response.handle(+ tool.name,+ context,+ );+ const result: CallToolResult & {+ structuredContent?: Record<string, unknown>;+ } = {+ content,+ };+ success = true;+ if (serverArgs.experimentalStructuredContent) {+ result.structuredContent = structuredContent as Record<+ string,+ unknown+ >;+ }+ return result;+ } finally {+ context.setRequestPage(undefined);}- return result;} catch (err) {logger(`${tool.name} error:`, err, err?.stack);let errorText = err && 'message' in err ? err.message : String(err);diff --git a/src/tools/ToolDefinition.ts b/src/tools/ToolDefinition.tsindex b2bea87a..8b16e3b2 100644--- a/src/tools/ToolDefinition.ts+++ b/src/tools/ToolDefinition.ts@@ -5,7 +5,6 @@*/import type {ParsedArguments} from '../cli.js';-import type {TextSnapshotNode, GeolocationOptions} from '../McpContext.js';import {zod} from '../third_party/index.js';import type {Dialog,@@ -15,6 +14,7 @@ import type {Viewport,} from '../third_party/index.js';import type {InsightName, TraceResult} from '../trace-processing/parse.js';+import type {TextSnapshotNode, GeolocationOptions} from '../types.js';import type {InstalledExtension} from '../utils/ExtensionRegistry.js';import type {PaginationOptions} from '../utils/types.js';@@ -33,6 +33,12 @@ export interface ToolDefinition<*/readOnlyHint: boolean;conditions?: string[];+ /**+ * If true, the tool operates on a specific page.+ * The `pageId` schema field is auto-injected and the resolved+ * page is provided via `request.page`.+ */+ pageScoped?: boolean;};schema: Schema;handler: (@@ -44,6 +50,8 @@ export interface ToolDefinition<export interface Request<Schema extends zod.ZodRawShape> {params: zod.objectOutputType<Schema, zod.ZodTypeAny>;+ /** Populated centrally for tools with `pageScoped: true`. */+ page?: Page;}export interface ImageContentData {@@ -54,6 +62,7 @@ export interface ImageContentData {export interface SnapshotParams {verbose?: boolean;filePath?: string;+ page?: Page;}export interface DevToolsData {@@ -107,23 +116,28 @@ export type Context = Readonly<{isCruxEnabled(): boolean;recordedTraces(): TraceResult[];storeTraceRecording(result: TraceResult): void;+ // TODO: Remove once slim tools are converted to pageScoped: true.getSelectedPage(): Page;- getDialog(): Dialog | undefined;- clearDialog(): void;+ getDialog(page?: Page): Dialog | undefined;+ clearDialog(page?: Page): void;getPageById(pageId: number): Page;newPage(background?: boolean, isolatedContextName?: string): Promise<Page>;closePage(pageId: number): Promise<void>;selectPage(page: Page): void;- getElementByUid(uid: string): Promise<ElementHandle<Element>>;+ assertPageIsFocused(page: Page): void;+ getElementByUid(uid: string, page?: Page): Promise<ElementHandle<Element>>;getAXNodeByUid(uid: string): TextSnapshotNode | undefined;- emulate(options: {- networkConditions?: string | null;- cpuThrottlingRate?: number | null;- geolocation?: GeolocationOptions | null;- userAgent?: string | null;- colorScheme?: 'dark' | 'light' | 'auto' | null;- viewport?: Viewport | null;- }): Promise<void>;+ emulate(+ options: {+ networkConditions?: string | null;+ cpuThrottlingRate?: number | null;+ geolocation?: GeolocationOptions | null;+ userAgent?: string | null;+ colorScheme?: 'dark' | 'light' | 'auto' | null;+ viewport?: Viewport | null;+ },+ targetPage?: Page,+ ): Promise<void>;saveTemporaryFile(data: Uint8Array<ArrayBufferLike>,mimeType: 'image/png' | 'image/jpeg' | 'image/webp',@@ -136,16 +150,16 @@ export type Context = Readonly<{action: () => Promise<unknown>,options?: {timeout?: number},): Promise<void>;- waitForTextOnPage(text: string[], timeout?: number): Promise<Element>;+ waitForTextOnPage(+ text: string[],+ timeout?: number,+ page?: Page,+ ): Promise<Element>;getDevToolsData(): Promise<DevToolsData>;/*** Returns a reqid for a cdpRequestId.*/resolveCdpRequestId(cdpRequestId: string): number | undefined;- /**- * Returns a reqid for a cdpRequestId.- */- resolveCdpElementId(cdpBackendNodeId: number): string | undefined;getScreenRecorder(): {recorder: ScreenRecorder; filePath: string} | null;setScreenRecorder(data: {recorder: ScreenRecorder; filePath: string} | null,@@ -175,12 +189,40 @@ export function defineTool<| ToolDefinition<Schema>| ((args?: Args) => ToolDefinition<Schema>),) {+ if (typeof definition === 'function') {+ const factory = definition;+ return (args: Args) => {+ const tool = factory(args);+ wrapPageScopedHandler(tool);+ return tool;+ };+ }+ wrapPageScopedHandler(definition);return definition;}+function wrapPageScopedHandler<Schema extends zod.ZodRawShape>(+ definition: ToolDefinition<Schema>,+) {+ if (definition.annotations.pageScoped) {+ const originalHandler = definition.handler;+ definition.handler = async (request, response, context) => {+ // In production, main.ts resolves request.page centrally before calling+ // the handler. This fallback exists for tests that invoke handlers+ // directly without going through main.ts.+ request.page ??= context.getSelectedPage();+ return originalHandler(request, response, context);+ };+ }+}+export const CLOSE_PAGE_ERROR ='The last open page cannot be closed. It is fine to keep it open.';+export const pageIdSchema = {+ pageId: zod.number().optional().describe('Targets a specific page by ID.'),+};+export const timeoutSchema = {timeout: zod.number()diff --git a/src/tools/console.ts b/src/tools/console.tsindex ace8f628..1f6aa377 100644--- a/src/tools/console.ts+++ b/src/tools/console.ts@@ -44,6 +44,7 @@ export const listConsoleMessages = defineTool({annotations: {category: ToolCategory.DEBUGGING,readOnlyHint: true,+ pageScoped: true,},schema: {pageSize: zod@@ -92,6 +93,7 @@ export const getConsoleMessage = defineTool({annotations: {category: ToolCategory.DEBUGGING,readOnlyHint: true,+ pageScoped: true,},schema: {msgid: zoddiff --git a/src/tools/emulation.ts b/src/tools/emulation.tsindex ea0538fd..b05221f0 100644--- a/src/tools/emulation.ts+++ b/src/tools/emulation.ts@@ -22,6 +22,7 @@ export const emulate = defineTool({annotations: {category: ToolCategory.EMULATION,readOnlyHint: false,+ pageScoped: true,},schema: {networkConditions: zod@@ -104,6 +105,7 @@ export const emulate = defineTool({),},handler: async (request, _response, context) => {- await context.emulate(request.params);+ const page = request.page!;+ await context.emulate(request.params, page);},});diff --git a/src/tools/input.ts b/src/tools/input.tsindex 2c338a52..d88b707c 100644--- a/src/tools/input.ts+++ b/src/tools/input.ts@@ -7,7 +7,7 @@import {logger} from '../logger.js';import type {McpContext, TextSnapshotNode} from '../McpContext.js';import {zod} from '../third_party/index.js';-import type {ElementHandle, KeyInput} from '../third_party/index.js';+import type {ElementHandle, KeyInput, Page} from '../third_party/index.js';import {parseKey} from '../utils/keyboard.js';import {ToolCategory} from './categories.js';@@ -88,6 +88,7 @@ export const clickAt = defineTool({category: ToolCategory.INPUT,readOnlyHint: false,conditions: ['computerVision'],+ pageScoped: true,},schema: {x: zod.number().describe('The x coordinate'),@@ -96,7 +97,8 @@ export const clickAt = defineTool({includeSnapshot: includeSnapshotSchema,},handler: async (request, response, context) => {- const page = context.getSelectedPage();+ const page = request.page!;+ context.assertPageIsFocused(page);await context.waitForEventsAfterAction(async () => {await page.mouse.click(request.params.x, request.params.y, {clickCount: request.params.dblClick ? 2 : 1,@@ -108,7 +110,7 @@ export const clickAt = defineTool({: `Successfully clicked at the coordinates`,);if (request.params.includeSnapshot) {- response.includeSnapshot();+ response.includeSnapshot({page});}},});@@ -192,8 +194,9 @@ async function fillFormElement(uid: string,value: string,context: McpContext,+ page: Page,) {- const handle = await context.getElementByUid(uid);+ const handle = await context.getElementByUid(uid, page);try {const aXNode = context.getAXNodeByUid(uid);// We assume that combobox needs to be handled as select if it has@@ -204,8 +207,7 @@ async function fillFormElement(// Increase timeout for longer input values.const timeoutPerChar = 10; // msconst fillTimeout =- context.getSelectedPage().getDefaultTimeout() +- value.length * timeoutPerChar;+ page.getDefaultTimeout() + value.length * timeoutPerChar;await handle.asLocator().setTimeout(fillTimeout).fill(value);}} catch (error) {@@ -221,6 +223,7 @@ export const fill = defineTool({annotations: {category: ToolCategory.INPUT,readOnlyHint: false,+ pageScoped: true,},schema: {uid: zod@@ -232,16 +235,18 @@ export const fill = defineTool({includeSnapshot: includeSnapshotSchema,},handler: async (request, response, context) => {+ const page = request.page!;await context.waitForEventsAfterAction(async () => {await fillFormElement(request.params.uid,request.params.value,context as McpContext,+ page,);});response.appendResponseLine(`Successfully filled out the element`);if (request.params.includeSnapshot) {- response.includeSnapshot();+ response.includeSnapshot({page});}},});@@ -252,14 +257,16 @@ export const typeText = defineTool({annotations: {category: ToolCategory.INPUT,readOnlyHint: false,+ pageScoped: true,},schema: {text: zod.string().describe('The text to type'),submitKey: submitKeySchema,},handler: async (request, response, context) => {+ const page = request.page!;+ context.assertPageIsFocused(page);await context.waitForEventsAfterAction(async () => {- const page = context.getSelectedPage();await page.keyboard.type(request.params.text);if (request.params.submitKey) {await page.keyboard.press(request.params.submitKey as KeyInput);@@ -309,6 +316,7 @@ export const fillForm = defineTool({annotations: {category: ToolCategory.INPUT,readOnlyHint: false,+ pageScoped: true,},schema: {elements: zod@@ -322,18 +330,20 @@ export const fillForm = defineTool({includeSnapshot: includeSnapshotSchema,},handler: async (request, response, context) => {+ const page = request.page!;for (const element of request.params.elements) {await context.waitForEventsAfterAction(async () => {await fillFormElement(element.uid,element.value,context as McpContext,+ page,);});}response.appendResponseLine(`Successfully filled out the form`);if (request.params.includeSnapshot) {- response.includeSnapshot();+ response.includeSnapshot({page});}},});@@ -344,6 +354,7 @@ export const uploadFile = defineTool({annotations: {category: ToolCategory.INPUT,readOnlyHint: false,+ pageScoped: true,},schema: {uid: zod@@ -358,6 +369,7 @@ export const uploadFile = defineTool({const {uid, filePath} = request.params;const handle = (await context.getElementByUid(uid,+ request.page,)) as ElementHandle<HTMLInputElement>;try {try {@@ -367,9 +379,8 @@ export const uploadFile = defineTool({// a type=file element. In this case, we want to default to// Page.waitForFileChooser() and upload the file this way.try {- const page = context.getSelectedPage();const [fileChooser] = await Promise.all([- page.waitForFileChooser({timeout: 3000}),+ request.page!.waitForFileChooser({timeout: 3000}),handle.asLocator().click(),]);await fileChooser.accept([filePath]);@@ -380,7 +391,7 @@ export const uploadFile = defineTool({}}if (request.params.includeSnapshot) {- response.includeSnapshot();+ response.includeSnapshot({page: request.page!});}response.appendResponseLine(`File uploaded from ${filePath}.`);} finally {@@ -395,6 +406,7 @@ export const pressKey = defineTool({annotations: {category: ToolCategory.INPUT,readOnlyHint: false,+ pageScoped: true,},schema: {key: zod@@ -405,7 +417,8 @@ export const pressKey = defineTool({includeSnapshot: includeSnapshotSchema,},handler: async (request, response, context) => {- const page = context.getSelectedPage();+ const page = request.page!;+ context.assertPageIsFocused(page);const tokens = parseKey(request.params.key);const [key, ...modifiers] = tokens;@@ -423,7 +436,7 @@ export const pressKey = defineTool({`Successfully pressed key: ${request.params.key}`,);if (request.params.includeSnapshot) {- response.includeSnapshot();+ response.includeSnapshot({page});}},});diff --git a/src/tools/memory.ts b/src/tools/memory.tsindex d75122ba..dc9252a8 100644--- a/src/tools/memory.ts+++ b/src/tools/memory.ts@@ -15,14 +15,15 @@ export const takeMemorySnapshot = defineTool({annotations: {category: ToolCategory.PERFORMANCE,readOnlyHint: true,+ pageScoped: true,},schema: {filePath: zod.string().describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),},- handler: async (request, response, context) => {- const page = context.getSelectedPage();+ handler: async (request, response, _context) => {+ const page = request.page!;await page.captureHeapSnapshot({path: request.params.filePath,diff --git a/src/tools/network.ts b/src/tools/network.tsindex 9a1d9da7..10e64cd9 100644--- a/src/tools/network.ts+++ b/src/tools/network.ts@@ -38,6 +38,7 @@ export const listNetworkRequests = defineTool({annotations: {category: ToolCategory.NETWORK,readOnlyHint: true,+ pageScoped: true,},schema: {pageSize: zod@@ -92,6 +93,7 @@ export const getNetworkRequest = defineTool({annotations: {category: ToolCategory.NETWORK,readOnlyHint: false,+ pageScoped: true,},schema: {reqid: zoddiff --git a/src/tools/pages.ts b/src/tools/pages.tsindex b3afe619..780f72f3 100644--- a/src/tools/pages.ts+++ b/src/tools/pages.ts@@ -130,6 +130,7 @@ export const navigatePage = defineTool({annotations: {category: ToolCategory.NAVIGATION,readOnlyHint: false,+ pageScoped: true,},schema: {type: zod@@ -158,7 +159,7 @@ export const navigatePage = defineTool({...timeoutSchema,},handler: async (request, response, context) => {- const page = context.getSelectedPage();+ const page = request.page!;const options = {timeout: request.params.timeout,};@@ -182,7 +183,7 @@ export const navigatePage = defineTool({void dialog.dismiss();}// We are not going to report the dialog like regular dialogs.- context.clearDialog();+ context.clearDialog(page);}};@@ -279,13 +280,14 @@ export const resizePage = defineTool({annotations: {category: ToolCategory.EMULATION,readOnlyHint: false,+ pageScoped: true,},schema: {width: zod.number().describe('Page width'),height: zod.number().describe('Page height'),},- handler: async (request, response, context) => {- const page = context.getSelectedPage();+ handler: async (request, response, _context) => {+ const page = request.page!;try {const browser = page.browser();@@ -318,6 +320,7 @@ export const handleDialog = defineTool({annotations: {category: ToolCategory.INPUT,readOnlyHint: false,+ pageScoped: true,},schema: {action: zod@@ -329,7 +332,8 @@ export const handleDialog = defineTool({.describe('Optional prompt text to enter into the dialog.'),},handler: async (request, response, context) => {- const dialog = context.getDialog();+ const page = request.page!;+ const dialog = context.getDialog(page);if (!dialog) {throw new Error('No open dialog found');}@@ -357,7 +361,7 @@ export const handleDialog = defineTool({}}- context.clearDialog();+ context.clearDialog(page);response.setIncludePages(true);},});diff --git a/src/tools/performance.ts b/src/tools/performance.tsindex 393d38f1..dd5f45e0 100644--- a/src/tools/performance.ts+++ b/src/tools/performance.ts@@ -32,6 +32,7 @@ export const startTrace = defineTool({annotations: {category: ToolCategory.PERFORMANCE,readOnlyHint: false,+ pageScoped: true,},schema: {reload: zod@@ -55,7 +56,7 @@ export const startTrace = defineTool({}context.setIsRunningPerformanceTrace(true);- const page = context.getSelectedPage();+ const page = request.page!;const pageUrlForTracing = page.url();if (request.params.reload) {@@ -119,6 +120,7 @@ export const stopTrace = defineTool({annotations: {category: ToolCategory.PERFORMANCE,readOnlyHint: false,+ pageScoped: true,},schema: {filePath: filePathSchema,@@ -127,7 +129,7 @@ export const stopTrace = defineTool({if (!context.isRunningPerformanceTrace()) {return;}- const page = context.getSelectedPage();+ const page = request.page!;await stopTracingAndAppendOutput(page,response,diff --git a/src/tools/screencast.ts b/src/tools/screencast.tsindex d24d9b0f..96626abf 100644--- a/src/tools/screencast.ts+++ b/src/tools/screencast.ts@@ -26,6 +26,7 @@ export const startScreencast = defineTool({annotations: {category: ToolCategory.DEBUGGING,readOnlyHint: false,+ pageScoped: true,conditions: ['screencast'],},schema: {@@ -47,7 +48,7 @@ export const startScreencast = defineTool({const filePath = request.params.path ?? (await generateTempFilePath());const resolvedPath = path.resolve(filePath);- const page = context.getSelectedPage();+ const page = request.page!;let recorder: ScreenRecorder;try {diff --git a/src/tools/screenshot.ts b/src/tools/screenshot.tsindex 4312c02a..4269f6e6 100644--- a/src/tools/screenshot.ts+++ b/src/tools/screenshot.ts@@ -17,6 +17,7 @@ export const screenshot = defineTool({category: ToolCategory.DEBUGGING,// Not read-only due to filePath param.readOnlyHint: false,+ pageScoped: true,},schema: {format: zod@@ -57,9 +58,12 @@ export const screenshot = defineTool({let pageOrHandle: Page | ElementHandle;if (request.params.uid) {- pageOrHandle = await context.getElementByUid(request.params.uid);+ pageOrHandle = await context.getElementByUid(+ request.params.uid,+ request.page,+ );} else {- pageOrHandle = context.getSelectedPage();+ pageOrHandle = request.page!;}const format = request.params.format;diff --git a/src/tools/script.ts b/src/tools/script.tsindex f3bc3c3c..c0e5f5b6 100644--- a/src/tools/script.ts+++ b/src/tools/script.ts@@ -17,6 +17,7 @@ so returned values have to be JSON-serializable.`,annotations: {category: ToolCategory.DEBUGGING,readOnlyHint: false,+ pageScoped: true,},schema: {function: zod.string().describe(@@ -49,7 +50,7 @@ Example with arguments: \`(el) => {try {const frames = new Set<Frame>();for (const el of request.params.args ?? []) {- const handle = await context.getElementByUid(el.uid);+ const handle = await context.getElementByUid(el.uid, request.page);frames.add(handle.frame);args.push(handle);}@@ -60,7 +61,7 @@ Example with arguments: \`(el) => {"Elements from different frames can't be evaluated together.",);} else {- pageOrFrame = [...frames.values()][0] ?? context.getSelectedPage();+ pageOrFrame = [...frames.values()][0] ?? request.page!;}const fn = await pageOrFrame.evaluateHandle(`(${request.params.function})`,diff --git a/src/tools/snapshot.ts b/src/tools/snapshot.tsindex a07bf582..b8d7a9df 100644--- a/src/tools/snapshot.ts+++ b/src/tools/snapshot.ts@@ -18,6 +18,7 @@ in the DevTools Elements panel (if any).`,category: ToolCategory.DEBUGGING,// Not read-only due to filePath param.readOnlyHint: false,+ pageScoped: true,},schema: {verbose: zod@@ -37,6 +38,7 @@ in the DevTools Elements panel (if any).`,response.includeSnapshot({verbose: request.params.verbose ?? false,filePath: request.params.filePath,+ page: request.page!,});},});@@ -47,6 +49,7 @@ export const waitFor = defineTool({annotations: {category: ToolCategory.NAVIGATION,readOnlyHint: true,+ pageScoped: true,},schema: {text: zod@@ -58,15 +61,17 @@ export const waitFor = defineTool({...timeoutSchema,},handler: async (request, response, context) => {+ const page = request.page!;await context.waitForTextOnPage(request.params.text,request.params.timeout,+ page,);response.appendResponseLine(`Element matching one of ${JSON.stringify(request.params.text)} found.`,);- response.includeSnapshot();+ response.includeSnapshot({page});},});diff --git a/src/types.ts b/src/types.tsnew file mode 100644index 00000000..69dddd2a--- /dev/null+++ b/src/types.ts@@ -0,0 +1,39 @@+/**+ * @license+ * Copyright 2025 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import type {SerializedAXNode, Viewport} from './third_party/index.js';++export interface TextSnapshotNode extends SerializedAXNode {+ id: string;+ backendNodeId?: number;+ loaderId?: string;+ children: TextSnapshotNode[];+}++export interface GeolocationOptions {+ latitude: number;+ longitude: number;+}++export interface TextSnapshot {+ root: TextSnapshotNode;+ idToNode: Map<string, TextSnapshotNode>;+ snapshotId: string;+ selectedElementUid?: string;+ // It might happen that there is a selected element, but it is not part of the+ // snapshot. This flag indicates if there is any selected element.+ hasSelectedElement: boolean;+ verbose: boolean;+}++export interface EmulationSettings {+ networkConditions?: string | null;+ cpuThrottlingRate?: number | null;+ geolocation?: GeolocationOptions | null;+ userAgent?: string | null;+ colorScheme?: 'dark' | 'light' | null;+ viewport?: Viewport | null;+}diff --git a/tests/McpContext.test.ts b/tests/McpContext.test.tsindex 03c51351..a0dd0091 100644--- a/tests/McpContext.test.ts+++ b/tests/McpContext.test.ts@@ -101,6 +101,178 @@ describe('McpContext', () => {},);});+ it('resolves uid from a non-selected page snapshot', async () => {+ await withMcpContext(async (_response, context) => {+ // Page 1: set content and snapshot+ const page1 = context.getSelectedPage();+ await page1.setContent(html`<button>Page1 Button</button>`);+ await context.createTextSnapshot(false, undefined, page1);++ // Capture a uid from page1's snapshot (snapshotId=1, button is node 1)+ const page1Uid = '1_1';+ const page1Node = context.getAXNodeByUid(page1Uid);+ assert.ok(page1Node, 'uid should resolve from page1 snapshot');++ // Page 2: new page, set content, snapshot+ const page2 = await context.newPage();+ context.selectPage(page2);+ await page2.setContent(html`<button>Page2 Button</button>`);+ await context.createTextSnapshot(false, undefined, page2);++ // Page 2 is now selected. Page 1's uid should still resolve.+ const node = context.getAXNodeByUid(page1Uid);+ assert.ok(node, 'page1 uid should still resolve after page2 snapshot');+ assert.strictEqual(node?.name, 'Page1 Button');++ // The element should also be retrievable when the target page is provided.+ const element = await context.getElementByUid(page1Uid, page1);+ assert.ok(element, 'should get element handle from page1 snapshot uid');+ });+ });++ describe('getElementByUid context-focus validation', () => {+ it('resolves for the focused page in an isolated context', async () => {+ await withMcpContext(async (_response, context) => {+ const page = await context.newPage(false, 'agent-a');+ await page.setContent(html`<button>A1 Button</button>`);+ await context.createTextSnapshot(false, undefined, page);++ // page is focused for agent-a context; should resolve.+ const handle = await context.getElementByUid('1_1');+ void handle.dispose();+ });+ });++ it('throws for a non-focused page in the same context', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'agent-a');+ await pageA1.setContent(html`<button>A1 Button</button>`);+ await context.createTextSnapshot(false, undefined, pageA1);+ const a1Uid = '1_1'; // button on pageA1++ // Open a second page in the same context (becomes focused).+ const pageA2 = await context.newPage(false, 'agent-a');+ await pageA2.setContent(html`<button>A2 Button</button>`);+ await context.createTextSnapshot(false, undefined, pageA2);++ // pageA2 is now focused for agent-a; clicking pageA1's uid should throw.+ await assert.rejects(+ () => context.getElementByUid(a1Uid),+ (err: Error) => {+ assert.ok(err.message.includes('belongs to page'));+ assert.ok(err.message.includes('currently selected'));+ return true;+ },+ );+ });+ });++ it('resolves after cross-context select_page race', async () => {+ await withMcpContext(async (_response, context) => {+ // Set up two pages in separate isolated contexts.+ const pageA = await context.newPage(false, 'agent-a');+ await pageA.setContent(html`<button>Agent A Button</button>`);+ await context.createTextSnapshot(false, undefined, pageA);+ const uidA = '1_1';++ const pageB = await context.newPage(false, 'agent-b');+ await pageB.setContent(html`<button>Agent B Button</button>`);+ await context.createTextSnapshot(false, undefined, pageB);+ const uidB = '2_1';++ // Simulate race: agent-a selects its page, then agent-b overwrites global.+ context.selectPage(pageA);+ context.selectPage(pageB);+ // Global #selectedPage is now pageB.++ // Agent A's uid should still resolve (per-context focus for agent-a is pageA).+ const handleA = await context.getElementByUid(uidA);+ void handleA.dispose();+ // Agent B's uid should also resolve.+ const handleB = await context.getElementByUid(uidB);+ void handleB.dispose();+ });+ });++ it('aligns global selectedPage after resolution', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA = await context.newPage(false, 'agent-a');+ await pageA.setContent(html`<button>Agent A Button</button>`);+ await context.createTextSnapshot(false, undefined, pageA);+ const uidA = '1_1';++ const pageB = await context.newPage(false, 'agent-b');+ await pageB.setContent(html`<button>Agent B Button</button>`);+ await context.createTextSnapshot(false, undefined, pageB);++ // Global is on pageB after newPage.+ assert.strictEqual(context.getSelectedPage(), pageB);++ // Resolve uid from pageA; should pass and align global.+ const handle = await context.getElementByUid(uidA);+ void handle.dispose();+ assert.strictEqual(context.getSelectedPage(), pageA);+ });+ });++ it('throws for nonexistent uid', async () => {+ await withMcpContext(async (_response, context) => {+ const page = await context.newPage(false, 'agent-a');+ await page.setContent(html`<button>A Button</button>`);+ await context.createTextSnapshot(false, undefined, page);++ await assert.rejects(() => context.getElementByUid('nonexistent_99'), {+ message: 'No such element found in any snapshot.',+ });+ });+ });++ it('resolves for default context page alongside isolated contexts', async () => {+ await withMcpContext(async (_response, context) => {+ // Default context page (already exists from withMcpContext setup).+ const defaultPage = context.getSelectedPage();+ await defaultPage.setContent(html`<button>Default Button</button>`);+ await context.createTextSnapshot(false, undefined, defaultPage);+ const defaultUid = '1_1';++ // Isolated context page.+ const isoPage = await context.newPage(false, 'agent-a');+ await isoPage.setContent(html`<button>Isolated Button</button>`);+ await context.createTextSnapshot(false, undefined, isoPage);+ const isoUid = '2_1';++ // Global is now isoPage. Default context focus is still defaultPage.+ // Both should resolve via per-context lookup.+ const handleDefault = await context.getElementByUid(defaultUid);+ void handleDefault.dispose();+ const handleIso = await context.getElementByUid(isoUid);+ void handleIso.dispose();+ });+ });++ it('scopes search to target page when page is provided', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA = await context.newPage(false, 'agent-a');+ await pageA.setContent(html`<button>Agent A Button</button>`);+ await context.createTextSnapshot(false, undefined, pageA);+ const uidA = '1_1';++ const pageB = await context.newPage(false, 'agent-b');+ await pageB.setContent(html`<button>Agent B Button</button>`);+ await context.createTextSnapshot(false, undefined, pageB);++ // uidA belongs to pageA; searching with pageB should throw.+ await assert.rejects(() => context.getElementByUid(uidA, pageB), {+ message: /not found on page/,+ });++ // Searching with the correct page should resolve.+ const handle = await context.getElementByUid(uidA, pageA);+ void handle.dispose();+ });+ });+ });+it('should include network requests in structured content', async t => {await withMcpContext(async (response, context) => {const mockRequest = getMockRequest({diff --git a/tests/tools/pageFocus.test.ts b/tests/tools/pageFocus.test.tsnew file mode 100644index 00000000..d266230f--- /dev/null+++ b/tests/tools/pageFocus.test.ts@@ -0,0 +1,312 @@+/**+ * @license+ * Copyright 2026 Google LLC+ * SPDX-License-Identifier: Apache-2.0+ */++import assert from 'node:assert';+import {describe, it} from 'node:test';++import type {ParsedArguments} from '../../src/cli.js';+import {McpResponse} from '../../src/McpResponse.js';+import {clickAt, pressKey, typeText} from '../../src/tools/input.js';+import {html, withMcpContext} from '../utils.js';++const emptyArgs = {} as ParsedArguments;++describe('assertPageIsFocused', () => {+ describe('McpContext method', () => {+ it('passes for the only page in an isolated context', async () => {+ await withMcpContext(async (_response, context) => {+ const page = await context.newPage(false, 'ctx-a');+ assert.doesNotThrow(() => context.assertPageIsFocused(page));+ });+ });++ it('throws when a different page is focused in the same context', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'ctx-a');+ const pageA2 = await context.newPage(false, 'ctx-a');+ assert.doesNotThrow(() => context.assertPageIsFocused(pageA2));+ assert.throws(+ () => context.assertPageIsFocused(pageA1),+ (err: Error) => {+ assert.ok(err.message.includes('not the active page'));+ assert.ok(err.message.includes('Call select_page'));+ return true;+ },+ );+ });+ });++ it('passes after re-selecting the page', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'ctx-a');+ await context.newPage(false, 'ctx-a');+ assert.throws(() => context.assertPageIsFocused(pageA1));+ context.selectPage(pageA1);+ assert.doesNotThrow(() => context.assertPageIsFocused(pageA1));+ });+ });++ it('does not cross-context interfere', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA = await context.newPage(false, 'ctx-a');+ const pageB = await context.newPage(false, 'ctx-b');+ assert.doesNotThrow(() => context.assertPageIsFocused(pageA));+ assert.doesNotThrow(() => context.assertPageIsFocused(pageB));+ });+ });++ it('tracks focus independently per context', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'ctx-a');+ const pageA2 = await context.newPage(false, 'ctx-a');+ const pageB1 = await context.newPage(false, 'ctx-b');+ const pageB2 = await context.newPage(false, 'ctx-b');++ // Latest page in each context is focused.+ assert.doesNotThrow(() => context.assertPageIsFocused(pageA2));+ assert.doesNotThrow(() => context.assertPageIsFocused(pageB2));+ assert.throws(() => context.assertPageIsFocused(pageA1));+ assert.throws(() => context.assertPageIsFocused(pageB1));++ // Switch focus within each context independently.+ context.selectPage(pageA1);+ context.selectPage(pageB1);+ assert.doesNotThrow(() => context.assertPageIsFocused(pageA1));+ assert.doesNotThrow(() => context.assertPageIsFocused(pageB1));+ assert.throws(() => context.assertPageIsFocused(pageA2));+ assert.throws(() => context.assertPageIsFocused(pageB2));+ });+ });+ });++ describe('type_text', () => {+ it('throws when targeting a non-focused page', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'ctx-a');+ await pageA1.setContent(html`<textarea></textarea>`);+ await pageA1.click('textarea');+ await context.newPage(false, 'ctx-a');++ await assert.rejects(+ () =>+ typeText.handler(+ {params: {text: 'fail'}, page: pageA1},+ new McpResponse(emptyArgs),+ context,+ ),+ (err: Error) => {+ assert.ok(err.message.includes('not the active page'));+ return true;+ },+ );+ });+ });++ it('succeeds on the focused page', async () => {+ await withMcpContext(async (_response, context) => {+ const page = await context.newPage(false, 'ctx-a');+ await page.setContent(html`<textarea></textarea>`);+ await page.click('textarea');++ const response = new McpResponse(emptyArgs);+ await typeText.handler(+ {params: {text: 'hello'}, page},+ response,+ context,+ );+ assert.strictEqual(response.responseLines[0], 'Typed text "hello"');+ assert.strictEqual(+ await page.evaluate(() => document.querySelector('textarea')?.value),+ 'hello',+ );+ });+ });++ it('succeeds after re-selecting the correct page', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'ctx-a');+ await pageA1.setContent(html`<textarea></textarea>`);+ await context.newPage(false, 'ctx-a');++ await assert.rejects(() =>+ typeText.handler(+ {params: {text: 'fail'}, page: pageA1},+ new McpResponse(emptyArgs),+ context,+ ),+ );++ context.selectPage(pageA1);+ await pageA1.click('textarea');++ const response = new McpResponse(emptyArgs);+ await typeText.handler(+ {params: {text: 'recovered'}, page: pageA1},+ response,+ context,+ );+ assert.strictEqual(response.responseLines[0], 'Typed text "recovered"');+ });+ });+ });++ describe('press_key', () => {+ it('throws when targeting a non-focused page', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'ctx-a');+ await pageA1.setContent(html`<div>content</div>`);+ await context.newPage(false, 'ctx-a');++ await assert.rejects(+ () =>+ pressKey.handler(+ {params: {key: 'Tab'}, page: pageA1},+ new McpResponse(emptyArgs),+ context,+ ),+ (err: Error) => {+ assert.ok(err.message.includes('not the active page'));+ return true;+ },+ );+ });+ });++ it('succeeds on the focused page', async () => {+ await withMcpContext(async (_response, context) => {+ const page = await context.newPage(false, 'ctx-a');+ await page.setContent(+ html`<script>+ logs = [];+ document.addEventListener('keydown', e => logs.push(e.key));+ </script>`,+ );++ const response = new McpResponse(emptyArgs);+ await pressKey.handler(+ {params: {key: 'Enter'}, page},+ response,+ context,+ );+ assert.strictEqual(+ response.responseLines[0],+ 'Successfully pressed key: Enter',+ );+ assert.deepStrictEqual(await page.evaluate('logs'), ['Enter']);+ });+ });+ });++ describe('click_at', () => {+ it('throws when targeting a non-focused page', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA1 = await context.newPage(false, 'ctx-a');+ await pageA1.setContent(+ html`<div style="width:100px;height:100px;background:red;"></div>`,+ );+ await context.newPage(false, 'ctx-a');++ await assert.rejects(+ () =>+ clickAt.handler(+ {params: {x: 50, y: 50}, page: pageA1},+ new McpResponse(emptyArgs),+ context,+ ),+ (err: Error) => {+ assert.ok(err.message.includes('not the active page'));+ return true;+ },+ );+ });+ });++ it('succeeds on the focused page', async () => {+ await withMcpContext(async (_response, context) => {+ const page = await context.newPage(false, 'ctx-a');+ await page.setContent(+ html`<div+ style="width:100px;height:100px;background:red;"+ onclick="this.innerText='clicked'"+ ></div>`,+ );++ const response = new McpResponse(emptyArgs);+ await clickAt.handler(+ {params: {x: 50, y: 50}, page},+ response,+ context,+ );+ assert.strictEqual(+ response.responseLines[0],+ 'Successfully clicked at the coordinates',+ );+ assert.ok(await page.$('text/clicked'));+ });+ });+ });++ describe('cross-context isolation', () => {+ it('type_text in one context does not affect another', async () => {+ await withMcpContext(async (_response, context) => {+ const pageA = await context.newPage(false, 'ctx-a');+ await pageA.setContent(html`<textarea></textarea>`);++ const pageB = await context.newPage(false, 'ctx-b');+ await pageB.setContent(html`<textarea></textarea>`);++ context.selectPage(pageA);+ await pageA.click('textarea');+ await typeText.handler(+ {params: {text: 'agent-a'}, page: pageA},+ new McpResponse(emptyArgs),+ context,+ );++ context.selectPage(pageB);+ await pageB.click('textarea');+ await typeText.handler(+ {params: {text: 'agent-b'}, page: pageB},+ new McpResponse(emptyArgs),+ context,+ );++ assert.strictEqual(+ await pageA.evaluate(() => document.querySelector('textarea')?.value),+ 'agent-a',+ );+ assert.strictEqual(+ await pageB.evaluate(() => document.querySelector('textarea')?.value),+ 'agent-b',+ );+ });+ });++ it('switching focus in context A does not break context B', async () => {+ await withMcpContext(async (_response, context) => {+ await context.newPage(false, 'ctx-a');+ const pageA2 = await context.newPage(false, 'ctx-a');+ await pageA2.setContent(html`<div>A2</div>`);++ const pageB = await context.newPage(false, 'ctx-b');+ await pageB.setContent(html`<textarea></textarea>`);++ // ctx-a focus is on pageA2, ctx-b focus is on pageB.+ await pageB.click('textarea');+ const response = new McpResponse(emptyArgs);+ await typeText.handler(+ {params: {text: 'still works'}, page: pageB},+ response,+ context,+ );+ assert.strictEqual(+ await pageB.evaluate(() => document.querySelector('textarea')?.value),+ 'still works',+ );+ });+ });+ });+});diff --git a/tests/tools/pages.test.ts b/tests/tools/pages.test.tsindex 3a740e25..ecc38e82 100644--- a/tests/tools/pages.test.ts+++ b/tests/tools/pages.test.ts@@ -235,6 +235,104 @@ describe('pages', () => {});});+ describe('resolvePageById', () => {+ it('returns the correct page regardless of global selection', async () => {+ await withMcpContext(async (response, context) => {+ // Create two pages with different content.+ await newPage.handler(+ {+ params: {+ url: 'data:text/html,<h1>Page A</h1>',+ isolatedContext: 'ctx-a',+ },+ },+ response,+ context,+ );+ const pageA = context.getSelectedPage();+ const pageAId = context.getPageId(pageA)!;++ await newPage.handler(+ {+ params: {+ url: 'data:text/html,<h1>Page B</h1>',+ isolatedContext: 'ctx-b',+ },+ },+ response,+ context,+ );+ const pageB = context.getSelectedPage();+ const pageBId = context.getPageId(pageB)!;++ // Global selection is now pageB (the last created page).+ assert.strictEqual(context.getSelectedPage(), pageB);++ // resolvePageById should return the correct page for each ID,+ // regardless of which page is globally selected.+ assert.strictEqual(context.resolvePageById(pageAId), pageA);+ assert.strictEqual(context.resolvePageById(pageBId), pageB);+ });+ });++ it('falls back to getSelectedPage when no pageId is provided', async () => {+ await withMcpContext(async (_response, context) => {+ const selectedPage = context.getSelectedPage();+ assert.strictEqual(context.resolvePageById(undefined), selectedPage);+ });+ });++ it('throws for an unknown pageId', async () => {+ await withMcpContext(async (_response, context) => {+ assert.throws(() => context.resolvePageById(99999), /No page found/);+ });+ });++ it('navigate_page targets the pageId page, not the global selection', async () => {+ await withMcpContext(async (response, context) => {+ await newPage.handler(+ {+ params: {+ url: 'data:text/html,<h1>Initial</h1>',+ isolatedContext: 'nav-ctx',+ },+ },+ response,+ context,+ );+ const isolatedPage = context.getSelectedPage();++ // Switch global selection back to the default page.+ await selectPage.handler({params: {pageId: 1}}, response, context);+ assert.notStrictEqual(context.getSelectedPage(), isolatedPage);++ // Navigate using page; should target the isolated page.+ await navigatePage.handler(+ {+ params: {+ url: 'data:text/html,<h1>Navigated</h1>',+ },+ page: isolatedPage,+ },+ response,+ context,+ );++ // Verify the isolated page was navigated.+ const content = await isolatedPage.evaluate(+ () => document.querySelector('h1')?.textContent,+ );+ assert.strictEqual(content, 'Navigated');++ // Verify the default page was NOT affected.+ const defaultContent = await context+ .getSelectedPage()+ .evaluate(() => document.querySelector('h1')?.textContent);+ assert.notStrictEqual(defaultContent, 'Navigated');+ });+ });+ });+describe('close_page', () => {it('closes a page', async () => {await withMcpContext(async (response, context) => {@@ -286,6 +384,165 @@ describe('pages', () => {assert.ok(response.includePages);});});+ it('preserves focus across different browser contexts', async () => {+ await withMcpContext(async (response, context) => {+ // Create pages in separate isolated contexts.+ await newPage.handler(+ {params: {url: 'about:blank', isolatedContext: 'ctx-a'}},+ response,+ context,+ );+ const pageA = context.getSelectedPage();+ const pageAId = context.getPageId(pageA)!;++ await newPage.handler(+ {params: {url: 'about:blank', isolatedContext: 'ctx-b'}},+ response,+ context,+ );+ const pageB = context.getSelectedPage();++ // Selecting pageB (ctx-b) should not defocus pageA (ctx-a).+ assert.strictEqual(+ await pageA.evaluate(() => document.hasFocus()),+ true,+ );+ assert.strictEqual(+ await pageB.evaluate(() => document.hasFocus()),+ true,+ );++ // Switching back to pageA should preserve pageB's focus.+ await selectPage.handler(+ {params: {pageId: pageAId}},+ response,+ context,+ );+ assert.strictEqual(+ await pageA.evaluate(() => document.hasFocus()),+ true,+ );+ assert.strictEqual(+ await pageB.evaluate(() => document.hasFocus()),+ true,+ );+ });+ });+ it('focuses correct same-context page after cross-context interleaving', async () => {+ await withMcpContext(async (response, context) => {+ // Create 2 pages in ctx-a, 1 in ctx-b.+ await newPage.handler(+ {params: {url: 'about:blank', isolatedContext: 'ctx-a'}},+ response,+ context,+ );+ const pageA1 = context.getSelectedPage();+ const pageA1Id = context.getPageId(pageA1)!;++ await newPage.handler(+ {params: {url: 'about:blank', isolatedContext: 'ctx-b'}},+ response,+ context,+ );+ const pageB = context.getSelectedPage();++ // pageA1 still focused (cross-context select doesn't defocus it).+ assert.strictEqual(+ await pageA1.evaluate(() => document.hasFocus()),+ true,+ );++ // Create second page in ctx-a. This should defocus pageA1,+ // even though #selectedPage was pageB (different context).+ await newPage.handler(+ {params: {url: 'about:blank', isolatedContext: 'ctx-a'}},+ response,+ context,+ );+ const pageA2 = context.getSelectedPage();++ // pageA1 and pageA2 share the same BrowserContext.+ assert.strictEqual(pageA1.browserContext(), pageA2.browserContext());++ assert.strictEqual(+ await pageA1.evaluate(() => document.hasFocus()),+ false,+ 'pageA1 should lose focus when pageA2 is created in the same context',+ );+ assert.strictEqual(+ await pageA2.evaluate(() => document.hasFocus()),+ true,+ );+ // pageB is unaffected by ctx-a changes.+ assert.strictEqual(+ await pageB.evaluate(() => document.hasFocus()),+ true,+ );++ // Re-selecting pageA1 should grant it focus via the override.+ await selectPage.handler(+ {params: {pageId: pageA1Id}},+ response,+ context,+ );+ assert.strictEqual(+ await pageA1.evaluate(() => document.hasFocus()),+ true,+ );+ // pageB still unaffected.+ assert.strictEqual(+ await pageB.evaluate(() => document.hasFocus()),+ true,+ );+ });+ });+ it('handles focus correctly after closing the focused page in a context', async () => {+ await withMcpContext(async (response, context) => {+ await newPage.handler(+ {params: {url: 'about:blank', isolatedContext: 'ctx-a'}},+ response,+ context,+ );+ const pageA1 = context.getSelectedPage();++ await newPage.handler(+ {params: {url: 'about:blank', isolatedContext: 'ctx-a'}},+ response,+ context,+ );+ const pageA2 = context.getSelectedPage();+ const pageA2Id = context.getPageId(pageA2)!;++ // pageA2 is focused, pageA1 is not.+ assert.strictEqual(+ await pageA2.evaluate(() => document.hasFocus()),+ true,+ );+ assert.strictEqual(+ await pageA1.evaluate(() => document.hasFocus()),+ false,+ );++ // Close pageA2 (the focused page).+ await closePage.handler(+ {params: {pageId: pageA2Id}},+ response,+ context,+ );++ // Selecting pageA1 should work without errors.+ const pageA1Id = context.getPageId(pageA1)!;+ await selectPage.handler(+ {params: {pageId: pageA1Id}},+ response,+ context,+ );+ assert.strictEqual(+ await pageA1.evaluate(() => document.hasFocus()),+ true,+ );+ });+ });});describe('navigate_page', () => {it('navigates to correct page', async () => {@@ -751,6 +1008,88 @@ describe('pages', () => {);});});+ it('can handle a dialog on a non-selected page via pageId', async () => {+ await withMcpContext(async (response, context) => {+ const page1 = context.getSelectedPage();+ await context.newPage(); // page2 is now selected++ const dialogPromise = new Promise<void>(resolve => {+ page1.once('dialog', () => {+ resolve();+ });+ });+ page1.evaluate(() => {+ alert('test');+ });+ await dialogPromise;++ // page1 is not selected, but its dialog should be accessible via page.+ await handleDialog.handler(+ {+ params: {+ action: 'accept',+ },+ page: page1,+ },+ response,+ context,+ );+ assert.strictEqual(context.getDialog(page1), undefined);+ assert.strictEqual(+ response.responseLines[0],+ 'Successfully accepted the dialog',+ );+ });+ });+ it('tracks dialogs independently per page', async () => {+ await withMcpContext(async (response, context) => {+ const page1 = context.getSelectedPage();+ const page2 = await context.newPage();++ // Trigger dialog on page1.+ const dialog1Promise = new Promise<void>(resolve => {+ page1.once('dialog', () => {+ resolve();+ });+ });+ page1.evaluate(() => {+ alert('dialog1');+ });+ await dialog1Promise;++ // Trigger dialog on page2.+ const dialog2Promise = new Promise<void>(resolve => {+ page2.once('dialog', () => {+ resolve();+ });+ });+ page2.evaluate(() => {+ alert('dialog2');+ });+ await dialog2Promise;++ // Both dialogs should be tracked.+ assert.ok(context.getDialog(page1));+ assert.ok(context.getDialog(page2));++ // Handle page1's dialog; page2's should remain.+ await handleDialog.handler(+ {params: {action: 'accept'}, page: page1},+ response,+ context,+ );+ assert.strictEqual(context.getDialog(page1), undefined);+ assert.ok(context.getDialog(page2));++ // Handle page2's dialog.+ await handleDialog.handler(+ {params: {action: 'dismiss'}, page: page2},+ response,+ context,+ );+ assert.strictEqual(context.getDialog(page2), undefined);+ });+ });});describe('get_tab_id', () => {