browser-debugger-cli 0.7.2 → 0.9.0

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

@@ -0,0 +1,20 @@
+/**
+ * `bdg dom listeners <selector|index>` - the event listeners that run for an
+ * element: on the element itself, its ancestors, its document and window.
+ *
+ * The daemon collects them with `DOMDebugger.getEventListeners`; listeners on
+ * ancestors matter because frameworks (React, jQuery) attach their handlers
+ * to a root container or the document and dispatch from there. jQuery's
+ * dispatcher is replaced by the jQuery handlers it runs for the element,
+ * React's `on…` props of the element and its ancestors are listed, and
+ * framework roots (React's root container) are summarised per node unless
+ * `--all` is given.
+ */
+import type { Command } from 'commander';
+/**
+ * Register `bdg dom listeners`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerListenersCommand(dom: Command): void;
+//# sourceMappingURL=listeners.d.ts.map

package/dist/commands/dom/listeners.js

@@ -0,0 +1,64 @@
+/**
+ * `bdg dom listeners <selector|index>` - the event listeners that run for an
+ * element: on the element itself, its ancestors, its document and window.
+ *
+ * The daemon collects them with `DOMDebugger.getEventListeners`; listeners on
+ * ancestors matter because frameworks (React, jQuery) attach their handlers
+ * to a root container or the document and dispatch from there. jQuery's
+ * dispatcher is replaced by the jQuery handlers it runs for the element,
+ * React's `on…` props of the element and its ancestors are listed, and
+ * framework roots (React's root container) are summarised per node unless
+ * `--all` is given.
+ */
+import { DomElementResolver } from './DomElementResolver.js';
+import { runElementCommand } from './helpers/runElementCommand.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { eventTypesOption, integerOption } from '../shared/validation.js';
+import { domListeners } from '../../ipc/client.js';
+import { formatListeners } from '../../ui/formatters/listeners.js';
+/**
+ * Register `bdg dom listeners`.
+ *
+ * @param dom - The `dom` command group
+ */
+export function registerListenersCommand(dom) {
+    dom
+        .command('listeners')
+        .description('List event listeners that run for an element (incl. delegated ones on ancestors)')
+        .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
+        .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
+        .option('--type <types>', 'Only these event types (comma-separated, e.g. click,keydown; repeatable)', eventTypesOption)
+        .option('--all', 'List every listener of framework roots (React) instead of one line per node')
+        .addOption(jsonOption())
+        .action(async (selectorOrIndex, options) => {
+        await runCommand(() => listElementListeners(selectorOrIndex, options), options, (data) => formatListeners(data, options.type));
+    });
+}
+/**
+ * Resolve the element and ask the daemon for its listeners.
+ *
+ * @param selectorOrIndex - CSS selector or cached query index
+ * @param options - Command options
+ * @returns Command result; an index argument is reported as `index`
+ */
+async function listElementListeners(selectorOrIndex, options) {
+    const result = await runElementCommand({
+        selectorOrIndex,
+        index: options.index,
+        buildRequest: (target) => ({
+            ...target,
+            ...(options.type && { types: options.type }),
+            ...(options.all && { all: true }),
+        }),
+        call: domListeners,
+        command: 'listeners',
+        action: 'list event listeners',
+        failureSuggestion: 'Verify the selector matches an element: bdg dom query "<selector>"',
+    });
+    if (!result.data || !DomElementResolver.getInstance().isNumericIndex(selectorOrIndex)) {
+        return result;
+    }
+    return { ...result, data: { ...result.data, index: Number(selectorOrIndex) } };
+}
+//# sourceMappingURL=listeners.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * `bdg dom query` — find elements by CSS selector and populate the query cache.
+ */
+import type { DomQueryCommandOptions } from '../shared/optionTypes.js';
+/**
+ * Handle `bdg dom query <selector>`.
+ *
+ * Runs the selector, caches the result set so later commands can reference
+ * elements by index, and renders the result either as JSON or human output.
+ * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
+ * indices of an earlier query are not used by mistake.
+ */
+export declare function handleDomQuery(selector: string, options: DomQueryCommandOptions): Promise<void>;
+//# sourceMappingURL=query.d.ts.map

package/dist/commands/dom/query.js

