cbrowser 18.55.1 → 18.57.0

package/dist/mcp-tools/base/advanced-interaction-tools.js

@@ -0,0 +1,174 @@
+/**
+ * CBrowser MCP Tools - Advanced Interaction Tools
+ *
+ * hover, type_text, press_key, handle_dialog, upload_file, drag
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import { z } from "zod";
+/**
+ * Register advanced interaction tools (6 tools)
+ */
+export function registerAdvancedInteractionTools(server, { getBrowser, getBrowserByToken }) {
+    // ── hover ──
+    server.registerTool("hover", {
+        title: "Hover Over Element",
+        description: "Hover over an element to trigger tooltips, dropdowns, or hover states. Uses CSS selector or smart selector.",
+        inputSchema: {
+            selector: z.string().describe("CSS selector or text description of the element to hover"),
+            _browserToken: z.string().optional().describe("Browser session token"),
+        },
+        annotations: { title: "Hover", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ selector, _browserToken }) => {
+        let b, token;
+        if (getBrowserByToken) {
+            const r = await getBrowserByToken(_browserToken);
+            b = r.browser;
+            token = r.token;
+        }
+        else {
+            b = await getBrowser();
+        }
+        const result = await b.hover(selector);
+        return { content: [{ type: "text", text: JSON.stringify({ ...result, _browserToken: token }, null, 2) }] };
+    });
+    // ── type_text ──
+    server.registerTool("type_text", {
+        title: "Type Text (Keyboard)",
+        description: "Type text character by character using keyboard events. Unlike 'fill', this triggers keydown/keypress/keyup events for each character. Use for inputs that need real keyboard events (autocomplete, search-as-you-type, game inputs).",
+        inputSchema: {
+            text: z.string().describe("Text to type"),
+            delay: z.number().optional().default(50).describe("Delay between keystrokes in ms (default 50)"),
+            _browserToken: z.string().optional().describe("Browser session token"),
+        },
+        annotations: { title: "Type Text", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ text, delay, _browserToken }) => {
+        let b, token;
+        if (getBrowserByToken) {
+            const r = await getBrowserByToken(_browserToken);
+            b = r.browser;
+            token = r.token;
+        }
+        else {
+            b = await getBrowser();
+        }
+        const page = await b.getPage();
+        await page.keyboard.type(text, { delay: delay || 50 });
+        return { content: [{ type: "text", text: JSON.stringify({ typed: text, characters: text.length, _browserToken: token }, null, 2) }] };
+    });
+    // ── press_key ──
+    server.registerTool("press_key", {
+        title: "Press Key",
+        description: "Press a keyboard key (Enter, Tab, Escape, ArrowDown, Backspace, etc). Supports modifier combos: 'Control+a', 'Shift+Enter', 'Meta+c'. Full list: https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values",
+        inputSchema: {
+            key: z.string().describe("Key to press (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown', 'Control+a', 'Meta+c')"),
+            _browserToken: z.string().optional().describe("Browser session token"),
+        },
+        annotations: { title: "Press Key", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ key, _browserToken }) => {
+        let b, token;
+        if (getBrowserByToken) {
+            const r = await getBrowserByToken(_browserToken);
+            b = r.browser;
+            token = r.token;
+        }
+        else {
+            b = await getBrowser();
+        }
+        const page = await b.getPage();
+        await page.keyboard.press(key);
+        return { content: [{ type: "text", text: JSON.stringify({ pressed: key, _browserToken: token }, null, 2) }] };
+    });
+    // ── handle_dialog ──
+    server.registerTool("handle_dialog", {
+        title: "Handle JavaScript Dialog",
+        description: "Set how to handle the next JavaScript dialog (alert, confirm, prompt). Call BEFORE the action that triggers the dialog. For prompts, provide the text to enter.",
+        inputSchema: {
+            action: z.enum(["accept", "dismiss"]).describe("Accept or dismiss the dialog"),
+            promptText: z.string().optional().describe("Text to enter for prompt() dialogs"),
+            _browserToken: z.string().optional().describe("Browser session token"),
+        },
+        annotations: { title: "Handle Dialog", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ action, promptText, _browserToken }) => {
+        let b, token;
+        if (getBrowserByToken) {
+            const r = await getBrowserByToken(_browserToken);
+            b = r.browser;
+            token = r.token;
+        }
+        else {
+            b = await getBrowser();
+        }
+        const page = await b.getPage();
+        // Set up a one-time dialog handler
+        const dialogPromise = new Promise((resolve) => {
+            page.once("dialog", async (dialog) => {
+                const info = { type: dialog.type(), message: dialog.message() };
+                if (action === "accept") {
+                    await dialog.accept(promptText);
+                }
+                else {
+                    await dialog.dismiss();
+                }
+                resolve(info);
+            });
+        });
+        // Wait briefly for the dialog (it may already be pending)
+        const timeout = new Promise((resolve) => setTimeout(() => resolve(null), 5000));
+        const result = await Promise.race([dialogPromise, timeout]);
+        if (result) {
+            return { content: [{ type: "text", text: JSON.stringify({ handled: true, dialogType: result.type, message: result.message, action, _browserToken: token }, null, 2) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ handled: false, message: "No dialog appeared within 5 seconds. Call this BEFORE the action that triggers the dialog.", _browserToken: token }, null, 2) }] };
+    });
+    // ── upload_file ──
+    server.registerTool("upload_file", {
+        title: "Upload File",
+        description: "Upload file(s) to a file input element. Works with <input type='file'> elements.",
+        inputSchema: {
+            selector: z.string().describe("CSS selector for the file input element"),
+            filePaths: z.array(z.string()).describe("Array of absolute file paths to upload"),
+            _browserToken: z.string().optional().describe("Browser session token"),
+        },
+        annotations: { title: "Upload File", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ selector, filePaths, _browserToken }) => {
+        let b, token;
+        if (getBrowserByToken) {
+            const r = await getBrowserByToken(_browserToken);
+            b = r.browser;
+            token = r.token;
+        }
+        else {
+            b = await getBrowser();
+        }
+        const page = await b.getPage();
+        await page.locator(selector).setInputFiles(filePaths);
+        return { content: [{ type: "text", text: JSON.stringify({ uploaded: filePaths, selector, _browserToken: token }, null, 2) }] };
+    });
+    // ── drag ──
+    server.registerTool("drag", {
+        title: "Drag and Drop",
+        description: "Drag an element to a target location. Simulates mouse press, move, and release.",
+        inputSchema: {
+            source: z.string().describe("CSS selector for the element to drag"),
+            target: z.string().describe("CSS selector for the drop target"),
+            _browserToken: z.string().optional().describe("Browser session token"),
+        },
+        annotations: { title: "Drag and Drop", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ source, target, _browserToken }) => {
+        let b, token;
+        if (getBrowserByToken) {
+            const r = await getBrowserByToken(_browserToken);
+            b = r.browser;
+            token = r.token;
+        }
+        else {
+            b = await getBrowser();
+        }
+        const page = await b.getPage();
+        await page.dragAndDrop(source, target);
+        return { content: [{ type: "text", text: JSON.stringify({ dragged: source, droppedOn: target, _browserToken: token }, null, 2) }] };
+    });
+}
+//# sourceMappingURL=advanced-interaction-tools.js.map

