browser-debugger-cli 0.8.0 → 0.9.0

package/dist/errors/messages.d.ts

@@ -3,9 +3,12 @@
  *
  * Centralized location for reusable error messages with consistent formatting.
  */
-import type { DomFrame } from '../ipc/protocol/commands.js';
+import type { DomFrame, PendingRequestInfo } from '../ipc/protocol/commands.js';
+import { type WaitCondition, type WaitSnapshot } from '../runtime/dom/waitCondition.js';
+import type { DocumentRequestState, IndexSource } from '../types.js';
 /**
- * Generate "session already running" error message.
+ * Generate "session already running" error message (commands carry
+ * `--session` for a named session).
  *
  * @param pid - Process ID of running session
  * @param duration - Session duration in milliseconds
@@ -19,8 +22,19 @@ import type { DomFrame } from '../ipc/protocol/commands.js';
  * ```
  */
 export declare function sessionAlreadyRunningError(pid: number, duration: number, targetUrl?: string): string;
-/** What to do when `bdg <url>` finds a session already running */
-export declare const ALREADY_RUNNING_SUGGESTION = "Use the running session (bdg status), or stop it first: bdg stop && bdg <url>";
+/**
+ * The daemon's one-line answer to `bdg <url>` while its session runs.
+ *
+ * @param pid - Daemon PID
+ * @returns Message
+ */
+export declare function sessionAlreadyRunningMessage(pid: number): string;
+/**
+ * What to do when `bdg <url>` finds the selected session already running.
+ *
+ * @returns Suggestion
+ */
+export declare function alreadyRunningSuggestion(): string;
 /**
  * Human-readable description of a bdg-launched Chrome (as opposed to one
  * reached via `--chrome-ws-url`). Used in mismatch errors where the active
@@ -157,6 +171,15 @@ export interface ErrorWithSuggestion {
  * Index out of range error.
  */
 export declare function indexOutOfRangeError(index: number, max: number): ErrorWithSuggestion;
+/** Finding elements by accessible name, quoted for the shell (the name may contain spaces and colons). */
+export declare const A11Y_NAME_QUERY_EXAMPLE = "bdg dom a11y query 'name=\u2026'";
+/**
+ * Empty (or blank) selector: the browser rejects it, so it is caught before
+ * any page script runs.
+ *
+ * @returns Message and suggestion
+ */
+export declare function emptySelectorError(): ErrorWithSuggestion;
 /**
  * CSS selector rejected by the browser. Playwright-only syntax (`:text()`,
  * `>>`, `text=`) gets the filters bdg supports instead.
@@ -167,14 +190,59 @@ export declare function indexOutOfRangeError(index: number, max: number): ErrorW
  */
 export declare function invalidSelectorError(selector: string, detail?: string): ErrorWithSuggestion;
 /**
- * A text or visibility filter (`:has-text()`, `:text-is()`, `:visible`) that
- * is not at the end of a selector.
+ * A text or visibility filter (`:has-text()`, `:text-is()`, `:visible`)
+ * inside a pseudo-class other than `:has()`, e.g. `:not(:visible)`.
  *
  * @param selector - Selector as given
  * @param filter - The misplaced filter as written
  * @returns Message and suggestion
  */
 export declare function misplacedSelectorFilterError(selector: string, filter: string): ErrorWithSuggestion;
