browser-debugger-cli 0.8.0 → 0.9.0

package/dist/ui/messages/commands.d.ts

@@ -4,7 +4,11 @@
  * User-facing messages for command-specific operations like stopping sessions,
  * cleaning up stale files, and validating command arguments.
  */
-import type { DomFrame } from '../../ipc/protocol/commands.js';
+import type { DomFrame, PageLoadingState, PendingRequestInfo } from '../../ipc/protocol/commands.js';
+import type { ElementLayout, FillValueMismatch, LayoutSize, NewMessage, PageLayout, PageNavigation } from '../../ipc/protocol/domTypes.js';
+import type { DelegationNote } from '../../runtime/dom/listenerSummary.js';
+import type { WaitCondition, WaitSnapshot } from '../../runtime/dom/waitCondition.js';
+import type { DocumentRequestState, ViewportPosition } from '../../types.js';
 /**
  * Chrome closed by `bdg stop` (gracefully, so the profile is saved).
  *
@@ -26,13 +30,205 @@ export declare function orphanedDaemonsCleanedMessage(count: number): string;
  * @returns Warning text
  */
 export declare function domClickFallbackWarning(reason: string | null | undefined): string;
+/** Reason of a `bdg dom form` blocker for a required field left empty */
+export declare const REQUIRED_FIELD_EMPTY_REASON = "Required field is empty";
+/**
+ * Part of the `bdg dom form` summary naming the required fields left empty.
+ *
+ * @param labels - Labels of the empty required fields
+ * @returns e.g. "2 required fields empty: Last Name, Zip"
+ */
+export declare function requiredFieldsEmptyMessage(labels: string[]): string;
+/**
+ * Readiness at the end of the `bdg dom form` summary.
+ *
+ * @param summary - Whether the form is ready, how many fields are filled and
+ *   required, and the labels of the empty ones
+ * @returns e.g. "READY to submit", "NOT ready (no fields filled)"
+ */
+export declare function formReadinessMessage(summary: {
+    readyToSubmit: boolean;
+    filledFields: number;
+    requiredTotal: number;
+    emptyFieldLabels: string[];
+}): string;
+/** Why an action's status line is not a clean success when nothing changed */
+export declare const NO_VISIBLE_EFFECT = "no visible effect observed: no DOM change, requests or navigation within 300 ms";
+/**
+ * Status line of a DOM action: a check mark only for a clean success.
+ *
+ * @param done - What was done, e.g. "Element Clicked"
+ * @param warned - Whether the action has warnings (shown right below)
+ * @param noEffect - Whether the action had no visible effect
+ * @returns e.g. "✓ Element Clicked", "⚠ Element Clicked (with warnings)" or
+ *   "⚠ Element Clicked (no visible effect observed: no DOM change, requests or navigation within 300 ms)"
+ */
+export declare function actionStatusLine(done: string, warned: boolean, noEffect?: boolean): string;
+/**
+ * How an action changed the page's location, for its `Page:` row.
+ *
+ * @param navigation - Navigation the action caused
+ * @returns e.g. "navigated to https://example.com/secure (200)" or
+ *   "URL changed to https://example.com/#/active (same document)"
+ */
+export declare function pageNavigationText(navigation: PageNavigation): string;
+/**
+ * A message an action made appear, for its `New text:` rows.
+ *
+ * @param message - New message
+ * @returns e.g. `"Your password is invalid!" (div#flash.flash.error)`
+ */
+export declare function newMessageText(message: NewMessage): string;
+/**
+ * Warning shown when a filled field's value read back is not the one given:
+ * cut to its maxlength, a password of another length (values never shown),
+ * or another value (naming the field the value went to, when one has it).
+ *
+ * @param mismatch - Value given and value found (masked for passwords)
+ * @returns Warning text
+ */
+export declare function valueMismatchWarning(mismatch: FillValueMismatch): string;
+/**
+ * Warning shown when a mouse press was dispatched but the target never
+ * received it (e.g. a browser dialog or bubble captured the input).
+ */
+export declare const CLICK_NOT_RECEIVED_WARNING = "The click may not have reached the element: the page saw no mouse press (the browser may be showing a dialog or bubble that captures input)";
 /**
  * Note under a shortened list of matches.
  *
  * @param hidden - Matches not listed
- * @returns e.g. "... and 1174 more (use --json for all)"
+ * @param jsonLimit - How many JSON output lists, when it leaves some out too
+ * @returns e.g. "... and 1174 more (use --json for all)",
+ *   "... and 8980 more (--json lists the first 100)"
+ */
+export declare function moreMatchesNote(hidden: number, jsonLimit?: number): string;
+/**
+ * Note under a list of a11y query matches cut by `--limit`.
+ *
+ * @param omitted - Matches not listed
+ * @returns e.g. "... and 213 more (--limit 0 lists all; their indices work too)"
+ */
+export declare function a11yMoreMatchesNote(omitted: number): string;
+/**
+ * Note under a shortened list of requests an action triggered when JSON
+ * output left some out too (they are only in the network telemetry then).
+ *
+ * @param hidden - Requests not listed
+ * @returns e.g. "... and 50 more (see bdg network list)"
  */
