cbrowser 19.4.3 → 19.6.0

package/dist/cli.js

@@ -20,7 +20,8 @@ import { capturePerformanceBaseline, listPerformanceBaselines, loadPerformanceBa
 // Visual module imports
 import { captureVisualBaseline, listVisualBaselines, getVisualBaseline, deleteVisualBaseline, runVisualRegression, runVisualRegressionSuite, formatVisualRegressionReport, generateVisualRegressionHtmlReport, runCrossBrowserTest, runCrossBrowserSuite, formatCrossBrowserReport, generateCrossBrowserHtmlReport, runResponsiveTest, runResponsiveSuite, formatResponsiveReport, generateResponsiveHtmlReport, listViewportPresets, runABComparison, runABSuite, formatABReport, generateABHtmlReport, crossBrowserDiff } from "./visual/index.js";
 import { BUILTIN_PERSONAS, loadCustomPersonas, saveCustomPersona, deleteCustomPersona, isBuiltinPersona, generatePersonaFromDescription, listAccessibilityPersonas, } from "./personas.js";
-import { DEVICE_PRESETS, LOCATION_PRESETS } from "./types.js";
+import { LOCATION_PRESETS } from "./types.js";
+import { CBROWSER_DEVICE_KEYS, DEVICE_PRESETS, resolveDevice } from "./devices.js";
 import { startMcpServer } from "./mcp-server.js";
 import { startRemoteMcpServer } from "./mcp-server-remote.js";
 import { startDaemon, stopDaemon, getDaemonStatus, isDaemonRunning, sendToDaemon, runDaemonServer } from "./daemon.js";
@@ -29,6 +30,8 @@ import { getStatusInfo, formatStatus, getDataDir, getPaths } from "./config.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolveCookieDomain, hostFromUrl } from "./utils.js";
 import { dirname, join, resolve } from "node:path";
+import { guardConsole, guardTerminalOutput } from "./terminal-safe.js";
+import { evaluateScript } from "./eval-script.js";
 import { VideoCaptureSession } from "./recording/engine.js";
 import { changeSignal, parseManifest } from "./recording/types.js";
 import { printEnterpriseStatus } from "./stealth/index.js";
@@ -298,7 +301,7 @@ COOKIE MANAGEMENT
   cookie clear                Clear all cookies
 
 DEVICE EMULATION
-  device list                 List available device presets
+  device list [filter]        List device presets, one per line (filter by name)
   device set <name>           Set device emulation for session
     Example: cbrowser device set iphone-15
 
@@ -345,6 +348,10 @@ NETWORK / HAR (need the daemon: each command is its own process)
   har stop [output]           Stop and save HAR file
   network list                List network requests the daemon's browser captured
   network clear               Clear that list
+  console                     List the daemon tab's console messages (errors, warnings, logs)
+    --filter <type>           all | error | warning | log | info (default all)
+    --clear                   Empty the console buffer after reading
+    --json                    Print the raw messages as JSON
 
 VISUAL REGRESSION (v2.5.0)
   visual save <name>          Save baseline screenshot
@@ -740,6 +747,8 @@ CLAUDE SKILL INSTALLATION & SYNC
 DAEMON MODE (v6.4.0)
   daemon start                Start background daemon (keeps browser running)
     --port <port>             Daemon port (default: 9222)
+    --device <name>           Device the daemon's browser emulates
+    --viewport <WxH>          Page size of the daemon's browser
     --timeout <min>           Idle timeout in minutes (default: 30)
   daemon stop                 Stop the running daemon
   daemon status               Check if daemon is running
@@ -791,7 +800,9 @@ STORAGE & CLEANUP
 
 OPTIONS
   --browser <type>            Browser: chromium, firefox, webkit (default: chromium)
-  --device <name>             Device preset: iphone-15, pixel-8, ipad-pro-12, etc.
+  --device <name>             Device preset: iphone-16, pixel-9, ipad-pro-13, ... ('device list')
+  --viewport <WxH>            Page size, e.g. 390x844; with --device it sets the size and
+                              the device keeps its pixel ratio, touch and user agent
   --geo <location>            Location preset or lat,lon coordinates
   --locale <locale>           Browser locale (e.g., en-US, fr-FR)
   --timezone <tz>             Timezone (e.g., America/New_York)
@@ -970,10 +981,17 @@ const DRIVES_THE_PAGE = [
     "keyboard", "press", "type", "evaluate", "eval", "drag", "upload",
     "smart-click", "dismiss-overlay", "assert",
 ];
-const GLOBAL_FLAGS = [
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose", "help", "no-color", "quiet", "json",
+/**
+ * Flags the shared CBrowser construction consumes, for every command that uses
+ * it. One list, spread into each command's set below: when this list was copied
+ * into each set, --viewport (2026-10-21) reached some commands and was refused
+ * by evaluate and keyboard.
+ */
+const SHARED_BROWSER_FLAGS = [
+    "url", "browser", "device", "viewport", "headless", "persistent", "restore",
+    "locale", "timezone", "geo", "verbose",
 ];
+const GLOBAL_FLAGS = [...SHARED_BROWSER_FLAGS, "help", "no-color", "quiet", "json"];
 /**
  * Declared options per command.
  *
@@ -1141,29 +1159,24 @@ const CAPTURE_FLAGS = new Set([
     "contact-sheet", "attention-overlay", "overlay-persona", "overlay-goal",
     "after", "after-element", "after-delay",
     "until-element", "until-element-gone", "until-idle", "timeout",
-    // globals honoured by the shared CBrowser construction
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose",
+    ...SHARED_BROWSER_FLAGS,
 ]);
 /**
  * Resolve `--device` to a real preset key, or exit naming the bad value.
  *
- * CBrowser silently ignores an unknown device name (browser.ts: the preset
- * lookup is inside the `if`), which would hand back a 1280x800 desktop capture
- * for `--device "iPhone 14"` and call it success. Spaces and case are
- * normalised so "iPhone 15" finds "iphone-15".
+ * `capture start` checks here, before it builds anything. Every other command
+ * gets the same check from CBrowser.launch() (src/devices.ts resolveDevice);
+ * before 2026-10-21 the browser skipped names it did not know and rendered
+ * 1280x800 desktop. Case and spaces do not matter: "iPhone 15" is "iphone-15".
  */
 function resolveDevicePreset(value) {
-    const normalised = value.trim().toLowerCase().replace(/\s+/g, "-");
-    if (DEVICE_PRESETS[normalised])
-        return normalised;
-    const known = Object.keys(DEVICE_PRESETS);
-    const stem = normalised.replace(/-?\d+.*$/, "");
-    const close = known.filter((k) => k.startsWith(stem) && stem.length > 0);
+    const resolved = resolveDevice(value);
+    if ("key" in resolved)
+        return resolved.key;
     console.error(`Error: unknown --device "${value}"`);
-    if (close.length > 0)
-        console.error(`  Did you mean: ${close.join(", ")}?`);
-    console.error(`  Available presets: ${known.join(", ")}`);
+    if (resolved.suggestions.length > 0)
+        console.error(`  Did you mean: ${resolved.suggestions.join(", ")}?`);
+    console.error(`  'cbrowser device list' shows all ${Object.keys(DEVICE_PRESETS).length} presets; --viewport WIDTHxHEIGHT sets any size.`);
     process.exit(1);
 }
 /** Reject any flag `capture start` cannot honour, naming it. */
@@ -1747,8 +1760,7 @@ function reportAutoCapture(capture) {
 /** Flags `evaluate` understands; anything else is rejected rather than ignored. */
 const EVALUATE_FLAGS = new Set([
     "file", "arg", "json", "raw", "wait-for", "timeout", "expect-truthy", "force",
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose",
+    ...SHARED_BROWSER_FLAGS,
 ]);
 /**
  * `--force` is a bare flag, but the parser gives any flag the next non-flag
@@ -1781,53 +1793,6 @@ function repeatedFlag(name) {
     }
     return values;
 }
-/**
- * Evaluate a script in the page, accepting all three shapes people write.
- *
- * `--file` exists because multi-line scripts die in shell quoting, so it has to
- * accept real scripts - `const`, `let`, an explicit `return` - not only a
- * single expression. The source is compiled inside the page as a function
- * body: a bare expression gets an implicit return, a statement body keeps its
- * own, and a function/arrow literal is called with the arguments.
- */
-async function evaluateScript(page, script, args) {
-    const source = script.trim();
-    // A function or arrow literal is called with the arguments directly.
-    const isCallable = /^(async\s+)?function\b/.test(source) || /=>/.test(source);
-    return page.evaluate((payload) => {
-        if (payload.callable) {
-            const fn = (0, eval)(`(${payload.src})`);
-            return fn(...payload.a);
-        }
-        const compile = (src) => {
-            // 1. A bare expression: implicit return.
-            try {
-                return new Function("args", `return (${src});`);
-            }
-            catch { /* not an expression */ }
-            // 2. Statements with no explicit return: return the final expression,
-            //    which is what a REPL and the old one-arg form both did.
-            if (!/\breturn\b/.test(src)) {
-                const trimmed = src.replace(/;\s*$/, "");
-                const split = Math.max(trimmed.lastIndexOf(";"), trimmed.lastIndexOf("\n"));
-                if (split > -1) {
-                    const head = trimmed.slice(0, split + 1);
-                    const tail = trimmed.slice(split + 1).trim();
-                    if (tail) {
-                        try {
-                            return new Function("args", `${head}\nreturn (${tail});`);
-                        }
-                        catch { /* the tail is not an expression either */ }
-                    }
-                }
-            }
-            // 3. Statements as written. Any syntax error surfaces from here, which
-            //    is the error the user should actually see.
-            return new Function("args", src);
-        };
-        return compile(payload.src)(payload.a);
-    }, { src: source, a: args, callable: isCallable });
-}
 /**
  * Run JavaScript in the page.
  *
@@ -2067,8 +2032,7 @@ function parseKeyboardToken(token, literal = false) {
 /** Flags `keyboard` understands. */
 const KEYBOARD_FLAGS = new Set([
     "delay", "selector", "hold", "repeat", "text", "force",
-    "url", "browser", "device", "headless", "persistent", "restore",
-    "locale", "timezone", "geo", "verbose",
+    ...SHARED_BROWSER_FLAGS,
 ]);
 /**
  * Drive a keyboard sequence.
@@ -2614,6 +2578,12 @@ async function main() {
     const outputOpts = detectOutputOptions(options);
     setOutputOptions(outputOpts);
     installOutputWrappers();
+    // Page-derived text (console messages, titles, extracted text) reaches stdout in
+    // many places; escape sequences and bidi overrides in it come out as visible
+    // escapes instead of acting on the terminal. (2026-10-12)
+    guardTerminalOutput(process.stdout);
+    guardTerminalOutput(process.stderr);
+    guardConsole();
     // --json-output must never leave stdout empty. Only two commands in this file
     // call emitJson, so without this every other command printed nothing at all and
     // still exited 0 — a CI step piping to jq saw empty input beside a success code.
@@ -2857,9 +2827,28 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
         const port = parseInt(options.port) || 9222;
         switch (subCommand) {
             case "start": {
+                // The daemon's browser takes its device and size from here. Both are
+                // checked now: a bad value inside the detached daemon would only show
+                // up as a daemon that failed to start.
+                const launchArgs = [];
+                if (typeof options.device === "string")
+                    launchArgs.push("--device", resolveDevicePreset(options.device));
+                if (typeof options.viewport === "string") {
+                    try {
+                        parseViewportList(options.viewport);
+                    }
+                    catch (e) {
+                        console.error(`Error: ${e.message}`);
+                        process.exit(1);
+                    }
+                    launchArgs.push("--viewport", options.viewport);
+                }
                 console.log("🚀 Starting CBrowser daemon...");
-                const result = await startDaemon(port);
+                const result = await startDaemon(port, launchArgs);
                 console.log(result.success ? `✓ ${result.message}` : `✗ ${result.message}`);
+                if (result.alreadyRunning && launchArgs.length > 0) {
+                    console.error("⚠ --device and --viewport were not applied: the daemon was already running. Run cbrowser daemon stop first.");
+                }
                 process.exit(result.success ? 0 : 1);
                 break;
             }
@@ -2883,9 +2872,12 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     : options.browser === "webkit" ? "webkit"
                         : "chromium";
                 // runDaemonServer will merge with defaults internally
+                const runViewport = typeof options.viewport === "string" ? parseViewportList(options.viewport)[0] : undefined;
                 await runDaemonServer({
                     browser: browserType,
                     headless: options.headless !== false && options.headless !== "false",
+                    ...(typeof options.device === "string" ? { device: options.device } : {}),
+                    ...(runViewport ? { viewportWidth: runViewport.width, viewportHeight: runViewport.height, viewportOverride: runViewport } : {}),
                 }, port);
                 return;
             }
@@ -2908,6 +2900,12 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
     ];
     if (daemonRunning && INTERACTION_COMMANDS.includes(command)) {
         console.log("🔌 Connected to running daemon");
+        // The daemon's browser keeps the device and size it started with; a flag on
+        // a command it runs cannot change them, so say so instead of ignoring it.
+        if (typeof options.device === "string" || typeof options.viewport === "string") {
+            console.error("⚠ --device and --viewport do not apply to commands the daemon runs: its browser keeps the device and size it started with.");
+            console.error("  To change them: cbrowser daemon stop, then cbrowser daemon start --device <name> --viewport <WxH>");
+        }
         const daemonCommand = command;
         let daemonArgs = {};
         switch (command) {
@@ -2978,7 +2976,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     console.error("  Re-run with --force to run it anyway.");
                     process.exit(1);
                 }
-                daemonArgs = { body: `return (function(){ ${/\breturn\b/.test(script) ? script : `return (${script});`} })();`, args: [], force: true };
+                // The raw script: the daemon compiles it with the same evaluateScript as the
+                // local path. This hand-built body treated a "return" anywhere - even inside
+                // a nested function - as statements, and an IIFE's value was dropped.
+                // (2026-10-13)
+                daemonArgs = { script, args: [], force: true };
                 break;
             }
             case "screenshot": {
@@ -3019,7 +3021,9 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
         const result = await sendToDaemon(daemonCommand, daemonArgs);
         if (result.success) {
             console.log("✓ Command executed via daemon");
-            if (result.result) {
+            // evaluate's value is the answer, so 0, false and "" print too; for other
+            // commands an empty result means nothing to show. (2026-10-13)
+            if (daemonCommand === "evaluate" ? result.result !== undefined : result.result) {
                 console.log(JSON.stringify(result.result, null, 2));
             }
         }
@@ -3085,7 +3089,7 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
         browser: browserType,
         headless,
         device: options.device,
-        ...(viewportOverride ? { viewportWidth: viewportOverride.width, viewportHeight: viewportOverride.height } : {}),
+        ...(viewportOverride ? { viewportWidth: viewportOverride.width, viewportHeight: viewportOverride.height, viewportOverride } : {}),
         geolocation,
         locale: options.locale,
         timezone: options.timezone,
@@ -4230,14 +4234,18 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                 const subcommand = args[0];
                 switch (subcommand) {
                     case "list": {
-                        console.log("\n📱 Available Device Presets:\n");
-                        for (const [name, device] of Object.entries(DEVICE_PRESETS)) {
-                            console.log(`  ${name}`);
-                            console.log(`    ${device.name}`);
-                            console.log(`    ${device.viewport.width}x${device.viewport.height} @${device.deviceScaleFactor}x`);
-                            console.log(`    Mobile: ${device.isMobile} | Touch: ${device.hasTouch}`);
-                            console.log("");
-                        }
+                        // One line per preset: there are a few hundred now. An optional
+                        // filter matches the key or the display name.
+                        const filter = (args[1] ?? "").toLowerCase();
+                        const rows = Object.entries(DEVICE_PRESETS).filter(([key, d]) => !filter || key.includes(filter) || d.name.toLowerCase().includes(filter));
+                        const width = Math.max(...rows.map(([key]) => key.length), 4);
+                        console.log(`\n📱 Device presets${filter ? ` matching "${filter}"` : ""}: ${rows.length}\n`);
+                        for (const [key, d] of rows) {
+                            const kind = d.isMobile ? "mobile" : "desktop";
+                            const touch = d.hasTouch ? ", touch" : "";
+                            console.log(`  ${key.padEnd(width)}  ${d.viewport.width}x${d.viewport.height} @${d.deviceScaleFactor}x  ${kind}${touch}  (${d.name})`);
+                        }
+                        console.log("\n  Case and spaces do not matter: --device \"iPhone 16\" is iphone-16.");
                         break;
                     }
                     case "set": {
@@ -4246,15 +4254,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("Usage: cbrowser device set <name>");
                             process.exit(1);
                         }
-                        if (!DEVICE_PRESETS[deviceName]) {
-                            console.error(`Unknown device: ${deviceName}`);
-                            console.error("Run 'cbrowser device list' to see available devices");
-                            process.exit(1);
-                        }
+                        const presetKey = resolveDevicePreset(deviceName);
                         // Save device setting to persistent session state
                         const deviceBrowser = new CBrowser({ persistent: true, headless: true, verbose: false });
-                        deviceBrowser.saveDeviceSetting(deviceName);
-                        console.log(`✓ Device set: ${deviceName}`);
+                        deviceBrowser.saveDeviceSetting(presetKey);
+                        console.log(`✓ Device set: ${presetKey}`);
                         console.log("  Device emulation will apply to all subsequent commands");
                         break;
                     }
@@ -4427,6 +4431,45 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
             // =========================================================================
             // Network
             // =========================================================================
+            case "console": {
+                // The daemon tab's console (log, info, warning, error, uncaught exceptions,
+                // failed resources), as get_console_messages returns it over MCP. Served by
+                // the daemon: a fresh process has no tab and would always list nothing.
+                const filter = typeof options.filter === "string" ? options.filter : "all";
+                if (!["all", "error", "warning", "log", "info"].includes(filter)) {
+                    console.error(`Error: --filter must be one of all, error, warning, log, info (got "${filter}")`);
+                    process.exit(1);
+                }
+                if (!(await isDaemonRunning())) {
+                    console.error("Error: the console log only spans commands in the daemon's browser; each cbrowser command is");
+                    console.error("  its own process. Start the daemon first:");
+                    console.error("  cbrowser daemon start  ->  navigate/click...  ->  cbrowser console [--filter error] [--clear] [--json]");
+                    process.exit(1);
+                }
+                const response = await sendToDaemon("consoleMessages", { filter, clear: options.clear === true });
+                if (!response.success) {
+                    console.error(`✗ Daemon error: ${response.error}`);
+                    process.exit(1);
+                }
+                const out = response.result;
+                if (options.json === true) {
+                    console.log(JSON.stringify(out, null, 2));
+                }
+                else if (out.count === 0) {
+                    console.log(filter === "all" ? "No console messages" : `No ${filter} console messages`);
+                }
+                else {
+                    console.log(`\n🖥  Console (${out.count}${out.dropped ? `, ${out.dropped} older dropped` : ""}):\n`);
+                    for (const m of out.messages) {
+                        const where = m.url ? ` (${m.url}${m.lineNumber !== undefined ? `:${m.lineNumber}` : ""})` : "";
+                        console.log(`  [${m.type}${m.source === "pageerror" ? ", uncaught" : ""}] ${m.text}${where}`);
+                        console.log(`    on ${m.pageUrl}`);
+                    }
+                }
+                if (options.clear === true)
+                    console.log("✓ Console cleared");
+                process.exit(0);
+            }
             case "network": {
                 const subcommand = args[0];
                 if (subcommand !== "list" && subcommand !== "clear") {
@@ -5398,9 +5441,10 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                             console.error("Usage: cbrowser parallel devices <url> [--devices <list>] [--concurrency <n>]");
                             process.exit(1);
                         }
+                        // Without --devices, cbrowser's own presets, not all few hundred.
                         const deviceList = options.devices
-                            ? options.devices.split(",")
-                            : Object.keys(DEVICE_PRESETS);
+                            ? options.devices.split(",").map((d) => resolveDevicePreset(d))
+                            : [...CBROWSER_DEVICE_KEYS];
                         const concurrency = options.concurrency ? parseInt(options.concurrency) : 3;
                         console.log(`\n🚀 Running parallel device tests...`);
                         console.log(`   URL: ${url}`);
@@ -5862,7 +5906,11 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     });
                     console.log(`\n🔍 Step-through mode enabled. Press Enter to execute each step.\n`);
                     const { CBrowser } = await import("./browser.js");
-                    const stepBrowser = new CBrowser({ headless });
+                    const stepBrowser = new CBrowser({
+                        headless,
+                        ...(typeof options.device === "string" ? { device: options.device } : {}),
+                        ...(viewportOverride ? { viewportWidth: viewportOverride.width, viewportHeight: viewportOverride.height, viewportOverride } : {}),
+                    });
                     await stepBrowser.launch();
                     try {
                         const totalSteps = suite.tests.reduce((sum, t) => sum + t.steps.length, 0);
@@ -5943,6 +5991,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                     continueOnFailure: options["continue-on-failure"] === true,
                     screenshotOnFailure: options["screenshot-on-failure"] !== false,
                     headless,
+                    device: typeof options.device === "string" ? options.device : undefined,
+                    viewport: viewportOverride,
                     fuzzyMatch: options["fuzzy-match"] === true,
                     capture: buildAutoCaptureSetting(options, `test-suite-${suite.name.replace(/[^a-zA-Z0-9-_]+/g, "-").toLowerCase()}-${Date.now()}`),
                 };
@@ -6517,6 +6567,8 @@ Documentation: https://github.com/alexandriashai/cbrowser/wiki
                         maxTime,
                         verbose,
                         headless,
+                        device: typeof options.device === "string" ? options.device : undefined,
+                        viewport: viewportOverride,
                         vision,
                         customTraits, // Pass custom traits from env var
                         location: locationOverride, // Pass location override