browser-debugger-cli 0.12.0 → 0.13.0

package/dist/commands/helpTopic.js

@@ -1,8 +1,9 @@
 /**
  * `bdg help <command...>` topics and Commander usage-error hints.
  */
+import { commandPath } from './helpJson.js';
 import { CommandError } from '../errors/index.js';
-import { unknownHelpTopicError } from '../errors/messages.js';
+import { missingSubcommandMessage, unknownHelpTopicError, usageHelpSuggestion, } from '../errors/messages.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
 /** Commander's typo hint on its own line, e.g. "(Did you mean query?)" */
@@ -55,4 +56,61 @@ export function splitCommanderHint(text) {
         return { message };
     return { message: message.slice(0, hint.index).trim(), suggestion: `Did you mean: ${hint[1]}?` };
 }
+/** The option named in Commander's "unknown option '--x'" message, without an `=value` */
+const UNKNOWN_OPTION = /unknown option '([^'=]+)/;
+/**
+ * The long option of a command closest to a mistyped one, hidden global
+ * options (`--session`, `--quiet`) included. Up to one edit per three letters
+ * of the name counts as a typo, so `--frob` does not suggest `--json`.
+ *
+ * @param flag - Option as typed, e.g. "--sesion"
+ * @param command - Command it was given to
+ * @returns Closest long option, if any is similar
+ */
+function closestOption(flag, command) {
+    const longs = command.options.flatMap((option) => (option.long ? [option.long] : []));
+    const maxDistance = Math.ceil(flag.replace(/^-+/, '').length / 3);
+    return findSimilar(flag, longs, { maxDistance })[0];
+}
+/**
+ * The option as typed, for one Commander split: it reads `-josn` as `-j`
+ * (`--json`) followed by `-osn`, and reports `-osn` as unknown.
+ *
+ * @param flag - Option Commander reported, e.g. "-osn"
+ * @param argv - Process arguments
+ * @returns The argument it came from, e.g. "-josn", else the option itself
+ */
+function typedOption(flag, argv) {
+    if (flag.startsWith('--'))
+        return flag;
+    const rest = flag.slice(1);
+    return (argv.find((arg) => /^-[^-]/.test(arg) && arg.length > flag.length && arg.endsWith(rest)) ?? flag);
+}
+/**
+ * Message and suggestion for a Commander usage error: a did-you-mean for an
+ * unknown option or command, otherwise a pointer to the command's `--help`.
+ * A word typed after a single dash (`-josn`) is matched against the long
+ * options.
+ *
+ * @param error - Commander error (not a help or version display)
+ * @param command - Command the error came from (see resolveCommand)
+ * @param argv - Process arguments (to name an option as typed)
+ * @returns Message and suggestion
+ */
+export function usageErrorDetails(error, command, argv = process.argv) {
+    const help = usageHelpSuggestion(commandPath(command));
+    if (error.code === 'commander.help') {
+        return { message: missingSubcommandMessage(), suggestion: help };
+    }
+    const { message, suggestion } = splitCommanderHint(error.message);
+    const flag = error.code === 'commander.unknownOption' && UNKNOWN_OPTION.exec(message)?.[1];
+    if (!flag)
+        return { message, suggestion: suggestion ?? help };
+    const typed = typedOption(flag, argv);
+    const closest = closestOption(/^-[^-]../.test(typed) ? `-${typed}` : typed, command);
+    return {
+        message: message.replace(`'${flag}'`, `'${typed}'`),
+        suggestion: closest ? `Did you mean: ${closest}?` : help,
+    };
+}
 //# sourceMappingURL=helpTopic.js.map

package/dist/commands/installSkill.d.ts

@@ -1,16 +1,26 @@
 import type { Command } from 'commander';
+import { CommandError } from '../errors/index.js';
 import type { InstalledSkill, SkillTarget } from '../types.js';
+/** What installing the skill did, and why it failed for a target, if it did */
+export interface SkillInstallResult {
+    /** Targets the skill was installed for (or left unchanged) */
+    skills: InstalledSkill[];
+    /** Error (82) for the targets that could not be written */
+    failure?: CommandError;
+}
 /**
- * Copy the bdg skill into each target's skill directory, overwriting an
- * older copy.
+ * Copy the bdg skill into each target's skill directory. A copy that differs
+ * (an older version, or one the user edited) is kept as `SKILL.md.bak`
+ * before it is overwritten. A target that cannot be written does not stop
+ * the others.
  *
  * @param targets - Agents to install for
  * @param home - Home directory the skill roots are relative to
  * @param source - SKILL.md to copy
- * @returns One entry per target, in the given order
- * @throws CommandError when the source is missing (83) or a write fails (82)
+ * @returns The targets written, in the given order, and the failure if any
+ * @throws CommandError when the source is missing (83)
  */
