browser-debugger-cli 0.15.0 → 0.16.0

package/dist/commands/cdp.d.ts

@@ -1,7 +1,7 @@
 import { type Command } from 'commander';
 import { type CommandResult } from './shared/CommandRunner.js';
 import type { CdpCommandOptions } from './shared/optionTypes.js';
-import { type CdpExecuteData } from '../ui/formatters/cdp.js';
+import { type CdpDomainDescription, type CdpExecuteData, type CdpMethodDescription, type CdpTypeDescription } from '../ui/formatters/cdp.js';
 /**
  * Register CDP command with full introspection support.
  *
@@ -35,4 +35,41 @@ export declare function isBareDomain(method: string, options: CdpCommandOptions)
  * @returns Error result, or undefined when the result has no exception
  */
 export declare function pageExceptionResult(result: unknown): CommandResult<CdpExecuteData> | undefined;
+/** A description `bdg cdp <name> --describe` gives */
+type CdpDescription = CdpMethodDescription | CdpDomainDescription | CdpTypeDescription;
+/**
+ * Handle describe mode: show a domain, a method's signature and parameters,
+ * or a protocol type's values or properties.
+ *
+ * @param name - Domain, `Domain.method` or `Domain.Type` (case-insensitive)
+ * @returns Success result with the description
+ */
+export declare function handleDescribeMethod(name: string): CommandResult<CdpDescription>;
+/**
+ * The method `bdg cdp <name>` sends: a bundled method with its casing, or a
+ * well-formed method the bundled protocol lacks, as typed with a warning.
+ *
+ * @param methodName - Method name as typed
+ * @param options - `sendAnyway` sends a close typo of bundled methods as typed
+ * @returns Method to send, and the warning for one the bundled protocol lacks
+ * @throws CommandError (exit 81) for a blocked method, a type, a close typo
+ *   of bundled methods (without `sendAnyway`) or a name that is not `Domain.method`
+ */
+export declare function methodToSend(methodName: string, options?: Pick<CdpCommandOptions, 'sendAnyway'>): {
+    method: string;
+    warning?: string;
+};
+/**
+ * The result of a CDP call: the page exception it reported (exit 91), or its
+ * result with the session's and the method's hints; either way with the
+ * warning for a method the bundled protocol lacks.
+ *
+ * @param method - Method called
+ * @param cdpResult - What Chrome returned
+ * @param warning - Warning for a method the bundled protocol lacks
+ * @param ipcHint - Hint the session gave (e.g. a repeated-call pattern)
+ * @returns Command result
+ */
+export declare function cdpCallResult(method: string, cdpResult: unknown, warning?: string, ipcHint?: string): CommandResult<CdpExecuteData>;
+export {};
 //# sourceMappingURL=cdp.d.ts.map

package/dist/commands/cdp.js

@@ -1,14 +1,16 @@
 import { Option } from 'commander';
-import { normalizeMethod } from '../cdp/protocol.js';
-import { getAllDomainSummaries, getDomainMethods, getProtocolCounts, getDomainSummary, getMethodSchema, } from '../cdp/schema.js';
+import { resolveMethodTarget } from '../cdp/methodTarget.js';
+import { getBundledProtocolVersion } from '../cdp/protocol.js';
+import { getAllDomainSummaries, getDomainMethods, getProtocolCounts, getDomainSummary, getMethodSchema, getTypeSchema, } from '../cdp/schema.js';
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
 import { CommandError } from '../errors/index.js';
-import { emptyCdpSearchError, missingArgumentError, scriptExecutionError, } from '../errors/messages.js';
+import { cdpMethodNotFoundError, cdpMethodNotInBundledProtocolError, cdpMethodTypoError, cdpTypeNotMethodError, emptyCdpSearchError, missingArgumentError, scriptExecutionError, } from '../errors/messages.js';
 import { callCDP } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
 import { describeException } from '../runtime/dom/evalHelpers.js';
 import { formatCdpDescription, formatCdpDomainMethods, formatCdpDomains, formatCdpResult, formatCdpSearch, isEmptyCdpResult, } from '../ui/formatters/cdp.js';
