mcp-web-inspector 0.2.1 → 0.4.0

package/dist/toolHandler.d.ts

@@ -19,6 +19,7 @@ export interface NetworkRequest {
         body: string | null;
     };
 }
+type ColorSchemeOverride = 'light' | 'dark' | 'no-preference';
 /**
  * Sets the session configuration
  */
@@ -49,6 +50,8 @@ export declare function clearNetworkLog(): void;
  * @param newPage The Page object to set as the global page
  */
 export declare function setGlobalPage(newPage: Page): Promise<void>;
+export declare function setColorSchemeOverride(scheme: ColorSchemeOverride | null): Promise<void>;
+export declare function getColorSchemeOverride(): ColorSchemeOverride | null;
 interface BrowserSettings {
     viewport?: {
         width?: number;

package/dist/toolHandler.js

@@ -12,6 +12,7 @@ let sessionConfig = {
     screenshotsDir: './.mcp-web-inspector/screenshots',
     headlessDefault: false,
 };
+let colorSchemeOverride = null;
 /**
  * Sets the session configuration
  */
@@ -61,9 +62,34 @@ export async function setGlobalPage(newPage) {
     // Register console message handlers and network listeners for the new page
     await registerConsoleMessage(page);
     await registerNetworkListeners(page);
+    await applyColorScheme(page);
     page.bringToFront(); // Bring the new tab to the front
     console.log("Global page has been updated with listeners registered.");
 }
+function getColorSchemeValue() {
+    return colorSchemeOverride;
+}
+async function applyColorScheme(targetPage) {
+    if (!targetPage) {
+        return;
+    }
+    try {
+        const scheme = getColorSchemeValue();
+        await targetPage.emulateMedia({ colorScheme: scheme ?? null });
+    }
+    catch (error) {
+        console.error("Failed to apply color scheme:", error);
+    }
+}
+export async function setColorSchemeOverride(scheme) {
+    colorSchemeOverride = scheme;
+    if (page && !page.isClosed()) {
+        await applyColorScheme(page);
+    }
+}
+export function getColorSchemeOverride() {
+    return colorSchemeOverride;
+}
 /**
  * Device preset mapping to Playwright device descriptors
  */
@@ -425,6 +451,7 @@ export async function ensureBrowser(browserSettings) {
             // Register console message handler and network listeners
             await registerConsoleMessage(page);
             await registerNetworkListeners(page);
+            await applyColorScheme(page);
         }
         // Verify page is still valid
         if (!page || page.isClosed()) {
@@ -435,7 +462,9 @@ export async function ensureBrowser(browserSettings) {
             // Re-register console message handler and network listeners
             await registerConsoleMessage(page);
             await registerNetworkListeners(page);
+            await applyColorScheme(page);
         }
+        await applyColorScheme(page);
         return page;
     }
     catch (error) {
@@ -552,6 +581,7 @@ export async function ensureBrowser(browserSettings) {
         }
         await registerConsoleMessage(page);
         await registerNetworkListeners(page);
+        await applyColorScheme(page);
         return page;
     }
 }

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

@@ -12,11 +12,14 @@ export declare abstract class BrowserToolBase implements ToolHandler {
      */
     abstract execute(args: any, context: ToolContext): Promise<ToolResponse>;
     /**
-     * Normalize selector shortcuts to full Playwright selectors
+     * 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']"
-     * - Everything else → pass through
+     * - 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)
      * @param selector The selector string
      * @returns Normalized selector
      */

package/dist/tools/browser/base.js

@@ -8,11 +8,14 @@ export class BrowserToolBase {
         this.server = server;
     }
     /**
-     * Normalize selector shortcuts to full Playwright selectors
+     * 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']"
-     * - Everything else → pass through
+     * - 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)
      * @param selector The selector string
      * @returns Normalized selector
      */
@@ -22,13 +25,22 @@ export class BrowserToolBase {
             'data-test:': 'data-test',
             'data-cy:': 'data-cy',
         };
+        // Handle testid shortcuts first
         for (const [prefix, attr] of Object.entries(prefixMap)) {
             if (selector.startsWith(prefix)) {
                 const value = selector.slice(prefix.length);
                 return `[${attr}="${value}"]`;
             }
         }
-        return selector; // CSS, text=, etc. pass through
+        // Clean up common escaping mistakes that LLMs make in CSS selectors
+        // These characters don't need to be escaped in CSS selectors: [ ] :
+        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, ':');
+        return cleaned;
     }
     /**
      * Ensures a page is available and returns it
@@ -140,7 +152,36 @@ export class BrowserToolBase {
      * @returns Object with { element: Locator, elementIndex: number, totalCount: number }
      */
     async selectPreferredLocator(locator, options) {
-        const count = await locator.count();
+        let count;
+        try {
+            count = await locator.count();
+        }
+        catch (error) {
+            // Catch selector syntax errors and provide helpful guidance
+            const errorMsg = error.message;
+            const selector = options?.originalSelector || 'selector';
+            if (errorMsg.includes('Unexpected token') ||
+                errorMsg.includes('Invalid selector') ||
+                errorMsg.includes('SyntaxError') ||
+                errorMsg.includes('selector')) {
+                throw new Error(`Invalid CSS selector: "${selector}"\n\n` +
+                    `Selector syntax error: ${errorMsg}\n\n` +
+                    `💡 Tips:\n` +
+                    `  • CSS selectors don't need backslash escapes for [ ] or :\n` +
+                    `  • Use .class-name or #id without escaping\n` +
+                    `  • For data attributes, use [data-attr="value"]\n` +
+                    `  • For testid shortcuts, use testid:name\n\n` +
+                    `Examples:\n` +
+                    `  ✓ .dark:bg-gray-700\n` +
+                    `  ✓ .top-[36px]\n` +
+                    `  ✓ testid:submit-button\n` +
+                    `  ✓ #login-form\n` +
+                    `  ✗ .dark\\:bg-gray-700 (unnecessary escape)\n` +
+                    `  ✗ .top-\\[36px\\] (unnecessary escape)`);
+            }
+            // Re-throw other errors as-is
+            throw error;
+        }
         if (count === 0) {
             throw new Error('No elements found');
         }

package/dist/tools/browser/content/__tests__/visiblePage.test.js

@@ -300,10 +300,11 @@ describe('GetHtmlTool', () => {
         expect(result.isError).toBe(false);
         expect(result.content[0].text).toContain('HTML content');
     });
-    test('should respect maxLength parameter', async () => {
+    test('should respect maxLength parameter for small HTML', async () => {
         const args = { maxLength: 50 };
-        const longHtml = '<div>' + 'A'.repeat(100) + '</div>';
-        mockEvaluate.mockImplementationOnce(() => Promise.resolve(longHtml));
+        // Small HTML that won't trigger preview threshold
+        const smallHtml = '<div>' + 'A'.repeat(100) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(smallHtml));
         const result = await visibleHtmlTool.execute(args, mockContext);
         expect(result.isError).toBe(false);
         expect(result.content[0].text).toContain('Output truncated due to size limits');
@@ -378,4 +379,107 @@ describe('GetHtmlTool', () => {
         expect(result.content[0].text).toContain('Failed to get visible HTML content');
         expect(result.content[0].text).toContain('Content retrieval failed');
     });
+    test('should return preview with token for large HTML (≥2000 chars)', async () => {
+        const args = {};
+        // Large HTML that exceeds preview threshold
+        const largeHtml = '<div>' + 'X'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(largeHtml));
+        const result = await visibleHtmlTool.execute(args, mockContext);
+        expect(result.isError).toBe(false);
+        expect(result.content[0].text).toContain('HTML size:');
+        expect(result.content[0].text).toContain('exceeds 2000 char threshold');
+        expect(result.content[0].text).toContain('Preview (first 500 chars)');
+        expect(result.content[0].text).toContain('⚠️ Full HTML not returned to save tokens');
+        expect(result.content[0].text).toContain('💡 RECOMMENDED: Use token-efficient alternatives');
+        expect(result.content[0].text).toContain('inspect_dom()');
+        expect(result.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
+    });
+    test('should return full HTML with valid confirmToken', async () => {
+        const args = {};
+        // Large HTML
+        const largeHtml = '<div>' + 'Y'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementation(() => Promise.resolve(largeHtml));
+        // First call - get preview and token
+        const previewResult = await visibleHtmlTool.execute(args, mockContext);
+        expect(previewResult.isError).toBe(false);
+        // Extract token from preview
+        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        expect(tokenMatch).toBeTruthy();
+        const token = tokenMatch[1];
+        // Second call - with token
+        const fullResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        expect(fullResult.isError).toBe(false);
+        expect(fullResult.content[0].text).toContain(largeHtml);
+        expect(fullResult.content[0].text).not.toContain('Preview (first 500 chars)');
+        expect(fullResult.content[0].text).toContain('💡 TIP: If you need structured inspection');
+    });
+    test('should generate new token for invalid confirmToken', async () => {
+        const args = { confirmToken: 'invalid123' };
+        // Large HTML
+        const largeHtml = '<div>' + 'Z'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(largeHtml));
+        const result = await visibleHtmlTool.execute(args, mockContext);
+        expect(result.isError).toBe(false);
+        expect(result.content[0].text).toContain('HTML size:');
+        expect(result.content[0].text).toContain('Preview (first 500 chars)');
+        expect(result.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
+        // Should not return full HTML
+        expect(result.content[0].text).not.toContain('Z'.repeat(3000));
+    });
+    test('should return small HTML directly without token requirement', async () => {
+        const args = {};
+        // Small HTML below threshold
+        const smallHtml = '<div>Small content with 1500 chars: ' + 'A'.repeat(1400) + '</div>';
+        mockEvaluate.mockImplementationOnce(() => Promise.resolve(smallHtml));
+        const result = await visibleHtmlTool.execute(args, mockContext);
+        expect(result.isError).toBe(false);
+        expect(result.content[0].text).toContain(smallHtml);
+        expect(result.content[0].text).not.toContain('confirmToken:');
+        expect(result.content[0].text).not.toContain('Preview (first 500 chars)');
+        expect(result.content[0].text).toContain('💡 TIP: If you need structured inspection');
+    });
+    test('should consume token only once (one-time use)', async () => {
+        const args = {};
+        // Large HTML
+        const largeHtml = '<div>' + 'M'.repeat(3000) + '</div>';
+        mockEvaluate.mockImplementation(() => Promise.resolve(largeHtml));
+        // First call - get token
+        const previewResult = await visibleHtmlTool.execute(args, mockContext);
+        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        const token = tokenMatch[1];
+        // Second call - use token (should work)
+        const fullResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        expect(fullResult.isError).toBe(false);
+        expect(fullResult.content[0].text).toContain(largeHtml);
+        // Third call - try to reuse same token (should fail, get new preview)
+        const retryResult = await visibleHtmlTool.execute({ confirmToken: token }, mockContext);
+        expect(retryResult.isError).toBe(false);
+        expect(retryResult.content[0].text).toContain('Preview (first 500 chars)');
+        expect(retryResult.content[0].text).toMatch(/confirmToken: "[\w\d]{8}"/);
+        // Should have different token
+        const newTokenMatch = retryResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        expect(newTokenMatch[1]).not.toBe(token);
+    });
+    test('should handle large HTML with selector and confirmToken', async () => {
+        const largeHtml = '<section>' + 'S'.repeat(3000) + '</section>';
+        const args = { selector: 'testid:large-section' };
+        mockLocator.mockImplementation(() => ({}));
+        const mockElement = {
+            evaluate: jest.fn(async () => largeHtml),
+        };
+        const selectSpy = jest
+            .spyOn(visibleHtmlTool, 'selectPreferredLocator')
+            .mockResolvedValue({ element: mockElement, elementIndex: 0, totalCount: 1 });
+        mockEvaluate.mockImplementation(() => Promise.resolve(largeHtml));
+        // First call - get preview
+        const previewResult = await visibleHtmlTool.execute(args, mockContext);
+        expect(previewResult.content[0].text).toContain('(from "testid:large-section")');
+        const tokenMatch = previewResult.content[0].text.match(/confirmToken: "([\w\d]{8})"/);
+        const token = tokenMatch[1];
+        // Second call - with token
+        const fullResult = await visibleHtmlTool.execute({ selector: 'testid:large-section', confirmToken: token }, mockContext);
+        expect(fullResult.isError).toBe(false);
+        expect(fullResult.content[0].text).toContain(largeHtml);
+        selectSpy.mockRestore();
+    });
 });

package/dist/tools/browser/content/get_html.d.ts

@@ -4,6 +4,7 @@ import { ToolContext, ToolResponse, ToolMetadata, SessionConfig } from '../../co
  * Tool for getting HTML from the page
  */
 export declare class GetHtmlTool extends BrowserToolBase {
+    private confirmTokens;
     static getMetadata(sessionConfig?: SessionConfig): ToolMetadata;
     execute(args: any, context: ToolContext): Promise<ToolResponse>;
 }

package/dist/tools/browser/content/get_html.js

@@ -4,10 +4,14 @@ import { createSuccessResponse, createErrorResponse, } from '../../common/types.
  * Tool for getting HTML from the page
  */
 export class GetHtmlTool extends BrowserToolBase {
+    constructor() {
+        super(...arguments);
+        this.confirmTokens = new Map(); // Stores tokens for two-step confirmation
+    }
     static getMetadata(sessionConfig) {
         return {
             name: "get_html",
-            description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Returns HTML up to 20000 chars (truncated if longer), scripts removed by default for security/size. Supports testid shortcuts.",
+            description: "⚠️ RARELY NEEDED: Get raw HTML markup from the page (no rendering, just source code). Most tasks need structured inspection instead. ONLY use get_html for: (1) checking specific HTML attributes or element nesting, (2) analyzing markup structure, (3) debugging SSR/HTML issues. For structured tasks, use: inspect_dom() to understand page structure with positions, query_selector() to find and inspect elements, get_computed_styles() for CSS values. Auto-returns HTML if <2000 chars (small elements), shows preview with token-based confirmation if larger. Scripts removed by default for security/size. Supports testid shortcuts.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -26,6 +30,10 @@ export class GetHtmlTool extends BrowserToolBase {
                     maxLength: {
                         type: "number",
                         description: "Maximum number of characters to return (default: 20000)"
+                    },
+                    confirmToken: {
+                        type: "string",
+                        description: "Confirmation token from preview response (required to retrieve large HTML). Get this token by calling without confirmToken first - the preview will include the token to use."
                     }
                 },
                 required: [],
@@ -37,6 +45,8 @@ export class GetHtmlTool extends BrowserToolBase {
             ? Math.floor(args.maxLength)
             : 20000;
         const clean = args.clean ?? false;
+        const confirmToken = args.confirmToken;
+        const PREVIEW_THRESHOLD = 2000;
         if (!context.page) {
             return createErrorResponse('Page is not available');
         }
@@ -58,6 +68,7 @@ export class GetHtmlTool extends BrowserToolBase {
                     const locator = page.locator(normalizedSelector);
                     const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
                         elementIndex: args.elementIndex,
+                        originalSelector: args.selector,
                     });
                     selectionWarning = this.formatElementSelectionInfo(args.selector, elementIndex, totalCount, true);
                     rawHtml = await element.evaluate((target) => {
@@ -99,6 +110,40 @@ export class GetHtmlTool extends BrowserToolBase {
                 const safeMaxLength = requestedMaxLength > 0 ? requestedMaxLength : 20000;
                 const processedHtml = sanitizedHtml ?? '';
                 const originalLength = processedHtml.length;
+                // Generate key for this HTML request
+                const tokenKey = `${args.selector || 'page'}:${originalLength}`;
+                // Check if HTML is too large
+                if (originalLength >= PREVIEW_THRESHOLD) {
+                    // Verify if confirmToken matches
+                    const expectedToken = this.confirmTokens.get(tokenKey);
+                    if (confirmToken && expectedToken && confirmToken === expectedToken) {
+                        // Valid token - delete it (one-time use) and proceed to return HTML
+                        this.confirmTokens.delete(tokenKey);
+                    }
+                    else {
+                        // No token or invalid token - show preview and generate new token
+                        const newToken = Math.random().toString(36).substring(2, 10);
+                        this.confirmTokens.set(tokenKey, newToken);
+                        lines.push(`HTML size: ${originalLength.toLocaleString()} characters (exceeds ${PREVIEW_THRESHOLD} char threshold)`);
+                        lines.push('');
+                        lines.push('Preview (first 500 chars):');
+                        lines.push(processedHtml.slice(0, 500));
+                        if (originalLength > 500) {
+                            lines.push('...');
+                        }
+                        lines.push('');
+                        lines.push('⚠️ Full HTML not returned to save tokens (~' + Math.round(originalLength / 3) + ' tokens)');
+                        lines.push('');
+                        lines.push('💡 RECOMMENDED: Use token-efficient alternatives:');
+                        lines.push('   • inspect_dom() - structured view with positions and layout');
+                        lines.push('   • query_selector_all() - find specific elements');
+                        lines.push('   • get_computed_styles() - CSS values for debugging');
+                        lines.push('');
+                        lines.push(`To get full HTML anyway, call again with: confirmToken: "${newToken}"`);
+                        return createSuccessResponse(lines.join('\n'));
+                    }
+                }
+                // Return full HTML (either small or explicitly requested)
                 let displayHtml = processedHtml;
                 const truncated = displayHtml.length > safeMaxLength;
                 if (truncated) {

package/dist/tools/browser/content/get_text.js

@@ -53,6 +53,7 @@ export class GetTextTool extends BrowserToolBase {
                     const locator = page.locator(normalizedSelector);
                     const { element, elementIndex, totalCount } = await this.selectPreferredLocator(locator, {
                         elementIndex: args.elementIndex,
+                        originalSelector: args.selector,
                     });
                     selectionWarning = this.formatElementSelectionInfo(args.selector, elementIndex, totalCount, true);
                     textContent = await element.evaluate((target) => {

package/dist/tools/browser/content/screenshot.js

@@ -82,9 +82,13 @@ export class ScreenshotTool extends BrowserToolBase {
                 });
                 messages.push(`Screenshot also stored in memory with name: '${args.name || 'screenshot'}'`);
             }
+            // Add token cost warning
+            messages.push('');
+            messages.push('📸 Open the file in your IDE to view the screenshot');
+            messages.push('⚠️  Reading the image file consumes ~1,500 tokens - only use Read tool if visual analysis is essential');
             // Add actionable guidance based on screenshot context
             messages.push('');
-            messages.push('💡 To debug layout issues in this screenshot:');
+            messages.push('💡 To debug layout issues without reading the screenshot:');
             if (args.selector) {
                 messages.push(`   inspect_ancestors({ selector: "${args.selector}" })`);
                 messages.push('   → See parent constraints (width, margins, overflow, borders)');

package/dist/tools/browser/evaluation/evaluate.js

@@ -79,6 +79,16 @@ export class EvaluateTool extends BrowserToolBase {
                 '   Returns: Alignment status (left/right/top/bottom/center), pixel gaps\n' +
                 '   Perfect for: Checking if elements are aligned or overlapping');
         }
+        // Pattern: Scrolling operations
+        if (scriptLower.match(/scrollto|scrollby|scrollintoview|scrolltop|scrollleft|window\.scroll|pageyoffset|scrolly/)) {
+            suggestions.push('📜 Scrolling - Use specialized scroll tools\n' +
+                '   • scroll_to_element({ selector: "...", position: "start|center|end" })\n' +
+                '     → Scrolls element into view (handles containers automatically)\n' +
+                '   • scroll_by({ selector: "html", pixels: 500 })\n' +
+                '     → Precise pixel scrolling for testing sticky headers, infinite scroll\n' +
+                '   Why: Playwright auto-scrolls before interactions, but these tools help with\n' +
+                '        testing scroll behavior, lazy-loading, and scroll-triggered content');
+        }
         return suggestions;
     }
     async execute(args, context) {

package/dist/tools/browser/inspection/__tests__/inspectAncestors.test.js

@@ -208,7 +208,7 @@ describe('InspectAncestorsTool', () => {
         expect(result.isError).toBeFalsy();
         const text = result.content[0].text;
         // Should show both overflow-x and overflow-y when different
-        expect(text).toMatch(/overflow-x.*overflow-y|overflow.*hidden.*auto/);
+        expect(text).toMatch(/overflow-[xy].*overflow-[xy]/);
     });
     it('should show flexbox layout context', async () => {
         await page.setContent(`
@@ -351,4 +351,115 @@ describe('InspectAncestorsTool', () => {
         expect(text).not.toContain('Test IDs should be unique');
         expect(text).toContain('Found 2 elements');
     });
+    it('should detect vertically scrollable containers with overflow amount', async () => {
+        await page.setContent(`
+      <html>
+        <body style="margin: 0; padding: 0;">
+          <div style="overflow-y: auto; height: 200px; width: 400px;">
+            <div style="height: 500px;">
+              <p data-testid="scrollable-content">Content that extends beyond container</p>
+            </div>
+          </div>
+        </body>
+      </html>
+    `);
+        const result = await tool.execute({ selector: 'testid:scrollable-content' }, { page, browser });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        // Should show overflow with scrollable indicator (uniform overflow shows as "overflow:")
+        expect(text).toMatch(/overflow(-y)?:/);
+        expect(text).toContain('↕️');
+        expect(text).toContain('scrollable');
+        // Should show scrollable container diagnostic
+        expect(text).toContain('SCROLLABLE CONTAINER');
+        expect(text).toContain('vertically');
+    });
+    it('should detect horizontally scrollable containers with overflow amount', async () => {
+        await page.setContent(`
+      <html>
+        <body style="margin: 0; padding: 0;">
+          <div style="overflow-x: scroll; width: 300px;">
+            <div style="width: 800px;">
+              <span data-testid="wide-content">Wide content</span>
+            </div>
+          </div>
+        </body>
+      </html>
+    `);
+        const result = await tool.execute({ selector: 'testid:wide-content' }, { page, browser });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        // Should show overflow-x with scrollable indicator
+        expect(text).toContain('overflow-x:');
+        expect(text).toContain('↔️');
+        expect(text).toContain('scrollable');
+        // Should show scrollable container diagnostic
+        expect(text).toContain('SCROLLABLE CONTAINER');
+        expect(text).toContain('horizontally');
+    });
+    it('should detect both vertically and horizontally scrollable containers', async () => {
+        await page.setContent(`
+      <html>
+        <body style="margin: 0; padding: 0;">
+          <div style="overflow: auto; height: 200px; width: 300px;">
+            <div style="height: 500px; width: 800px;">
+              <div data-testid="scroll-both">Content scrolls both ways</div>
+            </div>
+          </div>
+        </body>
+      </html>
+    `);
+        const result = await tool.execute({ selector: 'testid:scroll-both' }, { page, browser });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        // Should show overflow with both indicators
+        expect(text).toContain('overflow:');
+        expect(text).toContain('scrollable');
+        // Should show scrollable container diagnostic
+        expect(text).toContain('SCROLLABLE CONTAINER');
+        expect(text).toContain('vertically & horizontally');
+    });
+    it('should show clipped content when overflow:hidden with actual overflow', async () => {
+        await page.setContent(`
+      <html>
+        <body style="margin: 0; padding: 0;">
+          <div style="overflow: hidden; height: 150px;">
+            <div style="height: 400px;">
+              <p data-testid="clipped">This content is clipped</p>
+            </div>
+          </div>
+        </body>
+      </html>
+    `);
+        const result = await tool.execute({ selector: 'testid:clipped' }, { page, browser });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        // Should show overflow:hidden with clipped amount
+        expect(text).toContain('overflow:');
+        expect(text).toContain('🔒');
+        expect(text).toContain('hidden');
+        expect(text).toContain('clipped');
+        // Should show both clipping point and (still show it even though content is scrollable)
+        expect(text).toContain('CLIPPING POINT');
+    });
+    it('should not show overflow info when no CSS overflow is set and no actual overflow exists', async () => {
+        await page.setContent(`
+      <html>
+        <body style="margin: 0; padding: 0;">
+          <div style="height: 300px; width: 400px;">
+            <div style="height: 100px; width: 200px;">
+              <p data-testid="no-overflow">Normal content</p>
+            </div>
+          </div>
+        </body>
+      </html>
+    `);
+        const result = await tool.execute({ selector: 'testid:no-overflow' }, { page, browser });
+        expect(result.isError).toBeFalsy();
+        const text = result.content[0].text;
+        // Should NOT show overflow info when there's no overflow
+        // (overflow: visible is the default and is not shown)
+        const hasOverflowInfo = text.includes('overflow:') || text.includes('overflow-x:') || text.includes('overflow-y:');
+        expect(hasOverflowInfo).toBeFalsy();
+    });
 });