browser-debugger-cli 0.9.0 → 0.10.0

package/dist/ipc/client.d.ts

@@ -218,12 +218,21 @@ 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.

package/dist/ipc/client.js

@@ -313,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', {});
@@ -325,6 +334,10 @@ export async function domListeners(params) {
 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;
 /**

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

@@ -6,8 +6,9 @@
  */
 import type { HintDetails } from '../../errors/notices.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;
@@ -234,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;
 /**
@@ -305,6 +312,31 @@ export interface DomLayoutCommand {
     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.
  */
@@ -337,8 +369,10 @@ export type RegistryShape = {
     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';
@@ -421,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,9 +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

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

@@ -60,14 +60,40 @@ export interface NewMessage {
     /** The element showing it, e.g. `div#flash.flash.error` */
     element: string;
 }
+/** An element a hover or key press showed (added, or made visible) */
+export interface ShownElement {
+    /** Its visible text, at most 120 characters */
+    text: string;
+    /** The element, e.g. `div.figcaption` */
+    element: string;
+}
+/** What the page was still working on when an action returned */
+export interface PendingChanges {
+    /** Content requests (documents, fetch/XHR, scripts) the action started that were still running */
+    requests?: number;
+    /** A new document was still loading */
+    navigation?: true;
+    /** A loading indicator that appeared during the action and was still shown, e.g. `div#loading` */
+    loading?: string;
+    /** The DOM was still changing (several bursts of changes, the last one under 150 ms ago) */
+    domChanging?: true;
+    /** The page did not answer within 250 ms (a long-running script) */
+    busy?: true;
+}
 /** What an action changed on the page, besides its triggered requests */
 export interface ActionEffects {
     /** The page navigated or changed its URL (absent when it did not) */
     navigation?: PageNavigation;
     /** Messages that appeared or changed (at most 3; absent when none did) */
     messages?: NewMessage[];
+    /** Elements a hover or key press showed (at most 3, outermost first; absent when none) */
+    shown?: ShownElement[];
     /** "none" when the action had no visible effect: no DOM change, request or navigation */
     effect?: 'none';
+    /** False when the page was still changing as the action returned (absent otherwise) */
+    settled?: false;
+    /** What the page was still working on (with `settled: false`) */
+    pending?: PendingChanges;
 }
 /** A filled field's value differing from the one given */
 export interface FillValueMismatch {
@@ -270,9 +296,10 @@ export interface ElementListener {
     /**
      * Registered through this framework; `handler` is the real handler, not
      * the framework's dispatcher. React handlers are `on…` props of the node
-     * (`reactProp`), run by React's dispatchers on its root container.
+     * (`reactProp`), run by React's dispatchers on its root container;
+     * Preact handlers are run by Preact's event proxy on the node itself.
      */
-    framework?: 'jQuery' | 'React';
+    framework?: 'jQuery' | 'Preact' | 'React';
     /** React prop the handler is set as, e.g. `onClick`, `onClickCapture` */
     reactProp?: string;
     /** jQuery delegate selector (`.on(type, selector, fn)`) the element matched */
@@ -382,6 +409,12 @@ export interface ElementLayout {
     offScreenReason?: string;
     /** Topmost element at the center of its visible part, when that is another element */
     coveredBy?: string;
+    /**
+     * The covering element paints nothing at that point (no background, image,
+     * shadow or text of its own): the element still shows, but clicks land on
+     * the cover
+     */
+    coverTransparent?: true;
     /**
      * Why it cannot be seen although it is rendered: `opacity: 0` on it or an
      * ancestor, or a `clip-path`/`clip` that cuts it away entirely, e.g.

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

@@ -0,0 +1,388 @@
+/**
+ * What `bdg dom inspect` returns: one element's look as a designer reads it,
+ * in a schema aligned with Figma's concepts (rect, box, layout with
+ * hug/fill/fixed sizing, text, fills, strokes, radius, effects, children), so
+ * it can be compared key by key with a design. Lengths are CSS px as numbers
+ * (one decimal); other units stay text. Colors are hex (`#rrggbbaa` when
+ * translucent).
+ */
+import type { ContrastLevel } from '../../utils/color.js';
+import type { CssLength } from '../../utils/cssValues.js';
+/** Border box: page coordinates (iframe offsets and page scroll included) and size */
+export interface InspectRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Sides top, right, bottom, left */
+export type Sides = [CssLength, CssLength, CssLength, CssLength];
+/** How a box gets its size along an axis, as Figma's auto layout names it */
+export type SizingMode = 'fixed' | 'hug' | 'fill';
+/** Padding, margin, border widths and the constraints on the box */
+export interface InspectBox {
+    padding: Sides;
+    margin: Sides;
+    border: Sides;
+    sizing: string;
+    min?: {
+        w?: CssLength;
+        h?: CssLength;
+    };
+    max?: {
+        w?: CssLength;
+        h?: CssLength;
+    };
+    /** `overflow` when not visible, e.g. `hidden` or `hidden auto` (x y) */
+    overflow?: string;
+    /** Size of the content when it overflows the box by more than 1px */
+    scroll?: {
+        w: number;
+        h: number;
+    };
+}
+/** Flex or grid container properties */
+export interface InspectContainer {
+    direction?: string;
+    wrap?: string;
+    justify?: string;
+    align?: string;
+    /** Row and column gap (one number when equal) */
+    gap?: CssLength | [CssLength, CssLength];
+    columns?: string;
+    rows?: string;
+}
+/** The parent that lays the element out (display: contents wrappers skipped) */
+export interface InspectParent extends InspectContainer {
+    element: string;
+    display: string;
+    textAlign?: string;
+}
+/** Gaps to the previous and next rendered in-flow siblings, by the side each is on */
+export interface InspectSiblings {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+}
+/** Display, position and the layout the element takes part in */
+export interface InspectLayout extends InspectContainer {
+    display: string;
+    position?: string;
+    inset?: Sides;
+    z?: CssLength;
+    float?: string;
+    valign?: string;
+    /** As a flex item: grow shrink basis */
+    flex?: string;
+    self?: string;
+    order?: number;
+    /** As a grid item: row-start / column-start / row-end / column-end */
+    area?: string;
+    sizing?: {
+        w: SizingMode;
+        h: SizingMode;
+    };
+    parent?: InspectParent;
+    /** Distances from the parent's content box edges */
+    inParent?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    siblings?: InspectSiblings;
+}
+/** Contrast of the text with what is behind it */
+export interface InspectContrast {
+    ratio: number;
+    level: ContrastLevel;
+    /** Effective background (ancestor backgrounds composited) */
+    background: string;
+    /** The background was taken from an ancestor (or the page canvas) */
+    inherited?: boolean;
+    /** A background image or gradient is behind the text: the ratio uses the colors only */
+    overImage?: boolean;
+    /**
+     * Opacity of the element and its ancestors (below 1): the text color is
+     * faded by it before the ratio is taken (backgrounds inside the faded
+     * subtree are not, so the ratio is approximate)
+     */
+    opacity?: number;
+}
+/** Typography (for containers without text of their own: only what differs from the parent) */
+export interface InspectText {
+    family?: string;
+    /** Font Chrome rendered the text with, when it is not the first family */
+    rendered?: string;
+    /** The rendered font is a web font */
+    webfont?: boolean;
+    weight?: number;
+    style?: string;
+    size?: number;
+    lineHeight?: CssLength;
+    color?: string;
+    contrast?: InspectContrast;
+    align?: string;
+    transform?: string;
+    tracking?: CssLength;
+    decoration?: string;
+    whiteSpace?: string;
+    overflow?: string;
+    clamp?: string;
+    shadow?: string;
+    features?: string;
+}
+/** A background layer */
+export type InspectFill = {
+    type: 'solid';
+    color: string;
+} | {
+    type: 'gradient';
+    value: string;
+} | {
+    type: 'image';
+    value: string;
+    size?: string;
+};
+/** A border side (or all four) */
+export interface InspectStroke {
+    side: 'all' | 'top' | 'right' | 'bottom' | 'left';
+    width: number;
+    style: string;
+    color: string;
+}
+/** A shadow layer */
+export interface InspectEffect {
+    type: 'shadow' | 'inner-shadow';
+    x: number;
+    y: number;
+    blur: number;
+    spread: number;
+    color: string;
+}
+/** Visual effects other than shadows */
+export interface InspectFx {
+    transform?: string;
+    filter?: string;
+    backdrop?: string;
+    clip?: string;
+    mask?: string;
+    animation?: string;
+}
+/** Interaction state set by CSS */
+export interface InspectState {
+    cursor?: string;
+    pointerEvents?: string;
+    visibility?: string;
+    userSelect?: string;
+    appearance?: string;
+}
+/** A generated pseudo-element (`::before`, `::after`) or the placeholder */
+export interface InspectPseudo {
+    type: '::before' | '::after' | '::placeholder';
+    content?: string;
+    display?: string;
+    position?: string;
+    size?: {
+        w: number;
+        h: number;
+    };
+    color?: string;
+    fills?: InspectFill[];
+    radius?: string;
+    effects?: InspectEffect[];
+    transform?: string;
+    opacity?: number;
+    /** `::placeholder`: font style and weight, when not the field's */
+    fontStyle?: string;
+    fontWeight?: number;
+    /** `::placeholder`: contrast of the placeholder text with the field's background */
+    contrast?: InspectContrast;
+}
+/** A row of the child tree; identical siblings are one row with a count */
+export interface InspectTreeNode {
+    /** `tag.firstClass` */
+    element: string;
+    /** Position relative to the parent's border box (like Figma's x/y in a frame; a group's first member) */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** `flex` or `grid` container */
+    layout?: 'flex' | 'grid';
+    text?: string;
+    /** Identical siblings this row stands for (2 or more) */
+    count?: number;
+    children?: InspectTreeNode[];
+    /** Rendered element children (at the depth limit, where they are not listed) */
+    childCount?: number;
+    /** Children that are not rendered (not listed) */
+    hiddenChildren?: number;
+}
+/** Why the element cannot be seen, or where it is when it is out of view */
+export interface InspectVisibility {
+    /** No box: `display: none` on it or an ancestor, or not in the page's layout */
+    notRendered?: true;
+    /** Rendered but not seen, e.g. `visibility: hidden`, `zero size` */
+    hidden?: string;
+    /** Out of the viewport: `above`, `below`, `left` or `right` */
+    offscreen?: string;
+    /** Topmost element at the center of its visible part, when another one */
+    coveredBy?: string;
+    /** The cover paints nothing there: the element shows, but clicks land on the cover */
+    coverTransparent?: true;
+}
+/** A property asked for with `--props` */
+export interface InspectProp {
+    /** Computed value as Chrome reports it */
+    computed: string;
+    /** Normalized: px as numbers, colors as hex */
+    value: string;
+}
+/** A declaration that has no effect, and why */
+export interface InspectHint {
+    /** `inactive` (has no effect), `unset-variable` (var() of an unset custom property), `not-inherited` (a form control in the browser's font) */
+    kind: 'inactive' | 'unset-variable' | 'not-inherited';
+    /** Property as written */
+    property: string;
+    value: string;
+    /** e.g. `display is block` */
+    reason: string;
+    /** e.g. `use display: flex or grid on this element` */
+    fix: string;
+    /** e.g. `.hero (app.css:12)` */
+    source: string;
+}
+/** Which declaration sets a property */
+export interface InspectRule {
+    /** Longhand, or the shorthand when one declaration sets all its sides */
+    property: string;
+    /** Value as written (custom properties visible) */
+    value: string;
+    /** Computed value, normalized (px as numbers, colors as hex), when the written one has `var()` */
+    computed?: string;
+    /** e.g. `.btn-primary (bootstrap.min.css:5:52628)`, `style attribute` */
+    source: string;
+    /** Selectors of the declarations it beats */
+    overrides?: string[];
+    /** Set on an ancestor this many levels up (inherited) */
+    inherited?: number;
+    important?: true;
+    layer?: string;
+    /** Media or container condition of the rule */
+    condition?: string;
+}
+/** One declaration in the cascade of a property (`--why`) */
+export interface InspectWhyEntry {
+    /** Value as written (a shorthand's whole value) */
+    value: string;
+    /** Shorthand or logical property it was written as */
+    via?: string;
+    /** The value with its custom properties substituted, when it has `var()` */
+    resolved?: string;
+    /** Custom properties it uses that are not set (the declaration is then invalid) */
+    unset?: string[];
+    source: string;
+    /** Specificity of the rule's selector (ids, classes, types) */
+    specificity?: [number, number, number];
+    /** `applied` (wins), `overridden`, or `inherited` (from an ancestor: the winner, or one it beat there) */
+    status: 'applied' | 'overridden' | 'inherited';
+    important?: true;
+    layer?: string;
+    condition?: string;
+}
+/** `--why`: every declaration of one property, winner first */
+export interface InspectWhy {
+    property: string;
+    /** Computed value, normalized (px as numbers, colors as hex) */
+    computed: string;
+    chain: InspectWhyEntry[];
+    /** Where the custom properties of the winning value are set */
+    variables?: InspectVariable[];
+}
+/** A custom property a winning value uses, and where it is set */
+export interface InspectVariable {
+    name: string;
+    value: string;
+    source: string;
+    /** Set on an ancestor this many levels up */
+    inherited?: number;
+}
+/** `bdg dom inspect` result */
+export interface InspectResult {
+    success: true;
+    /** Selector the element was found with (for an index: the cached query's) */
+    selector: string;
+    /** Elements the selector matched */
+    count: number;
+    /** Which match was inspected (0-based) */
+    index: number;
+    /**
+     * How the match was chosen when no index was given and several matched:
+     * the first rendered one (`first-visible`, when earlier ones are not
+     * rendered) or the first
+     */
+    picked?: 'first-visible' | 'first';
+    /** `tag#id.c1.c2(+N)` */
+    element: string;
+    /** Its text (innerText) or form value, at most 30 characters; not for containers */
+    content?: string;
+    /** Placeholder of an empty field */
+    placeholder?: string;
+    /** Enclosing iframe(s) and shadow root */
+    context?: string;
+    /** Absent when not rendered */
+    rect?: InspectRect;
+    visibility: InspectVisibility;
+    /**
+     * `dark` when the page renders a dark theme (dark canvas or dark page
+     * background) while the session prefers dark; colors are then the dark
+     * theme's
+     */
+    theme?: 'dark';
+    /**
+     * Running CSS transitions (their property) and animations (their name):
+     * the values read are mid-way and will still change
+     */
+    animating?: string[];
+    /** `prefers-color-scheme` the page sees */
+    colorScheme?: 'light' | 'dark';
+    box?: InspectBox;
+    layout?: InspectLayout;
+    text?: InspectText;
+    fills?: InspectFill[];
+    opacity?: number;
+    blend?: string;
+    strokes?: InspectStroke[];
+    /** Corner radii top-left, top-right, bottom-right, bottom-left */
+    radius?: Sides;
+    outline?: {
+        width: number;
+        style: string;
+        color: string;
+        offset?: number;
+    };
+    effects?: InspectEffect[];
+    fx?: InspectFx;
+    state?: InspectState;
+    pseudo?: InspectPseudo[];
+    children?: InspectTreeNode[];
+    /** Children not rendered (not listed) */
+    hiddenChildren?: number;
+    /** Tree rows left out beyond `--tree-limit` */
+    moreRows?: number;
+    /** `--all`: every longhand that is not a no-op default, collapsed into shorthands */
+    all?: Record<string, string>;
+    /** `--props`: the properties asked for */
+    props?: Record<string, InspectProp>;
+    /** Declarations that have no effect (checked by default; empty when none) */
+    hints?: InspectHint[];
+    /** `--rules`: the declaration that sets each shown property */
+    rules?: InspectRule[];
+    /** `--why <property>`: one entry, or one per longhand of a shorthand whose sides differ */
+    why?: InspectWhy[];
+    /** The cascade was not read: Chrome took longer than the time allowed, or failed */
+    cascade?: 'timeout' | 'failed';
+}
+//# sourceMappingURL=inspectTypes.d.ts.map

package/dist/ipc/protocol/inspectTypes.js

@@ -0,0 +1,10 @@
+/**
+ * What `bdg dom inspect` returns: one element's look as a designer reads it,
+ * in a schema aligned with Figma's concepts (rect, box, layout with
+ * hug/fill/fixed sizing, text, fills, strokes, radius, effects, children), so
+ * it can be compared key by key with a design. Lengths are CSS px as numbers
+ * (one decimal); other units stay text. Colors are hex (`#rrggbbaa` when
+ * translucent).
+ */
+export {};
+//# sourceMappingURL=inspectTypes.js.map