browser-debugger-cli 0.7.2 → 0.9.0

package/dist/utils/shellDetection.js

@@ -4,16 +4,52 @@
  * Detects when shell quote handling has corrupted selectors or scripts,
  * providing actionable suggestions for recovery.
  */
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 const ATTRIBUTE_SELECTOR_PATTERN = /\[[\w-]+=/.source;
 const QUOTED_ATTRIBUTE_PATTERN = /\[[\w-]+=['"][^'"]*['"]\]/;
 const UNQUOTED_ATTRIBUTE_PATTERN = /\[([\w-]+)=([\w-]+)\]/;
-const BARE_ARGUMENT_PATTERN = /(\w+)\(\s*([a-zA-Z][\w-]*)\s*\)/;
-const UNEXPECTED_IDENTIFIER_PATTERN = /Unexpected identifier ['"]?(\w+)['"]?/;
+/** DOM methods whose one argument is a string (a selector, id, name or class) */
+const STRING_ARGUMENT_METHODS = new Set([
+    'querySelector',
+    'querySelectorAll',
+    'getElementById',
+    'getElementsByClassName',
+    'getElementsByTagName',
+    'getElementsByName',
+    'closest',
+    'matches',
+    'getAttribute',
+    'hasAttribute',
+    'removeAttribute',
+    'toggleAttribute',
+    'createElement',
+    'add',
+    'remove',
+    'toggle',
+]);
+/** A call with one argument and no quotes, parentheses or commas in it */
+const UNQUOTED_CALL_PATTERN = /([\w$]+)\(\s*([^()'"`,]+?)\s*\)/g;
+/** `x is not defined`: the shell may have turned `"x"` into `x` */
+const NOT_DEFINED_PATTERN = /^ReferenceError: ([\w$]+) is not defined/;
+/**
+ * The syntax errors V8 raises for `fn(div p)`: the shell may have turned
+ * `"div p"` into `div p`
+ */
+const SEVERAL_WORDS_PATTERN = /^SyntaxError: (?:missing \) after argument list|Unexpected identifier '([\w$]+)')/;
+/**
+ * The syntax errors V8 raises for a selector starting with punctuation:
+ * `fn(.btn)`, `fn(#main)`, `fn(> p)`
+ */
+const SELECTOR_SYNTAX_PATTERN = /^SyntaxError: (?:Unexpected token '[^']*'|Invalid or unexpected token|Private field '#[^']*' must be declared)/;
+/** Start of a CSS selector that is not a JavaScript expression */
+const SELECTOR_PUNCTUATION = /^[.#>~+*[:]/;
+/** Words that may start a valid expression of several words */
+const EXPRESSION_KEYWORDS = /^(?:new|typeof|void|delete|await|yield)\b/;
 function noDamage() {
     return { damaged: false };
 }
 function buildSelectorSuggestion(selector) {
-    return `Use the two-step pattern:\n  1. bdg dom query '${selector}'\n  2. bdg dom a11y describe 0`;
+    return `Use the two-step pattern:\n  1. ${sessionCommand(`bdg dom query '${selector}'`)}\n  2. ${sessionCommand('bdg dom a11y describe 0')}`;
 }
 function checkUnquotedAttribute(selector) {
     if (QUOTED_ATTRIBUTE_PATTERN.test(selector)) {
@@ -31,31 +67,66 @@ function checkUnquotedAttribute(selector) {
         suggestion: buildSelectorSuggestion(selector),
     };
 }
-function checkBareArgument(script) {
-    const match = BARE_ARGUMENT_PATTERN.exec(script);
-    if (!match) {
-        return noDamage();
-    }
-    const [matchedPart, funcName, bareArg] = match;
-    const fixedPart = `${funcName}("${bareArg}")`;
-    const fixedScript = script.replace(matchedPart, fixedPart);
-    return {
-        damaged: true,
-        type: 'unquoted-argument',
-        details: `${funcName}(${bareArg}) - quotes stripped by shell`,
-        suggestion: `Try: bdg dom eval '${fixedScript}'`,
-    };
+/**
+ * Whether the script declares a name itself (then it is a variable, not a
+ * string that lost its quotes).
+ *
+ * @param script - The script
+ * @param name - Identifier
+ * @returns True for a `const`/`let`/`var`/`function`/`class` declaration of it
+ */
+function declares(script, name) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`\\b(?:const|let|var|function|class)\\s+${escaped}\\b`).test(script);
 }
-function checkUnexpectedIdentifier(script) {
-    if (!UNEXPECTED_IDENTIFIER_PATTERN.test(script)) {
-        return noDamage();
-    }
-    return {
-        damaged: true,
-        type: 'unquoted-argument',
-        details: 'Unexpected identifier suggests quotes were stripped',
-        suggestion: "Use single quotes around the script: bdg dom eval '...'",
-    };
+/**
+ * Whether text starts with an identifier (and not with a longer one).
+ *
+ * @param text - Text
+ * @param name - Identifier
+ * @returns True when `text` is `name` or `name` followed by a non-identifier character
+ */
+function startsWithName(text, name) {
+    return text.startsWith(name) && !/^[\w$]/.test(text.slice(name.length));
+}
+/**
+ * Whether an unquoted argument is what the error complains about: for
+ * `ReferenceError` the argument starts with the undefined name (`input`,
+ * `my-id`, `button.primary`); for `SyntaxError` it is several bare words
+ * (`div p`), the unexpected one (when named) among the later ones; for a
+ * syntax error at punctuation it starts like a selector (`.btn`, `#main`).
+ *
+ * @param argument - Unquoted argument
+ * @param error - What the error says
+ * @returns True when quotes stripped from it explain the error
+ */
+function explainsError(argument, error) {
+    if (error.kind === 'undefined')
+        return startsWithName(argument, error.name);
+    if (error.kind === 'selector')
+        return SELECTOR_PUNCTUATION.test(argument);
+    const [, ...laterWords] = argument.split(/\s+/);
+    return (!EXPRESSION_KEYWORDS.test(argument) &&
+        laterWords.length > 0 &&
+        (error.name === undefined || laterWords.some((word) => startsWithName(word, error.name ?? ''))));
+}
+/**
+ * Read the identifier an error is about, when the error is one stripped
+ * quotes cause.
+ *
+ * @param errorMessage - The JavaScript error
+ * @returns The identifier and kind of error, or undefined for other errors
+ */
+function quoteRelatedError(errorMessage) {
+    const notDefined = NOT_DEFINED_PATTERN.exec(errorMessage);
+    if (notDefined?.[1])
+        return { kind: 'undefined', name: notDefined[1] };
+    if (SELECTOR_SYNTAX_PATTERN.test(errorMessage))
+        return { kind: 'selector' };
+    const syntax = SEVERAL_WORDS_PATTERN.exec(errorMessage);
+    if (!syntax)
+        return undefined;
+    return syntax[1] ? { kind: 'syntax', name: syntax[1] } : { kind: 'syntax' };
 }
 /**
  * Checks if a selector contains attribute syntax.
@@ -79,16 +150,32 @@ export function detectSelectorQuoteDamage(selector) {
     return checkUnquotedAttribute(selector);
 }
 /**
- * Detects shell quote damage in JavaScript expressions.
+ * Detects shell quote damage in JavaScript expressions. Conservative: only an
+ * error stripped quotes cause (`x is not defined`,
+ * `missing ) after argument list`, `Unexpected identifier`,
+ * `Unexpected token '.'`, `Invalid or unexpected token`) counts, about an
+ * argument of a DOM method that takes a string (`querySelector(input)`),
+ * which the script does not declare itself.
  *
  * @param script - The script as received by the command
+ * @param errorMessage - The error the script raised
  * @returns Detection result with details and suggestions
  */
-export function detectScriptQuoteDamage(script) {
-    const bareArgResult = checkBareArgument(script);
-    if (bareArgResult.damaged) {
-        return bareArgResult;
+export function detectScriptQuoteDamage(script, errorMessage) {
+    const error = quoteRelatedError(errorMessage);
+    if (!error || (error.name && declares(script, error.name)))
+        return noDamage();
+    for (const [call, method = '', argument = ''] of script.matchAll(UNQUOTED_CALL_PATTERN)) {
+        if (!STRING_ARGUMENT_METHODS.has(method) || !explainsError(argument, error))
+            continue;
+        const fixedScript = script.replace(call, `${method}("${argument}")`);
+        return {
+            damaged: true,
+            type: 'unquoted-argument',
+            details: `${method}(${argument}) - quotes stripped by shell`,
+            suggestion: `Try: ${sessionCommand(`bdg dom eval '${fixedScript}'`)}`,
+        };
     }
-    return checkUnexpectedIdentifier(script);
+    return noDamage();
 }
 //# sourceMappingURL=shellDetection.js.map

package/dist/utils/suggestions.d.ts

@@ -15,5 +15,31 @@ export declare function getSuggestion(input: string, candidates: readonly string
     prefix?: string;
     suffix?: string;
 }): string;
+/**
+ * Names (ids or classes) similar to one that matched nothing, best first, at
+ * most three: near-typos first (Levenshtein distance up to a fifth of the
+ * length, at least 2), then names sharing a long end, then names sharing a
+ * long start (at least a third of the name, at least 4 characters). The end
+ * ranks before the start because ids tend to name an action before the item
+ * (`add-to-cart-backpack` becomes `remove-backpack` once clicked).
+ *
+ * @param name - Id or class that matched nothing
+ * @param candidates - Ids or classes on the page
+ * @returns Up to three similar names
+ */
+export declare function findSimilarNames(name: string, candidates: readonly string[]): string[];
+/** A selector that is just one id or one class, e.g. `#save` or `.btn-primary` */
+export interface SingleNameSelector {
+    kind: 'id' | 'class';
+    name: string;
+}
+/**
+ * Whether a selector is a single id or class (the kind "did you mean" can
+ * suggest for).
+ *
+ * @param selector - CSS selector
+ * @returns The id or class, or null for any other selector
+ */
+export declare function parseSingleNameSelector(selector: string): SingleNameSelector | null;
 export {};
 //# sourceMappingURL=suggestions.d.ts.map

package/dist/utils/suggestions.js

@@ -1,7 +1,7 @@
 /**
  * Suggestion utilities for typo detection and helpful error messages.
  */
-import { levenshteinDistance } from '../utils/levenshtein.js';
+import { levenshteinDistance } from './levenshtein.js';
 function normalizeForComparison(str, caseInsensitive) {
     return caseInsensitive ? str.toLowerCase() : str;
 }
@@ -31,4 +31,77 @@ export function formatSuggestions(suggestions, options = {}) {
 export function getSuggestion(input, candidates, options = {}) {
     return formatSuggestions(findSimilar(input, candidates, options), options);
 }
+/** Most similar ids or classes suggested for a selector that matched nothing */
+const MAX_SIMILAR_NAMES = 3;
+/**
+ * Length of the common start of two strings.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns Characters they share from the start
+ */
+function commonPrefixLength(a, b) {
+    let length = 0;
+    while (length < a.length && length < b.length && a[length] === b[length])
+        length++;
+    return length;
+}
+/**
+ * Length of the common end of two strings.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns Characters they share from the end
+ */
+function commonSuffixLength(a, b) {
+    let length = 0;
+    while (length < a.length &&
+        length < b.length &&
+        a[a.length - 1 - length] === b[b.length - 1 - length]) {
+        length++;
+    }
+    return length;
+}
+/**
+ * Names (ids or classes) similar to one that matched nothing, best first, at
+ * most three: near-typos first (Levenshtein distance up to a fifth of the
+ * length, at least 2), then names sharing a long end, then names sharing a
+ * long start (at least a third of the name, at least 4 characters). The end
+ * ranks before the start because ids tend to name an action before the item
+ * (`add-to-cart-backpack` becomes `remove-backpack` once clicked).
+ *
+ * @param name - Id or class that matched nothing
+ * @param candidates - Ids or classes on the page
+ * @returns Up to three similar names
+ */
+export function findSimilarNames(name, candidates) {
+    const others = [...new Set(candidates)].filter((candidate) => candidate !== name);
+    const maxDistance = Math.max(2, Math.floor(name.length / 5));
+    const minAffix = Math.max(4, Math.ceil(name.length / 3));
+    const typos = findMatches(name, others, maxDistance, false).map((match) => match.value);
+    const byAffix = (length) => others
+        .map((candidate) => ({ candidate, length: length(candidate) }))
+        .filter((entry) => entry.length >= minAffix)
+        .sort((a, b) => b.length - a.length)
+        .map((entry) => entry.candidate);
+    const ranked = [
+        ...typos,
+        ...byAffix((candidate) => commonSuffixLength(name, candidate)),
+        ...byAffix((candidate) => commonPrefixLength(name, candidate)),
+    ];
+    return [...new Set(ranked)].slice(0, MAX_SIMILAR_NAMES);
+}
+/**
+ * Whether a selector is a single id or class (the kind "did you mean" can
+ * suggest for).
+ *
+ * @param selector - CSS selector
+ * @returns The id or class, or null for any other selector
+ */
+export function parseSingleNameSelector(selector) {
+    const match = /^([#.])(-?[_a-zA-Z][\w-]*)$/.exec(selector.trim());
+    if (!match)
+        return null;
+    return { kind: match[1] === '#' ? 'id' : 'class', name: match[2] };
+}
 //# sourceMappingURL=suggestions.js.map

package/dist/utils/taskMappings.js

@@ -35,6 +35,11 @@ export const TASK_MAPPINGS = {
         description: 'Fill form input field by selector',
         cdpAlternative: 'Runtime.evaluate with value assignment',
     },
+    wait_for_element: {
+        commands: ['dom wait'],
+        description: 'Wait until an element appears, becomes visible, contains a text or is gone (or the page loads)',
+        cdpAlternative: 'Runtime.evaluate polling with querySelector (awaitPromise)',
+    },
     click_element: {
         commands: ['dom click'],
         description: 'Click element by selector',
@@ -50,6 +55,16 @@ export const TASK_MAPPINGS = {
         description: 'Get detailed element information',
         cdpAlternative: 'Runtime.evaluate with property extraction',
     },
+    inspect_event_listeners: {
+        commands: ['dom listeners'],
+        description: 'List event listeners for an element, incl. delegated ones on ancestors/document/window',
+        cdpAlternative: 'DOMDebugger.getEventListeners on the element and each ancestor',
+    },
+    element_layout: {
+        commands: ['dom layout'],
+        description: 'Where elements are (page/viewport coordinates, size), whether they are in view, hidden or covered',
+        cdpAlternative: 'Runtime.evaluate with getBoundingClientRect, getComputedStyle and elementFromPoint',
+    },
     accessibility_tree: {
         commands: ['dom a11y'],
         description: 'Get accessibility tree for page or element',
@@ -93,7 +108,7 @@ export const TASK_MAPPINGS = {
     preview_data: {
         commands: ['peek'],
         description: 'Preview collected network and console data',
-        cdpAlternative: 'Multiple IPC queries to worker state',
+        cdpAlternative: 'Multiple IPC queries to session state',
     },
     live_monitoring: {
         commands: ['peek --follow', 'tail'],
@@ -103,7 +118,7 @@ export const TASK_MAPPINGS = {
     get_full_details: {
         commands: ['details network', 'details console'],
         description: 'Get complete request/response or console message details',
-        cdpAlternative: 'Worker state query + response body fetch',
+        cdpAlternative: 'Session state query + response body fetch',
     },
     check_session_status: {
         commands: ['status'],

package/dist/utils/typeGuards.js

@@ -8,8 +8,8 @@
  * runtime errors. Type guards provide actual runtime validation while
  * maintaining type safety.
  */
-import { CommandError } from '../ui/errors/index.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
+import { CommandError } from '../errors/index.js';
+import { EXIT_CODES } from './exitCodes.js';
 /**
  * Type guard to check if a value is a valid NetworkRequest.
  *

package/dist/utils/url.d.ts

@@ -1,6 +1,7 @@
 /**
  * URL normalization, validation, and parsing utilities.
  */
+import { type ValidationResult } from './validation.js';
 /**
  * Normalize a URL by adding http:// protocol if missing.
  *
@@ -49,11 +50,7 @@ export declare function normalizeUrl(url: string): string;
  * All URLs are normalized before validation to support convenient formats like
  * 'localhost:3000' or 'example.com'.
  */
-export declare function validateUrl(url: string): {
-    valid: boolean;
-    error?: string;
-    suggestion?: string;
-};
+export declare function validateUrl(url: string): ValidationResult;
 /**
  * Safely parse a URL string with automatic protocol detection.
  *
@@ -71,6 +68,27 @@ export declare function validateUrl(url: string): {
  * ```
  */
 export declare function safeParseUrl(input: string): URL | null;
+/**
+ * The HTTP DevTools endpoint a `--chrome-ws-url` value names instead of a
+ * WebSocket URL: a port (`9222`), `host:port` (nothing after it), or an
+ * `http(s)://` URL of the endpoint (any path is ignored).
+ *
+ * @param value - Option value
+ * @returns Endpoint origin, e.g. `http://127.0.0.1:9222`, or null for anything else
+ */
+export declare function devToolsHttpEndpoint(value: string): string | null;
+/**
+ * Validate a `--chrome-ws-url` value.
+ *
+ * Accepted: `ws://` and `wss://` DevTools URLs, or the HTTP endpoint they come
+ * from ({@link devToolsHttpEndpoint}). Rejects other schemes, malformed URLs,
+ * and empty input so users hear about the problem at the CLI boundary
+ * instead of after a daemon round-trip.
+ *
+ * @param url - ws URL to validate
+ * @returns Validation result with error/suggestion when invalid
+ */
+export declare function validateChromeWsUrl(url: string): ValidationResult;
 /**
  * Extract hostname from a URL string safely.
  *

package/dist/utils/url.js

@@ -1,6 +1,8 @@
 /**
  * URL normalization, validation, and parsing utilities.
  */
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
+import { invalid, valid } from './validation.js';
 /**
  * Dangerous URL protocols that must be explicitly blocked.
  *
@@ -102,40 +104,26 @@ export function normalizeUrl(url) {
  */
 export function validateUrl(url) {
     if (!url || url.trim().length === 0) {
-        return {
-            valid: false,
-            error: 'URL cannot be empty',
-            suggestion: 'Provide a valid URL, e.g.: http://localhost:3000',
-        };
+        return invalid('URL cannot be empty', 'Provide a valid URL, e.g.: http://localhost:3000');
     }
     if (url.includes(' ')) {
-        return {
-            valid: false,
-            error: `Invalid URL format: '${url}' (contains spaces)`,
-            suggestion: 'URLs cannot contain spaces. If your URL has query parameters, wrap it in quotes: bdg "https://example.com/search?q=test"',
-        };
-    }
-    // Check for signs of shell glob expansion issues
-    // If URL looks like it might have been mangled by shell expansion
-    if (!url.includes('?') && !url.includes('&') && /^[a-z]+:\/\/[^/]+\/[^/]+$/.test(url)) {
-        // URL has path but no query params - might be fine, continue validation
+        return invalid(`Invalid URL format: '${url}' (contains spaces)`, 'Encode spaces as %20, e.g. bdg "https://example.com/search?q=a%20b"');
     }
     // Detect if URL looks truncated (common when shell expands ? as glob)
     if (url.endsWith('?') || url.endsWith('&')) {
-        return {
-            valid: false,
-            error: `URL appears truncated: '${url}'`,
-            suggestion: 'URLs with query parameters (? or &) must be quoted: bdg "https://example.com/search?q=test"',
-        };
+        return invalid(`URL appears truncated: '${url}'`, 'URLs with query parameters (? or &) must be quoted: bdg "https://example.com/search?q=test"');
+    }
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)?.[1]?.toLowerCase();
+    if (scheme && !VALID_PROTOCOLS.includes(`${scheme}:`)) {
+        return invalid(`Unsupported protocol: '${scheme}:'`, 'bdg opens http://, https://, file://, about:, chrome:, and data: URLs');
     }
     const normalized = normalizeUrl(url);
     const urlLower = url.toLowerCase();
+    if (urlLower.startsWith('javascript:')) {
+        return invalid(`Cannot start a session on a javascript: URL`, `Open a page first, then run the script: ${sessionCommand('bdg about:blank')} && ${sessionCommand("bdg dom eval '...'")}`);
+    }
     if (urlLower.startsWith('vbscript:')) {
-        return {
-            valid: false,
-            error: `Dangerous protocol: 'vbscript:' is not allowed`,
-            suggestion: 'Use http://, https://, or other safe protocols',
-        };
+        return invalid(`Dangerous protocol: 'vbscript:' is not allowed`, 'Use http://, https://, or other safe protocols');
     }
     const isSpecialProtocol = urlLower.startsWith('javascript:') ||
         urlLower.startsWith('data:') ||
@@ -143,45 +131,26 @@ export function validateUrl(url) {
     if (!isSpecialProtocol) {
         const beforePath = url.split('/')[0] ?? '';
         if (/[!@#$%^&*()=+[\]{}\\|;'",<>?]/.test(beforePath)) {
-            return {
-                valid: false,
-                error: `Invalid URL format: '${url}' (contains invalid characters)`,
-                suggestion: 'URLs cannot contain special characters like !, @, #, etc. in hostname or protocol',
-            };
+            return invalid(`Invalid URL format: '${url}' (contains invalid characters)`, 'URLs cannot contain special characters like !, @, #, etc. in hostname or protocol');
         }
     }
     try {
         const parsed = new URL(normalized);
         // Explicitly block dangerous protocols (CodeQL js/incomplete-url-scheme-check)
         if (DANGEROUS_PROTOCOLS.includes(parsed.protocol)) {
-            return {
-                valid: false,
-                error: `Blocked dangerous protocol: '${parsed.protocol}'`,
-                suggestion: 'This protocol is not allowed for security reasons',
-            };
+            return invalid(`Blocked dangerous protocol: '${parsed.protocol}'`, 'This protocol is not allowed for security reasons');
         }
         if (!VALID_PROTOCOLS.includes(parsed.protocol)) {
-            return {
-                valid: false,
-                error: `Invalid protocol: '${parsed.protocol}'`,
-                suggestion: 'URLs must use http://, https://, or other valid protocols',
-            };
+            return invalid(`Invalid protocol: '${parsed.protocol}'`, 'URLs must use http://, https://, or other valid protocols');
         }
-        if ((parsed.protocol === 'http:' || parsed.protocol === 'https:') && !parsed.hostname) {
-            return {
-                valid: false,
-                error: `Invalid URL format: '${url}' (missing hostname)`,
-                suggestion: 'URLs must include a valid hostname, e.g.: http://example.com',
-            };
+        const isWeb = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+        if (isWeb && !/[a-z0-9]/i.test(parsed.hostname)) {
+            return invalid(`Invalid URL format: '${url}' (missing hostname)`, 'URLs must include a valid hostname, e.g.: http://example.com');
         }
-        return { valid: true };
+        return valid();
     }
     catch {
-        return {
-            valid: false,
-            error: `Invalid URL format: '${url}'`,
-            suggestion: 'URLs must include a valid protocol (http:// or https://). If URL has query parameters, quote it: bdg "https://example.com?q=test"',
-        };
+        return invalid(`Invalid URL format: '${url}'`, 'URLs must include a valid protocol (http:// or https://). If URL has query parameters, quote it: bdg "https://example.com?q=test"');
     }
 }
 /**
@@ -213,6 +182,100 @@ export function safeParseUrl(input) {
         }
     }
 }
+/**
+ * The HTTP DevTools endpoint a `--chrome-ws-url` value names instead of a
+ * WebSocket URL: a port (`9222`), `host:port` (nothing after it), or an
+ * `http(s)://` URL of the endpoint (any path is ignored).
+ *
+ * @param value - Option value
+ * @returns Endpoint origin, e.g. `http://127.0.0.1:9222`, or null for anything else
+ */
+export function devToolsHttpEndpoint(value) {
+    const trimmed = value.trim();
+    if (/^\d{1,5}$/.test(trimmed)) {
+        return isValidPort(Number(trimmed)) ? `http://127.0.0.1:${trimmed}` : null;
+    }
+    const candidate = /^https?:\/\//i.test(trimmed)
+        ? trimmed
+        : /^[^/\s]+:\d{1,5}\/?$/.test(trimmed)
+            ? `http://${trimmed}`
+            : null;
+    if (candidate === null)
+        return null;
+    try {
+        const url = new URL(candidate);
+        return url.port === '' || isValidPort(Number(url.port)) ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a number is a usable TCP port (1-65535).
+ *
+ * @param port - Port number
+ * @returns True if in range
+ */
+function isValidPort(port) {
+    return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+/** A `--chrome-ws-url` value shaped like a port or `host:port` (port possibly missing) */
+const PORT_SHAPED_VALUE = /^(?:[^/\s]+:)?(\d*)\/?$/;
+/**
+ * Why a port-shaped `--chrome-ws-url` value (`99999`, `0`, `localhost:`) has
+ * no usable port.
+ *
+ * @param value - Trimmed option value that is not a valid endpoint
+ * @returns Error and suggestion, or null when the value is not port-shaped
+ */
+function portShapedValueError(value) {
+    const match = PORT_SHAPED_VALUE.exec(value);
+    if (!match || /^[a-z][a-z0-9+.-]*:\/\//i.test(value))
+        return null;
+    const digits = match[1] ?? '';
+    return invalid(digits === ''
+        ? `--chrome-ws-url is missing the port: '${value}'`
+        : `--chrome-ws-url port ${digits} is out of range (1-65535)`, 'Expected: the DevTools port (9222), host:port, or ws://host:port/devtools/browser/<uuid>');
+}
+/**
+ * Validate a `--chrome-ws-url` value.
+ *
+ * Accepted: `ws://` and `wss://` DevTools URLs, or the HTTP endpoint they come
+ * from ({@link devToolsHttpEndpoint}). Rejects other schemes, malformed URLs,
+ * and empty input so users hear about the problem at the CLI boundary
+ * instead of after a daemon round-trip.
+ *
+ * @param url - ws URL to validate
+ * @returns Validation result with error/suggestion when invalid
+ */
+export function validateChromeWsUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        return invalid('--chrome-ws-url cannot be empty', 'Expected: the DevTools port (9222), host:port, or ws://host:port/devtools/browser/<uuid>');
+    }
+    if (devToolsHttpEndpoint(trimmed) !== null)
+        return valid();
+    const portError = portShapedValueError(trimmed);
+    if (portError)
+        return portError;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return invalid(`--chrome-ws-url is not a valid URL: '${url}'`, 'Expected: the DevTools port (9222), host:port, or ws://host:port/devtools/browser/<uuid>');
+    }
+    if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+        return invalid(`--chrome-ws-url must use ws:// or wss://, got '${parsed.protocol}'`, `Give the DevTools port instead, e.g. --chrome-ws-url ${parsed.hostname || '127.0.0.1'}:9222`);
+    }
+    if (!parsed.hostname) {
+        return invalid(`--chrome-ws-url is missing a hostname: '${url}'`, 'Expected: the DevTools port (9222), host:port, or ws://host:port/devtools/browser/<uuid>');
+    }
+    if (!/^\/devtools\/(browser|page)\/[^/]+$/.test(parsed.pathname)) {
+        return invalid(`--chrome-ws-url must point to /devtools/browser/<id> or /devtools/page/<id>, got '${parsed.pathname}'`, `Find it with: curl -s http://${parsed.host}/json/version | jq -r .webSocketDebuggerUrl`);
+    }
+    return valid();
+}
 /**
  * Extract hostname from a URL string safely.
  *