browser-debugger-cli 0.8.0 → 0.10.0

package/dist/ui/formatters/dom.js

@@ -1,28 +1,17 @@
+import { keyAttributeItems } from './keyAttributes.js';
 import { OutputFormatter } from '../formatting.js';
-import { evalFrameLine, frameLabel, moreMatchesNote, noFramesMessage, } from '../messages/commands.js';
-import { parseSelectorFilters } from '../../utils/selectorFilters.js';
+import { frameLabel, moreMatchesNote, framesStillLoadingNote, noFramesMessage, queryNextSteps, screenshotGrownNote, viewportPositionHint, } from '../messages/commands.js';
 /** Matches listed in human output (JSON has all of them) */
 const QUERY_DISPLAY_LIMIT = 50;
-/**
- * A shell-quoted `dom eval` script reading the text (or a field's value) of
- * the n-th match in the main document, as rendered (null for matches inside iframes or
- * shadow roots, which `document.querySelectorAll` does not reach).
- *
- * @param selector - CSS selector
- * @param index - Match to read
- * @returns Single-quoted script, safe to paste into a shell
- */
-function textExtractionScript(selector, index) {
-    const script = `(el => el && (el.value ?? el.innerText))(document.querySelectorAll(${JSON.stringify(selector)})[${index}])`;
-    return `'${script.replace(/'/g, `'\\''`)}'`;
-}
 /**
  * Format DOM query results for human-readable output.
  *
- * Displays found nodes with their index, tag, classes, and preview text,
- * up to {@link QUERY_DISPLAY_LIMIT} of them (no match is an error, exit 83).
- * The text extraction hint is left out for selectors with text or visibility
- * filters, which `document.querySelectorAll` does not understand.
+ * Displays found nodes with their index, tag, identifying attributes
+ * ({@link queryTagAttributes}), classes, and preview text
+ * (plus where they are when outside the viewport or hidden, e.g.
+ * `(below fold)`), up to {@link QUERY_DISPLAY_LIMIT} of them (no match is an error, exit 83).
+ * One line of next commands follows; they take the match's index, so they
+ * work for matches in shadow roots and iframes too.
  *
  * @param data - DOM query result containing selector, count, and matching nodes
  * @returns Formatted output string
@@ -47,33 +36,43 @@ export function formatDomQuery(data) {
     const { count, nodes, selector } = data;
     const fmt = new OutputFormatter();
     const nodeLines = nodes.slice(0, QUERY_DISPLAY_LIMIT).map((node) => {
-        const attributes = [
-            node.id && ` id="${node.id}"`,
-            node.name && ` name="${node.name}"`,
-            node.type && ` type="${node.type}"`,
-            node.classes?.length && ` class="${node.classes.join(' ')}"`,
-        ]
-            .filter(Boolean)
+        const attributes = queryTagAttributes(node)
+            .map((item) => ` ${item}`)
             .join('');
         const context = node.context ? ` (in ${node.context})` : '';
         const preview = node.preview ? ` ${node.preview}` : '';
-        return `[${node.index}] <${node.tag}${attributes}>${context}${preview}`;
+        const position = node.inViewport && viewportPositionHint(node.inViewport, node.clippedBy);
+        const location = position ? ` (${position})` : '';
+        return `[${node.index}] <${node.tag}${attributes}>${context}${preview}${location}`;
     });
-    const hasMultipleResults = count > 1;
-    const exampleIndex = hasMultipleResults ? (nodes[0]?.index ?? 0) : 0;
+    const exampleIndex = nodes[0]?.index ?? 0;
     return fmt
         .text(`Found ${count} node${count === 1 ? '' : 's'} matching "${selector}":`)
         .list(nodeLines)
         .list(count > QUERY_DISPLAY_LIMIT ? [moreMatchesNote(count - QUERY_DISPLAY_LIMIT)] : [])
-        .hints('Next steps:', [
-        `Get HTML:        bdg dom get ${exampleIndex} --raw`,
-        `Accessibility:   bdg dom get ${exampleIndex}`,
-        ...(parseSelectorFilters(selector)
-            ? []
-            : [`Extract text:    bdg dom eval ${textExtractionScript(selector, exampleIndex)}`]),
-    ])
+        .tip(queryNextSteps(exampleIndex))
         .build();
 }
+/**
+ * The attributes shown in a `dom query` match's tag: id, then name, type and
+ * the key attributes of its type ({@link keyAttributeItems}: an image's file
+ * name and alt, a link's href, a field's placeholder and value), then class.
+ *
+ * @param node - Query match
+ * @returns `name="value"` items
+ */
+function queryTagAttributes(node) {
+    const identifying = {
+        ...(node.name && { name: node.name }),
+        ...(node.type && { type: node.type }),
+        ...(node.value !== undefined && { value: node.value }),
+    };
+    return [
+        ...(node.id ? [`id="${node.id}"`] : []),
+        ...keyAttributeItems(node.tag ?? '', { ...identifying, ...node.attributes }),
+        ...(node.classes?.length ? [`class="${node.classes.join(' ')}"`] : []),
+    ];
+}
 /**
  * Format DOM get results for human-readable output.
  *
@@ -118,18 +117,23 @@ export function formatDomGet(data) {
 /**
  * Format DOM eval results for human-readable output.
  *
- * Outputs the evaluated JavaScript result as formatted JSON, preceded by a
- * `Frame: <url>` line when it ran in an iframe (`--frame`).
+ * A string result is printed as is (not JSON-quoted), so text reads and
+ * pipes like `echo`, unless that would read as another value (empty,
+ * `undefined`, or valid JSON such as `42` or `[1,2]`): then it stays
+ * JSON-quoted. Other values are formatted JSON, and values Chrome only
+ * describes (functions, DOM nodes) their description. The iframe it ran in
+ * (`--frame`) is reported on stderr, so stdout stays the bare value. `--json`
+ * output is unchanged (the value in `data.result`).
  *
- * @param data - DOM eval result containing the evaluated value (and its frame)
- * @returns Formatted JSON string
+ * @param data - DOM eval result containing the evaluated value
+ * @returns The string, or formatted JSON
  *
  * @example
  * ```typescript
- * formatDomEval({ result: 'My Page Title' });
- * // Output: "My Page Title"
+ * formatDomEval({ result: 'My Page Title', type: 'string' });
+ * // Output: My Page Title
  *
- * formatDomEval({ result: { url: 'https://example.com', title: 'Example' } });
+ * formatDomEval({ result: { url: 'https://example.com', title: 'Example' }, type: 'object' });
  * // Output:
  * // {
  * //   "url": "https://example.com",
@@ -138,39 +142,58 @@ export function formatDomGet(data) {
  * ```
  */
 export function formatDomEval(data) {
-    const value = formatEvalValue(data);
-    return data.frame === undefined ? value : `${evalFrameLine(data.frame)}\n${value}`;
+    if (data.type === 'undefined')
+        return 'undefined';
+    const { result } = data;
+    if (typeof result === 'string' && (data.type !== 'string' || !looksLikeOtherValue(result))) {
+        return result;
+    }
+    return JSON.stringify(result ?? null, null, 2);
 }
 /**
- * Format an eval result value: descriptions as is, JSON values pretty-printed.
+ * Whether a string printed as is would read as another value: empty,
+ * `undefined`, or valid JSON (`42`, `true`, `null`, `[1,2]`, `{"a":1}`).
  *
- * @param data - Result value and its JavaScript type
- * @returns Formatted value
+ * @param text - String result
+ * @returns True when it must be JSON-quoted to read as a string
  */
-function formatEvalValue(data) {
-    if (data.type === 'undefined')
-        return 'undefined';
-    const isDescription = typeof data.result === 'string' && data.type !== 'string';
-    if (isDescription)
-        return data.result;
-    return JSON.stringify(data.result ?? null, null, 2);
+function looksLikeOtherValue(text) {
+    if (text === '' || text === 'undefined')
+        return true;
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /**
- * Format the page's iframes, one per line.
+ * Format the page's iframes, one per line, nested frames indented below
+ * their parent. While the page is still loading (`readyState` set), the list
+ * may be incomplete, and says so.
  *
- * @param data - Frames from `bdg dom frames`
+ * @param data - Frames from `bdg dom frames`, with the readyState of a page still loading
  * @returns Formatted list
  *
  * @example
  * ```
  * [0] http://localhost:3000/widget  name=widget  same-origin
  * [1] https://pay.example/  #checkout  cross-origin, out-of-process
+ *   [2] about:blank  same-origin
  * ```
  */
 export function formatDomFrames(data) {
+    const loading = data.readyState !== undefined && data.readyState !== 'complete';
     if (data.frames.length === 0)
-        return noFramesMessage();
-    return data.frames.map(frameLabel).join('\n');
+        return loading ? framesStillLoadingNote(true) : noFramesMessage();
+    const depthOf = new Map();
+    const lines = data.frames.map((frame) => {
+        const depth = frame.parentIndex === undefined ? 0 : (depthOf.get(frame.parentIndex) ?? 0) + 1;
+        depthOf.set(frame.index, depth);
+        return '  '.repeat(depth) + frameLabel(frame);
+    });
+    return [...lines, ...(loading ? [framesStillLoadingNote(false)] : [])].join('\n');
 }
 /**
  * Format screenshot capture result for human-readable display.
@@ -187,6 +210,9 @@ export function formatDomFrames(data) {
  *
  * formatDomScreenshot({ path: './page.png', fullPageSkipped: { reason: 'page_too_tall', ... } });
  * // Output: Screenshot saved to ./page.png (viewport only - page too tall)
+ *
+ * // An element whose floated children overflow it
+ * // Output: Screenshot saved to ./el.png (grown from 940×37 to 940×285 to include content overflowing the element)
  * ```
  */
 export function formatDomScreenshot(data) {
@@ -194,6 +220,9 @@ export function formatDomScreenshot(data) {
     if (data.fullPageSkipped && !data.scrolledTo) {
         output += ' (viewport only - page too tall)';
     }
+    if (data.element?.captured) {
+        output += ` (${screenshotGrownNote(data.element.bounds, data.element.captured)})`;
+    }
     return output;
 }
 //# sourceMappingURL=dom.js.map

package/dist/ui/formatters/form.js

@@ -5,6 +5,7 @@
  * values, validation state, and suggested commands.
  */
 import { OutputFormatter, areHintsHidden } from '../formatting.js';
+import { REQUIRED_FIELD_EMPTY_REASON, formReadinessMessage, requiredFieldsEmptyMessage, } from '../messages/commands.js';
 const COLUMN_WIDTHS = {
     index: 4,
     type: 12,
@@ -64,6 +65,9 @@ function formatFieldValue(field) {
  * @returns Status string with icon
  */
 function formatFieldStatus(field) {
+    if (field.hidden) {
+        return 'hidden';
+    }
     if (field.disabled) {
         return 'disabled';
     }
@@ -127,12 +131,23 @@ function formatButtonRow(button) {
  * @returns Header string
  */
 function formatFormHeader(form) {
-    let header = `Form: "${form.name ?? 'Unnamed'}"`;
+    let header = `Form: "${form.name ?? 'Unnamed'}"${formVisibilityMarker(form)}`;
     if (form.step) {
         header += ` (step ${form.step.current} of ${form.step.total})`;
     }
     return header;
 }
+/**
+ * Marker of a form shown in an open dialog or not shown at all.
+ *
+ * @param form - Form (or its listing in "Other forms")
+ * @returns ` (in dialog)`, ` (hidden)`, or empty
+ */
+function formVisibilityMarker(form) {
+    if (form.hidden)
+        return ' (hidden)';
+    return form.inDialog ? ' (in dialog)' : '';
+}
 /**
  * Format table header row.
  *
@@ -147,7 +162,9 @@ function formatTableHeader() {
     return `${idx}  ${type} ${label} ${value} ${status}`;
 }
 /**
- * Format summary line.
+ * Format summary line, e.g. "Summary: 1/3 fields filled | 2 required fields
+ * empty: Last Name, Zip | NOT ready" (a radio or checkbox group counts as one
+ * field).
  *
  * @param summary - Form summary
  * @returns Summary string
@@ -158,15 +175,12 @@ function formatSummaryLine(summary) {
     if (summary.invalidFields > 0) {
         parts.push(`${summary.invalidFields} invalid`);
     }
-    if (summary.requiredRemaining > 0) {
-        parts.push(`${summary.requiredRemaining} required remaining`);
-    }
-    if (summary.readyToSubmit) {
-        parts.push('READY to submit');
-    }
-    else {
-        parts.push('NOT ready');
-    }
+    const requiredEmpty = summary.blockers
+        .filter((blocker) => blocker.reason === REQUIRED_FIELD_EMPTY_REASON)
+        .map((blocker) => blocker.label);
+    if (requiredEmpty.length > 0)
+        parts.push(requiredFieldsEmptyMessage(requiredEmpty));
+    parts.push(formReadinessMessage(summary));
     return `Summary: ${parts.join(' | ')}`;
 }
 /**
@@ -197,9 +211,7 @@ function formatSingleForm(form, fmt, brief = false) {
     fmt.text(formatTableHeader());
     fmt.text('─'.repeat(70));
     for (const field of form.fields) {
-        if (!field.hidden) {
-            fmt.text(formatFieldRow(field));
-        }
+        fmt.text(formatFieldRow(field));
     }
     if (form.buttons.length > 0) {
         fmt.text('─'.repeat(70));
@@ -228,13 +240,12 @@ function formatBriefFields(form, fmt) {
     fmt.text('IDX  TYPE         LABEL                    REQ VALUE');
     fmt.text('─'.repeat(70));
     for (const field of form.fields) {
-        if (field.hidden)
-            continue;
         const idx = `[${field.index}]`.padEnd(4);
         const type = (field.inputType ?? field.type).slice(0, 11).padEnd(12);
         const label = (field.label ?? field.name ?? '(no label)').slice(0, 23).padEnd(24);
         const req = (field.required ? '*' : '').padEnd(3);
-        fmt.text(`${idx} ${type} ${label} ${req} ${formatFieldValue(field)}`);
+        const hidden = field.hidden ? ' (hidden)' : '';
+        fmt.text(`${idx} ${type} ${label} ${req} ${formatFieldValue(field)}${hidden}`);
     }
     if (form.buttons.length > 0) {
         fmt.text('─'.repeat(70));
@@ -258,7 +269,7 @@ function formatOtherForms(others, fmt) {
     fmt.blank();
     fmt.text('Other forms on page:');
     for (const form of others) {
-        fmt.text(`  Form ${form.index}: "${form.name ?? 'Unnamed'}" - ${form.fieldCount} field(s)`);
+        fmt.text(`  Form ${form.index}: "${form.name ?? 'Unnamed'}"${formVisibilityMarker(form)} - ${form.fieldCount} field(s)`);
     }
     fmt.blank();
     fmt.text('Use --all to see all forms');

package/dist/ui/formatters/inspect.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Human output of `bdg dom inspect`: a header line, then one line per group
+ * in Figma's order with DevTools' names (box, layout, parent, text, fill,
+ * border, fx, state, pseudo), then the child tree. Fields within a line are
+ * separated by ` · `; lengths are CSS px without the unit.
+ *
+ * ```
+ * button#buy.btn "Buy now" 120x41 @20,20 [flex] [prefers light]
+ * box    p 12 24 · b 1
+ * layout inline-flex row · gap 8
+ * parent div.card flex column · gap 16 · in-parent l0 t0 r180 b0 · sib b16
+ * text   Inter (webfont) 600 16/24 · color #fff · contrast 5.17 AA
+ * fill   bg #1c69e3
+ * border 1 solid #32447f · radius 8
+ * ```
+ */
+import type { InspectResult } from '../../ipc/protocol/inspectTypes.js';
+import type { IndexSource } from '../../types.js';
+/** `bdg dom inspect` data (the `success` flag is implied by the envelope), with the list an index refers to */
+export type InspectOutput = Omit<InspectResult, 'success'> & {
+    indexSource?: IndexSource | undefined;
+};
+/**
+ * The header: label, text, size and position, layout badge, what keeps it
+ * from being seen, where it lives and the color scheme.
+ *
+ * @param data - Inspect result
+ * @returns Header line
+ */
+export declare function inspectHeader(data: InspectOutput): string;
+/**
+ * Format `bdg dom inspect` output (`--why` answers only its question:
+ * the header, hints and the declarations, no style groups or tree).
+ *
+ * @param data - Inspect result
+ * @returns Formatted output
+ */
+export declare function formatInspect(data: InspectOutput): string;
+//# sourceMappingURL=inspect.d.ts.map