-export declare function moreMatchesNote(hidden: number): string;
+export declare function moreRequestsNote(hidden: number): string;
+/**
+ * Title of the list of requests that started while an action ran (they are
+ * attributed by time, so a page poller's requests are listed too: the title
+ * doesn't claim the action caused them).
+ *
+ * @param total - Requests in all
+ * @returns e.g. "Requests during the action (18):"
+ */
+export declare function triggeredRequestsTitle(total: number): string;
+/**
+ * Line counting the static assets an action loaded instead of listing them.
+ *
+ * @param count - Asset requests
+ * @param types - Short type names, e.g. ["css", "js", "images"]
+ * @returns e.g. "+ 97 assets (css, js, fonts, images)"
+ */
+export declare function assetRequestsNote(count: number, types: string[]): string;
+/**
+ * Pieces of the reasons `bdg dom layout` gives for hidden and invisible
+ * elements. The page-side measurement builds the reasons from them, e.g.
+ * `clipped by div#acc: zero height`, `opacity: 0 on div#menu`.
+ */
+export declare const LAYOUT_REASONS: {
+    /** Hidden: an `<option>` of a closed `<select>` has no box */
+    readonly option: "not rendered (an <option> is shown by its <select>)";
+    /** Hidden: start of the reason for a clipping container with no area, followed by it */
+    readonly clippedBy: "clipped by ";
+    /** Which size of that container is zero */
+    readonly zeroHeight: "zero height";
+    readonly zeroWidth: "zero width";
+    /** Invisible: fully transparent */
+    readonly transparent: "opacity: 0";
+    /** Joins an invisible reason to the ancestor causing it */
+    readonly on: " on ";
+};
+/**
+ * Off-screen reason for an element out of view on a page whose scrolling is
+ * locked, naming the visible dialog that likely locked it when there is one.
+ *
+ * @param lock - What locks it, e.g. `overflow: hidden on body`
+ * @param dialog - Visible dialog on the page, e.g. `div#consent` (null: none)
+ * @returns e.g. `page scrolling is locked (overflow: hidden on body), likely by dialog div#consent`,
+ *   or `page scrolling is locked (overflow: hidden on body)`
+ */
+export declare function scrollLockedReason(lock: string, dialog?: string | null): string;
+/**
+ * Location hint for an element outside the viewport or hidden.
+ *
+ * @param position - Where the element is
+ * @param clippedBy - Ancestor or iframe cutting it off, if any
+ * @returns e.g. "below fold", "out of view in ul#list"; undefined for
+ *   elements (partly) in view
+ */
+export declare function viewportPositionHint(position: ViewportPosition, clippedBy?: string): string | undefined;
+/** What {@link layoutPositionLabel} reads of an element */
+type LabelledLayout = Pick<ElementLayout, 'inViewport' | 'percentVisible' | 'hiddenReason' | 'scrollBy' | 'clippedBy' | 'offScreenReason' | 'bounds'>;
+/**
+ * Where an element is relative to the viewport, for `bdg dom layout`.
+ *
+ * @param element - Element layout
+ * @param viewport - Viewport size, when known
+ * @returns e.g. "visible", "partly visible (40%); scroll down 302px to see all of it",
+ *   "below fold (scroll down 760px to centre it)",
+ *   "out of view in ul#list (below)", "hidden (display: none)",
+ *   "left of viewport (off-screen: beyond the page's scroll range)",
+ *   "below fold; page scrolling is locked (overflow: hidden on body), likely by dialog div#consent"
+ */
+export declare function layoutPositionLabel(element: LabelledLayout, viewport?: LayoutSize): string;
+/**
+ * The `prefers-color-scheme` media feature the page sees, labelled as the
+ * preference it is (the page may still render its own theme), and where it
+ * comes from.
+ *
+ * @param scheme - Light or dark
+ * @param emulated - Set with `--color-scheme` (otherwise the system setting)
+ * @returns e.g. `prefers-color-scheme: dark (from the system setting)`
+ */
+export declare function colorSchemeLabel(scheme: string, emulated: boolean): string;
+/**
+ * First line of `bdg status` for a running session.
+ *
+ * @param page - URL and title of the page, when the session reported them
+ * @returns e.g. `Session active: https://example.com/ — Example Domain`
+ */
+export declare function sessionActiveLine(page?: {
+    url: string;
+    title: string;
+}): string;
+/**
+ * Page dimensions line of `bdg dom layout`.
+ *
+ * @param page - Viewport, scroll position, document size and the color scheme the page is told to prefer
+ * @returns e.g. "Page: viewport 1280×720, scrolled to 0,0, document 1280×2400, prefers-color-scheme: dark"
+ */
+export declare function pageLayoutLine(page: PageLayout): string;
+/**
+ * Headline of `bdg dom layout`.
+ *
+ * @param count - Elements matched
+ * @param listed - Elements reported (fewer with --index)
+ * @param selector - Selector they matched
+ * @returns e.g. '3 elements match "button" (page x,y and size in CSS px):',
+ *   '1 of 3 elements matching "button" (...)'
+ */
+export declare function layoutHeadline(count: number, listed: number, selector: string): string;
+/**
+ * Headline of `bdg dom layout` for a cached index.
+ *
+ * @param target - The index and the list it refers to, in words
+ * @returns e.g. `Element at index 0 of the last dom query "h3" (page x,y and size in CSS px):`
+ */
+export declare function indexLayoutHeadline(target: string): string;
 /**
  * Warning when a selector matched several elements and no --index was given.
  *
@@ -41,14 +237,55 @@ export declare function moreMatchesNote(hidden: number): string;
  * @returns Warning text
  */
 export declare function multipleMatchesWarning(count: number, action: string): string;
