browser-debugger-cli 0.6.8 → 0.6.10

package/dist/commands/console.js

@@ -1,11 +1,12 @@
 import { Option } from 'commander';
 import { jsonOption } from '../commands/shared/commonOptions.js';
 import { handleDaemonConnectionError } from '../commands/shared/daemonErrorHandler.js';
+import { setupFollowMode } from '../commands/shared/followMode.js';
 import { getErrorMessage } from '../connection/errors.js';
 import { getPeek } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
 import { CommandError } from '../ui/errors/index.js';
-import { formatConsole, formatConsoleFollow, } from '../ui/formatters/console.js';
+import { formatConsole, formatConsoleFollow, LEVEL_MAP, } from '../ui/formatters/console.js';
 import { followingConsoleMessage, stoppedFollowingConsoleMessage, noConsoleDataMessage, } from '../ui/messages/consoleMessages.js';
 import { invalidLastRangeError } from '../ui/messages/validation.js';
 import { getExitCodeForConnectionError } from '../utils/errorMapping.js';
@@ -43,6 +44,14 @@ const followOption = new Option('-f, --follow', 'Stream console messages in real
  * By default, only current navigation messages are shown.
  */
 const historyOption = new Option('-H, --history', 'Show messages from all page loads (default: current only)').default(false);
+/**
+ * Valid console levels for filtering.
+ */
+const VALID_LEVELS = ['error', 'warning', 'info', 'debug'];
+/**
+ * --level option for filtering by message level.
+ */
+const levelOption = new Option('--level <level>', 'Filter by message level (error, warning, info, debug)').choices(VALID_LEVELS);
 /**
  * Fetch console messages from the daemon.
  *
@@ -51,7 +60,9 @@ const historyOption = new Option('-H, --history', 'Show messages from all page l
  */
 async function fetchConsoleMessages(options) {
     try {
-        const response = await getPeek();
+        // Pass lastN=0 to get all messages (worker applies filtering)
+        // We request all and filter client-side for flexibility
+        const response = await getPeek({ lastN: 0 });
         try {
             validateIPCResponse(response);
         }
@@ -115,41 +126,66 @@ export function filterByCurrentNavigation(messages) {
     return messages.filter((m) => m.navigationId === maxNavigationId);
 }
 /**
- * Display console output based on options.
+ * Filter messages by level.
  *
- * @param messages - Console messages to display
- * @param options - Command options
+ * @param messages - Console messages to filter
+ * @param level - Level to filter by (error, warning, info, debug)
+ * @returns Filtered messages matching the specified level
  */
-function displayConsole(messages, options) {
-    let filteredMessages = messages;
-    // Default: show only current navigation. Use --history for all.
-    if (!options.history) {
-        filteredMessages = filterByCurrentNavigation(messages);
+export function filterByLevel(messages, level) {
+    return messages.filter((m) => LEVEL_MAP[m.type] === level);
+}
+/**
+ * Apply navigation and level filters to console messages.
+ *
+ * @param messages - Raw console messages
+ * @param options - Filter options (history and level)
+ * @returns Filtered messages
+ */
+function applyMessageFilters(messages, options) {
+    let filtered = options.history ? messages : filterByCurrentNavigation(messages);
+    if (options.level) {
+        filtered = filterByLevel(filtered, options.level);
     }
-    const formatOptions = {
+    return filtered;
+}
+/**
+ * Build format options from command options.
+ *
+ * @param options - Command options
+ * @returns Format options for console formatters
+ */
+function buildFormatOptions(options) {
+    return {
         json: options.json,
         list: options.list,
         follow: options.follow,
         last: options.last,
         history: options.history,
+        level: options.level,
     };
+}
+/**
+ * Display console output based on options.
+ *
+ * @param messages - Console messages to display
+ * @param options - Command options
+ */
+function displayConsole(messages, options) {
+    const filteredMessages = applyMessageFilters(messages, options);
     if (options.follow) {
         console.clear();
     }
-    console.log(formatConsole(filteredMessages, formatOptions));
+    console.log(formatConsole(filteredMessages, buildFormatOptions(options)));
 }
 /**
  * Display console in follow mode with streaming updates.
  *
  * @param messages - Console messages to display
- * @param options - Command options (for --history flag)
+ * @param options - Command options (for --history and --level flags)
  */
 function displayConsoleStreaming(messages, options) {
-    let filteredMessages = messages;
-    // Default: show only current navigation. Use --history for all.
-    if (!options.history) {
-        filteredMessages = filterByCurrentNavigation(messages);
-    }
+    const filteredMessages = applyMessageFilters(messages, options);
     const lastMessages = filteredMessages.slice(-FOLLOW_MODE_MESSAGE_LIMIT);
     console.clear();
     console.log(formatConsoleFollow(lastMessages));
@@ -172,25 +208,21 @@ export function registerConsoleCommand(program) {
         .addOption(listOption)
         .addOption(followOption)
         .addOption(historyOption)
+        .addOption(levelOption)
         .addOption(consoleLastOption)
-        .addOption(jsonOption)
+        .addOption(jsonOption())
         .action(async (options) => {
         if (options.follow) {
-            console.error(followingConsoleMessage());
             const showConsole = async () => {
                 const messages = await fetchConsoleMessages(options);
                 if (messages) {
                     displayConsoleStreaming(messages, options);
                 }
             };
-            await showConsole();
-            const followInterval = setInterval(() => {
-                void showConsole();
-            }, 1000);
-            process.on('SIGINT', () => {
-                clearInterval(followInterval);
-                console.error(stoppedFollowingConsoleMessage());
-                process.exit(EXIT_CODES.SUCCESS);
+            await setupFollowMode(showConsole, {
+                startMessage: followingConsoleMessage,
+                stopMessage: stoppedFollowingConsoleMessage,
+                intervalMs: 1000,
             });
         }
         else {

package/dist/commands/console.js.map

@@ -1 +1 @@
-{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/commands/console.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAInC,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AAEtF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EACL,aAAa,EACb,mBAAmB,GAEpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD;;GAEG;AACH,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,cAAc,GAAG,KAAK,CAAC;AAC7B,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAErC;;GAEG;AACH,MAAM,iBAAiB,GAAG,IAAI,MAAM,CAClC,YAAY,EACZ,mDAAmD,kBAAkB,GAAG,CACzE;KACE,OAAO,CAAC,kBAAkB,CAAC;KAC3B,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE;IACjB,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC5B,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,cAAc,IAAI,CAAC,GAAG,cAAc,EAAE,CAAC;QACzD,MAAM,IAAI,YAAY,CACpB,qBAAqB,CAAC,cAAc,EAAE,cAAc,CAAC,EACrD,EAAE,EACF,UAAU,CAAC,iBAAiB,CAC7B,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC,CAAC,CAAC;AAEL;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,MAAM,CAAC,YAAY,EAAE,mCAAmC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEhG;;GAEG;AACH,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,cAAc,EAAE,sCAAsC,CAAC,CAAC,OAAO,CAC7F,KAAK,CACN,CAAC;AAEF;;;GAGG;AACH,MAAM,aAAa,GAAG,IAAI,MAAM,CAC9B,eAAe,EACf,2DAA2D,CAC5D,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEjB;;;;;GAKG;AACH,KAAK,UAAU,oBAAoB,CACjC,OAA8B;IAE9B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,EAAE,CAAC;QAEjC,IAAI,CAAC;YACH,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,eAAe,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,eAAe,CAAC,eAAe,CAAC,CAAC;YAClD,MAAM,QAAQ,GAAG,6BAA6B,CAAC,QAAQ,CAAC,CAAC;YACzD,MAAM,MAAM,GAAG,2BAA2B,CAAC,QAAQ,EAAE;gBACnD,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,eAAe,EAAE,IAAI;gBACrB,QAAQ;aACT,CAAC,CAAC;YACH,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;gBACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAgC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjB,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CAAC;oBACb,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,oBAAoB,EAAE;iBAC9B,CAAC,CACH,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,CAAC,CAAC;YACxC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;QAC9C,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,MAAM,GAAG,2BAA2B,CAAC,oBAAoB,EAAE;YAC/D,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,eAAe,EAAE,IAAI;SACtB,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAA0B;IAClE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,oDAAoD;IACpD,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAC9B,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,SAAS,CAAC,CAC7E,CAAC;IAEF,kDAAkD;IAClD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,eAAe,CAAC,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,QAA0B,EAAE,OAA8B;IAChF,IAAI,gBAAgB,GAAG,QAAQ,CAAC;IAEhC,gEAAgE;IAChE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,gBAAgB,GAAG,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,aAAa,GAAyB;QAC1C,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,SAAS,uBAAuB,CAAC,QAA0B,EAAE,OAA8B;IACzF,IAAI,gBAAgB,GAAG,QAAQ,CAAC;IAEhC,gEAAgE;IAChE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACrB,gBAAgB,GAAG,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,yBAAyB,CAAC,CAAC;IACxE,OAAO,CAAC,KAAK,EAAE,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,yCAAyC,CAAC;SACtD,SAAS,CAAC,UAAU,CAAC;SACrB,SAAS,CAAC,YAAY,CAAC;SACvB,SAAS,CAAC,aAAa,CAAC;SACxB,SAAS,CAAC,iBAAiB,CAAC;SAC5B,SAAS,CAAC,UAAU,CAAC;SACrB,MAAM,CAAC,KAAK,EAAE,OAA8B,EAAE,EAAE;QAC/C,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,CAAC,CAAC;YAEzC,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE;gBAC5C,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC;gBACrD,IAAI,QAAQ,EAAE,CAAC;oBACb,uBAAuB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAC7C,CAAC;YACH,CAAC,CAAC;YAEF,MAAM,WAAW,EAAE,CAAC;YACpB,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE;gBACtC,KAAK,WAAW,EAAE,CAAC;YACrB,CAAC,EAAE,IAAI,CAAC,CAAC;YAET,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;gBACxB,aAAa,CAAC,cAAc,CAAC,CAAC;gBAC9B,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,CAAC,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,QAAQ,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAC;YACrD,IAAI,QAAQ,EAAE,CAAC;gBACb,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/commands/console.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"details.d.ts","sourceRoot":"","sources":["../../src/commands/details.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BzC;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+C7D"}
+{"version":3,"file":"details.d.ts","sourceRoot":"","sources":["../../src/commands/details.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BzC;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuD7D"}

package/dist/commands/details.js

@@ -8,6 +8,7 @@ import { validateDetailsItem } from '../utils/typeGuards.js';
 /**
  * Format details for human-readable output.
  * Dispatches to the appropriate formatter based on type.
+ * TypeScript narrows the item type automatically via discriminated union.
  *
  * @param data - Details result containing item and type
  */
@@ -30,7 +31,7 @@ export function registerDetailsCommand(program) {
         .description('Get detailed information for a specific request or console message')
         .argument('<type>', 'Type of item: "network" or "console"')
         .argument('<id>', 'Request ID (for network) or index (for console)')
-        .addOption(jsonOption)
+        .addOption(jsonOption())
         .action(async (type, id, options) => {
         options.type = type;
         options.id = id;
@@ -51,14 +52,24 @@ export function registerDetailsCommand(program) {
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                 };
             }
-            const validatedItem = validateDetailsItem(response.data.item, opts.type);
-            return {
-                success: true,
-                data: {
-                    item: validatedItem,
-                    type: opts.type,
-                },
-            };
+            if (opts.type === 'network') {
+                return {
+                    success: true,
+                    data: {
+                        type: 'network',
+                        item: validateDetailsItem(response.data.item, 'network'),
+                    },
+                };
+            }
+            else {
+                return {
+                    success: true,
+                    data: {
+                        type: 'console',
+                        item: validateDetailsItem(response.data.item, 'console'),
+                    },
+                };
+            }
         }, options, formatDetails);
     });
 }

package/dist/commands/details.js.map

@@ -1 +1 @@
-{"version":3,"file":"details.js","sourceRoot":"","sources":["../../src/commands/details.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;GAKG;AACH,SAAS,aAAa,CAAC,IAAmB;IACxC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,oBAAoB,CAAC,IAAI,CAAC,IAAsB,CAAC,CAAC;IAC3D,CAAC;SAAM,CAAC;QACN,OAAO,oBAAoB,CAAC,IAAI,CAAC,IAAsB,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,oEAAoE,CAAC;SACjF,QAAQ,CAAC,QAAQ,EAAE,sCAAsC,CAAC;SAC1D,QAAQ,CAAC,MAAM,EAAE,iDAAiD,CAAC;SACnE,SAAS,CAAC,UAAU,CAAC;SACrB,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,EAAU,EAAE,OAA8B,EAAE,EAAE;QACzE,OAAO,CAAC,IAAI,GAAG,IAA6B,CAAC;QAC7C,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;QAEhB,MAAM,UAAU,CACd,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvD,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,iBAAiB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC;oBAC1E,QAAQ,EAAE,UAAU,CAAC,iBAAiB;iBACvC,CAAC;YACJ,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YAEtD,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAE9B,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;gBACzB,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,qBAAqB;oBAC5B,QAAQ,EAAE,UAAU,CAAC,kBAAkB;iBACxC,CAAC;YACJ,CAAC;YAED,MAAM,aAAa,GAAG,mBAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAEzE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,IAAI,EAAE;oBACJ,IAAI,EAAE,aAAa;oBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;iBAChB;aACF,CAAC;QACJ,CAAC,EACD,OAAO,EACP,aAAa,CACd,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"details.js","sourceRoot":"","sources":["../../src/commands/details.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,IAAmB;IACxC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;SAAM,CAAC;QACN,OAAO,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,oEAAoE,CAAC;SACjF,QAAQ,CAAC,QAAQ,EAAE,sCAAsC,CAAC;SAC1D,QAAQ,CAAC,MAAM,EAAE,iDAAiD,CAAC;SACnE,SAAS,CAAC,UAAU,EAAE,CAAC;SACvB,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,EAAU,EAAE,OAA8B,EAAE,EAAE;QACzE,OAAO,CAAC,IAAI,GAAG,IAA6B,CAAC;QAC7C,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;QAEhB,MAAM,UAAU,CACd,KAAK,EAAE,IAAI,EAAE,EAAE;YACb,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvD,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,iBAAiB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC;oBAC1E,QAAQ,EAAE,UAAU,CAAC,iBAAiB;iBACvC,CAAC;YACJ,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YAEtD,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAE9B,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;gBACzB,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,qBAAqB;oBAC5B,QAAQ,EAAE,UAAU,CAAC,kBAAkB;iBACxC,CAAC;YACJ,CAAC;YAED,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC5B,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,IAAI,EAAE;wBACJ,IAAI,EAAE,SAAkB;wBACxB,IAAI,EAAE,mBAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;qBACzD;iBACF,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,IAAI,EAAE;wBACJ,IAAI,EAAE,SAAkB;wBACxB,IAAI,EAAE,mBAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;qBACzD;iBACF,CAAC;YACJ,CAAC;QACH,CAAC,EACD,OAAO,EACP,aAAa,CACd,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

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

@@ -5,7 +5,9 @@
  * - Numeric indices (referencing cached query results)
  * - CSS selectors (used directly)
  *
- * Handles cache validation, staleness detection, and consistent error handling.
+ * Handles cache validation, staleness detection, and automatic refresh.
+ * When cache is stale due to navigation, automatically re-runs the original
+ * query to provide seamless "just works" experience.
  *
  * @example
  * ```typescript
@@ -56,7 +58,8 @@ export type ElementTargetResult = ElementTargetSuccess | ElementTargetFailure;
 /**
  * Singleton resolver for DOM element access patterns.
  *
- * Centralizes element resolution with cache validation and consistent error handling.
+ * Centralizes element resolution with cache validation, automatic refresh,
+ * and consistent error handling.
  */
 export declare class DomElementResolver {
     private static instance;
@@ -67,6 +70,16 @@ export declare class DomElementResolver {
      * @param cacheManager - Query cache manager (defaults to singleton)
      */
     constructor(cacheManager?: QueryCacheManager);
+    /**
+     * Refresh stale cache by re-running the original query.
+     *
+     * Called automatically when cache validation fails due to navigation.
+     * Re-queries using the stored selector and updates the cache with fresh results.
+     *
+     * @param selector - Original CSS selector from stale cache
+     * @returns Fresh query result
+     */
+    private refreshCache;
     /**
      * Get the singleton instance.
      *
@@ -84,7 +97,9 @@ export declare class DomElementResolver {
      * - A CSS selector string (used directly)
      * - A numeric index (resolved from cached query results)
      *
-     * Validates cache staleness by checking navigationId against current page state.
+     * Automatically refreshes stale cache by re-running the original query.
+     * This provides a "just works" experience where navigation doesn't break
+     * index-based access.
      *
      * @param selectorOrIndex - CSS selector or numeric index from query results
      * @param explicitIndex - Optional explicit --index flag value (1-based)
@@ -103,11 +118,12 @@ export declare class DomElementResolver {
     /**
      * Get nodeId for a cached index.
      *
-     * Validates cache staleness and throws CommandError if invalid.
+     * Automatically refreshes stale cache by re-running the original query.
+     * Throws CommandError only if refresh fails or index is out of range after refresh.
      *
      * @param index - Zero-based index from query results
      * @returns Node with nodeId from cache
-     * @throws CommandError if cache missing, stale, index out of range, or node not found
+     * @throws CommandError if cache missing, index out of range after refresh, or node not found
      *
      * @example
      * ```typescript
@@ -121,10 +137,10 @@ export declare class DomElementResolver {
     /**
      * Get the count of cached elements.
      *
-     * Validates cache and returns element count, or throws if cache is invalid.
+     * Automatically refreshes stale cache by re-running the original query.
      *
      * @returns Number of cached elements
-     * @throws CommandError if cache is missing or stale
+     * @throws CommandError if cache is missing or refresh fails
      */
     getElementCount(): Promise<number>;
     /**

package/dist/commands/dom/DomElementResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DomElementResolver.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/DomElementResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAInE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wBAAwB;IACxB,OAAO,EAAE,KAAK,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAE9E;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAC1D,OAAO,CAAC,YAAY,CAAoB;IAExC;;;;OAIG;gBACS,YAAY,CAAC,EAAE,iBAAiB;IAI5C;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,kBAAkB;IAKxC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,OAAO,CAAC,eAAe,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwC5F;;;;;;;;;;;;;;OAcG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAmCnE;;;;;;;OAOG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAcxC;;;;;OAKG;IACH,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO;CAGjD"}
+{"version":3,"file":"DomElementResolver.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/DomElementResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAOnE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,OAAO,EAAE,IAAI,CAAC;IACd,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wBAAwB;IACxB,OAAO,EAAE,KAAK,CAAC;IACf,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAE9E;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmC;IAC1D,OAAO,CAAC,YAAY,CAAoB;IAExC;;;;OAIG;gBACS,YAAY,CAAC,EAAE,iBAAiB;IAI5C;;;;;;;;OAQG;YACW,YAAY;IAkB1B;;;;OAIG;IACH,MAAM,CAAC,WAAW,IAAI,kBAAkB;IAKxC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,OAAO,CAAC,eAAe,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAiD5F;;;;;;;;;;;;;;;OAeG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA4CnE;;;;;;;OAOG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAoBxC;;;;;OAKG;IACH,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO;CAGjD"}

package/dist/commands/dom/DomElementResolver.js

@@ -5,7 +5,9 @@
  * - Numeric indices (referencing cached query results)
  * - CSS selectors (used directly)
  *
- * Handles cache validation, staleness detection, and consistent error handling.
+ * Handles cache validation, staleness detection, and automatic refresh.
+ * When cache is stale due to navigation, automatically re-runs the original
+ * query to provide seamless "just works" experience.
  *
  * @example
  * ```typescript
@@ -25,11 +27,14 @@
  */
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { CommandError } from '../../ui/errors/index.js';
+import { createLogger } from '../../ui/logging/index.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+const log = createLogger('dom');
 /**
  * Singleton resolver for DOM element access patterns.
  *
- * Centralizes element resolution with cache validation and consistent error handling.
+ * Centralizes element resolution with cache validation, automatic refresh,
+ * and consistent error handling.
  */
 export class DomElementResolver {
     static instance = null;
@@ -42,6 +47,28 @@ export class DomElementResolver {
     constructor(cacheManager) {
         this.cacheManager = cacheManager ?? QueryCacheManager.getInstance();
     }
+    /**
+     * Refresh stale cache by re-running the original query.
+     *
+     * Called automatically when cache validation fails due to navigation.
+     * Re-queries using the stored selector and updates the cache with fresh results.
+     *
+     * @param selector - Original CSS selector from stale cache
+     * @returns Fresh query result
+     */
+    async refreshCache(selector) {
+        log.debug(`Cache stale, auto-refreshing query "${selector}"`);
+        const { queryDOMElements } = await import('../../commands/dom/helpers.js');
+        const result = await queryDOMElements(selector);
+        const navigationId = await this.cacheManager.getCurrentNavigationId();
+        const resultWithNavId = {
+            ...result,
+            ...(navigationId !== null && { navigationId }),
+        };
+        await this.cacheManager.set(resultWithNavId);
+        this.cacheManager.invalidateNavigationCache();
+        log.debug(`Cache refreshed: found ${result.count} elements`);
+    }
     /**
      * Get the singleton instance.
      *
@@ -64,7 +91,9 @@ export class DomElementResolver {
      * - A CSS selector string (used directly)
      * - A numeric index (resolved from cached query results)
      *
-     * Validates cache staleness by checking navigationId against current page state.
+     * Automatically refreshes stale cache by re-running the original query.
+     * This provides a "just works" experience where navigation doesn't break
+     * index-based access.
      *
      * @param selectorOrIndex - CSS selector or numeric index from query results
      * @param explicitIndex - Optional explicit --index flag value (1-based)
@@ -82,7 +111,12 @@ export class DomElementResolver {
     async resolve(selectorOrIndex, explicitIndex) {
         const isNumericIndex = /^\d+$/.test(selectorOrIndex);
         if (isNumericIndex) {
-            const validation = await this.cacheManager.validate();
+            let validation = await this.cacheManager.validate();
+            // Auto-refresh: if cache is stale but has selector, re-run query
+            if (!validation.valid && validation.cache?.selector) {
+                await this.refreshCache(validation.cache.selector);
+                validation = await this.cacheManager.validate();
+            }
             if (!validation.valid || !validation.cache) {
                 return {
                     success: false,
@@ -96,9 +130,11 @@ export class DomElementResolver {
             if (index < 0 || index >= cachedQuery.nodes.length) {
                 return {
                     success: false,
-                    error: `Index ${index} out of range (found ${cachedQuery.nodes.length} elements)`,
-                    exitCode: EXIT_CODES.INVALID_ARGUMENTS,
-                    suggestion: `Use an index between 0 and ${cachedQuery.nodes.length - 1}`,
+                    error: `Index ${index} out of range (found ${cachedQuery.nodes.length} nodes from query "${cachedQuery.selector}")`,
+                    exitCode: EXIT_CODES.STALE_CACHE,
+                    suggestion: cachedQuery.nodes.length === 0
+                        ? `No elements found after refresh. The selector "${cachedQuery.selector}" may no longer match any elements.`
+                        : `Use an index between 0 and ${cachedQuery.nodes.length - 1}`,
                 };
             }
             return {
@@ -116,11 +152,12 @@ export class DomElementResolver {
     /**
      * Get nodeId for a cached index.
      *
-     * Validates cache staleness and throws CommandError if invalid.
+     * Automatically refreshes stale cache by re-running the original query.
+     * Throws CommandError only if refresh fails or index is out of range after refresh.
      *
      * @param index - Zero-based index from query results
      * @returns Node with nodeId from cache
-     * @throws CommandError if cache missing, stale, index out of range, or node not found
+     * @throws CommandError if cache missing, index out of range after refresh, or node not found
      *
      * @example
      * ```typescript
@@ -129,15 +166,21 @@ export class DomElementResolver {
      * ```
      */
     async getNodeIdForIndex(index) {
-        const validation = await this.cacheManager.validate();
+        let validation = await this.cacheManager.validate();
+        // Auto-refresh: if cache is stale but has selector, re-run query
+        if (!validation.valid && validation.cache?.selector) {
+            await this.refreshCache(validation.cache.selector);
+            validation = await this.cacheManager.validate();
+        }
         if (!validation.valid || !validation.cache) {
             throw new CommandError(validation.error ?? 'No cached query results found', validation.suggestion ? { suggestion: validation.suggestion } : {}, EXIT_CODES.INVALID_ARGUMENTS);
         }
         const cachedQuery = validation.cache;
         if (index < 0 || index >= cachedQuery.nodes.length) {
-            throw new CommandError(`Index ${index} out of range (found ${cachedQuery.nodes.length} elements)`, {
-                suggestion: `Use an index between 0 and ${cachedQuery.nodes.length - 1}`,
-            }, EXIT_CODES.INVALID_ARGUMENTS);
+            const suggestion = cachedQuery.nodes.length === 0
+                ? `No elements found after refresh. The selector "${cachedQuery.selector}" may no longer match any elements.`
+                : `Use an index between 0 and ${cachedQuery.nodes.length - 1}`;
+            throw new CommandError(`Index ${index} out of range (found ${cachedQuery.nodes.length} nodes from query "${cachedQuery.selector}")`, { suggestion }, EXIT_CODES.STALE_CACHE);
         }
         const targetNode = cachedQuery.nodes[index];
         if (!targetNode) {
@@ -148,13 +191,18 @@ export class DomElementResolver {
     /**
      * Get the count of cached elements.
      *
-     * Validates cache and returns element count, or throws if cache is invalid.
+     * Automatically refreshes stale cache by re-running the original query.
      *
      * @returns Number of cached elements
-     * @throws CommandError if cache is missing or stale
+     * @throws CommandError if cache is missing or refresh fails
      */
     async getElementCount() {
-        const validation = await this.cacheManager.validate();
+        let validation = await this.cacheManager.validate();
+        // Auto-refresh: if cache is stale but has selector, re-run query
+        if (!validation.valid && validation.cache?.selector) {
+            await this.refreshCache(validation.cache.selector);
+            validation = await this.cacheManager.validate();
+        }
         if (!validation.valid || !validation.cache) {
             throw new CommandError(validation.error ?? 'No cached query results found', validation.suggestion ? { suggestion: validation.suggestion } : {}, EXIT_CODES.INVALID_ARGUMENTS);
         }

package/dist/commands/dom/DomElementResolver.js.map

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

package/dist/commands/dom/a11y.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/a11y.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8KzC;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA0D1D"}
+{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../../../src/commands/dom/a11y.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0LzC;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA2D1D"}

package/dist/commands/dom/a11y.js

@@ -10,7 +10,7 @@
  */
 import { DomElementResolver } from '../../commands/dom/DomElementResolver.js';
 import { getDomContext } from '../../commands/dom/helpers.js';
-import { runCommand } from '../../commands/shared/CommandRunner.js';
+import { runCommand, runJsonCommand } from '../../commands/shared/CommandRunner.js';
 import { jsonOption } from '../../commands/shared/commonOptions.js';
 import { collectA11yTree, queryA11yTree, parseQueryPattern, resolveA11yNode, } from '../../telemetry/a11y.js';
 import { CommandError } from '../../ui/errors/index.js';
@@ -26,16 +26,17 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
  * @param options - Command options
  */
 async function handleA11yTree(options) {
-    const tree = await collectA11yTree();
     if (options.json) {
-        const serialized = {
-            root: tree.root,
-            nodes: Object.fromEntries(tree.nodes),
-            count: tree.count,
-        };
-        console.log(JSON.stringify(serialized, null, 2));
-        process.exit(EXIT_CODES.SUCCESS);
+        await runJsonCommand(async () => {
+            const tree = await collectA11yTree();
+            return {
+                root: tree.root,
+                nodes: Object.fromEntries(tree.nodes),
+                count: tree.count,
+            };
+        });
     }
+    const tree = await collectA11yTree();
     await runCommand(() => Promise.resolve({ success: true, data: tree }), options, formatA11yTree);
 }
 /**
@@ -66,7 +67,7 @@ async function handleA11yQuery(pattern, options) {
         const tree = await collectA11yTree();
         const result = queryA11yTree(tree, queryPattern);
         if (result.count === 0) {
-            throw new CommandError('No elements found matching pattern', {
+            throw new CommandError('No nodes found matching pattern', {
                 suggestion: 'Try a broader query or use "bdg dom a11y tree" to see all elements',
                 note: `Pattern: ${JSON.stringify(queryPattern)}`,
             }, EXIT_CODES.RESOURCE_NOT_FOUND);
@@ -96,7 +97,10 @@ async function handleA11yQuery(pattern, options) {
 async function handleA11yDescribe(selectorOrIndex, options) {
     const resolver = DomElementResolver.getInstance();
     const isNumericIndex = resolver.isNumericIndex(selectorOrIndex);
-    await runCommand(async () => {
+    /**
+     * Fetch a11y node data for a given selector or index.
+     */
+    async function fetchA11yNodeData() {
         let node;
         let nodeId;
         if (isNumericIndex) {
@@ -116,7 +120,14 @@ async function handleA11yDescribe(selectorOrIndex, options) {
         if (domNodeId) {
             domContext = await getDomContext(domNodeId);
         }
-        return { success: true, data: { node, domContext } };
+        return { node, domContext };
+    }
+    if (options.json) {
+        await runJsonCommand(fetchA11yNodeData);
+    }
+    await runCommand(async () => {
+        const data = await fetchA11yNodeData();
+        return { success: true, data };
     }, options, formatA11yNodeWithContext);
 }
 /**
@@ -128,16 +139,17 @@ export function registerA11yCommands(domCmd) {
     const a11y = domCmd
         .command('a11y')
         .description('Accessibility tree inspection and semantic queries')
-        .argument('[search]', 'Quick search: index (describe), pattern with ":" (query), or name search')
-        .addOption(jsonOption)
+        .argument('[search]', 'Quick search: index (describe), CSS selector (#id, .class), pattern with ":" (query), or name search')
+        .enablePositionalOptions()
         .action(async (search, options) => {
         if (!search) {
             a11y.help();
             return;
         }
         const isNumericIndex = /^\d+$/.test(search);
+        const isCssSelector = /^[#.[]/u.test(search) || search.includes(' ');
         const isPatternQuery = search.includes(':') || search.includes('=');
-        if (isNumericIndex) {
+        if (isNumericIndex || isCssSelector) {
             await handleA11yDescribe(search, options);
         }
         else if (isPatternQuery) {
@@ -150,7 +162,7 @@ export function registerA11yCommands(domCmd) {
     a11y
         .command('tree')
         .description('Dump full accessibility tree (filters ignored nodes)')
-        .addOption(jsonOption)
+        .addOption(jsonOption())
         .action(async (options) => {
         await handleA11yTree(options);
     });
@@ -158,7 +170,7 @@ export function registerA11yCommands(domCmd) {
         .command('query')
         .description('Query elements by accessibility properties (e.g., "role:button", "name:Submit")')
         .argument('<pattern>', 'Pattern with field prefix - role:button, name:Submit, name:*search* (supports wildcards)')
-        .addOption(jsonOption)
+        .addOption(jsonOption())
         .action(async (pattern, options) => {
         await handleA11yQuery(pattern, options);
     });
@@ -166,7 +178,7 @@ export function registerA11yCommands(domCmd) {
         .command('describe')
         .description('Get accessibility properties for CSS selector or index')
         .argument('<selectorOrIndex>', 'CSS selector (e.g., "button.submit") or numeric index from query results')
-        .addOption(jsonOption)
+        .addOption(jsonOption())
         .action(async (selectorOrIndex, options) => {
         await handleA11yDescribe(selectorOrIndex, options);
     });