feat: promote eval to top-level command, add --frame option for iframe targeting

- Move `bdg dom eval` to `bdg eval` as a top-level command
- Add FrameOptions interface and --frame flag for DOM commands to target iframes
- Add error logging utility
- Update all references, formatters, messages, and tests

Author: sfc-gh-mochen

.claude/skills/bdg/SKILL.md

@@ -5,6 +5,8 @@ description: Use bdg CLI for browser automation via Chrome DevTools Protocol. Pr
 
 # bdg - Browser Automation CLI
 
+**Always use `--json`** for programmatic output - human output truncates URLs and omits details.
+
 ## Quick Start
 
 ```bash
@@ -65,6 +67,32 @@ bdg dom query "button"            # Shows [0], [1], [2]...
 bdg dom click "button" --index 0  # Click first match
 ```
 
+## Iframe Support
+
+Use `--frame` to query/interact with elements inside iframes (same-origin only):
+
+```bash
+# Find iframe first
+bdg dom query "iframe" --json                           # List iframes by tag
+bdg dom query 'iframe[title="MyApp"]' --json            # Find by title attribute
+
+# Query inside iframe
+bdg dom query "[aria-label='Submit']" --frame 'iframe[title="MyApp"]' --json
+
+# Interact with elements inside iframe
+bdg dom click "button.submit" --frame 'iframe[title="MyApp"]'
+bdg dom fill "input[name='email']" "test@example.com" --frame 'iframe[title="MyApp"]'
+bdg dom pressKey "input" Enter --frame 'iframe[title="MyApp"]'
+bdg dom get "form" --raw --frame 'iframe[title="MyApp"]'
+```
+
+**Notes:**
+- Only works with same-origin iframes (cross-origin iframes are blocked by browser security)
+- Use `bdg eval` for advanced iframe access:
+  ```bash
+  bdg eval 'document.querySelector("iframe").contentDocument.querySelector("button")?.outerHTML'
+  ```
+
 ## Form Interaction
 
 ```bash
@@ -82,12 +110,32 @@ Options: `--no-wait`, `--wait-navigation`, `--wait-network <ms>`, `--index <n>`
 ## DOM Inspection
 
 ```bash