+/** Listeners found, by where they are attached */
+export interface ListenerCounts {
+    target: number;
+    ancestor: number;
+    /** On the document and the window */
+    global: number;
+}
 /**
- * Headline of `bdg dom listeners`.
+ * Headline of `bdg dom listeners`, saying where the counted listeners are:
+ * the list covers the element, its ancestors, its document and window.
  *
  * @param element - Inspected element, e.g. "button#save"
- * @param count - Listeners found
- * @returns e.g. "Event listeners for button#save (3)"
+ * @param counts - Listeners found, by placement
+ * @param context - Index of the element and the iframe it is in, if any
+ * @returns e.g. "Event listeners for button#save (156: 3 on the element, 120 on ancestors, 33 on document and window)"
  */
-export declare function listenersHeadline(element: string, count: number): string;
+export declare function listenersHeadline(element: string, counts: ListenerCounts, context?: {
+    index?: number | undefined;
+    frame?: string | undefined;
+}): string;
+/** Heading of the collapsed framework root listeners */
+export declare const COLLAPSED_LISTENERS_HEADING = "Framework roots (one line per node; --all lists each listener):";
+/**
+ * One collapsed framework root.
+ *
+ * @param root - Framework label, event types, phases and dispatcher names
+ * @returns e.g. "React root: 90 event types, capture and bubble (dispatchEvent, …)"
+ */
+export declare function collapsedListenersSummary(root: {
+    framework?: string | undefined;
+    types: string[];
+    capture: boolean;
+    bubble: boolean;
+    handlers: string[];
+}): string;
+/**
+ * jQuery handlers left unresolved because there were too many.
+ *
+ * @param count - Handlers not resolved
+ * @returns One-line note
+ */
+export declare function jqueryHandlersSkippedNote(count: number): string;
+/**
+ * Event types a mistyped `--type` probably meant.
+ *
+ * @param types - Suggested types
+ * @returns e.g. "Did you mean: --type click?"
+ */
+export declare function eventTypeSuggestion(types: string[]): string;
 /**
  * `bdg dom listeners` found nothing.
  *
@@ -60,12 +297,19 @@ export declare function noListenersMessage(element: string, types?: string[]): s
 /** What `bdg dom listeners` covers, shown when it found nothing */
 export declare const NO_LISTENERS_HINT = "Inline on\u2026 attributes and on\u2026 properties are included, and so are handlers frameworks delegate to ancestors (React, jQuery)";
 /**
- * Note for event types handled only by ancestors, document or window.
+ * Note for interaction event types the element has no listener of its own for.
+ *
+ * @param note - How the types reach their handlers
+ * @returns One-line note, or undefined when the listed handlers say it all
+ */
+export declare function delegationNote(note: DelegationNote): string | undefined;
+/**
+ * React prop handlers left unresolved because there were too many.
  *
- * @param types - Event types without a listener on the element itself
+ * @param count - Handlers not resolved
  * @returns One-line note
  */
