browser-debugger-cli 0.9.0 → 0.11.0

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

@@ -9,18 +9,19 @@
  * bdg invocations. Selectors are matched in the page, including open shadow
  * roots and same-origin iframes, like a user sees the page.
  */
+import { keyAttributes } from './keyAttributes.js';
 import { CommandError } from '../../../errors/index.js';
 import { noNodesFoundError, indexOutOfRangeError, eitherArgumentRequiredError, invalidSelectorError, nodeIdNotFoundError, operationFailedError, similarSelectorsLine, staleNodeError, } from '../../../errors/messages.js';
 import { callCDP } from '../../../ipc/client.js';
 import { ELEMENT_GEOMETRY_JS, VIEWPORT_SIZE_JS, classifyViewportPosition, } from '../../../runtime/dom/elementGeometry.js';
-import { ELEMENT_CONTEXT_JS, ELEMENT_TEXT_JS, ELEMENT_TEXT_LENGTH, textPreview, } from '../../../runtime/dom/elementInfo.js';
+import { ELEMENT_CONTEXT_JS, ELEMENT_STATE_JS, ELEMENT_TEXT_JS, ELEMENT_TEXT_LENGTH, textPreview, } from '../../../runtime/dom/elementInfo.js';
 import { DEEP_QUERY_JS, UNSEARCHED_CONTENT_JS, pageNamesJS, selectorArgsJS, } from '../../../runtime/dom/targetNode.js';
 import { createLogger } from '../../../ui/logging/index.js';
 import { sessionCommand } from '../../../ui/messages/sessionCommand.js';
 import { ConcurrencyLimiter } from '../../../utils/concurrency.js';
 import { getErrorMessage } from '../../../utils/errors.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
-import { parseSelectorFilters, withoutVisibleFilters } from '../../../utils/selectorFilters.js';
+import { leadingCompounds, parseSelectorFilters, withoutVisibleFilters, } from '../../../utils/selectorFilters.js';
 import { findSimilarNames, parseSingleNameSelector } from '../../../utils/suggestions.js';
 const log = createLogger('dom');
 /** Maximum concurrent CDP calls to avoid overwhelming the connection. */
