cbrowser 19.5.0 → 20.0.0

package/dist/browser.js

@@ -15,7 +15,8 @@ import { join, dirname } from "path";
 import { execSync } from "child_process";
 import { mergeConfig, getPaths, ensureDirectories } from "./config.js";
 import { getPersonaOrRefuse } from "./personas.js";
-import { DEVICE_PRESETS, LOCATION_PRESETS, CBrowserErrorCode } from "./types.js";
+import { LOCATION_PRESETS, CBrowserError, CBrowserErrorCode } from "./types.js";
+import { DEVICE_PRESETS, resolveDevice } from "./devices.js";
 import { runCognitiveJourney, isApiKeyConfigured, } from "./cognitive/index.js";
 import { SessionManager } from "./browser/session-manager.js";
 import { SelectorCacheManager } from "./browser/selector-cache.js";
@@ -258,6 +259,8 @@ export class CBrowser {
     // =========================================================================
     // Session State Persistence
     // =========================================================================
+    /** True when this run was given --device or --viewport (see launch). */
+    explicitPageShape = false;
     get sessionStateFile() {
         return join(this.paths.dataDir, "browser-state", "last-session.json");
     }
@@ -317,11 +320,22 @@ export class CBrowser {
             // Don't save about:blank or empty URLs
             if (!url || url === "about:blank" || url === "")
                 return;
+            // Device and location persist only when set on purpose (`device set`,
+            // `geo set`), so carry those over from the file. Saving this run's
+            // values made a one-off --device or --geo stick to every later command
+            // for an hour (audit 2026-10-21).
+            let previous = null;
+            try {
+                if (existsSync(this.sessionStateFile))
+                    previous = JSON.parse(readFileSync(this.sessionStateFile, "utf-8"));
+            }
+            catch { /* unreadable: start fresh */ }
             const state = {
                 url,
                 timestamp: Date.now(),
                 viewport,
-                device: device || this.config.device,
+                device: device ?? previous?.device,
+                ...(previous?.geolocation ? { geolocation: previous.geolocation } : {}),
             };
             const stateDir = join(this.paths.dataDir, "browser-state");
             if (!existsSync(stateDir)) {
@@ -362,6 +376,30 @@ export class CBrowser {
             console.error(`Failed to save device setting: ${e.message}`);
         }
     }
+    /**
+     * Save a geolocation to session state, so later commands launch with it
+     * (`cbrowser geo set`). Returns false when the state could not be written.
+     * Before 2026-10-21, geo set changed a browser that was never launched and
+     * printed success, so nothing changed.
+     */
+    saveGeolocationSetting(geo) {
+        try {
+            const stateDir = join(this.paths.dataDir, "browser-state");
+            if (!existsSync(stateDir))
+                mkdirSync(stateDir, { recursive: true });
+            const state = existsSync(this.sessionStateFile)
+                ? JSON.parse(readFileSync(this.sessionStateFile, "utf-8"))
+                : { url: "", timestamp: Date.now() };
+            state.geolocation = geo;
+            state.timestamp = Date.now();
+            writeFileSync(this.sessionStateFile, JSON.stringify(state, null, 2));
+            return true;
+        }
+        catch (e) {
+            console.error(`Failed to save geolocation: ${e.message}`);
+            return false;
+        }
+    }
     loadSessionState() {
         try {
             if (!existsSync(this.sessionStateFile))
@@ -460,6 +498,31 @@ For more help: https://playwright.dev/docs/browsers
     async launch() {
         if (this.browser || this.context)
             return;
+        // An unknown device is an error, never a silent desktop render (reported
+        // 2026-10-21: "iphone-16" captured 1280x800 and called it success, and so did
+        // "Pixel 7" from the MCP tools' own descriptions). Names are normalised here,
+        // so "iPhone 16" and "iphone-16" are the same preset.
+        if (this.config.device) {
+            const resolved = resolveDevice(this.config.device);
+            if ("error" in resolved) {
+                const closest = resolved.suggestions.length > 0 ? ` Closest presets: ${resolved.suggestions.join(", ")}.` : "";
+                throw new CBrowserError(CBrowserErrorCode.CONFIG_INVALID, `${resolved.error}.${closest}`, {
+                    device: this.config.device,
+                    suggestions: resolved.suggestions,
+                    howToFix: "Use a preset name ('cbrowser device list' shows them all; case and spaces do not matter), or set a custom size with --viewport WIDTHxHEIGHT.",
+                });
+            }
+            this.config.device = resolved.key;
+        }
+        // Was the page shape asked for on this run? Then the saved session's
+        // viewport must not overwrite it after launch.
+        this.explicitPageShape = !!this.config.device || !!this.config.viewportOverride;
+        // Restore a location saved by `cbrowser geo set` unless one was given.
+        if (this.config.persistent && !this.config.geolocation) {
+            const saved = this.loadSessionState();
+            if (saved?.geolocation)
+                this.config.geolocation = saved.geolocation;
+        }
         // Load saved session state to restore device setting if not explicitly set
         if (this.config.persistent && !this.config.device) {
             const savedSession = this.loadSessionState();
@@ -489,7 +552,11 @@ For more help: https://playwright.dev/docs/browsers
         if (this.config.device && DEVICE_PRESETS[this.config.device]) {
             const device = DEVICE_PRESETS[this.config.device];
             contextOptions.viewport = device.viewport;
-            contextOptions.userAgent = device.userAgent;
+            // The DevTools laptops have no user agent of their own and keep the
+            // browser's. Playwright 1.58 already treats "" as unset; this does not
+            // rely on that.
+            if (device.userAgent)
+                contextOptions.userAgent = device.userAgent;
             contextOptions.deviceScaleFactor = device.deviceScaleFactor;
             contextOptions.isMobile = device.isMobile;
             contextOptions.hasTouch = device.hasTouch;
@@ -502,6 +569,12 @@ For more help: https://playwright.dev/docs/browsers
             contextOptions.isMobile = device.isMobile;
             contextOptions.hasTouch = device.hasTouch;
         }
+        // An explicit --viewport sets the size even with a device preset, which
+        // keeps its pixel ratio, touch and user agent. Before 2026-10-21 the preset
+        // silently won.
+        if (this.config.viewportOverride) {
+            contextOptions.viewport = { ...this.config.viewportOverride };
+        }
         // Apply custom user agent if set (overrides device)
         if (this.config.userAgent) {
             contextOptions.userAgent = this.config.userAgent;
@@ -719,7 +792,8 @@ For more help: https://playwright.dev/docs/browsers
                     await this.page.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => { });
                     await this.page.waitForTimeout(1000);
                     // Apply saved viewport if available
-                    if (savedSession.viewport) {
+                    // An explicit --device or --viewport wins over last run's size.
+                    if (savedSession.viewport && !this.explicitPageShape) {
                         await this.page.setViewportSize(savedSession.viewport);
                     }
                 }
@@ -854,7 +928,7 @@ For more help: https://playwright.dev/docs/browsers
                         // Wait for network idle and JS hydration
                         await this.page.waitForLoadState("networkidle", { timeout: 10000 }).catch(() => { });
                         await this.page.waitForTimeout(1000);
-                        if (savedSession.viewport) {
+                        if (savedSession.viewport && !this.explicitPageShape) {
                             await this.page.setViewportSize(savedSession.viewport);
                         }
                     }
@@ -1658,7 +1732,8 @@ For more help: https://playwright.dev/docs/browsers
         const filtered = cookies.filter((c) => {
             if (c.name !== name)
                 return true;
-            if (domain && c.domain !== domain)
+            // ".example.com" and "example.com" name the same cookie domain.
+            if (domain && c.domain.replace(/^\./, "") !== domain.replace(/^\./, ""))
                 return true;
             return false;
         });
@@ -1700,11 +1775,42 @@ For more help: https://playwright.dev/docs/browsers
      * Set device emulation (requires browser restart).
      */
     setDevice(deviceName) {
-        if (DEVICE_PRESETS[deviceName]) {
-            this.config.device = deviceName;
-            return true;
+        const resolved = resolveDevice(deviceName);
+        if ("error" in resolved)
+            return false;
+        this.config.device = resolved.key;
+        return true;
+    }
+    /**
+     * Emulate a device preset and/or set the page size, relaunching if the
+     * browser is already up (context options are fixed at launch). An unknown
+     * device throws, as at launch. Returns the device key applied.
+     */
+    async emulate(opts) {
+        let key;
+        if (opts.device) {
+            const resolved = resolveDevice(opts.device);
+            if ("error" in resolved) {
+                const closest = resolved.suggestions.length > 0 ? ` Closest presets: ${resolved.suggestions.join(", ")}.` : "";
+                throw new CBrowserError(CBrowserErrorCode.CONFIG_INVALID, `${resolved.error}.${closest}`, {
+                    device: opts.device,
+                    suggestions: resolved.suggestions,
+                });
+            }
+            key = resolved.key;
         }
-        return false;
+        if (this.browser || this.context)
+            await this.close();
+        if (key)
+            this.config.device = key;
+        if (opts.viewport) {
+            this.config.viewportOverride = { ...opts.viewport };
+            if (!key) {
+                this.config.viewportWidth = opts.viewport.width;
+                this.config.viewportHeight = opts.viewport.height;
+            }
+        }
+        return { device: this.config.device ?? null };
     }
     /**
      * List available device presets.
@@ -5507,202 +5613,57 @@ For more help: https://playwright.dev/docs/browsers
     // Journeys
     // =========================================================================
     /**
-     * Run an autonomous journey.
+     * Run an autonomous journey: a model-driven cognitive journey for one persona.
      *
-     * When API key is configured, uses AI-driven cognitive journeys (Claude API)
-     * for realistic user simulation with cognitive state tracking.
+     * Needs an Anthropic API key. There is no keyless fallback any more (20.0.0):
+     * the old heuristic explorer clicked the highest keyword match among the first
+     * twenty links and called the goal reached when any goal word, "the"
+     * included, appeared anywhere on the page. Measured 2026-10-21: "buy the blue
+     * widget" on a page with no widget reported success for every persona, with
+     * identical click paths. A result that is always yes is not a measurement.
      *
-     * Without API key, falls back to heuristic exploration (simplified).
-     *
-     * @requires ANTHROPIC_API_KEY for cognitive mode (set via `npx cbrowser config set-api-key`)
+     * @requires ANTHROPIC_API_KEY (set via `npx cbrowser config set-api-key`)
      */
     async journey(options) {
         const { persona: personaName, startUrl, goal, maxSteps = 20, maxTime = 120 } = options;
-        // Check if cognitive journeys are available (API key configured)
-        if (isApiKeyConfigured()) {
-            try {
-                const cognitiveResult = await runCognitiveJourney({
-                    persona: personaName,
-                    startUrl,
-                    goal,
-                    maxSteps,
-                    maxTime,
-                    headless: this.config.headless,
-                    vision: false,
-                    verbose: false,
-                });
-                // Map cognitive journey result to JourneyResult format
-                return {
-                    persona: personaName,
-                    goal,
-                    steps: cognitiveResult.frictionPoints.map((fp, _i) => ({
-                        action: fp.type,
-                        target: fp.element || 'page',
-                        result: fp.monologue.substring(0, 100),
-                        screenshot: fp.screenshot,
-                        timestamp: new Date().toISOString(),
-                    })),
-                    success: cognitiveResult.goalAchieved,
-                    frictionPoints: cognitiveResult.frictionPoints.map(fp => `${fp.type}: ${fp.monologue.substring(0, 80)}`),
-                    totalTime: cognitiveResult.totalTime * 1000, // Convert to ms
-                    consoleLogs: [],
-                    cognitive: {
-                        patienceRemaining: cognitiveResult.finalState.patienceRemaining,
-                        frustrationLevel: cognitiveResult.finalState.frustrationLevel,
-                        confusionLevel: cognitiveResult.finalState.confusionLevel,
-                        abandonmentReason: cognitiveResult.abandonmentReason,
-                        backtrackCount: cognitiveResult.summary.backtrackCount,
-                        monologue: cognitiveResult.fullMonologue,
-                    },
-                };
-            }
-            catch (e) {
-                console.warn(`Cognitive journey failed, falling back to heuristic: ${e.message}`);
-                // Fall through to heuristic mode
-            }
-        }
-        // Heuristic mode (no API key or cognitive journey failed)
-        // NOTE: This is simplified exploration. For realistic user simulation,
-        // configure an API key: npx cbrowser config set-api-key YOUR_KEY
-        const persona = getPersonaOrRefuse(personaName);
-        this.currentPersona = persona;
-        // Set viewport based on persona
-        if (persona.context?.viewport) {
-            this.config.viewportWidth = persona.context.viewport[0];
-            this.config.viewportHeight = persona.context.viewport[1];
-        }
-        const page = await this.getPage();
-        const consoleLogs = [];
-        const frictionPoints = [];
-        const startTime = Date.now();
-        // Capture console logs. Removed in the finally below (v8 B27, 2026-10-10):
-        // it used to stay on the tab, which is the shared page in a hosted session,
-        // so every heuristic journey left one more listener and log array behind
-        // (measured 4 -> 7 console listeners over three runs). Not read from the
-        // tab's console buffer instead: that keeps 500 entries and omits an empty
-        // location, so a noisy page or an inline script would change consoleLogs.
-        const onConsole = (msg) => {
-            const entry = {
-                type: msg.type(),
-                text: msg.text().substring(0, 500),
-                timestamp: new Date().toISOString(),
-                url: msg.location()?.url,
-                lineNumber: msg.location()?.lineNumber,
-            };
-            consoleLogs.push(entry);
-            if (msg.type() === "error") {
-                frictionPoints.push(`Console error: ${msg.text().substring(0, 100)}`);
-            }
-        };
-        page.on("console", onConsole);
-        try {
-            return await this.heuristicJourney(page, persona, options, consoleLogs, frictionPoints, startTime);
+        if (!isApiKeyConfigured()) {
+            throw new Error("A journey needs an Anthropic API key (cbrowser config set-api-key <key>). The keyless heuristic explorer was removed in 20.0.0 because its results were not accurate.");
         }
-        finally {
-            page.off("console", onConsole);
-        }
-    }
-    /** journey()'s heuristic exploration; journey's listener fills `consoleLogs`. */
-    async heuristicJourney(page, persona, options, consoleLogs, frictionPoints, startTime) {
-        const { persona: personaName, startUrl, goal, maxSteps = 20 } = options;
-        const steps = [];
-        // Navigate to start
-        await this.navigate(startUrl);
-        steps.push({
-            action: "navigate",
-            target: startUrl,
-            result: `Loaded: ${await page.title()}`,
-            screenshot: await this.screenshot(),
-            timestamp: new Date().toISOString(),
-        });
-        // Heuristic exploration (simplified - no API key available)
-        // For realistic AI-driven exploration, set API key: npx cbrowser config set-api-key
-        let stepCount = 0;
-        let success = false;
-        while (stepCount < maxSteps && !success) {
-            stepCount++;
-            // Wait with human-like timing
-            const delay = this.getHumanDelay(persona);
-            await new Promise((r) => setTimeout(r, delay));
-            // Try to find clickable elements
-            const clickable = await page.evaluate((goalText) => {
-                const elements = Array.from(document.querySelectorAll('a, button, [role="button"], input[type="submit"]'));
-                // Score elements by relevance to goal (deterministic, not random)
-                const scored = elements.slice(0, 20).map((el) => {
-                    const text = el.textContent?.trim().substring(0, 50) || '';
-                    const href = el.href || '';
-                    const textLower = text.toLowerCase();
-                    const goalWords = goalText.toLowerCase().split(' ').filter(w => w.length > 2);
-                    // Calculate relevance score
-                    let score = 0;
-                    for (const word of goalWords) {
-                        if (textLower.includes(word))
-                            score += 3;
-                        if (href.toLowerCase().includes(word))
-                            score += 2;
-                    }
-                    // Boost common action words
-                    if (textLower.match(/submit|continue|next|proceed|sign|login|register/))
-                        score += 1;
-                    return { tag: el.tagName, text, href, score };
-                });
-                // Sort by score (highest first) and return top 5
-                return scored.sort((a, b) => b.score - a.score).slice(0, 5);
-            }, goal);
-            if (clickable.length === 0) {
-                frictionPoints.push("No clickable elements found");
-                break;
-            }
-            // Select highest-scored element (deterministic)
-            const target = clickable[0];
-            const result = await this.click(target.text || target.tag);
-            steps.push({
-                action: "click",
-                target: target.text || target.tag,
-                result: result.message,
-                screenshot: result.screenshot,
-                timestamp: new Date().toISOString(),
-            });
-            // Check if goal might be achieved
-            const pageText = await page.evaluate(() => document.body.innerText.toLowerCase());
-            if (goal.toLowerCase().split(" ").some((word) => pageText.includes(word))) {
-                success = true;
-            }
-        }
-        // Save final screenshot
-        steps.push({
-            action: "final",
-            result: `Final page: ${await page.title()}`,
-            screenshot: await this.screenshot(),
-            timestamp: new Date().toISOString(),
+        // Refuse an unknown persona before spending tokens.
+        this.currentPersona = getPersonaOrRefuse(personaName);
+        const cognitiveResult = await runCognitiveJourney({
+            persona: personaName,
+            startUrl,
+            goal,
+            maxSteps,
+            maxTime,
+            headless: this.config.headless,
+            vision: false,
+            verbose: false,
         });
-        const result = {
+        return {
             persona: personaName,
             goal,
-            steps,
-            success,
-            frictionPoints,
-            totalTime: Date.now() - startTime,
-            consoleLogs,
+            steps: cognitiveResult.frictionPoints.map((fp) => ({
+                action: fp.type,
+                target: fp.element || 'page',
+                result: fp.monologue.substring(0, 100),
+                screenshot: fp.screenshot,
+                timestamp: new Date().toISOString(),
+            })),
+            success: cognitiveResult.goalAchieved,
+            frictionPoints: cognitiveResult.frictionPoints.map(fp => `${fp.type}: ${fp.monologue.substring(0, 80)}`),
+            totalTime: cognitiveResult.totalTime * 1000, // Convert to ms
+            consoleLogs: [],
+            cognitive: {
+                patienceRemaining: cognitiveResult.finalState.patienceRemaining,
+                frustrationLevel: cognitiveResult.finalState.frustrationLevel,
+                confusionLevel: cognitiveResult.finalState.confusionLevel,
+                abandonmentReason: cognitiveResult.abandonmentReason,
+                backtrackCount: cognitiveResult.summary.backtrackCount,
+                monologue: cognitiveResult.fullMonologue,
+            },
         };
-        // Save journey results
-        const journeyFile = join(this.paths.dataDir, `journey-${Date.now()}.json`);
-        writeFileSync(journeyFile, JSON.stringify(result, null, 2));
-        return result;
-    }
-    /**
-     * Get human-like delay based on persona.
-     * Uses deterministic average of min/max (no random).
-     * For realistic variable timing, use cognitive journeys with API key.
-     */
-    getHumanDelay(persona) {
-        const timing = persona.humanBehavior?.timing;
-        if (!timing)
-            return 500;
-        const min = timing.reactionTime.min;
-        const max = timing.reactionTime.max;
-        // Use midpoint for deterministic behavior (no random)
-        return Math.floor((min + max) / 2);
     }
     // =========================================================================
     // Constitutional Safety
@@ -6825,12 +6786,18 @@ For more help: https://playwright.dev/docs/browsers
      */
     exportJUnit(suite, outputPath) {
         const filename = outputPath || join(this.paths.dataDir, `junit-${Date.now()}.xml`);
+        // Names and errors are page and test-file text: escaped, or a test named
+        // "Search & filter" wrote XML no CI parser accepts. A failed test is a
+        // failure with or without an error message; it used to pass without one.
+        const esc = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+        const failures = suite.tests.filter((t) => t.status === "failed").length;
         let xml = `<?xml version="1.0" encoding="UTF-8"?>\n`;
-        xml += `<testsuite name="${suite.name}" tests="${suite.tests.length}">\n`;
+        xml += `<testsuite name="${esc(suite.name)}" tests="${suite.tests.length}" failures="${failures}">\n`;
         for (const test of suite.tests) {
-            xml += `  <testcase name="${test.name}" time="${(test.duration / 1000).toFixed(3)}">\n`;
-            if (test.status === "failed" && test.error) {
-                xml += `    <failure message="${test.error.replace(/"/g, "&quot;")}">${test.error}</failure>\n`;
+            xml += `  <testcase name="${esc(test.name)}" time="${(test.duration / 1000).toFixed(3)}">\n`;
+            if (test.status === "failed") {
+                const message = test.error || "failed";
+                xml += `    <failure message="${esc(message)}">${esc(message)}</failure>\n`;
             }
             xml += `  </testcase>\n`;
         }
@@ -6847,7 +6814,8 @@ For more help: https://playwright.dev/docs/browsers
         tap += `1..${suite.tests.length}\n`;
         suite.tests.forEach((test, i) => {
             const status = test.status === "passed" ? "ok" : "not ok";
-            tap += `${status} ${i + 1} ${test.name}\n`;
+            // One line per test, and a "#" in a name is not read as a directive.
+            tap += `${status} ${i + 1} ${test.name.replace(/[\r\n]+/g, " ").replace(/#/g, "\\#")}\n`;
         });
         writeFileSync(filename, tap);
         return filename;
@@ -6894,9 +6862,11 @@ For more help: https://playwright.dev/docs/browsers
      * Run the same task across multiple device configurations in parallel.
      */
     static async parallelDevices(devices, run, options = {}) {
+        // `config` is shared by every device (headless, engine); each task's own
+        // device wins over one in it.
         const tasks = devices.map(device => ({
             name: device,
-            config: { device },
+            config: { ...options.config, device },
             run: (browser) => run(browser, device),
         }));
         const results = await CBrowser.parallel(tasks, options);