-export declare function delegatedListenersNote(types: string[]): string;
+export declare function reactHandlersSkippedNote(count: number): string;
 /**
  * A JavaScript dialog bdg accepted, as one line.
  *
@@ -91,18 +335,26 @@ export declare const PAGE_ACTION_DONE: {
     readonly forward: "Went forward";
 };
 /** Help text of the `bdg page` history commands */
+/** Description of `bdg page info` */
+export declare const PAGE_INFO_DESCRIPTION = "Show the URL and title of the session page";
 export declare const PAGE_ACTION_DESCRIPTIONS: {
     readonly reload: "Reload the page";
     readonly back: "Go back one page (like the browser button)";
     readonly forward: "Go forward one page (like the browser button)";
 };
 /**
- * `bdg page navigate` to a page that answered with an HTTP error.
+ * `bdg page navigate|reload|back|forward` when the document answered with an
+ * error status, or the page then loaded another document that answered
+ * differently (a 404 page whose script loads the app).
  *
- * @param status - HTTP status
- * @returns Warning
+ * @param status - HTTP status of the navigation's document
+ * @param later - The last document the page loaded afterwards, if any
+ * @returns Warning, or undefined when there is nothing to report
  */
-export declare function httpErrorWarning(status: number): string;
+export declare function documentStatusWarning(status: number, later?: {
+    status: number;
+    url: string;
+}): string | undefined;
 /**
  * `bdg page navigate` to a URL that loaded no page.
  *
@@ -116,6 +368,60 @@ export declare function notAPageWarning(): string;
  * @returns Warning
  */
 export declare function stillLoadingWarning(ms: number): string;
+/**
+ * Requests still running, the longest-running first, in words.
+ *
+ * @param pending - The requests to name
+ * @param count - All requests still running
+ * @returns e.g. `GET …/app.js (pending 30s) and 2 more`
+ */
+export declare function pendingRequestsText(pending: PendingRequestInfo[], count: number): string;
+/**
+ * How far a page request got, in words.
+ *
+ * @param request - The page request
+ * @returns e.g. `POST …/authenticate pending for 30s`, `POST …/authenticate returned 503 Service Unavailable`,
+ *   `POST …/authenticate failed (net::ERR_CONNECTION_REFUSED)`
+ */
+export declare function documentRequestText(request: DocumentRequestState): string;
+/**
+ * Start and `bdg page` when the document has not finished loading within
+ * the readiness wait: its readyState and the requests it is waiting on.
+ *
+ * @param state - Loading state of the page
+ * @returns Warning, e.g. `The page is still loading (document.readyState: loading); waiting on: GET …/jquery-ui.js (pending 30s)`
+ */
+export declare function pageLoadingWarning(state: PageLoadingState): string;
+/**
+ * Help of `dom click`/`submit`: they wait for the network only, so results a
+ * page shows later (timers, spinners, animations) are waited for with `dom wait`.
+ */
+export declare const CLICK_RESULT_WAIT_HELP: string;
+/** Examples in the help of `bdg dom wait` */
+export declare const WAIT_HELP_EXAMPLES: string;
+/**
+ * The elements `bdg dom wait` waits for.
+ *
+ * @param condition - What is waited for
+ * @returns e.g. `#finish with text "hello world"`
+ */
+export declare function waitTargetLabel(condition: WaitCondition): string;
+/**
+ * One-line result of `bdg dom wait`.
+ *
+ * @param condition - What was waited for
+ * @param elapsedMs - How long it took
+ * @returns e.g. `✓ div#finish visible after 5.1s`
+ */
+export declare function waitMetMessage(condition: WaitCondition, elapsedMs: number): string;
+/**
+ * What the page showed, for a `bdg dom wait` that timed out.
+ *
+ * @param snapshot - Last thing the page reported
+ * @param condition - What was waited for
+ * @returns e.g. `2 matches, none visible` or `document.readyState: loading`
+ */
+export declare function waitSnapshotSummary(snapshot: WaitSnapshot, condition: WaitCondition): string;
 /**
  * One line describing an iframe: index, URL, name/id, and how it is isolated.
  *
@@ -123,12 +429,65 @@ export declare function stillLoadingWarning(ms: number): string;
  * @returns e.g. `[1] https://pay.example/  #checkout  cross-origin, out-of-process`
  */
 export declare function frameLabel(frame: DomFrame): string;
