browser-debugger-cli 0.15.0 → 0.16.0

package/dist/ui/formatting.d.ts

@@ -83,4 +83,11 @@ export declare function truncateUrl(url: string, maxLength?: number): string;
 export declare function cutMiddle(text: string, maxLength: number): string;
 export declare function pluralize(count: number, singular: string, plural?: string): string;
 export declare function formatDuration(ms: number): string;
+/**
+ * Format a byte count for humans.
+ *
+ * @param bytes - Byte count
+ * @returns e.g. "512 B", "12.3 KB"
+ */
+export declare function formatBytes(bytes: number): string;
 //# sourceMappingURL=formatting.d.ts.map

package/dist/ui/formatting.js

@@ -216,4 +216,17 @@ export function formatDuration(ms) {
     }
     return `${ms}ms`;
 }
+/**
+ * Format a byte count for humans.
+ *
+ * @param bytes - Byte count
+ * @returns e.g. "512 B", "12.3 KB"
+ */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    return bytes < 1024 * 1024
+        ? `${(bytes / 1024).toFixed(1)} KB`
+        : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
 //# sourceMappingURL=formatting.js.map

package/dist/ui/logging/logger.d.ts

@@ -29,7 +29,7 @@ export type LogLevel = 'info' | 'debug';
  * Log contexts for different components.
  * Used to prefix log messages with component name.
  */
-export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'navigation' | 'page-crash' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher' | 'targets';
+export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'downloads' | 'navigation' | 'page-crash' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher' | 'targets';
 /**
  * Logger instance with support for different log levels.
  */

package/dist/ui/messages/chrome.d.ts

