browser-debugger-cli 0.8.0 → 0.10.0

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

@@ -3,6 +3,7 @@
  *
  * User-facing messages for the console command output and formatting.
  */
+import type { ConsoleSkipped } from '../formatters/console/shared.js';
 /**
  * Generate message for following console output.
  *
@@ -15,4 +16,13 @@ export declare function followingConsoleMessage(): string;
  * @returns Status message for stderr
  */
 export declare function stoppedFollowingConsoleMessage(): string;
+/**
+ * Note under a console list whose indices skip messages: the indices are
+ * positions in the session's message list (what `bdg details console <n>`
+ * takes), and the messages in between were left out by the filters.
+ *
+ * @param skipped - Messages left out between the first and last listed index
+ * @returns e.g. `[n] are positions in the session's message list; not listed in between: 1 message from another page load (-H lists all)`
+ */
+export declare function consoleIndexGapNote(skipped: ConsoleSkipped): string;
 //# sourceMappingURL=consoleMessages.d.ts.map

package/dist/ui/messages/consoleMessages.js

@@ -3,6 +3,7 @@
  *
  * User-facing messages for the console command output and formatting.
  */
+import { pluralize } from '../formatting.js';
 /**
  * Generate message for following console output.
  *
@@ -19,4 +20,20 @@ export function followingConsoleMessage() {
 export function stoppedFollowingConsoleMessage() {
     return 'Stopped streaming console messages';
 }
+/**
+ * Note under a console list whose indices skip messages: the indices are
+ * positions in the session's message list (what `bdg details console <n>`
+ * takes), and the messages in between were left out by the filters.
+ *
+ * @param skipped - Messages left out between the first and last listed index
+ * @returns e.g. `[n] are positions in the session's message list; not listed in between: 1 message from another page load (-H lists all)`
+ */
+export function consoleIndexGapNote(skipped) {
+    const reasons = [
+        skipped.otherLevels > 0 && `${pluralize(skipped.otherLevels, 'message')} of another level`,
+        skipped.otherPages > 0 &&
+            `${pluralize(skipped.otherPages, 'message')} from another page load (-H lists all)`,
+    ].filter(Boolean);
+    return `[n] are positions in the session's message list; not listed in between: ${reasons.join(', ')}`;
+}
 //# sourceMappingURL=consoleMessages.js.map

package/dist/ui/messages/hints.js

@@ -6,6 +6,7 @@
  * session stays free of UI imports.
  */
 import { joinLines } from '../formatting.js';
+import { sessionCommand } from './sessionCommand.js';
 /**
  * Format a structured hint into a user-facing string.
  *
@@ -19,7 +20,7 @@ export function formatHint(hint) {
         case 'PATTERN_HINT': {
             const alternative = ctx['alternative'];
             const cdpMethods = ctx['cdpMethods'] ?? [];
-            return joinLines('', `Hint: Consider using '${alternative}' instead of ${cdpMethods.join(' or ')}`, '');
+            return joinLines('', `Hint: Consider using '${sessionCommand(alternative)}' instead of ${cdpMethods.join(' or ')}`, '');
         }
     }
 }

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

@@ -15,4 +15,18 @@ export declare function followingNetworkMessage(): string;
  * @returns Status message for stderr
  */
 export declare function stoppedFollowingNetworkMessage(): string;
+/**
+ * Note after a header value the server sent more than once.
+ *
+ * @param count - Times it was sent
+ * @returns e.g. `(sent 2 times)`
+ */
+export declare function headerRepeatedNote(count: number): string;
+/**
+ * Note after a loopback remote address of a request to another host and
+ * port: Chrome probably connected to a proxy on this machine, not the server.
+ *
+ * @returns Note text
+ */
+export declare function localProxyNote(): string;
 //# sourceMappingURL=networkMessages.d.ts.map

package/dist/ui/messages/networkMessages.js

