browser-debugger-cli 0.8.0 → 0.10.0

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

@@ -0,0 +1,15 @@
+/**
+ * `bdg dom inspect <selector|index>` - what one element looks like, without a
+ * screenshot: its box, layout (and its place in the parent), typography with
+ * the rendered font and contrast, fills, borders, effects, CSS state,
+ * pseudo-elements and a compact child tree, as grouped lines (`--json`:
+ * Figma-aligned fields).
+ */
+import { type Command } from 'commander';
+/**
+ * Register `bdg dom inspect`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerInspectCommand(dom: Command): void;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/commands/dom/inspect.js

@@ -0,0 +1,82 @@
+/**
+ * `bdg dom inspect <selector|index>` - what one element looks like, without a
+ * screenshot: its box, layout (and its place in the parent), typography with
+ * the rendered font and contrast, fills, borders, effects, CSS state,
+ * pseudo-elements and a compact child tree, as grouped lines (`--json`:
+ * Figma-aligned fields).
+ */
+import { Option } from 'commander';
+import { runElementCommand } from './helpers/runElementCommand.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
+import { cssPropertiesOption, integerOption } from '../shared/validation.js';
+import { domInspect } from '../../ipc/client.js';
+import { DEFAULT_TREE_DEPTH, DEFAULT_TREE_LIMIT } from '../../runtime/dom/inspectTree.js';
+import { formatInspect } from '../../ui/formatters/inspect.js';
+import { INSPECT_OUTPUT_LEGEND } from '../../ui/messages/commands.js';
+import { filterDefined } from '../../utils/objects.js';
+/**
+ * Register `bdg dom inspect`.
+ *
+ * @param dom - The `dom` command group
+ */
+export function registerInspectCommand(dom) {
+    dom
+        .command('inspect')
+        .description('What one element looks like without a screenshot: box, layout, font (rendered, contrast), colors, borders, effects, pseudo-elements and child tree')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
+        .option('--index <n>', 'Which match to inspect (0-based; default: the first rendered one)', integerOption(0))
+        .option('--tree <depth>', `Child tree depth (default ${DEFAULT_TREE_DEPTH}; 0 for none)`, integerOption(0, 10))
+        .option('--tree-limit <n>', `Child tree rows at most (default ${DEFAULT_TREE_LIMIT})`, integerOption(1, 500))
+        .addOption(new Option('--all', 'Every computed property that is not its default, collapsed into shorthands, instead of the groups').conflicts('props'))
+        .addHelpText('after', INSPECT_OUTPUT_LEGEND)
+        .option('--props <names>', "Only these properties, computed and normalized (comma-separated, e.g. padding,color,--brand; '--*' or '--bs-btn-*' lists custom properties)", cssPropertiesOption)
+        .addOption(new Option('--rules', 'Also show which CSS rule sets each shown property (selector, file:line, what it overrides); with --props, those properties').conflicts('all'))
+        .addOption(new Option('--why <property>', 'Every declaration of one property: the one that applies and those it overrides (e.g. --why color)')
+        .conflicts('all')
+        .argParser(propertyOption))
+        .option('--no-hints', 'Skip the check for declarations that have no effect')
+        .addOption(jsonOption())
+        .action(async (selectorOrIndex, options) => {
+        await runCommand(() => inspectTarget(selectorOrIndex, options), options, formatInspect);
+    });
+}
+/**
+ * Parse `--why`: a property name, lowercased (custom properties as given).
+ *
+ * @param value - Property name
+ * @returns Name
+ */
+function propertyOption(value) {
+    return value.startsWith('--') ? value.trim() : value.trim().toLowerCase();
+}
+/**
+ * Resolve the target and ask the daemon to inspect it.
+ *
+ * @param selectorOrIndex - CSS selector or cached query index
+ * @param options - Command options
+ * @returns Command result
+ */
+async function inspectTarget(selectorOrIndex, options) {
+    return runElementCommand({
+        selectorOrIndex,
+        index: options.index,
+        buildRequest: (target) => ({
+            ...target,
+            ...filterDefined({
+                tree: options.tree,
+                treeLimit: options.treeLimit,
+                all: options.all,
+                props: options.props,
+                rules: options.rules,
+                why: options.why,
+                ...(options.hints === false && { hints: false }),
+            }),
+        }),
+        call: domInspect,
+        command: 'inspect',
+        action: 'inspect the element',
+        failureSuggestion: 'Verify the selector matches an element: bdg dom query "<selector>"',
+    });
+}
+//# sourceMappingURL=inspect.js.map

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

