browser-debugger-cli 0.8.0 → 0.9.0

package/dist/commands/dom/listeners.js

@@ -4,7 +4,11 @@
  *
  * The daemon collects them with `DOMDebugger.getEventListeners`; listeners on
  * ancestors matter because frameworks (React, jQuery) attach their handlers
- * to a root container or the document and dispatch from there.
+ * to a root container or the document and dispatch from there. jQuery's
+ * dispatcher is replaced by the jQuery handlers it runs for the element,
+ * React's `on…` props of the element and its ancestors are listed, and
+ * framework roots (React's root container) are summarised per node unless
+ * `--all` is given.
  */
 import { DomElementResolver } from './DomElementResolver.js';
 import { runElementCommand } from './helpers/runElementCommand.js';
@@ -24,7 +28,8 @@ export function registerListenersCommand(dom) {
         .description('List event listeners that run for an element (incl. delegated ones on ancestors)')
         .argument('<selectorOrIndex>', 'CSS selector or numeric index from query results (0-based)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
-        .option('--type <types>', 'Only these event types (comma-separated, e.g. click,keydown)', eventTypesOption)
+        .option('--type <types>', 'Only these event types (comma-separated, e.g. click,keydown; repeatable)', eventTypesOption)
+        .option('--all', 'List every listener of framework roots (React) instead of one line per node')
         .addOption(jsonOption())
         .action(async (selectorOrIndex, options) => {
         await runCommand(() => listElementListeners(selectorOrIndex, options), options, (data) => formatListeners(data, options.type));
@@ -41,8 +46,13 @@ async function listElementListeners(selectorOrIndex, options) {
     const result = await runElementCommand({
         selectorOrIndex,
         index: options.index,
-        buildRequest: (target) => ({ ...target, ...(options.type && { types: options.type }) }),
+        buildRequest: (target) => ({
+            ...target,
+            ...(options.type && { types: options.type }),
+            ...(options.all && { all: true }),
+        }),
         call: domListeners,
+        command: 'listeners',
         action: 'list event listeners',
         failureSuggestion: 'Verify the selector matches an element: bdg dom query "<selector>"',
     });

package/dist/commands/dom/query.js

@@ -1,9 +1,8 @@
 /**
  * `bdg dom query` — find elements by CSS selector and populate the query cache.
  */
-import { queryDOMElements } from './helpers/index.js';
+import { noMatchesError, queryDOMElements } from './helpers/index.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { noNodesFoundError } from '../../errors/messages.js';
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { formatDomQuery } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
@@ -21,7 +20,7 @@ export async function handleDomQuery(selector, options) {
         const cache = QueryCacheManager.getInstance();
         if (result.count === 0) {
             await cache.clear();
-            const err = noNodesFoundError(selector);
+            const err = await noMatchesError(selector);
             return {
                 success: false,
                 error: err.message,

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

@@ -13,9 +13,19 @@ import type { DomScreenshotCommandOptions } from '../shared/optionTypes.js';
  */
 export declare function resolveImageFormat(outputPath: string, requested?: 'png' | 'jpeg'): 'png' | 'jpeg';
 /**
- * Handle `bdg dom screenshot <path>`.
+ * Fold the optional positional target (`bdg dom screenshot out.png "#sel"`,
+ * or an index from a query) into `--selector` / `--index`.
+ *
+ * @param target - Positional selector or index, if given
+ * @param options - Command options
+ * @returns Options with the target as `selector` or `index`
+ * @throws CommandError (81) when the option names a different element
+ */
+export declare function withPositionalTarget(target: string | undefined, options: DomScreenshotCommandOptions): DomScreenshotCommandOptions;
+/**
+ * Handle `bdg dom screenshot <path> [selector|index]`.
  *
  * Dispatches to page, element, or sequence capture based on flags.
  */
-export declare function handleDomScreenshot(outputPath: string, options: DomScreenshotCommandOptions): Promise<void>;
+export declare function handleDomScreenshot(outputPath: string, target: string | undefined, commandOptions: DomScreenshotCommandOptions): Promise<void>;
 //# sourceMappingURL=screenshot.d.ts.map

package/dist/commands/dom/screenshot.js

@@ -8,7 +8,7 @@ import { runCommand } from '../shared/CommandRunner.js';
 import { assertFilePath, outputPathError } from '../shared/outputFile.js';
 import { positiveIntRule } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
-import { conflictingOptionsMessage, genericError } from '../../errors/messages.js';
+import { conflictingOptionsMessage, conflictingTargetError, genericError, } from '../../errors/messages.js';
 import { missingArgumentError } from '../../errors/messages.js';
 import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
 import { formatDomScreenshot } from '../../ui/formatters/dom.js';
@@ -90,6 +90,7 @@ function addElementInfo(result, options) {
             ...(options.selector !== undefined && { selector: options.selector }),
             ...(options.index !== undefined && { index: options.index }),
             bounds,
+            ...(result.element?.captured && { captured: result.element.captured }),
         },
     };
 }
@@ -227,11 +228,34 @@ function assertScreenshotOptions(outputPath, options) {
         throw new CommandError(message, {}, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
- * Handle `bdg dom screenshot <path>`.
+ * Fold the optional positional target (`bdg dom screenshot out.png "#sel"`,
+ * or an index from a query) into `--selector` / `--index`.
+ *
+ * @param target - Positional selector or index, if given
+ * @param options - Command options
+ * @returns Options with the target as `selector` or `index`
+ * @throws CommandError (81) when the option names a different element
+ */
+export function withPositionalTarget(target, options) {
+    if (target === undefined)
+        return options;
+    const isIndex = /^\d+$/.test(target);
+    const key = isIndex ? 'index' : 'selector';
+    const value = isIndex ? Number(target) : target;
+    const given = options[key];
+    if (given !== undefined && given !== value) {
+        const err = conflictingTargetError(`--${key} ${String(given)}`, target);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return { ...options, [key]: value };
+}
+/**
+ * Handle `bdg dom screenshot <path> [selector|index]`.
  *
  * Dispatches to page, element, or sequence capture based on flags.
  */
-export async function handleDomScreenshot(outputPath, options) {
+export async function handleDomScreenshot(outputPath, target, commandOptions) {
+    const options = withPositionalTarget(target, commandOptions);
     assertScreenshotOptions(outputPath, options);
     if (options.follow) {
         await handleSequenceCapture(outputPath, options);

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

@@ -5,7 +5,7 @@
  * their surrounding DOM context and to fall back gracefully when only one
  * of the two data sources is available.
  */
-import { type DomContext } from './helpers/index.js';
+import type { DomContext } from './helpers/index.js';
 import type { A11yNode } from '../../types.js';
 /**
  * Accessibility node paired with its surrounding DOM context for display.
@@ -17,8 +17,12 @@ export interface SemanticNodeWithContext {
 /**
  * Format a semantic node together with DOM context for human-readable output.
  *
+ * The role line is followed by up to 500 characters of the element's text
+ * (all of it with `dom get --full`) when it is longer than the one-line
+ * preview, or, for an element without text or name, what it holds.
+ *
  * @param data - Accessibility node and optional DOM context
- * @returns One-line formatted string
+ * @returns Role line, plus a text line for elements with longer text
  */
 export declare function formatSemanticNodeWithContext(data: SemanticNodeWithContext): string;
 /**
@@ -30,15 +34,4 @@ export declare function formatSemanticNodeWithContext(data: SemanticNodeWithCont
  * @param nodeId - CDP nodeId for synthesis
  */
 export declare function resolveNodeWithFallback(a11yNode: A11yNode | null, domContext: DomContext | null, nodeId: number | undefined): A11yNode | null;
-/**
- * Look up a single element by selector to produce its nodeId and DOM context.
- *
- * Used by `dom get` (semantic mode) when the accessibility tree has no node
- * for the selector — the selector-based DOM context allows us to synthesize
- * one.
- */
-export declare function queryDomContextBySelector(selector: string): Promise<{
-    nodeId: number | undefined;
-    domContext: DomContext | null;
-}>;
 //# sourceMappingURL=semanticUtils.d.ts.map

package/dist/commands/dom/semanticUtils.js

@@ -5,8 +5,9 @@
  * their surrounding DOM context and to fall back gracefully when only one
  * of the two data sources is available.
  */
-import { getDomContext, resolveBackendNodeIds, } from './helpers/index.js';
 import { synthesizeA11yNode } from '../../telemetry/roleInference.js';
+import { joinLines } from '../../ui/formatting.js';
+import { elementTextLine, emptyElementLine } from '../../ui/messages/commands.js';
 function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
@@ -29,7 +30,7 @@ function buildContextText(node, domContext) {
         const classPart = domContext.classes && domContext.classes.length > 0
             ? `.${domContext.classes.slice(0, 3).join('.')}`
             : '';
-        const previewPart = domContext.preview ? ` "${domContext.preview}"` : '';
+        const previewPart = domContext.preview && !domContext.text ? ` "${domContext.preview}"` : '';
         return ` ${tagPart}${classPart}>${previewPart}`;
     }
     return '';
@@ -58,8 +59,12 @@ function buildPropertiesText(node) {
 /**
  * Format a semantic node together with DOM context for human-readable output.
  *
+ * The role line is followed by up to 500 characters of the element's text
+ * (all of it with `dom get --full`) when it is longer than the one-line
+ * preview, or, for an element without text or name, what it holds.
+ *
  * @param data - Accessibility node and optional DOM context
- * @returns One-line formatted string
+ * @returns Role line, plus a text line for elements with longer text
  */
 export function formatSemanticNodeWithContext(data) {
     const { node, domContext } = data;
@@ -67,7 +72,13 @@ export function formatSemanticNodeWithContext(data) {
     const contextText = buildContextText(node, domContext);
     const propsText = buildPropertiesText(node);
     const inferredText = node.inferred ? ' (inferred from DOM)' : '';
-    return `${roleText}${contextText}${propsText}${inferredText}`;
+    const line = `${roleText}${contextText}${propsText}${inferredText}`;
+    if (domContext?.text)
+        return joinLines(line, elementTextLine(domContext.text));
+    if (domContext?.childCount !== undefined && !node.name) {
+        return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount));
+    }
+    return line;
 }
 /**
  * Resolve an a11y node, falling back to a DOM-synthesized one when only
@@ -84,19 +95,4 @@ export function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
         return synthesizeA11yNode(domContext, nodeId);
     return null;
 }
-/**
- * Look up a single element by selector to produce its nodeId and DOM context.
- *
- * Used by `dom get` (semantic mode) when the accessibility tree has no node
- * for the selector — the selector-based DOM context allows us to synthesize
- * one.
- */
-export async function queryDomContextBySelector(selector) {
-    const [backendNodeId] = await resolveBackendNodeIds([selector]);
-    if (backendNodeId === undefined) {
-        return { nodeId: undefined, domContext: null };
-    }
-    const domContext = await getDomContext({ backendNodeId });
-    return { nodeId: backendNodeId, domContext };
-}
 //# sourceMappingURL=semanticUtils.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * `bdg dom wait [selector]` - wait until elements appear, become visible,
+ * contain a text or are gone, and/or the page has loaded, instead of
+ * polling with `sleep` and `dom eval`.
+ */
+import type { Command } from 'commander';
+/**
+ * Register `bdg dom wait`.
+ *
+ * @param dom - The `dom` command group
+ */
+export declare function registerWaitCommand(dom: Command): void;
+//# sourceMappingURL=wait.d.ts.map

package/dist/commands/dom/wait.js

@@ -0,0 +1,83 @@
+/**
+ * `bdg dom wait [selector]` - wait until elements appear, become visible,
+ * contain a text or are gone, and/or the page has loaded, instead of
+ * polling with `sleep` and `dom eval`.
+ */
+import { runCommand } from '../shared/CommandRunner.js';
+import { jsonOption } from '../shared/commonOptions.js';
+import { integerOption } from '../shared/validation.js';
+import { waitTargetRequiredError } from '../../errors/messages.js';
+import { domWait } from '../../ipc/client.js';
+import { WAIT_HELP_EXAMPLES, waitMetMessage } from '../../ui/messages/commands.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { filterDefined } from '../../utils/objects.js';
+/** Default --timeout */
+const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+/** Longest --timeout (10 minutes) */
+const MAX_WAIT_TIMEOUT_MS = 600_000;
+/**
+ * Register `bdg dom wait`.
+ *
+ * @param dom - The `dom` command group
+ */
+export function registerWaitCommand(dom) {
+    dom
+        .command('wait')
+        .description('Wait until elements appear, become visible, contain a text or are gone (or the page loads)')
+        .argument('[selector]', 'CSS selector (:has-text, :visible allowed; shadow DOM and same-origin iframes searched); optional with --load')
+        .option('--text <text>', 'A match must contain this text (case-insensitive)')
+        .option('--visible', 'Only count visible matches')
+        .option('--gone', 'Wait until no element matches (none visible, with --visible)')
+        .option('--load', 'Also wait for the page to finish loading (document.readyState complete)')
+        .option('--timeout <ms>', 'Give up after this many milliseconds (exit 102)', integerOption(1, MAX_WAIT_TIMEOUT_MS), DEFAULT_WAIT_TIMEOUT_MS)
+        .addOption(jsonOption())
+        .addHelpText('after', WAIT_HELP_EXAMPLES)
+        .action(async (selector, options) => {
+        await runCommand(() => waitFor(selector, options), options, formatWait);
+    });
+}
+/**
+ * Validate the options and ask the daemon to wait.
+ *
+ * @param selector - Selector, if given
+ * @param options - Command options
+ * @returns Command result
+ */
+async function waitFor(selector, options) {
+    const needsSelector = options.text !== undefined || options.gone === true || !options.load;
+    if (selector === undefined && needsSelector) {
+        const err = waitTargetRequiredError();
+        return {
+            success: false,
+            error: err.message,
+            exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+            errorContext: { suggestion: err.suggestion },
+        };
+    }
+    const response = await domWait({
+        ...filterDefined({ selector, text: options.text }),
+        ...(options.gone && { gone: true }),
+        ...(options.visible && { visible: true }),
+        ...(options.load && { load: true }),
+        timeout: options.timeout,
+    });
+    if (response.status === 'error' || !response.data) {
+        return {
+            success: false,
+            error: response.error ?? 'Failed to wait',
+            exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+            ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+        };
+    }
+    return { success: true, data: response.data };
+}
+/**
+ * One line for human output.
+ *
+ * @param data - What the page showed when the condition was met
+ * @returns e.g. `✓ #finish visible after 5.1s`
+ */
+function formatWait(data) {
+    return waitMetMessage(data, data.elapsedMs);
+}
+//# sourceMappingURL=wait.js.map

package/dist/commands/helpJson.js

@@ -97,8 +97,8 @@ function convertCommand(command) {
 function generateRuntimeState() {
     const sessionActive = readLiveDaemonPid() !== null;
     const availableCommands = sessionActive
-        ? ['peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'stop']
-        : ['bdg <url>', 'cleanup', '--help', '--version'];
+        ? ['peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'sessions', 'stop']
+        : ['bdg <url>', 'sessions', 'cleanup', '--help', '--version'];
     return {
         sessionActive,
         daemonRunning: sessionActive,

package/dist/commands/network/list.js

@@ -4,9 +4,9 @@
 import { Option } from 'commander';
 import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
-import { handleDaemonConnectionError, noteFollowConnected, } from '../shared/daemonErrorHandler.js';
+import { noteFollowConnected } from '../shared/daemonErrorHandler.js';
 import { fetchNetworkRequests, createErrorResult } from '../shared/dataFetcher.js';
-import { setupFollowMode } from '../shared/followMode.js';
+import { followFetchFailure, setupFollowMode, } from '../shared/followMode.js';
 import { handleValidationError } from '../shared/handleValidationError.js';
 import { positiveIntRule, resourceTypeRule } from '../shared/validation.js';
 import { applyFilters, getFilterHelpText, validateFilterString } from '../../telemetry/filterDsl.js';
@@ -127,15 +127,7 @@ async function runFollowMode(options, resourceTypes, lastN) {
     const showNetwork = async () => {
         const result = await fetchNetworkRequests(filtersNeedHeaders(options));
         if (!result.success) {
-            const errorResult = handleDaemonConnectionError(result.error, {
-                json: options.json,
-                follow: true,
-                retryIntervalMs: FOLLOW_INTERVAL,
-                exitCode: result.exitCode,
-            });
-            if (errorResult.shouldExit)
-                process.exit(errorResult.exitCode);
-            return;
+            return followFetchFailure(result, { json: options.json, retryIntervalMs: FOLLOW_INTERVAL });
         }
         noteFollowConnected();
         const finished = filterRequests(result.data, options, resourceTypes).filter((request) => request.duration !== undefined && !shown.has(request.requestId));
@@ -164,6 +156,7 @@ async function runFollowMode(options, resourceTypes, lastN) {
                 console.log(text);
         }
         started = true;
+        return undefined;
     };
     await setupFollowMode(showNetwork, {
         startMessage: followingNetworkMessage,

package/dist/commands/optionBehaviors.js

@@ -7,12 +7,23 @@
  * @see docs/principles/SELF_DOCUMENTING_SYSTEMS.md
  */
 import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from './dom/screenshotResize.js';
+/** What DOM actions report about the network requests they triggered */
+const TRIGGERED_REQUESTS_BEHAVIOR = 'Requests (and WebSocket connections) that start after the action begins are returned as triggeredRequests (method, url, status, durationMs; pending when still running at return, loading when the response arrived but its body is still streaming; with resourceType; human output lists documents, XHR/fetch and WebSockets first (up to 10) and counts static assets on one line; absent when network telemetry is off). Attribution is by time: requests a page timer or poller starts meanwhile are listed too, whether or not the action caused them';
+/** What every DOM action reports about the page besides its requests */
+const ACTION_EFFECTS_BEHAVIOR = 'The result also says what changed on the page: a navigation (Page: navigated to <url> (status), or URL changed to <url> (same document); JSON navigation { url, sameDocument, status }), and messages that appeared or changed in alert/status/aria-live elements or flash/error/toast-like classes (New text: "…" (element); JSON messages [{ text, element }], at most 3; after a navigation every message on the new page counts; texts of only digits and time units, such as clocks and counters, are left out, but other text that changes on its own, such as a rotating banner, can show up). Both are absent when nothing changed. Cost: one page script sent before the action without waiting for it and one read after it, a few ms; when the page does not answer (a pending navigation) bdg waits at most 200 ms for the snapshot and 250 ms per read, and the navigation is still reported from CDP events';
+/** What `--no-wait` does to a DOM action's triggered requests */
+const NO_WAIT_TRIGGERED_REQUESTS = 'Returns immediately without waiting for network; triggeredRequests lists only requests bdg saw start before returning (often none yet; check bdg network list later)';
 /**
  * Behavioral metadata registry.
  *
  * Keyed by "command:flag" to support same flag names across different commands.
  */
 const OPTION_BEHAVIORS = {
+    'screenshot:--selector': {
+        default: 'Captures the page (full page unless --no-full-page)',
+        whenEnabled: 'Captures one element; the selector (or a query index) can also be given as the second argument: bdg dom screenshot out.png "#sel". Both given and naming different elements exits 81',
+        automaticBehavior: 'The capture covers the border box plus content overflowing it (uncleared floats, positioned children; not what an overflow: hidden ancestor cuts off, nor fixed descendants); JSON element.bounds is the border box and element.captured the larger area when it grew, which human output notes',
+    },
     'screenshot:--no-resize': {
         default: `Images auto-resized to max ${MAX_EDGE_PX}px longest edge for Claude Vision optimization (~1,600 tokens)`,
         whenDisabled: `Full resolution capture preserved (may use 10,000+ tokens for large pages)`,
@@ -42,18 +53,30 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'Returns full HTML with all attributes and classes',
         tokenImpact: 'Semantic output uses 70-99% fewer tokens than raw HTML. Use --raw only when you need exact HTML structure.',
     },
+    'get:--full': {
+        default: 'Semantic output shows the element text up to 500 characters (whitespace collapsed; close buttons such as "×" and aria-hidden icons left out)',
+        whenEnabled: 'Shows all of the element text; cannot be combined with --raw or --node-id',
+        tokenImpact: 'A page-sized container can add thousands of tokens; target the element you need',
+    },
     'get:--all': {
         default: 'Returns first matching element only',
         whenEnabled: 'Returns all matching elements (only works with --raw)',
     },
-    'get:--nth': {
-        default: 'Returns first matching element',
-        whenEnabled: 'Returns the nth matching element (0-based index, only works with --raw)',
+    'get:--index': {
+        default: 'Returns the first matching element (body without a selector)',
+        whenEnabled: 'Returns that match of the selector (0-based), in semantic and --raw output; --nth is an alias',
+        automaticBehavior: 'Out of range exits 81; with a numeric index argument (a cached query index) it exits 81',
+    },
+    'query:--limit': {
+        default: 'dom a11y query lists the first 50 matches and says how many more there are; --json returns all of them',
+        whenEnabled: 'Lists that many matches (0 = all), in human and JSON output; count is always the total, JSON omitted the rest',
+        automaticBehavior: 'All matches are cached for index-based access (bdg dom click 55 works even when 50 are listed); an element the page and frame trees both report is listed once. Indices work with click, fill, hover, pressKey, scroll, submit, layout, get and listeners, also for elements of a cross-origin iframe of the same site (a consent dialog), whose scripts then run in that frame',
+        tokenImpact: 'About one line per match; a page can have hundreds of links',
     },
     'eval:--frame': {
         default: "Evaluates in the page's main frame",
         whenEnabled: "Evaluates in one iframe's main world (its own globals), including cross-origin (out-of-process) iframes; output gains a frame field (its URL)",
-        automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order, main page not counted), else an exact name/id attribute, else a case-insensitive part of the URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again).',
+        automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order, main page not counted), else an exact name/id attribute, else a case-insensitive part of the name, id or URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again).',
     },
     'console:-H': {
         default: 'Shows messages from current page load only (most recent navigation)',
@@ -73,14 +96,19 @@ const OPTION_BEHAVIORS = {
         default: 'Smart summary with errors deduplicated and warnings grouped',
         whenEnabled: 'Lists all messages chronologically without deduplication',
     },
+    'console:--last': {
+        default: 'Smart summary (without --list); a list shows the last 100 messages',
+        whenEnabled: 'Lists the last N messages (0 = all) chronologically, also without --list; JSON gets messages',
+        automaticBehavior: 'The [n] shown are positions in the session message list (what bdg details console <n> takes); when the page or level filter left messages out between the listed ones, a note says how many and why',
+    },
     'console:--level': {
         default: 'Shows all log levels (error, warning, log, info, debug)',
         whenEnabled: 'Filters to specific level: error, warning, log, info, or debug',
     },
     'fill:--no-wait': {
-        default: 'Waits for network stability after filling input (200ms idle)',
-        whenDisabled: 'Returns immediately without waiting for network',
-        automaticBehavior: 'Network wait helps ensure React/Vue state updates complete before next action',
+        default: 'Waits for network stability after filling input (150ms idle, up to 2s)',
+        whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
+        automaticBehavior: `Network wait helps ensure React/Vue state updates complete before next action. The value is read back after filling: when the page rejected or moved it, the output starts with a warning and JSON has valueMismatch { expected, actual } (exit code stays 0), plus movedTo naming the field of the form that got the value instead. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`,
     },
     'fill:--no-blur': {
         default: 'Triggers blur event after filling (validates most form fields)',
@@ -88,9 +116,10 @@ const OPTION_BEHAVIORS = {
         automaticBehavior: 'Blur triggers validation in most frameworks - disable only if you need to continue typing',
     },
     'click:--no-wait': {
-        default: 'Waits for network stability after click (200ms idle)',
-        whenDisabled: 'Returns immediately without waiting for network',
-        automaticBehavior: 'Network wait helps ensure AJAX requests triggered by click complete. The click itself uses real mouse events in the visible part of the element (method "mouse"); if the element is covered or has no size it falls back to DOM events (method "dom", with a warning)',
+        default: 'Waits for network stability after click (150ms idle, up to 2s)',
+        whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
+        automaticBehavior: `Network wait helps ensure AJAX requests triggered by click complete. ${TRIGGERED_REQUESTS_BEHAVIOR}. The click itself uses real mouse events in the visible part of the element (method "mouse"); if the element is covered or has no size it falls back to DOM events (method "dom", with a warning). Results the page shows later without requests (timers, spinners) are not waited for: use bdg dom wait <selector> --visible. ${ACTION_EFFECTS_BEHAVIOR}. A click with no DOM change, no request and no navigation (checked again 300 ms later, which adds 300 ms plus at most 250 ms for the read) is reported as ⚠ Element Clicked (no visible effect observed: no DOM change, requests or navigation within 300 ms) and effect: "none" in JSON (exit code stays 0); not claimed with --no-wait, for hover or right-click, after a copy or cut, or when the click hit a form control, label, media, iframe, popover button, a mailto:/tel:/javascript: or other non-http link, a link to another window or a custom element with a closed shadow root, or moved focus to an element that is not a button or link. Effects outside the DOM (CSS :hover/:focus-within styles, canvas, clipboard without a copy event) are not seen`,
+        tokenImpact: 'A click that navigates lists the whole page load in JSON triggeredRequests',
     },
     'click:--double': {
         default: 'Single click',
@@ -102,17 +131,18 @@ const OPTION_BEHAVIORS = {
     },
     'hover:--no-wait': {
         default: 'Waits for network stability after moving the mouse (menus may load content)',
-        whenDisabled: 'Returns immediately without waiting for network',
-        automaticBehavior: 'The mouse stays over the element afterwards, so hover menus stay open until the next mouse action',
+        whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
+        automaticBehavior: `The mouse stays over the element afterwards, so hover menus stay open until the next mouse action. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`,
     },
     'navigate:--no-wait': {
         default: 'Waits until the new page has loaded and the network and DOM are idle (up to 15 s)',
         whenDisabled: 'Returns as soon as the navigation has started',
-        automaticBehavior: 'Also applies to page reload/back/forward; indices from earlier queries become stale (87)',
+        automaticBehavior: 'Also applies to page reload/back/forward; indices from earlier queries become stale (87). Triggered requests are not listed (they are the page load; see bdg network list)',
     },
     'pressKey:--no-wait': {
-        default: 'Waits for network stability after key press (200ms idle)',
-        whenDisabled: 'Returns immediately without waiting for network',
+        default: 'Waits for network stability after key press (150ms idle, up to 2s)',
+        whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
+        automaticBehavior: `${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`,
     },
     'pressKey:--times': {
         default: 'Presses key once',
@@ -124,16 +154,52 @@ const OPTION_BEHAVIORS = {
     'submit:--wait-navigation': {
         default: 'Waits for network stability only',
         whenEnabled: 'Waits for page navigation to complete (use for forms that redirect)',
+        automaticBehavior: 'A navigation is a new document loading in the main frame, also at the same URL (a POST that redirects back to the form after a login error). When the new page loaded but requests were still running at --timeout, the submit succeeds with a warning; without a navigation it exits 102, and the hint says whether a page request was sent (slow server) or not (the form may submit via fetch)',
     },
     'submit:--wait-network': {
         default: 'Default network idle timeout',
         whenEnabled: 'Custom network idle timeout in ms (use for slow APIs)',
+        automaticBehavior: `${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}. A submit with no DOM change, request or navigation reports effect: "none" like dom click`,
+    },
+    'wait:--timeout': {
+        default: 'Gives up after 10000 ms',
+        whenEnabled: 'Gives up after the given milliseconds (1 to 600000)',
+        automaticBehavior: 'The page is watched (DOM mutations plus a 100 ms poll for style changes) and answers as soon as the matches change; a navigation during the wait continues it on the new document. A timeout exits 102 (CDP_TIMEOUT) with what the page showed last, e.g. "2 matches, none visible" or "document.readyState: loading", and a next step (dom query for no matches, dom layout for hidden ones, peek for a page still loading)',
+    },
+    'wait:--visible': {
+        default: 'Counts every match, hidden ones included',
+        whenEnabled: 'Counts only visible matches (rendered, non-empty box, visibility: visible; opacity 0 counts as visible, as with :visible)',
+        automaticBehavior: 'With --gone, waits until no match is visible (the element may stay in the DOM hidden)',
+    },
+    'wait:--gone': {
+        default: 'Waits for at least one match',
+        whenEnabled: 'Waits until nothing matches (nothing visible with --visible, nothing containing the text with --text), seen twice in a row in the same document once it is no longer loading, so the empty document right after a navigation does not count (a page stuck in readyState loading never meets it)',
+    },
+    'wait:--text': {
+        default: 'Any match counts',
+        whenEnabled: 'Only matches whose text contains the given text count (case-insensitive, whitespace collapsed; hidden elements are matched by their text nodes, as with :has-text)',
+        automaticBehavior: 'Needs a selector; use body to look in the whole page',
+    },
+    'wait:--load': {
+        default: 'Does not look at document.readyState',
+        whenEnabled: 'Also waits for document.readyState "complete"; without a selector waits only for that (a script whose server never answers keeps it "loading")',
     },
     'listeners:--type': {
         default: 'Lists listeners of every event type on the element, its ancestors (through open shadow roots), its document and window',
-        whenEnabled: 'Lists only these event types (comma-separated, case-sensitive like addEventListener)',
-        automaticBehavior: 'Listeners are grouped by type, nearest first; JSON line/column numbers are 0-based (human output shows them 1-based like DevTools). The Debugger domain is not enabled',
-        tokenImpact: 'Pages with many window/document listeners produce long lists; --type keeps the output short',
+        whenEnabled: 'Lists only these event types (comma-separated or repeated, case-sensitive like addEventListener); when none match, typeSuggestions names close types (Click, onclick → click)',
+        automaticBehavior: "Listeners are grouped by type, the element's own handlers first (types handled on the element before delegated ones; nearest first, no-ops last); JSON line/column numbers are 0-based (human output shows them 1-based like DevTools). React's on… props that run for the element (its own and its React parents', through portals; onFocus/onBlur as focusin/focusout; parents' props for non-bubbling events left out) are listed with source and location (framework: \"React\", reactProp: \"onClick\"; at most 50 of the requested types, reactHandlersSkipped counts the rest). jQuery handlers are shown instead of jQuery's dispatcher (framework: \"jQuery\", delegateSelector for delegates the element matches; a dispatcher with no handler for the element is omitted; at most 50 are resolved, jqueryHandlersSkipped counts the rest). Empty handlers (React's onclick placeholder) are marked noop and do not count as the element's own handler. The Debugger domain is not enabled",
+        tokenImpact: 'Framework roots are already collapsed; --type keeps the output short on pages with many listeners',
+    },
+    'listeners:--all': {
+        default: 'Collapses React roots: on an ancestor recognised as a React root container (React\'s keys on the node, or dispatchers named dispatchDiscreteEvent/dispatchContinuousEvent/dispatchEvent), the function objects that each listen for several event types become one line / one "collapsed" entry with its types, phases and dispatchers. Other multi-type handlers are never collapsed',
+        whenEnabled: 'Lists every listener of framework roots individually',
+        tokenImpact: 'On React pages --all adds a row per event type and phase (about 140 rows, 60 KB of JSON)',
+    },
+    'layout:--index': {
+        default: 'Reports every match of the selector (human output lists the first 20, JSON up to 100 plus an omitted count); a numeric argument reports that cached query element',
+        whenEnabled: 'Reports only the nth match (0-based); out of range exits 81',
+        automaticBehavior: 'Coordinates are CSS px: bounds relative to the top-level page (iframe offsets and page scroll included), viewport relative to the visible area. Iframes and overflow containers (scroll lists, overflow: hidden) clip what counts as visible (clippedBy names the one cutting it off). scrollBy brings the whole element into view and is limited to how far the page can scroll: for an element out of view it centres it (aligns its start when it is larger than the viewport; human output says "to centre it"), for a partly visible one it is the smallest scroll that shows all of it (the part cut off at the top or bottom; the start of one larger than the viewport; "partly visible (87%); scroll up 5px to see all of it"). Elements a page script moves on scroll (floating menus) may move again after it; fixed and sticky elements (page scroll does not move them, or only until they stick) and ones beyond that range get offScreenReason instead, which says "page scrolling is locked (…)" when the page cannot scroll because body/html is position: fixed or overflow: hidden, so in-flow content is not called fixed; a visible dialog (dialog[open], [aria-modal=true], [role=dialog|alertdialog]) is named as the likely cause ("likely by dialog div#consent"). page.viewport is the layout viewport without scrollbars, as dom scroll reports it; page.colorScheme is the prefers-color-scheme media feature the page sees (not the theme it renders). Content in a closed <details> or under content-visibility: hidden is hidden. coveredBy is the topmost element at the center of the largest visible box (none for pointer-events: none, nor for an element of the same click target: an overlay inside the link, button or label the element is in, a link to the same URL, or the textless absolutely positioned overlay link spanning the card that holds plain content); inert elements are flagged, not hidden',
+        tokenImpact: 'About one line per element; a cheap alternative to screenshots for "where is it?"',
     },
     'scroll:--down': {
         whenEnabled: 'Scrolls page down by specified pixel amount',
@@ -152,11 +218,12 @@ const OPTION_BEHAVIORS = {
     },
     'scroll:--bottom': {
         whenEnabled: 'Scrolls to the very bottom of the page',
+        automaticBehavior: 'A page scroll (--down/--up/--left/--right/--top/--bottom) that moved nothing still exits 0 but starts with a warning saying why: the document is no taller (wider) than the viewport, the page was already at that edge, or scrolling is locked; while document.readyState is not complete it adds that the page is still loading (bdg dom wait --load)',
     },
     'scroll:--no-wait': {
-        default: 'Waits for lazy-loaded content to stabilize after scroll (200ms network idle)',
-        whenDisabled: 'Returns immediately without waiting for lazy-loaded content',
-        automaticBehavior: 'Wait helps ensure images and infinite scroll content load before next action',
+        default: 'Waits for lazy-loaded content to stabilize after scroll (150ms network idle, up to 2s)',
+        whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
+        automaticBehavior: `Wait helps ensure images and infinite scroll content load before next action. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`,
     },
     'scroll:--index': {
         whenEnabled: 'If selector matches multiple elements, scrolls to the nth element (0-based)',
@@ -196,6 +263,11 @@ const OPTION_BEHAVIORS = {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',
     },
+    'bdg:--session': {
+        default: 'The default session in ~/.bdg (or $BDG_SESSION_DIR); BDG_SESSION=<name> selects a named session like the flag',
+        whenEnabled: 'Uses the named session in ~/.bdg/sessions/<name>/ (or $BDG_SESSION_DIR/sessions/<name>/) with its own daemon, Chrome, profile and port; every command (status, stop, cleanup, ...) acts on that session only',
+        automaticBehavior: 'Accepted before or after any subcommand; --session wins over BDG_SESSION. Names are case-insensitive (lower-cased: ALPHA is alpha). Without --port a named session takes the first free port above 9222 not claimed by another running session, and keeps it in port.txt. Names: 1-40 letters, digits, "-" or "_", starting with a letter or digit (exit 81 otherwise, also when the socket path would be too long). Hints and suggestions in its output carry --session <name>',
+    },
     'cleanup:-f': {
         default: 'Refuses to run while a session is active; removes files left by a crashed session',
         whenEnabled: 'Kills the running daemon and its Chrome first (use when a session is stuck)',
@@ -203,6 +275,25 @@ const OPTION_BEHAVIORS = {
     'cleanup:--aggressive': {
         whenEnabled: 'Alias for --force, kept for compatibility',
     },
+    'cleanup:--purge': {
+        default: "A named session's directory (Chrome profile, ~60 MB; logs; port.txt) is kept for its next start",
+        whenEnabled: 'After cleaning up, deletes the directory of the session named by --session (exit 81 without --session); a running session is refused unless --force is given, and the directory is kept (exit 90) if the daemon still answers, cleanup reported a problem, or its Chrome has not exited',
+    },
+    'bdg:--viewport': {
+        default: 'A launched Chrome opens a 1920x1080 window (the viewport is smaller by the scrollbar, and in a visible window by the browser UI); an attached Chrome keeps its window',
+        whenEnabled: 'The page gets exactly that viewport (CSS px, e.g. 1280x800) for the whole session, through navigations and reloads (Emulation.setDeviceMetricsOverride at the display pixel ratio); a launched Chrome also opens its window at that size, so tabs the page opens get it too',
+        automaticBehavior: 'Works with --chrome-ws-url: the override belongs to the session, and Chrome drops it when the session ends, so the attached browser gets its own size back. bdg status shows the resulting layout viewport without the scrollbar (Viewport: 1265×800 (--viewport 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81',
+    },
+    'bdg:--color-scheme': {
+        default: 'The page sees the system setting for prefers-color-scheme (headless Chrome follows the OS, so a dark OS renders dark pages); bdg status and dom layout show which one',
+        whenEnabled: 'Emulates prefers-color-scheme: light or dark for the whole session (Emulation.setEmulatedMedia); other values exit 81 with a suggestion',
+        automaticBehavior: 'Applies to the session page (and its same-process iframes); Chrome drops it when the session ends, also for an attached Chrome (--chrome-ws-url)',
+    },
+    'bdg:--chrome-ws-url': {
+        default: 'bdg launches its own Chrome (closed on stop)',
+        whenEnabled: 'Attaches to a running Chrome instead; it keeps running after stop. --port, -u and --[no-]headless cannot be combined with it (exit 81)',
+        automaticBehavior: 'A port (9222), host:port or http://host:port is turned into the browser WebSocket URL via /json/version; a browser URL uses the first open tab. Refused with exit 90 when another running bdg session launched that Chrome or drives that tab (sessions of this BDG_SESSION_DIR, and of others that claimed a port)',
+    },
     'stop:--kill-chrome': {
         default: 'Chrome launched by bdg is always closed on stop; an attached Chrome (--chrome-ws-url) is left running',
         whenEnabled: 'No additional effect; kept for compatibility',