browser-debugger-cli 0.12.0 → 0.14.0

package/dist/commands/network/list.js

@@ -6,7 +6,7 @@ import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
 import { noteFollowConnected } from '../shared/daemonErrorHandler.js';
 import { fetchNetworkRequests, createErrorResult } from '../shared/dataFetcher.js';
-import { followFetchFailure, setupFollowMode, } from '../shared/followMode.js';
+import { followFetchFailure, newPageCrashes, 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';
@@ -14,6 +14,7 @@ import { resolvePreset, FILTER_PRESETS } from '../../telemetry/filterPresets.js'
 import { filterByResourceType } from '../../telemetry/filters.js';
 import { buildSuccessResponse } from '../../ui/OutputBuilder.js';
 import { formatNetworkFollowRows, formatNetworkList, pageStartOf, } from '../../ui/formatters/networkList.js';
+import { pageCrashedNote, withPageCrashedNote } from '../../ui/messages/commands.js';
 import { followingNetworkMessage, stoppedFollowingNetworkMessage, } from '../../ui/messages/networkMessages.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { validateFilterOption } from './shared.js';
@@ -111,12 +112,51 @@ function buildFormatOptions(options, result, lastLimit) {
         totalCount: result.totalCount,
         filteredCount: result.filteredCount,
         ...(result.pageStart && { pageStart: result.pageStart }),
+        evictions: {
+            requestsDropped: result.dropped ?? 0,
+            bodiesEvicted: result.bodiesEvicted ?? 0,
+        },
+    };
+}
+/**
+ * Watch the session's dropped/evicted counts across follow polls, so the
+ * stream notes them once per kind instead of on every poll.
+ *
+ * @returns Function giving the counts when requests or bodies were let go
+ *   for the first time since the stream started, otherwise undefined
+ */
+function newEvictionKinds() {
+    let requestsNoted = false;
+    let bodiesNoted = false;
+    return (counts) => {
+        const newRequests = !requestsNoted && counts.requestsDropped > 0;
+        const newBodies = !bodiesNoted && counts.bodiesEvicted > 0;
+        requestsNoted ||= newRequests;
+        bodiesNoted ||= newBodies;
+        return newRequests || newBodies ? counts : undefined;
+    };
+}
+/**
+ * JSON fields of the dropped/evicted counts (the non-zero ones).
+ *
+ * @param counts - Counts to report, if any
+ * @returns `dropped` and `bodiesEvicted` when non-zero
+ */
+function evictionFields(counts) {
+    if (!counts)
+        return {};
+    return {
+        ...(counts.requestsDropped > 0 && { dropped: counts.requestsDropped }),
+        ...(counts.bodiesEvicted > 0 && { bodiesEvicted: counts.bodiesEvicted }),
     };
 }
 /**
  * Stream network requests: the last `lastN` finished ones at start, then
  * each request once, when it has finished loading or failed (a request whose
- * headers arrived but whose body is still loading waits), like `tail -f`.
+ * headers arrived but whose body is still loading waits), like `tail -f`,
+ * with a warning (JSON `pageCrashedAt`) once when the page crashes, and a
+ * note (JSON `dropped`, `bodiesEvicted`) the first time the session drops
+ * requests or evicts bodies at its limits.
  *
  * @param options - Command options
  * @param resourceTypes - Validated resource types
@@ -124,6 +164,8 @@ function buildFormatOptions(options, result, lastLimit) {
  */
 async function runFollowMode(options, resourceTypes, lastN) {
     const shown = new Set();
+    const newCrash = newPageCrashes();
+    const newEviction = newEvictionKinds();
     let started = false;
     const showNetwork = async () => {
         const result = await fetchNetworkRequests(filtersNeedHeaders(options));
@@ -131,32 +173,40 @@ async function runFollowMode(options, resourceTypes, lastN) {
             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));
-        const present = new Set(result.data.map((request) => request.requestId));
+        const { requests } = result.data;
+        const crashedAt = newCrash(result.data.pageCrashedAt);
+        const evictions = newEviction(result.data.evictions);
+        const finished = filterRequests(requests, options, resourceTypes).filter((request) => request.duration !== undefined && !shown.has(request.requestId));
+        const present = new Set(requests.map((request) => request.requestId));
         for (const id of shown)
             if (!present.has(id))
                 shown.delete(id);
         finished.forEach((request) => shown.add(request.requestId));
         const fresh = started || lastN === 0 ? finished : finished.slice(-lastN);
         if (options.json) {
-            if (!started || fresh.length > 0) {
+            if (!started || fresh.length > 0 || crashedAt !== undefined || evictions) {
                 const data = {
                     requests: fresh,
-                    totalCount: result.data.length,
+                    totalCount: requests.length,
                     filteredCount: fresh.length,
+                    ...(crashedAt !== undefined && { pageCrashedAt: crashedAt }),
+                    ...evictionFields(evictions),
                 };
-                console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
+                console.log(JSON.stringify(buildSuccessResponse(data)));
             }
         }
         else {
-            const pageStart = pageStartOf(result.data);
+            const pageStart = pageStartOf(requests);
             const text = formatNetworkFollowRows(fresh, {
                 header: !started,
                 verbose: options.verbose ?? false,
                 ...(pageStart && { pageStart }),
+                ...(evictions && { evictions }),
             });
             if (text)
                 console.log(text);
+            if (crashedAt !== undefined)
+                console.log(pageCrashedNote(crashedAt));
         }
         started = true;
         return undefined;
@@ -219,18 +269,21 @@ export function registerListCommand(networkCmd) {
                 }
                 return createErrorResult(result.error, result.exitCode, result.suggestion);
             }
-            const filtered = filterRequests(result.data, options, resourceTypes);
-            const pageStart = pageStartOf(result.data);
+            const { requests, pageCrashedAt, evictions } = result.data;
+            const filtered = filterRequests(requests, options, resourceTypes);
+            const pageStart = pageStartOf(requests);
             return {
                 success: true,
                 data: {
                     requests: lastN === 0 ? filtered : filtered.slice(-lastN),
-                    totalCount: result.data.length,
+                    totalCount: requests.length,
                     filteredCount: filtered.length,
                     ...(pageStart && { pageStart }),
+                    ...(pageCrashedAt !== undefined && { pageCrashedAt }),
+                    ...evictionFields(evictions),
                 },
             };
-        }, options, (data) => formatNetworkList(data.requests, buildFormatOptions(options, data, lastN)));
+        }, options, (data) => withPageCrashedNote(formatNetworkList(data.requests, buildFormatOptions(options, data, lastN)), data.pageCrashedAt));
     });
 }
 //# sourceMappingURL=list.js.map