@@ -0,0 +1,14 @@
+/**
+ * `bdg dom layout <selector|index>` - where elements are on the page and
+ * whether a user can see them, without a screenshot: page and viewport
+ * coordinates, size, viewport position (visible, partly, above/below the
+ * fold, hidden), what covers them and the styles that decide how they show.
+ */
+import type { Command } from 'commander';
+/**
+ * Register `bdg dom layout`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerLayoutCommand(dom: Command): void;
+//# sourceMappingURL=layout.d.ts.map

package/dist/commands/dom/layout.js

@@ -0,0 +1,54 @@
+/**
+ * `bdg dom layout <selector|index>` - where elements are on the page and
+ * whether a user can see them, without a screenshot: page and viewport
+ * coordinates, size, viewport position (visible, partly, above/below the
+ * fold, hidden), what covers them and the styles that decide how they show.
+ */
+import { DomElementResolver } from './DomElementResolver.js';
+import { runElementCommand } from './helpers/runElementCommand.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
+import { integerOption } from '../shared/validation.js';
+import { domLayout } from '../../ipc/client.js';
+import { formatLayout } from '../../ui/formatters/layout.js';
+/**
+ * Register `bdg dom layout`.
+ *
+ * @param dom - The `dom` command group
+ */
+export function registerLayoutCommand(dom) {
+    dom
+        .command('layout')
+        .description('Positions, sizes and visibility of elements (above/below the fold, hidden, covered) without a screenshot')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
+        .option('--index <n>', 'Only this match of the selector (0-based)', integerOption(0))
+        .addOption(jsonOption())
+        .action(async (selectorOrIndex, options) => {
+        await runCommand(() => measureLayout(selectorOrIndex, options), options, formatLayout);
+    });
+}
+/**
+ * Resolve the target and ask the daemon to measure it.
+ *
+ * @param selectorOrIndex - CSS selector or cached query index
+ * @param options - Command options
+ * @returns Command result; an index argument is reported as the element's `index`
+ */
+async function measureLayout(selectorOrIndex, options) {
+    const result = await runElementCommand({
+        selectorOrIndex,
+        index: options.index,
+        buildRequest: (target) => target,
+        call: domLayout,
+        command: 'layout',
+        action: 'measure the layout',
+        failureSuggestion: 'Verify the selector matches an element: bdg dom query "<selector>"',
+    });
+    if (!result.data || !DomElementResolver.getInstance().isNumericIndex(selectorOrIndex)) {
+        return result;
+    }
+    const index = Number(selectorOrIndex);
+    const elements = result.data.elements.map((element) => ({ ...element, index }));
+    return { ...result, data: { ...result.data, elements } };
+}
+//# sourceMappingURL=layout.js.map

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

@@ -4,7 +4,11 @@
  *
  * 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.
+ * 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';
 /**

package/dist/commands/dom/listeners.js

@@ -4,12 +4,16 @@
  *
  * 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.
+ * 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 { jsonOption, SELECTOR_OR_INDEX_ARGUMENT } from '../shared/commonOptions.js';
 import { eventTypesOption, integerOption } from '../shared/validation.js';
 import { domListeners } from '../../ipc/client.js';
 import { formatListeners } from '../../ui/formatters/listeners.js';
@@ -22,9 +26,10 @@ 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)')
+        .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
         .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)', eventTypesOption)
+        .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));
@@ -41,8 +46,13 @@ async function listElementListeners(selectorOrIndex, options) {
     const result = await runElementCommand({
         selectorOrIndex,
         index: options.index,
-        buildRequest: (target) => ({ ...target, ...(options.type && { types: options.type }) }),
+        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>"',
     });

package/dist/commands/dom/query.js

@@ -1,9 +1,8 @@
 /**
  * `bdg dom query` — find elements by CSS selector and populate the query cache.
  */