@@ -113,6 +114,34 @@ async function withSelection(selector, use) {
 export async function noMatchesError(selector) {
     return noNodesFoundError(selector, await noMatchContext(selector));
 }
+/**
+ * Page-side index of the first leading compound that matches a shadow host
+ * (an element with an open shadow root, anywhere a selector reaches) while
+ * the selector after it finds something: then the selector only failed by
+ * crossing into the shadow root.
+ *
+ * @param compounds - Leading compounds of the selector
+ * @returns Expression evaluating to the index, or -1
+ */
+function shadowHostJS(compounds) {
+    const plain = compounds
+        .slice(0, MAX_HOST_COMPOUNDS)
+        .map((entry) => [withoutFilters(entry.compound), withoutFilters(entry.rest)]);
+    return `${JSON.stringify(plain)}.findIndex(([host, rest]) => { try { const deep = ${DEEP_QUERY_JS}; return deep(host, null).some((el) => el.shadowRoot) && deep(rest, null).length > 0; } catch (e) { return false; } })`;
+}
+/** Leading compounds checked for a shadow host (each check walks the page) */
+const MAX_HOST_COMPOUNDS = 4;
+/**
+ * A selector without bdg's filters (`:visible`, `:has-text()`, `:text-is()`),
+ * which plain CSS does not know.
+ *
+ * @param selector - Selector
+ * @returns Plain CSS
+ */
+function withoutFilters(selector) {
+    return (selector.replace(/:visible\b|:(has-text|text-is)\((?:"[^"]*"|'[^']*'|[^)"'])*\)/g, '').trim() ||
+        '*');
+}
 /**
  * What the page says about a selector that matched nothing, in one
  * evaluation: whether it is still loading, how many elements match with the
@@ -131,9 +160,11 @@ export async function noMatchContext(selector) {
         ? `(() => { try { return (${DEEP_QUERY_JS})(${JSON.stringify(selector)}, ${JSON.stringify(unfiltered)}).length; } catch (e) { return 0; } })()`
         : '0';
     const names = single ? pageNamesJS(single.kind) : '[]';
+    const compounds = leadingCompounds(selector);
+    const shadowHost = compounds.length > 0 ? shadowHostJS(compounds) : '-1';
     try {
         const evaluated = await callCDP('Runtime.evaluate', {
-            expression: `({ hidden: ${hidden}, readyState: document.readyState, unsearched: ${UNSEARCHED_CONTENT_JS}, names: ${names} })`,
+            expression: `({ hidden: ${hidden}, readyState: document.readyState, unsearched: ${UNSEARCHED_CONTENT_JS}, names: ${names}, shadowHost: ${shadowHost} })`,
             returnByValue: true,
         });
         const { result } = (evaluated.data?.result ?? {});
@@ -151,6 +182,8 @@ export async function noMatchContext(selector) {
                 },
             }),
             ...(similar && { similar }),
+            ...(typeof value.shadowHost === 'number' &&
+                compounds[value.shadowHost] && { shadowHost: compounds[value.shadowHost] }),
         };
     }
     catch (error) {
@@ -182,7 +215,8 @@ export async function documentReadyState() {
 const VIEWPORT_HINT_LIMIT = 100;
 /**
  * Where each element of a page-side array lives (an iframe and/or a shadow
- * root), its text and, for the first {@link VIEWPORT_HINT_LIMIT}, its position
+ * root), its text, its form control state ({@link ELEMENT_STATE_JS}) and, for
+ * the first {@link VIEWPORT_HINT_LIMIT}, its position
  * relative to the viewport, plus the viewport size. An element that cannot be
  * read gets empty details instead of failing the whole query.
  */
@@ -190,9 +224,10 @@ const ELEMENT_DETAILS_FUNCTION = `function () {
   const contextOf = ${ELEMENT_CONTEXT_JS};
   const textOf = ${ELEMENT_TEXT_JS};
   const geometryOf = ${ELEMENT_GEOMETRY_JS};
+  const stateOf = ${ELEMENT_STATE_JS};
   const read = (el, index) => {
     try {
-      return { context: contextOf(el), text: textOf(el), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
+      return { context: contextOf(el), text: textOf(el), state: stateOf(el), geometry: index < ${VIEWPORT_HINT_LIMIT} ? geometryOf(el) : null };
     } catch (e) {
       return {};
     }
@@ -219,6 +254,7 @@ async function elementsWithDetails(arrayObjectId) {
                 backendNodeId,
                 context: details?.context ?? '',
                 text: details?.text ?? '',
+                state: details?.state ?? {},
                 ...viewportHint(details?.geometry, viewport),
             },
         ];
@@ -334,18 +370,21 @@ export async function queryDOMElements(selector) {
         log.debug(`Querying ${elements.length} elements with selector: ${selector}`);
     }
     const nodes = await mapConcurrently(elements, async (element, index) => {
-        const { backendNodeId, context, text, inViewport, clippedBy } = element;
+        const { backendNodeId, context, text, state, inViewport, clippedBy } = element;
         const desc = await describeNode({ backendNodeId });
         if (!desc)
             return { index, nodeId: 0 };
         const attributes = unpackAttributes(desc.attributes);
         const classes = attributes['class']?.split(/\s+/).filter(Boolean);
         const preview = textPreview(text);
+        const tag = desc.nodeName.toLowerCase();
+        const keys = keyAttributes(tag, attributes, state);
         return {
             index,
             nodeId: desc.backendNodeId,
-            tag: desc.nodeName.toLowerCase(),
+            tag,
             ...identifyingAttributes(attributes, desc.nodeName),
+            ...(keys && { attributes: keys }),
             ...(classes && { classes }),
             ...(preview && { preview }),
             ...(context && { context }),
@@ -372,36 +411,39 @@ function identifyingAttributes(attributes, nodeName) {
     };
 }
 /**
- * The text of one element as the page renders it ({@link ELEMENT_TEXT_JS}).
+ * The text of one element as the page renders it ({@link ELEMENT_TEXT_JS})
+ * and its form control state ({@link ELEMENT_STATE_JS}).
  *
  * @param ref - Node reference
  * @param full - Read all of a large container's text, not just its start
- * @returns Element text, or empty when the node cannot be read
+ * @returns Element text and state, empty when the node cannot be read
  */
-async function elementText(ref, full) {
+async function elementTextAndState(ref, full) {
     const objectGroup = `bdg-text-${process.pid}-${++queryCount}`;
     const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
     const objectId = resolved.data?.result?.object
         .objectId;
     if (!objectId)
-        return '';
+        return { text: '', state: {} };
     try {
         const response = await callCDP('Runtime.callFunctionOn', {
             objectId,
-            functionDeclaration: `function (full) { return (${ELEMENT_TEXT_JS})(this, full); }`,
+            functionDeclaration: `function (full) { return { text: (${ELEMENT_TEXT_JS})(this, full), state: (${ELEMENT_STATE_JS})(this) }; }`,
             arguments: [{ value: full }],
             returnByValue: true,
         });
-        const value = response.data?.result?.result
-            ?.value;
-        return typeof value === 'string' ? value : '';
+        const value = response.data?.result?.result?.value;
+        return {
+            text: typeof value?.text === 'string' ? value.text : '',
+            state: value?.state ?? {},
+        };
     }
     finally {
         await callCDP('Runtime.releaseObjectGroup', { objectGroup });
     }
 }
 /**
- * Get DOM context (tag, classes, text preview) for a node: a one-line
+ * Get DOM context (tag, classes, key attributes, 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`).
  *
@@ -417,13 +459,18 @@ export async function getDomContext(ref, options = {}) {
         return null;
     }
     const full = options.full === true;
-    const classes = unpackAttributes(desc.attributes)['class']?.split(/\s+/).filter(Boolean);
-    const text = await elementText(ref, full);
+    const attributes = unpackAttributes(desc.attributes);
+    const classes = attributes['class']?.split(/\s+/).filter(Boolean);
+    const { text, state } = await elementTextAndState(ref, full);
     const preview = textPreview(text);
     const longer = textPreview(text, full ? Number.POSITIVE_INFINITY : ELEMENT_TEXT_LENGTH);
+    const tag = desc.nodeName.toLowerCase();
+    const keys = keyAttributes(tag, attributes, state);
     return {
-        tag: desc.nodeName.toLowerCase(),
+        tag,
         ...(classes && classes.length > 0 && { classes }),
+        ...(keys && { attributes: keys }),
+        ...(state.sensitive && { sensitive: true }),
         ...(preview && { preview }),
         ...(longer !== preview && { text: longer }),
         ...(!preview && (await childElements(ref))),

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

@@ -6,7 +6,7 @@
  */
 import { DomElementResolver } from '../DomElementResolver.js';
 import { noMatchContext } from './query.js';
-import { otherIndexSourceNote, staleNodeError, unreachableElementsNote, withLoadingHint, } from '../../../errors/messages.js';
+import { otherIndexSourceNote, staleNodeError, shadowBoundaryLine, unreachableElementsNote, withLoadingHint, } from '../../../errors/messages.js';
 import { joinLines } from '../../../ui/formatting.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 /**
@@ -110,7 +110,8 @@ function failedResultFailure(result, options) {
 }
 /**
  * Add what the page says to a "not found" failure (one page evaluation, on
- * this failure path only, {@link noMatchContext}): similar ids or classes,
+ * this failure path only, {@link noMatchContext}): similar ids or classes, a
+ * shadow host the selector tries to cross,
  * the places selectors do not search (for a page script that found nothing)
  * and the still-loading hint while the page loads.
  *
@@ -124,7 +125,7 @@ async function withNotFoundContext(failure, selector, searched) {
         return failure;
     const context = await noMatchContext(selector);
     const note = searched ? unreachableElementsNote(selector, context.unsearched) : '';
-    const suggestion = withLoadingHint(joinLines(context.similar, failure.errorContext?.suggestion, note ? note : undefined), context.readyState, selector);
+    const suggestion = withLoadingHint(joinLines(context.similar, context.shadowHost && shadowBoundaryLine(context.shadowHost), failure.errorContext?.suggestion, note ? note : undefined), context.readyState, selector);
     return suggestion ? { ...failure, errorContext: { suggestion } } : failure;
 }
 //# sourceMappingURL=runElementCommand.js.map

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

@@ -138,11 +138,32 @@ async function restoreScrollPosition(position) {
         returnByValue: true,
     });
 }
+/**
+ * The window's size with its scrollbars (`innerWidth`/`innerHeight`): an
+ * override at this size keeps the page's layout, where the visible size
+ * (without scrollbars) would narrow it and move centered content.
+ *
+ * @param viewport - Visible viewport size, used when the page does not answer
+ * @returns Width and height in CSS px
+ */
+async function windowSize(viewport) {
+    const response = await callCDP('Runtime.evaluate', {
+        expression: '[window.innerWidth, window.innerHeight]',
+        returnByValue: true,
+    });
+    const value = response.data?.result?.result?.value;
+    const [width, height] = Array.isArray(value) ? value : [];
+    return {
+        width: Math.round(width ?? viewport.clientWidth),
+        height: Math.round(height ?? viewport.clientHeight),
+    };
+}
 /**
  * Capture at a pixel ratio of 1 (CSS px = image px) on a high-DPI display:
- * the viewport is overridden at its size (the session's `--viewport`, else
- * the visible one) until the returned function puts back what was there
- * before, the session's viewport or none.
+ * the viewport is overridden at the window's size (the session's
+ * `--viewport`, else the window with its scrollbars, so the layout does not
+ * change) until the returned function puts back what was there before, the
+ * session's viewport or none.
  *
  * @param devicePixelRatio - Page's pixel ratio
  * @param viewport - Visible viewport size
@@ -152,10 +173,7 @@ async function useUnitPixelRatio(devicePixelRatio, viewport) {
     if (devicePixelRatio === 1)
         return () => Promise.resolve();
     const sessionViewport = readSessionMetadata()?.viewport;
-    const size = sessionViewport ?? {
-        width: Math.round(viewport.clientWidth),
-        height: Math.round(viewport.clientHeight),
-    };
+    const size = sessionViewport ?? (await windowSize(viewport));
     await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(size, 1));
     return async () => {
         if (sessionViewport) {
@@ -350,6 +368,53 @@ const CONTENT_OVERFLOW_JS = `function () {
   if (!clips(view.getComputedStyle(this))) walk(this);
   return { left: own.left - reach.left, top: own.top - reach.top, right: reach.right - own.right, bottom: reach.bottom - own.bottom };
 }`;
+/**
+ * The visible viewport (without scrollbars) in CSS px.
+ *
+ * @returns Width and height
+ */
+async function visibleViewport() {
+    const metrics = (await callCDP('Page.getLayoutMetrics', {})).data?.result;
+    const view = metrics?.cssVisualViewport ?? metrics?.visualViewport;
+    return { width: view?.clientWidth ?? 0, height: view?.clientHeight ?? 0 };
+}
+/**
+ * Whether an area (viewport coordinates) lies inside the viewport.
+ *
+ * @param area - Area
+ * @param view - Viewport size
+ * @returns True when fully inside
+ */
+function insideView(area, view) {
+    return (area.x >= 0 &&
+        area.y >= 0 &&
+        area.x + area.width <= view.width &&
+        area.y + area.height <= view.height);
+}
+/**
+ * Measure the area to capture and, when it fits in the viewport but is not
+ * in view, scroll it to the middle first. A capture inside the viewport
+ * keeps the page as it is; one beyond it makes Chrome lay the page out
+ * without its scrollbar, which moves centered content by half the
+ * scrollbar's width, so it is used only for areas larger than the viewport.
+ *
+ * @param ref - Node reference
+ * @returns Border box, area to capture (viewport coordinates) and whether it is in view
+ */
+async function measureInView(ref) {
+    const view = await visibleViewport();
+    let box = await getElementBounds(ref);
+    let bounds = await captureArea(ref, box);
+    const fits = bounds.width <= view.width && bounds.height <= view.height;
+    if (fits && !insideView(bounds, view)) {
+        const dx = bounds.x + bounds.width / 2 - view.width / 2;
+        const dy = bounds.y + bounds.height / 2 - view.height / 2;
+        await callCDP('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
+        box = await getElementBounds(ref);
+        bounds = await captureArea(ref, box);
+    }
+    return { box, bounds, inView: insideView(bounds, view) };
+}
 /** Overflow (px) below which the capture keeps to the border box (subpixel rounding) */
 const OVERFLOW_SLACK = 1;
 /**
@@ -403,8 +468,6 @@ async function captureArea(ref, bounds) {
  * (the reported bounds are page coordinates, like `dom layout`'s).
  */
 export async function captureElementScreenshot(outputPath, ref, options = {}) {
-    const box = await getElementBounds(ref);
-    const bounds = await captureArea(ref, box);
     const format = options.format ?? 'png';
     const quality = format === 'jpeg' ? (options.quality ?? 90) : undefined;
     const noResize = options.noResize ?? false;
@@ -413,6 +476,18 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
         returnByValue: true,
     });
     const devicePixelRatio = dprResponse.data?.result?.result?.value ?? 1;
+    const before = (await callCDP('Page.getLayoutMetrics', {})).data?.result;
+    const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, before?.visualViewport ?? { clientWidth: 800, clientHeight: 600 });
+    let box;
+    let bounds;
+    let inView;
+    try {
+        ({ box, bounds, inView } = await measureInView(ref));
+    }
+    catch (error) {
+        await restoreMetrics();
+        throw error;
+    }
     const originalWidth = bounds.width;
     const originalHeight = bounds.height;
     const resized = shouldResize(originalWidth, originalHeight, noResize);
@@ -421,7 +496,6 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     const finalHeight = Math.round(originalHeight * scale);
     const metricsResponse = await callCDP('Page.getLayoutMetrics', {});
     const metricsResult = metricsResponse.data?.result;
-    const viewport = metricsResult?.visualViewport ?? { clientWidth: 800, clientHeight: 600 };
     const scroll = metricsResult?.cssLayoutViewport ?? { pageX: 0, pageY: 0 };
     const onPage = (area) => ({
         ...area,
@@ -429,14 +503,13 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
         y: area.y + scroll.pageY,
     });
     const clip = onPage(bounds);
-    const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, viewport);
     let screenshotResult;
     try {
         const screenshotResponse = await callCDP('Page.captureScreenshot', {
             format,
             ...(quality !== undefined && { quality }),
             clip: { ...clip, scale },
-            captureBeyondViewport: true,
+            captureBeyondViewport: !inView,
         });
         screenshotResult = screenshotResponse.data?.result;
     }

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

@@ -9,6 +9,7 @@
  * - `frames.ts` — list the page's iframes
  * - `listeners.ts` — list event listeners that run for an element
  * - `layout.ts` — positions, sizes and visibility of elements
+ * - `inspect.ts` — what one element looks like (styles, box, layout, child tree)
  * - `wait.ts` — wait for elements to appear, show, contain a text or go away
  *
  * Form-related commands register via `form.ts` and `formInteraction.ts`.

package/dist/commands/dom/index.js

@@ -9,6 +9,7 @@
  * - `frames.ts` — list the page's iframes
  * - `listeners.ts` — list event listeners that run for an element
  * - `layout.ts` — positions, sizes and visibility of elements
+ * - `inspect.ts` — what one element looks like (styles, box, layout, child tree)
  * - `wait.ts` — wait for elements to appear, show, contain a text or go away
  *
  * Form-related commands register via `form.ts` and `formInteraction.ts`.
@@ -20,11 +21,13 @@ import { handleDomEval } from './eval.js';
 import { registerFormCommand } from './form.js';
 import { handleDomFrames } from './frames.js';
 import { DOM_GET_DEFAULT_SELECTOR, handleDomGet } from './get.js';
+import { registerInspectCommand } from './inspect.js';
 import { registerLayoutCommand } from './layout.js';
 import { registerListenersCommand } from './listeners.js';
 import { handleDomQuery } from './query.js';
 import { handleDomScreenshot } from './screenshot.js';
 import { registerWaitCommand } from './wait.js';
+import { SELECTOR_OR_INDEX_ARGUMENT, SELECTOR_SCOPE_HELP, } from '../shared/commonOptions.js';
 import { integerOption, screenshotFormatOption } from '../shared/validation.js';
 /**
  * Register DOM telemetry commands on the root Commander program.
@@ -38,12 +41,14 @@ export function registerDomCommands(program) {
     registerFormCommand(dom);
     registerListenersCommand(dom);
     registerLayoutCommand(dom);
+    registerInspectCommand(dom);
     registerWaitCommand(dom);
     dom
         .command('query')
         .description('Find elements by CSS selector')
         .argument('<selector>', 'CSS selector (e.g., ".error", "#app", "button")')
         .option('-j, --json', 'Output as JSON')
+        .addHelpText('after', SELECTOR_SCOPE_HELP)
         .action(async (selector, options) => {
         await handleDomQuery(selector, options);
     });
@@ -51,7 +56,7 @@ export function registerDomCommands(program) {
         .command('eval')
         .description('Evaluate JavaScript expression in the page context')
         .argument('<script>', 'JavaScript to execute (e.g., "document.title", "window.location.href")')
-        .option('--frame <frame>', 'Evaluate in an iframe, cross-origin ones included: index, name/id attribute, or part of the name, id or URL (see dom frames)')
+        .option('--frame <frame>', 'Evaluate in an iframe, cross-origin ones included: index (from dom frames; 87 when stale), name/id attribute, or part of the name, id or URL')
         .option('-j, --json', 'Output as JSON')
         .action(async (script, options) => {
         await handleDomEval(script, options);
@@ -67,7 +72,7 @@ export function registerDomCommands(program) {
     });
     dom
         .command('frames')
-        .description("List the page's iframes (nested and cross-origin ones included) for eval --frame")
+        .description("List the page's iframes in document order (nested and cross-origin ones included) for eval --frame")
         .option('-j, --json', 'Output as JSON')
         .action(async (options) => {
         await handleDomFrames(options);
@@ -75,7 +80,7 @@ export function registerDomCommands(program) {
     dom
         .command('get')
         .description('Get semantic accessibility structure (default) or raw HTML (--raw)')
-        .argument('[selectorOrIndex]', `CSS selector or numeric index from query results (0-based; e.g. ".error", "#app", 0); default: ${DOM_GET_DEFAULT_SELECTOR}`)
+        .argument('[selectorOrIndex]', `${SELECTOR_OR_INDEX_ARGUMENT} (e.g. ".error", "#app", 0); default: ${DOM_GET_DEFAULT_SELECTOR}`)
         .option('--raw', 'Output raw HTML with all filtering options')
         .option('--full', 'Show all of the element text (default: the first 500 characters)')
         .option('--all', 'Get all matches (only with --raw)')

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.js

@@ -7,7 +7,7 @@
 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 { integerOption } from '../shared/validation.js';
 import { domLayout } from '../../ipc/client.js';
 import { formatLayout } from '../../ui/formatters/layout.js';
@@ -20,7 +20,7 @@ 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>', 'CSS selector or numeric index from query results (0-based)')
+        .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) => {

package/dist/commands/dom/listeners.js

@@ -13,7 +13,7 @@
 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';
@@ -26,7 +26,7 @@ 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; repeatable)', eventTypesOption)
         .option('--all', 'List every listener of framework roots (React) instead of one line per node')

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

@@ -17,7 +17,9 @@ export interface SemanticNodeWithContext {
 /**
  * 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
+ * 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.
  *
@@ -34,4 +36,15 @@ export declare function formatSemanticNodeWithContext(data: SemanticNodeWithCont
  * @param nodeId - CDP nodeId for synthesis
  */
 export declare function resolveNodeWithFallback(a11yNode: A11yNode | null, domContext: DomContext | null, nodeId: number | undefined): A11yNode | null;
+/**
+ * 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.
+ *
+ * @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 withSecretMasked(node: A11yNode, domContext: DomContext | null): A11yNode;
 //# sourceMappingURL=semanticUtils.d.ts.map