@@ -0,0 +1,35 @@
+/**
+ * `bdg dom query` — find elements by CSS selector and populate the query cache.
+ */
+import { noMatchesError, queryDOMElements } from './helpers/index.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { QueryCacheManager } from '../../session/QueryCacheManager.js';
+import { formatDomQuery } from '../../ui/formatters/dom.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Handle `bdg dom query <selector>`.
+ *
+ * Runs the selector, caches the result set so later commands can reference
+ * elements by index, and renders the result either as JSON or human output.
+ * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
+ * indices of an earlier query are not used by mistake.
+ */
+export async function handleDomQuery(selector, options) {
+    await runCommand(async () => {
+        const result = await queryDOMElements(selector);
+        const cache = QueryCacheManager.getInstance();
+        if (result.count === 0) {
+            await cache.clear();
+            const err = await noMatchesError(selector);
+            return {
+                success: false,
+                error: err.message,
+                exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+                errorContext: { suggestion: err.suggestion },
+            };
+        }
+        await cache.set(result);
+        return { success: true, data: result };
+    }, options, formatDomQuery);
+}
+//# sourceMappingURL=query.js.map

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

@@ -0,0 +1,31 @@
+/**
+ * `bdg dom screenshot` — capture page, element, or frame-sequence screenshots.
+ */
+import type { DomScreenshotCommandOptions } from '../shared/optionTypes.js';
+/**
+ * Pick the image format for a file: `--format` if given, else the extension.
+ *
+ * @param outputPath - File to write
+ * @param requested - `--format` value
+ * @returns Format to capture in
+ * @throws CommandError (81) when the extension and `--format` disagree or the
+ *   extension names a format Chrome cannot capture
+ */
+export declare function resolveImageFormat(outputPath: string, requested?: 'png' | 'jpeg'): 'png' | 'jpeg';
+/**
+ * Fold the optional positional target (`bdg dom screenshot out.png "#sel"`,
+ * or an index from a query) into `--selector` / `--index`.
+ *
+ * @param target - Positional selector or index, if given
+ * @param options - Command options
+ * @returns Options with the target as `selector` or `index`
+ * @throws CommandError (81) when the option names a different element
+ */
+export declare function withPositionalTarget(target: string | undefined, options: DomScreenshotCommandOptions): DomScreenshotCommandOptions;
+/**
+ * Handle `bdg dom screenshot <path> [selector|index]`.
+ *
+ * Dispatches to page, element, or sequence capture based on flags.
+ */
+export declare function handleDomScreenshot(outputPath: string, target: string | undefined, commandOptions: DomScreenshotCommandOptions): Promise<void>;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/commands/dom/screenshot.js

