mcp-web-inspector 0.5.0 → 0.6.0

package/README.md

@@ -595,7 +595,7 @@ COMPARE TWO ELEMENTS: Get comprehensive alignment and dimension comparison in on
   - selector2 (string, required): CSS selector, text selector, or testid shorthand for the second element (e.g., 'testid:chat-header', '#secondary-header')
 
 - Output Format:
-  - Optional warnings when a selector matched multiple elements (using first).
+  - Optional warnings when a selector matched multiple elements (uses first visible; suggests adding unique data-testid).
   - Header: Alignment: <elem1> vs <elem2>
   - Two lines with each element's position and size: @ (x,y) w×h px
   - Edges block: Top/Left/Right/Bottom with ✓/✗ and diffs
@@ -911,11 +911,11 @@ Quick check if an element exists on the page. Ultra-lightweight alternative to q
 
 ### Navigation
 
-#### `go_back`
-Navigate back in browser history
+#### `go_history`
+Navigate browser history (back/forward). Returns: 'Navigated <direction> in browser history', a quick network-idle note if available, 'URL: <current>', and 'Title: <current>' when set. If console errors occur after the navigation, returns an error like 'Console error after history navigation: <message>' including Title when available.
 
-#### `go_forward`
-Navigate forward in browser history
+- Parameters:
+  - direction (string, required): History direction to navigate
 
 #### `navigate`
 Navigate to a URL. Browser sessions (cookies, localStorage, sessionStorage) are automatically saved in ./.mcp-web-inspector/user-data directory and persist across restarts. To clear saved sessions, delete the directory.
@@ -1031,8 +1031,6 @@ Upload a file to an input[type='file'] element on the page
 
 ⚠️ Token cost: ~1,500 tokens to read. Structural tools: <100 tokens.
 
-Admin control (optional): set env MCP_SCREENSHOT_GUARD=strict to block execution (prevents misuse by default). Unset to allow visuals for human review.
-
 Screenshots saved to ./.mcp-web-inspector/screenshots. Example: { name: "login-page", fullPage: true } or { name: "submit-btn", selector: "testid:submit" }
 
 - Parameters:
@@ -1050,7 +1048,7 @@ Clears captured console logs and returns the number of entries cleared.
 Retrieve console logs with filtering and token‑efficient output. Defaults: since='last-interaction', limit=20, format='grouped'. Grouped output deduplicates identical lines and shows counts. Use format='raw' for chronological, ungrouped lines. Large outputs return a preview and a one-time token to fetch the full payload.
 
 - Parameters:
-  - type (string, optional): Type of logs to retrieve (all, error, warning, log, info, debug, exception)
+  - type (string, optional): Type filter (all, error, warning, log, info, debug, exception). Note: 'error' also includes 'exception' entries for convenience.
   - search (string, optional): Text to search for in logs (handles text with square brackets)
   - limit (number, optional): Maximum entries to return (groups when grouped, lines when raw). Default: 20
   - since (string, optional): Filter logs since a specific event: 'last-call' (since last get_console_logs call), 'last-navigation' (since last page navigation), or 'last-interaction' (since last user interaction like click, fill, etc.). Default: 'last-interaction'

package/dist/toolHandler.d.ts

@@ -79,6 +79,10 @@ export declare function getConsoleLogs(): string[];
  * Get console logs captured after the last navigation
  */
 export declare function getConsoleLogsSinceLastNavigation(): string[];
+/**
+ * Get console logs captured after the last interaction
+ */
+export declare function getConsoleLogsSinceLastInteraction(): string[];
 /**
  * Get screenshots
  */

package/dist/toolHandler.js