-import { queryDOMElements } from './helpers/index.js';
+import { noMatchesError, queryDOMElements } from './helpers/index.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { noNodesFoundError } from '../../errors/messages.js';
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { formatDomQuery } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
@@ -21,7 +20,7 @@ export async function handleDomQuery(selector, options) {
         const cache = QueryCacheManager.getInstance();
         if (result.count === 0) {
             await cache.clear();
-            const err = noNodesFoundError(selector);
+            const err = await noMatchesError(selector);
             return {
                 success: false,
                 error: err.message,

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

@@ -13,9 +13,19 @@ import type { DomScreenshotCommandOptions } from '../shared/optionTypes.js';
  */
 export declare function resolveImageFormat(outputPath: string, requested?: 'png' | 'jpeg'): 'png' | 'jpeg';
 /**
- * Handle `bdg dom screenshot <path>`.
+ * 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, options: DomScreenshotCommandOptions): Promise<void>;
+export declare function handleDomScreenshot(outputPath: string, target: string | undefined, commandOptions: DomScreenshotCommandOptions): Promise<void>;
 //# sourceMappingURL=screenshot.d.ts.map

package/dist/commands/dom/screenshot.js

@@ -8,7 +8,7 @@ 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, genericError } from '../../errors/messages.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';
@@ -90,6 +90,7 @@ function addElementInfo(result, options) {
             ...(options.selector !== undefined && { selector: options.selector }),
             ...(options.index !== undefined && { index: options.index }),
             bounds,
+            ...(result.element?.captured && { captured: result.element.captured }),
         },
     };
 }
@@ -227,11 +228,34 @@ function assertScreenshotOptions(outputPath, options) {
         throw new CommandError(message, {}, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
- * Handle `bdg dom screenshot <path>`.
+ * 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, options) {
+export async function handleDomScreenshot(outputPath, target, commandOptions) {
+    const options = withPositionalTarget(target, commandOptions);
     assertScreenshotOptions(outputPath, options);
     if (options.follow) {
         await handleSequenceCapture(outputPath, options);

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

@@ -5,7 +5,7 @@
  * 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 { DomContext } from './helpers/index.js';
 import type { A11yNode } from '../../types.js';
 /**
  * Accessibility node paired with its surrounding DOM context for display.
@@ -17,8 +17,14 @@ export interface SemanticNodeWithContext {
 /**
  * Format a semantic node together with DOM context for human-readable output.
  *
+ * The role line names the element's key attributes (an image's file name, a
+ * link's href, a field's type and name), like `dom query` does, and 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 One-line formatted string
+ * @returns Role line, plus a text line for elements with longer text
  */
 export declare function formatSemanticNodeWithContext(data: SemanticNodeWithContext): string;
 /**
@@ -31,14 +37,14 @@ export declare function formatSemanticNodeWithContext(data: SemanticNodeWithCont
  */
 export declare function resolveNodeWithFallback(a11yNode: A11yNode | null, domContext: DomContext | null, nodeId: number | undefined): A11yNode | null;
 /**
- * Look up a single element by selector to produce its nodeId and DOM context.
+ * The accessibility node with its value masked when the element holds a
+ * secret (`domContext.sensitive`): Chrome reports a password field's value
+ * as one bullet per character, and a field switched to text by a "show
+ * password" button in clear.
  *
- * Used by `dom get` (semantic mode) when the accessibility tree has no node
- * for the selector — the selector-based DOM context allows us to synthesize
- * one.
+ * @param node - Accessibility node
+ * @param domContext - DOM context of the same element
+ * @returns The node, with {@link MASKED_VALUE} as its value for a secret
  */
-export declare function queryDomContextBySelector(selector: string): Promise<{
-    nodeId: number | undefined;
-    domContext: DomContext | null;
-}>;
+export declare function withSecretMasked(node: A11yNode, domContext: DomContext | null): A11yNode;
 //# sourceMappingURL=semanticUtils.d.ts.map

package/dist/commands/dom/semanticUtils.js

@@ -5,8 +5,11 @@
  * their surrounding DOM context and to fall back gracefully when only one
  * of the two data sources is available.
  */
-import { getDomContext, resolveBackendNodeIds, } from './helpers/index.js';
+import { MASKED_VALUE } from '../../runtime/dom/elementInfo.js';
 import { synthesizeA11yNode } from '../../telemetry/roleInference.js';
+import { keyAttributeItems } from '../../ui/formatters/keyAttributes.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);
 }
@@ -29,11 +32,32 @@ function buildContextText(node, domContext) {
         const classPart = domContext.classes && domContext.classes.length > 0
             ? `.${domContext.classes.slice(0, 3).join('.')}`
             : '';
-        const previewPart = domContext.preview ? ` "${domContext.preview}"` : '';
+        const previewPart = domContext.preview && !domContext.text ? ` "${domContext.preview}"` : '';
         return ` ${tagPart}${classPart}>${previewPart}`;
     }
     return '';
 }
+/**
+ * Key attributes of the element (src, href, a field's type and name, ...),
+ * leaving out what the role line already shows: values equal to the
+ * accessible name (an image's alt, a field's placeholder) and the value
+ * when the accessibility node has one.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context with the key attributes
+ * @returns ` src="…/logo.png"`-style text, or empty
+ */
+function buildKeyAttributesText(node, domContext) {
+    if (!domContext?.attributes)
+        return '';
+    const shown = Object.entries(domContext.attributes)
+        .filter(([, value]) => Boolean(node.name) && value === node.name)
+        .map(([name]) => name);
+    if (node.value !== undefined && node.value !== '')
+        shown.push('value');
+    const items = keyAttributeItems(domContext.tag, domContext.attributes, new Set(shown));
+    return items.length > 0 ? ` ${items.join(' ')}` : '';
+}
 function buildPropertiesText(node) {
     const props = [];
     if (node.value !== undefined && node.value !== '')
@@ -58,16 +82,29 @@ function buildPropertiesText(node) {
 /**
  * Format a semantic node together with DOM context for human-readable output.
  *
+ * The role line names the element's key attributes (an image's file name, a
+ * link's href, a field's type and name), like `dom query` does, and 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 One-line formatted string
+ * @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 keysText = buildKeyAttributesText(node, domContext);
     const propsText = buildPropertiesText(node);
     const inferredText = node.inferred ? ' (inferred from DOM)' : '';
-    return `${roleText}${contextText}${propsText}${inferredText}`;
+    const line = `${roleText}${contextText}${keysText}${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
@@ -79,24 +116,24 @@ export function formatSemanticNodeWithContext(data) {
  */
 export function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
     if (a11yNode)
-        return a11yNode;
+        return withSecretMasked(a11yNode, domContext);
     if (domContext && nodeId)
         return synthesizeA11yNode(domContext, nodeId);
     return null;
 }
 /**
- * Look up a single element by selector to produce its nodeId and DOM context.
+ * The accessibility node with its value masked when the element holds a
+ * secret (`domContext.sensitive`): Chrome reports a password field's value
+ * as one bullet per character, and a field switched to text by a "show
+ * password" button in clear.
  *
- * Used by `dom get` (semantic mode) when the accessibility tree has no node
- * for the selector — the selector-based DOM context allows us to synthesize
- * one.
+ * @param node - Accessibility node
+ * @param domContext - DOM context of the same element
+ * @returns The node, with {@link MASKED_VALUE} as its value for a secret
  */
-export async function queryDomContextBySelector(selector) {
-    const [backendNodeId] = await resolveBackendNodeIds([selector]);
-    if (backendNodeId === undefined) {
-        return { nodeId: undefined, domContext: null };
-    }
-    const domContext = await getDomContext({ backendNodeId });
-    return { nodeId: backendNodeId, domContext };
+export function withSecretMasked(node, domContext) {
+    if (!domContext?.sensitive || !node.value)
+        return node;
+    return { ...node, value: MASKED_VALUE };
 }
 //# 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

package/dist/commands/helpJson.js

@@ -97,8 +97,8 @@ function convertCommand(command) {
 function generateRuntimeState() {
     const sessionActive = readLiveDaemonPid() !== null;
     const availableCommands = sessionActive
-        ? ['peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'stop']
-        : ['bdg <url>', 'cleanup', '--help', '--version'];
+        ? ['peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'sessions', 'stop']
+        : ['bdg <url>', 'sessions', 'cleanup', '--help', '--version'];
     return {
         sessionActive,
         daemonRunning: sessionActive,