browser-debugger-cli 0.8.0 → 0.9.0

package/dist/runtime/dom/waitCondition.js

@@ -0,0 +1,75 @@
+/**
+ * What `bdg dom wait` waits for, and whether what the page shows meets it.
+ *
+ * The page reports a {@link WaitSnapshot} whenever it changes; the condition
+ * is decided here, in one place.
+ */
+/**
+ * The text as the page compares it: whitespace collapsed, lower case (like `:has-text`).
+ *
+ * @param text - Text as given
+ * @returns Normalized text
+ */
+export function normalizeWaitText(text) {
+    return text.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+/**
+ * The matches the condition counts: visible ones with `visible`, else those
+ * containing the text (all matches without a text).
+ *
+ * @param snapshot - What the page shows
+ * @param condition - What is waited for
+ * @returns Number of counted matches
+ */
+export function countedMatches(snapshot, condition) {
+    return condition.visible ? snapshot.visibleCount : snapshot.textCount;
+}
+/**
+ * Whether the page shows what is waited for.
+ *
+ * Elements are gone only when two consecutive snapshots of the same
+ * document, neither of it still `loading`, show none: right after a
+ * navigation commits, the new document is empty for a moment.
+ *
+ * @param snapshot - What the page shows
+ * @param condition - What is waited for
+ * @param previous - The snapshot before it, if any
+ * @returns True when the elements are there (or gone with `gone`) and, with `load`, the page loaded
+ */
+export function isWaitConditionMet(snapshot, condition, previous) {
+    if (condition.load && snapshot.readyState !== 'complete')
+        return false;
+    if (condition.selector === undefined)
+        return true;
+    if (!condition.gone)
+        return countedMatches(snapshot, condition) > 0;
+    if (previous?.documentId !== snapshot.documentId)
+        return false;
+    return showsNoneSettled(previous, condition) && showsNoneSettled(snapshot, condition);
+}
+/**
+ * Whether a `--gone` wait should confirm this snapshot with another one: it
+ * shows no (counted) matches in a document past `loading`.
+ *
+ * @param snapshot - What the page shows
+ * @param condition - What is waited for
+ * @returns True when one more snapshot of the same document may meet the condition
+ */
+export function needsGoneConfirmation(snapshot, condition) {
+    if (!condition.gone || condition.selector === undefined)
+        return false;
+    if (condition.load && snapshot.readyState !== 'complete')
+        return false;
+    return showsNoneSettled(snapshot, condition);
+}
+/**
+ * No counted matches, in a document that is no longer `loading`.
+ *
+ * @param snapshot - What the page shows
+ * @param condition - What is waited for
+ * @returns True when nothing counted matches in a settled document
+ */
+function showsNoneSettled(snapshot, condition) {
+    return snapshot.readyState !== 'loading' && countedMatches(snapshot, condition) === 0;
+}
+//# sourceMappingURL=waitCondition.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * Page emulation a session was started with: the viewport size
+ * (`--viewport`) and `prefers-color-scheme` (`--color-scheme`).
+ *
+ * The overrides belong to the session's CDP connection: they last across
+ * navigations and reloads, and Chrome drops them when the session ends, so
+ * an attached Chrome (`--chrome-ws-url`) gets its own settings back.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { ColorScheme, ViewportSize } from '../../types.js';
+/**
+ * `Emulation.setDeviceMetricsOverride` parameters for a session viewport: a
+ * desktop viewport of that size at the display's own pixel ratio.
+ *
+ * @param viewport - Viewport size in CSS px
+ * @param deviceScaleFactor - Pixel ratio (0 keeps the display's)
+ * @returns CDP parameters
+ */
+export declare function viewportOverride(viewport: ViewportSize, deviceScaleFactor?: number): {
+    width: number;
+    height: number;
+    deviceScaleFactor: number;
+    mobile: false;
+};
+/**
+ * Apply the session's emulation to its page.
+ *
+ * @param cdp - Session connection
+ * @param emulation - Viewport and color scheme, when given at start
+ */
+export declare function applySessionEmulation(cdp: CDPConnection, emulation: {
+    viewport?: ViewportSize;
+    colorScheme?: ColorScheme;
+}): Promise<void>;
+/** What the page currently renders with, for `bdg status` */
+export interface PageAppearance {
+    /** Layout viewport without scrollbars (as `dom layout` reports it) */
+    viewport?: ViewportSize;
+    /** `prefers-color-scheme` the page sees */
+    colorScheme?: ColorScheme;
+}
+/**
+ * The viewport and color scheme the page renders with. A busy page (or one
+ * still navigating) does not answer within {@link APPEARANCE_TIMEOUT_MS}; then
+ * nothing is reported rather than holding up `bdg status`.
+ *
+ * @param cdp - Session connection
+ * @returns Viewport and color scheme, or nothing
+ */
+export declare function pageAppearance(cdp: CDPConnection): Promise<PageAppearance>;
+//# sourceMappingURL=emulation.d.ts.map

package/dist/runtime/page/emulation.js

@@ -0,0 +1,80 @@
+/**
+ * Page emulation a session was started with: the viewport size
+ * (`--viewport`) and `prefers-color-scheme` (`--color-scheme`).
+ *
+ * The overrides belong to the session's CDP connection: they last across
+ * navigations and reloads, and Chrome drops them when the session ends, so
+ * an attached Chrome (`--chrome-ws-url`) gets its own settings back.
+ */
+import { VIEWPORT_SIZE_JS } from '../dom/elementGeometry.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('session');
+/**
+ * `Emulation.setDeviceMetricsOverride` parameters for a session viewport: a
+ * desktop viewport of that size at the display's own pixel ratio.
+ *
+ * @param viewport - Viewport size in CSS px
+ * @param deviceScaleFactor - Pixel ratio (0 keeps the display's)
+ * @returns CDP parameters
+ */
+export function viewportOverride(viewport, deviceScaleFactor = 0) {
+    return { width: viewport.width, height: viewport.height, deviceScaleFactor, mobile: false };
+}
+/**
+ * Apply the session's emulation to its page.
+ *
+ * @param cdp - Session connection
+ * @param emulation - Viewport and color scheme, when given at start
+ */
+export async function applySessionEmulation(cdp, emulation) {
+    if (emulation.viewport) {
+        await cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride(emulation.viewport));
+    }
+    if (emulation.colorScheme) {
+        await cdp.send('Emulation.setEmulatedMedia', {
+            features: [{ name: 'prefers-color-scheme', value: emulation.colorScheme }],
+        });
+    }
+}
+/** How long `bdg status` waits for the page to report its appearance */
+const APPEARANCE_TIMEOUT_MS = 1000;
+/**
+ * The viewport and color scheme the page renders with. A busy page (or one
+ * still navigating) does not answer within {@link APPEARANCE_TIMEOUT_MS}; then
+ * nothing is reported rather than holding up `bdg status`.
+ *
+ * @param cdp - Session connection
+ * @returns Viewport and color scheme, or nothing
+ */
+export async function pageAppearance(cdp) {
+    const expression = `(() => {
+    const size = (${VIEWPORT_SIZE_JS})(window);
+    return { width: Math.round(size.width), height: Math.round(size.height), dark: matchMedia('(prefers-color-scheme: dark)').matches };
+  })()`;
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), APPEARANCE_TIMEOUT_MS);
+    });
+    try {
+        const response = (await Promise.race([
+            cdp.send('Runtime.evaluate', { expression, returnByValue: true }),
+            timeout,
+        ]));
+        const value = response?.result?.value;
+        if (!value)
+            return {};
+        return {
+            viewport: { width: value.width, height: value.height },
+            colorScheme: value.dark ? 'dark' : 'light',
+        };
+    }
+    catch (error) {
+        log.debug(`Could not read the page's viewport and color scheme: ${getErrorMessage(error)}`);
+        return {};
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=emulation.js.map

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

@@ -0,0 +1,36 @@
+/**
+ * Whether the page finished loading, and what it is still waiting for.
+ *
+ * Start and `bdg page` wait a limited time for the page; a document still
+ * `loading` after that (a script whose server never answers) makes every
+ * later command misleading, so they report it with the requests still
+ * running.
+ */
+import type { PendingRequestInfo, PageLoadingState } from '../../ipc/protocol/commands.js';
+import type { PendingRequest } from '../../telemetry/network.js';
+import type { CDPSender } from '../../telemetry/objectExpander.js';
+/**
+ * The requests to name: load-blocking ones (scripts, styles, images, frames)
+ * first, the longest-running first within each group.
+ *
+ * @param pending - Requests still running
+ * @param now - Current time (ms)
+ * @returns Up to {@link MAX_NAMED_PENDING_REQUESTS} requests
+ */
+export declare function summarizePendingRequests(pending: Iterable<PendingRequest>, now: number): PendingRequestInfo[];
+/**
+ * The page's `document.readyState`.
+ *
+ * @param cdp - CDP connection
+ * @returns The state, or undefined when the page did not answer in time
+ */
+export declare function readDocumentReadyState(cdp: CDPSender): Promise<string | undefined>;
+/**
+ * What the page is still loading, if it has not finished.
+ *
+ * @param cdp - CDP connection
+ * @param pending - Requests still running (from the session's network telemetry)
+ * @returns The loading state, or undefined when the document is complete or did not answer
+ */
+export declare function readPageLoadingState(cdp: CDPSender, pending: Iterable<PendingRequest>): Promise<PageLoadingState | undefined>;
+//# sourceMappingURL=loadingState.d.ts.map

package/dist/runtime/page/loadingState.js

@@ -0,0 +1,86 @@
+/**
+ * Whether the page finished loading, and what it is still waiting for.
+ *
+ * Start and `bdg page` wait a limited time for the page; a document still
+ * `loading` after that (a script whose server never answers) makes every
+ * later command misleading, so they report it with the requests still
+ * running.
+ */
+import { createLogger } from '../../ui/logging/index.js';
+import { raceTimeout } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('readiness');
+/** Pending requests named in the report */
+const MAX_NAMED_PENDING_REQUESTS = 3;
+/** How long the page gets to report its readyState (a busy page is not waited on) */
+const READY_STATE_TIMEOUT_MS = 1000;
+/** Request types that never hold up the load event, listed after the ones that do */
+const NON_BLOCKING_TYPES = new Set([
+    'XHR',
+    'Fetch',
+    'EventSource',
+    'Ping',
+    'Preflight',
+    'Prefetch',
+]);
+/**
+ * The requests to name: load-blocking ones (scripts, styles, images, frames)
+ * first, the longest-running first within each group.
+ *
+ * @param pending - Requests still running
+ * @param now - Current time (ms)
+ * @returns Up to {@link MAX_NAMED_PENDING_REQUESTS} requests
+ */
+export function summarizePendingRequests(pending, now) {
+    const rank = (entry) => NON_BLOCKING_TYPES.has(entry.request.resourceType ?? '') ? 1 : 0;
+    return [...pending]
+        .sort((a, b) => rank(a) - rank(b) || a.request.timestamp - b.request.timestamp)
+        .slice(0, MAX_NAMED_PENDING_REQUESTS)
+        .map(({ request }) => ({
+        method: request.method,
+        url: request.url,
+        ...(request.resourceType && { resourceType: request.resourceType }),
+        pendingMs: Math.max(0, now - request.timestamp),
+    }));
+}
+/**
+ * The page's `document.readyState`.
+ *
+ * @param cdp - CDP connection
+ * @returns The state, or undefined when the page did not answer in time
+ */
+export async function readDocumentReadyState(cdp) {
+    try {
+        const evaluated = cdp.send('Runtime.evaluate', {
+            expression: 'document.readyState',
+            returnByValue: true,
+        });
+        evaluated.catch(() => undefined);
+        const response = await raceTimeout(evaluated, READY_STATE_TIMEOUT_MS);
+        const value = response?.result?.value;
+        return typeof value === 'string' ? value : undefined;
+    }
+    catch (error) {
+        log.debug(`Could not read document.readyState: ${getErrorMessage(error)}`);
+        return undefined;
+    }
+}
+/**
+ * What the page is still loading, if it has not finished.
+ *
+ * @param cdp - CDP connection
+ * @param pending - Requests still running (from the session's network telemetry)
+ * @returns The loading state, or undefined when the document is complete or did not answer
+ */
+export async function readPageLoadingState(cdp, pending) {
+    const readyState = await readDocumentReadyState(cdp);
+    if (readyState === undefined || readyState === 'complete')
+        return undefined;
+    const requests = [...pending];
+    return {
+        readyState,
+        pending: summarizePendingRequests(requests, Date.now()),
+        pendingCount: requests.length,
+    };
+}
+//# sourceMappingURL=loadingState.js.map

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

@@ -3,6 +3,7 @@
  */
 import type { CDPConnection } from '../../connection/cdp.js';
 import type { PageAction, PageNavigationResult } from '../../ipc/protocol/commands.js';
+import type { PendingRequest } from '../../telemetry/network.js';
 import type { CDPSender } from '../../telemetry/objectExpander.js';
 /**
  * Navigate the session's page and wait until it has loaded.
@@ -11,17 +12,21 @@ import type { CDPSender } from '../../telemetry/objectExpander.js';
  * 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.
+ * 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
+ * @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 declare function navigatePage(cdp: CDPConnection, action: PageAction, options?: {
     url?: string;
     wait?: boolean;
+    pendingRequests?: () => Iterable<PendingRequest>;
 }): Promise<PageNavigationResult>;
 /**
  * The URL of a navigation still waiting for the server, if any: the page
@@ -31,4 +36,43 @@ export declare function navigatePage(cdp: CDPConnection, action: PageAction, opt
  * @returns The pending URL, or undefined when the page is not navigating
  */
 export declare function pendingNavigationUrl(cdp: CDPSender): Promise<string | undefined>;
+/** HTTP response of a document loaded in the main frame */
+interface DocumentResponse {
+    status: number;
+    url: string;
+}
+/** Documents the main frame loaded during a navigation */
+export interface DocumentResponses {
+    /** The navigation's own document (after HTTP redirects) */
+    first: DocumentResponse;
+    /** The last document loaded after it (a script or meta refresh moved on), if any */
+    later?: DocumentResponse;
+}
+/**
+ * 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 declare function withStatus(result: PageNavigationResult, documents: DocumentResponses | undefined): PageNavigationResult;
+/**
+ * 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 declare function documentResponse(cdp: Pick<CDPConnection, 'on'>, mainFrameId: string): {
+    response: (loaderId?: string) => DocumentResponses | undefined;
+    stop: () => void;
+};
+export {};
 //# sourceMappingURL=navigation.d.ts.map

package/dist/runtime/page/navigation.js

@@ -5,8 +5,9 @@ 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 { httpErrorWarning, notAPageWarning, stillLoadingWarning } from '../../ui/messages/commands.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';
@@ -21,11 +22,14 @@ const PAGE_READY_TIMEOUT_MS = 15_000;
  * 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.
+ * 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
+ * @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
  */
@@ -37,15 +41,17 @@ export async function navigatePage(cdp, action, options = {}) {
     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 === 'not-a-page') {
+        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()) });
@@ -55,7 +61,9 @@ export async function navigatePage(cdp, action, options = {}) {
         navigated.stop();
         document.stop();
     }