-export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): InstalledSkill[];
+export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): SkillInstallResult;
 /**
  * Register the install-skill command.
  *

package/dist/commands/installSkill.js

@@ -1,14 +1,17 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
 import { runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
 import { CommandError } from '../errors/index.js';
 import { skillSourceMissingError, skillWriteFailedError } from '../errors/messages.js';
-import { formatInstalledSkills } from '../ui/formatters/installSkill.js';
+import { formatInstalledSkills, formatSkillTargets } from '../ui/formatters/installSkill.js';
+import { createLogger } from '../ui/logging/index.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { safeRemoveFile } from '../utils/file.js';
 import { PACKAGE_ROOT } from '../utils/packageRoot.js';
+const log = createLogger('bdg');
 /** The skill shipped with the package (also used by agents working in this repo). */
 const SKILL_SOURCE_PATH = join(PACKAGE_ROOT, '.claude', 'skills', 'bdg', 'SKILL.md');
 /** Skill roots, relative to the home directory, of the agents the skill is installed for. */
@@ -17,14 +20,16 @@ const SKILL_ROOTS = {
     agents: join('.agents', 'skills'),
 };
 /**
- * Copy the bdg skill into each target's skill directory, overwriting an
- * older copy.
+ * Copy the bdg skill into each target's skill directory. A copy that differs
+ * (an older version, or one the user edited) is kept as `SKILL.md.bak`
+ * before it is overwritten. A target that cannot be written does not stop
+ * the others.
  *
  * @param targets - Agents to install for
  * @param home - Home directory the skill roots are relative to
  * @param source - SKILL.md to copy
- * @returns One entry per target, in the given order
- * @throws CommandError when the source is missing (83) or a write fails (82)
+ * @returns The targets written, in the given order, and the failure if any
+ * @throws CommandError when the source is missing (83)
  */
 export function installSkill(targets, home = homedir(), source = SKILL_SOURCE_PATH) {
     if (!existsSync(source)) {
@@ -32,31 +37,76 @@ export function installSkill(targets, home = homedir(), source = SKILL_SOURCE_PA
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
     }
     const content = readFileSync(source, 'utf-8');
-    return targets.map((target) => writeSkill(target, join(home, SKILL_ROOTS[target], 'bdg', 'SKILL.md'), content));
+    const skills = [];
+    const failures = [];
+    for (const target of targets) {
+        const result = writeSkill(target, join(home, SKILL_ROOTS[target], 'bdg', 'SKILL.md'), content);
+        if ('error' in result)
+            failures.push(result);
+        else
+            skills.push(result);
+    }
+    if (failures.length === 0)
+        return { skills };
+    return { skills, failure: skillFailureError(failures, targets) };
+}
+/**
+ * The error for targets the skill could not be written for. When only one of
+ * several targets failed, it suggests installing for the other only. Each
+ * distinct suggestion is kept, so every failure cause gets its fix.
+ *
+ * @param failures - Targets that failed (at least one)
+ * @param targets - Targets picked
+ * @returns Command error (82)
+ */
+function skillFailureError(failures, targets) {
+    const other = failures.length === 1 ? targets.find((t) => t !== failures[0]?.target) : undefined;
+    const errors = failures.map(({ path, error }) => {
+        const code = error.code;
+        return skillWriteFailedError(path, getErrorMessage(error), code === 'ENOTDIR' || code === 'EEXIST', other && `--${other}`);
+    });
+    return new CommandError(errors.map((err) => err.message).join('\n'), { suggestion: [...new Set(errors.map((err) => err.suggestion))].join('\n') }, EXIT_CODES.PERMISSION_DENIED);
 }
 /**
- * Write the skill to one path unless it already holds the same content.
+ * Write the skill to one path unless it already holds the same content; a
+ * different copy is first kept next to it as `SKILL.md.bak` (replacing an
+ * earlier backup), so edits to it are not lost. The new text is written to a
+ * temporary file first, so a failed write leaves both the copy and the
+ * backup as they were; the backup gets the default file mode, whatever the
+ * copy's was.
  *
  * @param target - Agent the path belongs to
  * @param path - Destination SKILL.md
  * @param content - Skill text
- * @returns What happened to the file
- * @throws CommandError (82) when the directory or file cannot be written
+ * @returns What happened to the file, with the backup path when one was made,
+ *   or the file that could not be written and why
  */
 function writeSkill(target, path, content) {
     const existing = existsSync(path) ? readFileSync(path, 'utf-8') : undefined;
     if (existing === content) {
         return { target, path, status: 'unchanged' };
     }
+    const backup = existing === undefined ? undefined : `${path}.bak`;
+    const temporary = `${path}.tmp`;
+    let writing = path;
     try {
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, content);
+        writeFileSync(temporary, content);
+        if (backup !== undefined) {
+            writing = backup;
+            rmSync(backup, { force: true });
+            writeFileSync(backup, existing ?? '');
+        }
+        writing = path;
+        renameSync(temporary, path);
     }
-    catch (caught) {
-        const err = skillWriteFailedError(path, getErrorMessage(caught));
-        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.PERMISSION_DENIED);
+    catch (error) {
+        safeRemoveFile(temporary, 'temporary skill copy', log);
+        return { target, path: writing, error };
     }
-    return { target, path, status: existing === undefined ? 'installed' : 'updated' };
+    if (backup === undefined)
+        return { target, path, status: 'installed' };
+    return { target, path, status: 'updated', backup };
 }
 /**
  * Targets picked by the flags; no flag means every agent.
@@ -68,6 +118,26 @@ function selectedTargets(options) {
     const picked = Object.keys(SKILL_ROOTS).filter((target) => options[target]);
     return picked.length > 0 ? picked : Object.keys(SKILL_ROOTS);
 }
+/**
+ * Install the skill for the picked targets. When a target fails, the error
+ * still lists the targets that were written (and their backups): JSON
+ * `skills`, or the same lines as a successful install.
+ *
+ * @param options - Parsed command options
+ * @returns Command result
+ */
+function installSkillResult(options) {
+    const { skills, failure } = installSkill(selectedTargets(options));
+    if (!failure)
+        return { success: true, data: { skills } };
+    const written = skills.length === 0 ? {} : options.json ? { skills } : { written: formatSkillTargets(skills) };
+    return {
+        success: false,
+        error: failure.message,
+        exitCode: failure.exitCode,
+        errorContext: { ...written, ...failure.metadata },
+    };
+}
 /**
  * Register the install-skill command.
  *
@@ -81,7 +151,7 @@ export function registerInstallSkillCommand(program) {
         .option('--agents', 'Only ~/.agents/skills (Codex, Gemini CLI and other agents)')
         .addOption(jsonOption())
         .action(async (options) => {
-        await runCommand((opts) => Promise.resolve({ success: true, data: { skills: installSkill(selectedTargets(opts)) } }), options, formatInstalledSkills);
+        await runCommand((opts) => Promise.resolve(installSkillResult(opts)), options, formatInstalledSkills);
     });
 }
 //# sourceMappingURL=installSkill.js.map

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';
@@ -116,7 +117,8 @@ function buildFormatOptions(options, result, lastLimit) {
 /**
  * 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.
  *
  * @param options - Command options
  * @param resourceTypes - Validated resource types
@@ -124,6 +126,7 @@ function buildFormatOptions(options, result, lastLimit) {
  */
 async function runFollowMode(options, resourceTypes, lastN) {
     const shown = new Set();
+    const newCrash = newPageCrashes();
     let started = false;
     const showNetwork = async () => {
         const result = await fetchNetworkRequests(filtersNeedHeaders(options));
@@ -131,25 +134,28 @@ 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 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) {
                 const data = {
                     requests: fresh,
-                    totalCount: result.data.length,
+                    totalCount: requests.length,
                     filteredCount: fresh.length,
+                    ...(crashedAt !== undefined && { pageCrashedAt: crashedAt }),
                 };
-                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,
@@ -157,6 +163,8 @@ async function runFollowMode(options, resourceTypes, lastN) {
             });
             if (text)
                 console.log(text);
+            if (crashedAt !== undefined)
+                console.log(pageCrashedNote(crashedAt));
         }
         started = true;
         return undefined;