+/**
+ * A sibling combinator (`+`, `~`) after a filtered compound: the rest of the
+ * selector is matched under the filtered element, so only descendant and
+ * child combinators can follow it.
+ *
+ * @param selector - Selector as given
+ * @param combinator - The combinator found
+ * @returns Message and suggestion
+ */
+export declare function siblingAfterFilterError(selector: string, combinator: string): ErrorWithSuggestion;
+/**
+ * A `:has()` with filters whose selector starts with a sibling combinator
+ * (`:has(+ a:visible)`): its matches are searched under the element, where
+ * siblings are not.
+ *
+ * @param selector - Selector as given
+ * @param combinator - `+` or `~`
+ * @returns Message and suggestion
+ */
+export declare function siblingInHasError(selector: string, combinator: string): ErrorWithSuggestion;
+/** How a selector with filters is malformed (before the browser sees it). */
+declare const MALFORMED_SELECTOR_DETAILS: {
+    readonly 'empty-in-list': () => string;
+    readonly 'leading-combinator': (combinator: string) => string;
+    readonly 'trailing-combinator': () => string;
+    readonly 'empty-has': () => string;
+    readonly 'scope-in-has': () => string;
+};
+/**
+ * A selector with filters that is malformed in a way bdg detects while
+ * splitting it (so the error shows the selector as given, not rewritten CSS).
+ *
+ * @param selector - Selector as given
+ * @param problem - What is wrong
+ * @param combinator - The combinator, for `leading-combinator`
+ * @returns Message and suggestion
+ */
+export declare function malformedSelectorError(selector: string, problem: keyof typeof MALFORMED_SELECTOR_DETAILS, combinator?: string): ErrorWithSuggestion;
+/**
+ * `:has-text()` with empty text, which every element would match.
+ *
+ * @param selector - Selector as given
+ * @returns Message and suggestion
+ */
+export declare function emptyTextFilterError(selector: string): ErrorWithSuggestion;
 /**
  * A text filter without its text, e.g. `:has-text` or `:text-is("x"`.
  *
@@ -214,6 +282,21 @@ export declare function emptyOutputPathError(extension?: string): ErrorWithSugge
  * Start options given without the URL to open.
  */
 export declare function missingStartUrlError(): ErrorWithSuggestion;
+/**
+ * `--viewport` given something that is not a width and height.
+ *
+ * @param value - What was given
+ * @param max - Largest side accepted
+ */
+export declare function invalidViewportError(value: string, max: number): ErrorWithSuggestion;
+/**
+ * `--color-scheme` given another value than the ones it takes.
+ *
+ * @param value - What was given
+ * @param similar - Close matches
+ * @param schemes - Accepted values
+ */
+export declare function invalidColorSchemeError(value: string, similar: string[], schemes: readonly string[]): ErrorWithSuggestion;
 /**
  * `-u` / `--user-data-dir` given something that is not a directory path.
  *
@@ -221,6 +304,34 @@ export declare function missingStartUrlError(): ErrorWithSuggestion;
  * @param reason - Why it cannot be used
  */
 export declare function invalidUserDataDirError(value: string, reason: string): ErrorWithSuggestion;
+/**
+ * A `--session` / `BDG_SESSION` name bdg cannot use as a directory name.
+ *
+ * @param name - The rejected name
+ * @param maxLength - Longest allowed name
+ */
+export declare function invalidSessionNameError(name: string, maxLength: number): ErrorWithSuggestion;
+/**
+ * A session name whose daemon socket path would exceed the OS limit.
+ *
+ * @param name - Session name
+ * @param socketPath - Resulting socket path
+ * @param max - Longest socket path in bytes
+ */
+export declare function sessionNameSocketTooLongError(name: string, socketPath: string, max: number): ErrorWithSuggestion;
+/**
+ * `bdg cleanup --purge` without a named session (the default session's
+ * directory holds the named sessions).
+ */
+export declare function purgeNeedsNamedSessionError(): ErrorWithSuggestion;
+/**
+ * `bdg cleanup --purge` found the session still holding its directory after
+ * cleaning up, so the directory is kept.
+ *
+ * @param dir - Session directory
+ * @param reason - What still holds it
+ */
+export declare function purgeRefusedError(dir: string, reason: string): ErrorWithSuggestion;
 /**
  * The session directory exists but is not a directory.
  *
@@ -248,6 +359,27 @@ export declare function socketPathTooLongError(socketPath: string, max: number):
  * @param secure - Whether a wss: URL was given
  */
 export declare function externalChromeUnreachableError(endpoint: string, secure: boolean): ErrorWithSuggestion;