@@ -19,4 +19,22 @@ export function followingNetworkMessage() {
 export function stoppedFollowingNetworkMessage() {
     return '\nStopped following network requests.';
 }
+/**
+ * Note after a header value the server sent more than once.
+ *
+ * @param count - Times it was sent
+ * @returns e.g. `(sent 2 times)`
+ */
+export function headerRepeatedNote(count) {
+    return `(sent ${count} times)`;
+}
+/**
+ * Note after a loopback remote address of a request to another host and
+ * port: Chrome probably connected to a proxy on this machine, not the server.
+ *
+ * @returns Note text
+ */
+export function localProxyNote() {
+    return '(loopback; likely a local proxy)';
+}
 //# sourceMappingURL=networkMessages.js.map

package/dist/ui/messages/preview.js

@@ -4,6 +4,7 @@
  * User-facing messages for the peek command, including empty states,
  * tips, and interactive command suggestions.
  * */
+import { sessionCommand } from './sessionCommand.js';
 export const PREVIEW_EMPTY_STATES = {
     NO_DATA: '(none)',
     NO_NETWORK_REQUESTS: 'No network requests yet',
@@ -18,7 +19,7 @@ export const PREVIEW_HEADERS = {
  * @returns Single-line tip for basic peek usage
  */
 export function compactTipsMessage() {
-    return 'Tip: bdg peek --last 50 | bdg peek --verbose';
+    return `Tip: ${sessionCommand('bdg peek --last 50')} | ${sessionCommand('bdg peek --verbose')}`;
 }
 /**
  * Generate verbose mode commands section.
@@ -28,9 +29,9 @@ export function compactTipsMessage() {
 export function verboseCommandsMessage() {
     return [
         'Commands:',
-        '  Full preview:    bdg peek --last 50',
-        '  Watch live:      bdg tail',
-        '  End session:     bdg stop',
+        `  Full preview:    ${sessionCommand('bdg peek --last 50')}`,
+        `  Watch live:      ${sessionCommand('bdg tail')}`,
+        `  End session:     ${sessionCommand('bdg stop')}`,
     ].join('\n');
 }
 /**

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

@@ -4,6 +4,7 @@
  * Centralized location for all session UI text including landing pages,
  * status displays, and session management messages.
  */
+import type { PageLoadingState } from '../../ipc/protocol/commands.js';
 /**
  * Options for the landing page display.
  */
@@ -12,41 +13,37 @@ export interface LandingPageOptions {
     url: string;
     /** HTTP status of the main document (a warning is shown for 4xx/5xx) */
     documentStatus?: number;
+    /** The page had not finished loading (a warning names what it waits on) */
+    loading?: PageLoadingState;
     /** When `--timeout` will stop the session */
     autoStopAt?: Date;
+    /** Name of a named session (`--session`) */
+    session?: string;
 }
 /**
  * Lines shown under the target in both the full and the quiet start output:
- * an HTTP error of the page, and when the session stops by itself.
+ * the session name, an HTTP error of the page, a page still loading, and
+ * when the session stops by itself.
  *
  * @param options - Landing page options
  * @returns Lines (empty when there is nothing to say)
  */
 export declare function startNotices(options: LandingPageOptions): string[];
 /**
- * Generate the landing page display for session start.
- *
- * Shows a clean, organized overview of available commands grouped by priority.
- * High-level commands are presented first to guide agents toward token-efficient
- * wrappers before falling back to verbose CDP commands.
- *
- * Section order optimized for agent discoverability:
- * 1. Common tasks with token savings estimates
- * 2. Comprehensive domain command coverage (12+ commands)
- * 3. Live monitoring capabilities
- * 4. Session management
- * 5. Advanced CDP access (positioned as fallback)
- * 6. Discovery resources for agents
+ * Generate the start output: the target, the notices of {@link startNotices},
+ * one line of next commands and where to find the rest. Kept to a few lines
+ * because agents read it on every start; `bdg --help` lists everything.
  *
  * @param options - Landing page options
- * @returns Formatted landing page string
+ * @returns Formatted start output
  *
  * @example
  * ```typescript
- * const message = landingPage({
- *   url: 'http://localhost:3000'
- * });
- * console.log(message);
+ * landingPage({ url: 'http://localhost:3000' });
+ * // Session Started
+ * // Target: http://localhost:3000
+ * // Next: bdg dom layout <selector>, bdg dom query <selector>, ...
+ * // More: bdg --help (bdg --help --json for agents)
  * ```
  */
 export declare function landingPage(options: LandingPageOptions): string;
@@ -61,9 +58,7 @@ export declare function sessionStopped(): string;
  */
 export declare const STOP_MESSAGES: {
     readonly SUCCESS: "Session stopped successfully";
-    readonly NO_SESSION: "No active session found";
     readonly FAILED: "Failed to stop session";
-    readonly DAEMON_NOT_RUNNING: "No active session";
 };
 /**
  * Generate stop session failed error message.
@@ -82,4 +77,18 @@ export declare function lastSessionEndText(end: {
     reason: string;
     endedAt: number;
 }): string;
+/**
+ * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ *
+ * @param pid - Daemon PID, when known
+ * @param waitedMs - How long bdg waited
+ * @returns Note
+ */
+export declare function daemonStillExitingHint(pid: number | undefined, waitedMs: number): string;
+/**
+ * What to do about a daemon still shutting down after a failed start.
+ *
+ * @returns Suggestion
+ */
+export declare function daemonStillExitingSuggestion(): string;
 //# sourceMappingURL=session.d.ts.map

package/dist/ui/messages/session.js

@@ -4,54 +4,59 @@
  * Centralized location for all session UI text including landing pages,
  * status displays, and session management messages.
  */
-import { buildCommonTasksSection, buildDomainCommandsSection, buildLiveMonitoringSection, buildSessionManagementSection, buildCdpSection, buildDiscoverySection, } from '../formatters/sessionFormatters.js';
 import { joinLines } from '../formatting.js';
+import { pageLoadingWarning } from './commands.js';
+import { sessionCommand } from './sessionCommand.js';
 /**
  * Lines shown under the target in both the full and the quiet start output:
- * an HTTP error of the page, and when the session stops by itself.
+ * the session name, an HTTP error of the page, a page still loading, and
+ * when the session stops by itself.
  *
  * @param options - Landing page options
  * @returns Lines (empty when there is nothing to say)
  */
 export function startNotices(options) {
-    const { documentStatus, autoStopAt } = options;
+    const { documentStatus, loading, autoStopAt, session } = options;
     return [
+        ...(session
+            ? [
+                `Session: ${session} (pass --session ${session} or set BDG_SESSION=${session} on every command)`,
+            ]
+            : []),
         ...(documentStatus !== undefined && documentStatus >= 400
             ? [`⚠ The page responded with HTTP ${documentStatus}`]
             : []),
+        ...(loading ? [`⚠ ${pageLoadingWarning(loading)}`] : []),
         ...(autoStopAt ? [`Auto-stop: at ${autoStopAt.toLocaleTimeString()} (--timeout)`] : []),
     ];
 }
+/** Most useful commands after a start, cheapest first (screenshots cost the most tokens) */
+const START_NEXT_COMMANDS = [
+    'bdg dom layout <selector>',
+    'bdg dom query <selector>',
+    'bdg dom form',
+    'bdg peek',
+    'bdg dom screenshot out.png',
+];
 /**
- * Generate the landing page display for session start.
- *
- * Shows a clean, organized overview of available commands grouped by priority.
- * High-level commands are presented first to guide agents toward token-efficient
- * wrappers before falling back to verbose CDP commands.
- *
- * Section order optimized for agent discoverability:
- * 1. Common tasks with token savings estimates
- * 2. Comprehensive domain command coverage (12+ commands)
- * 3. Live monitoring capabilities
- * 4. Session management
- * 5. Advanced CDP access (positioned as fallback)
- * 6. Discovery resources for agents
+ * Generate the start output: the target, the notices of {@link startNotices},
+ * one line of next commands and where to find the rest. Kept to a few lines
+ * because agents read it on every start; `bdg --help` lists everything.
  *
  * @param options - Landing page options
- * @returns Formatted landing page string
+ * @returns Formatted start output
  *
  * @example
  * ```typescript
- * const message = landingPage({
- *   url: 'http://localhost:3000'
- * });
- * console.log(message);
+ * landingPage({ url: 'http://localhost:3000' });
+ * // Session Started
+ * // Target: http://localhost:3000
+ * // Next: bdg dom layout <selector>, bdg dom query <selector>, ...
+ * // More: bdg --help (bdg --help --json for agents)
  * ```
  */
 export function landingPage(options) {
-    const { url } = options;
-    const notices = startNotices(options);
-    return joinLines('', 'Session Started', '', `Target: ${url}`, '', ...(notices.length > 0 ? [...notices, ''] : []), buildCommonTasksSection(), '', buildDomainCommandsSection(), '', buildLiveMonitoringSection(), '', buildSessionManagementSection(), '', buildCdpSection(), '', buildDiscoverySection(), '');
+    return joinLines('Session Started', `Target: ${options.url}`, ...startNotices(options), `Next: ${START_NEXT_COMMANDS.join(', ')}`, 'More: bdg --help (bdg --help --json for agents)');
 }
 /**
  * Generate "session stopped" success message.
@@ -66,9 +71,7 @@ export function sessionStopped() {
  */
 export const STOP_MESSAGES = {
     SUCCESS: 'Session stopped successfully',
-    NO_SESSION: 'No active session found',
     FAILED: 'Failed to stop session',
-    DAEMON_NOT_RUNNING: 'No active session',
 };
 /**
  * Generate stop session failed error message.
@@ -94,4 +97,23 @@ export function lastSessionEndText(end) {
     const at = new Date(end.endedAt).toLocaleTimeString();
     return `The last session ended at ${at}: ${why[end.reason] ?? end.reason}`;
 }
+/**
+ * Note after a failed start whose daemon had not exited when bdg stopped waiting.
+ *
+ * @param pid - Daemon PID, when known
+ * @param waitedMs - How long bdg waited
+ * @returns Note
+ */
+export function daemonStillExitingHint(pid, waitedMs) {
+    const daemon = pid === undefined ? 'The daemon' : `The daemon (PID ${pid})`;
+    return `${daemon} was still shutting down after ${waitedMs / 1000}s`;
+}
+/**
+ * What to do about a daemon still shutting down after a failed start.
+ *
+ * @returns Suggestion
+ */
+export function daemonStillExitingSuggestion() {
+    return `check with bdg sessions, or end it with ${sessionCommand('bdg cleanup --force')}`;
+}
 //# sourceMappingURL=session.js.map

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

@@ -0,0 +1,43 @@
+/**
+ * bdg command lines and wording for the selected session.
+ *
+ * Every hint, suggestion and error that tells the user to run a bdg command
+ * goes through {@link sessionCommand}, so a named session's hints carry
+ * `--session <name>` and following them never acts on the default session.
+ */
+/**
+ * A bdg command for the selected session: ` --session <name>` is appended
+ * when a named session is selected.
+ *
+ * @param command - Command line, e.g. `bdg stop`
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns The command, scoped to the session
+ *
+ * @example
+ * ```typescript
+ * sessionCommand('bdg stop');            // 'bdg stop' (default session)
+ * sessionCommand('bdg stop', 'agent-1'); // 'bdg stop --session agent-1'
+ * ```
+ */
+export declare function sessionCommand(command: string, session?: string | null): string;
+/**
+ * "No active session", naming a named session.
+ *
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns `No active session` or `No active session "<name>"`
+ */
+export declare function noActiveSessionMessage(session?: string | null): string;
+/**
+ * Shell command that deletes a directory by hand (single-quoted).
+ *
+ * @param dir - Directory
+ * @returns Command line
+ */
+export declare function removeDirCommand(dir: string): string;
+/**
+ * How to start the selected session.
+ *
+ * @returns Suggestion
+ */
+export declare function startSessionSuggestion(): string;
+//# sourceMappingURL=sessionCommand.d.ts.map

package/dist/ui/messages/sessionCommand.js

@@ -0,0 +1,52 @@
+/**
+ * bdg command lines and wording for the selected session.
+ *
+ * Every hint, suggestion and error that tells the user to run a bdg command
+ * goes through {@link sessionCommand}, so a named session's hints carry
+ * `--session <name>` and following them never acts on the default session.
+ */
+import { getSessionName } from '../../session/paths.js';
+/**
+ * A bdg command for the selected session: ` --session <name>` is appended
+ * when a named session is selected.
+ *
+ * @param command - Command line, e.g. `bdg stop`
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns The command, scoped to the session
+ *
+ * @example
+ * ```typescript
+ * sessionCommand('bdg stop');            // 'bdg stop' (default session)
+ * sessionCommand('bdg stop', 'agent-1'); // 'bdg stop --session agent-1'
+ * ```
+ */
+export function sessionCommand(command, session = getSessionName()) {
+    return session === null ? command : `${command} --session ${session}`;
+}
+/**
+ * "No active session", naming a named session.
+ *
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns `No active session` or `No active session "<name>"`
+ */
+export function noActiveSessionMessage(session = getSessionName()) {
+    return session === null ? 'No active session' : `No active session "${session}"`;
+}
+/**
+ * Shell command that deletes a directory by hand (single-quoted).
+ *
+ * @param dir - Directory
+ * @returns Command line
+ */
+export function removeDirCommand(dir) {
+    return `rm -rf '${dir.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * How to start the selected session.
+ *
+ * @returns Suggestion
+ */
+export function startSessionSuggestion() {
+    return `Start a session with: ${sessionCommand('bdg <url>')}`;
+}
+//# sourceMappingURL=sessionCommand.js.map

package/dist/utils/async.d.ts

@@ -7,4 +7,21 @@
  * @param ms - Milliseconds to delay
  */
 export declare function delay(ms: number): Promise<void>;
+/**
+ * Wait for a promise, giving up after a time; the timer is cleared either way.
+ *
+ * @param promise - Work to wait for
+ * @param ms - Milliseconds to wait at most
+ * @returns The promise's result, or undefined when the time ran out first
+ */
+export declare function raceTimeout<T>(promise: Promise<T>, ms: number): Promise<T | undefined>;
+/**
+ * Poll a condition until it holds or a time runs out.
+ *
+ * @param condition - Checked first right away, then every `pollMs`
+ * @param timeoutMs - Milliseconds to wait at most
+ * @param pollMs - Milliseconds between checks
+ * @returns True when the condition held, false when the time ran out
+ */
+export declare function waitUntil(condition: () => boolean, timeoutMs: number, pollMs?: number): Promise<boolean>;
 //# sourceMappingURL=async.d.ts.map

package/dist/utils/async.js

@@ -9,4 +9,40 @@
 export function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Wait for a promise, giving up after a time; the timer is cleared either way.
+ *
+ * @param promise - Work to wait for
+ * @param ms - Milliseconds to wait at most
+ * @returns The promise's result, or undefined when the time ran out first
+ */
+export async function raceTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Poll a condition until it holds or a time runs out.
+ *
+ * @param condition - Checked first right away, then every `pollMs`
+ * @param timeoutMs - Milliseconds to wait at most
+ * @param pollMs - Milliseconds between checks
+ * @returns True when the condition held, false when the time ran out
+ */
+export async function waitUntil(condition, timeoutMs, pollMs = 25) {
+    const deadline = Date.now() + timeoutMs;
+    while (!condition()) {
+        if (Date.now() >= deadline)
+            return false;
+        await delay(Math.min(pollMs, Math.max(0, deadline - Date.now())));
+    }
+    return true;
+}
 //# sourceMappingURL=async.js.map

package/dist/utils/color.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CSS colors as `bdg dom inspect` reports them: parsed from the computed
+ * values Chrome returns (`rgb()`/`rgba()`, and `lab()`, `lch()`, `oklab()`,
+ * `oklch()` and `color()` as Tailwind v4 and other modern CSS leave them),
+ * converted to sRGB the way Chrome paints them on an sRGB screen (channels
+ * outside the gamut are clipped), and printed as short hex. Also the WCAG
+ * contrast math over alpha-composited backgrounds.
+ *
+ * Conversions follow the CSS Color 4 sample code (Bradford D50 → D65, the
+ * OKLab matrices of Björn Ottosson).
+ */
+/** A color in sRGB: channels 0-1 (unclipped until printed), alpha 0-1 */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * Parse a CSS color as Chrome computes it.
+ *
+ * @param value - e.g. `rgba(0, 0, 0, 0.2)`, `oklch(0.373 0.034 259.733)`, `#fff`, `transparent`
+ * @returns The color in sRGB, or null for anything else (`currentcolor`, keywords, gradients)
+ */
+export declare function parseColor(value: string): Rgba | null;
+/**
+ * A color as short hex: `#rgb` when every channel's digits repeat, else
+ * `#rrggbb`; `#rrggbbaa` when translucent; `transparent` at alpha 0.
+ *
+ * @param color - Color in sRGB
+ * @returns e.g. `#fff`, `#364153`, `#00000033`
+ */
+export declare function toHex(color: Rgba): string;
+/**
+ * A computed color as short hex ({@link toHex}).
+ *
+ * @param value - Computed color
+ * @returns Hex, or the value unchanged when it is not a color
+ */
+export declare function hexColor(value: string): string;
+/**
+ * Replace every color inside a value with its hex ({@link toHex}).
+ *
+ * @param value - e.g. `rgba(0, 0, 0, 0.2) 0px 1px 2px 0px`
+ * @returns e.g. `#00000033 0px 1px 2px 0px`
+ */
+export declare function hexColorsIn(value: string): string;
+/**
+ * Paint a color over another (source-over alpha compositing).
+ *
+ * @param top - Color on top
+ * @param bottom - Color below
+ * @returns The color a user sees
+ */
+export declare function composite(top: Rgba, bottom: Rgba): Rgba;
+/**
+ * WCAG relative luminance of an opaque color (clipped to sRGB).
+ *
+ * @param color - Color
+ * @returns Luminance 0-1
+ */
+export declare function relativeLuminance(color: Rgba): number;
+/**
+ * WCAG contrast ratio of text over an opaque background; translucent text
+ * is composited over the background first.
+ *
+ * @param text - Text color
+ * @param background - Opaque background color
+ * @returns Ratio 1-21
+ */
+export declare function contrastRatio(text: Rgba, background: Rgba): number;
+/** WCAG 2 conformance of a contrast ratio */
+export type ContrastLevel = 'AAA' | 'AA' | 'AA large' | 'fail';
+/**
+ * WCAG 2 level a contrast ratio reaches. Large text (24px, or 18.66px bold)
+ * needs 4.5 for AAA and 3 for AA; other text 7 and 4.5.
+ *
+ * @param ratio - Contrast ratio
+ * @param fontSize - Font size in px
+ * @param fontWeight - Font weight
+ * @returns Level reached
+ */
+export declare function contrastLevel(ratio: number, fontSize: number, fontWeight: number): ContrastLevel;
+//# sourceMappingURL=color.d.ts.map