browser-debugger-cli 0.7.2 → 0.9.0

package/dist/runtime/page/navigation.js

@@ -0,0 +1,285 @@
+/**
+ * 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 { readPageLoadingState } from './loadingState.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { documentStatusWarning, 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 server that has not answered. A document
+ * that has not finished loading by then is reported as `loading`, with the
+ * requests it waits on.
+ *
+ * @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,
+ *   `pendingRequests`: the session's requests still running
+ * @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;
+    let loaderId;
+    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.notAPage) {
+            return { action, ...(await currentLocation(cdp)), warning: notAPageWarning() };
+        }
+        loaderId = started.loaderId;
+        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();
+    }
+    const result = withStatus({ action, ...(await currentLocation(cdp)) }, document.response(loaderId));
+    const loading = await readPageLoadingState(cdp, options.pendingRequests?.() ?? []);
+    return loading ? { ...result, loading } : result;
+}
+/** 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?.notAPage ? { ...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 Whether a document is loading, and its loader when known
+ * @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 { notAPage: false };
+}
+/**
+ * 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 HTTP status of the navigation's own document, with a warning for an
+ * error status or for a later document that answered differently (a 404 page
+ * whose script loads the app, as single-page apps on static hosts do).
+ *
+ * @param result - Navigation result
+ * @param documents - The main frame's document responses, if one arrived
+ * @returns Result with status
+ */
+export function withStatus(result, documents) {
+    if (!documents)
+        return result;
+    const { first, later } = documents;
+    const url = result.url.startsWith('chrome-error://') ? first.url : result.url;
+    const warning = documentStatusWarning(first.status, later);
+    return { ...result, url, status: first.status, ...(warning && { warning }) };
+}
+/**
+ * Watch for the responses of the main frame's documents. Only documents
+ * requested after the watch began count (a response to a request from
+ * before belongs to an earlier navigation). The navigation's own document
+ * is the one of its loader when the browser named it, else the first; the
+ * documents after it were loaded by the page itself.
+ *
+ * @param cdp - CDP connection
+ * @param mainFrameId - Main frame id
+ * @returns The responses seen so far (given the navigation's loader, if known),
+ *   and a function to stop listening
+ */
+export function documentResponse(cdp, mainFrameId) {
+    const requested = new Set();
+    const responses = [];
+    const isMainDocument = (params) => params.type === 'Document' && params.frameId === mainFrameId;
+    const stopRequests = cdp.on('Network.requestWillBeSent', (params) => {
+        if (isMainDocument(params))
+            requested.add(params.requestId);
+    });
+    const stopResponses = cdp.on('Network.responseReceived', (params) => {
+        if (!isMainDocument(params) || !requested.has(params.requestId))
+            return;
+        const { status, url } = params.response;
+        responses.push({ status, url, ...(params.loaderId && { loaderId: params.loaderId }) });
+    });
+    const response = (loaderId) => {
+        const index = loaderId ? responses.findIndex((r) => r.loaderId === loaderId) : 0;
+        const own = responses[index];
+        if (index < 0 || !own)
+            return undefined;
+        const last = responses.length - 1 > index ? responses[responses.length - 1] : undefined;
+        const first = { status: own.status, url: own.url };
+        return last ? { first, later: { status: last.status, url: last.url } } : { first };
+    };
+    return {
+        response,
+        stop: () => {
+            stopRequests();
+            stopResponses();
+        },
+    };
+}
+/**
+ * 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 Whether a document is loading (not for a download), and its loader
+ * @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 { notAPage: true };
+    }
+    if (!navigation.errorText || !UNREACHABLE_ERRORS.test(navigation.errorText)) {
+        return { notAPage: false, ...(navigation.loaderId && { loaderId: navigation.loaderId }) };
+    }
+    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,52 +1,56 @@
 /**
  * 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;
  * }
  * ```
  */
-import type { DomQueryResult } from '../types.js';
+import type { DomQueryResult, IndexSource } from '../types.js';
+/**
+ * Selector recorded for `dom form` results (fields carry their own selectors).
+ */
+export declare const FORM_DISCOVERY_CACHE_SELECTOR = "form:auto-discovered";
+/** Prefix of the selector recorded for `dom a11y query` results (followed by the pattern) */
+export declare const A11Y_CACHE_SELECTOR_PREFIX = "a11y ";
+/**
+ * The list an index refers to, from the selector recorded with the cache.
+ *
+ * @param index - The index the user gave
+ * @param cacheSelector - Selector recorded with the cached results
+ * @returns The command whose results are cached, and its query
+ */
+export declare function indexSourceOf(index: number, cacheSelector: string): IndexSource;
 /**
- * Result of validating query cache against current navigation state.
+ * 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 +62,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.
+     * Read the cache and check that it can be used.
      *
-     * @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.
-     *
-     * @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