package/dist/mcp-tools/base/advanced-interaction-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-interaction-tools.js","sourceRoot":"","sources":["../../../src/mcp-tools/base/advanced-interaction-tools.ts"],"names":[],"mappings":"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"}

package/dist/mcp-tools/base/audit-tools.d.ts

@@ -4,9 +4,9 @@
  * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
  * @license MIT
  */
-import type { McpServer } from "../types.js";
+import type { McpServer, ToolRegistrationContext } from "../types.js";
 /**
- * Register audit tools (4 tools: agent_ready_audit, competitive_benchmark, empathy_audit, webmcp_ready_audit)
+ * Register audit tools (4 tools + site_cognitive_assessment + visual_cognitive_story)
  */
-export declare function registerAuditTools(server: McpServer): void;
+export declare function registerAuditTools(server: McpServer, context?: ToolRegistrationContext): void;
 //# sourceMappingURL=audit-tools.d.ts.map

package/dist/mcp-tools/base/audit-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/base/audit-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAS7C;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAo2B1D"}
+{"version":3,"file":"audit-tools.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/base/audit-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAStE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAo+B7F"}

package/dist/mcp-tools/base/audit-tools.js

@@ -8,9 +8,10 @@ import { z } from "zod";
 import { runAgentReadyAudit, runCompetitiveBenchmark, runEmpathyAudit, runWebMCPReadyAudit, } from "../../analysis/index.js";
 import { listAccessibilityPersonas } from "../../personas.js";
 /**
- * Register audit tools (4 tools: agent_ready_audit, competitive_benchmark, empathy_audit, webmcp_ready_audit)
+ * Register audit tools (4 tools + site_cognitive_assessment + visual_cognitive_story)
  */
