browser-debugger-cli 0.8.0 → 0.9.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/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.

package/dist/ui/messages/session.js

@@ -4,54 +4,58 @@
  * 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';
 /**
  * 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 +70,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.

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,12 @@
  * @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>;
 //# sourceMappingURL=async.d.ts.map

package/dist/utils/async.js

@@ -9,4 +9,23 @@
 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);
+    }
+}
 //# sourceMappingURL=async.js.map

package/dist/utils/http.d.ts

@@ -30,13 +30,34 @@ 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[]>;
+/**
+ * What answers on a DevTools HTTP endpoint: a Chrome (with its browser-level
+ * WebSocket URL), an HTTP server that is not DevTools, or nothing.
+ */
+export type DevToolsProbe = {
+    kind: 'devtools';
+    wsUrl: string;
+} | {
+    kind: 'not-devtools';
+} | {
+    kind: 'unreachable';
+};
+/**
+ * Ask an endpoint for its DevTools version (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns What answered
+ */
+export declare function probeDevToolsEndpoint(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): 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
- * @returns The URL, or null if Chrome could not be reached
+ * @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>;
 /**

package/dist/utils/http.js

@@ -63,26 +63,45 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger, options)
     }
 }
 /**
- * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
+ * Ask an endpoint for its DevTools version (`/json/version`).
  *
  * @param port - Chrome debugging port
  * @param logger - Optional logger for debug output
  * @param options - Host and HTTPS
- * @returns The URL, or null if Chrome could not be reached
+ * @returns What answered
  */
-export async function fetchBrowserWsUrl(port, logger, options) {
+export async function probeDevToolsEndpoint(port, logger, options) {
     const url = `${options?.secure ? 'https' : 'http'}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
+    let response;
     try {
-        const response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
-        if (!response.ok)
-            return null;
-        const data = (await response.json());
-        return typeof data.webSocketDebuggerUrl === 'string' ? data.webSocketDebuggerUrl : null;
+        response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
     }
     catch (error) {
         logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
-        return null;
+        return { kind: 'unreachable' };
+    }
+    try {
+        const data = (await response.json());
+        const wsUrl = data?.webSocketDebuggerUrl;
+        if (response.ok && typeof wsUrl === 'string')
+            return { kind: 'devtools', wsUrl };
+    }
+    catch (error) {
+        logger?.debug(`Chrome version response is not JSON: ${getErrorMessage(error)} (${url})`);
     }
+    return { kind: 'not-devtools' };
+}
+/**
+ * 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
+ * @returns The URL, or null if no Chrome answered
+ */
+export async function fetchBrowserWsUrl(port, logger, options) {
+    const probe = await probeDevToolsEndpoint(port, logger, options);
+    return probe.kind === 'devtools' ? probe.wsUrl : null;
 }
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.

package/dist/utils/selectorFilters.d.ts

@@ -3,12 +3,16 @@
  * `:visible`.
  *
  * They are not CSS, so the selector is split here (in Node) into the CSS the
- * browser runs and the filters the page applies to its matches. They are only
- * supported at the end of the last compound of each selector in a list
- * (`li.item:has-text("x"):visible`, `a:text-is("Home"), button:visible`):
- * there they narrow down the elements the CSS part matched. Anywhere else
- * (`div:has-text("x") > button`, `:not(:visible)`) they would have to be
- * evaluated inside the browser's selector matching, which bdg cannot do.
+ * browser runs and the filters the page applies to its matches. A filter
+ * applies to the compound it is written in (`li.item:has-text("x"):visible`,
+ * `a:visible.active`). On the last compound it narrows down the matches; on an
+ * earlier one it scopes the rest of the selector, which is then matched under
+ * each element passing the filter: `li:has-text("Buy milk") .toggle` is the
+ * `.toggle` inside the row that says "Buy milk". Only descendant and child
+ * combinators can follow a filtered compound. Inside `:has()` filters test
+ * what an element contains (`li:has(label:text-is("x"))`); inside other
+ * pseudo-classes (`:not(:visible)`) they would have to be evaluated by the
+ * browser's selector matching, which bdg cannot do.
  */
 /** Filter applied in the page to the elements the CSS part matched. */
 export type SelectorFilter = {
@@ -19,11 +23,27 @@ export type SelectorFilter = {
     text: string;
 } | {
     kind: 'visible';
+} | {
+    kind: 'has';
+    selectors: ScopedStep[][];
 };
-/** One selector of a selector list: the CSS to run and the filters for its matches. */
+/** Combinators a scoped step can follow: descendant (` `) and child (`>`). */
+export type ScopeCombinator = ' ' | '>';
+/** CSS matched under a scope element (`:scope <combinator> <css>`), then filtered. */
+export interface ScopedStep {
+    combinator: ScopeCombinator;
+    css: string;
+    filters: SelectorFilter[];
+}
+/**
+ * One selector of a selector list: the CSS to run and the filters for its
+ * matches; `steps` (when a filtered compound is not the last) are matched
+ * under each of them in turn, and the last step's matches are the result.
+ */
 export interface SelectorPart {
     css: string;
     filters: SelectorFilter[];
+    steps?: ScopedStep[];
 }
 /**
  * Split a selector into the CSS part and filters of each selector of its
@@ -31,9 +51,17 @@ export interface SelectorPart {
  *
  * @param selector - Selector as the user gave it
  * @returns The parts, or null for plain CSS (no filters anywhere), which runs unchanged
- * @throws CommandError (81) for a filter that is not at the end, or a malformed one
+ * @throws CommandError (81) for a misplaced or malformed filter
  */
 export declare function parseSelectorFilters(selector: string): SelectorPart[] | null;
+/**
+ * The parts with every `:visible` filter removed, to count what only
+ * visibility excluded.
+ *
+ * @param parts - Parsed selector parts
+ * @returns Parts without `:visible`, or null when they have none
+ */
+export declare function withoutVisibleFilters(parts: SelectorPart[]): SelectorPart[] | null;
 /**
  * Split a selector list at its top-level commas (not inside quotes,
  * attribute brackets or parentheses).