browser-debugger-cli 0.6.8 → 0.6.10

package/dist/commands/dom/index.js

@@ -1,7 +1,8 @@
 import { DomElementResolver } from '../../commands/dom/DomElementResolver.js';
 import { registerA11yCommands } from '../../commands/dom/a11y.js';
-import { queryDOMElements, getDOMElements, capturePageScreenshot, getDomContext, } from '../../commands/dom/helpers.js';
+import { queryDOMElements, getDOMElements, capturePageScreenshot, captureElementScreenshot, resolveSelector, getDomContext, } from '../../commands/dom/helpers.js';
 import { runCommand } from '../../commands/shared/CommandRunner.js';
+import { setupFollowMode } from '../../commands/shared/followMode.js';
 import { positiveIntRule } from '../../commands/shared/validation.js';
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { resolveA11yNode } from '../../telemetry/a11y.js';
@@ -12,164 +13,154 @@ import { elementNotFoundError } from '../../ui/messages/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
 /**
- * Handle bdg dom query <selector> command
+ * Build filtered screenshot options from command options.
  *
- * Queries the DOM using a CSS selector and displays matching elements.
- * Uses CDP relay through worker's persistent connection.
- * Results are cached for index-based access via "bdg dom get <index>".
+ * @param options - Raw command options
+ * @returns Filtered options with undefined values removed
+ */
+function buildPageScreenshotOptions(options) {
+    return filterDefined({
+        format: options.format,
+        quality: options.quality,
+        fullPage: options.fullPage,
+    });
+}
+/**
+ * Build filtered element screenshot options from command options.
  *
- * @param selector - CSS selector to query (e.g., ".error", "#app", "button")
- * @param options - Command options
+ * @param options - Raw command options
+ * @returns Filtered options with undefined values removed
  */
