browser-debugger-cli 0.9.0 → 0.11.0

package/dist/commands/dom/semanticUtils.js

@@ -5,7 +5,9 @@
  * their surrounding DOM context and to fall back gracefully when only one
  * of the two data sources is available.
  */
+import { MASKED_VALUE } from '../../runtime/dom/elementInfo.js';
 import { synthesizeA11yNode } from '../../telemetry/roleInference.js';
+import { keyAttributeItems } from '../../ui/formatters/keyAttributes.js';
 import { joinLines } from '../../ui/formatting.js';
 import { elementTextLine, emptyElementLine } from '../../ui/messages/commands.js';
 function capitalize(str) {
@@ -35,6 +37,27 @@ function buildContextText(node, domContext) {
     }
     return '';
 }
+/**
+ * Key attributes of the element (src, href, a field's type and name, ...),
+ * leaving out what the role line already shows: values equal to the
+ * accessible name (an image's alt, a field's placeholder) and the value
+ * when the accessibility node has one.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context with the key attributes
+ * @returns ` src="…/logo.png"`-style text, or empty
+ */
+function buildKeyAttributesText(node, domContext) {
+    if (!domContext?.attributes)
+        return '';
+    const shown = Object.entries(domContext.attributes)
+        .filter(([, value]) => Boolean(node.name) && value === node.name)
+        .map(([name]) => name);
+    if (node.value !== undefined && node.value !== '')
+        shown.push('value');
+    const items = keyAttributeItems(domContext.tag, domContext.attributes, new Set(shown));
+    return items.length > 0 ? ` ${items.join(' ')}` : '';
+}
 function buildPropertiesText(node) {
     const props = [];
     if (node.value !== undefined && node.value !== '')
@@ -59,7 +82,9 @@ function buildPropertiesText(node) {
 /**
  * Format a semantic node together with DOM context for human-readable output.
  *
- * The role line is followed by up to 500 characters of the element's text
+ * The role line names the element's key attributes (an image's file name, a
+ * link's href, a field's type and name), like `dom query` does, and is
+ * followed by up to 500 characters of the element's text
  * (all of it with `dom get --full`) when it is longer than the one-line
  * preview, or, for an element without text or name, what it holds.
  *
@@ -70,9 +95,10 @@ export function formatSemanticNodeWithContext(data) {
     const { node, domContext } = data;
     const roleText = buildRoleText(node);
     const contextText = buildContextText(node, domContext);
+    const keysText = buildKeyAttributesText(node, domContext);
     const propsText = buildPropertiesText(node);
     const inferredText = node.inferred ? ' (inferred from DOM)' : '';
-    const line = `${roleText}${contextText}${propsText}${inferredText}`;
+    const line = `${roleText}${contextText}${keysText}${propsText}${inferredText}`;
     if (domContext?.text)
         return joinLines(line, elementTextLine(domContext.text));
     if (domContext?.childCount !== undefined && !node.name) {
@@ -90,9 +116,24 @@ export function formatSemanticNodeWithContext(data) {
  */
 export function resolveNodeWithFallback(a11yNode, domContext, nodeId) {
     if (a11yNode)
-        return a11yNode;
+        return withSecretMasked(a11yNode, domContext);
     if (domContext && nodeId)
         return synthesizeA11yNode(domContext, nodeId);
     return null;
 }
+/**
+ * The accessibility node with its value masked when the element holds a
+ * secret (`domContext.sensitive`): Chrome reports a password field's value
+ * as one bullet per character, and a field switched to text by a "show
+ * password" button in clear.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context of the same element
+ * @returns The node, with {@link MASKED_VALUE} as its value for a secret
+ */
+export function withSecretMasked(node, domContext) {
+    if (!domContext?.sensitive || !node.value)
+        return node;
+    return { ...node, value: MASKED_VALUE };
+}
 //# sourceMappingURL=semanticUtils.js.map

package/dist/commands/installSkill.d.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+import type { InstalledSkill, SkillTarget } from '../types.js';
+/**
+ * Copy the bdg skill into each target's skill directory, overwriting an
+ * older copy.
+ *
+ * @param targets - Agents to install for
+ * @param home - Home directory the skill roots are relative to
+ * @param source - SKILL.md to copy
+ * @returns One entry per target, in the given order
+ * @throws CommandError when the source is missing (83) or a write fails (82)
+ */
+export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): InstalledSkill[];
+/**
+ * Register the install-skill command.
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export declare function registerInstallSkillCommand(program: Command): void;
+//# sourceMappingURL=installSkill.d.ts.map

package/dist/commands/installSkill.js

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { CommandError } from '../errors/index.js';
+import { skillSourceMissingError, skillWriteFailedError } from '../errors/messages.js';
+import { formatInstalledSkills } from '../ui/formatters/installSkill.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+import { PACKAGE_ROOT } from '../utils/packageRoot.js';
+/** The skill shipped with the package (also used by agents working in this repo). */
+const SKILL_SOURCE_PATH = join(PACKAGE_ROOT, '.claude', 'skills', 'bdg', 'SKILL.md');
+/** Skill roots, relative to the home directory, of the agents the skill is installed for. */
+const SKILL_ROOTS = {
+    claude: join('.claude', 'skills'),
+    agents: join('.agents', 'skills'),
+};
+/**
+ * Copy the bdg skill into each target's skill directory, overwriting an
+ * older copy.
+ *
+ * @param targets - Agents to install for
+ * @param home - Home directory the skill roots are relative to
+ * @param source - SKILL.md to copy
+ * @returns One entry per target, in the given order
+ * @throws CommandError when the source is missing (83) or a write fails (82)
+ */
+export function installSkill(targets, home = homedir(), source = SKILL_SOURCE_PATH) {
+    if (!existsSync(source)) {
+        const err = skillSourceMissingError(source);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    const content = readFileSync(source, 'utf-8');
+    return targets.map((target) => writeSkill(target, join(home, SKILL_ROOTS[target], 'bdg', 'SKILL.md'), content));
+}
+/**
+ * Write the skill to one path unless it already holds the same content.
+ *
+ * @param target - Agent the path belongs to
+ * @param path - Destination SKILL.md
+ * @param content - Skill text
+ * @returns What happened to the file
+ * @throws CommandError (82) when the directory or file cannot be written
+ */
+function writeSkill(target, path, content) {
+    const existing = existsSync(path) ? readFileSync(path, 'utf-8') : undefined;
+    if (existing === content) {
+        return { target, path, status: 'unchanged' };
+    }
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+    }
+    catch (caught) {
+        const err = skillWriteFailedError(path, getErrorMessage(caught));
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.PERMISSION_DENIED);
+    }
+    return { target, path, status: existing === undefined ? 'installed' : 'updated' };
+}
+/**
+ * Targets picked by the flags; no flag means every agent.
+ *
+ * @param options - Parsed command options
+ * @returns Targets to install for
+ */
+function selectedTargets(options) {
+    const picked = Object.keys(SKILL_ROOTS).filter((target) => options[target]);
+    return picked.length > 0 ? picked : Object.keys(SKILL_ROOTS);
+}
+/**
+ * Register the install-skill command.
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export function registerInstallSkillCommand(program) {
+    program
+        .command('install-skill')
+        .description('Install the bdg agent skill for Claude Code (~/.claude/skills) and agents reading ~/.agents/skills (Codex, Gemini CLI, ...); re-run after upgrading bdg')
+        .option('--claude', 'Only ~/.claude/skills (Claude Code)')
+        .option('--agents', 'Only ~/.agents/skills (Codex, Gemini CLI and other agents)')
+        .addOption(jsonOption())
+        .action(async (options) => {
+        await runCommand((opts) => Promise.resolve({ success: true, data: { skills: installSkill(selectedTargets(opts)) } }), options, formatInstalledSkills);
+    });
+}
+//# sourceMappingURL=installSkill.js.map

package/dist/commands/network/list.js

@@ -13,7 +13,7 @@ import { applyFilters, getFilterHelpText, validateFilterString } from '../../tel
 import { resolvePreset, FILTER_PRESETS } from '../../telemetry/filterPresets.js';
 import { filterByResourceType } from '../../telemetry/filters.js';
 import { buildSuccessResponse } from '../../ui/OutputBuilder.js';
-import { formatNetworkFollowRows, formatNetworkList, } from '../../ui/formatters/networkList.js';
+import { formatNetworkFollowRows, formatNetworkList, pageStartOf, } from '../../ui/formatters/networkList.js';
 import { followingNetworkMessage, stoppedFollowingNetworkMessage, } from '../../ui/messages/networkMessages.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { validateFilterOption } from './shared.js';
@@ -110,6 +110,7 @@ function buildFormatOptions(options, result, lastLimit) {
         last: lastLimit,
         totalCount: result.totalCount,
         filteredCount: result.filteredCount,
+        ...(result.pageStart && { pageStart: result.pageStart }),
     };
 }
 /**
@@ -148,9 +149,11 @@ async function runFollowMode(options, resourceTypes, lastN) {
             }
         }
         else {
+            const pageStart = pageStartOf(result.data);
             const text = formatNetworkFollowRows(fresh, {
                 header: !started,
                 verbose: options.verbose ?? false,
+                ...(pageStart && { pageStart }),
             });
             if (text)
                 console.log(text);
@@ -164,6 +167,12 @@ async function runFollowMode(options, resourceTypes, lastN) {
         intervalMs: FOLLOW_INTERVAL,
     });
 }
+/** What the less obvious columns of the list mean */
+const COLUMNS_HELP = `Columns:
+  START  When the request started, from the start of the current page (its document
+         request): +1.2s. Requests of earlier pages are negative. --json has the
+         absolute time (timestamp, epoch ms) and data.pageStart.
+  TIME   How long it took (to its last byte or failure); - while pending`;
 function formatPresetHelp() {
     return Object.entries(FILTER_PRESETS)
         .map(([name, preset]) => `  ${name.padEnd(12)} ${preset.description}`)
@@ -180,7 +189,7 @@ export function registerListCommand(networkCmd) {
         .addOption(networkLastOption)
         .addOption(new Option('-f, --follow', 'Stream network requests in real-time').default(false))
         .addOption(new Option('-v, --verbose', 'Show full URLs and additional details').default(false))
-        .addHelpText('after', `\n${getFilterHelpText()}\n\nPresets:\n${formatPresetHelp()}`)
+        .addHelpText('after', `\n${COLUMNS_HELP}\n\n${getFilterHelpText()}\n\nPresets:\n${formatPresetHelp()}`)
         .action(async (options) => {
         let resourceTypes;
         let lastN;
@@ -211,12 +220,14 @@ export function registerListCommand(networkCmd) {
                 return createErrorResult(result.error, result.exitCode, result.suggestion);
             }
             const filtered = filterRequests(result.data, options, resourceTypes);
+            const pageStart = pageStartOf(result.data);
             return {
                 success: true,
                 data: {
                     requests: lastN === 0 ? filtered : filtered.slice(-lastN),
                     totalCount: result.data.length,
                     filteredCount: filtered.length,
+                    ...(pageStart && { pageStart }),
                 },
             };
         }, options, (data) => formatNetworkList(data.requests, buildFormatOptions(options, data, lastN)));

package/dist/commands/optionBehaviors.js

@@ -11,6 +11,10 @@ import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from './dom/scree
 const TRIGGERED_REQUESTS_BEHAVIOR = 'Requests (and WebSocket connections) that start after the action begins are returned as triggeredRequests (method, url, status, durationMs; pending when still running at return, loading when the response arrived but its body is still streaming; with resourceType; human output lists documents, XHR/fetch and WebSockets first (up to 10) and counts static assets on one line; absent when network telemetry is off). Attribution is by time: requests a page timer or poller starts meanwhile are listed too, whether or not the action caused them';
 /** What every DOM action reports about the page besides its requests */
 const ACTION_EFFECTS_BEHAVIOR = 'The result also says what changed on the page: a navigation (Page: navigated to <url> (status), or URL changed to <url> (same document); JSON navigation { url, sameDocument, status }), and messages that appeared or changed in alert/status/aria-live elements or flash/error/toast-like classes (New text: "…" (element); JSON messages [{ text, element }], at most 3; after a navigation every message on the new page counts; texts of only digits and time units, such as clocks and counters, are left out, but other text that changes on its own, such as a rotating banner, can show up). Both are absent when nothing changed. Cost: one page script sent before the action without waiting for it and one read after it, a few ms; when the page does not answer (a pending navigation) bdg waits at most 200 ms for the snapshot and 250 ms per read, and the navigation is still reported from CDP events';
+/** What click and pressKey report when the page was still changing as they returned */
+const STILL_CHANGING_BEHAVIOR = 'When the page was still changing as the action returned, the status line says (page still changing), a note below it says what was pending and suggests bdg dom wait <selector>, and JSON has settled: false with pending { requests (document, fetch/XHR and script requests still running), navigation (a new page still loading), loading (a loading indicator that appeared, e.g. "div#loading"), domChanging (DOM changes kept coming in bursts over a second look 250 ms later; a single render, ticking text and style animations do not count), busy (the page did not answer within 250 ms: a long script) }; absent when the page looked settled (exit code stays 0). A result a timer renders later, with no DOM change, request or loading indicator before it, is not detected. Cost: nothing extra, except 250 ms plus one read when the DOM looked busy. Not checked with --no-wait';
+/** What hover and pressKey report about elements they showed */
+const SHOWN_BEHAVIOR = 'Elements the action showed are listed (Shown: <element> "<text>"; JSON shown [{ text, element }], at most 3, outermost first): elements with visible text added inside the target\'s form, search box, dialog or combobox (else its grandparent, or its parent when that is the body), and popups and messages added anywhere (tooltip, menu, listbox, dialog, alert, status roles, popover, aria-live, message-like classes); widgets elsewhere on the page and re-rendered elements whose text was there before do not count';
 /** What `--no-wait` does to a DOM action's triggered requests */
 const NO_WAIT_TRIGGERED_REQUESTS = 'Returns immediately without waiting for network; triggeredRequests lists only requests bdg saw start before returning (often none yet; check bdg network list later)';
 /**
@@ -76,7 +80,7 @@ const OPTION_BEHAVIORS = {
     'eval:--frame': {
         default: "Evaluates in the page's main frame",
         whenEnabled: "Evaluates in one iframe's main world (its own globals), including cross-origin (out-of-process) iframes; output gains a frame field (its URL)",
-        automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order, main page not counted), else an exact name/id attribute, else a case-insensitive part of the name, id or URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again).',
+        automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order: document order of the <iframe> elements, nested ones depth-first, main page not counted), else an exact name/id attribute, else a case-insensitive part of the name, id or URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again). An index that names another frame than in the last bdg dom frames listing (iframes added, removed or moved, or the page navigated) fails with 87 STALE_CACHE: re-run bdg dom frames or pick the frame by name.',
     },
     'console:-H': {
         default: 'Shows messages from current page load only (most recent navigation)',
@@ -118,7 +122,7 @@ const OPTION_BEHAVIORS = {
     'click:--no-wait': {
         default: 'Waits for network stability after click (150ms idle, up to 2s)',
         whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
-        automaticBehavior: `Network wait helps ensure AJAX requests triggered by click complete. ${TRIGGERED_REQUESTS_BEHAVIOR}. The click itself uses real mouse events in the visible part of the element (method "mouse"); if the element is covered or has no size it falls back to DOM events (method "dom", with a warning). Results the page shows later without requests (timers, spinners) are not waited for: use bdg dom wait <selector> --visible. ${ACTION_EFFECTS_BEHAVIOR}. A click with no DOM change, no request and no navigation (checked again 300 ms later, which adds 300 ms plus at most 250 ms for the read) is reported as ⚠ Element Clicked (no visible effect observed: no DOM change, requests or navigation within 300 ms) and effect: "none" in JSON (exit code stays 0); not claimed with --no-wait, for hover or right-click, after a copy or cut, or when the click hit a form control, label, media, iframe, popover button, a mailto:/tel:/javascript: or other non-http link, a link to another window or a custom element with a closed shadow root, or moved focus to an element that is not a button or link. Effects outside the DOM (CSS :hover/:focus-within styles, canvas, clipboard without a copy event) are not seen`,
+        automaticBehavior: `Network wait helps ensure AJAX requests triggered by click complete. ${TRIGGERED_REQUESTS_BEHAVIOR}. The click itself uses real mouse events in the visible part of the element (method "mouse"); if the element is covered or has no size it falls back to DOM events (method "dom", with a warning; --strict refuses instead). Results the page shows later (timers, spinners, slow renders) are not waited for but reported as pending work: use bdg dom wait <selector> --visible. ${ACTION_EFFECTS_BEHAVIOR}. ${STILL_CHANGING_BEHAVIOR}. A click with no DOM change, no request and no navigation (checked again 300 ms later, which adds 300 ms plus at most 250 ms for the read) is reported as ⚠ Element Clicked (no visible effect observed: no DOM change, requests or navigation within 300 ms) and effect: "none" in JSON (exit code stays 0); not claimed with --no-wait, for hover or right-click, after a copy or cut, or when the click hit a form control, label, media, iframe, popover button, a mailto:/tel:/javascript: or other non-http link, a link to another window or a custom element with a closed shadow root, or moved focus to an element that is not a button or link. Effects outside the DOM (CSS :hover/:focus-within styles, canvas, clipboard without a copy event) are not seen`,
         tokenImpact: 'A click that navigates lists the whole page load in JSON triggeredRequests',
     },
     'click:--double': {
@@ -129,10 +133,19 @@ const OPTION_BEHAVIORS = {
         default: 'Left click',
         whenEnabled: 'Right-click: the page gets contextmenu (custom context menus open); cannot be combined with --double',
     },
+    'click:--strict': {
+        default: 'A covered, hidden or zero-size element is clicked with DOM events (method "dom", with a warning, exit 0)',
+        whenEnabled: 'Refuses with exit 90 (RESOURCE_CONFLICT: the page state blocks the request) when a real mouse cannot reach the element, naming what covers it and suggesting bdg dom layout <selector>; also when the mouse press never reached the element (it is released, no further presses for --double)',
+        automaticBehavior: 'Applies to --double and --right too. Nothing is dispatched when the element is unreachable, so the page is unchanged',
+    },
     'hover:--no-wait': {
         default: 'Waits for network stability after moving the mouse (menus may load content)',
         whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
-        automaticBehavior: `The mouse stays over the element afterwards, so hover menus stay open until the next mouse action. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`,
+        automaticBehavior: `The mouse stays over the element afterwards, so hover menus stay open until the next mouse action. ${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}. ${SHOWN_BEHAVIOR}; for a hover also elements around it (its parent's subtree) and tooltips, menus, listboxes, dialogs and popovers anywhere that were hidden before, so captions shown by CSS :hover count (hidden elements noted by identity right before the mouse moves: up to 1500, within 8 ms). A hover never claims "no visible effect" and does not check whether the page was still changing`,
+    },
+    'hover:--strict': {
+        default: 'A covered, hidden or zero-size element gets synthetic mouseover/mouseenter events (method "dom", with a warning)',
+        whenEnabled: 'Refuses with exit 90 when a real mouse cannot reach the element, naming what covers it and suggesting bdg dom layout <selector>',
     },
     'navigate:--no-wait': {
         default: 'Waits until the new page has loaded and the network and DOM are idle (up to 15 s)',
@@ -142,7 +155,7 @@ const OPTION_BEHAVIORS = {
     'pressKey:--no-wait': {
         default: 'Waits for network stability after key press (150ms idle, up to 2s)',
         whenDisabled: NO_WAIT_TRIGGERED_REQUESTS,
-        automaticBehavior: `${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}`,
+        automaticBehavior: `${TRIGGERED_REQUESTS_BEHAVIOR}. ${ACTION_EFFECTS_BEHAVIOR}. ${SHOWN_BEHAVIOR}, such as the item Enter added to a list. ${STILL_CHANGING_BEHAVIOR}. A key press never claims "no visible effect"`,
     },
     'pressKey:--times': {
         default: 'Presses key once',
@@ -187,7 +200,7 @@ const OPTION_BEHAVIORS = {
     'listeners:--type': {
         default: 'Lists listeners of every event type on the element, its ancestors (through open shadow roots), its document and window',
         whenEnabled: 'Lists only these event types (comma-separated or repeated, case-sensitive like addEventListener); when none match, typeSuggestions names close types (Click, onclick → click)',
-        automaticBehavior: "Listeners are grouped by type, the element's own handlers first (types handled on the element before delegated ones; nearest first, no-ops last); JSON line/column numbers are 0-based (human output shows them 1-based like DevTools). React's on… props that run for the element (its own and its React parents', through portals; onFocus/onBlur as focusin/focusout; parents' props for non-bubbling events left out) are listed with source and location (framework: \"React\", reactProp: \"onClick\"; at most 50 of the requested types, reactHandlersSkipped counts the rest). jQuery handlers are shown instead of jQuery's dispatcher (framework: \"jQuery\", delegateSelector for delegates the element matches; a dispatcher with no handler for the element is omitted; at most 50 are resolved, jqueryHandlersSkipped counts the rest). Empty handlers (React's onclick placeholder) are marked noop and do not count as the element's own handler. The Debugger domain is not enabled",
+        automaticBehavior: 'Listeners are grouped by type, the element\'s own handlers first (types handled on the element before delegated ones; nearest first, no-ops last); JSON line/column numbers are 0-based (human output shows them 1-based like DevTools). React\'s on… props that run for the element (its own and its React parents\', through portals and from a nested root into the outer root; onFocus/onBlur as focusin/focusout; parents\' props for non-bubbling events left out) are listed with source and location (framework: "React", reactProp: "onClick"; at most 50 of the requested types, reactHandlersSkipped counts the rest). jQuery handlers are shown instead of jQuery\'s dispatcher (framework: "jQuery", delegateSelector for delegates the element matches; a dispatcher with no handler for the element is omitted; at most 50 are resolved, jqueryHandlersSkipped counts the rest). Preact\'s event proxy is replaced by the handler Preact runs (framework: "Preact"). Empty handlers (React\'s onclick placeholder) are marked noop and do not count as the element\'s own handler. The Debugger domain is not enabled',
         tokenImpact: 'Framework roots are already collapsed; --type keeps the output short on pages with many listeners',
     },
     'listeners:--all': {
@@ -201,6 +214,35 @@ const OPTION_BEHAVIORS = {
         automaticBehavior: 'Coordinates are CSS px: bounds relative to the top-level page (iframe offsets and page scroll included), viewport relative to the visible area. Iframes and overflow containers (scroll lists, overflow: hidden) clip what counts as visible (clippedBy names the one cutting it off). scrollBy brings the whole element into view and is limited to how far the page can scroll: for an element out of view it centres it (aligns its start when it is larger than the viewport; human output says "to centre it"), for a partly visible one it is the smallest scroll that shows all of it (the part cut off at the top or bottom; the start of one larger than the viewport; "partly visible (87%); scroll up 5px to see all of it"). Elements a page script moves on scroll (floating menus) may move again after it; fixed and sticky elements (page scroll does not move them, or only until they stick) and ones beyond that range get offScreenReason instead, which says "page scrolling is locked (…)" when the page cannot scroll because body/html is position: fixed or overflow: hidden, so in-flow content is not called fixed; a visible dialog (dialog[open], [aria-modal=true], [role=dialog|alertdialog]) is named as the likely cause ("likely by dialog div#consent"). page.viewport is the layout viewport without scrollbars, as dom scroll reports it; page.colorScheme is the prefers-color-scheme media feature the page sees (not the theme it renders). Content in a closed <details> or under content-visibility: hidden is hidden. coveredBy is the topmost element at the center of the largest visible box (none for pointer-events: none, nor for an element of the same click target: an overlay inside the link, button or label the element is in, a link to the same URL, or the textless absolutely positioned overlay link spanning the card that holds plain content); inert elements are flagged, not hidden',
         tokenImpact: 'About one line per element; a cheap alternative to screenshots for "where is it?"',
     },
+    'inspect:--index': {
+        default: 'Inspects the first rendered match (the first when none is rendered) and notes how many matched; a numeric argument inspects that cached element (from dom query, dom form or dom a11y query)',
+        whenEnabled: 'Inspects the nth match (0-based); out of range exits 81',
+        automaticBehavior: 'Answers "what does it look like" without a screenshot, grouped like Figma Dev Mode: header (element, text, size and page position, [flex]/[grid], [not rendered]/[hidden]/[offscreen]/[covered by …], prefers-color-scheme), box (margin, padding, border widths, box-sizing, overflow, scroll size), layout (display, position, flex/grid container and item settings), parent (its display and layout, distances to its content edges, gaps to the neighbouring siblings), text (first font family → the font Chrome rendered, (webfont) or local; weight size/line-height; color; WCAG contrast against the composited background; only for elements with text), fill, border (sides, radius, outline), fx (shadow, transform, filter, opacity, blend), state (cursor, pointer-events, user-select, appearance), pseudo (::before/::after with content, ::placeholder) and a child tree (depth 2, 20 rows, identical siblings grouped). Values that change nothing (0, none, transparent, normal) are left out; colors are hex (lab/oklch from Tailwind converted), lengths px without the unit, rounded to 0.1. Secrets are never shown. JSON uses Figma-aligned names (rect, box, layout.sizing hug/fill/fixed, text, fills, strokes, radius, effects, children). Also by default: hints, the element\'s own declarations that have no effect (justify-content on a block, width on an inline element, top on a static one, var() of an unset custom property) with the reason, the fix and the rule\'s file:line',
+        tokenImpact: 'About 60–80 tokens for the styles and 30–70 more for the child tree (--tree 0 drops it), against about 1,500 for a screenshot or 3,000+ for raw computed styles',
+    },
+    'inspect:--all': {
+        default: 'Shows the curated groups (the properties that define the look)',
+        whenEnabled: 'Lists every computed property that differs from the default of the same element type, longhands collapsed into shorthands, noise (logical duplicates, currentColor echoes, custom properties) dropped',
+        tokenImpact: 'About 80 tokens instead of 60–80',
+    },
+    'inspect:--props': {
+        default: 'Shows the curated groups',
+        whenEnabled: 'Shows only the named properties (custom properties like --brand included, "(not set)" when no rule sets one; --* lists every custom property the element has, --bs-btn-* those with a prefix), each computed and normalized; an unknown name exits 81 with a suggestion',
+    },
+    'inspect:--rules': {
+        default: 'Shows the values, not where they come from',
+        whenEnabled: "Adds a rules group: for each shown property the page's CSS sets, the value as written (with the computed value when it uses var()), selector, file:line (column for minified files), @media/@container condition, cascade layer, how many ancestors up it is inherited from, and the rules it beats. Sides one declaration sets are one row; browser defaults are left out. With --props, only those properties",
+        automaticBehavior: 'The cascade is computed by bdg from CSS.getMatchedStylesForNode (origin, !important, style attribute, layers, specificity and order); reading it waits up to 5 s, then the output notes the cascade was not read',
+        tokenImpact: 'About 15–25 tokens per row, 5–20 rows',
+    },
+    'inspect:--why': {
+        default: 'Not shown',
+        whenEnabled: "Adds why <property> = computed value, then every declaration of it on the element, highest precedence first: ✓ the winner (or the inherited ancestor's), ✗ the ones it beats, browser defaults included. Each rule shows its selector specificity [ids,classes,types]. var() values are shown substituted (or invalid: --x not set), with where the winner's custom properties are set, followed up to :root. Logical names map to physical ones (margin-inline-start → margin-left); a shorthand (padding, border) gives one answer when one declaration sets all its sides, else one per side",
+    },
+    'inspect:--no-hints': {
+        default: "Hints at the element's own author declarations that have no effect (flex/grid properties without flex or grid, item properties without a flex or grid parent, offsets on static elements, sizes on inline ones, var() of an unset custom property, form controls in the browser's font), within a 1 s budget; hints none when nothing was found",
+        whenEnabled: 'Skips the hints and does not read the matched rules',
+    },
     'scroll:--down': {
         whenEnabled: 'Scrolls page down by specified pixel amount',
     },
@@ -282,7 +324,7 @@ const OPTION_BEHAVIORS = {
     'bdg:--viewport': {
         default: 'A launched Chrome opens a 1920x1080 window (the viewport is smaller by the scrollbar, and in a visible window by the browser UI); an attached Chrome keeps its window',
         whenEnabled: 'The page gets exactly that viewport (CSS px, e.g. 1280x800) for the whole session, through navigations and reloads (Emulation.setDeviceMetricsOverride at the display pixel ratio); a launched Chrome also opens its window at that size, so tabs the page opens get it too',
-        automaticBehavior: 'Works with --chrome-ws-url: the override belongs to the session, and Chrome drops it when the session ends, so the attached browser gets its own size back. bdg status shows the resulting layout viewport without the scrollbar (Viewport: 1265×800 (--viewport 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81',
+        automaticBehavior: 'Works with --chrome-ws-url: the override belongs to the session, and Chrome drops it when the session ends, so the attached browser gets its own size back. bdg status shows the resulting layout viewport without the scrollbar (Viewport: 1265×800 (emulated 1280x800)). Invalid sizes (not WxH, a side outside 1-10000) exit 81',
     },
     'bdg:--color-scheme': {
         default: 'The page sees the system setting for prefers-color-scheme (headless Chrome follows the OS, so a dark OS renders dark pages); bdg status and dom layout show which one',

package/dist/commands/page.d.ts

@@ -2,7 +2,7 @@
  * `bdg page navigate|reload|back|forward` — move the session's page;
  * `bdg page info` — where it is.
  */
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 /**
  * Register the `page` command group.
  *

package/dist/commands/page.js

@@ -2,12 +2,15 @@
  * `bdg page navigate|reload|back|forward` — move the session's page;
  * `bdg page info` — where it is.
  */
+import { Option } from 'commander';
 import { noActiveSessionError, runCommand } from './shared/CommandRunner.js';
 import { jsonOption } from './shared/commonOptions.js';
+import { parseColorScheme, parseViewport } from './start.js';
+import { CommandError } from '../errors/index.js';
 import { javascriptNavigationError } from '../errors/messages.js';
-import { getStatus, pageNavigate } from '../ipc/client.js';
+import { getStatus, pageEmulate, pageNavigate } from '../ipc/client.js';
 import { OutputFormatter } from '../ui/formatting.js';
-import { PAGE_ACTION_DESCRIPTIONS, PAGE_ACTION_DONE, PAGE_INFO_DESCRIPTION, pageLoadingWarning, } from '../ui/messages/commands.js';
+import { PAGE_ACTION_DESCRIPTIONS, PAGE_ACTION_DONE, PAGE_EMULATE_DESCRIPTION, PAGE_INFO_DESCRIPTION, pageEmulateNothingError, pageEmulationLines, pageLoadingWarning, } from '../ui/messages/commands.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { validateUrl } from '../utils/url.js';
 /**
@@ -114,6 +117,49 @@ async function showPageInfo(options) {
     ], 8)
         .build());
 }
+/**
+ * The emulation request from the options.
+ *
+ * @param options - Command options
+ * @returns Request
+ * @throws CommandError (81) for nothing to change or an invalid value
+ */
+function emulationRequest(options) {
+    if (options.reset)
+        return { reset: true };
+    if (options.viewport === undefined && options.colorScheme === undefined) {
+        const err = pageEmulateNothingError();
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return {
+        ...(options.viewport !== undefined && { viewport: parseViewport(options.viewport) }),
+        ...(options.colorScheme !== undefined && {
+            colorScheme: parseColorScheme(options.colorScheme),
+        }),
+    };
+}
+/**
+ * `bdg page emulate`: change the viewport or color scheme mid-session.
+ *
+ * @param options - Command options
+ */
+async function emulate(options) {
+    await runCommand(async () => {
+        const response = await pageEmulate(emulationRequest(options));
+        if (response.status === 'error' || !response.data) {
+            return {
+                success: false,
+                error: response.error ?? 'Failed to change the emulation',
+                exitCode: response.exitCode ?? EXIT_CODES.SOFTWARE_ERROR,
+                ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+            };
+        }
+        return { success: true, data: response.data };
+    }, options, (result) => new OutputFormatter()
+        .text('✓ Page emulation changed')
+        .keyValueList(pageEmulationLines(result), 10)
+        .build());
+}
 /**
  * Register the `page` command group.
  *
@@ -122,7 +168,7 @@ async function showPageInfo(options) {
 export function registerPageCommands(program) {
     const page = program
         .command('page')
-        .description('The session page: info (URL and title), navigate <url>, reload, back, forward');
+        .description('The session page: info (URL and title), navigate <url>, reload, back, forward, emulate (viewport, color scheme)');
     page
         .command('info')
         .description(PAGE_INFO_DESCRIPTION)
@@ -139,6 +185,19 @@ export function registerPageCommands(program) {
         .argument('<url>', 'URL to load')).action(async (url, options) => {
         await runPageAction('navigate', options, url);
     });
+    page
+        .command('emulate')
+        .description(PAGE_EMULATE_DESCRIPTION)
+        .option('--viewport <WxH>', 'Viewport size in CSS px, e.g. 900x700')
+        .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme: light or dark')
+        .addOption(new Option('--reset', 'Back to the browser window size and the system setting').conflicts([
+        'viewport',
+        'colorScheme',
+    ]))
+        .addOption(jsonOption())
+        .action(async (options) => {
+        await emulate(options);
+    });
     for (const action of ['reload', 'back', 'forward']) {
         withCommon(page.command(action).description(PAGE_ACTION_DESCRIPTIONS[action])).action(async (options) => {
             await runPageAction(action, options);

package/dist/commands/shared/commonOptions.d.ts

@@ -30,4 +30,8 @@ export declare function showBothSectionsWhenBothRequested(options: {
     network?: boolean;
     console?: boolean;
 }): void;
+/** Help of a `<selectorOrIndex>` argument */
+export declare const SELECTOR_OR_INDEX_ARGUMENT = "CSS selector (searches open shadow roots and same-origin iframes) or numeric index from query results (0-based)";
+/** Help text after `dom query`'s options: what selectors search and what they cannot */
+export declare const SELECTOR_SCOPE_HELP = "\nSelectors search the page, open shadow roots and same-origin iframes (nested ones\nincluded). They cannot reach into closed shadow roots or cross-origin iframes:\nuse bdg dom eval --frame <frame> for those (see bdg dom frames).";
 //# sourceMappingURL=commonOptions.d.ts.map

package/dist/commands/shared/commonOptions.js

@@ -34,4 +34,13 @@ export function showBothSectionsWhenBothRequested(options) {
         options.console = false;
     }
 }
+/** Where selectors search, for the help of commands that take one */
+const SELECTOR_SCOPE = 'searches open shadow roots and same-origin iframes';
+/** Help of a `<selectorOrIndex>` argument */
+export const SELECTOR_OR_INDEX_ARGUMENT = `CSS selector (${SELECTOR_SCOPE}) or numeric index from query results (0-based)`;
+/** Help text after `dom query`'s options: what selectors search and what they cannot */
+export const SELECTOR_SCOPE_HELP = `
+Selectors search the page, open shadow roots and same-origin iframes (nested ones
+included). They cannot reach into closed shadow roots or cross-origin iframes:
+use bdg dom eval --frame <frame> for those (see bdg dom frames).`;
 //# sourceMappingURL=commonOptions.js.map

package/dist/commands/shared/optionTypes.d.ts

@@ -183,6 +183,8 @@ export interface ClickCommandOptions extends BaseOptions, IndexOptions {
     double?: boolean;
     /** Right-click */
     right?: boolean;
+    /** Refuse instead of falling back to DOM events when the mouse can't reach the element */
+    strict?: boolean;
 }
 /**
  * Options for submit command.
@@ -236,6 +238,25 @@ export interface ListenersCommandOptions extends BaseOptions, IndexOptions {
  * Options for `dom layout`.
  */
 export type LayoutCommandOptions = BaseOptions & IndexOptions;
+/**
+ * Options for `dom inspect`.
+ */
+export interface InspectCommandOptions extends BaseOptions, IndexOptions {
+    /** Child tree depth (0 for none) */
+    tree?: number;
+    /** Child tree rows at most */
+    treeLimit?: number;
+    /** Every non-default property instead of the groups */
+    all?: boolean;
+    /** Only these properties */
+    props?: string[];
+    /** Which declaration sets each shown property */
+    rules?: boolean;
+    /** Every declaration of this property */
+    why?: string;
+    /** `--no-hints` sets false */
+    hints?: boolean;
+}
 /** Options for `bdg dom wait` */
 export interface WaitCommandOptions extends BaseOptions {
     /** Text a match must contain */

package/dist/commands/shared/startHelpers.d.ts

@@ -5,7 +5,48 @@
  * Handles IPC communication with daemon to start browser sessions.
  */
 import type { SessionStartOptions } from './optionTypes.js';
+import { type SpawnedDaemon } from '../../daemon/launcher.js';
+import { startSession as sendStartSessionRequest } from '../../ipc/client.js';
+import { IPCErrorCode, type StartSessionResponseData } from '../../ipc/index.js';
 import type { TelemetryType } from '../../types.js';
+/**
+ * Outcome of a start attempt, printed by {@link reportStartOutcome}.
+ */
+export type StartOutcome = {
+    ok: true;
+    data: StartSessionResponseData;
+} | {
+    ok: false;
+    /** Message for `--json` (no "Error:" prefix) */
+    error: string;
+    /** Full human-readable message */
+    human: string;
+    exitCode: number;
+    /** Daemon's error code (internal: not printed) */
+    errorCode?: IPCErrorCode | undefined;
+    /** Extra fields of the JSON error envelope */
+    details?: Record<string, unknown>;
+    /** The daemon went away mid-request (e.g. the previous session was ending) */
+    retryable?: boolean;
+    /**
+     * The daemon reported the failure or dropped the connection, so it is
+     * exiting (a daemon this start spawned is then waited for)
+     */
+    daemonExiting?: boolean;
+    /** The daemon this attempt spawned, when it is exiting */
+    spawned?: SpawnedDaemon;
+};
+/** How long a failed start waits for the daemons it spawned to exit */
+export declare const SPAWNED_DAEMON_EXIT_WAIT_MS = 3000;
+/** What a start uses to reach the daemon (replaced in tests) */
+export interface StartDeps {
+    /** Spawns the daemon if none runs ({@link launchDaemon}) */
+    launch: () => Promise<SpawnedDaemon | undefined>;
+    /** Sends `start_session_request` */
+    send: typeof sendStartSessionRequest;
+    /** How long a failed start waits for the daemons it spawned to exit */
+    exitWaitMs: number;
+}
 /**
  * Start a session via the daemon and report the result.
  *
@@ -17,4 +58,29 @@ import type { TelemetryType } from '../../types.js';
  * @param telemetry - Array of telemetry types to enable
  */
 export declare function startSessionViaDaemon(url: string, options: SessionStartOptions, telemetry: TelemetryType[]): Promise<never>;
+/**
+ * Start a session, retrying while the previous session shuts down. After a
+ * failure the daemon reported (or a dropped connection), it waits for every
+ * daemon the attempts spawned to exit ({@link afterSpawnedDaemonExit}).
+ *
+ * @param url - Target URL
+ * @param options - Session options
+ * @param telemetry - Telemetry types
+ * @param deps - How to reach the daemon (tests replace it)
+ * @returns Start outcome, ready to report
+ */
+export declare function attemptStart(url: string, options: SessionStartOptions, telemetry: TelemetryType[], deps?: StartDeps): Promise<StartOutcome>;
+/**
+ * Let the daemons a failed start spawned finish exiting before the error is
+ * reported: a daemon removes its session files on the way out, and a command
+ * run right after (`bdg sessions`, another start) would otherwise still see
+ * the session as starting. The wait is bounded; a daemon still running after
+ * it is reported (`details.daemonStillRunning`, `daemonPid`, a suggestion).
+ *
+ * @param outcome - Start outcome
+ * @param spawned - Exiting daemons the attempts spawned
+ * @param waitMs - Milliseconds to wait at most for all of them
+ * @returns The failure (without internal fields), with a hint when a daemon did not exit in time
+ */
+export declare function afterSpawnedDaemonExit(outcome: StartOutcome, spawned: SpawnedDaemon[], waitMs: number): Promise<StartOutcome>;
 //# sourceMappingURL=startHelpers.d.ts.map