browser-debugger-cli 0.2.0 → 0.5.1

package/dist/commands/dom.js

@@ -1,8 +1,8 @@
-import { OutputBuilder } from '../commands/shared/OutputBuilder.js';
-import { queryDOM, highlightDOM, getDOM } from '../ipc/client.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
-import { handleCommandError } from './domErrorHandler.js';
-import { buildSelectorOptions } from './domOptionsBuilder.js';
+import { runCommand } from '../commands/shared/CommandRunner.js';
+import { queryDOM, highlightDOM, getDOM, captureScreenshot } from '../ipc/client.js';
+import { formatDomQuery, formatDomHighlight, formatDomGet, formatDomEval, formatDomScreenshot, } from '../ui/formatters/dom.js';
+import { filterDefined } from '../utils/objects.js';
+import { mergeWithSelector } from './domOptionsBuilder.js';
 /**
  * Handle bdg dom query <selector> command
  *
@@ -11,49 +11,27 @@ import { buildSelectorOptions } from './domOptionsBuilder.js';
  *
  * @param selector - CSS selector to query (e.g., ".error", "#app", "button")
  * @param options - Command options
- * @throws Error When IPC request fails or returns error response
- * @throws Error When response data is missing
  */
 async function handleDomQuery(selector, options) {
-    try {
-        // Send query request via IPC to daemon/worker
+    await runCommand(async () => {
         const response = await queryDOM(selector);
         if (response.status === 'error') {
-            throw new Error(response.error ?? 'Unknown error');
+            return {
+                success: false,
+                error: response.error ?? 'Unknown error',
+            };
         }
         if (!response.data) {
-            throw new Error('No data in response');
+            return {
+                success: false,
+                error: 'No data in response',
+            };
         }
-        const { count, nodes } = response.data;
-        if (count === 0) {
-            if (options.json) {
-                console.log(JSON.stringify({
-                    selector,
-                    count: 0,
-                    nodes: [],
-                }, null, 2));
-            }
-            else {
-                console.log(`No elements found matching "${selector}"`);
-            }
-            process.exit(EXIT_CODES.SUCCESS);
-        }
-        // Output results
-        if (options.json) {
-            console.log(JSON.stringify(response.data, null, 2));
-        }
-        else {
-            console.log(`Found ${count} element${count === 1 ? '' : 's'} matching "${selector}":`);
-            for (const node of nodes) {
-                const classInfo = node.classes && node.classes.length > 0 ? ` class="${node.classes.join(' ')}"` : '';
-                console.log(`  [${node.index}] <${node.tag}${classInfo}> ${node.preview}`);
-            }
-        }
-        process.exit(EXIT_CODES.SUCCESS);
-    }
-    catch (error) {
-        handleCommandError(error, options.json ?? false);
-    }
+        return {
+            success: true,
+            data: response.data,
+        };
+    }, options, formatDomQuery);
 }
 /**
  * Handle bdg dom highlight command
@@ -63,42 +41,34 @@ async function handleDomQuery(selector, options) {
  *
  * @param selectorOrIndex - CSS selector (e.g., ".error") or index from cached query (e.g., "2")
  * @param options - Command options including color, opacity, targeting flags, and nodeId
- * @throws Error When cached index not found (user must run 'bdg dom query' first)
- * @throws Error When IPC request fails or returns error response
- * @throws Error When response data is missing
  */
 async function handleDomHighlight(selectorOrIndex, options) {
-    try {
-        // Build base IPC request options (color, opacity, targeting)
-        const ipcOptions = {
-            ...(options.color !== undefined && { color: options.color }),
-            ...(options.opacity !== undefined && { opacity: options.opacity }),
-            ...(options.first !== undefined && { first: options.first }),
-            ...(options.nth !== undefined && { nth: options.nth }),
-        };
-        // Add selector/index/nodeId using shared helper
-        const selectorOptions = buildSelectorOptions(selectorOrIndex, options.nodeId);
-        Object.assign(ipcOptions, selectorOptions);
-        // Send highlight request via IPC to daemon/worker
+    await runCommand(async () => {
+        // Build IPC options with selector/index/nodeId merged
+        const ipcOptions = mergeWithSelector(filterDefined({
+            color: options.color,
+            opacity: options.opacity,
+            first: options.first,
+            nth: options.nth,
+        }), selectorOrIndex, options.nodeId);
         const response = await highlightDOM(ipcOptions);
         if (response.status === 'error') {
-            throw new Error(response.error ?? 'Unknown error');
+            return {
+                success: false,
+                error: response.error ?? 'Unknown error',
+            };
         }
         if (!response.data) {
-            throw new Error('No data in response');
-        }
-        // Output result
-        if (options.json) {
-            console.log(JSON.stringify(response.data, null, 2));
+            return {
+                success: false,
+                error: 'No data in response',
+            };
         }
-        else {
-            console.log(`✓ Highlighted ${response.data.highlighted} element${response.data.highlighted === 1 ? '' : 's'}`);
-        }
-        process.exit(EXIT_CODES.SUCCESS);
-    }
-    catch (error) {
-        handleCommandError(error, options.json ?? false);
-    }
+        return {
+            success: true,
+            data: response.data,
+        };
+    }, options, formatDomHighlight);
 }
 /**
  * Handle bdg dom get command
@@ -108,77 +78,90 @@ async function handleDomHighlight(selectorOrIndex, options) {
  *
  * @param selectorOrIndex - CSS selector (e.g., ".error") or index from cached query (e.g., "2")
  * @param options - Command options including --all, --nth, and nodeId
- * @throws Error When cached index not found (user must run 'bdg dom query' first)
- * @throws Error When IPC request fails or returns error response
- * @throws Error When response data is missing
  */
 async function handleDomGet(selectorOrIndex, options) {
-    try {
-        // Build base IPC request options (targeting flags)
-        const ipcOptions = {
-            ...(options.all !== undefined && { all: options.all }),
-            ...(options.nth !== undefined && { nth: options.nth }),
-        };
-        // Add selector/index/nodeId using shared helper
-        const selectorOptions = buildSelectorOptions(selectorOrIndex, options.nodeId);
-        Object.assign(ipcOptions, selectorOptions);
-        // Send get request via IPC to daemon/worker
+    await runCommand(async () => {
+        // Build IPC options with selector/index/nodeId merged
+        const ipcOptions = mergeWithSelector(filterDefined({
+            all: options.all,
+            nth: options.nth,
+        }), selectorOrIndex, options.nodeId);
         const response = await getDOM(ipcOptions);
         if (response.status === 'error') {
-            throw new Error(response.error ?? 'Unknown error');
+            return {
+                success: false,
+                error: response.error ?? 'Unknown error',
+            };
         }
         if (!response.data) {
-            throw new Error('No data in response');
+            return {
+                success: false,
+                error: 'No data in response',
+            };
         }
-        const { nodes } = response.data;
-        // Output results
-        if (options.json) {
-            console.log(JSON.stringify(nodes.length === 1 ? nodes[0] : nodes, null, 2));
+        return {
+            success: true,
+            data: response.data,
+        };
+    }, options, formatDomGet);
+}
+/**
+ * Handle bdg dom screenshot <path> command
+ *
+ * Captures a screenshot of the current page and saves it to disk.
+ * Supports PNG and JPEG formats with customizable quality and viewport options.
+ *
+ * @param path - Output file path (absolute or relative)
+ * @param options - Screenshot options (format, quality, fullPage)
+ */
+async function handleDomScreenshot(path, options) {
+    await runCommand(async () => {
+        const screenshotOptions = filterDefined({
+            format: options.format,
+            quality: options.quality,
+            fullPage: options.fullPage,
+        });
+        const response = await captureScreenshot(path, screenshotOptions);
+        if (response.status === 'error') {
+            return {
+                success: false,
+                error: response.error ?? 'Unknown error',
+            };
         }
-        else {
-            if (nodes.length === 1) {
-                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                console.log(nodes[0].outerHTML);
-            }
-            else {
-                for (const [i, node] of nodes.entries()) {
-                    console.log(`[${i + 1}] ${node.outerHTML}`);
-                }
-            }
+        if (!response.data) {
+            return {
+                success: false,
+                error: 'No data in response',
+            };
         }
-        process.exit(EXIT_CODES.SUCCESS);
-    }
-    catch (error) {
-        handleCommandError(error, options.json ?? false);
-    }
+        return {
+            success: true,
+            data: response.data,
+        };
+    }, options, formatDomScreenshot);
 }
 /**
  * Handle bdg dom eval <script> command
  *
  * 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 script - JavaScript expression to evaluate (e.g., "document.title", "window.location.href")
  * @param options - Command options including port and json formatting
- * @throws Error When no active session is running
- * @throws Error When session metadata is invalid
- * @throws Error When target no longer exists (tab closed)
- * @throws Error When CDP connection fails
- * @throws Error When script execution throws exception
  */
 async function handleDomEval(script, options) {
-    try {
+    await runCommand(async () => {
         // Lazy load CDP connection (only needed for eval command)
         const { CDPConnection } = await import('../connection/cdp.js');
         const { validateActiveSession, getValidatedSessionMetadata, verifyTargetExists, executeScript, } = await import('./domEvalHelpers.js');
         // Validate session is running
-        const jsonOutput = options.json ?? false;
-        validateActiveSession(jsonOutput);
+        validateActiveSession();
         // Get and validate session metadata
-        const metadata = getValidatedSessionMetadata(jsonOutput);
+        const metadata = getValidatedSessionMetadata();
         // Verify target still exists
         const port = parseInt(options.port ?? '9222', 10);
-        await verifyTargetExists(metadata, port, jsonOutput);
+        await verifyTargetExists(metadata, port);
         // Create temporary CDP connection and execute script
         const cdp = new CDPConnection();
         // getValidatedSessionMetadata ensures webSocketDebuggerUrl is defined
@@ -186,20 +169,11 @@ async function handleDomEval(script, options) {
         await cdp.connect(metadata.webSocketDebuggerUrl);
         const result = await executeScript(cdp, script);
         cdp.close();
-        // Output result (wrapped if --json, raw otherwise)
-        if (options.json) {
-            console.log(JSON.stringify(OutputBuilder.buildJsonSuccess({
-                result: result.result?.value,
-            }), null, 2));
-        }
-        else {
-            console.log(JSON.stringify(result.result?.value, null, 2));
-        }
-        process.exit(EXIT_CODES.SUCCESS);
-    }
-    catch (error) {
-        handleCommandError(error, options.json ?? false);
-    }
+        return {
+            success: true,
+            data: { result: result.result?.value },
+        };
+    }, options, formatDomEval);
 }
 /**
  * Register DOM telemetry commands
@@ -253,5 +227,17 @@ export function registerDomCommands(program) {
         .action(async (selectorOrIndex, options) => {
         await handleDomGet(selectorOrIndex, options);
     });
+    // bdg dom screenshot <path>
+    dom
+        .command('screenshot')
+        .description('Capture page screenshot')
+        .argument('<path>', 'Output file path (e.g., "./screenshot.png")')
+        .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('-j, --json', 'Output as JSON')
+        .action(async (path, options) => {
+        await handleDomScreenshot(path, options);
+    });
 }
 //# sourceMappingURL=dom.js.map

package/dist/commands/dom.js.map

@@ -1 +1 @@
-{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../src/commands/dom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../src/commands/dom.ts"],"names":[],"mappings":"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"}

package/dist/commands/domEvalHelpers.d.ts

@@ -16,36 +16,32 @@ interface RuntimeEvaluateResult {
 /**
  * Validate that an active session is running
  *
- * @param json - Whether to output JSON format
  * @returns PID of running session
- * @throws never Exits process if no active session found
+ * @throws Error When no active session is found
  */
-export declare function validateActiveSession(json: boolean): number;
+export declare function validateActiveSession(): number;
 /**
  * Get session metadata with validation
  *
- * @param json - Whether to output JSON format
  * @returns Session metadata including targetId and webSocketDebuggerUrl
- * @throws never Exits process if metadata is invalid or missing required fields
+ * @throws Error When metadata is invalid or missing required fields
  */
-export declare function getValidatedSessionMetadata(json: boolean): SessionMetadata;
+export declare function getValidatedSessionMetadata(): SessionMetadata;
 /**
  * Verify that the CDP target still exists
  *
  * @param metadata - Session metadata containing targetId
  * @param port - CDP port number
- * @param json - Whether to output JSON format
- * @throws Error When CDP response is invalid
- * @throws never Exits process if target not found
+ * @throws Error When CDP response is invalid or target not found
  */
-export declare function verifyTargetExists(metadata: SessionMetadata, port: number, json: boolean): Promise<void>;
+export declare function verifyTargetExists(metadata: SessionMetadata, port: number): Promise<void>;
 /**
  * Execute JavaScript in browser context via CDP
  *
  * @param cdp - CDP connection instance
  * @param script - JavaScript expression to execute
  * @returns Execution result
- * @throws Error When script execution throws exception
+ * @throws Error When script execution throws exception or returns invalid response
  */
 export declare function executeScript(cdp: CDPConnection, script: string): Promise<RuntimeEvaluateResult>;
 export {};

package/dist/commands/domEvalHelpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domEvalHelpers.d.ts","sourceRoot":"","sources":["../../src/commands/domEvalHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAclF;;GAEG;AACH,UAAU,qBAAqB;IAC7B,gBAAgB,CAAC,EAAE;QACjB,SAAS,CAAC,EAAE;YACV,WAAW,CAAC,EAAE,MAAM,CAAC;SACtB,CAAC;KACH,CAAC;IACF,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAW3D;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAc1E;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,CAAC,CAehC"}
+{"version":3,"file":"domEvalHelpers.d.ts","sourceRoot":"","sources":["../../src/commands/domEvalHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAclF;;GAEG;AACH,UAAU,qBAAqB;IAC7B,gBAAgB,CAAC,EAAE;QACjB,SAAS,CAAC,EAAE;YACV,WAAW,CAAC,EAAE,MAAM,CAAC;SACtB,CAAC;KACH,CAAC;IACF,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;CACH;AAoDD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAU9C;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,eAAe,CAY7D;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB/F;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,qBAAqB,CAAC,CA2BhC"}

package/dist/commands/domEvalHelpers.js

@@ -1,35 +1,75 @@
 import { readSessionMetadata } from '../session/metadata.js';
 import { readPid } from '../session/pid.js';
 import { isProcessAlive } from '../session/process.js';
+import { CommandError } from '../ui/errors/index.js';
+import { invalidCDPResponseError } from '../ui/messages/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
-import { handleCommandErrorWithContext } from './domErrorHandler.js';
+/**
+ * Type guard to validate CDP Runtime.evaluate response structure
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid RuntimeEvaluateResult
+ */
+function isRuntimeEvaluateResult(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    // Must have either result or exceptionDetails (or both)
+    if (!('result' in obj) && !('exceptionDetails' in obj)) {
+        return false;
+    }
+    // Validate exceptionDetails structure if present
+    if ('exceptionDetails' in obj) {
+        const exceptionDetails = obj['exceptionDetails'];
+        if (typeof exceptionDetails !== 'object' || exceptionDetails === null) {
+            return false;
+        }
+        const details = exceptionDetails;
+        if ('exception' in details) {
+            const exception = details['exception'];
+            if (typeof exception !== 'object' || exception === null) {
+                return false;
+            }
+            const exObj = exception;
+            if ('description' in exObj && typeof exObj['description'] !== 'string') {
+                return false;
+            }
+        }
+    }
+    // Validate result structure if present
+    if ('result' in obj) {
+        const result = obj['result'];
+        if (typeof result !== 'object' || result === null) {
+            return false;
+        }
+    }
+    return true;
+}
 /**
  * Validate that an active session is running
  *
- * @param json - Whether to output JSON format
  * @returns PID of running session
- * @throws never Exits process if no active session found
+ * @throws Error When no active session is found
  */
-export function validateActiveSession(json) {
+export function validateActiveSession() {
     const pid = readPid();
     if (!pid || !isProcessAlive(pid)) {
-        handleCommandErrorWithContext('No active session running', json, { suggestion: 'Start a session with: bdg <url>' }, EXIT_CODES.RESOURCE_NOT_FOUND);
+        throw new CommandError('No active session running', { suggestion: 'Start a session with: bdg <url>' }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
     return pid;
 }
 /**
  * Get session metadata with validation
  *
- * @param json - Whether to output JSON format
  * @returns Session metadata including targetId and webSocketDebuggerUrl
- * @throws never Exits process if metadata is invalid or missing required fields
+ * @throws Error When metadata is invalid or missing required fields
  */
-export function getValidatedSessionMetadata(json) {
+export function getValidatedSessionMetadata() {
     const metadata = readSessionMetadata();
     if (!metadata?.targetId || !metadata.webSocketDebuggerUrl) {
-        handleCommandErrorWithContext('No target information in session metadata', json, { note: 'Session may have been started with an older version' }, EXIT_CODES.SESSION_FILE_ERROR);
+        throw new CommandError('No target information in session metadata', { note: 'Session may have been started with an older version' }, EXIT_CODES.SESSION_FILE_ERROR);
     }
-    // TypeScript doesn't know handleCommandErrorWithContext never returns
     return metadata;
 }
 /**
@@ -37,19 +77,17 @@ export function getValidatedSessionMetadata(json) {
  *
  * @param metadata - Session metadata containing targetId
  * @param port - CDP port number
- * @param json - Whether to output JSON format
- * @throws Error When CDP response is invalid
- * @throws never Exits process if target not found
+ * @throws Error When CDP response is invalid or target not found
  */
-export async function verifyTargetExists(metadata, port, json) {
+export async function verifyTargetExists(metadata, port) {
     const response = await fetch(`http://127.0.0.1:${port}/json/list`);
     const targetsData = await response.json();
     if (!Array.isArray(targetsData)) {
-        throw new Error('Invalid response from CDP');
+        throw new Error(invalidCDPResponseError());
     }
     const target = targetsData.find((t) => t.id === metadata.targetId);
     if (!target) {
-        handleCommandErrorWithContext('Session target not found (tab may have been closed)', json, { suggestion: 'Start a new session with: bdg <url>' }, EXIT_CODES.RESOURCE_NOT_FOUND);
+        throw new CommandError('Session target not found (tab may have been closed)', { suggestion: 'Start a new session with: bdg <url>' }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
 }
 /**
@@ -58,19 +96,26 @@ export async function verifyTargetExists(metadata, port, json) {
  * @param cdp - CDP connection instance
  * @param script - JavaScript expression to execute
  * @returns Execution result
- * @throws Error When script execution throws exception
+ * @throws Error When script execution throws exception or returns invalid response
  */
 export async function executeScript(cdp, script) {
-    const result = (await cdp.send('Runtime.evaluate', {
+    const response = await cdp.send('Runtime.evaluate', {
         expression: script,
         returnByValue: true,
         awaitPromise: true,
-    }));
+    });
+    // Validate response structure at runtime
+    if (!isRuntimeEvaluateResult(response)) {
+        throw new CommandError('Invalid CDP Runtime.evaluate response structure', {
+            note: 'CDP response did not match expected format',
+            suggestion: 'This may indicate a CDP protocol version mismatch',
+        }, EXIT_CODES.CDP_CONNECTION_FAILURE);
+    }
     // Check for execution exceptions
-    if (result.exceptionDetails) {
-        const errorMsg = result.exceptionDetails.exception?.description ?? 'Unknown error executing script';
+    if (response.exceptionDetails) {
+        const errorMsg = response.exceptionDetails.exception?.description ?? 'Unknown error executing script';
         throw new Error(errorMsg);
     }
-    return result;
+    return response;
 }
 //# sourceMappingURL=domEvalHelpers.js.map

package/dist/commands/domEvalHelpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"domEvalHelpers.js","sourceRoot":"","sources":["../../src/commands/domEvalHelpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAwB,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAuBrE;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,6BAA6B,CAC3B,2BAA2B,EAC3B,IAAI,EACJ,EAAE,UAAU,EAAE,iCAAiC,EAAE,EACjD,UAAU,CAAC,kBAAkB,CAC9B,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAAa;IACvD,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;IAEvC,IAAI,CAAC,QAAQ,EAAE,QAAQ,IAAI,CAAC,QAAQ,CAAC,oBAAoB,EAAE,CAAC;QAC1D,6BAA6B,CAC3B,2CAA2C,EAC3C,IAAI,EACJ,EAAE,IAAI,EAAE,qDAAqD,EAAE,EAC/D,UAAU,CAAC,kBAAkB,CAC9B,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAyB,EACzB,IAAY,EACZ,IAAa;IAEb,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,oBAAoB,IAAI,YAAY,CAAC,CAAC;IACnE,MAAM,WAAW,GAAY,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,MAAM,GAAI,WAA2B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAEpF,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,6BAA6B,CAC3B,qDAAqD,EACrD,IAAI,EACJ,EAAE,UAAU,EAAE,qCAAqC,EAAE,EACrD,UAAU,CAAC,kBAAkB,CAC9B,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAkB,EAClB,MAAc;IAEd,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE;QACjD,UAAU,EAAE,MAAM;QAClB,aAAa,EAAE,IAAI;QACnB,YAAY,EAAE,IAAI;KACnB,CAAC,CAA0B,CAAC;IAE7B,iCAAiC;IACjC,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC5B,MAAM,QAAQ,GACZ,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,IAAI,gCAAgC,CAAC;QACrF,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"domEvalHelpers.js","sourceRoot":"","sources":["../../src/commands/domEvalHelpers.ts"],"names":[],"mappings":"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"}

package/dist/commands/domOptionsBuilder.d.ts

@@ -32,4 +32,36 @@ export interface SelectorBasedOptions {
  * ```
  */
 export declare function buildSelectorOptions<T extends SelectorBasedOptions>(selectorOrIndex: string, nodeId: number | undefined): T;
+/**
+ * Merge base options with selector-based options.
+ *
+ * Convenience helper that combines buildSelectorOptions with base options object.
+ * Eliminates the repeated pattern of:
+ * ```
+ * const selectorOpts = buildSelectorOptions(...);
+ * Object.assign(ipcOptions, selectorOpts);
+ * ```
+ *
+ * @param baseOptions - Base IPC options object
+ * @param selectorOrIndex - CSS selector or cached index
+ * @param nodeId - Optional direct nodeId
+ * @returns Merged options object with selector/index/nodeId added
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * const ipcOptions = { color: 'red', opacity: 0.5 };
+ * const selectorOptions = buildSelectorOptions('.error', undefined);
+ * Object.assign(ipcOptions, selectorOptions);
+ *
+ * // Use:
+ * const ipcOptions = mergeWithSelector(
+ *   { color: 'red', opacity: 0.5 },
+ *   '.error',
+ *   undefined
+ * );
+ * // → { color: 'red', opacity: 0.5, selector: '.error' }
+ * ```
+ */
+export declare function mergeWithSelector<T extends SelectorBasedOptions>(baseOptions: T, selectorOrIndex: string, nodeId: number | undefined): T;
 //# sourceMappingURL=domOptionsBuilder.d.ts.map

package/dist/commands/domOptionsBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domOptionsBuilder.d.ts","sourceRoot":"","sources":["../../src/commands/domOptionsBuilder.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,oBAAoB,EACjE,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,CAAC,CA2BH"}
+{"version":3,"file":"domOptionsBuilder.d.ts","sourceRoot":"","sources":["../../src/commands/domOptionsBuilder.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,oBAAoB,EACjE,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,CAAC,CA2BH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,oBAAoB,EAC9D,WAAW,EAAE,CAAC,EACd,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,CAAC,CAGH"}