package/dist/commands/optionBehaviors.d.ts

@@ -6,13 +6,36 @@
  *
  * @see docs/principles/SELF_DOCUMENTING_SYSTEMS.md
  */
+import type { Option } from 'commander';
 import type { OptionBehavior } from './helpJson.js';
+/**
+ * Registry key format: last command name, colon, long flag (the short flag
+ * when there is no long one), e.g. "screenshot:--no-resize", "bdg:--headless"
+ */
+type BehaviorKey = string;
+/**
+ * Build behavior registry key from command and option: the command's own
+ * name (`bdg` for the root) and the option's long flag, or its short flag
+ * when it has no long one.
+ *
+ * @param commandName - Command name (e.g., "screenshot")
+ * @param option - Commander option
+ * @returns Registry key
+ */
+export declare function behaviorKey(commandName: string, option: Option): BehaviorKey;
+/**
+ * Every key in the behavior registry.
+ *
+ * @returns Registry keys
+ */
+export declare function listBehaviorKeys(): BehaviorKey[];
 /**
  * Look up behavioral metadata for an option.
  *
  * @param commandName - Name of the command containing the option
- * @param flags - Option flags string from Commander
+ * @param option - Commander option
  * @returns Behavioral metadata if registered, undefined otherwise
  */
-export declare function getOptionBehavior(commandName: string, flags: string): OptionBehavior | undefined;
+export declare function getOptionBehavior(commandName: string, option: Option): OptionBehavior | undefined;
+export {};
 //# sourceMappingURL=optionBehaviors.d.ts.map

package/dist/commands/optionBehaviors.js

