mcp-web-inspector 0.11.0 → 0.13.0

package/README.md

@@ -723,7 +723,7 @@ Issues:
 Test a selector and return detailed information about all matched elements. Essential for selector debugging and finding the right element to interact with. Returns compact text format with element tag, position, text content, visibility status, and interaction capability. Shows why elements are hidden (display:none, opacity:0, zero size). Supports testid shortcuts (e.g., 'testid:submit-button'). Use limit parameter to control how many matches to show (default: 10). NEW: Use onlyVisible parameter to filter results (true=visible only, false=hidden only, undefined=all).
 
 - Parameters:
-  - selector (string, required): CSS selector, text selector, or testid shorthand to test (e.g., 'button.submit', 'testid:login-form', 'text=Sign In')
+  - selector (string, required): CSS selector, text selector, or testid shorthand to test (e.g., 'button.submit', 'testid:login-form', 'text=Sign In', 'dialog::button' to scope the lookup to the topmost open dialog/sheet)
   - limit (number, optional): Maximum number of elements to return detailed info for (default: 10, recommended max: 50)
   - onlyVisible (boolean, optional): Filter results by visibility: true = show only visible elements, false = show only hidden elements, undefined/not specified = show all elements (default: undefined)
   - showAttributes (string, optional): Comma-separated list of HTML attributes to display for each element (e.g., 'id,name,aria-label,href,type'). If not specified, attributes are not shown.
@@ -952,7 +952,7 @@ Scroll an element into view. Automatically handles scrolling within the nearest
 Click an element on the page
 
 - Parameters:
-  - selector (string, required): CSS selector for the element to click
+  - selector (string, required): CSS selector for the element to click. Supports 'testid:NAME' and 'dialog::SELECTOR' (scopes the lookup to the topmost open dialog/sheet, e.g. 'dialog::testid:confirm').
 
 #### `drag`
 Drag an element to a target location
@@ -965,7 +965,7 @@ Drag an element to a target location
 fill an input/textarea/contenteditable; if the selector matches a wrapper, descends up to 4 levels to a unique fillable descendant (errors if zero or multiple)
 
 - Parameters:
-  - selector (string, required): CSS selector for input field or its wrapper
+  - selector (string, required): CSS selector for input field or its wrapper. Supports 'testid:NAME' and 'dialog::SELECTOR' (scopes to the topmost open dialog/sheet).
   - value (string, required): Value to fill
 
 #### `hover`
@@ -1006,10 +1006,10 @@ Upload a file to an input[type='file'] element on the page
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
 
 #### `get_text`
-[may return preview+token] ⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Auto-returns text if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output via confirm_output. Supports testid shortcuts.
+[may return preview+token] ⚠️ RARELY NEEDED: Get ALL visible text content from the entire page (no structure, just raw text). Most tasks need structured inspection instead. ONLY use get_text for: (1) extracting text for content analysis (word count, language detection), (2) searching for text when location is completely unknown, (3) text-only snapshots for comparison. For structured tasks, use: inspect_dom() to understand page structure, find_by_text() to locate specific text with context, query_selector() to find elements. Auto-returns text if <2000 chars (small elements); if larger, returns a preview and a one-time token to fetch the full output via confirm_output. Supports testid shortcuts and the `dialog::SELECTOR` scope to read inside the topmost open dialog/sheet.
 
 - Parameters:
-  - selector (string, optional): CSS selector, text selector, or testid shorthand to limit text extraction to a specific container. Omit to get text from entire page. Example: 'testid:article-body' or '#main-content'
+  - selector (string, optional): CSS selector, text selector, or testid shorthand to limit text extraction to a specific container. Omit to get text from entire page. Examples: 'testid:article-body', '#main-content', 'dialog::section' (scopes lookup to the topmost open dialog/sheet — useful when a sheet covers ambiguous page chrome). Use bare 'dialog::' for the whole topmost dialog.
   - maxLength (number, optional): Maximum number of characters to return (default: 20000)
 
 #### `visual_screenshot_for_humans`

package/dist/index.js

@@ -4,10 +4,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { createToolDefinitions } from "./tools/common/registry.js";
 import { setupRequestHandlers } from "./requestHandler.js";
 import { parseArgs } from "node:util";
