browser-debugger-cli 0.8.0 → 0.9.0

package/README.md

@@ -58,12 +58,15 @@ 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 dom layout "#save"             # Where it is, whether it is visible or covered
+bdg dom wait "#result" --visible   # Wait for an element instead of sleeping
+bdg example.com --session agent2 --viewport 1280x800   # A second, independent session
 bdg stop                           # End session
 ```
 
 ## Current State
 
-**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.
+**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. Actions report what they changed (navigation, new messages, requests, or no visible effect), and several named sessions can run side by side. See the [CLI reference](docs/CLI_REFERENCE.md) for every command, and `bdg --help --json` for the machine-readable version.
 
 ## Agent Discovery Pattern
 

package/dist/cdp/schema.d.ts

@@ -154,7 +154,9 @@ export declare function getProtocolCounts(): {
 /**
  * Search methods by keyword (case-insensitive).
  *
- * Searches in method names and descriptions.
+ * Searches method names, extra keywords ({@link SEARCH_KEYWORDS}) and
+ * descriptions. Matches by name or keyword come first, then those found only
+ * in the description, each in protocol order.
  *
  * @param query - Search query
  * @returns Array of matching method schemas
@@ -163,6 +165,7 @@ export declare function getProtocolCounts(): {
  * ```typescript
  * const cookies = searchMethods('cookie');
  * // Returns: Network.getCookies, Network.setCookie, Network.deleteCookies, etc.
+ * searchMethods('viewport')[0]?.name; // 'Emulation.setDeviceMetricsOverride'
  * ```
  */
 export declare function searchMethods(query: string): MethodSchema[];

package/dist/cdp/schema.js

@@ -233,10 +233,45 @@ export function getProtocolCounts() {
         methodsIn: (domain) => summaries.find((d) => d.name === domain)?.commandCount ?? 0,
     };
 }
+/**
+ * Words agents search for that a method's name and description lack, e.g.
+ * "viewport" for `Emulation.setDeviceMetricsOverride`.
+ */
+const SEARCH_KEYWORDS = {
+    'Emulation.setDeviceMetricsOverride': [
+        'viewport',
+        'window size',
+        'screen size',
+        'resize',
+        'responsive',
+        'mobile',
+    ],
+    'Emulation.setEmulatedMedia': [
+        'color scheme',
+        'dark mode',
+        'light mode',
+        'prefers-color-scheme',
+        'reduced motion',
+        'print',
+    ],
+    'Browser.setWindowBounds': ['window size', 'resize'],
+};
+/**
+ * Lower-case text without spaces, hyphens and underscores, so "user agent"
+ * finds `setUserAgentOverride`.
+ *
+ * @param text - Text
+ * @returns Normalized text
+ */
+function searchable(text) {
+    return text.toLowerCase().replace(/[\s_-]+/g, '');
+}
 /**
  * Search methods by keyword (case-insensitive).
  *
- * Searches in method names and descriptions.
+ * Searches method names, extra keywords ({@link SEARCH_KEYWORDS}) and
+ * descriptions. Matches by name or keyword come first, then those found only
+ * in the description, each in protocol order.
  *
  * @param query - Search query
  * @returns Array of matching method schemas
@@ -245,23 +280,29 @@ export function getProtocolCounts() {
  * ```typescript
  * const cookies = searchMethods('cookie');
  * // Returns: Network.getCookies, Network.setCookie, Network.deleteCookies, etc.
