browser-debugger-cli 0.8.0 → 0.9.0

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

@@ -5,15 +5,18 @@
  * Keeps individual command handlers focused on option wiring and output formatting.
  */
 import { DomElementResolver } from '../DomElementResolver.js';
-import { UNREACHABLE_ELEMENTS_HINT, staleNodeError } from '../../../errors/messages.js';
+import { noMatchContext } from './query.js';
+import { otherIndexSourceNote, staleNodeError, unreachableElementsNote, withLoadingHint, } from '../../../errors/messages.js';
+import { joinLines } from '../../../ui/formatting.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 /**
  * Resolve an element target, invoke the IPC call, and normalize failures
- * into the structured `CommandRunner` result shape.
+ * into the structured `CommandRunner` result shape. A numeric index names the
+ * list it refers to (`indexSource` in the data, and in errors).
  */
 export async function runElementCommand(options) {
-    const { selectorOrIndex, index, buildRequest, call, action, failureSuggestion } = options;
-    const target = await DomElementResolver.getInstance().resolve(selectorOrIndex, index);
+    const { selectorOrIndex, index, command, buildRequest, call } = options;
+    const target = await DomElementResolver.getInstance().resolve(selectorOrIndex, index, command);
     if (!target.success) {
         return {
             success: false,
@@ -28,36 +31,100 @@ export async function runElementCommand(options) {
         ...(target.backendNodeId !== undefined && { backendNodeId: target.backendNodeId }),
     });
     const response = await call(request);
-    if (response.status === 'error' || !response.data) {
-        const staleIndex = response.exitCode === EXIT_CODES.STALE_CACHE && /^\d+$/.test(selectorOrIndex)
-            ? staleNodeError(Number(selectorOrIndex)).message
-            : undefined;
-        return {
-            success: false,
-            error: staleIndex ?? response.error ?? `Failed to ${action}`,
-            exitCode: response.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
-            ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
-        };
+    const failure = response.status === 'error' || !response.data
+        ? errorResponseFailure(response, options)
+        : response.data.success
+            ? undefined
+            : failedResultFailure(response.data, options);
+    if (failure && target.source) {
+        return indexFailure(failure, target.source, target.preview, response.data);
     }
-    const result = response.data;
-    if (!result.success) {
-        const exitCode = result.exitCode ??
-            (result.error?.includes('not found')
-                ? EXIT_CODES.RESOURCE_NOT_FOUND
-                : EXIT_CODES.INVALID_ARGUMENTS);
-        const suggestion = result.suggestion ?? failureSuggestion;
+    if (failure)
+        return withNotFoundContext(failure, target.selector, response.status !== 'error');
+    const { success: _success, ...data } = response.data;
+    return { success: true, data: { ...data, ...(target.source && { indexSource: target.source }) } };
+}
+/**
+ * A failure on a cached index, told in terms of the index: a stale element
+ * (87) names the index and the command that refreshes it, and an element a
+ * form command cannot act on, from the results of another command, gets a
+ * note on which list the index refers to.
+ *
+ * @param failure - Failed command result
+ * @param source - The index and the list it refers to
+ * @param preview - What the cached element was when listed
+ * @param result - Action result, when the daemon answered
+ * @returns The failure in terms of the index
+ */
+function indexFailure(failure, source, preview, result) {
+    if (failure.exitCode === EXIT_CODES.STALE_CACHE) {
+        const err = staleNodeError(source.index, source);
         return {
             success: false,
-            error: result.error ?? `Failed to ${action}`,
-            exitCode,
-            errorContext: {
-                suggestion: exitCode === EXIT_CODES.RESOURCE_NOT_FOUND
-                    ? `${suggestion} (${UNREACHABLE_ELEMENTS_HINT})`
-                    : suggestion,
-            },
+            error: err.message,
+            exitCode: EXIT_CODES.STALE_CACHE,
+            errorContext: { suggestion: err.suggestion },
         };
     }
-    const { success: _success, ...data } = result;
-    return { success: true, data };
+    if (!result?.unsuitableElement || source.command === 'dom form')
+        return failure;
+    const note = otherIndexSourceNote(source, preview);
+    return {
+        ...failure,
+        errorContext: { suggestion: joinLines(failure.errorContext?.suggestion, note) },
+    };
+}
+/**
+ * Failure for an error response of the daemon.
+ *
+ * @param response - Error response
+ * @param options - Command options (selector or index, action)
+ * @returns Failed command result
+ */
+function errorResponseFailure(response, options) {
+    return {
+        success: false,
+        error: response.error ?? `Failed to ${options.action}`,
+        exitCode: response.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+        ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+    };
+}
+/**
+ * Failure for an action whose page script reported failure.
+ *
+ * @param result - Action result
+ * @param options - Command options (action, fallback suggestion)
+ * @returns Failed command result
+ */
+function failedResultFailure(result, options) {
+    const exitCode = result.exitCode ??
+        (result.error?.includes('not found')
+            ? EXIT_CODES.RESOURCE_NOT_FOUND
+            : EXIT_CODES.INVALID_ARGUMENTS);
+    return {
+        success: false,
+        error: result.error ?? `Failed to ${options.action}`,
+        exitCode,
+        errorContext: { suggestion: result.suggestion ?? options.failureSuggestion },
+    };
+}
+/**
+ * Add what the page says to a "not found" failure (one page evaluation, on
+ * this failure path only, {@link noMatchContext}): similar ids or classes,
+ * the places selectors do not search (for a page script that found nothing)
+ * and the still-loading hint while the page loads.
+ *
+ * @param failure - Failed command result
+ * @param selector - Selector that was looked for (the cached query's for an index)
+ * @param searched - The page script searched the page (the daemon did not fail first)
+ * @returns The failure, with the context in its suggestion
+ */
+async function withNotFoundContext(failure, selector, searched) {
+    if (failure.exitCode !== EXIT_CODES.RESOURCE_NOT_FOUND)
+        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);
+    return suggestion ? { ...failure, errorContext: { suggestion } } : failure;
 }
 //# sourceMappingURL=runElementCommand.js.map

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

@@ -20,7 +20,10 @@ export declare function getElementBounds(ref: NodeRef): Promise<ElementBounds>;
  */
 export declare function capturePageScreenshot(outputPath: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
 /**
- * Capture a screenshot of a single element, clipped to its bounding box.
+ * Capture a screenshot of a single element: its border box, grown to include
+ * content overflowing it ({@link captureArea}). The box model is relative to
+ * the viewport and the capture clip to the page, so the page scroll is added
+ * (the reported bounds are page coordinates, like `dom layout`'s).
  */
 export declare function captureElementScreenshot(outputPath: string, ref: NodeRef, options?: {
     format?: 'png' | 'jpeg';

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

@@ -11,6 +11,8 @@ import { CommandError } from '../../../errors/index.js';
 import { noNodesFoundError, elementNotVisibleError, elementZeroDimensionsError, } from '../../../errors/messages.js';
 import { callCDP } from '../../../ipc/client.js';
 import { DEEP_QUERY_JS, selectorArgsJS } from '../../../runtime/dom/targetNode.js';
+import { viewportOverride } from '../../../runtime/page/emulation.js';
+import { readSessionMetadata } from '../../../session/metadata.js';
 import { createLogger } from '../../../ui/logging/index.js';
 import { EXIT_CODES } from '../../../utils/exitCodes.js';
 const log = createLogger('dom');
@@ -136,6 +138,34 @@ async function restoreScrollPosition(position) {
         returnByValue: true,
     });
 }
+/**
+ * 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.
+ *
+ * @param devicePixelRatio - Page's pixel ratio
+ * @param viewport - Visible viewport size
+ * @returns Function restoring the device metrics
+ */
+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),
+    };
+    await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(size, 1));
+    return async () => {
+        if (sessionViewport) {
+            await callCDP('Emulation.setDeviceMetricsOverride', viewportOverride(sessionViewport));
+        }
+        else {
+            await callCDP('Emulation.clearDeviceMetricsOverride', {});
+        }
+    };
+}
 /**
  * Get the bounding box (border box, so padding and border are included) of an
  * element via CDP DOM.getBoxModel.
@@ -161,6 +191,20 @@ export async function getElementBounds(ref) {
     }
     return { x, y, width, height };
 }
+/**
+ * Page coordinates of the visible area's top-left corner. A capture clip is
+ * in page coordinates, so a viewport capture must start at the scroll
+ * position, not at the page origin (which shows nothing once scrolled). Read
+ * after any metrics override, which can move the scroll position.
+ *
+ * @returns Scroll offset of the visual viewport in CSS pixels
+ */
+async function visibleAreaOrigin() {
+    const response = await callCDP('Page.getLayoutMetrics', {});
+    const metrics = response.data?.result;
+    const viewport = metrics?.cssVisualViewport;
+    return { x: viewport?.pageX ?? 0, y: viewport?.pageY ?? 0 };
+}
 /**
  * Capture a screenshot of the page. Auto-resizes oversized pages by default
  * to keep Claude Vision token cost bounded; falls back to viewport capture
@@ -193,13 +237,8 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     const scale = resized ? calculateResizeScale(captureWidth, captureHeight) : 1;
     const finalWidth = Math.round(captureWidth * scale);
     const finalHeight = Math.round(captureHeight * scale);
+    const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, viewport);
     if (devicePixelRatio !== 1) {
-        await callCDP('Emulation.setDeviceMetricsOverride', {
-            width: Math.round(viewport.clientWidth),
-            height: Math.round(viewport.clientHeight),
-            deviceScaleFactor: 1,
-            mobile: false,
-        });
         if (options.scroll) {
             await callCDP('Runtime.evaluate', {
                 expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(options.scroll)})[0]?.scrollIntoView({ block: 'center', behavior: 'instant' })`,
@@ -207,18 +246,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
             });
         }
     }
-    let clipX = 0;
-    let clipY = 0;
-    if (useScroll && !effectiveFullPage) {
-        const scrollResponse = await callCDP('Runtime.evaluate', {
-            expression: 'JSON.stringify({ x: window.scrollX, y: window.scrollY })',
-            returnByValue: true,
-        });
-        const scrollPos = JSON.parse(scrollResponse.data?.result?.result?.value ??
-            '{"x":0,"y":0}');
-        clipX = scrollPos.x;
-        clipY = scrollPos.y;
-    }
+    const clipOrigin = effectiveFullPage ? { x: 0, y: 0 } : await visibleAreaOrigin();
     let screenshotResult;
     try {
         const screenshotResponse = await callCDP('Page.captureScreenshot', {
@@ -226,8 +254,8 @@ export async function capturePageScreenshot(outputPath, options = {}) {
             ...(quality !== undefined && { quality }),
             captureBeyondViewport: effectiveFullPage,
             clip: {
-                x: clipX,
-                y: clipY,
+                x: clipOrigin.x,
+                y: clipOrigin.y,
                 width: captureWidth,
                 height: captureHeight,
                 scale,
@@ -236,9 +264,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
         screenshotResult = screenshotResponse.data?.result;
     }
     finally {
-        if (devicePixelRatio !== 1) {
-            await callCDP('Emulation.clearDeviceMetricsOverride', {});
-        }
+        await restoreMetrics();
     }
     if (!screenshotResult?.data) {
         throw new CDPConnectionError('No screenshot data returned', new Error('Empty response'));
@@ -287,11 +313,98 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     }
     return result;
 }
+/** Descendants {@link CONTENT_OVERFLOW_JS} looks at, so a huge element stays cheap */
+const OVERFLOW_SCAN_LIMIT = 2000;
+/**
+ * Page-side distances (CSS px, never negative) by which an element's rendered
+ * descendants reach beyond its border box on each side: uncleared floats,
+ * absolutely positioned and transformed children. Descendants of an element
+ * that clips its overflow (`overflow` other than `visible`) are cut off by it
+ * and not counted, nor are fixed ones (they belong to the viewport) or what
+ * lies outside the document (skip links at -9999px). Zero everywhere when the
+ * element clips its own overflow.
+ */
+const CONTENT_OVERFLOW_JS = `function () {
+  const view = this.ownerDocument.defaultView;
+  const scroller = this.ownerDocument.scrollingElement || this.ownerDocument.documentElement;
+  const own = this.getBoundingClientRect();
+  const reach = { left: own.left, top: own.top, right: own.right, bottom: own.bottom };
+  const page = { left: -view.scrollX, top: -view.scrollY, right: scroller.scrollWidth - view.scrollX, bottom: scroller.scrollHeight - view.scrollY };
+  const clips = (style) => style.overflowX !== 'visible' || style.overflowY !== 'visible';
+  let budget = ${OVERFLOW_SCAN_LIMIT};
+  const walk = (el) => {
+    for (const child of el.children) {
+      if (--budget < 0) return;
+      const style = view.getComputedStyle(child);
+      if (style.display === 'none' || style.position === 'fixed') continue;
+      const r = child.getBoundingClientRect();
+      if (r.width > 0 && r.height > 0 && style.visibility === 'visible') {
+        reach.left = Math.min(reach.left, Math.max(r.left, page.left));
+        reach.top = Math.min(reach.top, Math.max(r.top, page.top));
+        reach.right = Math.max(reach.right, Math.min(r.right, page.right));
+        reach.bottom = Math.max(reach.bottom, Math.min(r.bottom, page.bottom));
+      }
+      if (!clips(style)) walk(child);
+    }
+  };
+  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 };
+}`;
+/** Overflow (px) below which the capture keeps to the border box (subpixel rounding) */
+const OVERFLOW_SLACK = 1;
+/**
+ * Area an element screenshot captures: the border box, grown to the content
+ * that overflows it ({@link CONTENT_OVERFLOW_JS}), so floated children are
+ * not cropped away.
+ *
+ * @param ref - Node reference
+ * @param bounds - Border box (DOM.getBoxModel coordinates)
+ * @returns The area, or the border box when nothing overflows (or the page cannot be asked)
+ */
+async function captureArea(ref, bounds) {
+    const objectGroup = `bdg-shot-${process.pid}`;
+    try {
+        const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
+        const objectId = resolved.data?.result?.object
+            .objectId;
+        if (!objectId)
+            return bounds;
+        const response = await callCDP('Runtime.callFunctionOn', {
+            objectId,
+            functionDeclaration: CONTENT_OVERFLOW_JS,
+            returnByValue: true,
+        });
+        const overflow = response.data?.result
+            ?.result?.value;
+        if (!overflow)
+            return bounds;
+        const [left, top, right, bottom] = ['left', 'top', 'right', 'bottom'].map((side) => Math.max(0, overflow[side] ?? 0));
+        if (Math.max(left, top, right, bottom) <= OVERFLOW_SLACK)
+            return bounds;
+        return {
+            x: bounds.x - left,
+            y: bounds.y - top,
+            width: bounds.width + left + right,
+            height: bounds.height + top + bottom,
+        };
+    }
+    catch (error) {
+        log.debug(`Could not measure overflowing content: ${String(error)}`);
+        return bounds;
+    }
+    finally {
+        await callCDP('Runtime.releaseObjectGroup', { objectGroup }).catch(() => undefined);
+    }
+}
 /**
- * Capture a screenshot of a single element, clipped to its bounding box.
+ * Capture a screenshot of a single element: its border box, grown to include
+ * content overflowing it ({@link captureArea}). The box model is relative to
+ * the viewport and the capture clip to the page, so the page scroll is added
+ * (the reported bounds are page coordinates, like `dom layout`'s).
  */
 export async function captureElementScreenshot(outputPath, ref, options = {}) {
-    const bounds = await getElementBounds(ref);
+    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;
@@ -309,34 +422,26 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     const metricsResponse = await callCDP('Page.getLayoutMetrics', {});
     const metricsResult = metricsResponse.data?.result;
     const viewport = metricsResult?.visualViewport ?? { clientWidth: 800, clientHeight: 600 };
-    if (devicePixelRatio !== 1) {
-        await callCDP('Emulation.setDeviceMetricsOverride', {
-            width: Math.round(viewport.clientWidth),
-            height: Math.round(viewport.clientHeight),
-            deviceScaleFactor: 1,
-            mobile: false,
-        });
-    }
+    const scroll = metricsResult?.cssLayoutViewport ?? { pageX: 0, pageY: 0 };
+    const onPage = (area) => ({
+        ...area,
+        x: area.x + scroll.pageX,
+        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: {
-                x: bounds.x,
-                y: bounds.y,
-                width: bounds.width,
-                height: bounds.height,
-                scale,
-            },
+            clip: { ...clip, scale },
             captureBeyondViewport: true,
         });
         screenshotResult = screenshotResponse.data?.result;
     }
     finally {
-        if (devicePixelRatio !== 1) {
-            await callCDP('Emulation.clearDeviceMetricsOverride', {});
-        }
+        await restoreMetrics();
     }
     if (!screenshotResult?.data) {
         throw new CDPConnectionError('No screenshot data returned', new Error('Empty response'));
@@ -352,12 +457,8 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
         fullPage: false,
         finalTokens: calculateImageTokens(finalWidth, finalHeight),
         element: {
-            bounds: {
-                x: Math.round(bounds.x),
-                y: Math.round(bounds.y),
-                width: Math.round(bounds.width),
-                height: Math.round(bounds.height),
-            },
+            bounds: roundBounds(onPage(box)),
+            ...(bounds !== box && { captured: roundBounds(clip) }),
         },
     };
     if (quality !== undefined) {
@@ -371,4 +472,18 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     }
     return result;
 }
