browser-debugger-cli 0.8.0 → 0.9.0

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

@@ -6,14 +6,15 @@
  * - Raw: full HTML, attributes, and classes
  */
 import type { DomGetCommandOptions } from '../shared/optionTypes.js';
+/** What `bdg dom get` reads without a selector */
+export declare const DOM_GET_DEFAULT_SELECTOR = "body";
 /**
- * Handle `bdg dom get [selectorOrIndex] [--node-id <id>]`.
+ * Handle `bdg dom get [selectorOrIndex] [--index <n>] [--node-id <id>]`.
  *
- * `--node-id` reads that node directly (raw output); otherwise dispatches to
- * the selector or index handler based on whether the argument parses as a
- * numeric index.
+ * `--node-id` reads that node directly (raw output); otherwise reads a cached
+ * index or a selector's match (`body` without an argument).
  *
- * @param selectorOrIndex - CSS selector or cached index (optional with --node-id)
+ * @param selectorOrIndex - CSS selector or cached index (default: body)
  * @param options - Command options
  */
 export declare function handleDomGet(selectorOrIndex: string | undefined, options: DomGetCommandOptions): Promise<void>;

package/dist/commands/dom/get.js

@@ -6,86 +6,93 @@
  * - Raw: full HTML, attributes, and classes
  */
 import { DomElementResolver } from './DomElementResolver.js';
-import { getDOMElements, getDomContext, resolveA11yNodeForSelector, } from './helpers/index.js';
-import { formatSemanticNodeWithContext, queryDomContextBySelector, resolveNodeWithFallback, } from './semanticUtils.js';
+import { getDOMElements, getDomContext, selectMatch, } from './helpers/index.js';
+import { formatSemanticNodeWithContext, resolveNodeWithFallback, } from './semanticUtils.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { CommandError } from '../../errors/index.js';
-import { elementAtIndexNotFoundError, conflictingOptionsMessage, optionRequiresMessage, missingArgumentError, noNodesFoundError, } from '../../errors/messages.js';
+import { conflictingOptionsMessage, indexWithIndexOptionError, nodeIdNotFoundError, optionRequiresMessage, } from '../../errors/messages.js';
 import { resolveA11yNode } from '../../telemetry/a11y.js';
 import { formatDomGet } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