+/**
+ * Something answers on the `--chrome-ws-url` endpoint, but it is not Chrome's
+ * DevTools HTTP endpoint (e.g. a web server on that port).
+ *
+ * @param endpoint - e.g. http://127.0.0.1:3000
+ */
+export declare function notDevToolsEndpointError(endpoint: string): ErrorWithSuggestion;
+/**
+ * Another running bdg session uses the Chrome (or tab) `--chrome-ws-url`
+ * points to.
+ *
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @param owner - The other session: name (null for a default session),
+ *   directory, base directory and whether it launched that Chrome
+ */
+export declare function chromeInUseBySessionError(endpoint: string, owner: {
+    name: string | null;
+    dir: string;
+    baseDir: string;
+    launched: boolean;
+}): ErrorWithSuggestion;
 /**
  * The page id of a `--chrome-ws-url` page URL does not exist.
  *
@@ -272,8 +404,9 @@ export declare function chromeWsUrlConflictError(options: string[]): ErrorWithSu
  * A numeric index given together with `--index`.
  *
  * @param index - The index argument
+ * @param command - The `bdg dom` subcommand it was given to, e.g. "layout"
  */
-export declare function indexWithIndexOptionError(index: string): ErrorWithSuggestion;
+export declare function indexWithIndexOptionError(index: string, command: string): ErrorWithSuggestion;
 /** Problems with `bdg dom scroll` options, and how to fix each */
 declare const SCROLL_PROBLEMS: {
     readonly 'index-without-selector': readonly ["--index requires a selector", "Use: bdg dom scroll \"selector\" --index 2"];
@@ -295,8 +428,15 @@ export declare function scrollOptionsError(problem: keyof typeof SCROLL_PROBLEMS
  * @param similar - Similar key names
  */
 export declare function unknownKeyError(keyName: string, similar: string[]): ErrorWithSuggestion;
-/** Where selectors cannot look, for "not found" errors */
-export declare const UNREACHABLE_ELEMENTS_HINT = "elements in closed shadow roots and cross-origin iframes cannot be reached";
+/**
+ * `dom screenshot` given an element both as an argument and as an option,
+ * and they differ.
+ *
+ * @param option - The option and its value, e.g. `--selector #a`
+ * @param positional - The element argument
+ * @returns Message and suggestion
+ */
+export declare function conflictingTargetError(option: string, positional: string): ErrorWithSuggestion;
 /**
  * Two options given together where one would be ignored.
  *
@@ -347,35 +487,185 @@ export declare function navigationFailedError(url: string, errorText: string): E
  * @param direction - back or forward
  */
 export declare function noHistoryEntryError(direction: 'back' | 'forward'): ErrorWithSuggestion;
+/** What a submit was still waiting for when its wait ran out */
+export interface SubmitBlockers {
+    /** The page request the submit sent, if any */
+    document?: DocumentRequestState | undefined;
+    /** Requests still running (the longest-running first) */
+    pending?: PendingRequestInfo[] | undefined;
+    /** All requests still running */
+    pendingCount?: number | undefined;
+}
 /**
- * The form was submitted but the wait for its result timed out.
+ * The form was submitted but the wait for its result timed out. The message
+ * names what it was waiting on: the page request the submit sent (pending,
+ * answered with an error, failed; waiting for a navigation, also one that
+ * answered), or else the requests still running.
  *
  * @param timeout - Timeout in ms
  * @param waitNavigation - Whether a navigation was awaited
+ * @param blockers - The page request and the requests still running
+ * @returns e.g. `Form submitted, but timed out after 10000ms waiting for navigation: POST …/authenticate pending for 10s`
+ */
+export declare function submitTimeoutError(timeout: number, waitNavigation: boolean, blockers?: SubmitBlockers): ErrorWithSuggestion;
+/**
+ * Warning of a submit whose navigation happened but whose network was still
+ * busy when the wait ran out (the new page is there; a slow script or
+ * tracker kept loading).
+ *
+ * @param timeout - Timeout in ms
+ * @param pending - Requests still in flight
+ * @returns Warning text
  */
-export declare function submitTimeoutError(timeout: number, waitNavigation: boolean): ErrorWithSuggestion;
+export declare function submitNetworkBusyWarning(timeout: number, pending: number): string;
 /**
  * No element has the given node id.
  *
  * @param nodeId - Backend node id given with --node-id
  */
 export declare function nodeIdNotFoundError(nodeId: number): ErrorWithSuggestion;
+/**
+ * The list an index refers to, in words.
+ *
+ * @param source - Where the index comes from
+ * @returns e.g. `index 0 of the last dom query "h3"`, `index 2 of the last dom form`
+ */
+export declare function indexSourceText(source: IndexSource): string;
+/** Why an element's cross-origin iframe could not be placed in the page */
+export type FrameMappingProblem = 'no-box' | 'rotated' | 'unreadable';
+/**
+ * An element of a cross-origin iframe (from an a11y query) whose iframe
+ * could not be placed in the top-level viewport, so a mouse event or layout
+ * would land in the wrong place.
+ *
+ * @param problem - The iframe or element has no box, is rotated or skewed, or could not be read
+ * @param detail - Underlying error, if any
+ * @returns Message and suggestion
+ */
+export declare function frameMappingError(problem: FrameMappingProblem, detail?: string): ErrorWithSuggestion;
 /**
  * A cached node is gone (page navigated or the element was removed).
  *
- * @param index - Index the user gave (query or form results), if any
+ * @param index - Index the user gave, if any
+ * @param source - The list the index refers to, when known
+ * @returns Message and suggestion
+ */
+export declare function staleNodeError(index?: number, source?: IndexSource): ErrorWithSuggestion;
+/**
+ * An index beyond the cached results.
+ *
+ * @param source - The index and the list it refers to
+ * @param count - Number of cached results
+ * @returns Message and suggestion
  */
-export declare function staleNodeError(index?: number): ErrorWithSuggestion;
+export declare function cachedIndexOutOfRangeError(source: IndexSource, count: number): ErrorWithSuggestion;
 /**
- * Element at index not found (stale cache).
+ * Note for a form command (fill, submit) whose index refers to results of
+ * another command and hit an element it cannot act on.
+ *
+ * @param source - The index and the list it refers to
+ * @param preview - What the cached element is, e.g. `h3 "Welcome"`
+ * @returns e.g. `index 0 refers to the last dom query results ("h3": h3 "Welcome"); run bdg dom form to target form fields by index`
  */
-export declare function elementAtIndexNotFoundError(index: number, selector: string): ErrorWithSuggestion;
-/** Where selectors do not reach (open shadow roots and same-origin iframes are searched) */
-export declare const CROSS_ORIGIN_FRAMES_NOTE = "Elements inside cross-origin iframes and closed shadow roots are not searched";
+export declare function otherIndexSourceNote(source: IndexSource, preview?: string): string;
+/** What a page holds that selectors cannot search (a cheap page check) */
+export interface UnsearchedContent {
+    /** Iframes whose document the page cannot read (cross-origin) */
+    crossOriginFrames: boolean;
+    /** `<object>`/`<embed>` elements */
+    embeds: boolean;
+}
+/**
+ * Where selectors do not reach (open shadow roots and same-origin iframes are
+ * searched), and how to reach an element in a cross-origin iframe instead.
+ * When the page was checked, only what it has is named (nothing when it has
+ * neither cross-origin iframes nor embeds; closed shadow roots cannot be
+ * detected).
+ *
+ * @param selector - Selector that matched nothing
+ * @param unsearched - What the page holds, when it was checked
+ * @returns Note for "not found" suggestions (empty when nothing applies)
+ */
+export declare function unreachableElementsNote(selector: string, unsearched?: UnsearchedContent): string;
+/**
+ * "Did you mean" for a selector that is a single id or class.
+ *
+ * @param kind - Id or class
+ * @param names - Similar names on the page
+ * @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;
+/** What the page says about a selector that matched nothing */
+export interface NoMatchContext {
+    /** Elements only its `:visible` filters excluded */
+    hidden?: number;
+    /** The page's `document.readyState`, when known (a hint is added while it loads) */
+    readyState?: string;
+    /** What the page holds that selectors cannot search, when checked */
+    unsearched?: UnsearchedContent;
+    /** "Did you mean" line for a single id or class ({@link similarSelectorsLine}) */
+    similar?: string;
+}
 /**
  * No nodes found for selector.
+ *
+ * @param selector - Selector as given
+ * @param context - What the page says about it (hidden matches, readyState, unsearched content, similar names)
+ */
+export declare function noNodesFoundError(selector: string, context?: NoMatchContext): ErrorWithSuggestion;
+/** Why a page scroll moved nothing */
+export interface ScrollNoEffect {
+    /** Direction asked for */
+    direction: 'up' | 'down' | 'left' | 'right';
+    /** The document is no larger than the viewport, the page was at its edge already, or it did not move although it could */
+    reason: 'too-small' | 'at-edge' | 'locked';
+    /** Viewport size along the axis (px) */
+    viewport: number;
+    /** The page's `document.readyState` */
+    readyState: string;
+}
+/**
+ * Warning of `bdg dom scroll` when the page did not move, with the
+ * still-loading hint while the document is not complete (it may grow).
+ *
+ * @param effect - Why nothing scrolled
+ * @returns e.g. `Nothing to scroll: the document is no taller than the viewport (993px)`
+ */
+export declare function scrollNoEffectWarning(effect: ScrollNoEffect): string;
+/**
+ * Hint for something not found while the page has not finished loading.
+ *
+ * @param readyState - The page's `document.readyState` (not `complete`)
+ * @param selector - Selector that matched nothing, if any
+ * @returns e.g. `The page is still loading (document.readyState: loading); wait for the element with: bdg dom wait '#login'`
+ */
+export declare function pageStillLoadingHint(readyState: string, selector?: string): string;
+/**
+ * Put the still-loading hint before a "not found" suggestion when the page
+ * has not finished loading.
+ *
+ * @param suggestion - Suggestion of the error
+ * @param readyState - The page's `document.readyState`, if known
+ * @param selector - Selector that matched nothing, if any
+ * @returns The suggestion, with the hint first while the page loads
  */
-export declare function noNodesFoundError(selector: string): ErrorWithSuggestion;
+export declare function withLoadingHint(suggestion: string, readyState: string | undefined, selector?: string): string;
+/**
+ * `bdg dom wait` without a selector or --load, or with --text/--gone but no selector.
+ *
+ * @returns Message and suggestion
+ */
+export declare function waitTargetRequiredError(): ErrorWithSuggestion;
+/**
+ * `bdg dom wait` that ran out of time: what it waited for and what the page
+ * showed last, with a next step that fits.
+ *
+ * @param condition - What was waited for
+ * @param snapshot - Last thing the page reported (none when it never answered)
+ * @param timeoutMs - The --timeout
+ * @returns Message and suggestion
+ */
+export declare function waitTimeoutError(condition: WaitCondition, snapshot: WaitSnapshot | undefined, timeoutMs: number): ErrorWithSuggestion;
 /**
  * Element not visible/rendered.
  */
@@ -418,8 +708,10 @@ export declare function singleFileInputError(count: number): ErrorWithSuggestion
  * Unknown field in an a11y query pattern.
  *
  * @param field - The unrecognized key
+ * @param similar - A known field it looks like a typo of
+ * @param value - The `name=…`/`description=…` field that absorbed it
  */
-export declare function unknownQueryFieldError(field: string): ErrorWithSuggestion;
+export declare function unknownQueryFieldError(field: string, similar?: string, value?: string): ErrorWithSuggestion;
 /**
  * No a11y nodes matching pattern.
  */
@@ -435,6 +727,39 @@ export declare function notInAccessibilityTreeError(target: string, reasons: str
  * Fillable element not found.
  */
 export declare function fillableElementNotFoundError(selector: string): ErrorWithSuggestion;
+/** Appended to the element type when an action went to a label's control. */
+export declare const VIA_LABEL_SUFFIX = " (via label)";
+/** Placeholder for the shell-quoted `name=…` field in {@link LABEL_WITHOUT_CONTROL}. */
+export declare const NAME_QUERY_PLACEHOLDER = "{nameQuery}";
+/**
+ * Filling a `<label>` that has no form control (used by the page script,
+ * which puts the label's quoted `name=<text>` in place of
+ * {@link NAME_QUERY_PLACEHOLDER}).
+ */
+export declare const LABEL_WITHOUT_CONTROL: ErrorWithSuggestion;
+/**
+ * Why `dom fill` refused an element (used by the page script, which adds the
+ * cause in parentheses, e.g. `The element is read-only (contenteditable="false")`).
+ * All are invalid targets (exit 81), like any element that is not fillable.
+ */
+export declare const FILL_REFUSALS: {
+    readonly disabled: {
+        readonly message: "The element is disabled";
+        readonly suggestion: "Enable the field first (it may depend on another input)";
+    };
+    readonly readOnly: {
+        readonly message: "The element is read-only";
+        readonly suggestion: "A user cannot change it either; the page has to make it editable first";
+    };
+    readonly inert: {
+        readonly message: "The element is inert";
+        readonly suggestion: "The page made it non-interactive (often behind a dialog); close what covers it first";
+    };
+    readonly notFillable: {
+        readonly message: "Element is not fillable";
+        readonly suggestion: "Only input, textarea, select, and contenteditable elements can be filled";
+    };
+};
 /**
  * Clickable element not found.
  */
@@ -455,12 +780,13 @@ export declare function keyPressFailedError(details: string): ErrorWithSuggestio
  */
 export declare function scriptTimeoutError(timeoutMs: number): ErrorWithSuggestion;
 /**
- * The page was kept busy by a script (e.g. a loop started from a timer) and
- * bdg terminated it.
+ * The page (or an iframe) was kept busy by a script (e.g. a loop started
+ * from a timer) and bdg terminated it.
  *
  * @param timeoutMs - Time waited
+ * @param scope - What was busy: the page, or the iframe a command ran in
  */
-export declare function pageBusyError(timeoutMs: number): ErrorWithSuggestion;
+export declare function pageBusyError(timeoutMs: number, scope?: 'page' | 'frame', recovered?: boolean): ErrorWithSuggestion;
 /**
  * The page did not answer because a navigation is still waiting for the
  * server (Chrome holds commands for the page until the new document arrives).
@@ -497,11 +823,40 @@ export declare function frameNotFoundError(query: string, frames: DomFrame[]): E
  */
 export declare function ambiguousFrameError(query: string, candidates: DomFrame[]): ErrorWithSuggestion;
 /**
- * An iframe without a JavaScript context (still loading, or sandboxed without scripts).
+ * An iframe without a JavaScript context (still loading, or gone).
  *
  * @param url - Frame URL
  */
 export declare function frameNotReadyError(url: string): ErrorWithSuggestion;
+/**
+ * The iframe a `dom eval --frame` script ran in navigated before it finished.
+ *
+ * @param url - Frame URL when the script started
+ */
+export declare function frameNavigatedDuringEvalError(url: string): ErrorWithSuggestion;
+/**
+ * The iframe a `dom eval --frame` script ran in was removed (or vanished
+ * before it started).
+ *
+ * @param url - Frame URL when the script started
+ */
+export declare function frameRemovedDuringEvalError(url: string): ErrorWithSuggestion;
+/**
+ * The page (its tab) was closed while a `dom eval` script ran.
+ */
+export declare function pageClosedDuringEvalError(): ErrorWithSuggestion;
+/**
+ * The iframe a `dom eval --frame` script ran in went away, and bdg could not
+ * tell whether it navigated or was removed.
+ *
+ * @param url - Frame URL when the script started
+ */
+export declare function frameLostDuringEvalError(url: string): ErrorWithSuggestion;
+/**
+ * The page navigated while a `dom eval` script ran (e.g. it set
+ * `location.href` and then awaited).
+ */
+export declare function pageNavigatedDuringEvalError(): ErrorWithSuggestion;
 /**
  * Script execution error with shell quote detection.
  *
@@ -536,7 +891,15 @@ export declare function internalError(context: string): ErrorWithSuggestion;
 /**
  * No forms found on page.
  */
-export declare function noFormsFoundError(): ErrorWithSuggestion;
+export declare function noFormsFoundError(readyState?: string): ErrorWithSuggestion;
+/**
+ * The form discovery script threw.
+ *
+ * @param detail - What it threw, e.g. `TypeError: Cannot read properties of null`
+ * @param readyState - The page's `document.readyState`, when known
+ * @returns Message and suggestion (the still-loading hint while the page loads)
+ */
+export declare function formDiscoveryFailedError(detail: string, readyState?: string): ErrorWithSuggestion;
 /**
  * Form in iframe (cross-origin or same-origin).
  */