+import { CDP_EXECUTION_HELP, cdpUnlistedMethodWarning } from '../ui/messages/commands.js';
 import { formatHint } from '../ui/messages/hints.js';
 import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -83,7 +85,7 @@ export function registerCdpCommand(program) {
         .summary('CDP protocol introspection and execution')
         .description('CDP protocol introspection and execution\n' +
         '  Discovery: --list, --search, --describe\n' +
-        '  Execution: case-insensitive (network.getcookies works)')
+        CDP_EXECUTION_HELP)
         .argument('[method]', 'CDP method name (e.g., Network.getCookies, network.getcookies)')
         .addOption(new Option('--params <json>', 'Method parameters as JSON'))
         .addOption(new Option('--list', 'List all domains or methods in a domain').conflicts([
@@ -91,6 +93,7 @@ export function registerCdpCommand(program) {
         'params',
     ]))
         .addOption(new Option('--describe', 'Show method signature and parameters').conflicts('params'))
+        .addOption(new Option('--send-anyway', 'Send a Domain.method that looks like a typo of a bundled one as typed').conflicts(['list', 'describe', 'search']))
         .addOption(new Option('--search <query>', 'Search methods by keyword').conflicts([
         'list',
         'describe',
@@ -123,7 +126,7 @@ async function runCdpCommand(method, options) {
         return runCommand(async () => handleDescribeMethod(method), options, formatCdpDescription);
     }
     if (method) {
-        return runCommand(async () => handleExecuteMethod(method, options.params), options, formatCdpResult);
+        return runCommand(async () => handleExecuteMethod(method, options), options, formatCdpResult);
     }
     return runCommand(async () => {
         const err = missingArgumentError(CDP_USAGE);
@@ -331,99 +334,116 @@ function handleListDomainMethods(domainName) {
     };
 }
 /**
- * Handle describe method mode: Show method signature and parameters.
+ * Handle describe mode: show a domain, a method's signature and parameters,
+ * or a protocol type's values or properties.
  *
- * @param methodName - Method name (case-insensitive, with or without domain)
- * @returns Success result with method schema
+ * @param name - Domain, `Domain.method` or `Domain.Type` (case-insensitive)
+ * @returns Success result with the description
  */
-function handleDescribeMethod(methodName) {
-    const [domainName, method] = methodName.includes('.')
-        ? methodName.split('.')
-        : [methodName, undefined];
-    if (!method) {
-        const summary = getDomainSummary(domainName);
-        if (!summary) {
-            const similar = findSimilarMethods(methodName);
-            const suggestions = ['Use: bdg cdp --list (to see all domains)'];
-            if (similar.length > 0) {
-                suggestions.push('');
-                suggestions.push('Did you mean:');
-                similar.forEach((name) => suggestions.push(`  - ${name}`));
-            }
-            return {
-                success: false,
-                error: `Domain or method '${methodName}' not found`,
-                exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-                errorContext: {
-                    suggestion: suggestions.join('\n'),
-                },
-            };
-        }
-        const domainNote = DOMAIN_NOTES[summary.name];
-        return {
-            success: true,
-            data: {
-                type: 'domain',
-                domain: summary.name,
-                description: summary.description,
-                commands: summary.commandCount,
-                events: summary.eventCount,
-                experimental: summary.experimental,
-                deprecated: summary.deprecated,
-                note: domainNote,
-                nextStep: `Use: bdg cdp ${summary.name} --list (to see all methods)`,
-            },
-        };
-    }
-    const schema = getMethodSchema(domainName, method);
-    if (!schema) {
-        const similar = findSimilarMethods(methodName, domainName);
-        const suggestions = [`Use: bdg cdp ${domainName} --list (to see all ${domainName} methods)`];
-        if (similar.length > 0) {
-            suggestions.push('');
-            suggestions.push('Did you mean:');
-            similar.forEach((name) => suggestions.push(`  - ${name}`));
-        }
+export function handleDescribeMethod(name) {
+    const [domainName = '', member] = name.includes('.') ? name.split('.') : [name, undefined];
+    if (!member)
+        return describeDomain(name);
+    const schema = getMethodSchema(domainName, member);
+    if (schema)
+        return { success: true, data: describeMethod(schema) };
+    const type = getTypeSchema(domainName, member);
+    if (type)
+        return { success: true, data: { type: 'type', ...type } };
+    const target = resolveMethodTarget(name);
+    const err = target.kind === 'unlisted'
+        ? cdpMethodNotInBundledProtocolError(target.method, getBundledProtocolVersion())
+        : cdpMethodNotFoundError(name, findSimilarMethods(name, domainName), `Use: bdg cdp ${domainName} --list (to see all ${domainName} methods)`);
+    return {
+        success: false,
+        error: err.message,
+        exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+        errorContext: { suggestion: err.suggestion },
+    };
+}
+/**
+ * Describe a domain (`bdg cdp Network --describe`).
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @returns Domain description, or not found with similar names
+ */
+function describeDomain(domainName) {
+    const summary = getDomainSummary(domainName);
+    if (!summary) {
+        const err = cdpMethodNotFoundError(domainName, findSimilarMethods(domainName), 'Use: bdg cdp --list (to see all domains)');
         return {
             success: false,
-            error: `Method '${methodName}' not found`,
+            error: `Domain or method '${domainName}' not found`,
             exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-            errorContext: {
-                suggestion: suggestions.join('\n'),
-            },
+            errorContext: { suggestion: err.suggestion },
         };
     }
-    const methodNote = METHOD_NOTES[schema.name] ?? DOMAIN_NOTES[schema.domain];
-    const alternative = blockedAlternative(schema.name);
     return {
         success: true,
         data: {
-            type: 'method',
-            name: schema.name,
-            domain: schema.domain,
-            method: schema.method,
-            description: schema.description,
-            experimental: schema.experimental,
-            deprecated: schema.deprecated,
-            note: methodNote,
-            parameters: schema.parameters.map((p) => ({
-                name: p.name,
-                type: p.type,
-                required: p.required,
-                description: p.description,
-                enum: p.enum,
-                items: p.items,
-                deprecated: p.deprecated,
-            })),
-            returns: schema.returns.map((r) => ({
-                name: r.name,
-                type: r.type,
-                optional: r.optional,
-                description: r.description,
-                items: r.items,
-            })),
-            example: alternative ? { command: alternative } : schema.example,
+            type: 'domain',
+            domain: summary.name,
+            description: summary.description,
+            commands: summary.commandCount,
+            events: summary.eventCount,
+            experimental: summary.experimental,
+            deprecated: summary.deprecated,
+            note: DOMAIN_NOTES[summary.name],
+            nextStep: `Use: bdg cdp ${summary.name} --list (to see all methods)`,
+        },
+    };
+}
+/**
+ * A parameter as `--describe` shows it.
+ *
+ * @param p - Parameter schema
+ * @returns Described parameter
+ */
+function describeParameter(p) {
+    return {
+        name: p.name,
+        type: p.type,
+        required: p.required,
+        description: p.description,
+        enum: p.enum,
+        ref: p.ref,
+        refType: p.refType,
+        items: p.items,
+        experimental: p.experimental,
+        deprecated: p.deprecated,
+    };
+}
+/**
+ * Describe a method (`bdg cdp Network.getCookies --describe`).
+ *
+ * @param schema - Method schema
+ * @returns Method description with its redirect, note and example
+ */
+function describeMethod(schema) {
+    const alternative = blockedAlternative(schema.name);
+    return {
+        type: 'method',
+        name: schema.name,
+        domain: schema.domain,
+        method: schema.method,
+        description: schema.description,
+        experimental: schema.experimental,
+        deprecated: schema.deprecated,
+        note: METHOD_NOTES[schema.name] ?? DOMAIN_NOTES[schema.domain],
+        parameters: schema.parameters.map(describeParameter),
+        returns: schema.returns.map((r) => ({
+            name: r.name,
+            type: r.type,
+            optional: r.optional,
+            description: r.description,
+            items: r.items,
+        })),
+        redirect: schema.redirect && {
+            method: schema.redirect.method,
+            resolved: schema.redirect.resolved,
+            parameters: schema.redirect.parameters.map(describeParameter),
         },
+        example: alternative ? { command: alternative } : schema.example,
     };
 }
 /**
@@ -445,44 +465,78 @@ const BLOCKED_CDP_METHODS = {
     },
 };
 /**
- * Handle execute method mode: Call CDP method.
+ * The method `bdg cdp <name>` sends: a bundled method with its casing, or a
+ * well-formed method the bundled protocol lacks, as typed with a warning.
  *
- * @param methodName - Method name (case-insensitive)
- * @param paramsJson - Parameters as JSON string
- * @returns Success result with method response
+ * @param methodName - Method name as typed
+ * @param options - `sendAnyway` sends a close typo of bundled methods as typed
+ * @returns Method to send, and the warning for one the bundled protocol lacks
+ * @throws CommandError (exit 81) for a blocked method, a type, a close typo
+ *   of bundled methods (without `sendAnyway`) or a name that is not `Domain.method`
  */
-async function handleExecuteMethod(methodName, paramsJson) {
-    const normalized = normalizeMethod(methodName);
-    if (normalized && BLOCKED_CDP_METHODS[normalized]) {
-        const blocked = BLOCKED_CDP_METHODS[normalized];
-        return {
-            success: false,
-            error: `${normalized} is blocked via raw CDP: ${blocked.reason}`,
-            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-            errorContext: { suggestion: `Use: ${sessionCommand(blocked.alternative)}` },
-        };
-    }
-    if (!normalized) {
-        const similar = findSimilarMethods(methodName);
-        const suggestions = ['Use: bdg cdp --search <keyword> (to search for methods)'];
-        if (similar.length > 0) {
-            suggestions.push('');
-            suggestions.push('Did you mean:');
-            similar.forEach((name) => suggestions.push(`  - ${name}`));
+export function methodToSend(methodName, options = {}) {
+    const target = resolveMethodTarget(methodName);
+    if (target.kind === 'known') {
+        const blocked = BLOCKED_CDP_METHODS[target.method];
+        if (blocked) {
+            throw new CommandError(`${target.method} is blocked via raw CDP: ${blocked.reason}`, { suggestion: `Use: ${sessionCommand(blocked.alternative)}` }, EXIT_CODES.INVALID_ARGUMENTS);
         }
+        return { method: target.method };
+    }
+    if (target.kind === 'unlisted' || (target.kind === 'typo' && options.sendAnyway)) {
         return {
-            success: false,
-            error: `Method '${methodName}' not found`,
-            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-            errorContext: {
-                suggestion: suggestions.join('\n'),
-            },
+            method: target.method,
+            warning: cdpUnlistedMethodWarning(target.method, getBundledProtocolVersion()),
         };
     }
+    const err = target.kind === 'type'
+        ? cdpTypeNotMethodError(target.name)
+        : unknownMethodError(methodName, target);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Not found, for a close typo of bundled methods or domains, or a name that
+ * is not `Domain.method`.
+ *
+ * @param methodName - Method name as typed
+ * @param target - Typo with its suggestions, or malformed
+ * @returns Message and suggestion
+ */
+function unknownMethodError(methodName, target) {
+    if (target.kind === 'malformed') {
+        return cdpMethodNotFoundError(methodName, findSimilarMethods(methodName), 'Use: bdg cdp --search <keyword> (to search for methods)');
+    }
+    const [domainName = ''] = methodName.split('.');
+    return target.suggestions.length > 0
+        ? cdpMethodTypoError(methodName, target.suggestions.slice(0, 3), 'Use: bdg cdp --search <keyword> (to search for methods)')
+        : cdpMethodTypoError(methodName, [], domainSuggestion(domainName));
+}
+/**
+ * Add the warning about a method missing from the bundled protocol to the
+ * error Chrome gave for it, so a failed call still says it was sent as typed.
+ *
+ * @param error - Error of the call
+ * @param warning - Warning, when the method was not in the bundled protocol
+ * @returns The error, with the warning (top-level JSON `warning`) when there is one
+ */
+function withWarning(error, warning) {
+    if (!warning || !(error instanceof CommandError))
+        return error;
+    return new CommandError(error.message, { ...error.metadata, warning }, error.exitCode);
+}
+/**
+ * Handle execute method mode: Call CDP method.
+ *
+ * @param methodName - Method name (case-insensitive for bundled methods)
+ * @param paramsJson - Parameters as JSON string
+ * @returns Success result with method response
+ */
+async function handleExecuteMethod(methodName, options) {
+    const { method: normalized, warning } = methodToSend(methodName, options);
     let params;
-    if (paramsJson) {
+    if (options.params) {
         try {
-            params = JSON.parse(paramsJson);
+            params = JSON.parse(options.params);
         }
         catch (error) {
             return {
@@ -492,29 +546,42 @@ async function handleExecuteMethod(methodName, paramsJson) {
                 errorContext: {
                     suggestion: `Use: bdg cdp ${normalized} --describe (to see parameter schema)`,
                 },
+                ...(warning && { warning }),
             };
         }
     }
     const response = await callCDP(normalized, params);
-    validateIPCResponse(response);
-    const cdpResult = response.data?.result;
+    try {
+        validateIPCResponse(response);
+    }
+    catch (error) {
+        throw withWarning(error, warning);
+    }
+    const ipcHint = response.data?.hint && formatHint(response.data.hint);
+    return cdpCallResult(normalized, response.data?.result, warning, ipcHint);
+}
+/**
+ * The result of a CDP call: the page exception it reported (exit 91), or its
+ * result with the session's and the method's hints; either way with the
+ * warning for a method the bundled protocol lacks.
+ *
+ * @param method - Method called
+ * @param cdpResult - What Chrome returned
+ * @param warning - Warning for a method the bundled protocol lacks
+ * @param ipcHint - Hint the session gave (e.g. a repeated-call pattern)
+ * @returns Command result
+ */
+export function cdpCallResult(method, cdpResult, warning, ipcHint) {
+    const withCallWarning = warning ? { warning } : {};
     const exception = pageExceptionResult(cdpResult);
     if (exception)
-        return exception;
-    const result = {
+        return { ...exception, ...withCallWarning };
+    const hints = [ipcHint, getMethodHint(method, cdpResult)].filter(Boolean);
+    return {
         success: true,
-        data: {
-            method: normalized,
-            result: cdpResult,
-        },
+        data: { method, result: cdpResult },
+        ...withCallWarning,
+        ...(hints.length > 0 && { hint: hints.join('\n') }),
     };
-    if (response.data?.hint) {
-        result.hint = formatHint(response.data.hint);
-    }
-    const methodHint = getMethodHint(normalized, cdpResult);
-    if (methodHint) {
-        result.hint = result.hint ? `${result.hint}\n${methodHint}` : methodHint;
-    }
-    return result;
 }
 //# sourceMappingURL=cdp.js.map

package/dist/commands/cleanup.js

@@ -5,10 +5,10 @@ import { purgeNeedsNamedSessionError, purgeRefusedError, sessionDirIsFileError,
 import { isSessionChrome } from '../session/cleanup/staleSession.js';
 import { performSessionCleanup } from '../session/cleanup/userCommands.js';
 import { isDaemonAlive } from '../session/daemonSocket.js';
-import { getSessionDir, getSessionFilePath, getSessionName } from '../session/paths.js';
+import { getSessionDir, getSessionDownloadsDir, getSessionFilePath, getSessionName, } from '../session/paths.js';
 import { readDaemonPid, readPidFromFile } from '../session/pid.js';
 import { joinLines } from '../ui/formatting.js';
-import { sessionFilesCleanedMessage, sessionOutputRemovedMessage, sessionDirectoryCleanMessage, sessionDirectoryPurgedMessage, noSessionFilesMessage, sessionStillActiveError, sessionStillActiveSuggestion, warningMessage, } from '../ui/messages/commands.js';
+import { downloadsKeptMessage, 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';
@@ -19,7 +19,7 @@ import { isProcessAlive } from '../utils/process.js';
  */
 function formatCleanup(data) {
     const { cleaned } = data;
-    return joinLines(cleaned.session && sessionFilesCleanedMessage(), cleaned.output && sessionOutputRemovedMessage(), ...(data.warnings ?? []).map((warning) => warningMessage(warning)), '', data.message);
+    return joinLines(cleaned.session && sessionFilesCleanedMessage(), cleaned.output && sessionOutputRemovedMessage(), data.downloadsKept && downloadsKeptMessage(data.downloadsKept.dir, data.downloadsKept.files), ...(data.warnings ?? []).map((warning) => warningMessage(warning)), '', data.message);
 }
 /**
  * Delete the selected named session's directory (Chrome profile, logs, port).
@@ -162,11 +162,13 @@ async function cleanupSession(opts) {
         };
     }
     const didCleanup = Object.values(cleaned).some(Boolean) || purged !== undefined;
+    const downloadsKept = purged === undefined ? keptDownloads() : undefined;
     return {
         success: true,
         data: {
             cleaned,
             ...(purged !== undefined && { purged }),
+            ...(downloadsKept && { downloadsKept }),
             message: !didCleanup
                 ? noSessionFilesMessage()
                 : purged !== undefined
@@ -176,6 +178,18 @@ async function cleanupSession(opts) {
         },
     };
 }
+/**
+ * Downloaded files of the session, which cleanup keeps.
+ *
+ * @returns Their directory and count, or undefined when there are none
+ */
+function keptDownloads() {
+    const dir = getSessionDownloadsDir();
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+        return undefined;
+    const files = fs.readdirSync(dir).length;
+    return files > 0 ? { dir, files } : undefined;
+}
 /**
  * Register cleanup command
  *
@@ -184,7 +198,7 @@ async function cleanupSession(opts) {
 export function registerCleanupCommand(program) {
     program
         .command('cleanup')
-        .description('Clean up stale session files')
+        .description('Clean up stale session files (downloaded files are kept)')
         .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)

package/dist/commands/dom/formInteraction.js

@@ -18,7 +18,7 @@ import { callCDP, domClick, domFill, domPressKey, domScroll, domSubmit } from '.
 import { findUnknownModifiers } from '../../runtime/dom/keyMapping.js';
 import { formatTriggeredRequestLines, formatTriggeredRequestsTitle, } from '../../ui/formatters/triggeredRequests.js';
 import { OutputFormatter } from '../../ui/formatting.js';
-import { CLICK_RESULT_WAIT_HELP, HOVER_OFF_DONE, HOVER_USAGE, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, pointerScrollText, actionStatusLine, dialogConsoleText, moreMessagesText, newMessageText, pageNavigationText, shownElementText, stillChangingNote, } from '../../ui/messages/commands.js';
+import { CLICK_RESULT_WAIT_HELP, HOVER_OFF_DONE, HOVER_USAGE, POINTER_ACTION_DONE, POINTER_ACTION_NOUN, pointerScrollText, actionStatusLine, dialogConsoleText, downloadText, moreMessagesText, newMessageText, pageNavigationText, shownElementText, stillChangingNote, } from '../../ui/messages/commands.js';
 import { sessionCommand } from '../../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** Help of `--strict` on click and hover */
@@ -313,9 +313,9 @@ async function runPointerCommand(selectorOrIndex, options, action) {
  * "⚠ Element Clicked (page still changing)" with what it was still working
  * on, or "⚠ Element Clicked (no visible effect: …)"), the details, what
  * changed on the page (`Page:` navigation, `New text:` messages, `Shown:`
- * elements), then the network requests it triggered and the dialogs it
- * caused. No request list is shown when there were none (JSON has an empty
- * `triggeredRequests` then).
+ * elements), then the network requests it triggered, the downloads it
+ * started and the dialogs it caused. No request list is shown when there
+ * were none (JSON has an empty `triggeredRequests` then).
  *
  * @param done - What was done, e.g. "Element Clicked"
  * @param details - Label/value rows
@@ -353,6 +353,10 @@ function formatActionOutput(done, details, result, options = {}) {
             .blank()
             .section(formatTriggeredRequestsTitle(result.triggeredRequests ?? [], omitted), requests);
     }
+    if (result.downloads?.length)
+        fmt.blank();
+    for (const download of result.downloads ?? [])
+        fmt.text(downloadText(download));
     for (const dialog of result.dialogs ?? []) {
         fmt.blank();
         fmt.text(`Dialog: ${dialogConsoleText(dialog)}`);

package/dist/commands/dom/helpers/index.d.ts

@@ -3,9 +3,9 @@
  * so callers can keep importing from `@/commands/dom/helpers.js`.
  *
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
- * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
+ * - `screenshot.ts` — page / element capture through the daemon, writing the image
  */
-export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
-export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
-export type { DomQueryResult, DomGetResult, ScreenshotResult, DomGetOptions, ScreenshotOptions, DomContext, ElementBounds, } from '../../../types.js';
+export { noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
+export { captureScreenshot, screenshotInterrupted } from './screenshot.js';
+export type { DomGetOptions, DomContext } from '../../../types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/dom/helpers/index.js

@@ -3,8 +3,8 @@
  * so callers can keep importing from `@/commands/dom/helpers.js`.
  *
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
- * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
+ * - `screenshot.ts` — page / element capture through the daemon, writing the image
  */
-export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
-export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
+export { noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, pageDocumentId, } from './query.js';
+export { captureScreenshot, screenshotInterrupted } from './screenshot.js';
 //# sourceMappingURL=index.js.map

package/dist/commands/dom/helpers/query.d.ts

@@ -91,10 +91,10 @@ export declare function getDOMElements(options: DomGetOptions): Promise<DomGetRe
  * Resolve a selector to its first match.
  *
  * @param selector - CSS selector
- * @returns Reference to the first matching node (valid within this command)
+ * @returns Backend node id of the first match
  * @throws CommandError (83) when nothing matches
  */
-export declare function resolveSelector(selector: string): Promise<NodeRef>;
+export declare function resolveSelector(selector: string): Promise<number>;
 /**
  * Resolve selectors to backend node ids (first match each).
  *

package/dist/commands/dom/helpers/query.js

@@ -655,7 +655,7 @@ export async function getDOMElements(options) {
  * Resolve a selector to its first match.
  *
  * @param selector - CSS selector
- * @returns Reference to the first matching node (valid within this command)
+ * @returns Backend node id of the first match
  * @throws CommandError (83) when nothing matches
  */
 export async function resolveSelector(selector) {
@@ -664,7 +664,7 @@ export async function resolveSelector(selector) {
         const err = await noMatchesError(selector);
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
-    return { backendNodeId };
+    return backendNodeId;
 }
 /**
  * Resolve selectors to backend node ids (first match each).