browser-debugger-cli 0.11.0 → 0.13.0

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

@@ -10,13 +10,15 @@ import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from './dom/scree
 /** 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';
+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, with "(+N more)" and moreMessages for the rest; 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 click and pressKey report when the page was still changing as they returned */
 const STILL_CHANGING_BEHAVIOR = 'When the page was still changing as the action returned, the status line says (page still changing), a note below it says what was pending and suggests bdg dom wait <selector>, and JSON has settled: false with pending { requests (document, fetch/XHR and script requests still running), navigation (a new page still loading), loading (a loading indicator that appeared, e.g. "div#loading"), domChanging (DOM changes kept coming in bursts over a second look 250 ms later; a single render, ticking text and style animations do not count), busy (the page did not answer within 250 ms: a long script) }; absent when the page looked settled (exit code stays 0). A result a timer renders later, with no DOM change, request or loading indicator before it, is not detected. Cost: nothing extra, except 250 ms plus one read when the DOM looked busy. Not checked with --no-wait';
 /** What hover and pressKey report about elements they showed */
 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.
  *
@@ -25,8 +27,12 @@ const NO_WAIT_TRIGGERED_REQUESTS = 'Returns immediately without waiting for netw
 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',
+        whenEnabled: 'Captures one element; the selector (or a query index) can also be given as the second argument: bdg dom screenshot out.png "#sel". With --index it picks that match of the selector (--selector ".item" --index 2). A positional and an option naming different elements exits 81',
+        automaticBehavior: "The capture covers the border box plus what overflows it: uncleared floats, positioned children, text past a tight line height, and the element's own box shadows and outline (a focus ring); 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. An element smaller than the viewport is scrolled into view for the capture and the page scroll put back afterwards; a larger one is captured with the page laid out at its width without scrollbars, so it does not shift",
+    },
+    'screenshot:--padding': {
+        default: 'The element capture is its painted area (border box, overflowing content, shadows, outline)',
+        whenEnabled: 'Adds that many CSS px of the page around the element capture on every side (0-500); without an element it exits 81',
     },
     'screenshot:--no-resize': {
         default: `Images auto-resized to max ${MAX_EDGE_PX}px longest edge for Claude Vision optimization (~1,600 tokens)`,
@@ -69,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': {
@@ -93,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': {
@@ -122,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': {
@@ -141,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)',
@@ -208,22 +214,28 @@ const OPTION_BEHAVIORS = {
         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)',
     },
+    '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). 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': {
         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',
+        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 first element painted above it at the center of the largest visible box that paints there (the background of a sticky header rather than the transparent logo on it; inside a shadow host, what its shadow root paints), else the topmost one with coverTransparent (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?"',
     },
     'inspect:--index': {
         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',
@@ -286,16 +298,36 @@ const OPTION_BEHAVIORS = {
     },
     'peek:-f': {
         default: 'Shows snapshot of current data',
-        whenEnabled: 'Continuous monitoring - refreshes every second (like tail -f)',
+        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 - refreshes every second (like tail -f)',
+        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)',
@@ -326,6 +358,11 @@ const OPTION_BEHAVIORS = {
         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 (emulated 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81',
     },
+    'bdg:--mobile': {
+        default: 'A desktop viewport: classic scrollbars take ~15px of the width, no touch, a desktop user agent',
+        whenEnabled: 'Emulates a phone for the whole session: a mobile viewport (390x844 unless --viewport) at pixel ratio 3 with mobile layout (meta viewport, overlay scrollbars, so 100vw fits), touch (pointer: coarse, maxTouchPoints 5) and an Android Chrome user agent with mobile client hints; bdg page emulate --mobile turns it on mid-session, --viewport WxH without --mobile or --reset turns it off',
+        automaticBehavior: 'Screenshots keep the mobile layout and are taken at pixel ratio 1 (CSS px = image px); bdg status shows "(emulated 390x844, phone)"',
+    },
     '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',

package/dist/commands/page.js

@@ -5,7 +5,7 @@
 import { Option } from 'commander';
 import { noActiveSessionError, runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
-import { parseColorScheme, parseViewport } from './start.js';
+import { parseColorScheme, requestedViewport } from './start.js';
 import { CommandError } from '../errors/index.js';
 import { javascriptNavigationError } from '../errors/messages.js';
 import { getStatus, pageEmulate, pageNavigate } from '../ipc/client.js';
@@ -127,12 +127,13 @@ async function showPageInfo(options) {
 function emulationRequest(options) {
     if (options.reset)
         return { reset: true };
-    if (options.viewport === undefined && options.colorScheme === undefined) {
+    if (options.viewport === undefined && options.colorScheme === undefined && !options.mobile) {
         const err = pageEmulateNothingError();
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
+    const viewport = requestedViewport(options.viewport, options.mobile);
     return {
-        ...(options.viewport !== undefined && { viewport: parseViewport(options.viewport) }),
+        ...(viewport && { viewport }),
         ...(options.colorScheme !== undefined && {
             colorScheme: parseColorScheme(options.colorScheme),
         }),
@@ -188,11 +189,13 @@ export function registerPageCommands(program) {
     page
         .command('emulate')
         .description(PAGE_EMULATE_DESCRIPTION)
-        .option('--viewport <WxH>', 'Viewport size in CSS px, e.g. 900x700')
+        .option('--viewport <WxH>', 'Viewport size in CSS px, e.g. 900x700 (a desktop one unless --mobile)')
         .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme: light or dark')
+        .option('--mobile', 'Emulate a phone: mobile viewport (390x844 unless --viewport), touch, mobile user agent')
         .addOption(new Option('--reset', 'Back to the browser window size and the system setting').conflicts([
         'viewport',
         'colorScheme',
+        'mobile',
     ]))
         .addOption(jsonOption())
         .action(async (options) => {

package/dist/commands/peek.d.ts

@@ -2,5 +2,12 @@
  * Peek command for previewing collected session data.
  */
 import type { Command } from 'commander';
+import type { PeekCommandOptions } from './shared/optionTypes.js';
+/**
+ * Watch the session data (`peek --follow`, and the deprecated `tail`).
+ *
+ * @param options - Peek options (follow implied)
+ */
+export declare function followPreview(options: PeekCommandOptions): Promise<void>;
 export declare function registerPeekCommand(program: Command): void;
 //# sourceMappingURL=peek.d.ts.map