browser-debugger-cli 0.9.0 → 0.11.0

package/dist/errors/messages.d.ts

@@ -595,6 +595,17 @@ export declare function unreachableElementsNote(selector: string, unsearched?: U
  * @returns e.g. `Did you mean #remove-backpack? (similar id on the page)`; empty without names
  */
 export declare function similarSelectorsLine(kind: 'id' | 'class', names: string[]): string;
+/**
+ * A selector that would have to cross into a shadow root: selectors cannot,
+ * but bdg searches open shadow roots on its own.
+ *
+ * @param host - The compound matching the host, and the selector after it
+ * @returns e.g. `mdn-search-modal hosts a shadow root, which a selector cannot cross into; bdg searches open shadow roots itself: use "form"`
+ */
+export declare function shadowBoundaryLine(host: {
+    compound: string;
+    rest: string;
+}): string;
 /** What the page says about a selector that matched nothing */
 export interface NoMatchContext {
     /** Elements only its `:visible` filters excluded */
@@ -605,6 +616,11 @@ export interface NoMatchContext {
     unsearched?: UnsearchedContent;
     /** "Did you mean" line for a single id or class ({@link similarSelectorsLine}) */
     similar?: string;
+    /** A leading compound that matches a shadow host, and the selector after it */
+    shadowHost?: {
+        compound: string;
+        rest: string;
+    };
 }
 /**
  * No nodes found for selector.
@@ -768,6 +784,33 @@ export declare function clickableElementNotFoundError(selector: string): ErrorWi
  * Click target disappeared between locating and clicking it.
  */
 export declare function clickTargetDetachedError(selector: string): ErrorWithSuggestion;
+/**
+ * A pointer action refused under `--strict` because a real mouse could not
+ * reach the element (covered, hidden, zero-size, pointer-events: none).
+ *
+ * @param target - Selector and element description, as the click located it
+ * @param reason - Why the mouse could not reach it, e.g. "covered by another element (div#shield)"
+ * @param verb - What was refused, e.g. "click", "hover"
+ * @returns Message naming the obstruction, and how to inspect it
+ */
+export declare function unreachableElementError(target: {
+    selector: string;
+    element?: string | undefined;
+}, reason: string | null | undefined, verb: string): ErrorWithSuggestion;
+/**
+ * A mouse press refused under `--strict` because it did not reach the
+ * element: it was sent, but landed on another element, or the page never
+ * saw it (a browser dialog or bubble captured the input).
+ *
+ * @param target - Selector and element description, as the click located it
+ * @param verb - What was refused, e.g. "click"
+ * @param landedOn - The element the press landed on, when the page saw it
+ * @returns Message, and how to inspect the page
+ */
+export declare function pressNotReceivedError(target: {
+    selector: string;
+    element?: string | undefined;
+}, verb: string, landedOn?: string): ErrorWithSuggestion;
 /**
  * Key press failed.
  */
@@ -815,6 +858,13 @@ export declare function emptyFrameError(): ErrorWithSuggestion;
  * @param frames - Frames of the page
  */
 export declare function frameNotFoundError(query: string, frames: DomFrame[]): ErrorWithSuggestion;
+/**
+ * A `dom eval --frame` index that names another frame (or none) than when
+ * `bdg dom frames` listed it.
+ *
+ * @param index - Requested index
+ */
+export declare function staleFrameIndexError(index: number): ErrorWithSuggestion;
 /**
  * `dom eval --frame` matching more than one iframe.
  *
@@ -876,6 +926,14 @@ export declare function unexpectedResponseFormatError(context: string): ErrorWit
  * Generic operation failure with dynamic error message.
  */
 export declare function operationFailedError(operation: string, errorMessage: string): ErrorWithSuggestion;
+/**
+ * `dom inspect --props` named a property the element has no value for.
+ *
+ * @param names - Unknown property names
+ * @param suggestions - Similar computed property names
+ * @returns Message and suggestion
+ */
+export declare function unknownCssPropertyError(names: string[], suggestions: string[]): ErrorWithSuggestion;
 /**
  * The browser does not offer `DOMDebugger.getEventListeners` (non-Chrome
  * targets, or browsers that disable the DOMDebugger domain).
@@ -904,5 +962,32 @@ export declare function formDiscoveryFailedError(detail: string, readyState?: st
  * Form in iframe (cross-origin or same-origin).
  */
 export declare function formInIframeError(iframeUrl: string, crossOrigin: boolean): ErrorWithSuggestion;
+/**
+ * `bdg cdp` when Chrome rejected the call: a missing node, target or
+ * frame, or wrong parameters.
+ *
+ * @param method - CDP method
+ * @param message - Chrome's error
+ * @returns Message, suggestion, and whether something named was not found
+ */
+export declare function cdpCallError(method: string, message: string): ErrorWithSuggestion & {
+    notFound: boolean;
+};
+/**
+ * The skill file is not where the package should have it (a broken or
+ * partial install).
+ *
+ * @param source - Expected SKILL.md path
+ * @returns Message and suggestion
+ */
+export declare function skillSourceMissingError(source: string): ErrorWithSuggestion;
+/**
+ * The skill could not be written to an agent's skill directory.
+ *
+ * @param path - Destination SKILL.md
+ * @param reason - The file system error
+ * @returns Message and suggestion
+ */
+export declare function skillWriteFailedError(path: string, reason: string): ErrorWithSuggestion;
 export {};
 //# sourceMappingURL=messages.d.ts.map

package/dist/errors/messages.js

@@ -999,6 +999,16 @@ export function similarSelectorsLine(kind, names) {
     const plural = names.length === 1 ? what : kind === 'id' ? 'ids' : 'classes';
     return `Did you mean ${names.map((name) => sigil + name).join(', ')}? (similar ${plural} on the page)`;
 }
+/**
+ * A selector that would have to cross into a shadow root: selectors cannot,
+ * but bdg searches open shadow roots on its own.
+ *
+ * @param host - The compound matching the host, and the selector after it
+ * @returns e.g. `mdn-search-modal hosts a shadow root, which a selector cannot cross into; bdg searches open shadow roots itself: use "form"`
+ */
+export function shadowBoundaryLine(host) {
+    return `${host.compound} hosts a shadow root, which a selector cannot cross into; bdg searches open shadow roots itself: use "${host.rest}"`;
+}
 /**
  * No nodes found for selector.
  *
@@ -1015,7 +1025,7 @@ export function noNodesFoundError(selector, context = {}) {
     const note = unreachableElementsNote(selector, context.unsearched);
     return {
         message: `No nodes found matching "${selector}"`,
-        suggestion: withLoadingHint(joinLines(context.similar, `${hidden}Verify the CSS selector is correct.`, note ? note : undefined), context.readyState, selector),
+        suggestion: withLoadingHint(joinLines(context.similar, context.shadowHost && shadowBoundaryLine(context.shadowHost), `${hidden}Verify the CSS selector is correct.`, note ? note : undefined), context.readyState, selector),
     };
 }
 /**
@@ -1326,6 +1336,42 @@ export function clickTargetDetachedError(selector) {
         suggestion: 'The page changed during the click; wait for it to settle and retry',
     };
 }
+/**
+ * A pointer action refused under `--strict` because a real mouse could not
+ * reach the element (covered, hidden, zero-size, pointer-events: none).
+ *
+ * @param target - Selector and element description, as the click located it
+ * @param reason - Why the mouse could not reach it, e.g. "covered by another element (div#shield)"
+ * @param verb - What was refused, e.g. "click", "hover"
+ * @returns Message naming the obstruction, and how to inspect it
+ */
+export function unreachableElementError(target, reason, verb) {
+    const element = target.element ?? target.selector;
+    return {
+        message: `Did not ${verb} ${element}: it is ${reason ?? 'not reachable by the mouse'}, so a user could not ${verb} it (--strict)`,
+        suggestion: `See what is in the way with ${sessionCommand(`bdg dom layout ${shellQuote(target.selector)}`)}, then close the overlay or scroll; without --strict bdg uses DOM events instead`,
+    };
+}
+/**
+ * A mouse press refused under `--strict` because it did not reach the
+ * element: it was sent, but landed on another element, or the page never
+ * saw it (a browser dialog or bubble captured the input).
+ *
+ * @param target - Selector and element description, as the click located it
+ * @param verb - What was refused, e.g. "click"
+ * @param landedOn - The element the press landed on, when the page saw it
+ * @returns Message, and how to inspect the page
+ */
+export function pressNotReceivedError(target, verb, landedOn) {
+    const element = target.element ?? target.selector;
+    const where = landedOn === undefined
+        ? 'the page saw no press: the browser may be showing a dialog or bubble that captures input'
+        : `landed on ${landedOn}`;
+    return {
+        message: `Did not ${verb} ${element}: the press did not reach the element (it was sent, but ${where}) (--strict)`,
+        suggestion: `Check the page with ${sessionCommand('bdg dom screenshot page.png')} and ${sessionCommand(`bdg dom layout ${shellQuote(target.selector)}`)}`,
+    };
+}
 /**
  * Key press failed.
  */
@@ -1425,6 +1471,18 @@ export function frameNotFoundError(query, frames) {
         suggestion: joinLines('Available frames:', ...frames.map((frame) => `  ${frameLabel(frame)}`)),
     };
 }
+/**
+ * A `dom eval --frame` index that names another frame (or none) than when
+ * `bdg dom frames` listed it.
+ *
+ * @param index - Requested index
+ */
+export function staleFrameIndexError(index) {
+    return {
+        message: `Frame index ${index} is stale: the page's iframes changed since bdg dom frames listed them`,
+        suggestion: 'Re-run bdg dom frames to refresh the indices, or pick the frame by name, id or URL (--frame <name>)',
+    };
+}
 /**
  * `dom eval --frame` matching more than one iframe.
  *
@@ -1585,6 +1643,22 @@ export function operationFailedError(operation, errorMessage) {
         suggestion: errorMessage,
     };
 }
+/**
+ * `dom inspect --props` named a property the element has no value for.
+ *
+ * @param names - Unknown property names
+ * @param suggestions - Similar computed property names
+ * @returns Message and suggestion
+ */
+export function unknownCssPropertyError(names, suggestions) {
+    const plural = names.length > 1;
+    return {
+        message: `Unknown CSS ${plural ? 'properties' : 'property'}: ${names.join(', ')}`,
+        suggestion: suggestions.length > 0
+            ? `Did you mean: ${suggestions.join(', ')}?`
+            : 'Use CSS property names as in a stylesheet (e.g. --props padding-top,color,--brand); bdg dom inspect <selector> --all lists the set ones',
+    };
+}
 /**
  * The browser does not offer `DOMDebugger.getEventListeners` (non-Chrome
  * targets, or browsers that disable the DOMDebugger domain).
@@ -1650,4 +1724,57 @@ export function formInIframeError(iframeUrl, crossOrigin) {
             : 'dom form lists forms of the main document only; its fields are reachable directly: bdg dom query "input, select, textarea", then bdg dom fill <index> <value>',
     };
 }
+/** CDP error messages that name something that does not exist (a node, target, frame…) */
+const CDP_NOT_FOUND_PATTERN = /could not find|cannot find|not found|no \w+ (with|for) (the )?given|does not exist|no such/i;
+/**
+ * `bdg cdp` when Chrome rejected the call: a missing node, target or
+ * frame, or wrong parameters.
+ *
+ * @param method - CDP method
+ * @param message - Chrome's error
+ * @returns Message, suggestion, and whether something named was not found
+ */
+export function cdpCallError(method, message) {
+    if (CDP_NOT_FOUND_PATTERN.test(message)) {
+        const ids = /node/i.test(message)
+            ? 'Node ids come from DOM.getDocument (the root) or DOM.querySelector, and a new DOM.getDocument or a navigation replaces them; '
+            : '';
+        return {
+            message: `${method}: ${message}`,
+            suggestion: `${ids}check the ids with ${sessionCommand(`bdg cdp ${method} --describe`)}`,
+            notFound: true,
+        };
+    }
+    return {
+        message: `${method}: ${message}`,
+        suggestion: `See the parameters with ${sessionCommand(`bdg cdp ${method} --describe`)}`,
+        notFound: false,
+    };
+}
+/**
+ * The skill file is not where the package should have it (a broken or
+ * partial install).
+ *
+ * @param source - Expected SKILL.md path
+ * @returns Message and suggestion
+ */
+export function skillSourceMissingError(source) {
+    return {
+        message: `The bdg skill is missing from the installed package (${source})`,
+        suggestion: 'Reinstall bdg: npm install -g browser-debugger-cli',
+    };
+}
+/**
+ * The skill could not be written to an agent's skill directory.
+ *
+ * @param path - Destination SKILL.md
+ * @param reason - The file system error
+ * @returns Message and suggestion
+ */
+export function skillWriteFailedError(path, reason) {
+    return {
+        message: `Could not write ${path}: ${reason}`,
+        suggestion: 'Check the permissions of that directory, or install for the other agent only (--claude or --agents)',
+    };
+}
 //# sourceMappingURL=messages.js.map