browser-debugger-cli 0.11.0 → 0.12.0

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

@@ -6,6 +6,7 @@ import { registerFormInteractionCommands } from './commands/dom/formInteraction.
 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';
@@ -39,6 +40,7 @@ export const commandRegistry = [
     registerDomCommands,
     registerFormInteractionCommands,
     registerPageCommands,
+    registerCssCommands,
     addCommandGroup('CDP Commands:'),
     registerCdpCommand,
     addCommandGroup('Network Commands:'),

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 }),

package/dist/daemon/session/plugins.js

@@ -4,6 +4,7 @@ import { prepareDOMCollection } from '../../telemetry/dom.js';
 import { startNavigationTracking } from '../../telemetry/navigation.js';
 import { startNetworkCollection, startWebSocketCollection } from '../../telemetry/network.js';
 import { getErrorMessage } from '../../utils/errors.js';
+import { hideHeadlessUserAgent } from '../../runtime/page/userAgent.js';
 import { filterDefined } from '../../utils/objects.js';
 /** Delay before reading the title after a same-document navigation */
 const TITLE_REFRESH_DELAY_MS = 300;
@@ -83,56 +84,6 @@ async function emulatePageFocus(cdp, logger) {
         .send('Emulation.setFocusEmulationEnabled', { enabled: true })
         .catch((error) => logger.debug(`No focus emulation: ${getErrorMessage(error)}`));
 }
-/** Reads the client hints Chrome reports, renaming the HeadlessChrome brand */
-const USER_AGENT_METADATA_SCRIPT = `(async () => {
-  const data = navigator.userAgentData;
-  if (!data) return null;
-  const values = await data.getHighEntropyValues(
-    ['architecture', 'bitness', 'model', 'platformVersion', 'fullVersionList', 'wow64']
-  );
-  const rename = (list) => (list || []).map((entry) => ({
-    brand: entry.brand.replace('HeadlessChrome', 'Google Chrome'),
-    version: entry.version,
-  }));
-  return {
-    brands: rename(values.brands),
-    fullVersionList: rename(values.fullVersionList),
-    platform: values.platform,
-    platformVersion: values.platformVersion,
-    architecture: values.architecture,
-    model: values.model,
-    mobile: values.mobile,
-    bitness: values.bitness,
-    wow64: values.wow64,
-  };
-})()`;
-/**
- * Send the user agent and client hints of regular Chrome from headless
- * Chrome: sites serve "HeadlessChrome" a different page (or a bot
- * challenge), so the page would not be the one a user sees.
- *
- * @param cdp - CDP connection
- * @param logger - Logger for failures (the session works without it)
- */
-async function hideHeadlessUserAgent(cdp, logger) {
-    try {
-        const { userAgent } = (await cdp.send('Browser.getVersion'));
-        if (!userAgent.includes('HeadlessChrome'))
-            return;
-        const metadata = (await cdp.send('Runtime.evaluate', {
-            expression: USER_AGENT_METADATA_SCRIPT,
-            awaitPromise: true,
-            returnByValue: true,
-        }));
-        await cdp.send('Emulation.setUserAgentOverride', {
-            userAgent: userAgent.replace('HeadlessChrome', 'Chrome'),
-            ...(metadata.result?.value ? { userAgentMetadata: metadata.result.value } : {}),
-        });
-    }
-    catch (error) {
-        logger.debug(`User agent left as is: ${getErrorMessage(error)}`);
-    }
-}
 export function createDefaultTelemetryPlugins() {
     return [
         {
@@ -145,9 +96,10 @@ export function createDefaultTelemetryPlugins() {
         {
             name: 'page-identity',
             runAlways: true,
-            async start({ cdp, logger }) {
+            async start({ cdp, logger, config }) {
                 await emulatePageFocus(cdp, logger);
-                await hideHeadlessUserAgent(cdp, logger);
+                if (!config.viewport?.mobile)
+                    await hideHeadlessUserAgent(cdp, logger);
                 return () => undefined;
             },
         },