@@ -72,15 +72,30 @@ function getColorSchemeValue() {
     return colorSchemeOverride;
 }
 async function applyColorScheme(targetPage) {
-    if (!targetPage) {
+    if (!targetPage)
         return;
-    }
+    const scheme = getColorSchemeValue();
     try {
-        const scheme = getColorSchemeValue();
-        await targetPage.emulateMedia({ colorScheme: scheme ?? null });
+        // Some test environments or mocks may not implement emulateMedia
+        const anyPage = targetPage;
+        if (typeof anyPage.emulateMedia === 'function') {
+            await anyPage.emulateMedia({ colorScheme: scheme ?? null });
+            return;
+        }
+        // Fallback: if emulateMedia is unavailable, do a best-effort hint via CSS.
+        // This won't fully emulate prefers-color-scheme but avoids throwing in tests.
+        if (scheme) {
+            const css = scheme === 'dark' ? ':root{color-scheme: dark;}'
+                : scheme === 'light' ? ':root{color-scheme: light;}'
+                    : ':root{color-scheme: light dark;}';
+            if (typeof anyPage.addStyleTag === 'function') {
+                await anyPage.addStyleTag({ content: css });
+            }
+        }
     }
     catch (error) {
-        console.error("Failed to apply color scheme:", error);
+        // Swallow errors to keep color scheme application non-fatal
+        console.warn("Failed to apply color scheme (non-fatal):", error);
     }
 }
 export async function setColorSchemeOverride(scheme) {
@@ -258,13 +273,13 @@ async function getScreenSize() {
         await tempBrowser.close();
         // Validate the screen size values
         if (!screenSize || typeof screenSize.width !== 'number' || typeof screenSize.height !== 'number') {
-            console.error('Invalid screen size detected, using defaults');
+            console.warn('Invalid screen size detected, using defaults');
             return { width: 1280, height: 720 };
         }
         return screenSize;
     }
     catch (error) {
-        console.error('Failed to detect screen size, using defaults:', error);
+        console.warn('Failed to detect screen size, using defaults:', error);
         return { width: 1280, height: 720 };
     }
 }