@@ -0,0 +1,272 @@
+/**
+ * `bdg dom screenshot` — capture page, element, or frame-sequence screenshots.
+ */
+import { extname } from 'path';
+import { DomElementResolver } from './DomElementResolver.js';
+import { capturePageScreenshot, captureElementScreenshot, resolveSelector, } from './helpers/index.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { assertFilePath, outputPathError } from '../shared/outputFile.js';
+import { positiveIntRule } from '../shared/validation.js';
+import { CommandError } from '../../errors/index.js';
+import { conflictingOptionsMessage, conflictingTargetError, genericError, } from '../../errors/messages.js';
+import { missingArgumentError } from '../../errors/messages.js';
+import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
+import { formatDomScreenshot } from '../../ui/formatters/dom.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { delay } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { filterDefined } from '../../utils/objects.js';
+const log = createLogger('dom');
+/** Image format of each file extension Chrome can write */
+const EXTENSION_FORMATS = {
+    '.png': 'png',
+    '.jpg': 'jpeg',
+    '.jpeg': 'jpeg',
+};
+/** Image extensions Chrome cannot capture (writing PNG bytes to them would mislead) */
+const UNSUPPORTED_EXTENSIONS = new Set(['.gif', '.webp', '.bmp', '.tif', '.tiff', '.avif', '.svg']);
+/**
+ * Pick the image format for a file: `--format` if given, else the extension.
+ *
+ * @param outputPath - File to write
+ * @param requested - `--format` value
+ * @returns Format to capture in
+ * @throws CommandError (81) when the extension and `--format` disagree or the
+ *   extension names a format Chrome cannot capture
+ */
+export function resolveImageFormat(outputPath, requested) {
+    const extension = extname(outputPath).toLowerCase();
+    const fromExtension = EXTENSION_FORMATS[extension];
+    if (UNSUPPORTED_EXTENSIONS.has(extension) ||
+        (requested && fromExtension && requested !== fromExtension)) {
+        throw new CommandError(`Cannot write ${requested ?? 'a screenshot'} to a ${extension} file`, {
+            suggestion: 'Screenshots are png or jpeg: use a .png or .jpg file name (or --format to match it)',
+        }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return requested ?? fromExtension ?? 'png';
+}
+function buildPageScreenshotOptions(options) {
+    return filterDefined({
+        format: options.format,
+        quality: options.quality,
+        fullPage: options.fullPage,
+        noResize: options.resize === false,
+        scroll: options.scroll,
+    });
+}
+function buildElementScreenshotOptions(options) {
+    return filterDefined({
+        format: options.format,
+        quality: options.quality,
+        noResize: options.resize === false,
+    });
+}
+function hasElementTarget(options) {
+    return options.selector !== undefined || options.index !== undefined;
+}
+async function resolveElementNodeId(options) {
+    if (options.index !== undefined) {
+        const resolver = DomElementResolver.getInstance();
+        const node = await resolver.getNodeIdForIndex(options.index);
+        return { backendNodeId: node.nodeId };
+    }
+    if (options.selector !== undefined) {
+        return resolveSelector(options.selector);
+    }
+    const err = missingArgumentError('--selector "css-selector" or --index N from a previous query');
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+function addElementInfo(result, options) {
+    const bounds = result.element?.bounds ?? {
+        x: 0,
+        y: 0,
+        width: result.width,
+        height: result.height,
+    };
+    return {
+        ...result,
+        element: {
+            ...(options.selector !== undefined && { selector: options.selector }),
+            ...(options.index !== undefined && { index: options.index }),
+            bounds,
+            ...(result.element?.captured && { captured: result.element.captured }),
+        },
+    };
+}
+/**
+ * Make sure `--follow` has a directory to write frames to.
+ *
+ * @param dirPath - Directory the user gave
+ * @param fs - File system module
+ * @throws CommandError (81) when the path is a file, or naming the problem when it cannot be created
+ */
+function ensureDirectory(dirPath, fs) {
+    if (fs.existsSync(dirPath) && !fs.statSync(dirPath).isDirectory()) {
+        throw new CommandError(`--follow needs a directory, but ${dirPath} is a file`, { suggestion: 'Give a directory for the frames, e.g. bdg dom screenshot ./frames --follow' }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    try {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+    catch (error) {
+        throw outputPathError(dirPath, error);
+    }
+}
+function formatFrameFilename(frameNumber, format) {
+    return `${String(frameNumber).padStart(3, '0')}.${format}`;
+}
+async function handlePageScreenshot(outputPath, options) {
+    await runCommand(async () => {
+        const screenshotOptions = buildPageScreenshotOptions(options);
+        const result = await capturePageScreenshot(outputPath, screenshotOptions);
+        return { success: true, data: result };
+    }, options, formatDomScreenshot);
+}
+async function handleElementScreenshot(outputPath, options) {
+    await runCommand(async () => {
+        const nodeRef = await resolveElementNodeId(options);
+        const screenshotOptions = buildElementScreenshotOptions(options);
+        const result = await captureElementScreenshot(outputPath, nodeRef, screenshotOptions);
+        const elementResult = addElementInfo(result, options);
+        return { success: true, data: elementResult };
+    }, options, formatDomScreenshot);
+}
+async function captureSequenceFrame(outputPath, options) {
+    if (hasElementTarget(options)) {
+        const nodeRef = await resolveElementNodeId(options);
+        const elementOptions = buildElementScreenshotOptions(options);
+        await captureElementScreenshot(outputPath, nodeRef, elementOptions);
+    }
+    else {
+        const pageOptions = buildPageScreenshotOptions(options);
+        await capturePageScreenshot(outputPath, pageOptions);
+    }
+}
+async function handleSequenceCapture(outputDir, options) {
+    const fs = await import('fs');
+    const path = await import('path');
+    const absoluteDir = path.resolve(outputDir);
+    ensureDirectory(absoluteDir, fs);
+    const intervalRule = positiveIntRule({ name: '--interval', min: 100, max: 60000, default: 1000 });
+    const limitRule = positiveIntRule({ name: '--limit', min: 1, max: 10000, required: false });
+    const interval = intervalRule.validate(options.interval);
+    const limit = options.limit ? limitRule.validate(options.limit) : 0;
+    const format = options.format ?? 'png';
+    let frameCount = 0;
+    let stopping = false;
+    process.once('SIGINT', () => {
+        stopping = true;
+    });
+    console.error(`Capturing to ${absoluteDir} every ${interval}ms...`);
+    while (!stopping) {
+        frameCount++;
+        const filename = formatFrameFilename(frameCount, format);
+        const outputPath = path.join(absoluteDir, filename);
+        try {
+            await captureSequenceFrame(outputPath, options);
+        }
+        catch (error) {
+            reportSequenceError(error, frameCount - 1, options.json ?? false);
+        }
+        if (options.json) {
+            console.log(JSON.stringify(buildSuccessResponse({ frame: frameCount, path: outputPath })));
+        }
+        else {
+            log.info(`Frame ${frameCount}: ${filename}`);
+        }
+        if (limit > 0 && frameCount >= limit)
+            break;
+        await delay(interval);
+    }
+    console.error(`Captured ${frameCount} frames`);
+    process.exit(EXIT_CODES.SUCCESS);
+}
+/**
+ * End a capture sequence on an error (e.g. the element disappeared): print
+ * it (one JSON line with `--json`, like the frames) and exit with its code.
+ *
+ * @param error - Capture error
+ * @param captured - Frames captured before it
+ * @param json - JSON output
+ */
+function reportSequenceError(error, captured, json) {
+    const exitCode = error instanceof CommandError ? error.exitCode : EXIT_CODES.SOFTWARE_ERROR;
+    const suggestion = error instanceof CommandError && typeof error.metadata['suggestion'] === 'string'
+        ? error.metadata['suggestion']
+        : undefined;
+    const message = getErrorMessage(error);
+    if (json) {
+        console.log(JSON.stringify(OutputBuilder.buildJsonError(message, { exitCode, ...(suggestion && { suggestion }) })));
+    }
+    else {
+        console.error(genericError(message));
+        if (suggestion)
+            console.error(suggestion);
+    }
+    console.error(`Captured ${captured} frames`);
+    process.exit(exitCode);
+}
+/**
+ * Reject options that would be ignored: `--selector` with `--index` (the
+ * index already names an element), and `--quality` for a PNG.
+ *
+ * @param outputPath - File to write
+ * @param options - Command options
+ * @throws CommandError (81) for a conflict
+ */
+function assertScreenshotOptions(outputPath, options) {
+    let message;
+    if (options.selector !== undefined && options.index !== undefined) {
+        message = conflictingOptionsMessage('--selector', '--index');
+    }
+    else if (options.quality !== undefined &&
+        !options.follow &&
+        resolveImageFormat(outputPath, options.format) === 'png') {
+        message = '--quality applies to JPEG only; this screenshot is a PNG';
+    }
+    if (message)
+        throw new CommandError(message, {}, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Fold the optional positional target (`bdg dom screenshot out.png "#sel"`,
+ * or an index from a query) into `--selector` / `--index`.
+ *
+ * @param target - Positional selector or index, if given
+ * @param options - Command options
+ * @returns Options with the target as `selector` or `index`
+ * @throws CommandError (81) when the option names a different element
+ */
+export function withPositionalTarget(target, options) {
+    if (target === undefined)
+        return options;
+    const isIndex = /^\d+$/.test(target);
+    const key = isIndex ? 'index' : 'selector';
+    const value = isIndex ? Number(target) : target;
+    const given = options[key];
+    if (given !== undefined && given !== value) {
+        const err = conflictingTargetError(`--${key} ${String(given)}`, target);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return { ...options, [key]: value };
+}
+/**
+ * Handle `bdg dom screenshot <path> [selector|index]`.
+ *
+ * Dispatches to page, element, or sequence capture based on flags.
+ */
+export async function handleDomScreenshot(outputPath, target, commandOptions) {
+    const options = withPositionalTarget(target, commandOptions);
+    assertScreenshotOptions(outputPath, options);
+    if (options.follow) {
+        await handleSequenceCapture(outputPath, options);
+        return;
+    }
+    assertFilePath(outputPath);
+    const captureOptions = { ...options, format: resolveImageFormat(outputPath, options.format) };
+    if (hasElementTarget(captureOptions)) {
+        await handleElementScreenshot(outputPath, captureOptions);
+        return;
+    }
+    await handlePageScreenshot(outputPath, captureOptions);
+}
+//# sourceMappingURL=screenshot.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * Shared utilities for rendering semantic (a11y + DOM context) output.
+ *
+ * Used by both `dom query` and `dom get` to format accessibility nodes with
+ * their surrounding DOM context and to fall back gracefully when only one
+ * of the two data sources is available.
+ */
+import type { DomContext } from './helpers/index.js';
+import type { A11yNode } from '../../types.js';
+/**
+ * Accessibility node paired with its surrounding DOM context for display.
+ */
+export interface SemanticNodeWithContext {
+    node: A11yNode;
+    domContext: DomContext | null;
+}
+/**
+ * Format a semantic node together with DOM context for human-readable output.
+ *
+ * The role line is followed by up to 500 characters of the element's text
+ * (all of it with `dom get --full`) when it is longer than the one-line
+ * preview, or, for an element without text or name, what it holds.
+ *
+ * @param data - Accessibility node and optional DOM context
+ * @returns Role line, plus a text line for elements with longer text
+ */
+export declare function formatSemanticNodeWithContext(data: SemanticNodeWithContext): string;
+/**
+ * Resolve an a11y node, falling back to a DOM-synthesized one when only
+ * DOM context is available. Returns null when neither source can produce one.
+ *
+ * @param a11yNode - Accessibility node, if any
+ * @param domContext - DOM context, if any
+ * @param nodeId - CDP nodeId for synthesis
+ */
+export declare function resolveNodeWithFallback(a11yNode: A11yNode | null, domContext: DomContext | null, nodeId: number | undefined): A11yNode | null;
+//# sourceMappingURL=semanticUtils.d.ts.map

package/dist/commands/dom/semanticUtils.js

@@ -0,0 +1,98 @@
+/**
+ * Shared utilities for rendering semantic (a11y + DOM context) output.
+ *
+ * Used by both `dom query` and `dom get` to format accessibility nodes with
+ * their surrounding DOM context and to fall back gracefully when only one
+ * of the two data sources is available.
+ */
+import { synthesizeA11yNode } from '../../telemetry/roleInference.js';
+import { joinLines } from '../../ui/formatting.js';
+import { elementTextLine, emptyElementLine } from '../../ui/messages/commands.js';
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function buildRoleText(node) {
+    if (node.role.toLowerCase() === 'heading' && node.properties?.['level'] !== undefined) {
+        const level = node.properties['level'];
+        const levelNum = typeof level === 'number' ? level : Number(level);
+        if (!isNaN(levelNum)) {
+            return `[Heading L${levelNum}]`;
+        }
+    }
+    return `[${capitalize(node.role)}]`;
+}
+function buildContextText(node, domContext) {
+    if (node.name) {
+        return ` "${node.name}"`;
+    }
+    if (domContext) {
+        const tagPart = `<${domContext.tag}`;
+        const classPart = domContext.classes && domContext.classes.length > 0
+            ? `.${domContext.classes.slice(0, 3).join('.')}`
+            : '';
+        const previewPart = domContext.preview && !domContext.text ? ` "${domContext.preview}"` : '';
+        return ` ${tagPart}${classPart}>${previewPart}`;
+    }
+    return '';
+}
+function buildPropertiesText(node) {
+    const props = [];
+    if (node.value !== undefined && node.value !== '')
+        props.push(`value: "${node.value}"`);
+    const checked = node.properties?.['checked'];
+    if (checked !== undefined) {
+        props.push(checked === 'mixed' ? 'partly checked' : checked ? 'checked' : 'unchecked');
+    }
+    const expanded = node.properties?.['expanded'];
+    if (expanded !== undefined)
+        props.push(expanded ? 'expanded' : 'collapsed');
+    if (node.focusable)
+        props.push('focusable');
+    if (node.focused)
+        props.push('focused');
+    if (node.disabled)
+        props.push('disabled');
+    if (node.required)
+        props.push('required');
+    return props.length > 0 ? ` (${props.join(', ')})` : '';
+}
+/**
+ * Format a semantic node together with DOM context for human-readable output.
+ *
+ * The role line is followed by up to 500 characters of the element's text
+ * (all of it with `dom get --full`) when it is longer than the one-line
+ * preview, or, for an element without text or name, what it holds.
+ *
+ * @param data - Accessibility node and optional DOM context
+ * @returns Role line, plus a text line for elements with longer text
+ */
+export function formatSemanticNodeWithContext(data) {
+    const { node, domContext } = data;
+    const roleText = buildRoleText(node);
+    const contextText = buildContextText(node, domContext);
+    const propsText = buildPropertiesText(node);
+    const inferredText = node.inferred ? ' (inferred from DOM)' : '';
+    const line = `${roleText}${contextText}${propsText}${inferredText}`;
+    if (domContext?.text)
+        return joinLines(line, elementTextLine(domContext.text));
+    if (domContext?.childCount !== undefined && !node.name) {
+        return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount));
+    }
+    return line;
+}
+/**
+ * Resolve an a11y node, falling back to a DOM-synthesized one when only
+ * DOM context is available. Returns null when neither source can produce one.
+ *
+ * @param a11yNode - Accessibility node, if any
+ * @param domContext - DOM context, if any
+ * @param nodeId - CDP nodeId for synthesis
+ */
+export function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
+    if (a11yNode)
+        return a11yNode;
+    if (domContext && nodeId)
+        return synthesizeA11yNode(domContext, nodeId);
+    return null;
+}
+//# sourceMappingURL=semanticUtils.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * `bdg dom wait [selector]` - wait until elements appear, become visible,
+ * contain a text or are gone, and/or the page has loaded, instead of
+ * polling with `sleep` and `dom eval`.
+ */
+import type { Command } from 'commander';
+/**
+ * Register `bdg dom wait`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerWaitCommand(dom: Command): void;
+//# sourceMappingURL=wait.d.ts.map

package/dist/commands/dom/wait.js

@@ -0,0 +1,83 @@
+/**
+ * `bdg dom wait [selector]` - wait until elements appear, become visible,
+ * contain a text or are gone, and/or the page has loaded, instead of
+ * polling with `sleep` and `dom eval`.
+ */
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { integerOption } from '../shared/validation.js';
+import { waitTargetRequiredError } from '../../errors/messages.js';
+import { domWait } from '../../ipc/client.js';
+import { WAIT_HELP_EXAMPLES, waitMetMessage } from '../../ui/messages/commands.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { filterDefined } from '../../utils/objects.js';
+/** Default --timeout */
+const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+/** Longest --timeout (10 minutes) */
+const MAX_WAIT_TIMEOUT_MS = 600_000;
+/**
+ * Register `bdg dom wait`.
+ *
+ * @param dom - The `dom` command group
+ */
+export function registerWaitCommand(dom) {
+    dom
+        .command('wait')
+        .description('Wait until elements appear, become visible, contain a text or are gone (or the page loads)')
+        .argument('[selector]', 'CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); optional with --load')
+        .option('--text <text>', 'A match must contain this text (case-insensitive)')
+        .option('--visible', 'Only count visible matches')
+        .option('--gone', 'Wait until no element matches (none visible, with --visible)')
+        .option('--load', 'Also wait for the page to finish loading (document.readyState complete)')
+        .option('--timeout <ms>', 'Give up after this many milliseconds (exit 102)', integerOption(1, MAX_WAIT_TIMEOUT_MS), DEFAULT_WAIT_TIMEOUT_MS)
+        .addOption(jsonOption())
+        .addHelpText('after', WAIT_HELP_EXAMPLES)
+        .action(async (selector, options) => {
+        await runCommand(() => waitFor(selector, options), options, formatWait);
+    });
+}
+/**
+ * Validate the options and ask the daemon to wait.
+ *
+ * @param selector - Selector, if given
+ * @param options - Command options
+ * @returns Command result
+ */
+async function waitFor(selector, options) {
+    const needsSelector = options.text !== undefined || options.gone === true || !options.load;
+    if (selector === undefined && needsSelector) {
+        const err = waitTargetRequiredError();
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: err.suggestion },
+        };
+    }
+    const response = await domWait({
+        ...filterDefined({ selector, text: options.text }),
+        ...(options.gone && { gone: true }),
+        ...(options.visible && { visible: true }),
+        ...(options.load && { load: true }),
+        timeout: options.timeout,
+    });
+    if (response.status === 'error' || !response.data) {
+        return {
+            success: false,
+            error: response.error ?? 'Failed to wait',
+            exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+            ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+        };
+    }
+    return { success: true, data: response.data };
+}
+/**
+ * One line for human output.
+ *
+ * @param data - What the page showed when the condition was met
+ * @returns e.g. `✓ #finish visible after 5.1s`
+ */
+function formatWait(data) {
+    return waitMetMessage(data, data.elapsedMs);
+}
+//# sourceMappingURL=wait.js.map