browser-debugger-cli 0.7.2 → 0.9.0

package/dist/errors/messages.d.ts

@@ -0,0 +1,908 @@
+/**
+ * Common error messages and patterns.
+ *
+ * Centralized location for reusable error messages with consistent formatting.
+ */
+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 (commands carry
+ * `--session` for a named session).
+ *
+ * @param pid - Process ID of running session
+ * @param duration - Session duration in milliseconds
+ * @param targetUrl - Optional target URL to show
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * const message = sessionAlreadyRunningError(12345, 60000, 'http://localhost:3000');
+ * console.error(message);
+ * ```
+ */
+export declare function sessionAlreadyRunningError(pid: number, duration: number, targetUrl?: string): string;
+/**
+ * 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
+ * session or the caller's intent is launched-mode.
+ */
+export declare const LAUNCHED_CHROME_DESCRIPTION = "launched Chrome (bdg-managed)";
+/**
+ * Generate "session target mismatch" error message.
+ *
+ * Raised when a new start-session request names a different Chrome target
+ * (or switches between launched and attached modes) while an active session
+ * is healthy. Distinct from `sessionAlreadyRunningError` so agents can react
+ * programmatically via exit code + IPC error code.
+ *
+ * @param currentTarget - Target URL / ws URL / description of the active session
+ * @param requestedTarget - The ws URL / description of what the caller asked for
+ * @returns Formatted error message
+ */
+export declare function sessionTargetMismatchError(currentTarget: string | undefined, requestedTarget: string | undefined): string;
+/**
+ * Context for daemon error messages.
+ */
+export interface DaemonErrorContext {
+    /** Whether stale PID file was cleaned up */
+    staleCleanedUp?: boolean;
+    /** Whether to suggest checking status (for commands that expect daemon) */
+    suggestStatus?: boolean;
+    /** Whether to suggest retrying (for transient errors) */
+    suggestRetry?: boolean;
+    /** Last error message if available */
+    lastError?: string;
+}
+/**
+ * The daemon accepted the connection but did not answer in time (frozen or
+ * overloaded).
+ *
+ * @param seconds - How long the command waited
+ * @returns Message and suggestion
+ */
+export declare function sessionNotRespondingError(seconds: number): ErrorWithSuggestion;
+/**
+ * The daemon answered, but the command did not finish in time (slow or
+ * frozen page work).
+ *
+ * @param seconds - Timeout in seconds
+ */
+export declare function commandTimedOutError(seconds: number): ErrorWithSuggestion;
+/**
+ * What to do when a command finds no session to work with.
+ *
+ * @param exitCode - 85 while a start is in progress, otherwise 83
+ * @returns Suggestion
+ */
+export declare function sessionUnavailableSuggestion(exitCode: number): string;
+/**
+ * Generate unified "daemon not running" error message with context.
+ *
+ * This replaces the three previous variants:
+ * - daemonNotRunningError()
+ * - daemonConnectionFailedError()
+ * - daemonNotRunningWithCleanup()
+ *
+ * @param context - Optional context about the error
+ * @returns Formatted error message with suggestions
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * console.error(daemonNotRunningError());
+ *
+ * // With stale cleanup
+ * console.error(daemonNotRunningError({ staleCleanedUp: true }));
+ *
+ * // With status suggestion
+ * console.error(daemonNotRunningError({ suggestStatus: true }));
+ * ```
+ */
+export declare function daemonNotRunningError(context?: DaemonErrorContext): string;
+/**
+ * Generate generic error message with optional context.
+ *
+ * @param message - Error message
+ * @param context - Optional additional context
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * console.error(genericError('Operation failed', 'Network timeout'));
+ * ```
+ */
+export declare function genericError(message: string, context?: string): string;
+/**
+ * Generate "unknown error" message.
+ *
+ * @returns Formatted error message
+ */
+export declare function unknownError(): string;
+/**
+ * Generate "invalid response" error message.
+ *
+ * @param reason - Reason for invalid response
+ * @returns Formatted error message
+ */
+export declare function invalidResponseError(reason: string): string;
+/**
+ * Generate element not found error with shell quote detection and CDP fallback.
+ *
+ * Provides guidance for when high-level DOM commands fail to find elements.
+ * Detects shell quote damage for attribute selectors and provides specific
+ * recovery suggestions including the two-step query-then-inspect pattern.
+ *
+ * @param selector - CSS selector that failed (as received by the command)
+ * @returns Message and context-aware suggestion
+ *
+ * @example
+ * ```typescript
+ * // Simple selector - standard suggestions
+ * elementNotFoundError('#missing-element')
+ *
+ * // Attribute selector with shell damage detected
+ * elementNotFoundError('[data-test-id=value]')
+ * // Suggestion: "Shell quote handling detected: ..."
+ * ```
+ */
+export declare function elementNotFoundError(selector: string): ErrorWithSuggestion;
+/**
+ * Error with suggestion pair for CommandError usage.
+ */
+export interface ErrorWithSuggestion {
+    message: string;
+    suggestion: string;
+}
+/**
+ * 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.
+ *
+ * @param selector - Selector as given
+ * @param detail - Browser error, if any
+ * @returns Message and suggestion
+ */
+export declare function invalidSelectorError(selector: string, detail?: string): ErrorWithSuggestion;
+/**
+ * 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"`.
+ *
+ * @param selector - Selector as given
+ * @param filter - Filter name, e.g. ":has-text"
+ * @returns Message and suggestion
+ */
+export declare function invalidSelectorFilterError(selector: string, filter: string): ErrorWithSuggestion;
+/**
+ * `bdg help <topic>` for a command that does not exist.
+ *
+ * @param topic - Command path as typed, e.g. "dom quer"
+ * @param closest - Most similar existing command path, if any
+ */
+export declare function unknownHelpTopicError(topic: string, closest?: string): ErrorWithSuggestion;
+/**
+ * Chrome rejected a CDP method or its parameters.
+ *
+ * @param detail - Chrome's error message
+ */
+export declare function cdpRequestRejectedError(detail: string): ErrorWithSuggestion;
+/**
+ * A file the user asked for (screenshot, HAR) cannot be written.
+ *
+ * @param filePath - Path as given
+ * @param reason - What is wrong with it
+ * @param extension - Extension of the file kind, for the example (default .png)
+ */
+export declare function outputFileError(filePath: string, reason: string, extension?: string): ErrorWithSuggestion;
+/**
+ * An empty output path.
+ *
+ * @param extension - Extension of the file kind, for the example
+ */
+export declare function emptyOutputPathError(extension?: string): ErrorWithSuggestion;
+/**
+ * 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.
+ *
+ * @param value - What was given
+ * @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.
+ *
+ * @param dir - Session directory
+ */
+export declare function sessionDirIsFileError(dir: string): ErrorWithSuggestion;
+/**
+ * The session directory cannot be created or written.
+ *
+ * @param dir - Session directory
+ * @param reason - File-system error
+ */
+export declare function sessionDirNotWritableError(dir: string, reason: string): ErrorWithSuggestion;
+/**
+ * The daemon socket path exceeds the OS limit for Unix sockets.
+ *
+ * @param socketPath - Socket path
+ * @param max - Longest path the OS accepts
+ */
+export declare function socketPathTooLongError(socketPath: string, max: number): ErrorWithSuggestion;
+/**
+ * The Chrome of `--chrome-ws-url` does not answer on its HTTP endpoint.
+ *
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @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.
+ *
+ * @param id - Page id from the URL
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ */
+export declare function externalPageNotFoundError(id: string, endpoint: string): ErrorWithSuggestion;
+/**
+ * The browser id of a `--chrome-ws-url` browser URL is not this Chrome's.
+ *
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @param actual - The Chrome's browser WebSocket URL
+ */
+export declare function externalBrowserIdMismatchError(endpoint: string, actual: string): ErrorWithSuggestion;
+/**
+ * Options that only apply when bdg launches Chrome, given with `--chrome-ws-url`.
+ *
+ * @param options - The conflicting options, e.g. ["--port", "-u"]
+ */
+export declare function chromeWsUrlConflictError(options: string[]): ErrorWithSuggestion;
+/**
+ * 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, 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"];
+    readonly vertical: readonly ["Conflicting scroll directions: --up/--down/--top/--bottom", "Use one vertical direction"];
+    readonly horizontal: readonly ["Conflicting scroll directions: --left and --right", "Use either --left or --right"];
+    readonly 'selector-with-offset': readonly ["A selector cannot be combined with --up/--down/--left/--right/--top/--bottom", "Scroll to the element (bdg dom scroll \"footer\"), or by an offset (bdg dom scroll --down 500)"];
+    readonly 'no-target': readonly ["No scroll target specified", "Provide a selector (bdg dom scroll \"footer\") or offset (--down 500, --bottom)"];
+};
+/**
+ * Invalid `bdg dom scroll` options.
+ *
+ * @param problem - Which rule was broken
+ */
+export declare function scrollOptionsError(problem: keyof typeof SCROLL_PROBLEMS): ErrorWithSuggestion;
+/**
+ * A key name `dom pressKey` does not know.
+ *
+ * @param keyName - Key as given
+ * @param similar - Similar key names
+ */
+export declare function unknownKeyError(keyName: string, similar: string[]): ErrorWithSuggestion;
+/**
+ * `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.
+ *
+ * @param first - First option
+ * @param second - Option it conflicts with
+ * @returns Message
+ */
+export declare function conflictingOptionsMessage(first: string, second: string): string;
+/**
+ * A Chrome flag bdg cannot pass on.
+ *
+ * @param flag - The flag
+ */
+export declare function invalidChromeFlagError(flag: string): ErrorWithSuggestion;
+/**
+ * The session (its browser or daemon) went away while a command was running.
+ */
+export declare function sessionEndedDuringCommandError(): ErrorWithSuggestion;
+/**
+ * An option that only takes effect together with another one.
+ *
+ * @param option - Option given
+ * @param required - Option it needs
+ * @returns Message
+ */
+export declare function optionRequiresMessage(option: string, required: string): string;
+/**
+ * `bdg page navigate javascript:…`: scripts run with dom eval.
+ */
+export declare function javascriptNavigationError(): ErrorWithSuggestion;
+/**
+ * A bare word given where a URL is expected, most likely a mistyped command.
+ *
+ * @param word - The argument
+ * @param similar - Similar command names
+ */
+export declare function unknownCommandError(word: string, similar: string[]): ErrorWithSuggestion;
+/**
+ * The browser could not load the start URL at all.
+ *
+ * @param url - URL that failed
+ * @param errorText - Chrome network error (e.g. net::ERR_NAME_NOT_RESOLVED)
+ */
+export declare function navigationFailedError(url: string, errorText: string): ErrorWithSuggestion;
+/**
+ * `bdg page back/forward` at the end of the page's history.
+ *
+ * @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 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 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, 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 cachedIndexOutOfRangeError(source: IndexSource, count: number): ErrorWithSuggestion;
+/**
+ * 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 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 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.
+ */
+export declare function elementNotVisibleError(): ErrorWithSuggestion;
+/**
+ * Element has zero dimensions.
+ */
+export declare function elementZeroDimensionsError(): ErrorWithSuggestion;
+/**
+ * Missing required argument.
+ */
+export declare function missingArgumentError(usage: string): ErrorWithSuggestion;
+/**
+ * Either/or argument required.
+ */
+export declare function eitherArgumentRequiredError(arg1: string, arg2: string, example: string): ErrorWithSuggestion;
+/**
+ * Invalid query pattern.
+ */
+export declare function invalidQueryPatternError(pattern: string): ErrorWithSuggestion;
+/**
+ * A file to upload does not exist.
+ *
+ * @param file - Path that was not found
+ */
+export declare function fileNotFoundError(file: string): ErrorWithSuggestion;
+/**
+ * A directory given for a file input.
+ *
+ * @param file - Resolved path
+ */
+export declare function uploadDirectoryError(file: string): ErrorWithSuggestion;
+/**
+ * Several files given for a file input that accepts one.
+ *
+ * @param count - Number of files given
+ */
+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, similar?: string, value?: string): ErrorWithSuggestion;
+/**
+ * No a11y nodes matching pattern.
+ */
+export declare function noA11yNodesFoundError(pattern: string): ErrorWithSuggestion;
+/**
+ * An element that exists but has no node in the accessibility tree.
+ *
+ * @param target - Selector or index the user gave
+ * @param reasons - Why Chrome leaves it out
+ */
+export declare function notInAccessibilityTreeError(target: string, reasons: string[]): ErrorWithSuggestion;
+/**
+ * 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.
+ */
+export declare function clickableElementNotFoundError(selector: string): ErrorWithSuggestion;
+/**
+ * Click target disappeared between locating and clicking it.
+ */
+export declare function clickTargetDetachedError(selector: string): ErrorWithSuggestion;
+/**
+ * Key press failed.
+ */
+export declare function keyPressFailedError(details: string): ErrorWithSuggestion;
+/**
+ * A `bdg dom eval` script ran too long and was terminated.
+ *
+ * @param timeoutMs - Time limit in ms
+ * @returns Error with suggestion
+ */
+export declare function scriptTimeoutError(timeoutMs: number): ErrorWithSuggestion;
+/**
+ * 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, 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).
+ *
+ * @param url - URL being loaded
+ */
+export declare function navigationPendingError(url: string): ErrorWithSuggestion;
+/**
+ * `dom eval` given an empty script (often a shell variable that was not set).
+ */
+export declare function emptyScriptError(): ErrorWithSuggestion;
+/**
+ * A promise returned by `dom eval` that did not settle in time.
+ *
+ * @param timeoutMs - Time waited
+ */
+export declare function promiseTimeoutError(timeoutMs: number): ErrorWithSuggestion;
+/**
+ * `dom eval --frame` given an empty frame.
+ */
+export declare function emptyFrameError(): ErrorWithSuggestion;
+/**
+ * `dom eval --frame` matching no iframe.
+ *
+ * @param query - Requested frame
+ * @param frames - Frames of the page
+ */
+export declare function frameNotFoundError(query: string, frames: DomFrame[]): ErrorWithSuggestion;
+/**
+ * `dom eval --frame` matching more than one iframe.
+ *
+ * @param query - Requested frame
+ * @param candidates - Matching frames
+ */
+export declare function ambiguousFrameError(query: string, candidates: DomFrame[]): ErrorWithSuggestion;
+/**
+ * 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.
+ *
+ * Shows the script as received to help diagnose shell quote stripping issues.
+ * Detects common patterns like `querySelector(input)` that indicate shell damage.
+ *
+ * @param errorMessage - The JavaScript error message
+ * @param receivedScript - The script as received by the command (optional for backwards compat)
+ * @returns Error with context-aware suggestions
+ */
+export declare function scriptExecutionError(errorMessage: string, receivedScript?: string): ErrorWithSuggestion;
+/**
+ * Unexpected CDP response format.
+ */
+export declare function unexpectedResponseFormatError(context: string): ErrorWithSuggestion;
+/**
+ * Generic operation failure with dynamic error message.
+ */
+export declare function operationFailedError(operation: string, errorMessage: string): ErrorWithSuggestion;
+/**
+ * The browser does not offer `DOMDebugger.getEventListeners` (non-Chrome
+ * targets, or browsers that disable the DOMDebugger domain).
+ *
+ * @param detail - Chrome's error
+ * @returns Message and suggestion
+ */
+export declare function eventListenersUnavailableError(detail: string): ErrorWithSuggestion;
+/**
+ * Internal error (should not happen in normal usage).
+ */
+export declare function internalError(context: string): ErrorWithSuggestion;
+/**
+ * No forms found on page.
+ */
+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).
+ */
+export declare function formInIframeError(iframeUrl: string, crossOrigin: boolean): ErrorWithSuggestion;
+export {};
+//# sourceMappingURL=messages.d.ts.map