-import { setSessionConfig } from "./toolHandler.js";
+import { setSessionConfig, ensureBrowser } from "./toolHandler.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import { createServer } from "node:net";
 // Get package.json version
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = join(__dirname, "..");
@@ -37,6 +38,13 @@ const { values } = parseArgs({
             type: 'boolean',
             default: false,
         },
+        'cdp-port': {
+            type: 'string',
+        },
+        'warmup-browser': {
+            type: 'boolean',
+            default: false,
+        },
         'print-tools-json': {
             type: 'boolean',
             default: false,
@@ -48,17 +56,50 @@ const { values } = parseArgs({
     },
     strict: false,
 });
+// Probe localhost:port; resolve true if free, false if in use.
+function isPortFree(port) {
+    return new Promise(resolve => {
+        const srv = createServer();
+        srv.once('error', () => resolve(false));
+        srv.once('listening', () => srv.close(() => resolve(true)));
+        srv.listen(port, '127.0.0.1');
+    });
+}
+// First free port in [start, start+span). Throws if none.
+async function findFreePort(start, span) {
+    for (let p = start; p < start + span; p++) {
+        if (await isPortFree(p))
+            return p;
+    }
+    throw new Error(`No free CDP port in ${start}..${start + span - 1}`);
+}
+// Resolve --cdp-port: 0 disables; explicit value used as-is; unset auto-picks from 9222 upward.
+async function resolveCdpPort(raw) {
+    if (raw === undefined)
+        return findFreePort(9222, 100);
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        console.error(`Invalid --cdp-port value: ${raw}. Must be an integer in 0..65535 (0 disables).`);
+        process.exit(1);
+    }
+    return n;
+}
 // Configure session settings (session saving is enabled by default)
 const baseDir = String(values['user-data-dir'] || './.mcp-web-inspector');