-async function handleIndexGetRaw(index, options) {
-    const resolver = DomElementResolver.getInstance();
-    await runCommand(async () => {
-        const targetNode = await resolver.getNodeIdForIndex(index);
-        const getOptions = filterDefined({ nodeId: targetNode.nodeId });
-        const result = await getDOMElements(getOptions);
-        return { success: true, data: result };
-    }, options, formatDomGet);
-}
-async function handleIndexGetSemantic(index, options) {
+/** What `bdg dom get` reads without a selector */
+export const DOM_GET_DEFAULT_SELECTOR = 'body';
+/**
+ * The element to read: a cached index or a selector match.
+ *
+ * @param selectorOrIndex - CSS selector or cached index
+ * @param index - Which match of the selector (0-based)
+ * @returns Backend node id
+ * @throws CommandError (83) no match, (81) index out of range, (87) stale cached index
+ */
+async function targetNodeId(selectorOrIndex, index) {
     const resolver = DomElementResolver.getInstance();
-    await runCommand(async () => {
-        const targetNode = await resolver.getNodeIdForIndex(index);
-        const ref = { backendNodeId: targetNode.nodeId };
-        const [a11yNode, domContext] = await Promise.all([resolveA11yNode(ref), getDomContext(ref)]);
-        const node = resolveNodeWithFallback(a11yNode, domContext, targetNode.nodeId);
-        if (!node) {
-            const err = elementAtIndexNotFoundError(index, 'cached query');
-            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
-        }
-        return { success: true, data: { node, domContext } };
-    }, options, formatSemanticNodeWithContext);
-}
-async function handleIndexGet(index, options) {
-    if (options.raw) {
-        await handleIndexGetRaw(index, options);
+    if (resolver.isNumericIndex(selectorOrIndex)) {
+        return (await resolver.getNodeIdForIndex(Number(selectorOrIndex))).nodeId;
     }
-    else {
-        await handleIndexGetSemantic(index, options);
+    return selectMatch(selectorOrIndex, index ?? 0);
+}
+/**
+ * Semantic view of one element: its accessibility node (or one inferred from
+ * the DOM) and its DOM context.
+ *
+ * @param backendNodeId - The element
+ * @param full - All of its text instead of the first 500 characters
+ * @returns Node and context
+ * @throws CommandError (83) when the element is gone
+ */
+async function semanticElement(backendNodeId, full) {
+    const ref = { backendNodeId };
+    const [a11yNode, domContext] = await Promise.all([
+        resolveA11yNode(ref),
+        getDomContext(ref, { full }),
+    ]);
+    const node = resolveNodeWithFallback(a11yNode, domContext, backendNodeId);
+    if (!node) {
+        const err = nodeIdNotFoundError(backendNodeId);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
+    return { node, domContext };
 }
-async function handleSelectorGetRaw(selector, options) {
+/**
+ * Raw view: the element(s) with attributes and outer HTML.
+ *
+ * @param selectorOrIndex - CSS selector or cached index
+ * @param options - Command options (`--all`, `--index`)
+ */
+async function handleRawGet(selectorOrIndex, options) {
     await runCommand(async () => {
-        const getOptions = filterDefined({
-            selector,
-            all: options.all,
-            nth: options.nth,
-        });
-        const result = await getDOMElements(getOptions);
-        return { success: true, data: result };
+        const resolver = DomElementResolver.getInstance();
+        const getOptions = resolver.isNumericIndex(selectorOrIndex)
+            ? { nodeId: (await resolver.getNodeIdForIndex(Number(selectorOrIndex))).nodeId }
+            : filterDefined({
+                selector: selectorOrIndex,
+                all: options.all,
+                nth: matchIndex(options),
+            });
+        return { success: true, data: await getDOMElements(getOptions) };
     }, options, formatDomGet);
 }
-async function handleSelectorGetSemantic(selector, options) {
+/**
+ * Semantic view of the target.
+ *
+ * @param selectorOrIndex - CSS selector or cached index
+ * @param options - Command options (`--index`, `--full`)
+ */
+async function handleSemanticGet(selectorOrIndex, options) {
     await runCommand(async () => {
-        const a11yNode = await resolveA11yNodeForSelector(selector);
-        let domContext = null;
-        let nodeId;
-        if (a11yNode?.backendDOMNodeId) {
-            nodeId = a11yNode.backendDOMNodeId;
-            domContext = await getDomContext({ backendNodeId: nodeId });
-        }
-        else if (!a11yNode) {
-            const queryResult = await queryDomContextBySelector(selector);
-            nodeId = queryResult.nodeId;
-            domContext = queryResult.domContext;
-        }
-        const node = resolveNodeWithFallback(a11yNode, domContext, nodeId);
-        if (!node) {
-            const err = noNodesFoundError(selector);
-            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
-        }
-        return { success: true, data: { node, domContext } };
+        const backendNodeId = await targetNodeId(selectorOrIndex, matchIndex(options));
+        return { success: true, data: await semanticElement(backendNodeId, options.full === true) };
     }, options, formatSemanticNodeWithContext);
 }
-async function handleSelectorGet(selector, options) {
-    if (options.raw) {
-        await handleSelectorGetRaw(selector, options);
-    }
-    else {
-        await handleSelectorGetSemantic(selector, options);
-    }
+/**
+ * Which match of the selector to read: `--index`, or its alias `--nth`.
+ *
+ * @param options - Command options
+ * @returns 0-based index, undefined for the first match
+ */
+function matchIndex(options) {
+    return options.index ?? options.nth;
 }
 /**
  * Options of `dom get` that cannot be combined (one would be ignored).
@@ -98,22 +105,26 @@ function getOptionsConflict(selectorOrIndex, options) {
     if (options.nodeId !== undefined && selectorOrIndex !== undefined) {
         return conflictingOptionsMessage('--node-id', 'a selector or index');
     }
-    if (options.all && options.nth !== undefined) {
-        return conflictingOptionsMessage('--all', '--nth');
+    if (options.full && (options.raw || options.nodeId !== undefined)) {
+        return conflictingOptionsMessage('--full', options.raw ? '--raw' : '--node-id');
     }
-    if (!options.raw && (options.all || options.nth !== undefined)) {
-        return optionRequiresMessage(options.all ? '--all' : '--nth', '--raw');
+    if (options.index !== undefined && options.nth !== undefined) {
+        return conflictingOptionsMessage('--index', '--nth');
     }
+    if (options.all && matchIndex(options) !== undefined) {
+        return conflictingOptionsMessage('--all', '--index');
+    }
+    if (options.all && !options.raw)
+        return optionRequiresMessage('--all', '--raw');
     return null;
 }
 /**
- * Handle `bdg dom get [selectorOrIndex] [--node-id <id>]`.
+ * Handle `bdg dom get [selectorOrIndex] [--index <n>] [--node-id <id>]`.
  *
- * `--node-id` reads that node directly (raw output); otherwise dispatches to
- * the selector or index handler based on whether the argument parses as a
- * numeric index.
+ * `--node-id` reads that node directly (raw output); otherwise reads a cached
+ * index or a selector's match (`body` without an argument).
  *
- * @param selectorOrIndex - CSS selector or cached index (optional with --node-id)
+ * @param selectorOrIndex - CSS selector or cached index (default: body)
  * @param options - Command options
  */
 export async function handleDomGet(selectorOrIndex, options) {
@@ -126,16 +137,15 @@ export async function handleDomGet(selectorOrIndex, options) {
         await runCommand(async () => ({ success: true, data: await getDOMElements({ nodeId }) }), options, formatDomGet);
         return;
     }
-    if (selectorOrIndex === undefined) {
-        const err = missingArgumentError('bdg dom get <selector|index> or bdg dom get --node-id <id>');
+    const target = selectorOrIndex ?? DOM_GET_DEFAULT_SELECTOR;
+    if (DomElementResolver.getInstance().isNumericIndex(target) &&
+        matchIndex(options) !== undefined) {
+        const err = indexWithIndexOptionError(target, 'get');
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
-    const isNumericIndex = /^\d+$/.test(selectorOrIndex);
-    if (isNumericIndex) {
-        await handleIndexGet(parseInt(selectorOrIndex, 10), options);
-    }
-    else {
-        await handleSelectorGet(selectorOrIndex, options);
-    }
+    if (options.raw)
+        await handleRawGet(target, options);
+    else
+        await handleSemanticGet(target, options);
 }
 //# sourceMappingURL=get.js.map

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

@@ -5,7 +5,7 @@
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
  * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
  */
-export { queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, resolveA11yNodeForSelector, assertNodeAttached, } from './query.js';
+export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, } from './query.js';
 export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
 export type { DomQueryResult, DomGetResult, ScreenshotResult, DomGetOptions, ScreenshotOptions, DomContext, ElementBounds, } from '../../../types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -5,6 +5,6 @@
  * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
  * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
  */
-export { queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, resolveA11yNodeForSelector, assertNodeAttached, } from './query.js';
+export { documentReadyState, noMatchesError, queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, selectMatch, assertNodeAttached, } from './query.js';
 export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
 //# sourceMappingURL=index.js.map

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

@@ -9,15 +9,35 @@
  * bdg invocations. Selectors are matched in the page, including open shadow
  * roots and same-origin iframes, like a user sees the page.
  */
-import type { A11yNode, DomQueryResult, DomGetResult, DomGetOptions, DomContext, NodeRef } from '../../../types.js';
+import { type ErrorWithSuggestion, type NoMatchContext } from '../../../errors/messages.js';
+import type { DomQueryResult, DomGetResult, DomGetOptions, DomContext, IndexSource, NodeRef } from '../../../types.js';
 /**
- * Short text preview of an element's text: whitespace collapsed, cut on a
- * whole character (an emoji is never split, which would make JSON invalid).
+ * The "no nodes" error for a selector that matched nothing. One more page
+ * evaluation, on this failure path only, tells what the page says about it
+ * ({@link noMatchContext}).
  *
- * @param text - Element text as the page renders it
- * @returns Collapsed text, truncated to {@link PREVIEW_LENGTH} characters
+ * @param selector - Selector as given
+ * @returns Message and suggestion
  */
-export declare function textPreview(text: string): string;
+export declare function noMatchesError(selector: string): Promise<ErrorWithSuggestion>;
+/**
+ * What the page says about a selector that matched nothing, in one
+ * evaluation: whether it is still loading, how many elements match with the
+ * selector's `:visible` filters removed, whether it has cross-origin iframes
+ * or embeds (which selectors do not search), and for a selector that is a
+ * single id or class, the similar ids or classes on the page.
+ *
+ * @param selector - Selector as given
+ * @returns Context for {@link noNodesFoundError} (empty when the page did not answer)
+ */
+export declare function noMatchContext(selector: string): Promise<NoMatchContext>;
+/**
+ * The page's `document.readyState`, read for a failure that may come from a
+ * page still loading.
+ *
+ * @returns The state, or undefined when the page did not answer
+ */
+export declare function documentReadyState(): Promise<string | undefined>;
 /**
  * Query elements by selector for `bdg dom query`.
  *
@@ -26,12 +46,26 @@ export declare function textPreview(text: string): string;
  */
 export declare function queryDOMElements(selector: string): Promise<DomQueryResult>;
 /**
- * Get DOM context (tag, classes, text preview) for a node.
+ * Get DOM context (tag, classes, text preview) for a node: a one-line
+ * preview, and up to {@link ELEMENT_TEXT_LENGTH} characters of text when it
+ * is longer (all of it with `full`).
  *
  * @param ref - Node reference
+ * @param options - `full`: the whole text instead of its first 500 characters
  * @returns DOM context, or null if the node does not exist
  */
-export declare function getDomContext(ref: NodeRef): Promise<DomContext | null>;
+export declare function getDomContext(ref: NodeRef, options?: {
+    full?: boolean;
+}): Promise<DomContext | null>;
+/**
+ * One match of a selector.
+ *
+ * @param selector - CSS selector
+ * @param index - Which match (0-based)
+ * @returns Its backend node id
+ * @throws CommandError (83) when nothing matches, (81) for an index beyond the matches
+ */
+export declare function selectMatch(selector: string, index?: number): Promise<number>;
 /**
  * Get full details (attributes, outer HTML) for `bdg dom get --raw`.
  *
@@ -55,13 +89,6 @@ export declare function resolveSelector(selector: string): Promise<NodeRef>;
  * @returns Backend node id per selector, or undefined when it matches nothing
  */
 export declare function resolveBackendNodeIds(selectors: string[]): Promise<(number | undefined)[]>;
-/**
- * Accessibility node of the first element matching a selector.
- *
- * @param selector - CSS selector
- * @returns A11y node, or null when nothing matches or the node is not exposed
- */
-export declare function resolveA11yNodeForSelector(selector: string): Promise<A11yNode | null>;
 /**
  * Check that a cached element is still part of the current page.
  *
@@ -71,8 +98,8 @@ export declare function resolveA11yNodeForSelector(selector: string): Promise<A1
  * false for removed elements.
  *
  * @param backendNodeId - Backend node id from the query cache
- * @param index - Index the user gave, for the error message
+ * @param source - Index the user gave and the list it refers to, for the error message
  * @throws CommandError (87) when the element is gone
  */
-export declare function assertNodeAttached(backendNodeId: number, index?: number): Promise<void>;
+export declare function assertNodeAttached(backendNodeId: number, source?: IndexSource): Promise<void>;
 //# sourceMappingURL=query.d.ts.map