browser-debugger-cli 0.7.1 → 0.8.0

package/README.md

@@ -9,7 +9,7 @@ Chrome DevTools Protocol in your terminal. Opens a persistent connection to Chro
 
 ## Why bdg?
 
-- **Raw CDP access** - All [644 protocol methods](https://chromedevtools.github.io/devtools-protocol/) available directly
+- **Raw CDP access** - Every [protocol method](https://chromedevtools.github.io/devtools-protocol/) available directly
 - **Token efficient** - No overhead from MCP tool definitions; progressive discovery loads only what's needed
 - **Self-correcting** - Errors clearly exposed with semantic exit codes and suggestions
 - **Composable** - Unix philosophy: pipes, jq, shell scripts work naturally
@@ -33,9 +33,11 @@ We benchmarked bdg against Chrome DevTools MCP Server on real developer debuggin
 ## Install
 
 ```bash
-npm install -g browser-debugger-cli@alpha
+npm install -g browser-debugger-cli
 ```
 
+**Requirements:** Node.js 22.12+ and Chrome (or Chromium).
+
 **Platform Support:**
 - ✅ macOS and Linux
 - ✅ Windows via WSL
@@ -50,25 +52,31 @@ bdg https://localhost:5173 --chrome-flags="--disable-web-security"       # Disab
 bdg cdp --search cookie            # Discover commands
 bdg cdp Network.getCookies         # Run any CDP method
 bdg dom query "button"             # High-level helpers
+bdg dom fill 'input[name="q"]' "shoes"
+bdg dom click 'button:has-text("Search")'
+bdg page navigate example.com/about
+bdg eval "document.title"          # Run JavaScript in the page (--frame for iframes)
+bdg network list --preset errors   # Network requests, console: bdg console
+bdg dom listeners "#save"          # Which event listeners run for an element
 bdg stop                           # End session
 ```
 
 ## Current State
 
-**Raw CDP access is complete.** All 644 protocol methods (53 domains) work now. High-level wrappers (`bdg dom`, `bdg network`) are being added for common operations. See [Commands](https://github.com/szymdzum/browser-debugger-cli/wiki/Commands) for full reference.
+**Raw CDP access is complete.** Every protocol method works now. High-level commands cover the common work: page navigation, DOM queries and interaction (click, fill, hover, keys, forms, shadow DOM and iframes), accessibility tree, screenshots, network requests and HAR export, console messages and event listeners. See the [CLI reference](docs/CLI_REFERENCE.md) for every command, and `bdg --help --json` for the machine-readable version.
 
 ## Agent Discovery Pattern
 
 ```bash
 # Agent explores what's possible (no docs needed)
-bdg cdp --list                              # 53 domains
-bdg cdp Network --list                      # 39 methods
+bdg cdp --list                              # All domains
+bdg cdp Network --list                      # Methods in one domain
 bdg cdp Network.getCookies --describe       # Full schema + examples
 bdg cdp Network.getCookies                  # Execute
 
 # Search across all domains
 bdg cdp --search screenshot                 # Find relevant methods
-bdg cdp --search cookie                     # 14 results
+bdg cdp --search cookie                     # methods mentioning cookies
 ```
 
 ## Documentation

package/dist/cdp/protocol.d.ts

@@ -20,7 +20,7 @@ import type { ProtocolSchema, Domain, Command } from './types.js';
  * ```typescript
  * const protocol = loadProtocol();
  * console.log(`Protocol version: ${protocol.version.major}.${protocol.version.minor}`);
- * console.log(`Domains: ${protocol.domains.length}`); // ~53 domains (47 browser + 6 JS)
+ * console.log(`Domains: ${protocol.domains.length}`); // browser + JS domains
  * ```
  */
 export declare function loadProtocol(): ProtocolSchema;

package/dist/cdp/protocol.js

@@ -24,7 +24,7 @@ let cachedProtocol = null;
  * ```typescript
  * const protocol = loadProtocol();
  * console.log(`Protocol version: ${protocol.version.major}.${protocol.version.minor}`);
- * console.log(`Domains: ${protocol.domains.length}`); // ~53 domains (47 browser + 6 JS)
+ * console.log(`Domains: ${protocol.domains.length}`); // browser + JS domains
  * ```
  */
 export function loadProtocol() {

package/dist/cdp/schema.d.ts

@@ -141,6 +141,16 @@ export declare function getDomainSummary(domainName: string): DomainSummary | un
  * ```
  */
 export declare function getAllDomainSummaries(): DomainSummary[];
+/**
+ * Domain and method counts of the bundled protocol (for help text).
+ *
+ * @returns Number of domains, of methods overall, and of methods per domain
+ */
+export declare function getProtocolCounts(): {
+    domains: number;
+    methods: number;
+    methodsIn: (domain: string) => number;
+};
 /**
  * Search methods by keyword (case-insensitive).
  *

package/dist/cdp/schema.js

@@ -220,6 +220,19 @@ export function getAllDomainSummaries() {
     const protocol = loadProtocol();
     return protocol.domains.map(buildDomainSummary);
 }
+/**
+ * Domain and method counts of the bundled protocol (for help text).
+ *
+ * @returns Number of domains, of methods overall, and of methods per domain
+ */
+export function getProtocolCounts() {
+    const summaries = getAllDomainSummaries();
+    return {
+        domains: summaries.length,
+        methods: summaries.reduce((total, domain) => total + domain.commandCount, 0),
+        methodsIn: (domain) => summaries.find((d) => d.name === domain)?.commandCount ?? 0,
+    };
+}
 /**
  * Search methods by keyword (case-insensitive).
  *

package/dist/commands/cdp.js

@@ -1,9 +1,11 @@
 import { normalizeMethod } from '../cdp/protocol.js';
-import { getAllDomainSummaries, getDomainMethods, getDomainSummary, getMethodSchema, } from '../cdp/schema.js';
-import { runCommand } from '../commands/shared/CommandRunner.js';
+import { getAllDomainSummaries, getDomainMethods, getProtocolCounts, getDomainSummary, getMethodSchema, } from '../cdp/schema.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { CommandError } from '../errors/index.js';
 import { callCDP } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
-import { CommandError } from '../ui/errors/index.js';
+import { formatHint } from '../ui/messages/hints.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
@@ -23,12 +25,19 @@ const DOMAIN_NOTES = {
     Tracing: 'Performance tracing. Call Tracing.start, perform actions, then Tracing.end. ' +
         'Data arrives via Tracing.dataCollected events.',
 };
+/**
+ * Domain and method counts of the bundled protocol, for the help text.
+ *
+ * @returns e.g. "59 domains, 675 methods"
+ */
+function cdpCountsText() {
+    const counts = getProtocolCounts();
+    return `${counts.domains} domains, ${counts.methods} methods`;
+}
 /**
  * Method-specific notes for methods with non-obvious behavior.
  */
 const METHOD_NOTES = {
-    'Audits.checkContrast': 'This method triggers contrast analysis but results are sent via Audits.issueAdded events. ' +
-        'Alternative: bdg dom eval with getComputedStyle() for direct contrast checking.',
     'Audits.enable': 'Enables the Audits domain. Issues will arrive via Audits.issueAdded events.',
     'Overlay.highlightNode': 'Highlights a node visually. Returns empty on success. Use Overlay.hideHighlight to clear.',
     'Profiler.start': 'Starts CPU profiling. Returns empty. Call Profiler.stop to get the profile data.',
@@ -76,7 +85,7 @@ function getMethodHint(methodName, result) {
 export function registerCdpCommand(program) {
     program
         .command('cdp')
-        .description('CDP protocol introspection and execution (53 domains, 300+ methods)\n' +
+        .description('CDP protocol introspection and execution\n' +
         '  Discovery: --list, --search, --describe\n' +
         '  Execution: case-insensitive (network.getcookies works)')
         .argument('[method]', 'CDP method name (e.g., Network.getCookies, network.getcookies)')
@@ -84,10 +93,12 @@ export function registerCdpCommand(program) {
         .option('--list', 'List all domains or methods in a domain')
         .option('--describe', 'Show method signature and parameters')
         .option('--search <query>', 'Search methods by keyword')
+        .addOption(jsonOption().hideHelp())
+        .addHelpText('after', () => `\nBundled protocol: ${cdpCountsText()}`)
         .action(async (method, options) => {
         await runCommand(async (opts) => {
             if (opts.search) {
-                return await handleSearch(opts.search);
+                return await handleSearch(opts.search, method);
             }
             if (opts.list && !method) {
                 return handleListDomains();
@@ -135,15 +146,46 @@ function findSimilarMethods(methodName, domain) {
         caseInsensitive: true,
     });
 }
+/**
+ * Did-you-mean for an unknown domain, or how to list them.
+ *
+ * @param domainName - Domain as typed
+ * @returns Suggestion
+ */
+function domainSuggestion(domainName) {
+    const [closest] = findSimilar(domainName, getAllDomainSummaries().map((summary) => summary.name));
+    return closest
+        ? `Did you mean: bdg cdp ${closest} --list?`
+        : 'Use: bdg cdp --list (to see all domains)';
+}
+/**
+ * For a method bdg refuses to run, what to use instead (shown as its example).
+ *
+ * @param methodName - Full method name, e.g. Page.captureScreenshot
+ * @returns Alternative command, or undefined for methods that run
+ */
+function blockedAlternative(methodName) {
+    const blocked = BLOCKED_CDP_METHODS[methodName];
+    return blocked && `${blocked.alternative} (raw ${methodName} is blocked)`;
+}
 /**
  * Handle search mode: Find methods by keyword.
  *
  * @param query - Search query
+ * @param domain - Domain to search in (`bdg cdp Network --search cookie`)
  * @returns Success result with matching methods
  */
-async function handleSearch(query) {
+async function handleSearch(query, domain) {
+    if (domain !== undefined && !getDomainSummary(domain)) {
+        return {
+            success: false,
+            error: `Domain '${domain}' not found`,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: domainSuggestion(domain) },
+        };
+    }
     const { searchMethods } = await import('../cdp/schema.js');
-    const results = searchMethods(query);
+    const results = searchMethods(query).filter((m) => domain === undefined || m.domain.toLowerCase() === domain.toLowerCase());
     return {
         success: true,
         data: {
@@ -157,7 +199,7 @@ async function handleSearch(query) {
                 experimental: m.experimental,
                 deprecated: m.deprecated,
                 parameterCount: m.parameters.length,
-                example: m.example?.command,
+                example: blockedAlternative(m.name) ?? m.example?.command,
             })),
         },
     };
@@ -199,7 +241,7 @@ function handleListDomainMethods(domainName) {
             error: `Domain '${domainName}' not found`,
             exitCode: EXIT_CODES.INVALID_ARGUMENTS,
             errorContext: {
-                suggestion: 'Use: bdg cdp --list (to see all domains)',
+                suggestion: domainSuggestion(domainName),
             },
         };
     }
@@ -226,7 +268,7 @@ function handleListDomainMethods(domainName) {
                     name: r.name,
                     type: r.type,
                 })),
-                example: m.example?.command,
+                example: blockedAlternative(m.name) ?? m.example?.command,
             })),
         },
     };
@@ -322,19 +364,29 @@ function handleDescribeMethod(methodName) {
                 description: r.description,
                 items: r.items,
             })),