+/**
+ * Bounds in whole pixels.
+ *
+ * @param bounds - Bounds
+ * @returns Rounded bounds
+ */
+function roundBounds(bounds) {
+    return {
+        x: Math.round(bounds.x),
+        y: Math.round(bounds.y),
+        width: Math.round(bounds.width),
+        height: Math.round(bounds.height),
+    };
+}
 //# sourceMappingURL=screenshot.js.map

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

@@ -8,11 +8,13 @@
  * - `eval.ts` — evaluate JavaScript in the page (or an iframe)
  * - `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
+ * - `wait.ts` — wait for elements to appear, show, contain a text or go away
  *
  * Form-related commands register via `form.ts` and `formInteraction.ts`.
  * Accessibility commands register via `a11y.ts`.
  */
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 /**
  * Register DOM telemetry commands on the root Commander program.
  */

package/dist/commands/dom/index.js

@@ -8,18 +8,23 @@
  * - `eval.ts` — evaluate JavaScript in the page (or an iframe)
  * - `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
+ * - `wait.ts` — wait for elements to appear, show, contain a text or go away
  *
  * Form-related commands register via `form.ts` and `formInteraction.ts`.
  * Accessibility commands register via `a11y.ts`.
  */
+import { Option } from 'commander';
 import { registerA11yCommands } from './a11y.js';
 import { handleDomEval } from './eval.js';
 import { registerFormCommand } from './form.js';
 import { handleDomFrames } from './frames.js';