+ * searchMethods('viewport')[0]?.name; // 'Emulation.setDeviceMetricsOverride'
  * ```
  */
 export function searchMethods(query) {
     const protocol = loadProtocol();
-    const results = [];
+    const named = [];
+    const described = [];
     const lowerQuery = query.toLowerCase();
+    const needle = searchable(query);
     protocol.domains.forEach((domain) => {
         if (!domain.commands)
             return;
         domain.commands.forEach((command) => {
-            const nameMatch = command.name.toLowerCase().includes(lowerQuery);
+            const keywords = SEARCH_KEYWORDS[`${domain.domain}.${command.name}`] ?? [];
+            const nameMatch = searchable(command.name).includes(needle) ||
+                keywords.some((keyword) => searchable(keyword).includes(needle));
             const descMatch = command.description?.toLowerCase().includes(lowerQuery) ?? false;
-            if (nameMatch || descMatch) {
-                results.push(buildMethodSchema(domain.domain, command));
-            }
+            if (nameMatch)
+                named.push(buildMethodSchema(domain.domain, command));
+            else if (descMatch)
+                described.push(buildMethodSchema(domain.domain, command));
         });
     });
-    return results;
+    return [...named, ...described];
 }
 //# sourceMappingURL=schema.js.map

package/dist/commands/cdp.js

@@ -6,6 +6,7 @@ import { CommandError } from '../errors/index.js';
 import { callCDP } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
 import { formatHint } from '../ui/messages/hints.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
@@ -166,7 +167,7 @@ function domainSuggestion(domainName) {
  */
 function blockedAlternative(methodName) {
     const blocked = BLOCKED_CDP_METHODS[methodName];
-    return blocked && `${blocked.alternative} (raw ${methodName} is blocked)`;
+    return blocked && `${sessionCommand(blocked.alternative)} (raw ${methodName} is blocked)`;
 }
 /**
  * Handle search mode: Find methods by keyword.
@@ -403,7 +404,7 @@ async function handleExecuteMethod(methodName, paramsJson) {
             success: false,
             error: `${normalized} is blocked via raw CDP: ${blocked.reason}`,
             exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-            errorContext: { suggestion: `Use: ${blocked.alternative}` },
+            errorContext: { suggestion: `Use: ${sessionCommand(blocked.alternative)}` },
         };
     }
     if (!normalized) {

package/dist/commands/cleanup.d.ts

@@ -1,4 +1,15 @@
 import type { Command } from 'commander';
+import { type ErrorWithSuggestion } from '../errors/messages.js';
+/**
+ * Why the session directory must not be deleted after cleanup: its daemon
+ * still runs, cleanup reported problems, or its Chrome has not exited.
+ *
+ * @param chromePid - The session's Chrome as found before cleanup, or null
+ * @param warnings - Warnings from cleanup
+ * @param exitWaitMs - How long to wait for that Chrome to exit
+ * @returns Error and suggestion, or null when the directory may be deleted
+ */
+export declare function purgeBlocker(chromePid: number | null, warnings: string[], exitWaitMs?: number): Promise<ErrorWithSuggestion | null>;
 /**
  * Register cleanup command
  *

package/dist/commands/cleanup.js

@@ -1,14 +1,17 @@
 import * as fs from 'fs';
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
-import { sessionDirIsFileError } from '../errors/messages.js';
+import { purgeNeedsNamedSessionError, purgeRefusedError, sessionDirIsFileError, } from '../errors/messages.js';
+import { isSessionChrome } from '../session/cleanup/staleSession.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 { getSessionDir, getSessionFilePath, getSessionName } from '../session/paths.js';
+import { readDaemonPid, readPidFromFile } from '../session/pid.js';
 import { joinLines } from '../ui/formatting.js';
-import { sessionFilesCleanedMessage, sessionOutputRemovedMessage, sessionDirectoryCleanMessage, noSessionFilesMessage, sessionStillActiveError, warningMessage, } from '../ui/messages/commands.js';
+import { sessionFilesCleanedMessage, sessionOutputRemovedMessage, sessionDirectoryCleanMessage, sessionDirectoryPurgedMessage, noSessionFilesMessage, sessionStillActiveError, sessionStillActiveSuggestion, warningMessage, } from '../ui/messages/commands.js';
+import { delay } from '../utils/async.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { isProcessAlive } from '../utils/process.js';
 /**
  * Format cleanup result for human-readable output.
  *
@@ -18,6 +21,158 @@ function formatCleanup(data) {
     const { cleaned } = data;
     return joinLines(cleaned.session && sessionFilesCleanedMessage(), cleaned.output && sessionOutputRemovedMessage(), ...(data.warnings ?? []).map((warning) => warningMessage(warning)), '', data.message);
 }
+/**
+ * Delete the selected named session's directory (Chrome profile, logs, port).
+ *
+ * @returns The deleted directory, or undefined if there was none
+ */
+function purgeSessionDir() {
+    const dir = getSessionDir();
+    if (!fs.existsSync(dir))
+        return undefined;
+    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+    return dir;
+}
+/** How long `--purge` waits for a killed Chrome to exit */
+const PURGE_CHROME_EXIT_WAIT_MS = 5000;
+/**
+ * The running Chrome bdg launched for the selected session (from chrome.pid,
+ * verified by its marker flag).
+ *
+ * @returns Chrome PID, or null
+ */
+function liveSessionChromePid() {
+    const pid = readPidFromFile(getSessionFilePath('CHROME_PID'));
+    if (pid === null || !isProcessAlive(pid))
+        return null;
+    return isSessionChrome(pid, getSessionDir()) ? pid : null;
+}
+/**
+ * Wait until a process has exited.
+ *
+ * @param pid - Process ID
+ * @param timeoutMs - Longest wait
+ * @returns True if it exited
+ */
+async function waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (isProcessAlive(pid) && Date.now() < deadline)
+        await delay(50);
+    return !isProcessAlive(pid);
+}
+/**
+ * Why the session directory must not be deleted after cleanup: its daemon
+ * still runs, cleanup reported problems, or its Chrome has not exited.
+ *
+ * @param chromePid - The session's Chrome as found before cleanup, or null
+ * @param warnings - Warnings from cleanup
+ * @param exitWaitMs - How long to wait for that Chrome to exit
+ * @returns Error and suggestion, or null when the directory may be deleted
+ */
+export async function purgeBlocker(chromePid, warnings, exitWaitMs = PURGE_CHROME_EXIT_WAIT_MS) {
+    const dir = getSessionDir();
+    if (await isDaemonAlive())
+        return purgeRefusedError(dir, 'its daemon is still running');
+    if (warnings.length > 0)
+        return purgeRefusedError(dir, warnings.join('; '));
+    if (chromePid !== null && !(await waitForExit(chromePid, exitWaitMs))) {
+        return purgeRefusedError(dir, `its Chrome (PID ${chromePid}) is still running`);
+    }
+    return null;
+}
+/**
+ * Delete the session directory unless {@link purgeBlocker} objects.
+ *
+ * @param chromePid - The session's Chrome as found before cleanup, or null
+ * @param warnings - Warnings from cleanup
+ * @returns The deleted directory (undefined if there was none), or the refusal
+ */
+async function purge(chromePid, warnings) {
+    const refusal = await purgeBlocker(chromePid, warnings);
+    if (refusal)
+        return { refusal };
+    const purged = purgeSessionDir();
+    return purged === undefined ? {} : { purged };
+}
+/**
+ * Why cleanup cannot run: the session directory is a file, `--purge` lacks a
+ * named session, or the session is still running (without `--force`).
+ *
+ * @param opts - Cleanup options
+ * @returns Error result, or null when cleanup may run
+ */
+async function cleanupBlocker(opts) {
+    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.purge && getSessionName() === null) {
+        const err = purgeNeedsNamedSessionError();
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            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: sessionStillActiveSuggestion(getSessionName()),
+                warning: 'Force cleanup kills the running daemon and its Chrome',
+            },
+        };
+    }
+    return null;
+}
+/**
+ * Clean up the selected session (and delete its directory with `--purge`).
+ *
+ * @param opts - Cleanup options
+ * @returns Command result
+ */
+async function cleanupSession(opts) {
+    const blocker = await cleanupBlocker(opts);
+    if (blocker)
+        return blocker;
+    const chromePid = opts.purge ? liveSessionChromePid() : null;
+    const { cleaned, warnings } = await performSessionCleanup({
+        force: Boolean(opts.force) || Boolean(opts.aggressive),
+        removeOutput: opts.removeOutput,
+    });
+    const { purged, refusal } = opts.purge ? await purge(chromePid, warnings) : {};
+    if (refusal) {
+        return {
+            success: false,
+            error: refusal.message,
+            exitCode: EXIT_CODES.RESOURCE_CONFLICT,
+            errorContext: { suggestion: refusal.suggestion },
+        };
+    }
+    const didCleanup = Object.values(cleaned).some(Boolean) || purged !== undefined;
+    return {
+        success: true,
+        data: {
+            cleaned,
+            ...(purged !== undefined && { purged }),
+            message: !didCleanup
+                ? noSessionFilesMessage()
+                : purged !== undefined
+                    ? sessionDirectoryPurgedMessage(purged)
+                    : sessionDirectoryCleanMessage(),
+            ...(warnings.length > 0 && { warnings }),
+        },
+    };
+}
 /**
  * Register cleanup command
  *
@@ -30,61 +185,10 @@ export function registerCleanupCommand(program) {
         .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', 'Alias for --force (kept for compatibility)', false)
+        .option('--purge', "Also delete a named session's directory (Chrome profile, logs, port); needs --session", false)
         .addOption(jsonOption())
         .action(async (options) => {
-        await runCommand(async (opts) => {
-            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: Boolean(opts.force) || Boolean(opts.aggressive),
-                removeOutput: opts.removeOutput,
-            });
-            const didCleanup = cleanupResult.cleaned.session ||
-                cleanupResult.cleaned.chrome ||
-                cleanupResult.cleaned.daemons ||
-                cleanupResult.cleaned.output;
-            if (!didCleanup) {
-                return {
-                    success: true,
-                    data: {
-                        cleaned: { session: false, output: false, chrome: false, daemons: false },
-                        message: noSessionFilesMessage(),
-                    },
-                };
-            }
-            return {
-                success: true,
-                data: {
-                    cleaned: {
-                        session: cleanupResult.cleaned.session,
-                        output: cleanupResult.cleaned.output,
-                        chrome: cleanupResult.cleaned.chrome,
-                        daemons: cleanupResult.cleaned.daemons,
-                    },
-                    message: sessionDirectoryCleanMessage(),
-                    ...(cleanupResult.warnings.length > 0 && { warnings: cleanupResult.warnings }),
-                },
-            };
-        }, options, formatCleanup);
+        await runCommand(cleanupSession, options, formatCleanup);
     });
 }
 //# sourceMappingURL=cleanup.js.map

package/dist/commands/console.d.ts

@@ -2,8 +2,17 @@
  * Console command for inspecting and filtering console messages.
  */
 import { type Command } from 'commander';
+import type { ConsoleCommandOptions } from './shared/optionTypes.js';
 import type { ConsoleMessage } from '../types.js';
-import { type ConsoleLevel } from '../ui/formatters/console.js';
+import { type ConsoleLevel, type ConsoleSkipped } from '../ui/formatters/console.js';
+/**
+ * Whether to list the messages instead of summarising them: with `--list`,
+ * and when `--last` asks for a number of them.
+ *
+ * @param options - Command options
+ * @returns True to list
+ */
+export declare function listsMessages(options: Pick<ConsoleCommandOptions, 'list' | 'last'>): boolean;
 /**
  * Keep the messages of the page currently loaded.
  *
@@ -14,6 +23,16 @@ import { type ConsoleLevel } from '../ui/formatters/console.js';
  */
 export declare function filterByCurrentNavigation(messages: ConsoleMessage[], currentNavigationId?: number): ConsoleMessage[];
 export declare function filterByLevel(messages: ConsoleMessage[], level: ConsoleLevel): ConsoleMessage[];
+/**
+ * Messages the filters left out between the first and the last listed
+ * message (their session indices skip them), by why: logged by another page
+ * load, or of another level.
+ *
+ * @param all - All messages of the session
+ * @param listed - Messages listed
+ * @returns Counts per reason
+ */
+export declare function skippedMessages(all: ConsoleMessage[], listed: ConsoleMessage[]): ConsoleSkipped;
 /**
  * Identity of each message across polls (its index can shift when an earlier
  * message is inserted late). Identical messages logged in the same

package/dist/commands/console.js

@@ -4,18 +4,28 @@
 import { Option } from 'commander';
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
-import { handleDaemonConnectionError, noteFollowConnected, } from './shared/daemonErrorHandler.js';
+import { noteFollowConnected } from './shared/daemonErrorHandler.js';
 import { fetchConsoleMessages, createErrorResult } from './shared/dataFetcher.js';
-import { setupFollowMode } from './shared/followMode.js';
+import { followFetchFailure, 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 { buildConsoleJsonOutput, formatConsole, formatConsoleFollowLines, LEVEL_MAP, lastMessages, } from '../ui/formatters/console.js';
 import { followingConsoleMessage, stoppedFollowingConsoleMessage, } from '../ui/messages/consoleMessages.js';
 const MIN_LAST = 0;
 const MAX_LAST = 10000;
 const DEFAULT_LAST = 100;
-const consoleLastOption = new Option('--last <n>', 'Show last N console messages (0 = all)').default(String(DEFAULT_LAST));
+const consoleLastOption = new Option('--last <n>', `List the last N console messages (0 = all; default: ${DEFAULT_LAST} with --list or --follow)`);
+/**
+ * Whether to list the messages instead of summarising them: with `--list`,
+ * and when `--last` asks for a number of them.
+ *
+ * @param options - Command options
+ * @returns True to list
+ */
+export function listsMessages(options) {
+    return options.list === true || options.last !== undefined;
+}
 /**
  * Keep the messages of the page currently loaded.
  *
@@ -41,14 +51,50 @@ function applyFilters(messages, options, currentNavigationId) {
         filtered = filterByLevel(filtered, options.level);
     return filtered;
 }
-function buildFormatOptions(options, lastN) {
+/**
+ * Messages the filters left out between the first and the last listed
+ * message (their session indices skip them), by why: logged by another page
+ * load, or of another level.
+ *
+ * @param all - All messages of the session
+ * @param listed - Messages listed
+ * @returns Counts per reason
+ */
+export function skippedMessages(all, listed) {
+    const shown = new Set(listed.map((message) => message.index));
+    const indices = listed.map((message) => message.index).filter((index) => index !== undefined);
+    const skipped = { otherPages: 0, otherLevels: 0 };
+    if (indices.length < 2)
+        return skipped;
+    const [first, last] = [Math.min(...indices), Math.max(...indices)];
+    const pages = new Set(listed.map((message) => message.navigationId));
+    for (const { index, navigationId } of all) {
+        if (index === undefined || index < first || index > last || shown.has(index))
+            continue;
+        if (pages.has(navigationId))
+            skipped.otherLevels++;
+        else
+            skipped.otherPages++;
+    }
+    return skipped;
+}
+/**
+ * Formatting options from the command options.
+ *
+ * @param options - Command options
+ * @param lastN - `--last` value
+ * @param skipped - Messages the filters left out between the listed ones
+ * @returns Formatting options
+ */
+function buildFormatOptions(options, lastN, skipped) {
     return {
         json: options.json,
-        list: options.list,
+        list: listsMessages(options),
         follow: options.follow,
         last: lastN,
         history: options.history,
         level: options.level,
+        skipped,
     };
 }
 /**
@@ -65,15 +111,7 @@ async function runFollowMode(options, lastN) {
     const showConsole = async () => {
         const result = await fetchConsoleMessages();
         if (!result.success) {
-            const errorResult = handleDaemonConnectionError(result.error, {
-                json: options.json,
-                follow: true,
-                retryIntervalMs: 1000,
-                exitCode: result.exitCode,
-            });
-            if (errorResult.shouldExit)
-                process.exit(errorResult.exitCode);
-            return;
+            return followFetchFailure(result, { json: options.json, retryIntervalMs: 1000 });
         }
         noteFollowConnected();
         const { messages, currentNavigationId } = result.data;
@@ -101,6 +139,7 @@ async function runFollowMode(options, lastN) {
                 console.log(text);
         }
         started = true;
+        return undefined;
     };
     await setupFollowMode(showConsole, {
         startMessage: followingConsoleMessage,
@@ -167,8 +206,9 @@ export function registerConsoleCommand(program) {
             }
             return { success: true, data: { messages, filtered } };
         }, options, (data) => {
-            const { filtered } = data;
-            return formatConsole(filtered, buildFormatOptions(options, lastN));
+            const { messages, filtered } = data;
+            const skipped = skippedMessages(messages, lastMessages(filtered, lastN));
+            return formatConsole(filtered, buildFormatOptions(options, lastN, skipped));
         });
     });
 }

package/dist/commands/details.js

@@ -3,6 +3,7 @@ import { jsonOption } from './shared/commonOptions.js';
 import { getDetails } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
 import { formatNetworkDetails, formatConsoleDetails } from '../ui/formatters/details.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { validateDetailsItem } from '../utils/typeGuards.js';
 /**
@@ -65,8 +66,8 @@ export function registerDetailsCommand(program) {
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                     errorContext: {
                         suggestion: opts.type === 'network'
-                            ? 'Use bdg network list to see available request IDs'
-                            : 'Use bdg peek --console to see available console message indices',
+                            ? `Use ${sessionCommand('bdg network list')} to see available request IDs`
+                            : `Use ${sessionCommand('bdg peek --console')} to see available console message indices`,
                     },
                 };
             }

package/dist/commands/dom/DomElementResolver.d.ts

@@ -11,14 +11,15 @@
  * ```typescript
  * const resolver = DomElementResolver.getInstance();
  *