@@ -219,18 +227,20 @@ 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 } = 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 }),
                 },
             };
-        }, 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.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.
  *
@@ -73,12 +75,12 @@ 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 returns 1000 (dom query) or all of them (dom a11y query)',
         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',
+        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; a page can have hundreds of links',
     },
     'eval:--frame': {
@@ -97,16 +99,16 @@ const OPTION_BEHAVIORS = {
         automaticBehavior: 'Page navigations create new "navigation contexts" - default filters to latest context',
     },
     'console:-l': {
-        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:--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 +128,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 +147,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 +217,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 +230,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',
@@ -297,15 +299,35 @@ const OPTION_BEHAVIORS = {
     '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',
+        automaticBehavior: FOLLOW_BEHAVIOR,
     },
     '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:-f': {
+        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:-f': {
+        default: 'Lists the requests captured so far and exits',
+        whenEnabled: 'Streams requests as they finish',
+        automaticBehavior: FOLLOW_BEHAVIOR,
     },
     'peek:-v': {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',
     },
+    'start:--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)',
+    },
+    'start:--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)',
+    },
     'start:--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)',

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

package/dist/commands/shared/daemonErrorHandler.js

@@ -4,7 +4,7 @@
 import { sessionUnavailableSuggestion } from '../../errors/messages.js';
 import { genericError } from '../../errors/messages.js';
 import { OutputBuilder } from '../../ui/OutputBuilder.js';