-async function handleDomQuery(selector, options) {
-    await runCommand(async () => {
-        const result = await queryDOMElements(selector);
-        const cacheManager = QueryCacheManager.getInstance();
-        const navigationId = await cacheManager.getCurrentNavigationId();
-        const resultWithNavId = {
-            ...result,
-            ...(navigationId !== null && { navigationId }),
-        };
-        await cacheManager.set(resultWithNavId);
-        return { success: true, data: result };
-    }, options, formatDomQuery);
+function buildElementScreenshotOptions(options) {
+    return filterDefined({
+        format: options.format,
+        quality: options.quality,
+    });
 }
 /**
- * Handle bdg dom get command
+ * Check if options specify an element target.
  *
- * Retrieves semantic accessibility structure by default (70% token reduction).
- * Use --raw flag for full HTML output.
- * Supports index-based access from query results (e.g., "bdg dom get 0").
+ * @param options - Screenshot command options
+ * @returns True if selector or index is specified
+ */
+function hasElementTarget(options) {
+    return options.selector !== undefined || options.index !== undefined;
+}
+/**
+ * Resolve element nodeId from selector or cached index.
  *
- * @param selectorOrIndex - CSS selector (e.g., ".error") or numeric index from query results
- * @param options - Command options including --all, --nth, nodeId, and raw
+ * @param options - Options containing selector or index
+ * @returns CDP nodeId
+ * @throws CommandError if neither selector nor index provided
  */
-async function handleDomGet(selectorOrIndex, options) {
-    const isNumericIndex = /^\d+$/.test(selectorOrIndex);
-    if (isNumericIndex) {
-        await handleIndexGet(parseInt(selectorOrIndex, 10), options);
+async function resolveElementNodeId(options) {
+    if (options.index !== undefined) {
+        const resolver = DomElementResolver.getInstance();
+        const node = await resolver.getNodeIdForIndex(options.index);
+        return node.nodeId;
     }
-    else {
-        await handleSelectorGet(selectorOrIndex, options);
+    if (options.selector !== undefined) {
+        return resolveSelector(options.selector);
     }
+    throw new CommandError('Either --selector or --index must be provided for element screenshot', {}, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
- * Handle get command with numeric index
+ * Add element metadata to screenshot result.
+ *
+ * @param result - Base screenshot result
+ * @param options - Options containing selector or index
+ * @returns Screenshot result with element info
  */
-async function handleIndexGet(index, options) {
-    const resolver = DomElementResolver.getInstance();
-    if (options.raw) {
-        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);
-    }
-    else {
-        await runCommand(async () => {
-            const targetNode = await resolver.getNodeIdForIndex(index);
-            const [a11yNode, domContext] = await Promise.all([
-                resolveA11yNode('', targetNode.nodeId),
-                getDomContext(targetNode.nodeId),
-            ]);
-            // Graceful degradation: synthesize node from DOM context when a11y unavailable
-            const node = a11yNode ?? (domContext ? synthesizeA11yNode(domContext, targetNode.nodeId) : null);
-            if (!node) {
-                throw new CommandError(elementNotFoundError(`index ${index}`), {}, EXIT_CODES.RESOURCE_NOT_FOUND);
-            }
-            return { success: true, data: { node, domContext } };
-        }, options, formatSemanticNodeWithContext);
-    }
+function addElementInfo(result, options) {
+    const bounds = {
+        x: 0,
+        y: 0,
+        width: result.width,
+        height: result.height,
+    };
+    return {
+        ...result,
+        element: {
+            ...(options.selector !== undefined && { selector: options.selector }),
+            ...(options.index !== undefined && { index: options.index }),
+            bounds,
+        },
+    };
 }
 /**
- * Handle get command with CSS selector
+ * Ensure directory exists, creating it if necessary.
+ *
+ * @param dirPath - Directory path to ensure
+ * @param fs - File system module
  */
-async function handleSelectorGet(selector, options) {
-    if (options.raw) {
-        await runCommand(async () => {
-            const getOptions = filterDefined({
-                selector,
-                all: options.all,
-                nth: options.nth,
-                nodeId: options.nodeId,
-            });
-            const result = await getDOMElements(getOptions);
-            return { success: true, data: result };
-        }, options, formatDomGet);
-    }
-    else {
-        await runCommand(async () => {
-            const a11yNode = await resolveA11yNode(selector);
-            // Fetch DOM context for enrichment or fallback
-            let domContext = null;
-            let nodeId;
-            if (a11yNode?.backendDOMNodeId) {
-                nodeId = a11yNode.backendDOMNodeId;
-                domContext = await getDomContext(nodeId);
-            }
-            else if (!a11yNode) {
-                // Try to get DOM context by querying the selector directly
-                const { callCDP } = await import('../../ipc/client.js');
-                const docResponse = await callCDP('DOM.getDocument', {});
-                const doc = docResponse.data?.result;
-                if (doc?.root?.nodeId) {
-                    const queryResponse = await callCDP('DOM.querySelector', {
-                        nodeId: doc.root.nodeId,
-                        selector,
-                    });
-                    const queryResult = queryResponse.data?.result;
-                    if (queryResult?.nodeId) {
-                        nodeId = queryResult.nodeId;
-                        domContext = await getDomContext(nodeId);
-                    }
-                }
-            }
-            // Graceful degradation: synthesize node from DOM context when a11y unavailable
-            const node = a11yNode ?? (domContext && nodeId ? synthesizeA11yNode(domContext, nodeId) : null);
-            if (!node) {
-                throw new CommandError(elementNotFoundError(selector), {}, EXIT_CODES.RESOURCE_NOT_FOUND);
-            }
-            return { success: true, data: { node, domContext } };
-        }, options, formatSemanticNodeWithContext);
+function ensureDirectory(dirPath, fs) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
     }
 }
 /**
- * Formatter for single semantic node with DOM context fallback.
+ * Format frame filename with zero-padded number.
  *
- * When a11y name is missing, shows DOM context (tag, classes, text preview)
- * to provide useful information instead of just "[Role]".
- * Shows "(inferred from DOM)" indicator when node is synthesized.
+ * @param frameNumber - Frame number (1-based)
+ * @param format - Image format extension
+ * @returns Formatted filename
  */
-function formatSemanticNodeWithContext(data) {
-    const { node, domContext } = data;
-    // Build the role text
-    let roleText = `[${capitalize(node.role)}]`;
+function formatFrameFilename(frameNumber, format) {
+    return `${String(frameNumber).padStart(3, '0')}.${format}`;
+}
+/**
+ * Capitalize first letter of string.
+ *
+ * @param str - Input string
+ * @returns String with first letter capitalized
+ */
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+/**
+ * Build role text for accessibility node display.
+ *
+ * @param node - Accessibility node
+ * @returns Formatted role text
+ */
+function buildRoleText(node) {
     if (node.role.toLowerCase() === 'heading' && node.properties?.['level'] !== undefined) {
         const level = node.properties['level'];
         const levelNum = typeof level === 'number' ? level : Number(level);
         if (!isNaN(levelNum)) {
-            roleText = `[Heading L${levelNum}]`;
+            return `[Heading L${levelNum}]`;
         }
     }
-    // Build the name/context text
-    let contextText = '';
+    return `[${capitalize(node.role)}]`;
+}
+/**
+ * Build context text from a11y name or DOM context fallback.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context for fallback
+ * @returns Formatted context text
+ */
+function buildContextText(node, domContext) {
     if (node.name) {
-        // Use a11y name when available
-        contextText = ` "${node.name}"`;
+        return ` "${node.name}"`;
     }
-    else if (domContext) {
-        // Fallback to DOM context when a11y name is missing
+    if (domContext) {
         const tagPart = `<${domContext.tag}`;
         const classPart = domContext.classes && domContext.classes.length > 0
             ? `.${domContext.classes.slice(0, 3).join('.')}`
             : '';
         const previewPart = domContext.preview ? ` "${domContext.preview}"` : '';
-        contextText = ` ${tagPart}${classPart}>${previewPart}`;
+        return ` ${tagPart}${classPart}>${previewPart}`;
     }
-    // Build properties text
+    return '';
+}
+/**
+ * Build properties text from accessibility node state.
+ *
+ * @param node - Accessibility node
+ * @returns Formatted properties text
+ */
+function buildPropertiesText(node) {
     const props = [];
     if (node.focusable)
         props.push('focusable');
@@ -179,47 +170,304 @@ function formatSemanticNodeWithContext(data) {
         props.push('disabled');
     if (node.required)
         props.push('required');
-    const propsText = props.length > 0 ? ` (${props.join(', ')})` : '';
-    // Add inferred indicator when node is synthesized from DOM
+    return props.length > 0 ? ` (${props.join(', ')})` : '';
+}
+/**
+ * Format semantic node with DOM context for display.
+ *
+ * @param data - Node and context data
+ * @returns Formatted string representation
+ */
+function formatSemanticNodeWithContext(data) {
+    const { node, domContext } = data;
+    const roleText = buildRoleText(node);
+    const contextText = buildContextText(node, domContext);
+    const propsText = buildPropertiesText(node);
     const inferredText = node.inferred ? ' (inferred from DOM)' : '';
     return `${roleText}${contextText}${propsText}${inferredText}`;
 }
 /**
- * Capitalize first letter of string.
+ * Resolve node with graceful degradation to synthesized node.
+ *
+ * @param a11yNode - Accessibility node or null
+ * @param domContext - DOM context for synthesis fallback
+ * @param nodeId - Node ID for synthesis
+ * @returns Resolved node or null
  */
-function capitalize(str) {
-    return str.charAt(0).toUpperCase() + str.slice(1);
+function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
+    if (a11yNode)
+        return a11yNode;
+    if (domContext && nodeId)
+        return synthesizeA11yNode(domContext, nodeId);
+    return null;
 }
 /**
- * Handle bdg dom screenshot <path> command
+ * Query DOM context by selector when a11y node is unavailable.
  *
- * Captures a screenshot of the current page and saves it to disk.
- * Supports PNG and JPEG formats with customizable quality and viewport options.
- * Uses CDP relay through worker's persistent connection.
+ * @param selector - CSS selector
+ * @returns Object with nodeId and domContext
+ */
+async function queryDomContextBySelector(selector) {
+    const { callCDP } = await import('../../ipc/client.js');
+    const docResponse = await callCDP('DOM.getDocument', {});
+    const doc = docResponse.data?.result;
+    if (!doc?.root?.nodeId) {
+        return { nodeId: undefined, domContext: null };
+    }
+    const queryResponse = await callCDP('DOM.querySelector', {
+        nodeId: doc.root.nodeId,
+        selector,
+    });
+    const queryResult = queryResponse.data?.result;
+    if (!queryResult?.nodeId) {
+        return { nodeId: undefined, domContext: null };
+    }
+    const domContext = await getDomContext(queryResult.nodeId);
+    return { nodeId: queryResult.nodeId, domContext };
+}
+/**
+ * Handle bdg dom query command.
  *
- * @param path - Output file path (absolute or relative)
- * @param options - Screenshot options (format, quality, fullPage)
+ * @param selector - CSS selector to query
+ * @param options - Command options
  */
-async function handleDomScreenshot(path, options) {
+async function handleDomQuery(selector, options) {
     await runCommand(async () => {
-        const screenshotOptions = filterDefined({
-            format: options.format,
-            quality: options.quality,
-            fullPage: options.fullPage,
+        const result = await queryDOMElements(selector);
+        const cacheManager = QueryCacheManager.getInstance();
+        const navigationId = await cacheManager.getCurrentNavigationId();
+        const resultWithNavId = {
+            ...result,
+            ...(navigationId !== null && { navigationId }),
+        };
+        await cacheManager.set(resultWithNavId);
+        return { success: true, data: result };
+    }, options, formatDomQuery);
+}
+/**
+ * Handle get command with numeric index in raw mode.
+ *
+ * @param index - Element index
+ * @param options - Command options
+ */
+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);
+}
+/**
+ * Handle get command with numeric index in semantic mode.
+ *
+ * @param index - Element index
+ * @param options - Command options
+ */
+async function handleIndexGetSemantic(index, options) {
+    const resolver = DomElementResolver.getInstance();
+    await runCommand(async () => {
+        const targetNode = await resolver.getNodeIdForIndex(index);
+        const [a11yNode, domContext] = await Promise.all([
+            resolveA11yNode('', targetNode.nodeId),
+            getDomContext(targetNode.nodeId),
+        ]);
+        const node = resolveNodeWithFallback(a11yNode, domContext, targetNode.nodeId);
+        if (!node) {
+            throw new CommandError(elementNotFoundError(`index ${index}`), {}, EXIT_CODES.RESOURCE_NOT_FOUND);
+        }
+        return { success: true, data: { node, domContext } };
+    }, options, formatSemanticNodeWithContext);
+}
+/**
+ * Handle get command with numeric index.
+ *
+ * @param index - Element index
+ * @param options - Command options
+ */
+async function handleIndexGet(index, options) {
+    if (options.raw) {
+        await handleIndexGetRaw(index, options);
+    }
+    else {
+        await handleIndexGetSemantic(index, options);
+    }
+}
+/**
+ * Handle get command with CSS selector in raw mode.
+ *
+ * @param selector - CSS selector
+ * @param options - Command options
+ */
+async function handleSelectorGetRaw(selector, options) {
+    await runCommand(async () => {
+        const getOptions = filterDefined({
+            selector,
+            all: options.all,
+            nth: options.nth,
+            nodeId: options.nodeId,
         });
-        const result = await capturePageScreenshot(path, screenshotOptions);
+        const result = await getDOMElements(getOptions);
+        return { success: true, data: result };
+    }, options, formatDomGet);
+}
+/**
+ * Handle get command with CSS selector in semantic mode.
+ *
+ * @param selector - CSS selector
+ * @param options - Command options
+ */
+async function handleSelectorGetSemantic(selector, options) {
+    await runCommand(async () => {
+        const a11yNode = await resolveA11yNode(selector);
+        let domContext = null;
+        let nodeId;
+        if (a11yNode?.backendDOMNodeId) {
+            nodeId = a11yNode.backendDOMNodeId;
+            domContext = await getDomContext(nodeId);
+        }
+        else if (!a11yNode) {
+            const queryResult = await queryDomContextBySelector(selector);
+            nodeId = queryResult.nodeId;
+            domContext = queryResult.domContext;
+        }
+        const node = resolveNodeWithFallback(a11yNode, domContext, nodeId);
+        if (!node) {
+            throw new CommandError(elementNotFoundError(selector), {}, EXIT_CODES.RESOURCE_NOT_FOUND);
+        }
+        return { success: true, data: { node, domContext } };
+    }, options, formatSemanticNodeWithContext);
+}
+/**
+ * Handle get command with CSS selector.
+ *
+ * @param selector - CSS selector
+ * @param options - Command options
+ */
+async function handleSelectorGet(selector, options) {
+    if (options.raw) {
+        await handleSelectorGetRaw(selector, options);
+    }
+    else {
+        await handleSelectorGetSemantic(selector, options);
+    }
+}
+/**
+ * Handle bdg dom get command.
+ *
+ * @param selectorOrIndex - CSS selector or numeric index
+ * @param options - Command options
+ */
+async function handleDomGet(selectorOrIndex, options) {
+    const isNumericIndex = /^\d+$/.test(selectorOrIndex);
+    if (isNumericIndex) {
+        await handleIndexGet(parseInt(selectorOrIndex, 10), options);
+    }
+    else {
+        await handleSelectorGet(selectorOrIndex, options);
+    }
+}
+/**
+ * Handle page-level screenshot capture.
+ *
+ * @param outputPath - Output file path
+ * @param options - Screenshot options
+ */
+async function handlePageScreenshot(outputPath, options) {
+    await runCommand(async () => {
+        const screenshotOptions = buildPageScreenshotOptions(options);
+        const result = await capturePageScreenshot(outputPath, screenshotOptions);
         return { success: true, data: result };
     }, options, formatDomScreenshot);
 }
 /**
- * Handle bdg dom eval <script> command
+ * Handle element-level screenshot capture.
  *
- * Evaluates arbitrary JavaScript in the browser context and returns the result.
- * Requires an active session. Uses CDP Runtime.evaluate with async support.
- * Note: This command uses direct CDP connection (not IPC) so it follows a different pattern.
+ * @param outputPath - Output file path
+ * @param options - Screenshot options with selector or index
+ */
+async function handleElementScreenshot(outputPath, options) {
+    await runCommand(async () => {
+        const nodeId = await resolveElementNodeId(options);
+        const screenshotOptions = buildElementScreenshotOptions(options);
+        const result = await captureElementScreenshot(outputPath, nodeId, screenshotOptions);
+        const elementResult = addElementInfo(result, options);
+        return { success: true, data: elementResult };
+    }, options, formatDomScreenshot);
+}
+/**
+ * Capture a single frame in sequence mode.
+ *
+ * @param outputPath - Full path for the frame file
+ * @param options - Screenshot options
+ */
+async function captureSequenceFrame(outputPath, options) {
+    if (hasElementTarget(options)) {
+        const nodeId = await resolveElementNodeId(options);
+        const elementOptions = buildElementScreenshotOptions(options);
+        await captureElementScreenshot(outputPath, nodeId, elementOptions);
+    }
+    else {
+        const pageOptions = buildPageScreenshotOptions(options);
+        await capturePageScreenshot(outputPath, pageOptions);
+    }
+}
+/**
+ * Handle screenshot sequence capture to directory.
+ *
+ * @param outputDir - Output directory path
+ * @param options - Screenshot options with interval and limit
+ */
+async function handleSequenceCapture(outputDir, options) {
+    const fs = await import('fs');
+    const path = await import('path');
+    const absoluteDir = path.resolve(outputDir);
+    ensureDirectory(absoluteDir, fs);
+    const intervalRule = positiveIntRule({ min: 100, max: 60000, default: 1000 });
+    const limitRule = positiveIntRule({ min: 1, max: 10000, required: false });
+    const interval = intervalRule.validate(options.interval);
+    const limit = options.limit ? limitRule.validate(options.limit) : 0;
+    const format = options.format ?? 'png';
+    let frameCount = 0;
+    const captureFrame = async () => {
+        frameCount++;
+        const filename = formatFrameFilename(frameCount, format);
+        const outputPath = path.join(absoluteDir, filename);
+        await captureSequenceFrame(outputPath, options);
+        console.error(`Frame ${frameCount}: ${filename}`);
+        if (limit > 0 && frameCount >= limit) {
+            process.emit('SIGINT');
+        }
+    };
+    await setupFollowMode(captureFrame, {
+        startMessage: () => `Capturing to ${absoluteDir} every ${interval}ms...`,
+        stopMessage: () => `Captured ${frameCount} frames`,
+        intervalMs: interval,
+    });
+}
+/**
+ * Handle bdg dom screenshot command.
  *
- * @param script - JavaScript expression to evaluate (e.g., "document.title", "window.location.href")
- * @param options - Command options including port and json formatting
+ * @param outputPath - Output file path or directory
+ * @param options - Screenshot options
+ */
+async function handleDomScreenshot(outputPath, options) {
+    if (options.follow) {
+        await handleSequenceCapture(outputPath, options);
+        return;
+    }
+    if (hasElementTarget(options)) {
+        await handleElementScreenshot(outputPath, options);
+        return;
+    }
+    await handlePageScreenshot(outputPath, options);
+}
+/**
+ * Handle bdg dom eval command.
+ *
+ * @param script - JavaScript expression to evaluate
+ * @param options - Command options
  */
 async function handleDomEval(script, options) {
     await runCommand(async () => {
@@ -243,12 +491,15 @@ async function handleDomEval(script, options) {
     }, options, formatDomEval);
 }
 /**
- * Register DOM telemetry commands
+ * Register DOM telemetry commands.
  *
  * @param program - Commander.js Command instance
  */
 export function registerDomCommands(program) {
-    const dom = program.command('dom').description('DOM inspection and manipulation');
+    const dom = program
+        .command('dom')
+        .description('DOM inspection and manipulation')
+        .enablePositionalOptions();
     registerA11yCommands(dom);
     dom
         .command('query')
@@ -281,11 +532,16 @@ export function registerDomCommands(program) {
     });
     dom
         .command('screenshot')
-        .description('Capture page screenshot')
-        .argument('<path>', 'Output file path (e.g., "./screenshot.png")')
+        .description('Capture page or element screenshot')
+        .argument('<path>', 'Output file path, or directory for --follow mode')
+        .option('--selector <selector>', 'CSS selector for element capture')
+        .option('--index <number>', 'Cached element index (0-based) from previous query', parseInt)
         .option('--format <format>', 'Image format: png or jpeg (default: png)')
         .option('--quality <number>', 'JPEG quality 0-100 (default: 90)', parseInt)
         .option('--no-full-page', 'Capture viewport only (default: full page)')
+        .option('-f, --follow', 'Continuous capture mode to directory')
+        .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);