browser-debugger-cli 0.8.0 → 0.10.0

package/dist/ipc/client.d.ts

@@ -28,6 +28,7 @@ export declare function connectToDaemon(): Promise<HandshakeResponse>;
  * Request status information from the daemon.
  * Returns daemon state, session metadata, and activity metrics.
  *
+ * @param socketPath - Daemon socket to ask (default: the selected session's)
  * @returns Status response with daemon and session information
  * @throws Error if connection fails or times out
  *
@@ -40,7 +41,7 @@ export declare function connectToDaemon(): Promise<HandshakeResponse>;
  * }
  * ```
  */
-export declare function getStatus(): Promise<StatusResponse>;
+export declare function getStatus(socketPath?: string): Promise<StatusResponse>;
 /**
  * Request preview data from the daemon.
  * Returns snapshot of collected telemetry without stopping session.
@@ -217,8 +218,27 @@ export declare function domScroll(params: NoType<(typeof COMMANDS)['dom_scroll']
  * @returns Where the page is now
  */
 export declare function pageNavigate(params: NoType<(typeof COMMANDS)['page_navigate']['requestSchema']>): Promise<ClientResponse<'page_navigate'>>;
+/**
+ * Change the page emulation (viewport, color scheme) or clear it.
+ *
+ * @param params - What to set, or reset
+ * @returns Emulation and what the page now has
+ */
+export declare function pageEmulate(params: NoType<(typeof COMMANDS)['page_emulate']['requestSchema']>): Promise<ClientResponse<'page_emulate'>>;
 /** Run form discovery and return the raw structured form data. */
 export declare function domFormDiscover(): Promise<ClientResponse<'dom_form_discover'>>;
 /** List the event listeners that run for an element. */
 export declare function domListeners(params: NoType<(typeof COMMANDS)['dom_listeners']['requestSchema']>): Promise<ClientResponse<'dom_listeners'>>;
+/** Positions, sizes and visibility of elements. */
+export declare function domLayout(params: NoType<(typeof COMMANDS)['dom_layout']['requestSchema']>): Promise<ClientResponse<'dom_layout'>>;
+/** What one element looks like: styles, box, layout and child tree. */
+export declare function domInspect(params: NoType<(typeof COMMANDS)['dom_inspect']['requestSchema']>): Promise<ClientResponse<'dom_inspect'>>;
+/**
+ * Wait until elements appear, become visible, contain a text or are gone,
+ * and/or the page has loaded.
+ *
+ * @param params - Condition and timeout
+ * @returns What the page showed once the condition was met
+ */
+export declare function domWait(params: NoType<(typeof COMMANDS)['dom_wait']['requestSchema']>): Promise<ClientResponse<'dom_wait'>>;
 //# sourceMappingURL=client.d.ts.map

package/dist/ipc/client.js

@@ -4,7 +4,7 @@
  * Public API for communicating with the daemon via Unix socket.
  * Provides high-level functions for session lifecycle and queries.
  */
-import { getQuickIPCRequestTimeout } from '../constants.js';
+import { getIPCRequestTimeout, getQuickIPCRequestTimeout } from '../constants.js';
 import { CommandError } from '../errors/index.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { sendRequest } from './transport/index.js';
@@ -42,6 +42,7 @@ async function assertResponsive() {
  * Request status information from the daemon.
  * Returns daemon state, session metadata, and activity metrics.
  *
+ * @param socketPath - Daemon socket to ask (default: the selected session's)
  * @returns Status response with daemon and session information
  * @throws Error if connection fails or times out
  *
@@ -54,9 +55,9 @@ async function assertResponsive() {
  * }
  * ```
  */
