browser-debugger-cli 0.7.2 → 0.8.0

package/dist/runtime/dom/targetNode.js

@@ -0,0 +1,154 @@
+/**
+ * Bind interaction scripts to an exact DOM node.
+ *
+ * Indices from `bdg dom query` / `bdg dom form` refer to one specific node
+ * (by backend node id). Re-running the selector at action time would hit a
+ * different element after the DOM changed, so the node itself is handed to
+ * the page scripts: it is resolved through CDP and stored on `window`, and the
+ * scripts' element lookup ({@link FIND_ELEMENTS_JS}) returns it for
+ * {@link BOUND_TARGET_SELECTOR}.
+ */
+import { CommandError } from '../../errors/index.js';
+import { staleNodeError } from '../../errors/messages.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { parseSelectorFilters } from '../../utils/selectorFilters.js';
+/** Selector placeholder that makes page scripts use the bound node. */
+export const BOUND_TARGET_SELECTOR = '__bdg_bound_target__';
+/**
+ * Page-side test of one text or visibility filter ({@link SelectorFilter}).
+ * Visible means a non-empty box and `visibility: visible`, as in Playwright
+ * (`opacity: 0` still counts as visible). Text is the rendered text (`innerText`, `textContent` for elements without
+ * it) with whitespace collapsed; filter texts arrive normalized (`has-text`
+ * lowercased).
+ */
+const FILTER_MATCHES_JS = `(el, filter) => {
+  if (filter.kind === 'visible') {
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0 && el.ownerDocument.defaultView.getComputedStyle(el).visibility === 'visible';
+  }
+  const text = (typeof el.innerText === 'string' ? el.innerText : el.textContent || '').replace(/\\s+/g, ' ').trim();
+  return filter.kind === 'text-is' ? text === filter.text : text.toLowerCase().includes(filter.text);
+}`;
+/**
+ * Page-side selector search that also reaches into open shadow roots and
+ * same-origin iframes (recursively), like a user sees the page.
+ *
+ * Takes the selector and, when it has text or visibility filters, its parts
+ * from {@link parseSelectorFilters}: their CSS runs as one selector list and
+ * a match is kept when it passes the filters of a part it matches.
+ * Matches of the document come first, then those of each shadow root and
+ * frame in document order. Cross-origin iframes are separate processes and
+ * cannot be searched. Throws a `SyntaxError` for an invalid selector.
+ */
+export const DEEP_QUERY_JS = `function (selector, parts) {
+  const css = parts ? parts.map((part) => part.css).join(', ') : selector;
+  const found = [];
+  const visit = (root) => {
+    for (const match of root.querySelectorAll(css)) found.push(match);
+    for (const el of root.querySelectorAll('*')) {
+      if (el.shadowRoot) visit(el.shadowRoot);
+      if (el.tagName === 'IFRAME' || el.tagName === 'FRAME') {
+        let frameDocument = null;
+        try { frameDocument = el.contentDocument; } catch (e) { frameDocument = null; }
+        if (frameDocument) visit(frameDocument);
+      }
+    }
+  };
+  visit(document);
+  if (!parts) return found;
+  const passes = ${FILTER_MATCHES_JS};
+  return found.filter((el) => parts.some((part) => el.matches(part.css) && part.filters.every((filter) => passes(el, filter))));
+}`;
+/**
+ * Page-side element lookup shared by the interaction scripts.
+ *
+ * Returns the bound node (if still in the page) for the placeholder selector,
+ * otherwise all matches of the selector ({@link DEEP_QUERY_JS}).
+ */
+export const FIND_ELEMENTS_JS = `function (selector, parts) {
+  if (selector === '${BOUND_TARGET_SELECTOR}') {
+    const el = window.__bdgTarget;
+    return el && el.isConnected ? [el] : [];
+  }
+  return (${DEEP_QUERY_JS})(selector, parts);
+}`;
+/**
+ * Arguments for {@link DEEP_QUERY_JS} / {@link FIND_ELEMENTS_JS} and the page
+ * scripts built on them: the selector as a JS string literal and its parts
+ * (`null` for plain CSS, which runs unchanged).
+ *
+ * @param selector - Selector as the user gave it (or the bound-node placeholder)
+ * @returns JS source of the two arguments, e.g. `"li:visible", [{...}]`
+ * @throws CommandError (81) for a misplaced or malformed filter
+ */
+export function selectorArgsJS(selector) {
+    return `${JSON.stringify(selector)}, ${JSON.stringify(parseSelectorFilters(selector))}`;
+}
+/**
+ * Store the node for the page scripts. It runs in the node's own frame, while
+ * the scripts run in the top page, so the node goes on the top window (always
+ * reachable for the same-origin frames bdg can target).
+ */
+const BIND_FUNCTION = `function () {
+  let host = window;
+  try { host = window.top; host.__bdgTarget = this; } catch (e) { host = window; host.__bdgTarget = this; }
+  return this.isConnected;
+}`;
+/**
+ * Make the node with `backendNodeId` the target of the next page script.
+ *
+ * @param cdp - CDP connection
+ * @param backendNodeId - Backend node id from the query cache
+ * @throws CommandError (exit 87) when the node no longer exists in the page
+ */
+export async function bindTargetNode(cdp, backendNodeId) {
+    const err = staleNodeError();
+    const stale = new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+    let objectId;
+    try {
+        const resolved = (await cdp.send('DOM.resolveNode', { backendNodeId }));
+        objectId = resolved.object?.objectId;
+    }
+    catch {
+        throw stale;
+    }
+    if (!objectId)
+        throw stale;
+    const bound = (await cdp.send('Runtime.callFunctionOn', {
+        objectId,
+        functionDeclaration: BIND_FUNCTION,
+        returnByValue: true,
+    }));
+    if (bound.result?.value !== true)
+        throw stale;
+}
+/**
+ * Resolve what a page script should target for an interaction request.
+ *
+ * @param cdp - CDP connection
+ * @param params - Request with a selector (and optional index) or a backend node id
+ * @returns Selector/index for the page script
+ */
+export async function resolveScriptTarget(cdp, params) {
+    if (params.backendNodeId === undefined) {
+        return {
+            selector: params.selector ?? '',
+            ...(params.index !== undefined && { index: params.index }),
+        };
+    }
+    await bindTargetNode(cdp, params.backendNodeId);
+    return { selector: BOUND_TARGET_SELECTOR };
+}
+/**
+ * Report the user's selector instead of the internal placeholder.
+ *
+ * @param result - Script result
+ * @param selector - Selector the user gave (or the cached query's selector)
+ * @returns Result with the placeholder replaced
+ */
+export function withUserSelector(result, selector) {
+    if (result.selector !== BOUND_TARGET_SELECTOR)
+        return result;
+    return { ...result, ...(selector !== undefined && { selector }) };
+}
+//# sourceMappingURL=targetNode.js.map