@@ -17,6 +17,8 @@ const STILL_CHANGING_BEHAVIOR = 'When the page was still changing as the action
 const SHOWN_BEHAVIOR = 'Elements the action showed are listed (Shown: <element> "<text>"; JSON shown [{ text, element }], at most 3, outermost first): elements with visible text added inside the target\'s form, search box, dialog or combobox (else its grandparent, or its parent when that is the body), and popups and messages added anywhere (tooltip, menu, listbox, dialog, alert, status roles, popover, aria-live, message-like classes); widgets elsewhere on the page and re-rendered elements whose text was there before do not count';
 /** 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)';
+/** How every follow mode (peek, console, network list) runs and ends */
+const FOLLOW_BEHAVIOR = 'Stops with exit 83 when the session it follows ends, 130 on Ctrl-C, 143 on SIGTERM; with --json prints one compact object per line (NDJSON). Other failures (a busy page, a timeout) are retried: reported once in text, as one error line per refresh in JSON';
 /**
  * Behavioral metadata registry.
  *
@@ -63,8 +65,9 @@ const OPTION_BEHAVIORS = {
     },
     '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',
+        whenEnabled: 'Shows all of the element text; with --raw (or --node-id) prints the whole outer HTML instead of its first 20000 characters, and JSON outerHTML is whole too (else cut to 20000 with truncatedFrom, the original length)',
+        automaticBehavior: 'Without --full, --raw output cuts each element\'s HTML at 20000 characters and ends it with "… N more chars (use --full)"',
+        tokenImpact: 'A page-sized container can add thousands of tokens; dom get body --raw --full on Wikipedia is about 3.4 MB. Target the element you need',
     },
     'get:--all': {
         default: 'Returns first matching element only',
@@ -73,40 +76,52 @@ const OPTION_BEHAVIORS = {
     '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',
+        automaticBehavior: 'Past the last match exits 81; a numeric index argument (a cached query index) past the indexed matches, or from an earlier page, exits 87 (re-run dom query)',
     },
     'query:--limit': {
-        default: 'dom a11y query lists the first 50 matches and says how many more there are; --json returns all of them',
+        default: 'dom query and dom a11y query list the first 50 matches and say how many more there are; --json lists the first 100 with count (all matches) and omitted (the rest)',
         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',
+        automaticBehavior: 'Matches are cached for index-based access (bdg dom click 55 works even when 50 are listed): all of them for dom a11y query, the first 1000 (or --limit, if higher) for dom query, which describes only those, so a page with 50000 matches answers in under a second; 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 (piped JSON about 160 bytes per dom query match, 230 per a11y match); a page can have thousands of links: on Wikipedia "United States" --limit 0 --json is 1.0 MB (dom query a) and 1.3 MB (dom a11y query role:link), the default 16 KB and 23 KB',
+    },
+    'tree:--limit': {
+        default: 'dom a11y tree lists the first 50 meaningful nodes depth-first, in human and JSON output; JSON count is the whole tree = nodes listed + omitted (cut by --limit/--depth) + skipped (never listed)',
+        whenEnabled: 'Lists that many nodes; 0 = all listed nodes (text boxes and empty wrappers are always skipped)',
+        automaticBehavior: 'Ignored nodes, text boxes, blank text, text repeating its parent name and nameless layout wrappers (generic, none, presentation, layout tables) are never listed (JSON skipped counts them); their children move up a level. For the raw tree with every node use bdg cdp Accessibility.getFullAXTree --json. JSON nodes carry depth (0 = root) instead of childIds; nodes outside the root (frame content) follow the root tree',
+        tokenImpact: 'About 140 bytes per piped JSON node (7 KB by default); the whole tree of a long page is megabytes (Wikipedia "United States": 51k nodes, 20k listed, 2.6 MB with --limit 0 --json), so prefer --depth or dom a11y query "role:<role>"',
+    },
+    'tree:--depth': {
+        default: 'dom a11y tree lists every level (up to --limit nodes)',
+        whenEnabled: 'Lists nodes down to that level (0 = root only); deeper nodes are counted in omitted',
+        tokenImpact: 'An outline of a page (landmarks, headings) in a few levels',
     },
     '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: document order of the <iframe> elements, nested ones depth-first, 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). An index that names another frame than in the last bdg dom frames listing (iframes added, removed or moved, or the page navigated) fails with 87 STALE_CACHE: re-run bdg dom frames or pick the frame by name.',
     },
-    'console:-H': {
-        default: 'Shows messages from current page load only (most recent navigation)',
-        whenEnabled: 'Shows messages from ALL page loads during the session',
-        automaticBehavior: 'Page navigations create new "navigation contexts" - default filters to latest context',
+    'eval:--full': {
+        default: 'Human output prints the first 20000 characters of the value followed by "… N more chars (use --full)"; in JSON a string result is cut to 20000 characters with truncatedFrom (the original length). Objects and arrays in JSON are not cut',
+        whenEnabled: 'Prints the whole value, byte for byte',
+        tokenImpact: 'dom eval document.documentElement.outerHTML on Wikipedia is about 3.6 MB with --full; select what you need in the expression instead',
+    },
+    'console:--full': {
+        default: 'Message texts are cut: human output (summary, --list, --follow) at 200 characters followed by "… N more chars (use --full)"; JSON text at 10000 characters with truncatedFrom (the original length)',
+        whenEnabled: 'Message texts are printed whole, in human and JSON output',
+        tokenImpact: 'A page that logs a large payload or throws a long error can add megabytes; bdg details console <n> shows one message whole',
     },
     'console:--history': {
         default: 'Shows messages from current page load only (most recent navigation)',
         whenEnabled: 'Shows messages from ALL page loads during the session',
         automaticBehavior: 'Page navigations create new "navigation contexts" - default filters to latest context',
     },
-    'console:-l': {
-        default: 'Smart summary with errors deduplicated and warnings grouped',
-        whenEnabled: 'Lists all messages chronologically without deduplication',
-    },
     'console:--list': {
-        default: 'Smart summary with errors deduplicated and warnings grouped',
+        default: 'Smart summary with errors deduplicated and warnings grouped: the newest 50 distinct errors and warnings, with a note for the earlier ones. The session keeps the newest 10000 messages; dropped ones are counted (dropped in JSON)',
         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',
+        whenEnabled: 'Lists the last N messages (0 = all) chronologically, also without --list; JSON gets messages and N distinct errors and warnings (0 = all; default 50)',
         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': {
@@ -126,7 +141,7 @@ const OPTION_BEHAVIORS = {
     'click:--no-wait': {
         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; --strict refuses instead). Results the page shows later (timers, spinners, slow renders) are not waited for but reported as pending work: use bdg dom wait <selector> --visible. ${ACTION_EFFECTS_BEHAVIOR}. ${STILL_CHANGING_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`,
+        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; --strict refuses instead). Results the page shows later (timers, spinners, slow renders) are not waited for but reported as pending work: use bdg dom wait <selector> --visible. ${ACTION_EFFECTS_BEHAVIOR}. ${STILL_CHANGING_BEHAVIOR}. A click with no DOM change, no request, no navigation and no console message (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': {
@@ -145,7 +160,7 @@ const OPTION_BEHAVIORS = {
     'hover:--no-wait': {
         default: 'Waits for network stability after moving the mouse (menus may load content)',
         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}. ${SHOWN_BEHAVIOR}; for a hover also elements around it (its parent's subtree) and tooltips, menus, listboxes, dialogs and popovers anywhere that were hidden before, so captions shown by CSS :hover count (hidden elements noted by identity right before the mouse moves: up to 1500, within 8 ms). A hover never claims "no visible effect" and does not check whether the page was still changing`,
+        automaticBehavior: `The element is scrolled into view first; when the page moved, Scrolled (JSON scrolledBy) says how far. The mouse stays over the element afterwards, so hover menus stay open until the next mouse action. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}. ${SHOWN_BEHAVIOR}; for a hover also elements around it (its parent's subtree) and tooltips, menus, listboxes, dialogs and popovers anywhere that were hidden before, so captions shown by CSS :hover count (hidden elements noted by identity right before the mouse moves: up to 1500, within 8 ms). A hover never claims "no visible effect" and does not check whether the page was still changing`,
     },
     'hover:--strict': {
         default: 'A covered, hidden or zero-size element gets synthetic mouseover/mouseenter events (method "dom", with a warning)',
@@ -215,7 +230,7 @@ const OPTION_BEHAVIORS = {
     'audit:--level': {
         default: 'Text must reach WCAG AA: 4.5, or 3 for large text (24px, or 18.66px bold); every text-drawing element is checked, composited like dom inspect',
         whenEnabled: '--level AAA asks 7, or 4.5 for large text',
-        automaticBehavior: 'One walk over the rendered elements (open shadow roots included, at most 20000; capped says when it stopped). Findings are sorted weakest first; --limit (default 20) lists that many per check and the rest are counted. Overflow leaves out content inside horizontal scrollers and visually-hidden 1px text; identical findings are grouped (×N)',
+        automaticBehavior: 'One walk over the rendered elements (open shadow roots included, at most 20000; capped says when it stopped). Findings are sorted weakest first; --limit (default 20) lists that many per check and the rest are counted. Overflow leaves out content inside horizontal scrollers and visually-hidden 1px text; identical findings are grouped (×N). Contrast is approximate (approximate: …) when something is painted behind or on top of text in view (hit-tested), or for text out of view whose ancestors paint nothing below body (only its ancestors were checked). Canvas animations cannot be listed; visible canvas elements are counted (canvases)',
         tokenImpact: 'About one line per finding; --limit bounds it',
     },
     'layout:--index': {
@@ -228,12 +243,12 @@ const OPTION_BEHAVIORS = {
         default: 'Inspects the first rendered match (the first when none is rendered) and notes how many matched; a numeric argument inspects that cached element (from dom query, dom form or dom a11y query)',
         whenEnabled: 'Inspects the nth match (0-based); out of range exits 81',
         automaticBehavior: 'Answers "what does it look like" without a screenshot, grouped like Figma Dev Mode: header (element, text, size and page position, [flex]/[grid], [not rendered]/[hidden]/[offscreen]/[covered by …], prefers-color-scheme), box (margin, padding, border widths, box-sizing, overflow, scroll size), layout (display, position, flex/grid container and item settings), parent (its display and layout, distances to its content edges, gaps to the neighbouring siblings), text (first font family → the font Chrome rendered, (webfont) or local; weight size/line-height; color; WCAG contrast against the composited background; only for elements with text), fill, border (sides, radius, outline), fx (shadow, transform, filter, opacity, blend), state (cursor, pointer-events, user-select, appearance), pseudo (::before/::after with content, ::placeholder) and a child tree (depth 2, 20 rows, identical siblings grouped). Values that change nothing (0, none, transparent, normal) are left out; colors are hex (lab/oklch from Tailwind converted), lengths px without the unit, rounded to 0.1. Secrets are never shown. JSON uses Figma-aligned names (rect, box, layout.sizing hug/fill/fixed, text, fills, strokes, radius, effects, children). Also by default: hints, the element\'s own declarations that have no effect (justify-content on a block, width on an inline element, top on a static one, var() of an unset custom property) with the reason, the fix and the rule\'s file:line',
-        tokenImpact: 'About 60–80 tokens for the styles and 30–70 more for the child tree (--tree 0 drops it), against about 1,500 for a screenshot or 3,000+ for raw computed styles',
+        tokenImpact: 'About 80–130 tokens for a button: 80–100 for the styles, up to 50 per hint (--no-hints drops them), and 30–70 more for a child tree (--tree 0 drops it), against about 1,500 for a screenshot or 3,000+ for raw computed styles',
     },
     'inspect:--all': {
         default: 'Shows the curated groups (the properties that define the look)',
         whenEnabled: 'Lists every computed property that differs from the default of the same element type, longhands collapsed into shorthands, noise (logical duplicates, currentColor echoes, custom properties) dropped',
-        tokenImpact: 'About 80 tokens instead of 60–80',
+        tokenImpact: 'About as many tokens as the curated groups (about 90 for a button)',
     },
     'inspect:--props': {
         default: 'Shows the curated groups',
@@ -251,6 +266,7 @@ const OPTION_BEHAVIORS = {
     },
     'inspect:--no-hints': {
         default: "Hints at the element's own author declarations that have no effect (flex/grid properties without flex or grid, item properties without a flex or grid parent, offsets on static elements, sizes on inline ones, var() of an unset custom property, form controls in the browser's font), within a 1 s budget; hints none when nothing was found",
+        automaticBehavior: "After a hint read times out, later inspects on the same page skip the hints without waiting (hints skipped: this page's stylesheets are slow to read) until a read is fast again, a stylesheet changes or it navigates; --rules and --why still wait up to 5 s. Matched rules that took over 300 ms are reused for up to 5 s, until a command that may change the page or a stylesheet or DOM change",
         whenEnabled: 'Skips the hints and does not read the matched rules',
     },
     'scroll:--down': {
@@ -291,36 +307,52 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'Quick scan: field names, types, and required status only',
         tokenImpact: 'Reduces output ~50% for initial discovery',
     },
+    'peek:--full': {
+        default: 'Console message texts are cut: human output at 200 characters (compact output also at 2 lines) followed by "… N more chars (use --full)"; JSON text at 10000 characters with truncatedFrom (the original length)',
+        whenEnabled: 'Console message texts are printed whole, in human and JSON output',
+        tokenImpact: 'A page that logs a large payload can add megabytes per peek',
+    },
     'peek:--type': {
         whenEnabled: 'Filters network requests by CDP resource type. Case-insensitive, comma-separated. Valid: Document, Stylesheet, Image, Media, Font, Script, XHR, Fetch, WebSocket, etc.',
     },
-    'peek:-f': {
-        default: 'Shows snapshot of current data',
-        whenEnabled: 'Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail',
-    },
     'peek:--follow': {
         default: 'Shows snapshot of current data',
         whenEnabled: 'Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail',
+        automaticBehavior: FOLLOW_BEHAVIOR,
+    },
+    'console:--follow': {
+        default: 'Prints the messages logged so far and exits',
+        whenEnabled: 'Streams new messages as they come (the last --last at start)',
+        automaticBehavior: FOLLOW_BEHAVIOR,
+    },
+    'list:--follow': {
+        default: 'Lists the requests captured so far and exits',
+        whenEnabled: 'Streams requests as they finish',
+        automaticBehavior: FOLLOW_BEHAVIOR,
     },
-    'peek:-v': {
+    'peek:--verbose': {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',
     },
-    'start:--all': {
+    'bdg:--headless': {
+        default: 'A window when there is a display: on macOS unless over SSH (SSH_CONNECTION, SSH_TTY) or CI is set; on Linux when DISPLAY or WAYLAND_DISPLAY is set. Servers, containers and CI run headless',
+        whenEnabled: 'Chrome runs without a window (pass it when running unattended on a Mac)',
+    },
+    'bdg:--no-headless': {
+        default: 'A window when there is a display: on macOS unless over SSH (SSH_CONNECTION, SSH_TTY) or CI is set; on Linux when DISPLAY or WAYLAND_DISPLAY is set',
+        whenEnabled: 'Chrome shows its window even without a detected display (it fails without one)',
+    },
+    'bdg:--all': {
         default: 'Tracking/analytics requests and console noise are filtered; bodies of binary responses (images, fonts) are not captured',
         whenEnabled: 'Everything is captured, including binary response bodies (base64, flagged by responseBodyBase64, within --max-body-size)',
         tokenImpact: 'details network --json and HAR exports can grow considerably on media-heavy pages',
     },
-    'peek:--verbose': {
-        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': {
+    'cleanup:--force': {
         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)',
     },
@@ -355,36 +387,39 @@ const OPTION_BEHAVIORS = {
         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',
     },
-    'status:-v': {
-        default: 'Basic session status (daemon running, session active, URL)',
-        whenEnabled: 'Includes Chrome diagnostics and CDP connection details',
-    },
     'status:--verbose': {
         default: 'Basic session status (daemon running, session active, URL)',
         whenEnabled: 'Includes Chrome diagnostics and CDP connection details',
     },
 };
 /**
- * Build behavior registry key from command and flag.
+ * Build behavior registry key from command and option: the command's own
+ * name (`bdg` for the root) and the option's long flag, or its short flag
+ * when it has no long one.
  *
  * @param commandName - Command name (e.g., "screenshot")
- * @param flags - Option flags string (e.g., "--no-resize")
+ * @param option - Commander option
  * @returns Registry key
  */