-export function registerAuditTools(server) {
+export function registerAuditTools(server, context) {
+    const getBrowserByToken = context?.getBrowserByToken;
     server.registerTool("agent_ready_audit", {
         title: "Agent-Ready Audit",
         description: "Audit a website for AI-agent friendliness. Analyzes findability, stability, accessibility, and semantics. Returns score (0-100), grade (A-F), issues, and remediation recommendations.",
@@ -287,6 +288,9 @@ export function registerAuditTools(server) {
             proxy: z.string().optional().describe("Proxy server URL for geo-accurate testing (e.g., 'http://user:pass@proxy.example.com:12321'). Routes browser through the proxy so sites see the proxy's IP/location instead of the server's."),
             geoRegion: z.string().optional().describe("Route through a residential proxy in this region. Available: us-west, us-east, us-central, uk, germany, japan. Overrides proxy parameter."),
             device: z.string().optional().describe("Device emulation: 'mobile', 'tablet', 'desktop', or specific device like 'iPhone 15'. Default: desktop."),
+            waitAfterLoad: z.number().optional().describe("Extra milliseconds to wait after page loads. Use for sites with client-side translation or deferred rendering (e.g., 3000-5000 for i18n sites)."),
+            waitForSelector: z.string().optional().describe("CSS selector to wait for after load. Example: '[data-translated]', '.content-loaded'. Times out gracefully."),
+            _browserToken: z.string().optional().describe("Reuse an existing browser session. Essential for testing translated pages: first navigate + click the language selector, then pass the token here to assess the already-translated page. Without this, the tool creates a fresh browser that defaults to English."),
         },
         annotations: {
             title: "Site Cognitive Assessment",
@@ -295,7 +299,7 @@ export function registerAuditTools(server) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ url, personas, threshold, userLocation, userTimezone, userLanguage, proxy, geoRegion }) => {
+    }, async ({ url, personas, threshold, userLocation, userTimezone, userLanguage, proxy, geoRegion, waitAfterLoad, waitForSelector, _browserToken }) => {
         const startTime = Date.now();
         const personaList = (personas || "first-timer,cognitive-adhd").split(",").map(s => s.trim()).filter(Boolean);
         // Derive locale from userLanguage (e.g., "en-US" → locale "en-US", language "en")
@@ -312,42 +316,131 @@ export function registerAuditTools(server) {
             },
         };
         // ── Gate 1: Bot Detection Probe ──
+        let ownsBrowser = true;
+        let proxyConfig;
         try {
             const { CBrowser: BrowserClass } = await import("../../browser.js");
-            // Set browser locale to match user's expected language
-            // Resolve geoRegion to proxy config (overrides raw proxy)
-            if (geoRegion && !proxy) {
-                const { getGeoProxy } = await import("../../geo-proxy.js");
-                const geoProxy = getGeoProxy(geoRegion);
-                if (geoProxy) {
-                    proxy = `http://${encodeURIComponent(geoProxy.username)}:${encodeURIComponent(geoProxy.password)}@${geoProxy.server.replace('http://', '')}`;
-                    response.geoRegion = geoRegion;
-                }
+            let browser;
+            let token;
+            // If _browserToken is provided, reuse existing session (preserves language selection, cookies, etc.)
+            if (_browserToken && getBrowserByToken) {
+                const session = await getBrowserByToken(_browserToken);
+                browser = session.browser;
+                token = session.token;
+                ownsBrowser = false; // Don't close — it belongs to the session pool
+                response._browserToken = token;
+                response.sessionReused = true;
             }
-            // Parse proxy URL if provided (format: socks5://user:pass@host:port or http://host:port)
-            const proxyConfig = proxy ? (() => {
-                try {
-                    const u = new URL(proxy);
-                    return {
-                        server: `${u.protocol}//${u.hostname}:${u.port}`,
-                        ...(u.username ? { username: decodeURIComponent(u.username) } : {}),
-                        ...(u.password ? { password: decodeURIComponent(u.password) } : {}),
-                    };
+            else {
+                // Create fresh browser with locale and proxy settings
+                // Resolve geoRegion to proxy config (overrides raw proxy)
+                if (geoRegion && !proxy) {
+                    const { getGeoProxy } = await import("../../geo-proxy.js");
+                    const geoProxy = getGeoProxy(geoRegion);
+                    if (geoProxy) {
+                        proxy = `http://${encodeURIComponent(geoProxy.username)}:${encodeURIComponent(geoProxy.password)}@${geoProxy.server.replace('http://', '')}`;
+                        response.geoRegion = geoRegion;
+                    }
                 }
-                catch {
-                    return { server: proxy };
+                proxyConfig = proxy ? (() => {
+                    try {
+                        const u = new URL(proxy);
+                        return {
+                            server: `${u.protocol}//${u.hostname}:${u.port}`,
+                            ...(u.username ? { username: decodeURIComponent(u.username) } : {}),
+                            ...(u.password ? { password: decodeURIComponent(u.password) } : {}),
+                        };
+                    }
+                    catch {
+                        return { server: proxy };
+                    }
+                })() : undefined;
+                browser = new BrowserClass({
+                    headless: true,
+                    locale: expectedLocale,
+                    ...(userTimezone ? { timezone: userTimezone } : {}),
+                    ...(proxyConfig ? { proxy: proxyConfig, timeout: 60000 } : {}),
+                });
+                await browser.launch();
+                // Pre-seed localStorage for client-side i18n frameworks
+                if (expectedLang !== "en") {
+                    try {
+                        const page = await browser.getPage();
+                        await page.context().addInitScript((lang) => {
+                            try {
+                                localStorage.setItem("cbrowser-lang", lang);
+                                localStorage.setItem("lang", lang);
+                                localStorage.setItem("locale", lang);
+                            }
+                            catch { }
+                        }, expectedLang);
+                    }
+                    catch { }
                 }
-            })() : undefined;
-            const browser = new BrowserClass({
-                headless: true,
-                locale: expectedLocale,
-                ...(userTimezone ? { timezone: userTimezone } : {}),
-                ...(proxyConfig ? { proxy: proxyConfig, timeout: 60000 } : {}),
-            });
-            await browser.launch();
+            }
             try {
-                const navResult = await browser.navigate(url);
+                // For non-English, ensure enough total wait time for client-side translation:
+                // waitForSelector catches the marker, then waitAfterLoad gives GT time to finish text swaps
+                const effectiveWaitAfterLoad = waitAfterLoad || (expectedLang !== "en" ? 3000 : 0);
+                const navResult = await browser.navigate(url, {
+                    ...(effectiveWaitAfterLoad ? { waitAfterLoad: effectiveWaitAfterLoad } : {}),
+                    ...(waitForSelector ? { waitForSelector } : {}),
+                });
                 const page = await browser.getPage();
+                // Verify translation actually happened by checking page content, not just a DOM attribute.
+                // The selector may exist (set by our own addInitScript) even when GT failed silently.
+                if (expectedLang !== "en") {
+                    const contentCheck = await page.evaluate(() => {
+                        // Check VISIBLE body content only (not <title> which can't be client-side translated)
+                        const h1 = document.querySelector("h1")?.textContent || "";
+                        const nav = document.querySelector("nav")?.textContent || "";
+                        const body = document.body?.innerText?.substring(0, 500) || "";
+                        const visibleText = h1 + " " + nav + " " + body;
+                        // Check primary nav items that are always above-fold and always visible.
+                        // Translation is viewport-progressive, so only check items guaranteed
+                        // to be in the first viewport at 1920x1080.
+                        const englishIndicators = ["Docs", "Pricing", "Log in", "Sign up"];
+                        const stillEnglish = englishIndicators.filter(en => visibleText.includes(en)).length;
+                        // Also check page lang attribute
+                        const pageLang = document.documentElement.lang || "en";
+                        return { stillEnglish, totalChecked: englishIndicators.length, pageLang, visibleSample: visibleText.substring(0, 100) };
+                    }).catch(() => ({ stillEnglish: 0, totalChecked: 0, pageLang: "en", visibleSample: "" }));
+                    if (contentCheck.stillEnglish >= 2) {
+                        // Multiple English indicators still present — translation didn't work
+                        response.translationWarning = {
+                            expected: expectedLocale,
+                            actual: "en",
+                            englishIndicatorsFound: contentCheck.stillEnglish,
+                            pageLang: contentCheck.pageLang,
+                            message: `Page content appears to still be in English despite userLanguage="${expectedLocale}". ${contentCheck.stillEnglish}/${contentCheck.totalChecked} English UI strings found in visible content. The site may require a language selector click, not just Accept-Language. Scores reflect English content, not ${expectedLocale}.`,
+                        };
+                    }
+                    else if (contentCheck.stillEnglish === 0) {
+                        response.translationNote = {
+                            language: expectedLocale,
+                            verified: true,
+                            pageLang: contentCheck.pageLang,
+                            message: `Page content verified as translated — no English UI indicators found in visible text. Scores reflect ${expectedLocale} content.`,
+                        };
+                    }
+                    else {
+                        response.translationNote = {
+                            language: expectedLocale,
+                            verified: "partial",
+                            pageLang: contentCheck.pageLang,
+                            englishIndicatorsRemaining: contentCheck.stillEnglish,
+                            message: `Page mostly translated — ${contentCheck.stillEnglish}/${contentCheck.totalChecked} English UI strings still present in visible content. Scores mostly reflect ${expectedLocale} content.`,
+                        };
+                    }
+                }
+                // Also surface waitForSelector timeout if relevant
+                if (waitForSelector && navResult.waitSelectorTimedOut) {
+                    response.waitWarning = {
+                        selector: waitForSelector,
+                        timedOut: true,
+                        message: `waitForSelector "${waitForSelector}" timed out — element not found after page load.`,
+                    };
+                }
                 const pageTitle = await page.title().catch(() => "");
                 const bodyText = await page.evaluate(() => document.body?.innerText?.slice(0, 500) || "").catch(() => "");
                 const elementCount = await page.evaluate(() => document.querySelectorAll("a, button, input, select, textarea").length).catch(() => 0);
@@ -360,7 +453,7 @@ export function registerAuditTools(server) {
                 const lowerBody = bodyText.toLowerCase();
                 const blockSignature = BLOCK_SIGNATURES.find(sig => lowerTitle.includes(sig) || lowerBody.includes(sig));
                 const isEmpty = elementCount < 5 && bodyText.length < 100;
-                // Language mismatch detection
+                // Language mismatch detection — runs regardless of waitForSelector
                 const pageLang = await page.evaluate(() => document.documentElement.lang || "").catch(() => "");
                 const pageLangShort = pageLang.split("-")[0].toLowerCase();
                 const languageMismatch = pageLangShort && pageLangShort !== expectedLang && pageLangShort !== "";
@@ -382,7 +475,8 @@ export function registerAuditTools(server) {
                     response.result = "BLOCKED";
                     response.message = `Site is bot-blocked (${blockSignature || "empty DOM"}). Cannot assess cognitive experience. Try with stealth mode enabled or use a staging URL.`;
                     response.duration = `${Date.now() - startTime}ms`;
-                    await browser.close();
+                    if (ownsBrowser)
+                        await browser.close();
                     return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
                 }
                 response.gate1 = { status: "accessible", pageTitle, elementCount };
@@ -412,7 +506,8 @@ export function registerAuditTools(server) {
                         response.result = "UNQUALIFIED";
                         response.message = `Site scored ${score}/100 (grade ${grade}), below the ${threshold} threshold. Fix structural issues before persona testing adds value.`;
                         response.duration = `${Date.now() - startTime}ms`;
-                        await browser.close();
+                        if (ownsBrowser)
+                            await browser.close();
                         return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
                     }
                 }
@@ -474,6 +569,13 @@ export function registerAuditTools(server) {
                     visualComplexity: Math.round(pageMetrics.visualComplexity * 1000) / 1000,
                     interactiveElements: pageMetrics.interactiveElementCount,
                     choiceCount: pageMetrics.choiceCount,
+                    // Text readability metrics (v18.56)
+                    avgWordLength: Math.round(pageMetrics.avgWordLength * 1000) / 1000,
+                    avgSentenceLength: Math.round(pageMetrics.avgSentenceLength * 1000) / 1000,
+                    lexicalDiversity: Math.round(pageMetrics.lexicalDiversity * 1000) / 1000,
+                    longWordRatio: Math.round(pageMetrics.longWordRatio * 1000) / 1000,
+                    technicalDensity: Math.round(pageMetrics.technicalDensity * 1000) / 1000,
+                    scriptFamily: pageMetrics.scriptFamily || "alphabetic",
                 };
                 if (pageUnderstanding)
                     response.pageUnderstanding = pageUnderstanding;
@@ -488,17 +590,34 @@ export function registerAuditTools(server) {
                 response.recommendations = recommendations.slice(0, 5);
                 response.result = "COMPLETE";
                 response.duration = `${Date.now() - startTime}ms`;
-                await browser.close();
+                if (ownsBrowser)
+                    await browser.close();
             }
             catch (navErr) {
-                response.gate1 = { status: "error", error: navErr instanceof Error ? navErr.message : String(navErr) };
-                response.result = "ERROR";
+                const errMsg = navErr instanceof Error ? navErr.message : String(navErr);
+                const isProxyBlock = errMsg.includes("ERR_TUNNEL_CONNECTION_FAILED") || errMsg.includes("ERR_PROXY_CONNECTION_FAILED");
+                const isProxyTimeout = errMsg.includes("ERR_NETWORK_CHANGED") && geoRegion;
+                if (isProxyBlock || isProxyTimeout) {
+                    response.gate1 = {
+                        status: "proxy_blocked",
+                        error: errMsg.split("\n")[0],
+                        geoRegion: geoRegion || undefined,
+                    };
+                    response.result = "PROXY_BLOCKED";
+                    response.message = `The site rejected the residential proxy connection${geoRegion ? ` (${geoRegion})` : ""}. This means ${url} actively blocks proxy/VPN traffic — this is the site's anti-bot defense, not a CBrowser issue.\n\nRecommendations:\n1. Re-run without --geo-region to test from the server's direct IP\n2. Try a different geo region (the site may block specific IP ranges)\n3. If you need geo-accurate results, use a datacenter proxy or test from a machine in the target region`;
+                }
+                else {
+                    response.gate1 = { status: "error", error: errMsg };
+                    response.result = "ERROR";
+                }
                 response.duration = `${Date.now() - startTime}ms`;
-                await browser.close();
+                if (ownsBrowser)
+                    await browser.close();
             }
         }
         catch (browserErr) {
-            response.gate1 = { status: "error", error: browserErr instanceof Error ? browserErr.message : String(browserErr) };
+            const errMsg = browserErr instanceof Error ? browserErr.message : String(browserErr);
+            response.gate1 = { status: "error", error: errMsg };
             response.result = "ERROR";
             response.duration = `${Date.now() - startTime}ms`;
         }
@@ -513,6 +632,7 @@ export function registerAuditTools(server) {
             persona: z.string().optional().default("cognitive-adhd").describe("Persona name"),
             device: z.string().optional().describe("Device to emulate: 'mobile', 'tablet', 'desktop', or a specific device like 'iPhone 15', 'Pixel 7', 'iPad Pro'. Default: desktop (1920x1080)."),
             useValues: z.boolean().optional().default(false).describe("Enable motivational value influence on saliency map generation, attention scoring, and narrative. Default: false."),
+            _browserToken: z.string().optional().describe("Reuse an existing browser session. Useful for testing translated or state-dependent pages."),
         },
         annotations: {
             title: "Visual Cognitive Story",
@@ -521,18 +641,29 @@ export function registerAuditTools(server) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ url, persona, device, useValues }) => {
+    }, async ({ url, persona, device, useValues, _browserToken }) => {
         const startTime = Date.now();
         const { join } = await import("path");
         const { tmpdir } = await import("os");
         const { writeFileSync, mkdirSync, existsSync, unlinkSync } = await import("fs");
+        let ownsVcsBrowser = true;
         try {
             const { CBrowser: BrowserClass } = await import("../../browser.js");
-            const browser = new BrowserClass({
-                headless: true,
-                ...(device ? { device: device.toLowerCase() } : { viewportWidth: 1920, viewportHeight: 1080 }),
-            });
-            await browser.launch();
+            let browser;
+            let vcsToken;
+            if (_browserToken && getBrowserByToken) {
+                const session = await getBrowserByToken(_browserToken);
+                browser = session.browser;
+                vcsToken = session.token;
+                ownsVcsBrowser = false;
+            }
+            else {
+                browser = new BrowserClass({
+                    headless: true,
+                    ...(device ? { device: device.toLowerCase() } : { viewportWidth: 1920, viewportHeight: 1080 }),
+                });
+                await browser.launch();
+            }
             try {
                 await browser.navigate(url);
                 await new Promise(r => setTimeout(r, 2000));
@@ -820,7 +951,8 @@ export function registerAuditTools(server) {
                 return { content };
             }
             finally {
-                await browser.close();
+                if (ownsVcsBrowser)
+                    await browser.close();
             }
         }
         catch (err) {