package/dist/runtime/page/navigation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Page navigation for `bdg page navigate|reload|back|forward`.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { PageAction, PageNavigationResult } from '../../ipc/protocol/commands.js';
+import type { CDPSender } from '../../telemetry/objectExpander.js';
+/**
+ * Navigate the session's page and wait until it has loaded.
+ *
+ * With `wait: false` the command is sent and the call returns at once (the
+ * navigation may still be waiting for the server). Otherwise the server gets
+ * {@link PAGE_READY_TIMEOUT_MS} to answer, then the new document is waited on
+ * to settle; its HTTP status is reported, with a warning for 4xx/5xx, for a
+ * URL that is a download, or a page still loading.
+ *
+ * @param cdp - CDP connection
+ * @param action - Navigate to a URL, reload, or go back/forward in history
+ * @param options - `url` for navigate, `wait: false` to return without waiting
+ * @returns Where the page is now
+ * @throws CommandError (80) for an unreachable URL, (81) without a history entry
+ */
+export declare function navigatePage(cdp: CDPConnection, action: PageAction, options?: {
+    url?: string;
+    wait?: boolean;
+}): Promise<PageNavigationResult>;
+/**
+ * The URL of a navigation still waiting for the server, if any: the page
+ * target already shows it while the history's current entry does not.
+ *
+ * @param cdp - CDP connection
+ * @returns The pending URL, or undefined when the page is not navigating
+ */
+export declare function pendingNavigationUrl(cdp: CDPSender): Promise<string | undefined>;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/runtime/page/navigation.js