-bdg dom query "selector"     # Find elements matching selector
-bdg dom get "selector"       # Get semantic a11y info (token-efficient)
-bdg dom get "selector" --raw # Get full HTML
-bdg dom eval "js expression" # Run JavaScript (handles DOM elements)
+bdg dom query "selector" --json  # Find elements (returns nodeIds, classes, text)
+bdg dom get "selector" --json    # Get semantic a11y info (token-efficient)
+bdg dom get "selector" --raw     # Get full HTML
+bdg eval "js expression"         # Run JavaScript (handles DOM elements)
 ```
 
+## Network Requests
+
+Network capture is **automatic** from session start. **Always use `--json`** for full data (URLs are truncated in human output).
+
+```bash
+bdg network list --json                              # List requests (full URLs, headers, bodies)
+bdg network list --json --last 0                     # All requests
+bdg network list --json --preset errors              # 4xx/5xx responses
+bdg network list --json --preset api                 # XHR/Fetch only
+bdg network list --json --filter "domain:api.* status-code:>=400"
+bdg network har /tmp/trace.har                       # Export as HAR file
+bdg network getCookies --json                        # List cookies
+bdg network headers --json                           # Main document headers
+bdg network headers --json <request-id>              # Specific request headers
+```
+
+Filter syntax: `status-code:>=400`, `domain:api.*`, `method:POST`, `mime-type:application/json`, `larger-than:100KB`, `!domain:cdn.*` (negate)
+
+Presets: `errors`, `api`, `large`, `cached`, `documents`, `media`, `scripts`, `pending`
+
 ## CDP Access
 
 Direct access to Chrome DevTools Protocol:

src/commands.ts

@@ -6,6 +6,7 @@ import { registerConsoleCommand } from '@/commands/console.js';
 import { registerDetailsCommand } from '@/commands/details.js';
 import { registerFormInteractionCommands } from '@/commands/dom/formInteraction.js';
 import { registerDomCommands } from '@/commands/dom/index.js';
+import { registerEvalCommand } from '@/commands/eval.js';
 import { registerNetworkCommands } from '@/commands/network/index.js';
 import { registerPeekCommand } from '@/commands/peek.js';
 import { registerStartCommands } from '@/commands/start.js';
@@ -45,6 +46,7 @@ export const commandRegistry: CommandRegistrar[] = [
   registerDetailsCommand,
   registerDomCommands,
   registerFormInteractionCommands,
+  registerEvalCommand,
 
   addCommandGroup('CDP Commands:'),
   registerCdpCommand,

src/commands/cdp.ts

@@ -25,7 +25,7 @@ import { findSimilar } from '@/utils/suggestions.js';
 const DOMAIN_NOTES: Record<string, string> = {
   Audits:
     'Event-based domain. Results arrive via events (e.g., Audits.issueAdded), not method responses. ' +
-    "For contrast checking, use: bdg dom eval 'getComputedStyle(el).color'",
+    "For contrast checking, use: bdg eval 'getComputedStyle(el).color'",
   Overlay:
     'Visual debugging domain. Methods like highlightNode show overlays but return empty. ' +
     'Use Overlay.hideHighlight to clear.',
@@ -44,7 +44,7 @@ const DOMAIN_NOTES: Record<string, string> = {
 const METHOD_NOTES: Record<string, string> = {
   'Audits.checkContrast':
     'This method triggers contrast analysis but results are sent via Audits.issueAdded events. ' +
-    'Alternative: bdg dom eval with getComputedStyle() for direct contrast checking.',
+    'Alternative: bdg eval with getComputedStyle() for direct contrast checking.',
   'Audits.enable': 'Enables the Audits domain. Issues will arrive via Audits.issueAdded events.',
   'Overlay.highlightNode':
     'Highlights a node visually. Returns empty on success. Use Overlay.hideHighlight to clear.',

src/commands/dom/formFillHelpers.ts

@@ -90,12 +90,12 @@ function formatScriptExecutionError(
       ? [
           `1. Verify element exists: bdg dom query "${selector}"`,
           '2. Check element is visible and not disabled',
-          `3. Try direct eval: bdg dom eval "document.querySelector('${escapeSelectorForJS(selector)}').value = 'your-value'"`,
+          `3. Try direct eval: bdg eval "document.querySelector('${escapeSelectorForJS(selector)}').value = 'your-value'"`,
         ]
       : [
           `1. Verify element exists: bdg dom query "${selector}"`,
           '2. Check element is visible and clickable',
-          `3. Try direct eval: bdg dom eval "document.querySelector('${escapeSelectorForJS(selector)}').click()"`,
+          `3. Try direct eval: bdg eval "document.querySelector('${escapeSelectorForJS(selector)}').click()"`,
         ];
 
   lines.push('');
@@ -133,6 +133,7 @@ export async function fillElement(
   const scriptOptions = {
     blur: options.blur ?? true,
     index: options.index,
+    frame: options.frame,
   };
 
   const expression = `(${REACT_FILL_SCRIPT})('${escapeSelectorForJS(selector)}', '${escapeValueForJS(value)}', ${JSON.stringify(scriptOptions)})`;
@@ -201,10 +202,11 @@ export async function fillElement(
 export async function clickElement(
   cdp: CDPConnection,
   selector: string,
-  options: { index?: number } = {}
+  options: { index?: number; frame?: string } = {}
 ): Promise<ClickResult> {
   const indexArg = options.index ?? 'null';
-  const expression = `(${CLICK_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}', ${indexArg})`;
+  const frameArg = options.frame ? `'${escapeSelectorForJS(options.frame)}'` : 'null';
+  const expression = `(${CLICK_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}', ${indexArg}, ${frameArg})`;
 
   try {
     const response = await cdp.send('Runtime.evaluate', {
@@ -346,6 +348,8 @@ export interface PressKeyOptions {
   index?: number;
   /** Number of times to press the key (default: 1) */
   times?: number;
+  /** CSS selector for iframe to query within */
+  frame?: string;
   /** Comma-separated modifier keys (shift, ctrl, alt, meta) */
   modifiers?: string;
 }
@@ -370,9 +374,9 @@ export interface PressKeyResult {
  * @returns Object with success status and element info
  */
 const FOCUS_ELEMENT_SCRIPT = `
-(function(selector) {
+(function(selector, frameSelector) {
 ${QUERY_ELEMENTS_HELPER}
-  const elements = __bdgQueryElements(selector);
+  const elements = __bdgQueryElements(selector, frameSelector || null);
   if (elements.length === 0) {
     return { success: false, error: 'No nodes found matching selector: ' + selector };
   }
@@ -429,7 +433,8 @@ export async function pressKeyElement(
 
   const times = options.times ?? 1;
   const modifierFlags = parseModifiers(options.modifiers);
-  const focusExpression = `(${FOCUS_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}')`;
+  const frameArg = options.frame ? `'${escapeSelectorForJS(options.frame)}'` : 'null';
+  const focusExpression = `(${FOCUS_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}', ${frameArg})`;
 
   try {
     const focusResponse = await cdp.send('Runtime.evaluate', {
@@ -597,6 +602,8 @@ export interface ScrollOptions {
   bottom?: boolean;
   /** Element index if selector matches multiple (0-based) */
   index?: number;
+  /** CSS selector for iframe to query within */
+  frame?: string;
 }
 
 /**
@@ -631,9 +638,9 @@ export interface ScrollResult {
  * Script to scroll an element into view.
  */
 const SCROLL_TO_ELEMENT_SCRIPT = `
-(function(selector) {
+(function(selector, frameSelector) {
 ${QUERY_ELEMENTS_HELPER}
-  const elements = __bdgQueryElements(selector);
+  const elements = __bdgQueryElements(selector, frameSelector || null);
   if (elements.length === 0) {
     return { success: false, error: 'No nodes found matching selector: ' + selector };
   }
@@ -747,7 +754,8 @@ export async function scrollPage(
 ): Promise<ScrollResult> {
   try {
     if (selector) {
-      const expression = `(${SCROLL_TO_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}')`;
+      const frameArg = options.frame ? `'${escapeSelectorForJS(options.frame)}'` : 'null';
+      const expression = `(${SCROLL_TO_ELEMENT_SCRIPT})('${escapeSelectorForJS(selector)}', ${frameArg})`;
 
       const response = await cdp.send('Runtime.evaluate', {
         expression,

src/commands/dom/formInteraction.ts

@@ -113,6 +113,7 @@ export function registerFormInteractionCommands(program: Command): void {
     .option('--index <n>', 'Element index if selector matches multiple (0-based)', parseInt)
     .option('--no-blur', 'Do not blur after filling (keeps focus on element)')
     .option('--no-wait', 'Skip waiting for network stability after fill')
+    .option('--frame <selector>', 'Query inside iframe matching selector')
     .addOption(jsonOption())
     .action(async (selector: string, value: string, options: FillCommandOptions) => {
       await runCommand(
@@ -121,7 +122,8 @@ export function registerFormInteractionCommands(program: Command): void {
             const fillOptions = filterDefined({
               index: options.index,
               blur: options.blur,
-            }) as { index?: number; blur?: boolean };
+              frame: options.frame,
+            }) as { index?: number; blur?: boolean; frame?: string };
 
             const result = await fillElement(cdp, selector, value, fillOptions);
 
@@ -158,14 +160,16 @@ export function registerFormInteractionCommands(program: Command): void {
     .argument('<selector>', 'CSS/Playwright selector (e.g., "button", ":text(\'Submit\')")')
     .option('--index <n>', 'Element index if selector matches multiple (0-based)', parseInt)
     .option('--no-wait', 'Skip waiting for network stability after click')
+    .option('--frame <selector>', 'Query inside iframe matching selector')
     .addOption(jsonOption())
     .action(async (selector: string, options: ClickCommandOptions) => {
       await runCommand(
         async () => {
           return await withCDPConnection(async (cdp) => {
             const clickOptions = filterDefined({
               index: options.index,
-            }) as { index?: number };
+              frame: options.frame,
+            }) as { index?: number; frame?: string };
 
             const result = await clickElement(cdp, selector, clickOptions);
 
@@ -255,6 +259,7 @@ export function registerFormInteractionCommands(program: Command): void {
     .option('--times <n>', 'Press key multiple times (default: 1)', parseInt)
     .option('--modifiers <mods>', 'Modifier keys: shift,ctrl,alt,meta (comma-separated)')
     .option('--no-wait', 'Skip waiting for network stability after key press')
+    .option('--frame <selector>', 'Query inside iframe matching selector')
     .addOption(jsonOption())
     .action(async (selector: string, key: string, options: PressKeyCommandOptions) => {
       await runCommand(
@@ -264,7 +269,8 @@ export function registerFormInteractionCommands(program: Command): void {
               index: options.index,
               times: options.times,
               modifiers: options.modifiers,
-            }) as { index?: number; times?: number; modifiers?: string };
+              frame: options.frame,
+            }) as { index?: number; times?: number; modifiers?: string; frame?: string };
 
             const result = await pressKeyElement(cdp, selector, key, pressKeyOptions);
 
@@ -306,6 +312,7 @@ export function registerFormInteractionCommands(program: Command): void {
     .option('--top', 'Scroll to page top')
     .option('--bottom', 'Scroll to page bottom')
     .option('--no-wait', 'Skip waiting for lazy-loaded content after scroll')
+    .option('--frame <selector>', 'Query inside iframe matching selector')
     .addOption(jsonOption())
     .action(async (selector: string | undefined, options: ScrollCommandOptions) => {
       await runCommand(
@@ -369,6 +376,7 @@ export function registerFormInteractionCommands(program: Command): void {
               right: options.right,
               top: options.top,
               bottom: options.bottom,
+              frame: options.frame,
             }) as {
               index?: number;
               down?: number;
@@ -377,6 +385,7 @@ export function registerFormInteractionCommands(program: Command): void {
               right?: number;
               top?: boolean;
               bottom?: boolean;
+              frame?: string;
             };
 
             const result = await scrollPage(cdp, selector, scrollOptions);

src/commands/dom/helpers.ts

@@ -68,12 +68,24 @@ const STABILITY_CHECK_INTERVAL_MS = 50;
 /**
  * JavaScript helper for Playwright-style selector support.
  * Injected into browser context for all DOM queries.
+ *
+ * @param selector - CSS/Playwright selector
+ * @param frameSelector - Optional iframe selector to query within
  */
 const QUERY_ELEMENTS_JS = `
-function __bdgQueryElements(selector) {
+function __bdgQueryElements(selector, frameSelector) {
+  // Get the document to query (main document or iframe contentDocument)
+  let doc = document;
+  if (frameSelector) {
+    const frame = document.querySelector(frameSelector);
+    if (!frame) return [];
+    doc = frame.contentDocument;
+    if (!doc) return []; // Cross-origin iframe
+  }
+
   // Quick check for Playwright pseudo-classes
   if (!/:(?:has-text|text-is|text|visible)\\s*(?:\\(|$)/.test(selector)) {
-    return [...document.querySelectorAll(selector)];
+    return [...doc.querySelectorAll(selector)];
   }
 
   // Parse out Playwright pseudo-classes
@@ -108,9 +120,10 @@ function __bdgQueryElements(selector) {
   cssSelector = cssSelector.replace(/\\s+/g, ' ').trim() || '*';
 
   // Query with CSS selector
-  let elements = [...document.querySelectorAll(cssSelector)];
+  let elements = [...doc.querySelectorAll(cssSelector)];
 
-  // Apply filters for each pseudo-class
+  // Apply filters for each pseudo-class (use main window for getComputedStyle)
+  const win = doc.defaultView || window;
   for (const pseudo of pseudoMatches) {
     elements = elements.filter(el => {
       switch (pseudo.type) {
@@ -133,7 +146,7 @@ function __bdgQueryElements(selector) {
           return el.textContent?.replace(/\\s+/g, ' ').trim() === pseudo.arg;
         }
         case 'visible': {
-          const style = window.getComputedStyle(el);
+          const style = win.getComputedStyle(el);
           if (style.display === 'none') return false;
           if (style.visibility === 'hidden') return false;
           if (style.opacity === '0') return false;
@@ -325,16 +338,19 @@ async function restoreScrollPosition(position: ScrollPosition): Promise<void> {
  * Supports standard CSS selectors and Playwright-style pseudo-classes.
  *
  * @param selector - CSS/Playwright selector
+ * @param frame - Optional iframe selector to query within
  * @returns Query result with matched nodes
  */
-export async function queryDOMElements(selector: string): Promise<DomQueryResult> {
+export async function queryDOMElements(selector: string, frame?: string): Promise<DomQueryResult> {
   const escapedSelector = escapeSelector(selector);
+  const escapedFrame = frame ? escapeSelector(frame) : '';
+  const frameArg = frame ? `'${escapedFrame}'` : 'null';
 
   const result = await callCDP('Runtime.evaluate', {
     expression: `
       ${QUERY_ELEMENTS_JS}
       (() => {
-        const elements = __bdgQueryElements('${escapedSelector}');
+        const elements = __bdgQueryElements('${escapedSelector}', ${frameArg});
         return elements.map((el, index) => {
           const tag = el.tagName?.toLowerCase() || '';
           const classes = el.className?.split?.(/\\s+/).filter(c => c.length > 0) || [];
@@ -383,12 +399,14 @@ export async function getDOMElements(options: DomGetOptions): Promise<DomGetResu
   }
 
   const escapedSelector = escapeSelector(options.selector);
+  const escapedFrame = options.frame ? escapeSelector(options.frame) : '';
+  const frameArg = options.frame ? `'${escapedFrame}'` : 'null';
 
   const result = await callCDP('Runtime.evaluate', {
     expression: `
       ${QUERY_ELEMENTS_JS}
       (() => {
-        const elements = __bdgQueryElements('${escapedSelector}');
+        const elements = __bdgQueryElements('${escapedSelector}', ${frameArg});
         ${options.all ? '' : 'elements.splice(1);'} // Keep only first unless --all
         return elements.map(el => {
           const tag = el.tagName?.toLowerCase() || '';