browser-debugger-cli 0.8.0 → 0.9.0

package/dist/errors/messages.js

@@ -4,11 +4,15 @@
  * Centralized location for reusable error messages with consistent formatting.
  */
 import * as path from 'path';
+import { countedMatches, } from '../runtime/dom/waitCondition.js';
+import { getSessionBaseDir, getSessionName } from '../session/paths.js';
 import { escapeControlChars, formatDuration, joinLines } from '../ui/formatting.js';
-import { frameLabel } from '../ui/messages/commands.js';
+import { documentRequestText, frameLabel, frameUrlLabel, pendingRequestsText, waitSnapshotSummary, waitTargetLabel, } from '../ui/messages/commands.js';
+import { noActiveSessionMessage, sessionCommand, startSessionSuggestion, } from '../ui/messages/sessionCommand.js';
 import { detectSelectorQuoteDamage, detectScriptQuoteDamage, hasAttributeSelector, } from '../utils/shellDetection.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
@@ -22,10 +26,42 @@ import { detectSelectorQuoteDamage, detectScriptQuoteDamage, hasAttributeSelecto
  * ```
  */
 export function sessionAlreadyRunningError(pid, duration, targetUrl) {
-    return joinLines('', 'Error: Session already running', '', `  PID:      ${pid}`, targetUrl && `  Target:   ${targetUrl}`, `  Duration: ${formatDuration(duration)}`, '', 'Suggestions:', '  View session:     bdg status', '  Stop and restart: bdg stop && bdg <url>', '');
+    return joinLines('', `Error: ${sessionLabel()} already running`, '', `  PID:      ${pid}`, targetUrl && `  Target:   ${targetUrl}`, `  Duration: ${formatDuration(duration)}`, '', 'Suggestions:', `  View session:     ${sessionCommand('bdg status')}`, `  Stop and restart: ${stopAndRestartCommand()}`, '');
+}
+/**
+ * The daemon's one-line answer to `bdg <url>` while its session runs.
+ *
+ * @param pid - Daemon PID
+ * @returns Message
+ */
+export function sessionAlreadyRunningMessage(pid) {
+    return `${sessionLabel()} already running (PID ${pid}). Stop it first with: ${sessionCommand('bdg stop')}`;
+}
+/**
+ * "Session" or `Session "<name>"` for the selected session.
+ *
+ * @returns Label
+ */
+function sessionLabel() {
+    const name = getSessionName();
+    return name === null ? 'Session' : `Session "${name}"`;
+}
+/**
+ * Stop the selected session and start it again.
+ *
+ * @returns Command line
+ */
+function stopAndRestartCommand() {
+    return `${sessionCommand('bdg stop')} && ${sessionCommand('bdg <url>')}`;
+}
+/**
+ * What to do when `bdg <url>` finds the selected session already running.
+ *
+ * @returns Suggestion
+ */
+export function alreadyRunningSuggestion() {
+    return `Use the running session (${sessionCommand('bdg status')}), or stop it first: ${stopAndRestartCommand()}`;
 }
-/** What to do when `bdg <url>` finds a session already running */
-export const ALREADY_RUNNING_SUGGESTION = 'Use the running session (bdg status), or stop it first: bdg stop && bdg <url>';
 /**
  * Human-readable description of a bdg-launched Chrome (as opposed to one
  * reached via `--chrome-ws-url`). Used in mismatch errors where the active
@@ -45,7 +81,7 @@ export const LAUNCHED_CHROME_DESCRIPTION = 'launched Chrome (bdg-managed)';
  * @returns Formatted error message
  */
 export function sessionTargetMismatchError(currentTarget, requestedTarget) {
-    return joinLines('', 'Error: Active session is attached to a different Chrome target', '', `  Current:   ${currentTarget ?? '(unknown)'}`, `  Requested: ${requestedTarget ?? '(unknown)'}`, '', "Run 'bdg stop' before attaching to a different target.", '');
+    return joinLines('', 'Error: Active session is attached to a different Chrome target', '', `  Current:   ${currentTarget ?? '(unknown)'}`, `  Requested: ${requestedTarget ?? '(unknown)'}`, '', `Run '${sessionCommand('bdg stop')}' before attaching to a different target.`, '');
 }
 /**
  * The daemon accepted the connection but did not answer in time (frozen or
@@ -57,7 +93,7 @@ export function sessionTargetMismatchError(currentTarget, requestedTarget) {
 export function sessionNotRespondingError(seconds) {
     return {
         message: `The session did not respond within ${seconds}s`,
-        suggestion: 'Retry in a moment; if it stays unresponsive, end it with: bdg cleanup --force (stops the daemon and its Chrome)',
+        suggestion: `Retry in a moment; if it stays unresponsive, end it with: ${sessionCommand('bdg cleanup --force')} (stops the daemon and its Chrome)`,
     };
 }
 /**
@@ -69,7 +105,7 @@ export function sessionNotRespondingError(seconds) {
 export function commandTimedOutError(seconds) {
     return {
         message: `The command did not finish within ${seconds}s (the page may be busy or frozen)`,
-        suggestion: 'Check the session with: bdg status; if the page stays frozen, end it with: bdg cleanup --force',
+        suggestion: `Check the session with: ${sessionCommand('bdg status')}; if the page stays frozen, end it with: ${sessionCommand('bdg cleanup --force')}`,
     };
 }
 /**
@@ -80,8 +116,8 @@ export function commandTimedOutError(seconds) {
  */
 export function sessionUnavailableSuggestion(exitCode) {
     return exitCode === 85
-        ? 'Wait until "bdg <url>" returns, then retry'
-        : 'Start a session with: bdg <url>';
+        ? `Wait until "${sessionCommand('bdg <url>')}" returns, then retry`
+        : startSessionSuggestion();
 }
 /**
  * Generate unified "daemon not running" error message with context.
@@ -107,7 +143,7 @@ export function sessionUnavailableSuggestion(exitCode) {
  * ```
  */
 export function daemonNotRunningError(context) {
-    return joinLines('Error: No active session', context?.staleCleanedUp && '(Stale daemon files were cleaned up)', context?.lastError && `Last error: ${context.lastError}`, 'Start a session with: bdg <url>', context?.suggestStatus && '', context?.suggestStatus && 'Or check daemon status:', context?.suggestStatus && '  bdg status', context?.suggestRetry && '', context?.suggestRetry && 'Or try the command again if this was transient');
+    return joinLines(`Error: ${noActiveSessionMessage()}`, context?.staleCleanedUp && '(Stale daemon files were cleaned up)', context?.lastError && `Last error: ${context.lastError}`, startSessionSuggestion(), context?.suggestStatus && '', context?.suggestStatus && 'Or check daemon status:', context?.suggestStatus && `  ${sessionCommand('bdg status')}`, context?.suggestRetry && '', context?.suggestRetry && 'Or try the command again if this was transient');
 }
 /**
  * Generate generic error message with optional context.
@@ -166,8 +202,8 @@ export function elementNotFoundError(selector) {
     const message = `Element not found: ${selector}`;
     const discovery = [
         'Discovery path:',
-        `  1. Query first:  bdg dom query '${selector}'`,
-        '  2. Then inspect: bdg dom a11y describe 0',
+        `  1. Query first:  ${sessionCommand(`bdg dom query '${selector}'`)}`,
+        `  2. Then inspect: ${sessionCommand('bdg dom a11y describe 0')}`,
     ];
     const quoteCheck = detectSelectorQuoteDamage(selector);
     if (quoteCheck.damaged) {
@@ -184,7 +220,7 @@ export function elementNotFoundError(selector) {
     }
     return {
         message,
-        suggestion: joinLines('Check the selector syntax, or wait for the element to load (bdg peek shows the page state)', CROSS_ORIGIN_FRAMES_NOTE),
+        suggestion: joinLines(`Check the selector syntax, or wait for the element to load (${sessionCommand('bdg peek')} shows the page state)`, unreachableElementsNote(selector)),
     };
 }
 /**
@@ -196,8 +232,24 @@ export function indexOutOfRangeError(index, max) {
         suggestion: `Use an index between 0 and ${max}`,
     };
 }
+/** Finding elements by accessible name, quoted for the shell (the name may contain spaces and colons). */
+export const A11Y_NAME_QUERY_EXAMPLE = "bdg dom a11y query 'name=…'";
+/** Where text filters can go, for selector errors. */
+const SCOPED_FILTER_EXAMPLES = 'Put the filter on the element it tests, e.g. li:has-text("Buy milk") .toggle (the .toggle in that row) or label:has-text("Name") input, or test what an element contains with :has(), e.g. li:has(label:text-is("Buy milk"))';
 /** Playwright selector syntax bdg does not support (`:text()`, `>>` chains, `text=` engines, layout pseudo-classes). */
 const PLAYWRIGHT_ONLY_SYNTAX = /:(?:text|text-matches|nth-match|left-of|right-of|above|below|near)\(|>>|^\s*(?:text|css|xpath|role|id|data-testid|internal:\w+)=/i;
+/**
+ * Empty (or blank) selector: the browser rejects it, so it is caught before
+ * any page script runs.
+ *
+ * @returns Message and suggestion
+ */
+export function emptySelectorError() {
+    return {
+        message: 'Invalid CSS selector: The provided selector is empty',
+        suggestion: 'Pass a selector, e.g. bdg dom query "button.primary"',
+    };
+}
 /**
  * CSS selector rejected by the browser. Playwright-only syntax (`:text()`,
  * `>>`, `text=`) gets the filters bdg supports instead.
@@ -210,13 +262,13 @@ export function invalidSelectorError(selector, detail) {
     return {
         message: `Invalid CSS selector: ${selector}${detail ? ` (${detail})` : ''}`,
         suggestion: PLAYWRIGHT_ONLY_SYNTAX.test(selector)
-            ? 'Playwright-only syntax is not CSS. bdg supports :has-text("…"), :text-is("…") and :visible at the end of a selector, e.g. button:has-text("Save"), or find elements by accessible name: bdg dom a11y query name="…"'
+            ? `Playwright-only syntax is not CSS. bdg supports :has-text("…"), :text-is("…") and :visible, e.g. button:has-text("Save"), or scoped to a row or label: li:has-text("Buy milk") .toggle; or find elements by accessible name: ${A11Y_NAME_QUERY_EXAMPLE}`
             : 'Check the selector syntax, e.g. bdg dom query "button.primary"',
     };
 }
 /**
- * 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
@@ -224,8 +276,70 @@ export function invalidSelectorError(selector, detail) {
  */
 export function misplacedSelectorFilterError(selector, filter) {
     return {
-        message: `${filter} must come last in a selector (after the CSS of the element to match): ${selector}`,
-        suggestion: `Move it to the end, e.g. form button:has-text("Save"); to match an element by what it contains use CSS :has(), e.g. div:has(> button), or find elements by accessible name: bdg dom a11y query name="…"`,
+        message: `${filter} can only be used on an element of the selector or inside :has(), not inside other pseudo-classes: ${selector}`,
+        suggestion: `${SCOPED_FILTER_EXAMPLES}; or find elements by accessible name: ${A11Y_NAME_QUERY_EXAMPLE}`,
+    };
+}
+/**
+ * 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 function siblingAfterFilterError(selector, combinator) {
+    return {
+        message: `Only a descendant (space) or child (>) combinator can follow a text or visibility filter, not "${combinator}": ${selector}`,
+        suggestion: `Put the filter on the element to match, e.g. h2 + p:has-text("x"), or scope by a common ancestor: section:has-text("x") p`,
+    };
+}
+/**
+ * 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 function siblingInHasError(selector, combinator) {
+    return {
+        message: `:has() with text or visibility filters can only look inside an element, not at its siblings ("${combinator}"): ${selector}`,
+        suggestion: 'Use a descendant or child: li:has(a:visible), li:has(> a:visible); for a sibling, put the filter on it: li + a:visible',
+    };
+}
+/** How a selector with filters is malformed (before the browser sees it). */
+const MALFORMED_SELECTOR_DETAILS = {
+    'empty-in-list': () => 'a selector in the list is empty',
+    'leading-combinator': (combinator) => `it starts with the combinator "${combinator}"`,
+    'trailing-combinator': () => 'it ends with a combinator',
+    'empty-has': () => ':has() has an empty selector',
+    'scope-in-has': () => ':has() with filters is already relative to the element; write :has(> a:visible) instead of :has(:scope > a:visible)',
+};
+/**
+ * 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 function malformedSelectorError(selector, problem, combinator = '') {
+    return invalidSelectorError(selector, MALFORMED_SELECTOR_DETAILS[problem](combinator));
+}
+/**
+ * `:has-text()` with empty text, which every element would match.
+ *
+ * @param selector - Selector as given
+ * @returns Message and suggestion
+ */
+export function emptyTextFilterError(selector) {
+    return {
+        message: `:has-text() needs the text to look for (empty text matches every element): ${selector}`,
+        suggestion: 'Give the text, e.g. button:has-text("Save"); use :text-is("") for elements without text',
     };
 }
 /**
@@ -301,6 +415,31 @@ export function missingStartUrlError() {
         suggestion: 'Put the URL first, e.g. bdg localhost:3000 --port 9333',
     };
 }
+/**
+ * `--viewport` given something that is not a width and height.
+ *
+ * @param value - What was given
+ * @param max - Largest side accepted
+ */
+export function invalidViewportError(value, max) {
+    return {
+        message: `Invalid --viewport: "${value}"`,
+        suggestion: `Give width x height in CSS px (1-${max} each), e.g. --viewport 1280x800`,
+    };
+}
+/**
+ * `--color-scheme` given another value than the ones it takes.
+ *
+ * @param value - What was given
+ * @param similar - Close matches
+ * @param schemes - Accepted values
+ */
+export function invalidColorSchemeError(value, similar, schemes) {
+    return {
+        message: `Unknown --color-scheme: "${value}"`,
+        suggestion: similar[0] ? `Did you mean: ${similar[0]}?` : `Available: ${schemes.join(', ')}`,
+    };
+}
 /**
  * `-u` / `--user-data-dir` given something that is not a directory path.
  *
@@ -313,6 +452,54 @@ export function invalidUserDataDirError(value, reason) {
         suggestion: 'Give a directory for the Chrome profile, e.g. -u ./profile (it is created if missing)',
     };
 }
+/**
+ * A `--session` / `BDG_SESSION` name bdg cannot use as a directory name.
+ *
+ * @param name - The rejected name
+ * @param maxLength - Longest allowed name
+ */
+export function invalidSessionNameError(name, maxLength) {
+    return {
+        message: `Invalid session name "${name}"`,
+        suggestion: `Use 1-${maxLength} letters, digits, "-" or "_", starting with a letter or digit, e.g. --session agent-1`,
+    };
+}
+/**
+ * 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 function sessionNameSocketTooLongError(name, socketPath, max) {
+    return {
+        message: `Session name "${name}" makes the daemon socket path too long (${Buffer.byteLength(socketPath)} bytes, at most ${max}): ${socketPath}`,
+        suggestion: 'Use a shorter session name, or a shorter BDG_SESSION_DIR (e.g. /tmp/bdg)',
+    };
+}
+/**
+ * `bdg cleanup --purge` without a named session (the default session's
+ * directory holds the named sessions).
+ */
+export function purgeNeedsNamedSessionError() {
+    return {
+        message: "--purge deletes a named session's directory and needs --session <name>",
+        suggestion: 'Name the session: bdg cleanup --session <name> --purge (see bdg sessions)',
+    };
+}
+/**
+ * `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 function purgeRefusedError(dir, reason) {
+    return {
+        message: `Not deleting ${dir}: ${reason}`,
+        suggestion: `End the session first (${sessionCommand('bdg cleanup --force')}), then retry: ${sessionCommand('bdg cleanup --purge')}`,
+    };
+}
 /** Fix for an unusable session directory */
 const SESSION_DIR_SUGGESTION = 'Set BDG_SESSION_DIR to a short, writable directory, e.g. BDG_SESSION_DIR=/tmp/bdg';
 /**
@@ -343,7 +530,7 @@ export function sessionDirNotWritableError(dir, reason) {
  */
 export function socketPathTooLongError(socketPath, max) {
     return {
-        message: `Session directory path is too long for the daemon socket (${socketPath.length} characters, at most ${max})`,
+        message: `Session directory path is too long for the daemon socket (${Buffer.byteLength(socketPath)} bytes, at most ${max}): ${socketPath}`,
         suggestion: SESSION_DIR_SUGGESTION,
     };
 }
@@ -361,6 +548,36 @@ export function externalChromeUnreachableError(endpoint, secure) {
             : 'Check that Chrome runs with --remote-debugging-port and is reachable from here',
     };
 }
+/**
+ * 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 function notDevToolsEndpointError(endpoint) {
+    return {
+        message: `${endpoint} answers, but it is not a Chrome DevTools endpoint (no /json/version)`,
+        suggestion: "Give Chrome's debugging port (the --remote-debugging-port it was started with), not the page's port",
+    };
+}
+/**
+ * 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 function chromeInUseBySessionError(endpoint, owner) {
+    const label = owner.name === null ? 'the default bdg session' : `bdg session "${owner.name}"`;
+    const what = owner.launched ? 'was launched by' : 'has its tab driven by';
+    const envPrefix = owner.baseDir === getSessionBaseDir() ? '' : `BDG_SESSION_DIR=${owner.baseDir} `;
+    const ownerCommand = (command) => envPrefix + sessionCommand(command, owner.name);
+    return {
+        message: `The Chrome at ${endpoint} ${what} ${label} (${owner.dir}); attaching would take it over`,
+        suggestion: `Use that session (${ownerCommand('bdg status')}), stop it first (${ownerCommand('bdg stop')}), or attach to another Chrome or tab (a page URL from ${endpoint}/json/list)`,
+    };
+}
 /**
  * The page id of a `--chrome-ws-url` page URL does not exist.
  *
@@ -382,7 +599,7 @@ export function externalPageNotFoundError(id, endpoint) {
 export function externalBrowserIdMismatchError(endpoint, actual) {
     return {
         message: `The Chrome at ${endpoint} has a different browser id (it was restarted, or the URL is from another Chrome)`,
-        suggestion: `Use its current URL: bdg <url> --chrome-ws-url ${actual}`,
+        suggestion: `Use its current URL: ${sessionCommand(`bdg <url> --chrome-ws-url ${actual}`)}`,
     };
 }
 /**
@@ -392,7 +609,7 @@ export function externalBrowserIdMismatchError(endpoint, actual) {
  */
 export function chromeWsUrlConflictError(options) {
     return {
-        message: `${options.join(' and ')} cannot be used with --chrome-ws-url (the running Chrome already has its port and profile)`,
+        message: `${options.join(' and ')} cannot be used with --chrome-ws-url (the running Chrome already has its port, profile and window mode)`,
         suggestion: 'Drop them, or let bdg launch Chrome without --chrome-ws-url',
     };
 }
@@ -400,11 +617,12 @@ export function chromeWsUrlConflictError(options) {
  * 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 function indexWithIndexOptionError(index) {
+export function indexWithIndexOptionError(index, command) {
     return {
         message: `--index applies to a selector, but "${index}" is already an index from the last query`,
-        suggestion: `Use one: bdg dom click ${index}, or bdg dom click "<selector>" --index <n>`,
+        suggestion: `Use one: bdg dom ${command} ${index}, or bdg dom ${command} "<selector>" --index <n>`,
     };
 }
 /** Problems with `bdg dom scroll` options, and how to fix each */
@@ -450,8 +668,20 @@ export function unknownKeyError(keyName, similar) {
             : 'Keys: Enter, Tab, Escape, Space, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, F1-F12, a-z, A-Z, 0-9, !@#$%^&*()',
     };
 }
-/** Where selectors cannot look, for "not found" errors */
-export 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 function conflictingTargetError(option, positional) {
+    return {
+        message: `${option} and the element argument "${positional}" name different elements`,
+        suggestion: 'Name the element once: bdg dom screenshot <path> <selector|index>',
+    };
+}
 /**
  * Two options given together where one would be ignored.
  *
@@ -484,7 +714,7 @@ export function invalidChromeFlagError(flag) {
 export function sessionEndedDuringCommandError() {
     return {
         message: 'The session ended while the command was running',
-        suggestion: 'Start a new session with: bdg <url>',
+        suggestion: `Start a new session with: ${sessionCommand('bdg <url>')}`,
     };
 }
 /**
@@ -545,18 +775,79 @@ export function noHistoryEntryError(direction) {
     };
 }
 /**
- * The form was submitted but the wait for its result timed out.
+ * What to do about a submit that timed out waiting for a navigation, by how
+ * far its page request got: without one the form probably submits via fetch.
+ *
+ * @param document - The page request, if one was sent
+ * @returns Suggestion
+ */
+function submitNavigationSuggestion(document) {
+    if (document === undefined) {
+        return 'The form sent no page request, so it may not navigate (e.g. it submits via fetch); retry without --wait-navigation';
+    }
+    const details = `see it with ${sessionCommand('bdg network list --last 10')}`;
+    if (document.errorText !== undefined)
+        return `The page request failed; ${details}`;
+    if (document.status !== undefined && document.status >= 400) {
+        return `The server answered with an error; ${details}`;
+    }
+    if (document.status !== undefined) {
+        return 'The server answered without a new page; retry without --wait-navigation';
+    }
+    return 'The server has not answered the page request yet; retry with a larger --timeout';
+}
+/**
+ * What a timed-out submit was waiting on, in words: its page request when a
+ * navigation was awaited or the request had not loaded a page, otherwise the
+ * requests still running.
+ *
+ * @param waitNavigation - Whether a navigation was awaited
+ * @param blockers - The page request and the requests still running
+ * @returns e.g. `POST …/authenticate pending for 10s`; undefined when nothing is known
+ */
+function submitWaitDetail(waitNavigation, blockers) {
+    const { document, pending = [] } = blockers;
+    const loadedPage = document?.status !== undefined && document.status < 400 && document.errorText === undefined;
+    if (document && (waitNavigation || !loadedPage))
+        return documentRequestText(document);
+    if (pending.length === 0)
+        return undefined;
+    return `waiting on ${pendingRequestsText(pending, blockers.pendingCount ?? pending.length)}`;
+}
+/**
+ * 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 function submitTimeoutError(timeout, waitNavigation) {
-    return {
-        message: `Form submitted, but timed out after ${timeout}ms waiting for ${waitNavigation ? 'navigation' : 'network idle'}`,
-        suggestion: waitNavigation
-            ? 'The form may not navigate (e.g. it submits via fetch); retry without --wait-navigation or with a larger --timeout'
-            : 'Increase --timeout, or use --wait-network 0 to return right after submitting',
-    };
+export function submitTimeoutError(timeout, waitNavigation, blockers = {}) {
+    const detail = submitWaitDetail(waitNavigation, blockers);
+    const message = `Form submitted, but timed out after ${timeout}ms waiting for ${waitNavigation ? 'navigation' : 'network idle'}${detail ? `: ${detail}` : ''}`;
+    if (!waitNavigation) {
+        return {
+            message,
+            suggestion: 'Increase --timeout, or use --wait-network 0 to return right after submitting',
+        };
+    }
+    return { message, suggestion: submitNavigationSuggestion(blockers.document) };
+}
+/**
+ * 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 function submitNetworkBusyWarning(timeout, pending) {
+    const requests = pending === 1 ? '1 request' : `${pending} requests`;
+    return `The new page loaded, but ${requests} still had not finished after ${timeout}ms`;
 }
 /**
  * No element has the given node id.
@@ -569,12 +860,70 @@ export function nodeIdNotFoundError(nodeId) {
         suggestion: 'Get current node ids with "bdg dom query <selector>" or "bdg dom get <selector> --raw"',
     };
 }
+/**
+ * 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 function indexSourceText(source) {
+    return `index ${source.index} of ${cachedListText(source)}`;
+}
+/**
+ * The cached list an index refers to, in words.
+ *
+ * @param source - Where the index comes from
+ * @returns e.g. `the last dom query "h3"`
+ */
+function cachedListText(source) {
+    const query = source.query === undefined ? '' : ` "${source.query}"`;
+    return `the last ${source.command}${query}`;
+}
+/**
+ * The command that refreshes the list an index refers to.
+ *
+ * @param source - Where the index comes from
+ * @returns e.g. `bdg dom query 'h3'`
+ */
+function refreshCommand(source) {
+    if (source.query === undefined)
+        return sessionCommand(`bdg ${source.command}`);
+    return sessionCommand(`bdg ${source.command} ${shellQuote(source.query)}`);
+}
+/**
+ * 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 function frameMappingError(problem, detail) {
+    const reasons = {
+        'no-box': 'neither the element nor its iframe document has a box (hidden or removed)',
+        rotated: 'the iframe is rotated or skewed, which bdg cannot map',
+        unreadable: `it could not be measured${detail ? ` (${detail})` : ''}`,
+    };
+    return {
+        message: `Cannot place the element's cross-origin iframe in the page: ${reasons[problem]}`,
+        suggestion: `Act inside the frame instead: ${sessionCommand('bdg dom frames')}, then ${sessionCommand('bdg dom eval --frame <n> \'document.querySelector("…").click()\'')}`,
+    };
+}
 /**
  * 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 function staleNodeError(index) {
+export function staleNodeError(index, source) {
+    if (source) {
+        return {
+            message: `The element at ${indexSourceText(source)} is no longer in the page (it was removed or the page navigated)`,
+            suggestion: `Re-run "${refreshCommand(source)}" to get fresh indices`,
+        };
+    }
     const element = index === undefined ? 'The element' : `The element at index ${index}`;
     return {
         message: `${element} is no longer in the page (it was removed or the page navigated)`,
@@ -582,25 +931,222 @@ export function staleNodeError(index) {
     };
 }
 /**
- * Element at index not found (stale cache).
+ * 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 function elementAtIndexNotFoundError(index, selector) {
+export function cachedIndexOutOfRangeError(source, count) {
+    const results = count === 1 ? '1 result' : `${count} results`;
     return {
-        message: `Element at index ${index} not found`,
-        suggestion: `Re-run "bdg dom query ${selector}" to refresh the cache`,
+        message: `Index ${source.index} is out of range for ${cachedListText(source)} (${results})`,
+        suggestion: count > 0
+            ? `Use an index between 0 and ${count - 1}, or re-run "${refreshCommand(source)}"`
+            : `Re-run "${refreshCommand(source)}"`,
     };
 }
-/** Where selectors do not reach (open shadow roots and same-origin iframes are searched) */
-export const CROSS_ORIGIN_FRAMES_NOTE = 'Elements inside cross-origin iframes and closed shadow roots are not searched';
 /**
- * No nodes found for selector.
+ * 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 function noNodesFoundError(selector) {
+export function otherIndexSourceNote(source, preview) {
+    const query = source.query === undefined ? '' : `"${source.query}"`;
+    const what = [query, preview].filter(Boolean).join(': ');
+    return `index ${source.index} refers to the last ${source.command} results${what ? ` (${what})` : ''}; run ${sessionCommand('bdg dom form')} to target form fields by index`;
+}
+/**
+ * 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 function unreachableElementsNote(selector, unsearched) {
+    const script = `document.querySelector(${JSON.stringify(selector)})`.replaceAll("'", `'\\''`);
+    const framesHelp = `For an element in a cross-origin iframe: ${sessionCommand('bdg dom frames')}, then ${sessionCommand(`bdg dom eval --frame <n> '${script}'`)}`;
+    if (!unsearched) {
+        return joinLines('Closed shadow roots, cross-origin iframes and <object>/<embed> documents are not searched.', framesHelp);
+    }
+    const places = [
+        unsearched.crossOriginFrames && 'cross-origin iframes',
+        unsearched.embeds && '<object>/<embed> documents',
+    ].filter(Boolean);
+    if (places.length === 0)
+        return '';
+    return joinLines(`The page has ${places.join(' and ')}, which are not searched.`, unsearched.crossOriginFrames ? framesHelp : undefined);
+}
+/**
+ * "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 function similarSelectorsLine(kind, names) {
+    if (names.length === 0)
+        return '';
+    const sigil = kind === 'id' ? '#' : '.';
+    const what = kind === 'id' ? 'id' : 'class';
+    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)`;
+}
+/**
+ * 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 function noNodesFoundError(selector, context = {}) {
+    const hiddenMatches = context.hidden ?? 0;
+    const hidden = hiddenMatches > 0
+        ? hiddenMatches === 1
+            ? '1 element matches without :visible but is hidden (check with bdg dom layout). '
+            : `${hiddenMatches} elements match without :visible but are hidden (check with bdg dom layout). `
+        : '';
+    const note = unreachableElementsNote(selector, context.unsearched);
     return {
         message: `No nodes found matching "${selector}"`,
-        suggestion: `Verify the CSS selector is correct. ${CROSS_ORIGIN_FRAMES_NOTE}`,
+        suggestion: withLoadingHint(joinLines(context.similar, `${hidden}Verify the CSS selector is correct.`, note ? note : undefined), context.readyState, selector),
+    };
+}
+/**
+ * Quote a value for a POSIX shell command line.
+ *
+ * @param value - Value
+ * @returns The value in single quotes
+ */
+function shellQuote(value) {
+    return `'${value.split("'").join(`'\\''`)}'`;
+}
+/** Edge of the page in each direction */
+const SCROLL_EDGES = { up: 'top', down: 'bottom', left: 'left edge', right: 'right edge' };
+/**
+ * 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 function scrollNoEffectWarning(effect) {
+    const vertical = effect.direction === 'up' || effect.direction === 'down';
+    const reasons = {
+        'too-small': `Nothing to scroll: the document is no ${vertical ? 'taller' : 'wider'} than the viewport (${effect.viewport}px)`,
+        'at-edge': `Nothing scrolled: the page is already at the ${SCROLL_EDGES[effect.direction]}`,
+        locked: 'Nothing scrolled although the page is larger than the viewport; its scrolling may be locked (e.g. overflow: hidden while a dialog is open)',
+    };
+    const loading = effect.readyState === 'complete' ? undefined : pageStillLoadingHint(effect.readyState);
+    return [reasons[effect.reason], loading].filter(Boolean).join('. ');
+}
+/**
+ * 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 function pageStillLoadingHint(readyState, selector) {
+    const wait = selector !== undefined && selector.trim() !== ''
+        ? `wait for the element with: ${sessionCommand(`bdg dom wait ${shellQuote(selector)}`)}`
+        : `wait for it with: ${sessionCommand('bdg dom wait --load')}`;
+    return `The page is still loading (document.readyState: ${readyState}); ${wait}`;
+}
+/**
+ * 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 function withLoadingHint(suggestion, readyState, selector) {
+    if (readyState === undefined || readyState === 'complete')
+        return suggestion;
+    return joinLines(pageStillLoadingHint(readyState, selector), suggestion || undefined);
+}
+/**
+ * `bdg dom wait` without a selector or --load, or with --text/--gone but no selector.
+ *
+ * @returns Message and suggestion
+ */
+export function waitTargetRequiredError() {
+    return {
+        message: 'dom wait needs a selector (--text and --gone apply to its matches), or --load',
+        suggestion: `e.g. ${sessionCommand("bdg dom wait '#result' --visible")}, ${sessionCommand("bdg dom wait body --text 'Welcome'")} or ${sessionCommand('bdg dom wait --load')}`,
+    };
+}
+/**
+ * `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 function waitTimeoutError(condition, snapshot, timeoutMs) {
+    const seen = snapshot
+        ? `last seen: ${waitSnapshotSummary(snapshot, condition)}`
+        : 'the page did not answer';
+    return {
+        message: `Timed out after ${formatDuration(timeoutMs)} waiting for ${waitGoal(condition)} (${seen})`,
+        suggestion: waitTimeoutSuggestion(condition, snapshot),
     };
 }
+/**
+ * What `bdg dom wait` waits for, as a phrase.
+ *
+ * @param condition - What is waited for
+ * @returns e.g. `#finish to be visible` or `the page to load`
+ */
+function waitGoal(condition) {
+    if (condition.selector === undefined)
+        return 'the page to load';
+    const state = condition.gone
+        ? condition.visible
+            ? 'to be hidden'
+            : 'to be gone'
+        : condition.visible
+            ? 'to be visible'
+            : 'to appear';
+    return `${waitTargetLabel(condition)} ${state}${condition.load ? ' and the page to load' : ''}`;
+}
+/**
+ * Next step after a `bdg dom wait` timeout.
+ *
+ * @param condition - What was waited for
+ * @param snapshot - Last thing the page reported
+ * @returns Suggestion
+ */
+function waitTimeoutSuggestion(condition, snapshot) {
+    const more = 'allow more time with --timeout <ms>';
+    const selector = condition.selector;
+    if (snapshot && snapshot.readyState !== 'complete') {
+        return `The page is still loading; see the requests it waits on with ${sessionCommand('bdg peek')}, or ${more}`;
+    }
+    if (!snapshot ||
+        selector === undefined ||
+        condition.gone ||
+        countedMatches(snapshot, condition) > 0) {
+        return `Check the page with ${sessionCommand('bdg peek')}, or ${more}`;
+    }
+    if (snapshot.count === 0) {
+        return `Check the selector with ${sessionCommand(`bdg dom query ${shellQuote(selector)}`)}, or ${more}`;
+    }
+    if (snapshot.textCount === 0) {
+        return `The matches do not contain the text; see what they say with ${sessionCommand(`bdg dom query ${shellQuote(selector)}`)}`;
+    }
+    return `The matches are hidden; see why with ${sessionCommand(`bdg dom layout ${shellQuote(selector)}`)}, or ${more}`;
+}
 /**
  * Element not visible/rendered.
  */
@@ -643,7 +1189,7 @@ export function eitherArgumentRequiredError(arg1, arg2, example) {
 export function invalidQueryPatternError(pattern) {
     return {
         message: 'Query pattern must specify at least one field',
-        suggestion: `Received: "${pattern}". Try: bdg dom a11y query "role:button" or "name:Submit"`,
+        suggestion: `Received: "${pattern}". Try: bdg dom a11y query role=button, or ${A11Y_NAME_QUERY_EXAMPLE}`,
     };
 }
 /**
@@ -683,11 +1229,17 @@ export function singleFileInputError(count) {
  * Unknown field in an a11y query pattern.
  *
  * @param field - The unrecognized key
- */
-export function unknownQueryFieldError(field) {
+ * @param similar - A known field it looks like a typo of
+ * @param value - The `name=…`/`description=…` field that absorbed it
+ */
+export function unknownQueryFieldError(field, similar, value) {
+    const usage = "Use role, name or description, e.g. bdg dom a11y query 'role=button name=Sign in'. Quote the whole pattern for the shell; a name with spaces or colons goes last ('name=E-mail address:') or in inner quotes ('name=\"Role: admin\" role=textbox')";
+    if (!similar)
+        return { message: `Unknown query field: "${field}"`, suggestion: usage };
+    const [key = '', ...text] = (value ?? '').split('=');
     return {
-        message: `Unknown query field: "${field}"`,
-        suggestion: 'Use role, name or description, e.g.: bdg dom a11y query "role:button name:Submit"',
+        message: `Unknown query field: "${field}" (did you mean "${similar}"?)`,
+        suggestion: `Fix the field name, e.g. ${similar}=…; if the ${key} really contains "${field}:", put it in inner quotes: '${key}="${text.join('=')}"'`,
     };
 }
 /**
@@ -720,6 +1272,42 @@ export function fillableElementNotFoundError(selector) {
         suggestion: 'Verify the selector matches a fillable element (input, textarea, select)',
     };
 }
+/** Appended to the element type when an action went to a label's control. */
+export const VIA_LABEL_SUFFIX = ' (via label)';
+/** Placeholder for the shell-quoted `name=…` field in {@link LABEL_WITHOUT_CONTROL}. */
+export 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 const LABEL_WITHOUT_CONTROL = {
+    message: 'Element is not fillable (a <label> not associated with a form control)',
+    suggestion: `Find the field by its accessible name: bdg dom a11y query ${NAME_QUERY_PLACEHOLDER}, or list the form fields: bdg dom form`,
+};
+/**
+ * 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 const FILL_REFUSALS = {
+    disabled: {
+        message: 'The element is disabled',
+        suggestion: 'Enable the field first (it may depend on another input)',
+    },
+    readOnly: {
+        message: 'The element is read-only',
+        suggestion: 'A user cannot change it either; the page has to make it editable first',
+    },
+    inert: {
+        message: 'The element is inert',
+        suggestion: 'The page made it non-interactive (often behind a dialog); close what covers it first',
+    },
+    notFillable: {
+        message: 'Element is not fillable',
+        suggestion: 'Only input, textarea, select, and contenteditable elements can be filled',
+    },
+};
 /**
  * Clickable element not found.
  */
@@ -760,15 +1348,23 @@ export function scriptTimeoutError(timeoutMs) {
     };
 }
 /**
- * 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 function pageBusyError(timeoutMs) {
+export function pageBusyError(timeoutMs, scope = 'page', recovered = true) {
+    const busy = `The ${scope} was busy for ${Math.round(timeoutMs / 1000)}s (a script kept it running)`;
+    if (!recovered) {
+        return {
+            message: `${busy} and its scripts could not be stopped`,
+            suggestion: 'Retry in a moment; if it stays busy, reload the page: bdg page reload',
+        };
+    }
     return {
-        message: `The page was busy for ${Math.round(timeoutMs / 1000)}s (a script kept it running), so its scripts were terminated`,
-        suggestion: 'The page is usable again; re-run the command',
+        message: `${busy}, so its scripts were terminated`,
+        suggestion: `The ${scope} is usable again; re-run the command`,
     };
 }
 /**
@@ -799,8 +1395,8 @@ export function emptyScriptError() {
  */
 export function promiseTimeoutError(timeoutMs) {
     return {
-        message: `The returned promise did not settle within ${Math.round(timeoutMs / 1000)}s`,
-        suggestion: 'Check that it resolves or rejects, or race it with a timeout in the script',
+        message: `The awaited promise did not settle within ${Math.round(timeoutMs / 1000)}s`,
+        suggestion: 'Nothing was busy; check that the promise resolves or rejects, or race it with a timeout in the script',
     };
 }
 /** How to see the frames `--frame` accepts */
@@ -811,7 +1407,7 @@ const LIST_FRAMES_HINT = 'List frames: bdg dom frames';
 export function emptyFrameError() {
     return {
         message: 'The frame is empty',
-        suggestion: `Pass an index, a name/id attribute, or part of the URL. ${LIST_FRAMES_HINT}`,
+        suggestion: `Pass an index, a name/id attribute, or part of the name, id or URL. ${LIST_FRAMES_HINT}`,
     };
 }
 /**
@@ -838,20 +1434,90 @@ export function frameNotFoundError(query, frames) {
 export function ambiguousFrameError(query, candidates) {
     return {
         message: `Frame "${query}" matches ${candidates.length} frames`,
-        suggestion: joinLines('Pick one by index or a longer part of the URL:', ...candidates.map((frame) => `  ${frameLabel(frame)}`)),
+        suggestion: joinLines('Pick one by index, or a longer part of the name, id or URL:', ...candidates.map((frame) => `  ${frameLabel(frame)}`)),
     };
 }
 /**
- * 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 function frameNotReadyError(url) {
     return {
-        message: `The frame has no JavaScript context: ${url}`,
-        suggestion: `Wait for it to load and retry (sandboxed frames without allow-scripts never get one). ${LIST_FRAMES_HINT}`,
+        message: `The frame has no JavaScript context: ${frameUrlLabel(url)}`,
+        suggestion: `Wait for it to load and retry, or re-run bdg dom frames: the frame may no longer exist`,
     };
 }
+/**
+ * The iframe a `dom eval --frame` script ran in navigated before it finished.
+ *
+ * @param url - Frame URL when the script started
+ */
+export function frameNavigatedDuringEvalError(url) {
+    return {
+        message: `The frame navigated while the script ran: ${frameUrlLabel(url)}`,
+        suggestion: 'The result was lost with the old document; re-run the script once the frame has loaded. List frames: bdg dom frames',
+    };
+}
+/**
+ * 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 function frameRemovedDuringEvalError(url) {
+    return {
+        message: `The frame was removed before the script finished: ${frameUrlLabel(url)}`,
+        suggestion: 'The frame no longer exists; re-run bdg dom frames to see the current ones',
+    };
+}
+/**
+ * The page (its tab) was closed while a `dom eval` script ran.
+ */
+export function pageClosedDuringEvalError() {
+    return {
+        message: 'The page was closed while the script ran',
+        suggestion: 'Its tab is gone; start a new session with: bdg <url>',
+    };
+}
+/**
+ * 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 function frameLostDuringEvalError(url) {
+    return {
+        message: `The frame navigated or was removed while the script ran: ${frameUrlLabel(url)}`,
+        suggestion: 'Re-run bdg dom frames to see the current frames, then the script',
+    };
+}
+/**
+ * The page navigated while a `dom eval` script ran (e.g. it set
+ * `location.href` and then awaited).
+ */
+export function pageNavigatedDuringEvalError() {
+    return {
+        message: 'The page navigated while the script ran',
+        suggestion: 'The result was lost with the old document; re-run the script on the new page (navigate with: bdg page navigate <url>)',
+    };
+}
+/** `Identifier 'x' has already been declared` */
+const REDECLARED_PATTERN = /^SyntaxError: Identifier '([\w$]+)' has already been declared/;
+/**
+ * Tip for a top-level `const`/`let` whose name the page or the script itself
+ * already declares (`dom eval` runs like the console: names persist between
+ * calls, and a page's own top-level `let`/`const`/`class` cannot be declared again).
+ *
+ * @param name - The redeclared identifier
+ * @returns Tip
+ */
+function redeclarationTip(name) {
+    return [
+        `'${name}' is already declared at the top level, by the page or earlier in this script.`,
+        `Rename it, or wrap the script in a block so its names stay local: ${sessionCommand(`bdg dom eval '{ const ${name} = ...; ${name} }'`)}`,
+    ].join('\n');
+}
 /**
  * Script execution error with shell quote detection.
  *
@@ -869,7 +1535,8 @@ export function scriptExecutionError(errorMessage, receivedScript) {
             suggestion: 'Check JavaScript syntax and ensure the expression is valid',
         };
     }
-    const quoteCheck = detectScriptQuoteDamage(receivedScript);
+    const quoteCheck = detectScriptQuoteDamage(receivedScript, errorMessage);
+    const redeclared = REDECLARED_PATTERN.exec(errorMessage)?.[1];
     const truncatedScript = receivedScript.length > 100 ? receivedScript.slice(0, 100) + '...' : receivedScript;
     const lines = [];
     lines.push(`Script received: ${truncatedScript}`);
@@ -884,6 +1551,10 @@ export function scriptExecutionError(errorMessage, receivedScript) {
             lines.push(quoteCheck.suggestion);
         }
     }
+    else if (redeclared) {
+        lines.push('');
+        lines.push(redeclarationTip(redeclared));
+    }
     else if (/^SyntaxError\b/.test(errorMessage)) {
         lines.push('');
         lines.push('Tips:');
@@ -939,10 +1610,33 @@ export function internalError(context) {
 /**
  * No forms found on page.
  */
-export function noFormsFoundError() {
+export function noFormsFoundError(readyState) {
+    const check = 'Check if forms exist with: bdg dom query "form, input, [role=textbox]" or inspect the page manually';
+    if (readyState === undefined || readyState === 'complete') {
+        return { message: 'No forms discovered on the page', suggestion: check };
+    }
+    return {
+        message: 'No forms discovered on the page yet; it is still loading',
+        suggestion: joinLines(pageStillLoadingHint(readyState), check),
+    };
+}
+/**
+ * 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 function formDiscoveryFailedError(detail, readyState) {
+    if (readyState !== undefined && readyState !== 'complete') {
+        return {
+            message: `Form discovery failed while the page is still loading (${detail})`,
+            suggestion: pageStillLoadingHint(readyState),
+        };
+    }
     return {
-        message: 'No forms discovered on the page',
-        suggestion: 'Check if forms exist with: bdg dom query "form, input, [role=textbox]" or inspect the page manually',
+        message: `Form discovery failed: ${detail}`,
+        suggestion: `The page changed or threw while it was read; retry, or look at the fields with ${sessionCommand('bdg dom query "form, input, select, textarea"')}`,
     };
 }
 /**