-import { connectionLostRetryMessage, connectionLostStopHintMessage, } from '../../ui/messages/preview.js';
+import { connectionLostRetryMessage, connectionLostStopHintMessage, followedSessionEndedMessage, } from '../../ui/messages/preview.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /** Follow-mode state: whether a session ever answered, and whether its loss was reported */
 const followState = { connected: false, lossReported: false };
@@ -20,8 +20,11 @@ export function noteFollowConnected() {
  * 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
@@ -29,22 +32,30 @@ export function noteFollowConnected() {
  */
 export function handleDaemonConnectionError(error, options) {
     const { json = false, follow = false, retryIntervalMs = 1000, exitCode = EXIT_CODES.RESOURCE_NOT_FOUND, } = options;
-    const exits = !follow || !followState.connected;
-    if (exits || !followState.lossReported) {
+    const sessionGone = exitCode === EXIT_CODES.RESOURCE_NOT_FOUND;
+    const exits = !follow || !followState.connected || sessionGone;
+    const message = follow && followState.connected && sessionGone ? followedSessionEndedMessage() : error;
+    if (exits || json || !followState.lossReported) {
         if (json) {
             const suggestion = exits ? sessionUnavailableSuggestion(exitCode) : undefined;
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error, { exitCode, ...(suggestion && { suggestion }) }), null, 2));
+            const envelope = OutputBuilder.buildJsonError(message, {
+                exitCode,
+                ...(suggestion && { suggestion }),
+            });
+            console.log(follow ? JSON.stringify(envelope) : JSON.stringify(envelope, null, 2));
         }
         else {
-            console.error(genericError(error));
+            console.error(genericError(message));
         }
     }
     if (exits)
         return { shouldExit: true, exitCode };
     if (!followState.lossReported) {
         const retryMessage = retryIntervalMs >= 1000 ? `${retryIntervalMs / 1000}s` : `${retryIntervalMs}ms`;
-        console.error(connectionLostRetryMessage(new Date().toISOString(), retryMessage));
-        console.error(connectionLostStopHintMessage());
+        if (!json) {
+            console.error(connectionLostRetryMessage(new Date().toISOString(), retryMessage));
+            console.error(connectionLostStopHintMessage());
+        }
         followState.lossReported = true;
     }
     return { shouldExit: false };

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

@@ -47,18 +47,26 @@ export declare function fetchPreviewData(query?: PreviewQuery): Promise<FetchRes
  * Fetch all captured network requests from daemon.
  *
  * @param withHeaders - Include request/response headers (needed by header filters)
- * @returns Requests or a fetch error
+ * @returns Requests, and when the page crashed (while it is not loaded
+ *   again), or a fetch error
  */
-export declare function fetchNetworkRequests(withHeaders?: boolean): Promise<FetchResult<NetworkRequest[]>>;
+export declare function fetchNetworkRequests(withHeaders?: boolean): Promise<FetchResult<{
+    requests: NetworkRequest[];
+    pageCrashedAt: number | undefined;
+}>>;
 /**
  * Fetch all console messages from daemon.
  *
- * @returns Messages (with their session-wide index) and the navigation id of
- *   the page currently loaded
+ * @returns Messages (with their session-wide index), the navigation id of
+ *   the page currently loaded, how many of the oldest messages the session
+ *   dropped at its limit and when the page crashed (while it is not loaded
+ *   again)
  */
 export declare function fetchConsoleMessages(): Promise<FetchResult<{
     messages: ConsoleMessage[];
     currentNavigationId: number | undefined;
+    dropped: number;
+    pageCrashedAt: number | undefined;
 }>>;
 interface ErrorResult {
     success: false;