-            example: schema.example,
+            example: blockedAlternative(schema.name)
+                ? { command: blockedAlternative(schema.name) }
+                : schema.example,
         },
     };
 }
 /**
- * CDP methods blocked from raw execution due to output issues.
- * These methods return large binary data that corrupts terminal/agent sessions.
+ * CDP methods blocked from raw execution: they return large binary data that
+ * corrupts terminal/agent sessions, or end the session behind bdg's back.
  */
 const BLOCKED_CDP_METHODS = {
     'Page.captureScreenshot': {
         alternative: 'bdg dom screenshot [path]',
         reason: 'Returns large base64 data that corrupts terminal sessions',
     },
+    'Page.close': {
+        alternative: 'bdg stop',
+        reason: 'Closes the page under the session, which then ends',
+    },
+    'Browser.close': {
+        alternative: 'bdg stop',
+        reason: 'Closes Chrome under the session, which then ends without saving its state',
+    },
 };
 /**
  * Handle execute method mode: Call CDP method.
@@ -345,14 +397,14 @@ const BLOCKED_CDP_METHODS = {
  */
 async function handleExecuteMethod(methodName, paramsJson) {
     const normalized = normalizeMethod(methodName);
-    // Block methods that return large binary data
-    // Output error to stderr only and exit - no JSON output to avoid confusing pipelines
     if (normalized && BLOCKED_CDP_METHODS[normalized]) {
         const blocked = BLOCKED_CDP_METHODS[normalized];
-        console.error(`Error: ${normalized} is blocked via raw CDP`);
-        console.error(`Reason: ${blocked.reason}`);
-        console.error(`Use: ${blocked.alternative}`);
-        process.exit(1);
+        return {
+            success: false,
+            error: `${normalized} is blocked via raw CDP: ${blocked.reason}`,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: `Use: ${blocked.alternative}` },
+        };
     }
     if (!normalized) {
         const similar = findSimilarMethods(methodName);
@@ -379,7 +431,7 @@ async function handleExecuteMethod(methodName, paramsJson) {
         catch (error) {
             return {
                 success: false,
-                error: `Error parsing --params: ${getErrorMessage(error)}. Parameters must be valid JSON.`,
+                error: `Invalid --params JSON: ${getErrorMessage(error)}`,
                 exitCode: EXIT_CODES.INVALID_ARGUMENTS,
                 errorContext: {
                     suggestion: `Use: bdg cdp ${normalized} --describe (to see parameter schema)`,
@@ -398,7 +450,7 @@ async function handleExecuteMethod(methodName, paramsJson) {
         },
     };
     if (response.data?.hint) {
-        result.hint = response.data.hint;
+        result.hint = formatHint(response.data.hint);
     }
     const methodHint = getMethodHint(normalized, cdpResult);
     if (methodHint) {

package/dist/commands/cleanup.js

@@ -1,11 +1,14 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
-import { performSessionCleanup } from '../session/cleanup.js';
-import { readPid } from '../session/pid.js';
+import * as fs from 'fs';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { sessionDirIsFileError } from '../errors/messages.js';
+import { performSessionCleanup } from '../session/cleanup/userCommands.js';
+import { isDaemonAlive } from '../session/daemonSocket.js';
+import { getSessionDir } from '../session/paths.js';
+import { readDaemonPid } from '../session/pid.js';
 import { joinLines } from '../ui/formatting.js';
 import { sessionFilesCleanedMessage, sessionOutputRemovedMessage, sessionDirectoryCleanMessage, noSessionFilesMessage, sessionStillActiveError, warningMessage, } from '../ui/messages/commands.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
-import { isProcessAlive } from '../utils/process.js';
 /**
  * Format cleanup result for human-readable output.
  *
@@ -24,30 +27,35 @@ export function registerCleanupCommand(program) {
     program
         .command('cleanup')
         .description('Clean up stale session files')
-        .option('-f, --force', 'Force cleanup even if session appears active', false)
+        .option('-f, --force', 'Kill a running (possibly hung) session, then clean up', false)
         .option('--remove-output', 'Also remove session.json output file', false)
-        .option('--aggressive', 'Kill orphaned daemon processes and all stale Chrome instances', false)
+        .option('--aggressive', 'Alias for --force (kept for compatibility)', false)
         .addOption(jsonOption())
         .action(async (options) => {
         await runCommand(async (opts) => {
-            const pid = readPid();
-            if (pid) {
-                const isAlive = isProcessAlive(pid);
-                if (isAlive && !opts.force) {
-                    return {
-                        success: false,
-                        error: sessionStillActiveError(pid),
-                        exitCode: EXIT_CODES.RESOURCE_BUSY,
-                        errorContext: {
-                            suggestion: 'Stop gracefully: bdg stop\nForce cleanup: bdg cleanup --force',
-                            warning: 'Force cleanup will remove session files but will NOT kill the running process',
-                        },
-                    };
-                }
+            const dir = getSessionDir();
+            if (fs.existsSync(dir) && !fs.statSync(dir).isDirectory()) {
+                const err = sessionDirIsFileError(dir);
+                return {
+                    success: false,
+                    error: err.message,
+                    exitCode: EXIT_CODES.SESSION_FILE_ERROR,
+                    errorContext: { suggestion: err.suggestion },
+                };
+            }
+            if (!opts.force && !opts.aggressive && (await isDaemonAlive())) {
+                return {
+                    success: false,
+                    error: sessionStillActiveError(readDaemonPid() ?? 0),
+                    exitCode: EXIT_CODES.RESOURCE_BUSY,
+                    errorContext: {
+                        suggestion: 'Stop gracefully: bdg stop\nForce cleanup: bdg cleanup --force',
+                        warning: 'Force cleanup kills the running daemon and its Chrome',
+                    },
+                };
             }
             const cleanupResult = await performSessionCleanup({
-                force: opts.force,
-                aggressive: opts.aggressive,
+                force: Boolean(opts.force) || Boolean(opts.aggressive),
                 removeOutput: opts.removeOutput,
             });
             const didCleanup = cleanupResult.cleaned.session ||

package/dist/commands/console.d.ts

@@ -4,7 +4,24 @@
 import { type Command } from 'commander';
 import type { ConsoleMessage } from '../types.js';
 import { type ConsoleLevel } from '../ui/formatters/console.js';
-export declare function filterByCurrentNavigation(messages: ConsoleMessage[]): ConsoleMessage[];
+/**
+ * Keep the messages of the page currently loaded.
+ *
+ * @param messages - All captured messages
+ * @param currentNavigationId - Navigation id of the current page; when unknown,
+ *   the newest navigation id among the messages is used
+ * @returns Messages of the current page (empty if it logged nothing)
+ */
+export declare function filterByCurrentNavigation(messages: ConsoleMessage[], currentNavigationId?: number): ConsoleMessage[];
 export declare function filterByLevel(messages: ConsoleMessage[], level: ConsoleLevel): ConsoleMessage[];
+/**
+ * Identity of each message across polls (its index can shift when an earlier
+ * message is inserted late). Identical messages logged in the same
+ * millisecond are told apart by their order.
+ *
+ * @param messages - Messages in order
+ * @returns One key per message
+ */
+export declare function messageKeys(messages: ConsoleMessage[]): string[];
 export declare function registerConsoleCommand(program: Command): void;
 //# sourceMappingURL=console.d.ts.map

package/dist/commands/console.js

@@ -2,61 +2,41 @@
  * Console command for inspecting and filtering console messages.
  */
 import { Option } from 'commander';
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
-import { handleDaemonConnectionError } from '../commands/shared/daemonErrorHandler.js';
-import { fetchConsoleMessages, createErrorResult } from '../commands/shared/dataFetcher.js';
-import { setupFollowMode } from '../commands/shared/followMode.js';
-import { positiveIntRule } from '../commands/shared/validation.js';
-import { OutputBuilder } from '../ui/OutputBuilder.js';
-import { CommandError } from '../ui/errors/index.js';
-import { formatConsole, formatConsoleFollow, LEVEL_MAP, } from '../ui/formatters/console.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { handleDaemonConnectionError, noteFollowConnected, } from './shared/daemonErrorHandler.js';
+import { fetchConsoleMessages, createErrorResult } from './shared/dataFetcher.js';
+import { setupFollowMode } from './shared/followMode.js';
+import { handleValidationError } from './shared/handleValidationError.js';
+import { consoleLevelOption, positiveIntRule } from './shared/validation.js';
+import { buildSuccessResponse } from '../ui/OutputBuilder.js';
+import { buildConsoleJsonOutput, formatConsole, formatConsoleFollowLines, LEVEL_MAP, } from '../ui/formatters/console.js';
 import { followingConsoleMessage, stoppedFollowingConsoleMessage, } from '../ui/messages/consoleMessages.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
 const MIN_LAST = 0;
 const MAX_LAST = 10000;
 const DEFAULT_LAST = 100;
-const FOLLOW_LIMIT = 20;
-const VALID_LEVELS = ['error', 'warning', 'info', 'debug'];
-const consoleLastOption = new Option('--last <n>', `Show last N console messages (0 = all, default: ${DEFAULT_LAST})`).default(String(DEFAULT_LAST));
+const consoleLastOption = new Option('--last <n>', 'Show last N console messages (0 = all)').default(String(DEFAULT_LAST));
 /**
- * Handle validation errors with proper JSON/human formatting.
+ * Keep the messages of the page currently loaded.
  *
- * @param error - Error from validation
- * @param json - Whether to output JSON format
+ * @param messages - All captured messages
+ * @param currentNavigationId - Navigation id of the current page; when unknown,
+ *   the newest navigation id among the messages is used
+ * @returns Messages of the current page (empty if it logged nothing)
  */
-function handleValidationError(error, json) {
-    if (error instanceof CommandError) {
-        if (json) {
-            const errorOptions = {
-                exitCode: error.exitCode,
-            };
-            if (error.metadata.suggestion) {
-                errorOptions.suggestion = error.metadata.suggestion;
-            }
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, errorOptions)));
-        }
-        else {
-            console.error(error.message);
-            if (error.metadata.suggestion)
-                console.error(error.metadata.suggestion);
-        }
-        process.exit(error.exitCode);
-    }
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
-}
-export function filterByCurrentNavigation(messages) {
+export function filterByCurrentNavigation(messages, currentNavigationId) {
     if (messages.length === 0)
         return messages;
-    const maxNavId = Math.max(...messages.map((m) => m.navigationId ?? 0));
-    return messages.filter((m) => m.navigationId === maxNavId);
+    const navId = currentNavigationId ?? Math.max(...messages.map((m) => m.navigationId ?? 0));
+    return messages.filter((m) => (m.navigationId ?? 0) === navId);
 }
 export function filterByLevel(messages, level) {
     return messages.filter((m) => LEVEL_MAP[m.type] === level);
 }
-function applyFilters(messages, options) {
-    let filtered = options.history ? messages : filterByCurrentNavigation(messages);
+function applyFilters(messages, options, currentNavigationId) {
+    let filtered = options.history
+        ? messages
+        : filterByCurrentNavigation(messages, currentNavigationId);
     if (options.level)
         filtered = filterByLevel(filtered, options.level);
     return filtered;
@@ -71,7 +51,17 @@ function buildFormatOptions(options, lastN) {
         level: options.level,
     };
 }
-async function runFollowMode(options) {
+/**
+ * Stream console messages: the last `lastN` at start, then each new message
+ * once (like `tail -f`), with a separator when the page navigates.
+ *
+ * @param options - Command options
+ * @param lastN - Messages to show at start (0 = all)
+ */
+async function runFollowMode(options, lastN) {
+    const shown = new Set();
+    let navigationId;
+    let started = false;
     const showConsole = async () => {
         const result = await fetchConsoleMessages();
         if (!result.success) {
@@ -85,9 +75,32 @@ async function runFollowMode(options) {
                 process.exit(errorResult.exitCode);
             return;
         }
-        const filtered = applyFilters(result.data, options);
-        console.clear();
-        console.log(formatConsoleFollow(filtered.slice(-FOLLOW_LIMIT)));
+        noteFollowConnected();
+        const { messages, currentNavigationId } = result.data;
+        const matching = applyFilters(messages, options, currentNavigationId);
+        const keys = messageKeys(matching);
+        const fresh = matching.filter((_message, i) => !shown.has(keys[i]));
+        const backlog = started || lastN === 0 ? fresh : fresh.slice(-lastN);
+        shown.clear();
+        keys.forEach((key) => shown.add(key));
+        const navigated = started && navigationId !== currentNavigationId;
+        navigationId = currentNavigationId;
+        if (options.json) {
+            if (!started || backlog.length > 0) {
+                const data = buildConsoleJsonOutput(backlog, { list: true, last: 0 });
+                console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
+            }
+        }
+        else {
+            const text = formatConsoleFollowLines(backlog, {
+                header: !started,
+                ...(navigated &&
+                    currentNavigationId !== undefined && { navigationId: currentNavigationId }),
+            });
+            if (text)
+                console.log(text);
+        }
+        started = true;
     };
     await setupFollowMode(showConsole, {
         startMessage: followingConsoleMessage,
@@ -95,6 +108,23 @@ async function runFollowMode(options) {
         intervalMs: 1000,
     });
 }
+/**
+ * Identity of each message across polls (its index can shift when an earlier
+ * message is inserted late). Identical messages logged in the same
+ * millisecond are told apart by their order.
+ *
+ * @param messages - Messages in order
+ * @returns One key per message
+ */
+export function messageKeys(messages) {
+    const seen = new Map();
+    return messages.map((message) => {
+        const base = `${message.timestamp}|${message.type}|${message.navigationId ?? ''}|${message.text}`;
+        const occurrence = (seen.get(base) ?? 0) + 1;
+        seen.set(base, occurrence);
+        return `${base}#${occurrence}`;
+    });
+}
 export function registerConsoleCommand(program) {
     program
         .command('console')
@@ -102,29 +132,44 @@ export function registerConsoleCommand(program) {
         .addOption(new Option('-l, --list', 'List all messages chronologically').default(false))
         .addOption(new Option('-f, --follow', 'Stream console messages in real-time').default(false))
         .addOption(new Option('-H, --history', 'Show messages from all page loads (default: current only)').default(false))
-        .addOption(new Option('--level <level>', 'Filter by message level (error, warning, info, debug)').choices(VALID_LEVELS))
+        .addOption(new Option('--level <level>', 'Filter by message level: error, warning, info (includes log), debug; any case').argParser(consoleLevelOption))
         .addOption(consoleLastOption)
         .addOption(jsonOption())
         .action(async (options) => {
         let lastN;
         try {
-            lastN = positiveIntRule({ min: MIN_LAST, max: MAX_LAST, default: DEFAULT_LAST }).validate(options.last);
+            lastN = positiveIntRule({
+                name: '--last',
+                min: MIN_LAST,
+                max: MAX_LAST,
+                default: DEFAULT_LAST,
+            }).validate(options.last);
         }
         catch (error) {
             handleValidationError(error, options.json ?? false);
         }
         if (options.follow) {
-            await runFollowMode(options);
+            await runFollowMode(options, lastN);
             return;
         }
         await runCommand(async () => {
             const result = await fetchConsoleMessages();
             if (!result.success) {
-                return createErrorResult(result.error, result.exitCode);
+                return createErrorResult(result.error, result.exitCode, result.suggestion);
+            }
+            const { messages, currentNavigationId } = result.data;
+            const filtered = applyFilters(messages, options, currentNavigationId);
+            if (options.json) {
+                return {
+                    success: true,
+                    data: buildConsoleJsonOutput(filtered, buildFormatOptions(options, lastN)),
+                };
             }
-            const filtered = applyFilters(result.data, options);
-            return { success: true, data: { messages: result.data, filtered } };
-        }, options, (data) => formatConsole(data.filtered, buildFormatOptions(options, lastN)));
+            return { success: true, data: { messages, filtered } };
+        }, options, (data) => {
+            const { filtered } = data;
+            return formatConsole(filtered, buildFormatOptions(options, lastN));
+        });
     });
 }
 //# sourceMappingURL=console.js.map