browser-debugger-cli 0.10.0 → 0.12.0

package/dist/commands/installSkill.js

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, readFileSync, 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 { getErrorMessage } from '../utils/errors.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+import { PACKAGE_ROOT } from '../utils/packageRoot.js';
+/** 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. */
+const SKILL_ROOTS = {
+    claude: join('.claude', 'skills'),
+    agents: join('.agents', 'skills'),
+};
+/**
+ * Copy the bdg skill into each target's skill directory, overwriting an
+ * older copy.
+ *
+ * @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)
+ */
+export function installSkill(targets, home = homedir(), source = SKILL_SOURCE_PATH) {
+    if (!existsSync(source)) {
+        const err = skillSourceMissingError(source);
+        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));
+}
+/**
+ * Write the skill to one path unless it already holds the same content.
+ *
+ * @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
+ */
+function writeSkill(target, path, content) {
+    const existing = existsSync(path) ? readFileSync(path, 'utf-8') : undefined;
+    if (existing === content) {
+        return { target, path, status: 'unchanged' };
+    }
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+    }
+    catch (caught) {
+        const err = skillWriteFailedError(path, getErrorMessage(caught));
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.PERMISSION_DENIED);
+    }
+    return { target, path, status: existing === undefined ? 'installed' : 'updated' };
+}
+/**
+ * Targets picked by the flags; no flag means every agent.
+ *
+ * @param options - Parsed command options
+ * @returns Targets to install for
+ */
+function selectedTargets(options) {
+    const picked = Object.keys(SKILL_ROOTS).filter((target) => options[target]);
+    return picked.length > 0 ? picked : Object.keys(SKILL_ROOTS);
+}
+/**
+ * Register the install-skill command.
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export function registerInstallSkillCommand(program) {
+    program
+        .command('install-skill')
+        .description('Install the bdg agent skill for Claude Code (~/.claude/skills) and agents reading ~/.agents/skills (Codex, Gemini CLI, ...); re-run after upgrading bdg')
+        .option('--claude', 'Only ~/.claude/skills (Claude Code)')
+        .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);
+    });
+}
+//# sourceMappingURL=installSkill.js.map

package/dist/commands/optionBehaviors.js

@@ -10,7 +10,7 @@ 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 */
@@ -25,8 +25,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)`,
@@ -208,10 +212,16 @@ 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)',
+        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': {
@@ -286,11 +296,11 @@ 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',
     },
     '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',
     },
     'peek:-v': {
         default: 'Compact output (truncated URLs, no resource types)',
@@ -326,6 +336,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

package/dist/commands/peek.js

@@ -8,9 +8,12 @@ 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 { CommandError } from '../errors/index.js';
+import { intervalWithoutFollowError } from '../errors/messages.js';
 import { filterByResourceType } from '../telemetry/filters.js';
 import { buildPreviewJsonData, formatPreview, } from '../ui/formatters/preview.js';
 import { followingPreviewMessage, stoppedFollowingPreviewMessage } from '../ui/messages/preview.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
 function parseOptions(options) {
     const lastN = positiveIntRule({
         name: '--last',
@@ -20,7 +23,17 @@ function parseOptions(options) {
         allowZeroForAll: true,
     }).validate(options.last);
     const resourceTypes = resourceTypeRule().validate(options.type);
-    return { lastN, resourceTypes };
+    if (options.interval !== undefined && !options.follow) {
+        const err = intervalWithoutFollowError();
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const interval = positiveIntRule({
+        name: '--interval',
+        min: 100,
+        max: 60000,
+        default: 1000,
+    }).validate(options.interval);
+    return { lastN, resourceTypes, interval };
 }
 /**
  * Data section selected by `--network` / `--console`, if any.
@@ -75,11 +88,12 @@ function createPreviewOptions(base, resourceTypes, unfilteredCount) {
     }
     return options;
 }
-async function runFollowMode(options, lastN, resourceTypes, baseOptions) {
+async function runFollowMode(options, parsed, baseOptions) {
+    const { lastN, resourceTypes, interval } = parsed;
     const showPreview = async () => {
         const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
         if (!result.success) {
-            return followFetchFailure(result, { json: options.json, retryIntervalMs: 1000 });
+            return followFetchFailure(result, { json: options.json, retryIntervalMs: interval });
         }
         noteFollowConnected();
         if (!options.json)
@@ -91,9 +105,51 @@ async function runFollowMode(options, lastN, resourceTypes, baseOptions) {
     await setupFollowMode(showPreview, {
         startMessage: followingPreviewMessage,
         stopMessage: stoppedFollowingPreviewMessage,
-        intervalMs: 1000,
+        intervalMs: interval,
     });
 }
+/**
+ * Parse the options, reporting an invalid one and exiting.
+ *
+ * @param options - Peek options
+ * @returns Parsed options
+ */
+function parsePeekOptions(options) {
+    try {
+        return parseOptions(options);
+    }
+    catch (error) {
+        handleValidationError(error, options.json ?? false);
+    }
+}
+/**
+ * How the preview is shown.
+ *
+ * @param options - Peek options
+ * @param lastN - Items to show
+ * @returns Preview options
+ */
+function previewDisplayOptions(options, lastN) {
+    return {
+        json: options.json,
+        network: options.network,
+        console: options.console,
+        last: lastN,
+        verbose: options.verbose,
+        follow: options.follow,
+    };
+}
+/**
+ * Watch the session data (`peek --follow`, and the deprecated `tail`).
+ *
+ * @param options - Peek options (follow implied)
+ */
+export async function followPreview(options) {
+    const following = { ...options, follow: true };
+    showBothSectionsWhenBothRequested(following);
+    const parsed = parsePeekOptions(following);
+    await runFollowMode(following, parsed, previewDisplayOptions(following, parsed.lastN));
+}
 export function registerPeekCommand(program) {
     program
         .command('peek')
@@ -103,6 +159,7 @@ export function registerPeekCommand(program) {
         .option('-n, --network', 'Show only network requests', false)
         .option('-c, --console', 'Show only console messages', false)
         .option('-f, --follow', 'Watch for updates (like tail -f)', false)
+        .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.)')
         .action(async (options) => {
@@ -110,26 +167,11 @@ export function registerPeekCommand(program) {
         if (options.network && !options.json) {
             console.error('Note: "bdg peek --network" is deprecated. Use "bdg network list" for enhanced filtering.');
         }
-        let lastN;
-        let resourceTypes;
-        try {
-            const parsed = parseOptions(options);
-            lastN = parsed.lastN;
-            resourceTypes = parsed.resourceTypes;
-        }
-        catch (error) {
-            handleValidationError(error, options.json ?? false);
-        }
-        const baseOptions = {
-            json: options.json,
-            network: options.network,
-            console: options.console,
-            last: lastN,
-            verbose: options.verbose,
-            follow: options.follow,
-        };
+        const parsed = parsePeekOptions(options);
+        const { lastN, resourceTypes } = parsed;
+        const baseOptions = previewDisplayOptions(options, lastN);
         if (options.follow) {
-            await runFollowMode(options, lastN, resourceTypes, baseOptions);
+            await runFollowMode(options, parsed, baseOptions);
             return;
         }
         await runCommand(async () => {

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

@@ -93,8 +93,10 @@ export interface ScreenshotOptions {
     fullPage?: boolean;
     /** CSS selector for element capture */
     selector?: string;
-    /** Cached element index (0-based) from previous query */
+    /** Cached element index (0-based) from previous query, or with `selector`, which of its matches */
     index?: number;
+    /** Extra space (CSS px) around an element capture */
+    padding?: number;
     /** Continuous capture mode to directory */
     follow?: boolean;
     /** Capture interval in ms for follow mode (string from CLI) */
@@ -373,6 +375,8 @@ export interface PeekCommandOptions extends BaseOptions, PreviewDisplayOptions {
     last?: string;
     /** Filter network requests by resource type (comma-separated) */
     type?: string;
+    /** Refresh interval of --follow in ms (string from CLI, default: 1000) */
+    interval?: string;
 }
 /**
  * Options for tail command.

package/dist/commands/start.d.ts

@@ -26,6 +26,8 @@ export interface CollectorOptions {
     chromeFlags?: string;
     /** Viewport size, e.g. `1280x800`. */
     viewport?: string;
+    /** Emulate a phone (`--mobile`) */
+    mobile?: boolean;
     /** `prefers-color-scheme` to emulate: light or dark. */
     colorScheme?: string;
 }
@@ -53,6 +55,17 @@ export declare function extractUserDataDirFromFlags(flags: string[]): {
  * @returns The modified Command instance with all telemetry options applied
  */
 export declare function applyCollectorOptions(command: Command): Command;
+/** Viewport of `--mobile` without `--viewport` (a common phone, CSS px) */
+export declare const MOBILE_VIEWPORT: ViewportSize;
+/**
+ * The viewport to emulate from `--viewport` and `--mobile`.
+ *
+ * @param viewport - `--viewport` value
+ * @param mobile - `--mobile` was given
+ * @returns Viewport (a phone's with `--mobile`), or undefined for neither
+ * @throws CommandError (81) for an invalid size
+ */
+export declare function requestedViewport(viewport: string | undefined, mobile: boolean | undefined): ViewportSize | undefined;
 /**
  * Parse a `--viewport` value: width and height in CSS px joined by `x`
  * (`1280x800`; `X`, `×` and `,` work too).

package/dist/commands/start.js

@@ -81,7 +81,24 @@ export function applyCollectorOptions(command) {
         .addOption(jsonOption())
         .option('--chrome-flags <flags>', 'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")')
         .option('--viewport <WxH>', 'Viewport size in CSS px for the whole session, e.g. 1280x800 (default: 1920x1080 window)')
-        .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme for the session: light or dark (default: the system setting)');
+        .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme for the session: light or dark (default: the system setting)')
+        .option('--mobile', `Emulate a phone for the session: mobile viewport (${MOBILE_VIEWPORT.width}x${MOBILE_VIEWPORT.height} unless --viewport), touch, mobile user agent`);
+}
+/** Viewport of `--mobile` without `--viewport` (a common phone, CSS px) */
+export const MOBILE_VIEWPORT = { width: 390, height: 844 };
+/**
+ * The viewport to emulate from `--viewport` and `--mobile`.
+ *
+ * @param viewport - `--viewport` value
+ * @param mobile - `--mobile` was given
+ * @returns Viewport (a phone's with `--mobile`), or undefined for neither
+ * @throws CommandError (81) for an invalid size
+ */
+export function requestedViewport(viewport, mobile) {
+    const size = viewport !== undefined ? parseViewport(viewport) : undefined;
+    if (!mobile)
+        return size;
+    return { ...(size ?? MOBILE_VIEWPORT), mobile: true };
 }
 /** Largest viewport side accepted by `--viewport` (CSS px) */
 const MAX_VIEWPORT_SIDE = 10000;
@@ -157,7 +174,7 @@ function buildSessionOptions(options) {
         quiet: options.quiet ?? false,
         json: options.json ?? false,
         chromeFlags,
-        viewport: options.viewport !== undefined ? parseViewport(options.viewport) : undefined,
+        viewport: requestedViewport(options.viewport, options.mobile),
         colorScheme: options.colorScheme !== undefined ? parseColorScheme(options.colorScheme) : undefined,
     };
 }

package/dist/commands/tail.d.ts

@@ -1,6 +1,12 @@
 /**
- * Tail command for continuous session monitoring.
+ * `bdg tail`: deprecated alias of `bdg peek --follow` (#115). It keeps its
+ * options and says to use `peek --follow` instead.
  */
 import type { Command } from 'commander';
+/**
+ * Register the deprecated `tail` command.
+ *
+ * @param program - Root command
+ */
 export declare function registerTailCommand(program: Command): void;
 //# sourceMappingURL=tail.d.ts.map

package/dist/commands/tail.js

@@ -1,43 +1,19 @@
 /**
- * Tail command for continuous session monitoring.
+ * `bdg tail`: deprecated alias of `bdg peek --follow` (#115). It keeps its
+ * options and says to use `peek --follow` instead.
+ */
+import { followPreview } from './peek.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { tailDeprecatedNotice } from '../ui/messages/preview.js';
+/**
+ * Register the deprecated `tail` command.
+ *
+ * @param program - Root command
  */
-import { jsonOption, showBothSectionsWhenBothRequested } from './shared/commonOptions.js';
-import { noteFollowConnected } from './shared/daemonErrorHandler.js';
-import { fetchPreviewOutput } from './shared/dataFetcher.js';
-import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
-import { handleValidationError } from './shared/handleValidationError.js';
-import { MAX_LAST_ITEMS, positiveIntRule } from './shared/validation.js';
-import { formatPreview } from '../ui/formatters/preview.js';
-import { followingPreviewMessage, stoppedFollowingPreviewMessage } from '../ui/messages/preview.js';
-function parseOptions(options) {
-    const lastRule = positiveIntRule({
-        name: '--last',
-        min: 1,
-        max: MAX_LAST_ITEMS,
-        default: 10,
-        allowZeroForAll: true,
-    });
-    const intervalRule = positiveIntRule({ name: '--interval', min: 100, max: 60000, default: 1000 });
-    return {
-        lastN: lastRule.validate(options.last),
-        interval: intervalRule.validate(options.interval),
-    };
-}
-function createPreviewOptions(options, lastN) {
-    return {
-        json: options.json,
-        network: options.network,
-        console: options.console,
-        last: lastN,
-        verbose: options.verbose,
-        follow: true,
-        viewedAt: new Date(),
-    };
-}
 export function registerTailCommand(program) {
     program
         .command('tail')
-        .description('Continuously monitor session data (like tail -f)')
+        .description('Deprecated: use "bdg peek --follow" (same options)')
         .addOption(jsonOption())
         .option('-v, --verbose', 'Use verbose output with full URLs and formatting', false)
         .option('-n, --network', 'Show only network requests', false)
@@ -45,33 +21,8 @@ export function registerTailCommand(program) {
         .option('--last <count>', 'Show last N items (network requests + console messages), 0 for all', '10')
         .option('--interval <ms>', 'Update interval in milliseconds', '1000')
         .action(async (options) => {
-        showBothSectionsWhenBothRequested(options);
-        let lastN;
-        let interval;
-        try {
-            const parsed = parseOptions(options);
-            lastN = parsed.lastN;
-            interval = parsed.interval;
-        }
-        catch (error) {
-            handleValidationError(error, options.json ?? false);
-        }
-        const showPreview = async () => {
-            const result = await fetchPreviewOutput({ lastN });
-            if (!result.success) {
-                return followFetchFailure(result, { json: options.json, retryIntervalMs: interval });
-            }
-            noteFollowConnected();
-            if (!options.json)
-                console.clear();
-            console.log(formatPreview(result.data, createPreviewOptions(options, lastN)));
-            return undefined;
-        };
-        await setupFollowMode(showPreview, {
-            startMessage: followingPreviewMessage,
-            stopMessage: stoppedFollowingPreviewMessage,
-            intervalMs: interval,
-        });
+        console.error(tailDeprecatedNotice());
+        await followPreview({ ...options, follow: true });
     });
 }
 //# sourceMappingURL=tail.js.map

package/dist/commands.js

@@ -4,7 +4,9 @@ import { registerConsoleCommand } from './commands/console.js';
 import { registerDetailsCommand } from './commands/details.js';
 import { registerFormInteractionCommands } from './commands/dom/formInteraction.js';
 import { registerDomCommands } from './commands/dom/index.js';
+import { registerInstallSkillCommand } from './commands/installSkill.js';
 import { registerNetworkCommands } from './commands/network/index.js';
+import { registerCssCommands } from './commands/css.js';
 import { registerPageCommands } from './commands/page.js';
 import { registerPeekCommand } from './commands/peek.js';
 import { registerSessionsCommand } from './commands/sessions.js';
@@ -38,11 +40,14 @@ export const commandRegistry = [
     registerDomCommands,
     registerFormInteractionCommands,
     registerPageCommands,
+    registerCssCommands,
     addCommandGroup('CDP Commands:'),
     registerCdpCommand,
     addCommandGroup('Network Commands:'),
     registerNetworkCommands,
     addCommandGroup('Console Commands:'),
     registerConsoleCommand,
+    addCommandGroup('Agent Setup:'),
+    registerInstallSkillCommand,
 ];
 //# sourceMappingURL=commands.js.map

package/dist/daemon/session/commandRegistry.js

@@ -4,6 +4,8 @@ import { createInteractionRunner } from './interactions.js';
 import { withTriggeredRequestCount } from './triggeredRequests.js';
 import { CommandError } from '../../errors/index.js';
 import { cdpCallError, formDiscoveryFailedError } from '../../errors/messages.js';
+import { searchStyleSheets } from '../../runtime/css/search.js';
+import { auditPage } from '../../runtime/dom/audit.js';
 import { evaluateScript, withBusyPageRecovery } from '../../runtime/dom/evalHelpers.js';
 import { inspectEventListeners } from '../../runtime/dom/eventListeners.js';
 import { FORM_DISCOVERY_SCRIPT, isRawFormData } from '../../runtime/dom/formDiscovery.js';
@@ -458,7 +460,11 @@ export function createCommandRegistry(store, emulation) {
         })), params.wait !== false))),
         dom_listeners: async (cdp, params) => withBusyPageRecovery(cdp, inspectEventListeners(cdp, params)),
         dom_layout: async (cdp, params) => withBusyPageRecovery(cdp, inspectLayout(cdp, params)),
-        dom_inspect: async (cdp, params) => withBusyPageRecovery(cdp, inspectElement(cdp, params)),
+        dom_audit: async (cdp, params) => withBusyPageRecovery(cdp, auditPage(cdp, params)),
+        css_search: async (cdp, params) => searchStyleSheets(cdp, params),
+        dom_inspect: async (cdp, params) => withBusyPageRecovery(cdp, inspectElement(cdp, params).then((result) => result.theme === 'dark' && emulation.get().colorScheme === 'dark'
+            ? { ...result, themeFrom: 'emulation' }
+            : result)),
         dom_wait: async (cdp, params) => waitForCondition(cdp, params),
         page_navigate: async (cdp, params) => interact(cdp, () => navigatePage(cdp, params.action, {
             ...filterDefined({ url: params.url, wait: params.wait }),