@@ -279,15 +294,15 @@ export async function ensureBrowser(browserSettings) {
             const browserCheck = checkBrowsersInstalled();
             if (!browserCheck.installed) {
                 // Try to install browsers automatically
-                console.error('🎭 Playwright browsers not found. Installing automatically...');
-                console.error('⏳ This will download ~1GB of browser binaries. Please wait...');
+                console.warn('🎭 Playwright browsers not found. Installing automatically...');
+                console.warn('⏳ This will download ~1GB of browser binaries. Please wait...');
                 try {
                     const { execSync } = await import('child_process');
                     execSync('npx playwright install chromium firefox webkit', {
                         stdio: 'inherit',
                         encoding: 'utf8'
                     });
-                    console.error('✅ Browsers installed successfully! Starting browser...');
+                    console.log('✅ Browsers installed successfully! Starting browser...');
                     // Note: browser variable is still undefined here, which is correct.
                     // The code below (line 342) will launch the browser after installation.
                 }
@@ -300,7 +315,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Check if browser exists but is disconnected
         if (browser && !browser.isConnected()) {
-            console.error("Browser exists but is disconnected. Cleaning up...");
+            console.warn("Browser exists but is disconnected. Cleaning up...");
             try {
                 await browser.close().catch(err => console.error("Error closing disconnected browser:", err));
             }
@@ -312,7 +327,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Check if device preset has changed (requires browser restart)
         if (browser && browserSettings?.device && browserSettings.device !== currentDevice) {
-            console.error(`Device preset changed from ${currentDevice || 'none'} to ${browserSettings.device}. Restarting browser...`);
+            console.warn(`Device preset changed from ${currentDevice || 'none'} to ${browserSettings.device}. Restarting browser...`);
             try {
                 await browser.close().catch(err => console.error("Error closing browser on device change:", err));
             }
@@ -331,7 +346,7 @@ export async function ensureBrowser(browserSettings) {
                 const targetHeight = height ?? currentViewport?.height ?? 720;
                 // Check if viewport size actually changed
                 if (!currentViewport || currentViewport.width !== targetWidth || currentViewport.height !== targetHeight) {
-                    console.error(`Resizing viewport to ${targetWidth}x${targetHeight}`);
+                    console.log(`Resizing viewport to ${targetWidth}x${targetHeight}`);
                     await page.setViewportSize({ width: targetWidth, height: targetHeight });
                 }
             }
@@ -356,18 +371,18 @@ export async function ensureBrowser(browserSettings) {
                 // Check custom configs first, then Playwright's built-in devices
                 deviceConfig = CUSTOM_DEVICE_CONFIGS[playwrightDeviceName] || devices[playwrightDeviceName];
                 if (deviceConfig) {
-                    console.error(`Using device preset: ${device} (${playwrightDeviceName})`);
+                    console.log(`Using device preset: ${device} (${playwrightDeviceName})`);
                     currentDevice = device;
                 }
                 else {
-                    console.error(`Warning: Device preset ${playwrightDeviceName} not found`);
+                    console.warn(`Warning: Device preset ${playwrightDeviceName} not found`);
                     currentDevice = undefined;
                 }
             }
             else {
                 currentDevice = undefined;
             }
-            console.error(`Launching new ${browserType} browser instance...`);
+            console.warn(`Launching new ${browserType} browser instance...`);
             // Use the appropriate browser engine
             let browserInstance;
             switch (browserType) {
@@ -397,7 +412,7 @@ export async function ensureBrowser(browserSettings) {
                 viewportWidth = screenSize?.width ?? 1280;
                 viewportHeight = screenSize?.height ?? 720;
                 if (screenSize && screenSize.width > 0 && screenSize.height > 0) {
-                    console.error(`No viewport specified, using screen size: ${viewportWidth}x${viewportHeight}`);
+                    console.log(`No viewport specified, using screen size: ${viewportWidth}x${viewportHeight}`);
                 }
             }
             // Prepare context options
@@ -421,14 +436,14 @@ export async function ensureBrowser(browserSettings) {
             }
             // Use persistent context if session saving is enabled
             if (sessionConfig.saveSession) {
-                console.error(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir}...`);
+                console.warn(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir}...`);
                 const context = await browserInstance.launchPersistentContext(sessionConfig.userDataDir, contextOptions);
                 // Get the browser instance from the context
                 browser = context.browser();
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
                 browser.on('disconnected', () => {
-                    console.error("Browser disconnected event triggered");
+                    console.warn("Browser disconnected event triggered");
                     browser = undefined;
                     page = undefined;
                 });
@@ -444,7 +459,7 @@ export async function ensureBrowser(browserSettings) {
                 currentBrowserType = browserType;
                 // Add cleanup logic when browser is disconnected
                 browser.on('disconnected', () => {
-                    console.error("Browser disconnected event triggered");
+                    console.warn("Browser disconnected event triggered");
                     browser = undefined;
                     page = undefined;
                 });
@@ -473,7 +488,7 @@ export async function ensureBrowser(browserSettings) {
         }
         // Verify page is still valid
         if (!page || page.isClosed()) {
-            console.error("Page is closed or invalid. Creating new page...");
+            console.warn("Page is closed or invalid. Creating new page...");
             // Create a new page if the current one is invalid
             const context = browser.contexts()[0] || await browser.newContext();
             page = await context.newPage();
@@ -565,12 +580,12 @@ export async function ensureBrowser(browserSettings) {
         }
         // Use persistent context if session saving is enabled
         if (sessionConfig.saveSession) {
-            console.error(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir} (retry)...`);
+            console.warn(`Launching ${browserType} with persistent context at ${sessionConfig.userDataDir} (retry)...`);
             const context = await browserInstance.launchPersistentContext(sessionConfig.userDataDir, retryContextOptions);
             browser = context.browser();
             currentBrowserType = browserType;
             browser.on('disconnected', () => {
-                console.error("Browser disconnected event triggered (retry)");
+                console.warn("Browser disconnected event triggered (retry)");
                 browser = undefined;
                 page = undefined;
             });
@@ -584,7 +599,7 @@ export async function ensureBrowser(browserSettings) {
             });
             currentBrowserType = browserType;
             browser.on('disconnected', () => {
-                console.error("Browser disconnected event triggered (retry)");
+                console.warn("Browser disconnected event triggered (retry)");
                 browser = undefined;
                 page = undefined;
             });
@@ -650,7 +665,7 @@ export async function handleToolCall(name, args, server) {
         const requiresBrowser = isBrowserTool(name);
         // Check if we have a disconnected browser that needs cleanup
         if (browser && !browser.isConnected() && requiresBrowser) {
-            console.error("Detected disconnected browser before tool execution, cleaning up...");
+            console.warn("Detected disconnected browser before tool execution, cleaning up...");
             try {
                 await browser.close().catch(() => { }); // Ignore errors
             }
@@ -739,6 +754,16 @@ export function getConsoleLogsSinceLastNavigation() {
         return [];
     return consoleLogsTool.getLogsSinceLastNavigation();
 }
+/**
+ * Get console logs captured after the last interaction
+ */
+export function getConsoleLogsSinceLastInteraction() {
+    const consoleLogsTool = getToolInstance("get_console_logs", null);
+    if (!consoleLogsTool)
+        return [];
+    // Expose a compact accessor mirroring navigation-based retrieval
+    return consoleLogsTool.getLogsSinceLastInteraction?.() ?? [];
+}
 /**
  * Get screenshots
  */

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

@@ -12,14 +12,14 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      */
     abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
     /**
-     * Normalize selector shortcuts to full Playwright selectors and clean common escaping mistakes
-     * - "testid:foo" → "[data-testid='foo']"
-     * - "data-test:bar" → "[data-test='bar']"
-     * - "data-cy:baz" → "[data-cy='baz']"
-     * - Removes unnecessary backslash escapes from CSS selectors that LLMs often add
-     * - ".dark\\:bg-gray-700" → ".dark:bg-gray-700"
-     * - ".top-\\[36px\\]" → ".top-[36px]"
-     * - ".top-\\\\[36px\\\\]" → ".top-[36px]" (double-escaped)
+     * Normalize selector shortcuts and fix common escaping mistakes safely.
+     * - "testid:foo" → "[data-testid=\"foo\"]"
+     * - "data-test:bar" → "[data-test=\"bar\"]"
+     * - "data-cy:baz" → "[data-cy=\"baz\"]"
+     * - Convert simple ID-only selectors with special chars to Playwright's id engine:
+     *     "#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.
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -28,7 +28,7 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      * Sanitize verbose Playwright selector engine messages by removing stack traces and
      * keeping only the essential syntax error information.
      */
-    private sanitizeSelectorEngineMessage;
+    protected sanitizeSelectorEngineMessage(msg: string): string;
     /**
      * Ensures a page is available and returns it
      * @param context The tool context containing browser and page
@@ -121,4 +121,10 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      * @param totalCount Total number of matches
      */
     protected buildNthSelectorHint(selector: string, totalCount: number): string;
+    /**
+     * Describe matched elements in a compact, copyable format for disambiguation errors.
+     * Shows: index, tag, trimmed text, nearest parent marker, and a suggested selector.
+     * Suggests testid:VALUE when present; otherwise falls back to id=VALUE or original >> nth=i.
+     */
+    protected describeMatchedElements(locator: any, originalSelector: string, count: number): Promise<string>;
 }

package/dist/tools/browser/base.js

@@ -8,14 +8,14 @@ export class BrowserToolBase {
         this.server = server;
     }
     /**
-     * Normalize selector shortcuts to full Playwright selectors and clean common escaping mistakes
-     * - "testid:foo" → "[data-testid='foo']"
-     * - "data-test:bar" → "[data-test='bar']"
-     * - "data-cy:baz" → "[data-cy='baz']"
-     * - Removes unnecessary backslash escapes from CSS selectors that LLMs often add
-     * - ".dark\\:bg-gray-700" → ".dark:bg-gray-700"
-     * - ".top-\\[36px\\]" → ".top-[36px]"
-     * - ".top-\\\\[36px\\\\]" → ".top-[36px]" (double-escaped)
+     * Normalize selector shortcuts and fix common escaping mistakes safely.
+     * - "testid:foo" → "[data-testid=\"foo\"]"
+     * - "data-test:bar" → "[data-test=\"bar\"]"
+     * - "data-cy:baz" → "[data-cy=\"baz\"]"
+     * - Convert simple ID-only selectors with special chars to Playwright's id engine:
+     *     "#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.
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -32,14 +32,33 @@ export class BrowserToolBase {
                 return `[${attr}="${value}"]`;
             }
         }
-        // Clean up common escaping mistakes that LLMs make in CSS selectors
-        // These characters don't need to be escaped in many selector contexts: [ ] :
-        let cleaned = selector;
-        // Remove backslash escapes before brackets and colons
-        // Handle both single escapes (\[) and double escapes (\\[)
-        cleaned = cleaned.replace(/\\+\[/g, '[');
-        cleaned = cleaned.replace(/\\+\]/g, ']');
-        cleaned = cleaned.replace(/\\+:/g, ':');
+        const trimmed = selector.trim();
+        // Helper: unescape simple backslash-escapes used inside IDs (e.g., \:, \[, \])
+        const unescapeCssIdentifier = (s) => {
+            // Collapse multiple backslashes before a single char to the char itself
+            return s
+                .replace(/\\+:/g, ':')
+                .replace(/\\+\[/g, '[')
+                .replace(/\\+\]/g, ']');
+        };
+        // If this looks like a simple, standalone ID selector (no combinators or descendants),
+        // switch to Playwright's id engine. This avoids CSS escaping pitfalls with colons.
+        if (/^#[^\s>+~]+$/.test(trimmed)) {
+            const idToken = trimmed.slice(1);
+            // Only switch to id= engine if ID contains characters that commonly break CSS (#... with colons or escapes)
+            if (idToken.includes('\\') || idToken.includes(':') || idToken.includes('[') || idToken.includes(']')) {
+                const idValue = unescapeCssIdentifier(idToken);
+                return `id=${idValue}`;
+            }
+            // Otherwise, keep simple IDs as-is
+            return trimmed;
+        }
+        // For general CSS selectors, preserve required escapes for special chars.
+        // Collapse over-escaping (e.g., \\\\[ → \\[, but keep a single backslash before [ ] :)
+        let cleaned = trimmed;
+        cleaned = cleaned.replace(/\\{2,}(?=\[)/g, '\\');
+        cleaned = cleaned.replace(/\\{2,}(?=\])/g, '\\');
+        cleaned = cleaned.replace(/\\{2,}(?=:)/g, '\\');
         return cleaned;
     }
     /**
@@ -214,8 +233,8 @@ export class BrowserToolBase {
         // Check for multiple elements with errorOnMultiple flag
         if (options?.errorOnMultiple && count > 1) {
             const selector = options.originalSelector || 'selector';
-            const nthHint = this.buildNthSelectorHint(selector, count).trimEnd();
-            const warning = this.getDuplicateTestIdWarning(selector, count).trimEnd();
+            const nthHint = ''.trimEnd();
+            const warning = ''.trimEnd();
             let message = `Selector "${selector}" matched ${count} elements. Please use a more specific selector.`;
             if (nthHint) {
                 message += `\n${nthHint}`;
@@ -223,7 +242,15 @@ export class BrowserToolBase {
             if (warning) {
                 message += `\n${warning}`;
             }
-            throw new Error(message);
+            {
+                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);
+            }
         }
         // Handle explicit element index (1-based)
         if (options?.elementIndex !== undefined) {
@@ -274,12 +301,19 @@ export class BrowserToolBase {
      * @returns Formatted string or empty if only one element
      */
     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
+            // because it is brittle across layout/content changes.
+            if (usesNth) {
+                return "💡 Tip: Selector uses '>> nth='. Prefer adding a unique data-testid for robust selection.";
+            }
             return '';
         }
         const duplicateWarning = this.getDuplicateTestIdWarning(selector, totalCount).trimEnd();
         const nthHint = this.buildNthSelectorHint(selector, totalCount).trimEnd();
-        const extraHints = [duplicateWarning, nthHint].filter(Boolean).join('\n');
+        const avoidNth = usesNth ? "💡 Tip: Avoid relying on '>> nth='; add a unique data-testid instead." : '';
+        const extraHints = [duplicateWarning, nthHint, avoidNth].filter(Boolean).join('\n');
         const baseMessage = preferredVisible
             ? `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1} (first visible)`
             : `⚠ Found ${totalCount} elements matching "${selector}", using element ${elementIndex + 1}`;
@@ -302,10 +336,14 @@ export class BrowserToolBase {
             selector.startsWith('data-cy:') ||
             selector.match(/^\[data-(testid|test|cy)=/);
         if (isTestIdSelector) {
-            return `💡 Tip: Test IDs should be unique. Consider making this test ID unique to avoid ambiguity.\n\n`;
+            return (`💡 Tip: Test IDs should be unique. Consider making this test ID unique to avoid ambiguity.\n` +
+                `   Primary fix: assign a unique data-testid to the intended element.\n` +
+                `   Workaround: if you cannot change markup, you may use '>> nth=<index>' temporarily.\n\n`);
         }
         // Suggest testid for non-testid selectors
-        return `💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.\n\n`;
+        return (`💡 Tip: Consider adding a unique data-testid attribute for more reliable selection.\n` +
+            `   Primary fix: add data-testid and target it (e.g., testid:submit).\n` +
+            `   Workaround: use '>> nth=<index>' only when you can't add test IDs.\n\n`);
     }
     /**
      * Provide a hint for using >> nth= when multiple elements match a selector
@@ -321,6 +359,75 @@ export class BrowserToolBase {
         const firstExample = `${trimmed} >> nth=0`;
         const lastIndex = Math.max(totalCount - 1, 1);
         const lastExample = `${trimmed} >> nth=${lastIndex}`;
-        return `💡 Hint: Append ">> nth=<index>" to target a specific match.\n   Example: ${firstExample} (first match)\n   Or: ${lastExample} (last match)`;
+        return (`Primary fix: add a unique data-testid to the intended element and select it directly.\n` +
+            `Workaround: Append ">> nth=<index>" to target a specific match when you cannot change markup.\n` +
+            `   Example: ${firstExample} (first match)\n` +
+            `   Or: ${lastExample} (last match)\n` +
+            `Note: nth selectors are brittle and may break with layout/content changes.\n` +
+            `Prefer unique data-testid attributes for long-term stability.`);
+    }
+    /**
+     * Describe matched elements in a compact, copyable format for disambiguation errors.
+     * Shows: index, tag, trimmed text, nearest parent marker, and a suggested selector.
+     * Suggests testid:VALUE when present; otherwise falls back to id=VALUE or original >> nth=i.
+     */
+    async describeMatchedElements(locator, originalSelector, count) {
+        const maxItems = Math.min(count, 5);
+        const lines = [];
+        for (let i = 0; i < maxItems; i++) {
+            const nth = locator.nth(i);
+            try {
+                const info = await nth.evaluate((el) => {
+                    const tag = (el.tagName || '').toLowerCase();
+                    let text = el.innerText || el.textContent || '';
+                    text = (text || '').replace(/\s+/g, ' ').trim();
+                    const testid = el.getAttribute?.('data-testid') || el.getAttribute?.('data-test') || el.getAttribute?.('data-cy') || null;
+                    const id = el.id || null;
+                    let parentLabel = null;
+                    let p = el.parentElement;
+                    while (p && !parentLabel) {
+                        const ptid = p.getAttribute?.('data-testid');
+                        const ptest = p.getAttribute?.('data-test');
+                        const pcy = p.getAttribute?.('data-cy');
+                        const pid = p.id || null;
+                        if (ptid)
+                            parentLabel = `[data-testid="${ptid}"]`;
+                        else if (ptest)
+                            parentLabel = `[data-test="${ptest}"]`;
+                        else if (pcy)
+                            parentLabel = `[data-cy="${pcy}"]`;
+                        else if (pid)
+                            parentLabel = `#${pid}`;
+                        p = p.parentElement;
+                    }
+                    return { tag, text, testid, id, parentLabel };
+                });
+                const truncatedText = info.text && info.text.length > 80 ? `${info.text.slice(0, 77)}...` : info.text;
+                let selectorSuggestion = `${originalSelector} >> nth=${i}`;
+                let altSuggestion;
+                if (info?.testid) {
+                    selectorSuggestion = `testid:${info.testid}`;
+                    altSuggestion = `${originalSelector} >> nth=${i}`;
+                }
+                else if (info?.id) {
+                    selectorSuggestion = `id=${info.id}`;
+                    altSuggestion = `${originalSelector} >> nth=${i}`;
+                }
+                const parts = [
+                    `[${i}] <${info.tag}>${truncatedText ? ` "${truncatedText}"` : ''}`,
+                    info.parentLabel ? `    parent: ${info.parentLabel}` : undefined,
+                    `    selector: ${selectorSuggestion}`,
+                    altSuggestion ? `    alt: ${altSuggestion}` : undefined,
+                ].filter(Boolean);
+                lines.push(parts.join('\n'));
+            }
+            catch {
+                lines.push(`[${i}] (element)\n    selector: ${originalSelector} >> nth=${i}`);
+            }
+        }
+        if (count > maxItems) {
+            lines.push(`… and ${count - maxItems} more matches (use >> nth=<index> to target).`);
+        }
+        return lines.join('\n');
     }
 }

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

@@ -0,0 +1,7 @@
+import type { Page } from 'playwright';
+export declare function gatherConsoleErrorsSince(since: 'navigation' | 'interaction'): Promise<string[]>;
+export declare function quickNetworkIdleNote(page: Page): Promise<string>;
+export declare function titleUrlChangeLines(page: Page, initial?: {
+    url?: string;
+    title?: string;
+}): Promise<string[]>;

package/dist/tools/browser/common/postAction.js

@@ -0,0 +1,46 @@
+// Gather console error/exception logs since a baseline event
+export async function gatherConsoleErrorsSince(since) {
+    const { getConsoleLogsSinceLastNavigation, getConsoleLogsSinceLastInteraction } = await import('../../../toolHandler.js');
+    const logs = since === 'navigation'
+        ? getConsoleLogsSinceLastNavigation()
+        : getConsoleLogsSinceLastInteraction();
+    return logs.filter(l => l.startsWith('[error]') || l.startsWith('[exception]'));
+}
+// Provide a compact, best-effort network idle note
+export async function quickNetworkIdleNote(page) {
+    try {
+        const start = Date.now();
+        const anyPage = page;
+        const wait = anyPage?.waitForLoadState?.bind(page);
+        if (typeof wait === 'function') {
+            await wait('networkidle', { timeout: 500 });
+            const ms = Date.now() - start;
+            return `✓ Network idle after ${ms}ms, 0 pending requests`;
+        }
+    }
+    catch {
+        // fall through to no-activity note
+    }
+    return 'No new network activity detected (quick check)';
+}
+// Compute concise lines for title/URL when changed
+export async function titleUrlChangeLines(page, initial = {}) {
+    const lines = [];
+    let newUrl = '';
+    let newTitle = '';
+    try {
+        newUrl = page.url();
+    }
+    catch { }
+    try {
+        newTitle = await page.title();
+    }
+    catch { }
+    if (initial.url && newUrl && initial.url !== newUrl) {
+        lines.push(`URL changed: ${newUrl}`);
+    }
+    if (initial.title && newTitle && initial.title !== newTitle) {
+        lines.push(`Title changed: ${newTitle}`);
+    }
+    return lines;
+}

package/dist/tools/browser/console/__tests__/console.test.js

@@ -195,4 +195,55 @@ describe('GetConsoleLogsTool', () => {
         // (The truncation happens in toolHandler.ts before calling registerConsoleMessage)
         expect(logsText).toContain(longStackError);
     });
+    test('raw format preview should include confirm token and confirmation returns full payload', async () => {
+        // Generate enough long logs to exceed preview threshold
+        for (let i = 0; i < 40; i++) {
+            consoleLogsTool.registerConsoleMessage('log', `RAW-LONG-${i} ` + 'X'.repeat(160));
+        }
+        const previewResult = await consoleLogsTool.execute({ format: 'raw' }, mockContext);
+        expect(previewResult.isError).toBe(false);
+        const previewText = previewResult.content.map(c => c.text).join('\n');
+        // Should include confirm_output token reference
+        expect(previewText).toMatch(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        const token = (previewText.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        // Confirm to retrieve full payload
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const full = await confirmTool.execute({ token }, mockContext);
+        expect(full.isError).toBe(false);
+        const fullText = full.content.map(c => c.text).join('\n');
+        // By default limit=20 → header should reflect 20 lines
+        expect(fullText).toContain('Retrieved 20 console log(s):');
+        // And include one of our long messages
+        expect(fullText).toContain('RAW-LONG-39');
+    });
+    test('grouped format preview should include confirm token and confirmation returns full payload', async () => {
+        // Generate 30 unique messages to form distinct groups and exceed threshold
+        for (let i = 0; i < 30; i++) {
+            consoleLogsTool.registerConsoleMessage('log', `GROUP-LONG-${i} ` + 'G'.repeat(160));
+        }
+        const previewResult = await consoleLogsTool.execute({}, mockContext); // grouped is default
+        expect(previewResult.isError).toBe(false);
+        const previewText = previewResult.content.map(c => c.text).join('\n');
+        expect(previewText).toMatch(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/);
+        const token = (previewText.match(/confirm_output\(\{ token: \"([\w\d]+)\" \}\)/) || [])[1];
+        const { ConfirmOutputTool } = await import('../../../common/confirm_output.js');
+        const confirmTool = new ConfirmOutputTool({});
+        const full = await confirmTool.execute({ token }, mockContext);
+        expect(full.isError).toBe(false);
+        const fullText = full.content.map(c => c.text).join('\n');
+        // Header reflects number of groups shown (limit default 20)
+        expect(fullText).toContain('Retrieved 20 console log(s):');
+        // Should include one of the first 20 grouped messages
+        expect(fullText).toContain('GROUP-LONG-0');
+    });
+    test('type: error should include exception entries', async () => {
+        consoleLogsTool.registerConsoleMessage('exception', 'Hook failed');
+        consoleLogsTool.registerConsoleMessage('error', 'Console error');
+        const result = await consoleLogsTool.execute({ type: 'error' }, mockContext);
+        expect(result.isError).toBe(false);
+        const text = result.content.map(c => c.text).join('\n');
+        expect(text).toContain('[exception] Hook failed');
+        expect(text).toContain('[error] Console error');
+    });
 });

package/dist/tools/browser/console/get_console_logs.d.ts

@@ -36,6 +36,10 @@ export declare class GetConsoleLogsTool extends BrowserToolBase {
      * Return messages for logs captured after the last recorded navigation
      */
     getLogsSinceLastNavigation(): string[];
+    /**
+     * Return messages for logs captured after the last recorded interaction
+     */
+    getLogsSinceLastInteraction(): string[];
 }
 /**
  * Tool for clearing console logs (atomic operation)