-export async function getStatus() {
+export async function getStatus(socketPath) {
     const request = withSession({ type: 'status_request' });
-    return sendRequest(request, 'status', 'status_response', getQuickIPCRequestTimeout());
+    return sendRequest(request, 'status', 'status_response', getQuickIPCRequestTimeout(), socketPath);
 }
 /**
  * Request preview data from the daemon.
@@ -145,6 +146,8 @@ export async function startSession(url, options) {
             headless: options.headless,
             chromeWsUrl: options.chromeWsUrl,
             chromeFlags: options.chromeFlags,
+            viewport: options.viewport,
+            colorScheme: options.colorScheme,
         }),
     });
     await assertResponsive();
@@ -310,6 +313,15 @@ export async function domScroll(params) {
 export async function pageNavigate(params) {
     return sendCommand('page_navigate', params);
 }
+/**
+ * Change the page emulation (viewport, color scheme) or clear it.
+ *
+ * @param params - What to set, or reset
+ * @returns Emulation and what the page now has
+ */
+export async function pageEmulate(params) {
+    return sendCommand('page_emulate', params);
+}
 /** Run form discovery and return the raw structured form data. */
 export async function domFormDiscover() {
     return sendCommand('dom_form_discover', {});
@@ -318,4 +330,24 @@ export async function domFormDiscover() {
 export async function domListeners(params) {
     return sendCommand('dom_listeners', params);
 }
+/** Positions, sizes and visibility of elements. */
+export async function domLayout(params) {
+    return sendCommand('dom_layout', params);
+}
+/** What one element looks like: styles, box, layout and child tree. */
+export async function domInspect(params) {
+    return sendCommand('dom_inspect', params);
+}
+/** Time the client gives `dom wait` beyond its --timeout (the daemon reports the timeout first) */
+const WAIT_IPC_MARGIN_MS = 10_000;
+/**
+ * Wait until elements appear, become visible, contain a text or are gone,
+ * and/or the page has loaded.
+ *
+ * @param params - Condition and timeout
+ * @returns What the page showed once the condition was met
+ */
+export async function domWait(params) {
+    return sendCommand('dom_wait', params, Math.max(getIPCRequestTimeout(), params.timeout + WAIT_IPC_MARGIN_MS));
+}
 //# sourceMappingURL=client.js.map

package/dist/ipc/protocol/commands.d.ts

@@ -5,9 +5,10 @@
  * Each command has a request schema (input) and response data schema (output).
  */
 import type { HintDetails } from '../../errors/notices.js';
-import type { ClickResult, FillResult, ListenersResult, PressKeyResult, RawFormData, ScrollResult, SubmitResult } from './domTypes.js';
+import type { ClickResult, FillResult, LayoutResult, ListenersResult, PressKeyResult, RawFormData, ScrollResult, SubmitResult } from './domTypes.js';
+import type { InspectResult } from './inspectTypes.js';
 import type { PageState, SessionActivity } from '../session/types.js';
-import type { NetworkRequest } from '../../types.js';
+import type { ColorScheme, NetworkRequest, ViewportSize } from '../../types.js';
 /**
  * Session peek command request schema.
  */
@@ -38,6 +39,10 @@ export interface SessionPeekData {
     network: Array<{
         requestId: string;
         timestamp: number;
+        /** Chrome's monotonic time (seconds) when the request was sent */
+        sentTime?: number;
+        /** Main-frame navigation (page load) the request belongs to */
+        navigationId?: number;
         method: string;
         url: string;
         status?: number;
@@ -147,6 +152,14 @@ export interface SessionNetworkHeadersData {
     url: string;
     /** Request ID for correlation with peek output. */
     requestId: string;
+    /** HTTP method. */
+    method?: string;
+    /** HTTP status (0: failed without a response; missing while pending). */
+    status?: number;
+    /** Status text sent by the server (empty for HTTP/2). */
+    statusText?: string;
+    /** Why loading failed, when it did. */
+    errorText?: string;
     /** Request headers. */
     requestHeaders: Record<string, string>;
     /** Response headers. */
@@ -167,7 +180,7 @@ export interface DomEvalData {
     type: string;
     /** Object subtype (node, date, array, ...) */
     subtype?: string;
-    /** URL of the iframe the script ran in (with `frame`) */
+    /** URL of the iframe the script ran in (with `frame`; empty when it has none) */
     frame?: string;
 }
 /** An iframe of the page, as listed by `bdg dom frames` */
@@ -180,12 +193,18 @@ export interface DomFrame {
     name?: string;
     /** `id` attribute of the iframe element */
     id?: string;
-    /** Security origin */
+    /**
+     * Origin the frame's scripts run with: inherited from the parent for
+     * srcdoc and about:blank, `"null"` (opaque) for data: URLs and sandboxes
+     * without allow-same-origin
+     */
     origin: string;
-    /** Origin differs from the page's */
+    /** The page cannot reach its document: the origin differs from the page's, or is opaque */
     crossOrigin: boolean;
     /** Runs in its own renderer process (site isolation) */
     outOfProcess: boolean;
+    /** Index of the frame it is nested in (missing for frames of the page itself) */
+    parentIndex?: number;
 }
 /**
  * dom_frames: list the page's iframes (including nested and out-of-process ones).
@@ -220,6 +239,8 @@ export interface DomClickCommand {
     wait?: boolean;
     /** Double or right click, or only hover (default: click) */
     action?: 'click' | 'double' | 'right' | 'hover';
+    /** Refuse (exit 90) instead of falling back to DOM events when a real mouse can't reach it */
+    strict?: boolean;
 }
 export type DomClickData = ClickResult;
 /**
@@ -276,8 +297,46 @@ export interface DomListenersCommand {
     backendNodeId?: number;
     /** Only these event types (default: all) */
     types?: string[];
+    /** List every listener of framework roots instead of one summary per node */
+    all?: boolean;
 }
 export type DomListenersData = ListenersResult;
+/**
+ * dom_layout: positions, sizes and visibility of elements.
+ */
+export interface DomLayoutCommand {
+    selector: string;
+    /** Only this match (default: every match) */
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+}
+export type DomLayoutData = LayoutResult;
+/**
+ * dom_inspect: what one element looks like (styles, box, layout, child tree).
+ */
+export interface DomInspectCommand {
+    selector: string;
+    /** Which match (default: the first rendered one, else the first) */
+    index?: number;
+    /** Exact element from the query cache (overrides selector/index) */
+    backendNodeId?: number;
+    /** Child tree depth (default 2; 0 for none) */
+    tree?: number;
+    /** Child tree rows at most (default 20) */
+    treeLimit?: number;
+    /** Every non-default longhand instead of the groups */
+    all?: boolean;
+    /** Only these properties (lowercase names) */
+    props?: string[];
+    /** Check for declarations that have no effect (default true) */
+    hints?: boolean;
+    /** Report which declaration sets each shown property */
+    rules?: boolean;
+    /** Report every declaration of this property */
+    why?: string;
+}
+export type DomInspectData = InspectResult;
 /**
  * dom_form_discover: run the form discovery script and return raw form data.
  */
@@ -309,7 +368,11 @@ export type RegistryShape = {
     dom_scroll: CommandDef<DomScrollCommand, DomScrollData>;
     dom_form_discover: CommandDef<DomFormDiscoverCommand, DomFormDiscoverData>;
     dom_listeners: CommandDef<DomListenersCommand, DomListenersData>;
+    dom_layout: CommandDef<DomLayoutCommand, DomLayoutData>;
+    dom_inspect: CommandDef<DomInspectCommand, DomInspectData>;
+    dom_wait: CommandDef<DomWaitCommand, DomWaitData>;
     page_navigate: CommandDef<PageNavigateCommand, PageNavigationResult>;
+    page_emulate: CommandDef<PageEmulateCommand, PageEmulationResult>;
 };
 /** What `bdg page` does */
 export type PageAction = 'navigate' | 'reload' | 'back' | 'forward';
@@ -325,6 +388,62 @@ export interface PageNavigationResult {
     status?: number;
     /** Something worth knowing: an HTTP error, a download, a page still loading */
     warning?: string;
+    /** The new document had not finished loading within the wait (absent once complete) */
+    loading?: PageLoadingState;
+}
+/** A request the page is still waiting for */
+export interface PendingRequestInfo {
+    method: string;
+    url: string;
+    /** CDP resource type (Script, Stylesheet, Image, ...) when known */
+    resourceType?: string;
+    /** How long it has been running */
+    pendingMs: number;
+}
+/** A document that has not finished loading (`document.readyState` is not `complete`) */
+export interface PageLoadingState {
+    /** `loading` or `interactive` */
+    readyState: string;
+    /** The longest-running requests, load-blocking ones (scripts, styles, images, frames) first */
+    pending: PendingRequestInfo[];
+    /** All requests still running (more than `pending` lists when there are many) */
+    pendingCount: number;
+}
+/**
+ * dom_wait: wait until elements matching a selector appear, become visible,
+ * contain a text or are gone, and/or the page has loaded.
+ */
+export interface DomWaitCommand {
+    /** Selector (filters like :has-text and :visible allowed); optional with `load` */
+    selector?: string;
+    /** Text one of the matches must contain (case-insensitive) */
+    text?: string;
+    /** Wait for the matches (or visible matches with `visible`) to be gone */
+    gone?: boolean;
+    /** Only count visible matches */
+    visible?: boolean;
+    /** Also wait for `document.readyState` to be `complete` */
+    load?: boolean;
+    /** Give up after this many milliseconds */
+    timeout: number;
+}
+/** What the page showed when a `dom wait` condition was met */
+export interface DomWaitData {
+    selector?: string;
+    text?: string;
+    gone?: boolean;
+    visible?: boolean;
+    load?: boolean;
+    /** Time from the start of the wait until the condition was met */
+    elapsedMs: number;
+    /** Elements matching the selector */
+    count: number;
+    /** Of those, the ones containing `text` (with `text` only) */
+    textCount?: number;
+    /** Of those (or of the text matches), the visible ones */
+    visibleCount: number;
+    /** `document.readyState` of the page */
+    readyState: string;
 }
 /**
  * page_navigate: navigate, reload, or go back/forward, then wait for the page.
@@ -336,6 +455,27 @@ export interface PageNavigateCommand {
     /** Wait for the page to load (default: true) */
     wait?: boolean;
 }
+/**
+ * page_emulate: change the viewport or color scheme mid-session, or clear both.
+ */
+export interface PageEmulateCommand {
+    viewport?: ViewportSize;
+    colorScheme?: ColorScheme;
+    /** Clear both: back to the browser window and the system setting */
+    reset?: boolean;
+}
+/** The page after `page emulate` */
+export interface PageEmulationResult {
+    /** What bdg emulates now (empty after a reset) */
+    emulated: {
+        viewport?: ViewportSize;
+        colorScheme?: ColorScheme;
+    };
+    /** Layout viewport the page has, without scrollbars */
+    viewport?: ViewportSize;
+    /** `prefers-color-scheme` the page sees */
+    colorScheme?: ColorScheme;
+}
 /**
  * Central registry of all session commands.
  * Maps command names to their request/response schemas.

package/dist/ipc/protocol/commands.js

@@ -31,7 +31,11 @@ export const COMMANDS = {
     dom_press_key: defineCommand(),
     dom_scroll: defineCommand(),
     page_navigate: defineCommand(),
+    page_emulate: defineCommand(),
     dom_form_discover: defineCommand(),
     dom_listeners: defineCommand(),
+    dom_layout: defineCommand(),
+    dom_inspect: defineCommand(),
+    dom_wait: defineCommand(),
 };
 //# sourceMappingURL=commands.js.map