-const sessionConfig = {
-    saveSession: !Boolean(values['no-save-session']),
-    userDataDir: `${baseDir}/user-data`,
-    screenshotsDir: `${baseDir}/screenshots`,
-    headlessDefault: Boolean(values['headless']) || (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY),
-    exposeSensitiveNetworkData: Boolean(values['expose-sensitive-network-data']),
-};
-setSessionConfig(sessionConfig);
 async function runServer() {
+    // Skip port resolution when only printing metadata — no browser will launch.
+    const printOnly = Boolean(values['print-tools-json'] || values['print-tools-md']);
+    const cdpPort = printOnly ? 0 : await resolveCdpPort(values['cdp-port']);
+    const sessionConfig = {
+        saveSession: !Boolean(values['no-save-session']),
+        userDataDir: `${baseDir}/user-data`,
+        screenshotsDir: `${baseDir}/screenshots`,
+        headlessDefault: Boolean(values['headless']) || (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY),
+        exposeSensitiveNetworkData: Boolean(values['expose-sensitive-network-data']),
+        cdpPort,
+        warmupBrowser: Boolean(values['warmup-browser']),
+    };
+    setSessionConfig(sessionConfig);
     // Create tool definitions with session config
     const TOOLS = createToolDefinitions(sessionConfig);
     // CLI utilities: print tools metadata (JSON/Markdown) and exit
@@ -72,6 +113,9 @@ async function runServer() {
         return;
     }
     console.error(`Starting mcp-web-inspector v${VERSION}`);
+    const cdpInstruction = sessionConfig.cdpPort > 0
+        ? `External Playwright clients can attach to this browser via Chrome DevTools Protocol at http://localhost:${sessionConfig.cdpPort} — pass that URL to chromium.connectOverCDP() to share cookies, localStorage, and the open page set with this server.`
+        : undefined;
     const server = new Server({
         name: "mcp-web-inspector",
         version: VERSION,
@@ -80,6 +124,7 @@ async function runServer() {
             resources: {},
             tools: {},
         },
+        ...(cdpInstruction ? { instructions: cdpInstruction } : {}),
     });
     // Setup request handlers
     setupRequestHandlers(server, TOOLS);
@@ -97,6 +142,15 @@ async function runServer() {
     // Create transport and connect
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Optional eager browser launch. Off by default — sessions that never invoke
+    // an MCP tool shouldn't pay for Chromium startup. Useful when external
+    // clients (e.g. CDP seed/login scripts) need the browser up before any tool
+    // call. Non-blocking — failures surface on the first tool call.
+    if (sessionConfig.warmupBrowser) {
+        ensureBrowser({ headless: sessionConfig.headlessDefault }).catch(err => {
+            console.error("Eager browser warmup failed (will retry on first tool call):", err);
+        });
+    }
 }
 runServer().catch((error) => {
     console.error("Fatal error in main():", error);

package/dist/toolHandler.d.ts

@@ -19,6 +19,8 @@ export interface NetworkRequest {
     };
 }
 type ColorSchemeOverride = 'light' | 'dark' | 'no-preference';
+export declare function hasShownNthHint(): boolean;
+export declare function markNthHintShown(): void;
 /**
  * Sets the session configuration
  */

package/dist/toolHandler.js

@@ -13,8 +13,20 @@ let sessionConfig = {
     screenshotsDir: './.mcp-web-inspector/screenshots',
     headlessDefault: false,
     exposeSensitiveNetworkData: false,
+    cdpPort: 0,
+    warmupBrowser: false,
 };
 let colorSchemeOverride = null;
+// Session-scoped flag: the verbose "matched multiple elements" nth-selector
+// guidance is only emitted once per browser session. After the first emit,
+// tools surface only the short ⚠ warning to keep agent context lean.
+let nthHintShown = false;
+export function hasShownNthHint() {
+    return nthHintShown;
+}
+export function markNthHintShown() {
+    nthHintShown = true;
+}
 /**
  * Sets the session configuration
  */
@@ -49,6 +61,7 @@ export function resetBrowserState() {
     currentBrowserType = 'chromium';
     currentDevice = undefined;
     networkLog = [];
+    nthHintShown = false;
     clearConsoleLogs();
 }
 /**
@@ -400,10 +413,14 @@ export async function ensureBrowser(browserSettings) {
             // IPs (e.g. Tailscale 100.64.0.0/10). This breaks environments where the API is on an
             // internal network but the app is served from a public CDN.
             // Prepare context options
+            const launchArgs = ['--disable-features=LocalNetworkAccessChecks'];
+            if (sessionConfig.cdpPort && sessionConfig.cdpPort > 0) {
+                launchArgs.push(`--remote-debugging-port=${sessionConfig.cdpPort}`);
+            }
             const contextOptions = {
                 headless,
                 executablePath: executablePath,
-                args: ['--disable-features=LocalNetworkAccessChecks'],
+                args: launchArgs,
             };
             // If device config exists, use it; otherwise use manual viewport/userAgent
             if (deviceConfig) {
@@ -439,7 +456,10 @@ export async function ensureBrowser(browserSettings) {
             else {
                 browser = await browserInstance.launch({
                     headless,
-                    executablePath: executablePath
+                    executablePath: executablePath,
+                    args: sessionConfig.cdpPort && sessionConfig.cdpPort > 0
+                        ? [`--remote-debugging-port=${sessionConfig.cdpPort}`]
+                        : [],
                 });
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
@@ -608,10 +628,14 @@ export async function ensureBrowser(browserSettings) {
             retryViewportHeight = screenSize?.height ?? 720;
         }
         // Prepare context options
+        const retryLaunchArgs = ['--disable-features=LocalNetworkAccessChecks'];
+        if (sessionConfig.cdpPort && sessionConfig.cdpPort > 0) {
+            retryLaunchArgs.push(`--remote-debugging-port=${sessionConfig.cdpPort}`);
+        }
         const retryContextOptions = {
             headless,
             executablePath: executablePath,
-            args: ['--disable-features=LocalNetworkAccessChecks'],
+            args: retryLaunchArgs,
         };
         // If device config exists, use it; otherwise use manual viewport/userAgent
         if (deviceConfig) {
@@ -644,7 +668,10 @@ export async function ensureBrowser(browserSettings) {
         else {
             browser = await browserInstance.launch({
                 headless,
-                executablePath: executablePath
+                executablePath: executablePath,
+                args: sessionConfig.cdpPort && sessionConfig.cdpPort > 0
+                    ? [`--remote-debugging-port=${sessionConfig.cdpPort}`]
+                    : [],
             });
             currentBrowserType = browserType;
             browser.on('disconnected', () => {

package/dist/tools/browser/base.d.ts

@@ -1,4 +1,4 @@
-import type { Page } from 'playwright';
+import type { Locator, Page } from 'playwright';
 import { ToolHandler, ToolContext, ToolResponse } from '../common/types.js';
 /**
  * Base class for all browser-based tools
@@ -20,10 +20,49 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      *     "#radix-\:rc\:-content-123" → "id=radix-:rc:-content-123"
      * - Remove unnecessary escapes for bracket characters only (\\[ and \\])
      *   DO NOT unescape colons globally — colons in class/ID names must stay escaped in CSS.
+     *
+     * Note: the `dialog::SELECTOR` scope shortcut (e.g., `dialog::section`,
+     * `dialog::testid:close`) is NOT handled here — it is a runtime scope
+     * resolved by `createScopedLocator()`, not a syntactic rewrite.
+     *
      * @param selector The selector string
      * @returns Normalized selector
      */
     protected normalizeSelector(selector: string): string;
+    /**
+     * Build a Playwright `Locator` honoring the `dialog::SELECTOR` scope shortcut.
+     *
+     * - `dialog::section`           → topmost open dialog/sheet, then `section` inside it
+     * - `dialog::testid:close`      → topmost open dialog, then `[data-testid="close"]` inside it
+     * - `dialog::`                  → the topmost open dialog itself
+     * - anything else               → `page.locator(normalizeSelector(rawSelector))`
+     *
+     * "Topmost" is determined by the highest effective z-index — for each
+     * candidate dialog, we walk up to the nearest positioned ancestor (almost
+     * always the backdrop/glass-screen wrapper, which is what stacking actually
+     * follows) and read its z-index. DOM order is the tiebreaker. This is more
+     * robust than picking `.last()` because portal frameworks don't always
+     * append in z-order, and modal stacking is driven by the backdrop's
+     * z-index, not the dialog content's.
+     */
+    protected createScopedLocator(page: Page, rawSelector: string): Promise<Locator>;
+    /**
+     * Detect a "user-dominating" open modal — i.e. one that a human would
+     * visually focus on and interact with to the exclusion of the rest of the
+     * page. Used by inspect_dom / get_text / get_html to auto-scope when no
+     * selector is provided, so the LLM's view matches the human's view.
+     *
+     * Strict criterion: requires `aria-modal="true"` (or native `dialog[open]`)
+     * because non-modal `[role="dialog"]` includes things like side panels and
+     * tooltips that don't dominate the page.
+     *
+     * Returns null if no active modal is open. Otherwise returns the topmost
+     * one, ranked by the same z-index walk used by `createScopedLocator()`.
+     */
+    protected detectActiveModal(page: Page): Promise<{
+        descriptor: string;
+        suggestion: string;
+    } | null>;
     /**
      * Sanitize verbose Playwright selector engine messages by removing stack traces and
      * keeping only the essential syntax error information.
@@ -105,7 +144,7 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      * @param preferredVisible Whether visibility preference was used
      * @returns Formatted string or empty if only one element
      */
-    protected formatElementSelectionInfo(selector: string, elementIndex: number, totalCount: number, preferredVisible?: boolean): string;
+    protected formatElementSelectionInfo(selector: string, elementIndex: number, totalCount: number, preferredVisible?: boolean): Promise<string>;
     /**
      * Generate a warning message if the selector is a testid and there are duplicates
      *

package/dist/tools/browser/base.js

@@ -16,6 +16,11 @@ export class BrowserToolBase {
      *     "#radix-\:rc\:-content-123" → "id=radix-:rc:-content-123"
      * - Remove unnecessary escapes for bracket characters only (\\[ and \\])
      *   DO NOT unescape colons globally — colons in class/ID names must stay escaped in CSS.
+     *
+     * Note: the `dialog::SELECTOR` scope shortcut (e.g., `dialog::section`,
+     * `dialog::testid:close`) is NOT handled here — it is a runtime scope
+     * resolved by `createScopedLocator()`, not a syntactic rewrite.
+     *
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -76,6 +81,188 @@ export class BrowserToolBase {
         cleaned = cleaned.replace(/\\{2,}(?=:)/g, '\\');
         return cleaned;
     }
+    /**
+     * Build a Playwright `Locator` honoring the `dialog::SELECTOR` scope shortcut.
+     *
+     * - `dialog::section`           → topmost open dialog/sheet, then `section` inside it
+     * - `dialog::testid:close`      → topmost open dialog, then `[data-testid="close"]` inside it
+     * - `dialog::`                  → the topmost open dialog itself
+     * - anything else               → `page.locator(normalizeSelector(rawSelector))`
+     *
+     * "Topmost" is determined by the highest effective z-index — for each
+     * candidate dialog, we walk up to the nearest positioned ancestor (almost
+     * always the backdrop/glass-screen wrapper, which is what stacking actually
+     * follows) and read its z-index. DOM order is the tiebreaker. This is more
+     * robust than picking `.last()` because portal frameworks don't always
+     * append in z-order, and modal stacking is driven by the backdrop's
+     * z-index, not the dialog content's.
+     */
+    async createScopedLocator(page, rawSelector) {
+        const trimmed = (rawSelector ?? '').trim();
+        const DIALOG_PREFIX = 'dialog::';
+        if (!trimmed.startsWith(DIALOG_PREFIX)) {
+            return page.locator(this.normalizeSelector(trimmed));
+        }
+        const dialogRoots = '[role="dialog"]:not([aria-hidden="true"]),' +
+            '[role="alertdialog"]:not([aria-hidden="true"]),' +
+            'dialog[open]';
+        // Match detectActiveModal: include only user-visible candidates and
+        // rank by effective z-index. Without the visibility filter, a hidden
+        // dialog left in the DOM (display:none) could be picked over an
+        // actually-open one.
+        const result = await page.evaluate((rootsSelector) => {
+            const isUserVisible = (el) => {
+                const cs = getComputedStyle(el);
+                if (cs.display === 'none' || cs.visibility === 'hidden' || parseFloat(cs.opacity) === 0) {
+                    return false;
+                }
+                const rect = el.getBoundingClientRect();
+                return rect.width > 0 && rect.height > 0;
+            };
+            const allCandidates = Array.from(document.querySelectorAll(rootsSelector));
+            const visibleIndices = [];
+            allCandidates.forEach((el, i) => {
+                if (isUserVisible(el))
+                    visibleIndices.push(i);
+            });
+            if (visibleIndices.length === 0)
+                return { topIndex: -1, hasVisible: false };
+            if (visibleIndices.length === 1)
+                return { topIndex: visibleIndices[0], hasVisible: true };
+            const effectiveZ = (start) => {
+                let z = 0;
+                let node = start;
+                while (node && node !== document.body) {
+                    const cs = getComputedStyle(node);
+                    if (cs.position !== 'static') {
+                        const parsed = parseInt(cs.zIndex, 10);
+                        if (!isNaN(parsed)) {
+                            z = Math.max(z, parsed);
+                        }
+                    }
+                    node = node.parentElement;
+                }
+                return z;
+            };
+            let bestIdx = visibleIndices[0];
+            let bestScore = -Infinity;
+            visibleIndices.forEach((i) => {
+                // Tiebreaker: DOM order — later element is on top.
+                const score = effectiveZ(allCandidates[i]) * 1000000 + i;
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestIdx = i;
+                }
+            });
+            return { topIndex: bestIdx, hasVisible: true };
+        }, dialogRoots).catch(() => ({ topIndex: -1, hasVisible: false }));
+        // No visible dialog → return a never-matching locator so downstream
+        // callers see a clean "No elements found" instead of silently scoping
+        // to a hidden dialog left in the DOM.
+        if (!result.hasVisible) {
+            return page.locator('dialog-no-such-element-sentinel');
+        }
+        const topmostDialog = page.locator(dialogRoots).nth(result.topIndex);
+        const inner = trimmed.slice(DIALOG_PREFIX.length).trim();
+        if (!inner) {
+            return topmostDialog;
+        }
+        return topmostDialog.locator(this.normalizeSelector(inner));
+    }
+    /**
+     * Detect a "user-dominating" open modal — i.e. one that a human would
+     * visually focus on and interact with to the exclusion of the rest of the
+     * page. Used by inspect_dom / get_text / get_html to auto-scope when no
+     * selector is provided, so the LLM's view matches the human's view.
+     *
+     * Strict criterion: requires `aria-modal="true"` (or native `dialog[open]`)
+     * because non-modal `[role="dialog"]` includes things like side panels and
+     * tooltips that don't dominate the page.
+     *
+     * Returns null if no active modal is open. Otherwise returns the topmost
+     * one, ranked by the same z-index walk used by `createScopedLocator()`.
+     */
+    async detectActiveModal(page) {
+        const ACTIVE_MODAL_SELECTOR = '[role="dialog"][aria-modal="true"]:not([aria-hidden="true"]),' +
+            '[role="alertdialog"][aria-modal="true"]:not([aria-hidden="true"]),' +
+            'dialog[open]';
+        return await page.evaluate((rootsSelector) => {
+            const isUserVisible = (el) => {
+                const cs = getComputedStyle(el);
+                if (cs.display === 'none' || cs.visibility === 'hidden' || parseFloat(cs.opacity) === 0) {
+                    return false;
+                }
+                const rect = el.getBoundingClientRect();
+                return rect.width > 0 && rect.height > 0;
+            };
+            const candidates = Array.from(document.querySelectorAll(rootsSelector)).filter(isUserVisible);
+            if (candidates.length === 0)
+                return null;
+            const effectiveZ = (start) => {
+                let z = 0;
+                let node = start;
+                while (node && node !== document.body) {
+                    const cs = getComputedStyle(node);
+                    if (cs.position !== 'static') {
+                        const parsed = parseInt(cs.zIndex, 10);
+                        if (!isNaN(parsed)) {
+                            z = Math.max(z, parsed);
+                        }
+                    }
+                    node = node.parentElement;
+                }
+                return z;
+            };
+            let bestIdx = 0;
+            let bestScore = -Infinity;
+            candidates.forEach((el, i) => {
+                const score = effectiveZ(el) * 1000000 + i;
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestIdx = i;
+                }
+            });
+            const top = candidates[bestIdx];
+            const tag = top.tagName.toLowerCase();
+            const role = top.getAttribute('role') || (tag === 'dialog' ? 'dialog' : '');
+            const testid = top.getAttribute('data-testid') ||
+                top.getAttribute('data-test') ||
+                top.getAttribute('data-cy');
+            const id = top.id || null;
+            const ariaLabel = top.getAttribute('aria-label');
+            const ariaLabelledBy = top.getAttribute('aria-labelledby');
+            let labelText = null;
+            if (ariaLabelledBy) {
+                const labelEl = document.getElementById(ariaLabelledBy);
+                labelText = labelEl?.textContent?.trim() || null;
+            }
+            const parts = [`<${tag}`];
+            if (role)
+                parts.push(`role="${role}"`);
+            if (testid)
+                parts.push(`data-testid="${testid}"`);
+            else if (id)
+                parts.push(`id="${id}"`);
+            if (ariaLabel)
+                parts.push(`aria-label="${ariaLabel}"`);
+            else if (labelText)
+                parts.push(`labelled="${labelText.slice(0, 60)}"`);
+            parts[parts.length - 1] += '>';
+            return {
+                descriptor: parts.join(' '),
+                suggestion: testid ? `dialog::testid:${testid}` : 'dialog::',
+            };
+        }, ACTIVE_MODAL_SELECTOR).then((result) => {
+            // Defensive: only treat as a real modal if the result is a
+            // properly-shaped object. Mocked test environments may return
+            // arbitrary values from page.evaluate() that should not trigger
+            // auto-scope.
+            if (result && typeof result === 'object' && typeof result.descriptor === 'string') {
+                return result;
+            }
+            return null;
+        }, () => null);
+    }
     /**
      * Sanitize verbose Playwright selector engine messages by removing stack traces and
      * keeping only the essential syntax error information.
@@ -249,24 +436,27 @@ export class BrowserToolBase {
         // Check for multiple elements with errorOnMultiple flag
         if (options?.errorOnMultiple && count > 1) {
             const selector = options.originalSelector || 'selector';
-            const nthHint = ''.trimEnd();
-            const warning = ''.trimEnd();
             let message = `Selector "${selector}" matched ${count} elements. Please use a more specific selector.`;
-            if (nthHint) {
-                message += `\n${nthHint}`;
-            }
-            if (warning) {
-                message += `\n${warning}`;
-            }
-            {
+            // Verbose disambiguation guidance is rate-limited per session — useful
+            // once for the agent to learn the pattern, noise on every subsequent call.
+            // After the first emit, fall back to a one-line pointer.
+            const { hasShownNthHint, markNthHintShown } = await import('../../toolHandler.js');
+            if (!hasShownNthHint()) {
                 const guidance = [
                     `1) Preferred: add a unique data-testid and select it directly (e.g., testid:submit).`,
                     `2) If you cannot change markup: append \`>> nth=<index>\` to target a specific match.`,
                 ];
-                const matchesDetails = await this.describeMatchedElements(locator, selector, count);
-                message += `\n${guidance.join('\n')}\n\nMatches:\n${matchesDetails}`;
-                throw new Error(message);
+                message += `\n${guidance.join('\n')}`;
+                markNthHintShown();
             }
+            else {
+                message += `\nUse a more specific selector (e.g. testid:..., or '>> nth=<index>').`;
+            }
+            // Per-call match details remain — they describe what's actually on the
+            // page, not generic advice.
+            const matchesDetails = await this.describeMatchedElements(locator, selector, count);
+            message += `\n\nMatches:\n${matchesDetails}`;
+            throw new Error(message);
         }
         // Handle explicit element index (1-based)
         if (options?.elementIndex !== undefined) {
@@ -316,7 +506,7 @@ export class BrowserToolBase {
      * @param preferredVisible Whether visibility preference was used
      * @returns Formatted string or empty if only one element
      */