- * const target = await resolver.resolve('0');
+ * const target = await resolver.resolve('0', undefined, 'click');
  * // { success: true, selector: '.cached-selector', backendNodeId: 42 }
  *
- * const target = await resolver.resolve('button.submit');
+ * const target = await resolver.resolve('button.submit', undefined, 'click');
  * // { success: true, selector: 'button.submit' }
  * ```
  */
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
+import type { IndexSource } from '../../types.js';
 /**
  * Successful result of resolving a selector or index argument.
  */
@@ -31,6 +32,10 @@ export interface ElementTargetSuccess {
     index?: number | undefined;
     /** Exact element from the query cache (index arguments only) */
     backendNodeId?: number | undefined;
+    /** The list the index refers to (index arguments only) */
+    source?: IndexSource | undefined;
+    /** What the cached element was when listed, e.g. `h3 "Welcome"` (index arguments only) */
+    preview?: string | undefined;
 }
 /**
  * Failed result of resolving a selector or index argument.
@@ -76,9 +81,10 @@ export declare class DomElementResolver {
      *
      * @param selectorOrIndex - CSS selector or numeric index from query results
      * @param explicitIndex - Optional explicit --index flag value (0-based, selectors only)
+     * @param command - `bdg dom` subcommand being run, e.g. "click" (for suggestions)
      * @returns Resolution result
      */
-    resolve(selectorOrIndex: string, explicitIndex?: number): Promise<ElementTargetResult>;
+    resolve(selectorOrIndex: string, explicitIndex: number | undefined, command: string): Promise<ElementTargetResult>;
     /**
      * Get the backend node id for a cached index, checking the element still exists.
      *
@@ -89,6 +95,7 @@ export declare class DomElementResolver {
      */
     getNodeIdForIndex(index: number): Promise<{
         nodeId: number;
+        source: IndexSource;
     }>;
     /**
      * Check if the argument is a numeric index.