-function buildKey(commandName, flags) {
-    const firstFlag = flags.split(',')[0] ?? flags;
-    const flagName = firstFlag.trim().split(' ')[0] ?? firstFlag.trim();
-    return `${commandName}:${flagName}`;
+export function behaviorKey(commandName, option) {
+    return `${commandName}:${option.long ?? option.short ?? option.flags}`;
+}
+/**
+ * Every key in the behavior registry.
+ *
+ * @returns Registry keys
+ */
+export function listBehaviorKeys() {
+    return Object.keys(OPTION_BEHAVIORS);
 }
 /**
  * Look up behavioral metadata for an option.
  *
  * @param commandName - Name of the command containing the option
- * @param flags - Option flags string from Commander
+ * @param option - Commander option
  * @returns Behavioral metadata if registered, undefined otherwise
  */
-export function getOptionBehavior(commandName, flags) {
-    const key = buildKey(commandName, flags);
-    return OPTION_BEHAVIORS[key];
+export function getOptionBehavior(commandName, option) {
+    return OPTION_BEHAVIORS[behaviorKey(commandName, option)];
 }
 //# sourceMappingURL=optionBehaviors.js.map

package/dist/commands/peek.js

@@ -8,6 +8,7 @@ import { fetchPreviewOutput, createErrorResult, } from './shared/dataFetcher.js'
 import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
 import { handleValidationError } from './shared/handleValidationError.js';
 import { MAX_LAST_ITEMS, positiveIntRule, resourceTypeRule } from './shared/validation.js';
+import { MAX_CONSOLE_JSON_TEXT_LENGTH, MAX_CONSOLE_TEXT_LENGTH } from '../constants.js';
 import { CommandError } from '../errors/index.js';
 import { intervalWithoutFollowError } from '../errors/messages.js';
 import { filterByResourceType } from '../telemetry/filters.js';
@@ -137,6 +138,7 @@ function previewDisplayOptions(options, lastN) {
         last: lastN,
         verbose: options.verbose,
         follow: options.follow,
+        full: options.full,
     };
 }
 /**
@@ -162,6 +164,7 @@ export function registerPeekCommand(program) {
         .option('--interval <ms>', 'Refresh interval of --follow in ms, 100-60000 (default: 1000)')
         .option('--last <count>', 'Show last N items, 0 for all', '10')
         .option('--type <types>', 'Filter network requests by resource type (comma-separated: Document,XHR,Fetch,etc.)')
+        .option('--full', `Print console message texts whole (default: the first ${MAX_CONSOLE_TEXT_LENGTH} characters, ${MAX_CONSOLE_JSON_TEXT_LENGTH} in JSON)`, false)
         .action(async (options) => {
         showBothSectionsWhenBothRequested(options);
         if (options.network && !options.json) {

package/dist/commands/shared/CommandRunner.js

@@ -2,7 +2,7 @@ import { getQuickIPCRequestTimeout } from '../../constants.js';
 import { CommandError, isDaemonConnectionError } from '../../errors/index.js';
 import { daemonNotRunningError, unknownError, genericError, commandTimedOutError, sessionNotRespondingError, sessionEndedDuringCommandError, } from '../../errors/messages.js';
 import { IPCEarlyCloseError, IPCTimeoutError } from '../../ipc/transport/IPCError.js';
-import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
+import { OutputBuilder, buildSuccessResponse, stringifyEnvelope } from '../../ui/OutputBuilder.js';
 import { escapeControlChars } from '../../ui/formatting.js';
 import { noActiveSessionMessage, startSessionSuggestion } from '../../ui/messages/sessionCommand.js';
 import { getErrorExitCode, getErrorMessage } from '../../utils/errors.js';
@@ -36,7 +36,7 @@ export function noActiveSessionError() {
 export async function runJsonCommand(fn) {
     try {
         const data = await fn();
-        console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
+        console.log(stringifyEnvelope(buildSuccessResponse(data)));
         process.exit(EXIT_CODES.SUCCESS);
     }
     catch (caught) {
@@ -49,10 +49,10 @@ export async function runJsonCommand(fn) {
         const suggestion = error instanceof CommandError && typeof error.metadata['suggestion'] === 'string'
             ? error.metadata['suggestion']
             : undefined;
-        console.log(JSON.stringify(OutputBuilder.buildJsonError(getErrorMessage(error), {
+        console.log(stringifyEnvelope(OutputBuilder.buildJsonError(getErrorMessage(error), {
             exitCode,
             ...(suggestion && { suggestion }),
-        }), null, 2));
+        })));
         process.exit(exitCode);
     }
 }
@@ -112,10 +112,10 @@ export async function runCommand(handler, options, formatter) {
         if (!result.success) {
             const exitCode = result.exitCode ?? EXIT_CODES.UNHANDLED_EXCEPTION;
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(result.error ?? 'Unknown error', {
+                console.log(stringifyEnvelope(OutputBuilder.buildJsonError(result.error ?? 'Unknown error', {
                     ...result.errorContext,
                     exitCode,
-                }), null, 2));
+                })));
             }
             else {
                 console.error(result.error ? genericError(result.error) : unknownError());
@@ -133,14 +133,14 @@ export async function runCommand(handler, options, formatter) {
             console.error(escapeControlChars(result.hint));
         }
         if (options.json) {
-            console.log(JSON.stringify(buildSuccessResponse(result.data), null, 2));
+            console.log(stringifyEnvelope(buildSuccessResponse(result.data)));
         }
         else if (formatter) {
             const formattedOutput = formatter(result.data);
             console.log(escapeControlChars(formattedOutput));
         }
         else {
-            console.log(JSON.stringify(buildSuccessResponse(result.data), null, 2));
+            console.log(stringifyEnvelope(buildSuccessResponse(result.data)));
         }
         process.exit(EXIT_CODES.SUCCESS);
     }
@@ -152,10 +152,10 @@ export async function runCommand(handler, options, formatter) {
                 : caught;
         if (error instanceof CommandError) {
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, {
+                console.log(stringifyEnvelope(OutputBuilder.buildJsonError(error.message, {
                     ...error.metadata,
                     exitCode: error.exitCode,
-                }), null, 2));
+                })));
             }
             else {
                 console.error(genericError(error.message));
@@ -168,10 +168,10 @@ export async function runCommand(handler, options, formatter) {
         const errorMessage = getErrorMessage(error);
         if (isDaemonConnectionError(error)) {
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(noActiveSessionMessage(), {
+                console.log(stringifyEnvelope(OutputBuilder.buildJsonError(noActiveSessionMessage(), {
                     suggestion: startSessionSuggestion(),
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
-                }), null, 2));
+                })));
             }
             else {
                 console.error(daemonNotRunningError());
@@ -180,7 +180,7 @@ export async function runCommand(handler, options, formatter) {
         }
         const exitCode = getErrorExitCode(error, EXIT_CODES.UNHANDLED_EXCEPTION);
         if (options.json) {
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(errorMessage, { exitCode }), null, 2));
+            console.log(stringifyEnvelope(OutputBuilder.buildJsonError(errorMessage, { exitCode })));
         }
         else {
             console.error(genericError(errorMessage));

package/dist/commands/shared/daemonErrorHandler.d.ts

@@ -28,8 +28,11 @@ export declare function noteFollowConnected(): void;
  * Handle daemon connection errors with consistent formatting and behavior.
  *
  * Outside follow mode the command exits. In follow mode, a session that never
- * answered exits too (there is nothing to follow, exit 83); a session that
- * goes away is reported once and retried until a new one starts.
+ * answered exits too (there is nothing to follow, exit 83), and so does one
+ * that ends while followed (no session any more, exit 83), so a follower
+ * running in the background finds out. Other failures (a busy page, a
+ * timeout) are retried: reported once in text, and on every failed refresh
+ * in JSON, one object per line.
  *
  * @param error - Error message to display
  * @param options - Error handling options