-import { handleDomGet } from './get.js';
+import { DOM_GET_DEFAULT_SELECTOR, handleDomGet } from './get.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 { integerOption, screenshotFormatOption } from '../shared/validation.js';
 /**
  * Register DOM telemetry commands on the root Commander program.
@@ -32,6 +37,8 @@ export function registerDomCommands(program) {
     registerA11yCommands(dom);
     registerFormCommand(dom);
     registerListenersCommand(dom);
+    registerLayoutCommand(dom);
+    registerWaitCommand(dom);
     dom
         .command('query')
         .description('Find elements by CSS selector')
@@ -44,7 +51,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 URL (see dom frames)')
+        .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('-j, --json', 'Output as JSON')
         .action(async (script, options) => {
         await handleDomEval(script, options);
@@ -68,10 +75,12 @@ export function registerDomCommands(program) {
     dom
         .command('get')
         .description('Get semantic accessibility structure (default) or raw HTML (--raw)')
-        .argument('[selector]', 'CSS selector or index from query results (e.g., ".error", "#app", 0); optional with --node-id')
+        .argument('[selectorOrIndex]', `CSS selector or numeric index from query results (0-based; 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)')
-        .option('--nth <n>', 'Get the nth match, 0-based (only with --raw)', integerOption(0))
+        .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
+        .addOption(new Option('--nth <n>', 'Alias of --index').argParser(integerOption(0)).hideHelp())
         .option('--node-id <id>', 'Get the element with this node id (from dom query/get --raw or a11y describe; implies --raw)', integerOption(1))
         .option('-j, --json', 'Output as JSON')
         .action(async (selector, options) => {
@@ -81,6 +90,7 @@ export function registerDomCommands(program) {
         .command('screenshot')
         .description('Capture page or element screenshot')
         .argument('<path>', 'Output file path, or directory for --follow mode')
+        .argument('[selector]', 'Element to capture: CSS selector or index from a query (same as --selector / --index)')
         .option('--selector <selector>', 'CSS selector for element capture')
         .option('--index <number>', 'Cached element index (0-based) from previous query', integerOption(0))
         .option('--format <format>', 'Image format: png or jpeg/jpg (default: from the file extension, else png)', screenshotFormatOption)
@@ -92,8 +102,8 @@ export function registerDomCommands(program) {
         .option('--interval <ms>', 'Capture interval for --follow (default: 1000)')
         .option('--limit <count>', 'Max frames for --follow')
         .option('-j, --json', 'Output as JSON')
-        .action(async (path, options) => {
-        await handleDomScreenshot(path, options);
+        .action(async (path, target, options) => {
+        await handleDomScreenshot(path, target, options);
     });
 }
 //# sourceMappingURL=index.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 } 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>', 'CSS selector or numeric index from query results (0-based)')
+        .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';
 /**