-    formatElementSelectionInfo(selector, elementIndex, totalCount, preferredVisible = true) {
+    async formatElementSelectionInfo(selector, elementIndex, totalCount, preferredVisible = true) {
         const usesNth = selector.includes('>> nth=');
         if (totalCount <= 1) {
             // Even when a single element is ultimately targeted, discourage nth usage
@@ -326,10 +516,25 @@ export class BrowserToolBase {
             }
             return '';
         }
-        const duplicateWarning = this.getDuplicateTestIdWarning(selector, totalCount).trimEnd();
-        const nthHint = this.buildNthSelectorHint(selector, totalCount).trimEnd();
         const avoidNth = usesNth ? "💡 Tip: Avoid relying on '>> nth='; add a unique data-testid instead." : '';
-        const extraHints = [duplicateWarning, nthHint, avoidNth].filter(Boolean).join('\n');
+        // Verbose nth-selector guidance is rate-limited to one emit per session.
+        // The short ⚠ warning still surfaces every call; the multi-line hint block
+        // (duplicate-testid tip + nth-selector workaround) appears only on the
+        // first multi-match of the session — it's reference material the agent
+        // only needs once.
+        let extraHints = '';
+        const { hasShownNthHint, markNthHintShown } = await import('../../toolHandler.js');
+        if (!hasShownNthHint()) {
+            const duplicateWarning = this.getDuplicateTestIdWarning(selector, totalCount).trimEnd();
+            const nthHint = this.buildNthSelectorHint(selector, totalCount).trimEnd();
+            extraHints = [duplicateWarning, nthHint, avoidNth].filter(Boolean).join('\n');
+            if (duplicateWarning || nthHint) {
+                markNthHintShown();
+            }
+        }
+        else if (avoidNth) {
+            extraHints = avoidNth;
+        }
         const baseMessage = preferredVisible
             ? `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1} (first visible)`
             : `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1}`;

package/dist/tools/browser/common/postAction.d.ts

@@ -5,3 +5,15 @@ export declare function titleUrlChangeLines(page: Page, initial?: {
     url?: string;
     title?: string;
 }): Promise<string[]>;
+export type OverlayKind = 'dialog' | 'menu' | 'listbox' | 'tooltip' | 'popup';
+export interface OverlayEntry {
+    descriptor: string;
+    kind: OverlayKind;
+    suggestion?: string;
+}
+export interface OverlaySnapshot {
+    keys: string[];
+    entries: Record<string, OverlayEntry>;
+}
+export declare function snapshotOpenOverlays(page: Page): Promise<OverlaySnapshot>;
+export declare function overlayChangeLines(before: OverlaySnapshot, after: OverlaySnapshot): string[];