-    return withStatus({ action, ...(await currentLocation(cdp)) }, document.response());
+    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;
@@ -74,7 +82,7 @@ async function startWithoutWaiting(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;
+    return started?.notAPage ? { ...result, warning: notAPageWarning() } : result;
 }
 /**
  * Send the command of an action.
@@ -82,7 +90,7 @@ async function startWithoutWaiting(cdp, action, url) {
  * @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'
+ * @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) {
@@ -92,7 +100,7 @@ async function startAction(cdp, action, url) {
         await cdp.send('Page.reload', {});
     else
         await goThroughHistory(cdp, action === 'back' ? -1 : 1);
-    return 'started';
+    return { notAPage: false };
 }
 /**
  * The page target as the browser sees it. Unlike the page's own state, this
@@ -151,38 +159,64 @@ async function stillLoading(cdp, action) {
     };
 }
 /**
- * Add the document's HTTP status (and a warning for an error status).
+ * 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 response - The main document's response, if one arrived
+ * @param documents - The main frame's document responses, if one arrived
  * @returns Result with status
  */
-function withStatus(result, response) {
-    if (!response)
+export function withStatus(result, documents) {
+    if (!documents)
         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) }),
-    };
+    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 response of the main frame's next document.
+ * 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 response seen so far, and a function to stop listening
+ * @returns The responses seen so far (given the navigation's loader, if known),
+ *   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 };
-        }
+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);
     });
-    return { response: () => seen, stop };
+    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
@@ -216,15 +250,17 @@ function nextNavigation(cdp, mainFrameId) {
  *
  * @param cdp - CDP connection
  * @param url - Normalized URL
- * @returns 'not-a-page' when no document was loaded (a download), else 'started'
+ * @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 'not-a-page';
-    if (!navigation.errorText || !UNREACHABLE_ERRORS.test(navigation.errorText))
-        return 'started';
+    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);
 }

package/dist/session/QueryCacheManager.d.ts

@@ -18,11 +18,21 @@
  * }
  * ```
  */
-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 reading the cache.
  */