@@ -26,6 +26,8 @@ export declare function formatChromeNotice(notice: NoticeDetails<ChromeNoticeCod
  * @returns User-facing message
  */
 export declare function formatChromeIssue(issue: IssueDetails, diagnostics?: () => ChromeDiagnostics): string;
+/** Chrome's launch ended because the session was stopped meanwhile */
+export declare const CHROME_LAUNCH_ABORTED_MESSAGE = "Chrome launch aborted: the session was stopped";
 /**
  * Chrome exited before its debugging port opened.
  *
@@ -188,6 +190,17 @@ export declare function portTakenByReason(answeredBy: 'browser' | 'process' | 'n
  * @returns Reason for the CHROME_LAUNCH_FAILED issue
  */
 export declare function chromeNotAnsweringReason(port: number, waitedMs: number): string;
+/**
+ * Chrome is running but did not open its debugging port within
+ * chrome-launcher's readiness budget (a slow start, not a crash or a port
+ * conflict: nothing answered on the port, which was free before the launch).
+ *
+ * @param pid - Chrome's PID
+ * @param port - Debugging port
+ * @param waitedMs - The readiness budget
+ * @returns Error message
+ */
+export declare function chromePortNotOpenedMessage(pid: number, port: number, waitedMs: number): string;
 /**
  * Warning when bdg's Chrome preferences (password manager and leak check
  * off, etc.) could not be written into the profile.

package/dist/ui/messages/chrome.js

@@ -62,6 +62,8 @@ export function formatChromeIssue(issue, diagnostics = getChromeDiagnostics) {
                 return joinLines(header, '', ...diagnosticLines);
             return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnosticLines, '', 'Try:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('bdg <url>')}`);
         }
+        case 'CHROME_PORT_NOT_OPENED':
+            return joinLines(chromePortNotOpenedMessage(ctx['pid'], ctx['port'], ctx['waitedMs']), chromePortNotOpenedSuggestion());
         case 'CHROME_EXITED_DURING_STARTUP':
             return chromeExitedDuringStartupError(ctx['exitCode'], ctx['output'] ?? [], ctx['userDataDir'], ctx['profileInUse'] === true);
         case 'NO_PAGE_TARGET_FOUND':
@@ -86,6 +88,8 @@ export function formatChromeIssue(issue, diagnostics = getChromeDiagnostics) {
             return `Chrome preferences must be JSON-serializable: ${ctx['reason'] ?? 'unknown error'}`;
     }
 }
+/** Chrome's launch ended because the session was stopped meanwhile */
+export const CHROME_LAUNCH_ABORTED_MESSAGE = 'Chrome launch aborted: the session was stopped';
 /**
  * Chrome exited before its debugging port opened.
  *
@@ -345,6 +349,28 @@ export function portTakenByReason(answeredBy, chromeHost) {
 export function chromeNotAnsweringReason(port, waitedMs) {
     return `Chrome announced port ${port} but did not answer on 127.0.0.1 within ${(waitedMs / 1000).toFixed(1)}s (slow start)`;
 }
+/**
+ * Chrome is running but did not open its debugging port within
+ * chrome-launcher's readiness budget (a slow start, not a crash or a port
+ * conflict: nothing answered on the port, which was free before the launch).
+ *
+ * @param pid - Chrome's PID
+ * @param port - Debugging port
+ * @param waitedMs - The readiness budget
+ * @returns Error message
+ */
+export function chromePortNotOpenedMessage(pid, port, waitedMs) {
+    return `Chrome started (pid ${pid}) but did not open its debugging port ${port} within ${Number((waitedMs / 1000).toFixed(1))} s`;
+}
+/**
+ * What to do when Chrome started but did not open its debugging port in time.
+ *
+ * @returns Suggestion
+ */
+function chromePortNotOpenedSuggestion() {
+    return (`Retry: ${sessionCommand('bdg <url>')} (a first start on a cold machine can be slow). ` +
+        `If it keeps failing: ${sessionCommand('bdg cleanup')} && ${sessionCommand('bdg <url>')}`);
+}
 /**
  * Warning when bdg's Chrome preferences (password manager and leak check
  * off, etc.) could not be written into the profile.

package/dist/ui/messages/commands.d.ts

@@ -5,7 +5,7 @@
  * cleaning up stale files, and validating command arguments.
  */
 import type { DomFrame, PageLoadingState, PendingRequestInfo } from '../../ipc/protocol/commands.js';
-import type { ElementLayout, FillValueMismatch, LayoutSize, NewMessage, PageLayout, PageNavigation, PendingChanges, ShownElement } from '../../ipc/protocol/domTypes.js';
+import type { DownloadInfo, ElementLayout, FillValueMismatch, LayoutSize, NewMessage, PageLayout, PageNavigation, PendingChanges, ShownElement } from '../../ipc/protocol/domTypes.js';
 import type { InspectVisibility } from '../../ipc/protocol/inspectTypes.js';
 import type { DelegationNote } from '../../runtime/dom/listenerSummary.js';
 import type { WaitCondition, WaitSnapshot } from '../../runtime/dom/waitCondition.js';
@@ -40,6 +40,34 @@ export declare function skillBackupMessage(path: string): string;
 export declare function domClickFallbackWarning(reason: string | null | undefined): string;
 /** Reason of a `bdg dom form` blocker for a required field left empty */
 export declare const REQUIRED_FIELD_EMPTY_REASON = "Required field is empty";
+/**
+ * Warning for a `bdg cdp` method the bundled protocol lacks, sent anyway.
+ *
+ * @param method - Method sent
+ * @param protocolVersion - Bundled devtools-protocol version
+ * @returns Warning text
+ */
+export declare function cdpUnlistedMethodWarning(method: string, protocolVersion: string): string;
+/**
+ * `bdg cdp --describe` line for a redirect to a method the protocol lacks
+ * (e.g. Page.deleteCookie names Network.deleteCookie).
+ *
+ * @param method - Redirect target
+ * @returns Line text
+ */
+export declare function cdpUnresolvedRedirectLine(method: string): string;
+/**
+ * `bdg cdp --describe` title of a redirect to a method the protocol has.
+ *
+ * @param method - Redirect target
+ * @returns Title text
+ */
+export declare function cdpRedirectTitle(method: string): string;
+/**
+ * Lines of `bdg cdp --help` saying how names are matched (each short
+ * enough not to be wrapped).
+ */
+export declare const CDP_EXECUTION_HELP: string;
 /**
  * Part of the `bdg dom form` summary naming the required fields left empty.
  *
@@ -101,6 +129,38 @@ export declare function shownElementText(element: ShownElement): string;
  *   "URL changed to https://example.com/#/active (same document)"
  */
 export declare function pageNavigationText(navigation: PageNavigation): string;
+/**
+ * A download an action started, as its output line reads.
+ *
+ * @param download - Download
+ * @returns e.g. `Download: report.txt → /Users/me/.bdg/downloads/report.txt (completed, 15 B)`,
+ *   `Download: big.zip → … (inProgress, 9.8 KB so far)` (no size before the first
+ *   bytes), `Download: report.txt (canceled)`
+ */
+export declare function downloadText(download: DownloadInfo): string;
+/**
+ * The session's downloads in one line: how many, and the last one.
+ *
+ * @param downloads - Downloads, oldest first (at least one)
+ * @returns e.g. `2 (last: report.txt → /Users/me/.bdg/downloads/report.txt, completed)`
+ */
+export declare function downloadsSummary(downloads: DownloadInfo[]): string;
+/**
+ * Warning while Chrome did not take bdg's download behavior, so downloads
+ * are not saved in the session directory.
+ *
+ * @param detail - Chrome's error
+ * @returns Warning shown by `bdg status`
+ */
+export declare function downloadsNotRedirectedWarning(detail: string): string;
+/**
+ * Why downloads are refused when the session's downloads directory could not
+ * be created.
+ *
+ * @param detail - What went wrong, e.g. `/home/me/.bdg/downloads is a file`
+ * @returns Reason recorded on each refused download
+ */
+export declare function downloadsDirUnavailableReason(detail: string): string;
 /**
  * Last `New text:` row when an action made more messages appear than are listed.
  *
@@ -748,9 +808,17 @@ export declare function sessionFilesCleanedMessage(): string;
  */
 export declare function sessionOutputRemovedMessage(): string;
 /**
- * Generate session directory clean message.
+ * Cleanup left the session's downloaded files in place.
  *
- * @returns Formatted success message
+ * @param dir - Downloads directory
+ * @param files - Files in it
+ * @returns e.g. `Downloads kept: 2 files in /Users/me/.bdg/downloads (delete them yourself when done)`
+ */
+export declare function downloadsKeptMessage(dir: string, files: number): string;
+/**
+ * Cleanup finished and left nothing behind.
+ *
+ * @returns Message
  */
 export declare function sessionDirectoryCleanMessage(): string;
 /**

package/dist/ui/messages/commands.js

@@ -5,7 +5,7 @@
  * cleaning up stale files, and validating command arguments.
  */
 import { buildAgentDiscoveryHelp, buildCommonTaskExamples, buildUrlExamples, buildSessionManagementReminder, } from '../formatters/helpFormatters.js';
-import { formatDuration, joinLines, pluralize, truncateUrl } from '../formatting.js';
+import { formatBytes, formatDuration, joinLines, pluralize, truncateUrl } from '../formatting.js';
 import { sessionCommand } from './sessionCommand.js';
 import { truncateByLength } from '../../utils/strings.js';
 /**
@@ -60,6 +60,41 @@ function fieldLabelList(labels) {
         .join(', ');
     return labels.length > 5 ? `${shown} and ${labels.length - 5} more` : shown;
 }
+/**
+ * Warning for a `bdg cdp` method the bundled protocol lacks, sent anyway.
+ *
+ * @param method - Method sent
+ * @param protocolVersion - Bundled devtools-protocol version
+ * @returns Warning text
+ */
+export function cdpUnlistedMethodWarning(method, protocolVersion) {
+    return `${method} is not in the bundled protocol (devtools-protocol ${protocolVersion}); sending it to Chrome as is`;
+}
+/**
+ * `bdg cdp --describe` line for a redirect to a method the protocol lacks
+ * (e.g. Page.deleteCookie names Network.deleteCookie).
+ *
+ * @param method - Redirect target
+ * @returns Line text
+ */
+export function cdpUnresolvedRedirectLine(method) {
+    return `Redirect target ${method} is not in the protocol (unresolved redirect)`;
+}
+/**
+ * `bdg cdp --describe` title of a redirect to a method the protocol has.
+ *
+ * @param method - Redirect target
+ * @returns Title text
+ */
+export function cdpRedirectTitle(method) {
+    return `Implemented by ${method} (redirect)`;
+}
+/**
+ * Lines of `bdg cdp --help` saying how names are matched (each short
+ * enough not to be wrapped).
+ */
+export const CDP_EXECUTION_HELP = '  Execution: bundled methods are case-insensitive (network.getcookies works)\n' +
+    '  Other methods are sent as typed (case-sensitive)';
 /**
  * Part of the `bdg dom form` summary naming the required fields left empty.
  *
@@ -145,6 +180,56 @@ export function pageNavigationText(navigation) {
     const status = navigation.status === undefined ? '' : ` (${navigation.status})`;
     return `navigated to ${navigation.url}${status}`;
 }
+/**
+ * A download an action started, as its output line reads.
+ *
+ * @param download - Download
+ * @returns e.g. `Download: report.txt → /Users/me/.bdg/downloads/report.txt (completed, 15 B)`,
+ *   `Download: big.zip → … (inProgress, 9.8 KB so far)` (no size before the first
+ *   bytes), `Download: report.txt (canceled)`
+ */
+export function downloadText(download) {
+    const where = download.path === undefined ? '' : ` → ${download.path}`;
+    const running = download.state === 'inProgress';
+    const bytes = download.bytes === undefined || (running && download.bytes === 0)
+        ? ''
+        : `, ${formatBytes(download.bytes)}${running ? ' so far' : ''}`;
+    const reason = download.reason === undefined ? '' : `: ${download.reason}`;
+    return `Download: ${download.suggestedFilename}${where} (${download.state}${bytes}${reason})`;
+}
+/**
+ * The session's downloads in one line: how many, and the last one.
+ *
+ * @param downloads - Downloads, oldest first (at least one)
+ * @returns e.g. `2 (last: report.txt → /Users/me/.bdg/downloads/report.txt, completed)`
+ */
+export function downloadsSummary(downloads) {
+    const last = downloads[downloads.length - 1];
+    if (!last)
+        return '0';
+    const where = last.path === undefined ? '' : ` → ${last.path}`;
+    return `${downloads.length} (last: ${last.suggestedFilename}${where}, ${last.state})`;
+}
+/**
+ * Warning while Chrome did not take bdg's download behavior, so downloads
+ * are not saved in the session directory.
+ *
+ * @param detail - Chrome's error
+ * @returns Warning shown by `bdg status`
+ */
+export function downloadsNotRedirectedWarning(detail) {
+    return `downloads are not redirected to the session directory (Chrome refused the download behavior: ${detail}); Chrome saves them in its default folder, usually ~/Downloads`;
+}
+/**
+ * Why downloads are refused when the session's downloads directory could not
+ * be created.
+ *
+ * @param detail - What went wrong, e.g. `/home/me/.bdg/downloads is a file`
+ * @returns Reason recorded on each refused download
+ */
+export function downloadsDirUnavailableReason(detail) {
+    return `bdg's downloads directory could not be created (${detail}), so downloads are refused`;
+}
 /**
  * Last `New text:` row when an action made more messages appear than are listed.
  *
@@ -1161,9 +1246,19 @@ export function sessionOutputRemovedMessage() {
     return 'Session output file removed';
 }
 /**
- * Generate session directory clean message.
+ * Cleanup left the session's downloaded files in place.
  *
- * @returns Formatted success message
+ * @param dir - Downloads directory
+ * @param files - Files in it
+ * @returns e.g. `Downloads kept: 2 files in /Users/me/.bdg/downloads (delete them yourself when done)`
+ */
+export function downloadsKeptMessage(dir, files) {
+    return `Downloads kept: ${pluralize(files, 'file')} in ${dir} (delete them yourself when done)`;
+}
+/**
+ * Cleanup finished and left nothing behind.
+ *
+ * @returns Message
  */
 export function sessionDirectoryCleanMessage() {
     return 'Session directory is now clean';

package/dist/ui/messages/networkMessages.d.ts

@@ -4,23 +4,42 @@
  * User-facing messages for the network list command output and formatting.
  */
 /**
- * Why a stored response body was replaced by a placeholder (shown by
- * `bdg details network <id>` as `bodyNotCaptured`).
+ * Why a stored request or response body was replaced by a placeholder
+ * (shown by `bdg details network <id>` as `requestBodyNotCaptured` or
+ * `bodyNotCaptured`).
  *
  * @param budgetBytes - Total body budget of the session
- * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of response bodies)`
+ * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of request and response bodies)`
  */
 export declare function bodyEvictedReason(budgetBytes: number): string;
+/**
+ * Why a response body is missing when Chrome no longer had it
+ * (`Network.getResponseBody` failed with "No resource with given identifier
+ * found" or "No data found for resource with given identifier"), shown by
+ * `bdg details network <id>` as `bodyNotCaptured` and in the HAR as the
+ * content comment.
+ *
+ * @returns Reason text
+ */
+export declare function bodyGoneReason(): string;
+/**
+ * Why a response body is missing when `Network.getResponseBody` failed for
+ * another reason (a CDP timeout, the connection closing mid-fetch).
+ *
+ * @param errorMessage - The error Chrome or the connection gave
+ * @returns e.g. `Chrome did not return the body: CDP command timeout`
+ */
+export declare function bodyFetchFailedReason(errorMessage: string): string;
 /** What a session's network capture let go at its limits */
 export interface NetworkEvictionCounts {
     /** Oldest finished requests dropped at the request cap */
     requestsDropped: number;
-    /** Oldest response bodies evicted at the body budget */
+    /** Oldest request and response bodies evicted at the body budget */
     bodiesEvicted: number;
 }
 /**
  * Note that the session dropped its oldest requests or evicted its oldest
- * response bodies at its limits.
+ * request and response bodies at its limits.
  *
  * @param counts - Requests dropped and bodies evicted
  * @returns e.g. `⚠ 2000 older network requests were dropped: bdg keeps the newest 10000`;

package/dist/ui/messages/networkMessages.js

@@ -15,18 +15,41 @@ function megabytes(bytes) {
     return `${Math.round(bytes / (1024 * 1024))} MB`;
 }
 /**
- * Why a stored response body was replaced by a placeholder (shown by
- * `bdg details network <id>` as `bodyNotCaptured`).
+ * Why a stored request or response body was replaced by a placeholder
+ * (shown by `bdg details network <id>` as `requestBodyNotCaptured` or
+ * `bodyNotCaptured`).
  *
  * @param budgetBytes - Total body budget of the session
- * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of response bodies)`
+ * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of request and response bodies)`
  */
 export function bodyEvictedReason(budgetBytes) {
-    return `evicted: total body budget (bdg keeps the newest ${megabytes(budgetBytes)} of response bodies)`;
+    return `evicted: total body budget (bdg keeps the newest ${megabytes(budgetBytes)} of request and response bodies)`;
+}
+/**
+ * Why a response body is missing when Chrome no longer had it
+ * (`Network.getResponseBody` failed with "No resource with given identifier
+ * found" or "No data found for resource with given identifier"), shown by
+ * `bdg details network <id>` as `bodyNotCaptured` and in the HAR as the
+ * content comment.
+ *
+ * @returns Reason text
+ */
+export function bodyGoneReason() {
+    return 'Chrome no longer had the body (its network buffer evicted it, or the request was cancelled)';
+}
+/**
+ * Why a response body is missing when `Network.getResponseBody` failed for
+ * another reason (a CDP timeout, the connection closing mid-fetch).
+ *
+ * @param errorMessage - The error Chrome or the connection gave
+ * @returns e.g. `Chrome did not return the body: CDP command timeout`
+ */
+export function bodyFetchFailedReason(errorMessage) {
+    return `Chrome did not return the body: ${errorMessage}`;
 }
 /**
  * Note that the session dropped its oldest requests or evicted its oldest
- * response bodies at its limits.
+ * request and response bodies at its limits.
  *
  * @param counts - Requests dropped and bodies evicted
  * @returns e.g. `⚠ 2000 older network requests were dropped: bdg keeps the newest 10000`;
@@ -35,7 +58,7 @@ export function bodyEvictedReason(budgetBytes) {
 export function networkEvictedNote(counts) {
     const { requestsDropped, bodiesEvicted } = counts;
     const requests = pluralize(requestsDropped, 'older network request');
-    const bodies = pluralize(bodiesEvicted, 'older response body', 'older response bodies');
+    const bodies = pluralize(bodiesEvicted, 'older request/response body', 'older request/response bodies');
     const budget = megabytes(MAX_TOTAL_BODY_BYTES);
     if (requestsDropped > 0 && bodiesEvicted > 0) {
         return `⚠ ${requests} dropped, ${bodies} evicted: bdg keeps the newest ${MAX_NETWORK_REQUESTS} requests and ${budget} of bodies`;
@@ -88,7 +111,7 @@ export function localProxyNote() {
  * @returns Comment naming what was redacted and the flag that keeps it
  */
 export function harSanitizedComment() {
-    return 'Sanitized by bdg: values of auth, cookie, API key, token and session headers, cookies, credential query parameters in URLs, and password/token fields of request bodies are [redacted] (by name, so some harmless values are too); response bodies and WebSocket messages are not sanitized. Export with --include-sensitive to keep everything';
+    return 'Sanitized by bdg: values of auth, cookie, API key, token and session headers, cookies, credential query parameters in URLs, password/token/secret fields of JSON and form request and response bodies and WebSocket messages (also truncated JSON, JSON encoded in strings, socket.io, SockJS, server-sent events, NDJSON, and base64 bodies and binary messages that are UTF-8 text), and any JWT (also inside longer strings and form values) are [redacted] in place (by name, so some harmless values are too); everything else stays byte for byte. Not sanitized: other binary data, text that is not JSON or a form, and non-JSON syntax (single quotes, unquoted keys, JSONP, bare values with spaces); a body that could not be sanitized is [redacted] whole. Export with --include-sensitive to keep everything';
 }
 /**
  * Success message of `bdg network har`.
@@ -99,7 +122,7 @@ export function harSanitizedComment() {
 export function harExportedMessage(result) {
     const filterNote = result.filtered ? ' (filtered)' : '';
     const note = result.sanitized
-        ? 'Credentials sanitized (auth/cookie/API key/token headers, cookies, URL tokens, password and token body fields are [redacted]); --include-sensitive keeps them'
+        ? 'Credentials sanitized (auth/cookie/API key/token headers, cookies, URL tokens, password and token fields of bodies and WebSocket messages are [redacted]); --include-sensitive keeps them'
         : '⚠ Includes credentials (--include-sensitive): share this file with care';
     return `✓ Exported ${result.entries} requests${filterNote} to ${result.file}\n  ${note}`;
 }

package/dist/utils/async.d.ts

@@ -2,11 +2,12 @@
  * Async utilities for common patterns.
  */
 /**
- * Delay execution for a specified duration.
+ * Delay execution for a specified duration, ending early when `signal` aborts.
  *
  * @param ms - Milliseconds to delay
+ * @param signal - Optional abort signal (the delay resolves, not rejects, on abort)
  */
-export declare function delay(ms: number): Promise<void>;
+export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
 /**
  * Wait for a promise, giving up after a time; the timer is cleared either way.
  *

package/dist/utils/async.js

@@ -2,12 +2,25 @@
  * Async utilities for common patterns.
  */
 /**
- * Delay execution for a specified duration.
+ * Delay execution for a specified duration, ending early when `signal` aborts.
  *
  * @param ms - Milliseconds to delay
+ * @param signal - Optional abort signal (the delay resolves, not rejects, on abort)
  */
-export function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
 }
 /**
  * Wait for a promise, giving up after a time; the timer is cleared either way.

package/dist/utils/http.d.ts

@@ -37,6 +37,13 @@ export interface FetchCDPTargetsOptions {
  * - Network errors are logged to help diagnose Chrome connectivity issues
  */
 export declare function fetchCDPTargets(port?: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<CDPTarget[]>;
+/**
+ * Options for a DevTools endpoint probe.
+ */
+export interface DevToolsProbeOptions extends FetchCDPTargetsOptions {
+    /** Ends a pending request early (the probe then reports `unreachable`) */
+    signal?: AbortSignal | undefined;
+}
 /**
  * What answers on a DevTools HTTP endpoint: a Chrome (with its browser-level
  * WebSocket URL), an HTTP server that is not DevTools, or nothing.
@@ -54,19 +61,19 @@ export type DevToolsProbe = {
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host, HTTPS and request timeout
+ * @param options - Host, HTTPS, request timeout and abort signal
  * @returns What answered
  */
-export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<DevToolsProbe>;
+export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: DevToolsProbeOptions): Promise<DevToolsProbe>;
 /**
  * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host and HTTPS
+ * @param options - Host, HTTPS and abort signal
  * @returns The URL, or null if no Chrome answered
  */
-export declare function fetchBrowserWsUrl(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<string | null>;
+export declare function fetchBrowserWsUrl(port: number, logger?: Logger, options?: Pick<DevToolsProbeOptions, 'host' | 'secure' | 'signal'>): Promise<string | null>;
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.
  *

package/dist/utils/http.js

@@ -67,15 +67,17 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger, options)
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host, HTTPS and request timeout
+ * @param options - Host, HTTPS, request timeout and abort signal
  * @returns What answered
  */
 export async function probeDevToolsEndpoint(port, logger, options) {
     const url = `${options?.secure ? 'https' : 'http'}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
     const timeoutMs = options?.timeoutMs ?? CDP_HTTP_TIMEOUT_MS;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = options?.signal ? AbortSignal.any([timeout, options.signal]) : timeout;
     let response;
     try {
-        response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        response = await fetch(url, { signal });
     }
     catch (error) {
         logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
@@ -97,7 +99,7 @@ export async function probeDevToolsEndpoint(port, logger, options) {
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
- * @param options - Host and HTTPS
+ * @param options - Host, HTTPS and abort signal
  * @returns The URL, or null if no Chrome answered
  */
 export async function fetchBrowserWsUrl(port, logger, options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "browser-debugger-cli",
-  "version": "0.15.0",
-  "description": "DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.",
+  "version": "0.16.0",
+  "description": "Let Claude Code and other coding agents drive and debug Chrome from the shell. DOM, network, console and raw CDP as short commands, no screenshots and no MCP needed.",
   "type": "module",
   "bin": {
     "bdg": "dist/index.js"
@@ -37,10 +37,24 @@
   "keywords": [
     "cdp",
     "chrome-devtools-protocol",
+    "chrome",
+    "devtools",
+    "debugging",
     "browser",
-    "telemetry",
+    "browser-automation",
+    "headless-chrome",
     "cli",
-    "devtools"
+    "claude",
+    "claude-code",
+    "coding-agent",
+    "ai-agent",
+    "agent-skill",
+    "codex",
+    "css",
+    "figma",
+    "telemetry",
+    "puppeteer-alternative",
+    "playwright-alternative"
   ],
   "license": "MIT",
   "dependencies": {