+/**
+ * A frame URL for human output: shortened, and named when empty.
+ *
+ * @param url - Frame URL
+ * @returns e.g. `https://pay.example/checkout?…`, or `(no URL)`
+ */
+export declare function frameUrlLabel(url: string): string;
 /**
  * `bdg dom frames` on a page without iframes.
  *
  * @returns Message
  */
 export declare function noFramesMessage(): string;
+/**
+ * `bdg dom frames` while the page is still loading: its iframes may not
+ * exist yet.
+ *
+ * @param empty - No iframe was found
+ * @returns e.g. `No iframes yet; the page is still loading, so the list may be incomplete (bdg dom wait --load)`
+ */
+export declare function framesStillLoadingNote(empty: boolean): string;
+/**
+ * Text of an element in `bdg dom get` output.
+ *
+ * @param text - Collapsed text, ending in `...` when it was cut
+ * @returns e.g. `Text: Welcome to ... (cut at 500 characters; --full shows all of it)`
+ */
+export declare function elementTextLine(text: string): string;
+/**
+ * What an element without text holds, in `bdg dom get` output.
+ *
+ * @param children - First child elements, e.g. `iframe#app`
+ * @param count - Number of child elements
+ * @returns e.g. `No text; holds 1 element: iframe (see its HTML with --raw)`
+ */
+export declare function emptyElementLine(children: string[], count: number): string;
+/**
+ * Note on an element screenshot that captured more than the element's border
+ * box, because content (floats, positioned children) overflows it.
+ *
+ * @param box - Border box
+ * @param captured - Area captured
+ * @returns e.g. `grown from 940×37 to 940×285 to include content overflowing the element`
+ */
+export declare function screenshotGrownNote(box: {
+    width: number;
+    height: number;
+}, captured: {
+    width: number;
+    height: number;
+}): string;
+/**
+ * Next commands after `bdg dom query`, by index so they reach matches in
+ * shadow roots and iframes too.
+ *
+ * @param index - Match to use in the examples
+ * @returns One line
+ */
+export declare function queryNextSteps(index: number): string;
 /**
  * Header of `bdg dom eval --frame` output naming the frame the script ran in.
  *
@@ -161,6 +520,13 @@ export declare function sessionOutputRemovedMessage(): string;
  * @returns Formatted success message
  */
 export declare function sessionDirectoryCleanMessage(): string;
+/**
+ * `bdg cleanup --purge` deleted a named session's directory.
+ *
+ * @param dir - Deleted directory
+ * @returns Message
+ */
+export declare function sessionDirectoryPurgedMessage(dir: string): string;
 /**
  * Generate no session files found message.
  *
@@ -174,6 +540,13 @@ export declare function noSessionFilesMessage(): string;
  * @returns Formatted error message
  */
 export declare function sessionStillActiveError(pid: number): string;
+/**
+ * How to clean up a session that is still running.
+ *
+ * @param session - Name of a named session, or null for the default session
+ * @returns Suggestion lines
+ */
+export declare function sessionStillActiveSuggestion(session: string | null): string;
 /**
  * Generate help message when no URL is provided to start command.
  *
@@ -189,4 +562,5 @@ export declare function sessionStillActiveError(pid: number): string;
  * @returns Multi-line help message with examples
  * */
 export declare function startCommandHelpMessage(): string;
+export {};
 //# sourceMappingURL=commands.d.ts.map