@@ -0,0 +1,249 @@
+/**
+ * Page navigation for `bdg page navigate|reload|back|forward`.
+ */
+import { waitForPageReady } from '../../connection/pageReadiness.js';
+import { UNREACHABLE_ERRORS } from '../../daemon/session/cdpSetup.js';
+import { CommandError } from '../../errors/index.js';
+import { navigationFailedError, noHistoryEntryError } from '../../errors/messages.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { httpErrorWarning, notAPageWarning, stillLoadingWarning } from '../../ui/messages/commands.js';
+import { delay } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { normalizeUrl } from '../../utils/url.js';
+const log = createLogger('session');
+/** How long to wait in all for the page to load and settle after navigating */
+const PAGE_READY_TIMEOUT_MS = 15_000;
+/**
+ * Navigate the session's page and wait until it has loaded.
+ *
+ * With `wait: false` the command is sent and the call returns at once (the
+ * navigation may still be waiting for the server). Otherwise the server gets
+ * {@link PAGE_READY_TIMEOUT_MS} to answer, then the new document is waited on
+ * to settle; its HTTP status is reported, with a warning for 4xx/5xx, for a
+ * URL that is a download, or a page still loading.
+ *
+ * @param cdp - CDP connection
+ * @param action - Navigate to a URL, reload, or go back/forward in history
+ * @param options - `url` for navigate, `wait: false` to return without waiting
+ * @returns Where the page is now
+ * @throws CommandError (80) for an unreachable URL, (81) without a history entry
+ */
+export async function navigatePage(cdp, action, options = {}) {
+    const url = action === 'navigate' ? normalizeUrl(options.url ?? '') : undefined;
+    if (options.wait === false)
+        return startWithoutWaiting(cdp, action, url);
+    const mainFrameId = (await pageTarget(cdp)).targetId;
+    const navigated = nextNavigation(cdp, mainFrameId);
+    const document = documentResponse(cdp, mainFrameId);
+    const deadline = Date.now() + PAGE_READY_TIMEOUT_MS;
+    try {
+        const sent = startAction(cdp, action, url);
+        sent.catch(() => undefined);
+        const started = await Promise.race([sent, delay(PAGE_READY_TIMEOUT_MS)]);
+        if (started === undefined)
+            return await stillLoading(cdp, action);
+        if (started === 'not-a-page') {
+            return { action, ...(await currentLocation(cdp)), warning: notAPageWarning() };
+        }
+        const how = await Promise.race([navigated.done, delay(Math.max(0, deadline - Date.now()))]);
+        if (how === 'loaded') {
+            await waitForPageReady(cdp, { maxWaitMs: Math.max(0, deadline - Date.now()) });
+        }
+    }
+    finally {
+        navigated.stop();
+        document.stop();
+    }
+    return withStatus({ action, ...(await currentLocation(cdp)) }, document.response());
+}
+/** How long `--no-wait` waits for an action to be refused (no history entry, unreachable URL) */
+const NO_WAIT_GRACE_MS = 1_000;
+/**
+ * Start an action without waiting for the page: errors that come at once
+ * are still reported, a server that has not answered is not waited for.
+ *
+ * @param cdp - CDP connection
+ * @param action - What to do
+ * @param url - Normalized URL for navigate
+ * @returns The URL being loaded
+ * @throws CommandError (80) for an unreachable URL, (81) without a history entry
+ */
+async function startWithoutWaiting(cdp, action, url) {
+    const sent = startAction(cdp, action, url);
+    sent.catch((error) => log.debug(`Navigation not started: ${getErrorMessage(error)}`));
+    const started = await Promise.race([sent, delay(NO_WAIT_GRACE_MS)]);
+    const result = { action, url: url ?? (await pageTarget(cdp)).url, title: '' };
+    return started === 'not-a-page' ? { ...result, warning: notAPageWarning() } : result;
+}
+/**
+ * Send the command of an action.
+ *
+ * @param cdp - CDP connection
+ * @param action - What to do
+ * @param url - Normalized URL for navigate
+ * @returns 'not-a-page' when the URL loaded no document (a download), else 'started'
+ * @throws CommandError (80) when the URL cannot be reached, (81) without a history entry
+ */
+async function startAction(cdp, action, url) {
+    if (action === 'navigate')
+        return navigateTo(cdp, url ?? '');
+    if (action === 'reload')
+        await cdp.send('Page.reload', {});
+    else
+        await goThroughHistory(cdp, action === 'back' ? -1 : 1);
+    return 'started';
+}
+/**
+ * The page target as the browser sees it. Unlike the page's own state, this
+ * answers while a navigation waits for the server (Chrome holds commands for
+ * the page until the new document commits). A page target's id is its main
+ * frame's id; its URL is the one being navigated to.
+ *
+ * @param cdp - CDP connection
+ * @returns Target id and URL
+ */
+async function pageTarget(cdp) {
+    const { targetInfo } = (await cdp.send('Target.getTargetInfo', {}));
+    return targetInfo;
+}
+/**
+ * The URL of a navigation still waiting for the server, if any: the page
+ * target already shows it while the history's current entry does not.
+ *
+ * @param cdp - CDP connection
+ * @returns The pending URL, or undefined when the page is not navigating
+ */
+export async function pendingNavigationUrl(cdp) {
+    const [target, history] = await Promise.all([
+        pageTarget(cdp),
+        cdp.send('Page.getNavigationHistory', {}),
+    ]);
+    const committedUrl = history.entries[history.currentIndex]?.url;
+    return target.url !== committedUrl ? target.url : undefined;
+}
+/**
+ * The page's URL and title.
+ *
+ * @param cdp - CDP connection
+ * @returns URL and title
+ */
+async function currentLocation(cdp) {
+    const location = (await cdp.send('Runtime.evaluate', {
+        expression: '({ url: location.href, title: document.title })',
+        returnByValue: true,
+    }));
+    return { url: location.result?.value?.url ?? '', title: location.result?.value?.title ?? '' };
+}
+/**
+ * Result for a server that has not answered within the time limit.
+ *
+ * @param cdp - CDP connection
+ * @param action - What was done
+ * @returns The URL being loaded, with a warning
+ */
+async function stillLoading(cdp, action) {
+    return {
+        action,
+        url: (await pageTarget(cdp)).url,
+        title: '',
+        warning: stillLoadingWarning(PAGE_READY_TIMEOUT_MS),
+    };
+}
+/**
+ * Add the document's HTTP status (and a warning for an error status).
+ *
+ * @param result - Navigation result
+ * @param response - The main document's response, if one arrived
+ * @returns Result with status
+ */
+function withStatus(result, response) {
+    if (!response)
+        return result;
+    const url = result.url.startsWith('chrome-error://') ? response.url : result.url;
+    return {
+        ...result,
+        url,
+        status: response.status,
+        ...(response.status >= 400 && { warning: httpErrorWarning(response.status) }),
+    };
+}
+/**
+ * Watch for the response of the main frame's next document.
+ *
+ * @param cdp - CDP connection
+ * @param mainFrameId - Main frame id
+ * @returns The response seen so far, and a function to stop listening
+ */
+function documentResponse(cdp, mainFrameId) {
+    let seen;
+    const stop = cdp.on('Network.responseReceived', (params) => {
+        if (params.type === 'Document' && params.frameId === mainFrameId) {
+            seen = { status: params.response.status, url: params.response.url };
+        }
+    });
+    return { response: () => seen, stop };
+}
+/**
+ * Resolve once the page has loaded a new document, moved within its
+ * document (hash or history changes), or was restored from the back/forward
+ * cache (those fire no load event). Only a newly loaded document is then
+ * waited on to settle: a restored or same-document page already is. Without this, the
+ * readiness check would see the old page, still complete, and return at once.
+ *
+ * @param cdp - CDP connection
+ * @param mainFrameId - The page's main frame (iframes moving within their document don't count)
+ * @returns The wait, and a function to stop listening
+ */
+function nextNavigation(cdp, mainFrameId) {
+    const unsubscribes = [];
+    const done = new Promise((resolve) => {
+        unsubscribes.push(cdp.on('Page.loadEventFired', () => resolve('loaded')));
+        unsubscribes.push(cdp.on('Page.navigatedWithinDocument', (params) => {
+            if (params.frameId === mainFrameId)
+                resolve('same-document');
+        }));
+        unsubscribes.push(cdp.on('Page.frameNavigated', (params) => {
+            if (!params.frame.parentId && params.type === 'BackForwardCacheRestore') {
+                resolve('restored');
+            }
+        }));
+    });
+    return { done, stop: () => unsubscribes.forEach((unsubscribe) => unsubscribe()) };
+}
+/**
+ * Load a URL in the page.
+ *
+ * @param cdp - CDP connection
+ * @param url - Normalized URL
+ * @returns 'not-a-page' when no document was loaded (a download), else 'started'
+ * @throws CommandError (80) when the URL cannot be reached
+ */
+async function navigateTo(cdp, url) {
+    const navigation = (await cdp.send('Page.navigate', { url }));
+    if (navigation.errorText === 'net::ERR_ABORTED' && !navigation.loaderId)
+        return 'not-a-page';
+    if (!navigation.errorText || !UNREACHABLE_ERRORS.test(navigation.errorText))
+        return 'started';
+    const err = navigationFailedError(url, navigation.errorText);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_URL);
+}
+/**
+ * Go back or forward one entry in the page's history.
+ *
+ * @param cdp - CDP connection
+ * @param step - -1 for back, 1 for forward
+ * @throws CommandError (81) when there is no such entry
+ */
+async function goThroughHistory(cdp, step) {
+    const history = (await cdp.send('Page.getNavigationHistory', {}));
+    const index = history.currentIndex + step;
+    const entry = history.entries[index];
+    const blankStart = index === 0 && entry?.url === 'about:blank';
+    if (!entry || blankStart) {
+        const err = noHistoryEntryError(step < 0 ? 'back' : 'forward');
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    await cdp.send('Page.navigateToHistoryEntry', { entryId: entry.id });
+}
+//# sourceMappingURL=navigation.js.map

package/dist/session/QueryCacheManager.d.ts

@@ -1,22 +1,17 @@
 /**
  * Query cache manager for DOM element index-based access.
  *
- * Provides centralized management of DOM query result caching with:
- * - Singleton pattern for consistent cache access
- * - Navigation-aware staleness detection
- * - TTL-based navigation ID caching to reduce IPC calls
- *
- * The cache enables index-based element access patterns like
- * "bdg dom get 0" after running "bdg dom query .selector".
+ * Stores the last `bdg dom query` / `bdg dom form` result so later commands
+ * can address its elements by index ("bdg dom get 0"). Each cached node holds
+ * its backend node id, which identifies that exact element for as long as it
+ * stays in the page; whether it still does is checked when the index is used,
+ * not here.
  *
  * @example
  * ```typescript
  * const manager = QueryCacheManager.getInstance();
- *
- * // Store query results
  * await manager.set(queryResult);
  *
- * // Validate and retrieve (throws if stale)
  * const validation = await manager.validate();
  * if (validation.valid) {
  *   const cache = validation.cache;
@@ -25,28 +20,27 @@
  */
 import type { DomQueryResult } from '../types.js';
 /**
- * Result of validating query cache against current navigation state.
+ * Selector recorded for `dom form` results (fields carry their own selectors).
+ */
+export declare const FORM_DISCOVERY_CACHE_SELECTOR = "form:auto-discovered";
+/**
+ * Result of reading the cache.
  */
 export interface QueryCacheValidation {
-    /** Whether the cache is valid for use. */
+    /** Whether cached indices can be used */
     valid: boolean;
-    /** The cached query result (if exists). */
+    /** Cached result, if readable */
     cache: DomQueryResult | null;
-    /** Error message if cache is invalid. */
+    /** Why the cache can't be used */
     error?: string;
-    /** Suggestion for fixing the error. */
+    /** How to fix it */
     suggestion?: string;
 }
 /**
- * Singleton manager for DOM query result caching.
- *
- * Centralizes all cache operations with navigation-aware staleness detection.
- * Uses file-based persistence for cross-process access.
+ * Singleton manager for the on-disk query cache.
  */
 export declare class QueryCacheManager {
     private static instance;
-    /** Cached navigation ID with timestamp for TTL-based invalidation. */
-    private cachedNavigationId;
     /**
      * Get the singleton instance.
      *
@@ -58,83 +52,32 @@ export declare class QueryCacheManager {
      */
     static resetInstance(): void;
     /**
-     * Get path to query cache file.
+     * Path of the cache file in the session directory.
      *
-     * @returns Absolute path to query-cache.json
+     * @returns Absolute cache file path
      */
     private getCachePath;
     /**
-     * Store query results for index-based access.
-     *
-     * Writes results to ~/.bdg/query-cache.json for cross-process access.
+     * Store a query result.
      *
-     * @param result - DOM query result to cache
+     * @param result - Query result whose nodes carry backend node ids
      */
     set(result: DomQueryResult): Promise<void>;
     /**
-     * Get validated cache results.
-     *
-     * Returns null if cache is stale or doesn't exist.
-     * Use getRaw() for unchecked access.
-     *
-     * @returns Cached query result or null if invalid/missing
-     */
-    get(): Promise<DomQueryResult | null>;
-    /**
-     * Get raw cache without validation.
-     *
-     * Reads from ~/.bdg/query-cache.json if it exists.
-     * Does not check navigation staleness.
-     *
-     * @returns Cached query result or null if no cache exists
-     */
-    getRaw(): Promise<DomQueryResult | null>;
-    /**
-     * Validate cache against current navigation state.
-     *
-     * Checks if the cached query results are still valid by comparing
-     * the stored navigationId with the current one from the daemon.
+     * Read the cache and check that it can be used.
      *
-     * @returns Validation result with cache and error info
-     *
-     * @example
-     * ```typescript
-     * const validation = await manager.validate();
-     * if (!validation.valid) {
-     *   throw new CommandError(validation.error, { suggestion: validation.suggestion });
-     * }
-     * const cache = validation.cache;
-     * ```
+     * @returns Validation result with the cached query when usable
      */
     validate(): Promise<QueryCacheValidation>;
     /**
-     * Clear the query cache.
-     *
-     * Removes ~/.bdg/query-cache.json.
-     * Called when starting a new query or when the session ends.
+     * Remove the cache file.
      */
     clear(): Promise<void>;
     /**
-     * Check if cache file exists.
-     *
-     * @returns True if cache file exists
-     */
-    exists(): boolean;
-    /**
-     * Get current navigation ID from the daemon.
-     *
-     * Caches the result for 500ms to avoid redundant IPC calls within a single
-     * command execution while ensuring freshness for subsequent commands.
-     *
-     * @returns Current navigation ID or null if unavailable
-     */
-    getCurrentNavigationId(): Promise<number | null>;
-    /**
-     * Invalidate cached navigation ID.
+     * Read the raw cache file.
      *
-     * Forces fresh fetch on next getCurrentNavigationId() call.
-     * Useful after navigation events.
+     * @returns Parsed cache content, or null if missing/unreadable
      */
-    invalidateNavigationCache(): void;
+    private read;
 }
 //# sourceMappingURL=QueryCacheManager.d.ts.map