browser-debugger-cli 0.11.0 → 0.13.0

package/dist/runtime/page/bdgWorld.js

@@ -0,0 +1,180 @@
+/**
+ * bdg's own JavaScript world in the page (a CDP isolated world): it shares
+ * the DOM with the page but has its own built-ins, so a page that replaces
+ * `Element.prototype.querySelectorAll`, `JSON.stringify` or
+ * `Array.prototype.map` (polyfills, old frameworks, anti-bot scripts) cannot
+ * change what bdg's page scripts find or return.
+ *
+ * Only the entry points need the world: `Runtime.evaluate` runs in it with
+ * its `contextId`, and `DOM.resolveNode` hands out objects of it with its
+ * `executionContextId`; `Runtime.callFunctionOn` on such an object runs in
+ * the same world. The world belongs to the top frame (same-origin iframes are
+ * reached through it); a node of another frame, a connection without the
+ * Page domain (a frame-scoped one) or a failure to create it fall back to the
+ * main world, as before.
+ */
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('cdp');
+/** Name of bdg's isolated world (shown in DevTools' context selector) */
+export const BDG_WORLD_NAME = 'bdg';
+/** Errors of a context that is gone (navigation, reload) */
+const CONTEXT_GONE = /Cannot find context with specified id|Execution context was destroyed/;
+/** The world's context id per connection, until the page navigates */
+const worlds = new WeakMap();
+/**
+ * The execution context id of bdg's world in the top frame, created on first
+ * use and forgotten when the top frame navigates or its contexts are cleared.
+ *
+ * @param cdp - Connection to the page
+ * @returns Context id, or null when no world can be made on this connection
+ */
+function worldContext(cdp) {
+    const known = worlds.get(cdp);
+    if (known)
+        return known;
+    const created = createWorld(cdp);
+    worlds.set(cdp, created);
+    return created;
+}
+/**
+ * Create the world in the top frame and forget it when the page changes.
+ *
+ * @param cdp - Connection to the page
+ * @returns Context id, or null when it cannot be created
+ */
+async function createWorld(cdp) {
+    const { on } = cdp;
+    if (!on)
+        return null;
+    try {
+        const { frameTree } = (await cdp.send('Page.getFrameTree'));
+        const { executionContextId } = (await cdp.send('Page.createIsolatedWorld', {
+            frameId: frameTree.frame.id,
+            worldName: BDG_WORLD_NAME,
+            grantUniveralAccess: false,
+        }));
+        const forget = () => {
+            if (worlds.get(cdp) === created)
+                worlds.delete(cdp);
+            stopNavigated();
+            stopCleared();
+        };
+        const created = worlds.get(cdp);
+        const stopNavigated = on.call(cdp, 'Page.frameNavigated', (params) => {
+            if (params.frame.parentId === undefined)
+                forget();
+        });
+        const stopCleared = on.call(cdp, 'Runtime.executionContextsCleared', forget);
+        return executionContextId;
+    }
+    catch (error) {
+        log.debug(`bdg's isolated world not available: ${getErrorMessage(error)}`);
+        worlds.delete(cdp);
+        return null;
+    }
+}
+/**
+ * Send a command with the world's context, once more with a new world when
+ * the context is gone, and in the main world when there is none.
+ *
+ * @param cdp - Connection to the page
+ * @param method - CDP method
+ * @param params - Its parameters
+ * @param withContext - The parameters with the world's context id
+ * @returns The command's result
+ */
+async function sendInWorld(cdp, method, params, withContext) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const contextId = await worldContext(cdp);
+        if (contextId === null)
+            break;
+        try {
+            return await cdp.send(method, withContext(contextId));
+        }
+        catch (error) {
+            if (!CONTEXT_GONE.test(getErrorMessage(error)))
+                throw error;
+            worlds.delete(cdp);
+        }
+    }
+    return cdp.send(method, params);
+}
+/**
+ * `Runtime.evaluate` in bdg's world of the top frame. A call that names its
+ * own context is sent as it is.
+ *
+ * @param cdp - Connection to the page
+ * @param params - Evaluate parameters
+ * @returns Evaluate response
+ */
+export async function evaluateInBdgWorld(cdp, params) {
+    if (params.contextId !== undefined || params.uniqueContextId !== undefined) {
+        return (await cdp.send('Runtime.evaluate', { ...params }));
+    }
+    return (await sendInWorld(cdp, 'Runtime.evaluate', { ...params }, (contextId) => ({
+        ...params,
+        contextId,
+    })));
+}
+/**
+ * `DOM.resolveNode` into bdg's world of the top frame, so functions called on
+ * the node run there. A node the world cannot use (one of a cross-origin
+ * frame, or one no longer in the page) is resolved in its own frame's main
+ * world, as before.
+ *
+ * @param cdp - Connection to the page
+ * @param params - Resolve parameters
+ * @returns Resolve response
+ */
+export async function resolveNodeInBdgWorld(cdp, params) {
+    if (params.executionContextId !== undefined) {
+        return (await cdp.send('DOM.resolveNode', { ...params }));
+    }
+    try {
+        const resolved = (await sendInWorld(cdp, 'DOM.resolveNode', { ...params }, (executionContextId) => ({ ...params, executionContextId })));
+        if (await usableInWorld(cdp, resolved.object.objectId))
+            return resolved;
+    }
+    catch (error) {
+        log.debug(`Node resolved in the page's world: ${getErrorMessage(error)}`);
+    }
+    return (await cdp.send('DOM.resolveNode', { ...params }));
+}
+/**
+ * Whether a node resolved into bdg's world can be used there: a node of a
+ * cross-origin frame resolves, but every access to it throws.
+ *
+ * @param cdp - Connection to the page
+ * @param objectId - The node in bdg's world
+ * @returns True when it can be read
+ */
+async function usableInWorld(cdp, objectId) {
+    if (!objectId)
+        return false;
+    const probe = (await cdp.send('Runtime.callFunctionOn', {
+        objectId,
+        functionDeclaration: 'function () { try { return this.isConnected === true; } catch (e) { return false; } }',
+        returnByValue: true,
+    }));
+    return probe.result.value === true;
+}
+/**
+ * Send a CDP command for bdg's own scripts: `Runtime.evaluate` and
+ * `DOM.resolveNode` go to bdg's world, other methods as they are.
+ *
+ * @param cdp - Connection to the page
+ * @param method - CDP method
+ * @param params - Its parameters
+ * @returns The command's result
+ */
+export function sendForBdgScript(cdp, method, params) {
+    if (method === 'Runtime.evaluate') {
+        return evaluateInBdgWorld(cdp, params);
+    }
+    if (method === 'DOM.resolveNode') {
+        return resolveNodeInBdgWorld(cdp, params);
+    }
+    return cdp.send(method, params);
+}
+//# sourceMappingURL=bdgWorld.js.map

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

@@ -10,17 +10,18 @@ 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.
+ * desktop viewport of that size at the display's own pixel ratio, or a
+ * phone's (mobile layout: meta viewport, overlay scrollbars; pixel ratio 3).
  *
- * @param viewport - Viewport size in CSS px
- * @param deviceScaleFactor - Pixel ratio (0 keeps the display's)
+ * @param viewport - Viewport size in CSS px, `mobile` for a phone
+ * @param deviceScaleFactor - Pixel ratio (0 keeps the display's, or a phone's)
  * @returns CDP parameters
  */
 export declare function viewportOverride(viewport: ViewportSize, deviceScaleFactor?: number): {
     width: number;
     height: number;
     deviceScaleFactor: number;
-    mobile: false;
+    mobile: boolean;
 };
 /**
  * Apply the session's emulation to its page.
@@ -32,6 +33,14 @@ export declare function applySessionEmulation(cdp: CDPConnection, emulation: {
     viewport?: ViewportSize;
     colorScheme?: ColorScheme;
 }): Promise<void>;
+/**
+ * A mobile user agent from a desktop one: an Android platform, `Mobile`
+ * before `Safari`, and `Chrome` for `HeadlessChrome`.
+ *
+ * @param desktop - The browser's user agent
+ * @returns Mobile user agent
+ */
+export declare function mobileUserAgent(desktop: string): string;
 /** Page emulation of a session: what `--viewport` and `--color-scheme` set */
 export interface SessionEmulation {
     viewport?: ViewportSize;

package/dist/runtime/page/emulation.js

@@ -7,19 +7,29 @@
  * an attached Chrome (`--chrome-ws-url`) gets its own settings back.
  */
 import { VIEWPORT_SIZE_JS } from '../dom/elementGeometry.js';
+import { hideHeadlessUserAgent } from './userAgent.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { getErrorMessage } from '../../utils/errors.js';
 const log = createLogger('session');
+/** Pixel ratio of an emulated phone (a common one) */
+const MOBILE_PIXEL_RATIO = 3;
 /**
  * `Emulation.setDeviceMetricsOverride` parameters for a session viewport: a
- * desktop viewport of that size at the display's own pixel ratio.
+ * desktop viewport of that size at the display's own pixel ratio, or a
+ * phone's (mobile layout: meta viewport, overlay scrollbars; pixel ratio 3).
  *
- * @param viewport - Viewport size in CSS px
- * @param deviceScaleFactor - Pixel ratio (0 keeps the display's)
+ * @param viewport - Viewport size in CSS px, `mobile` for a phone
+ * @param deviceScaleFactor - Pixel ratio (0 keeps the display's, or a phone's)
  * @returns CDP parameters
  */
 export function viewportOverride(viewport, deviceScaleFactor = 0) {
-    return { width: viewport.width, height: viewport.height, deviceScaleFactor, mobile: false };
+    const mobile = viewport.mobile === true;
+    return {
+        width: viewport.width,
+        height: viewport.height,
+        deviceScaleFactor: deviceScaleFactor || (mobile ? MOBILE_PIXEL_RATIO : 0),
+        mobile,
+    };
 }
 /**
  * Apply the session's emulation to its page.
@@ -30,6 +40,8 @@ export function viewportOverride(viewport, deviceScaleFactor = 0) {
 export async function applySessionEmulation(cdp, emulation) {
     if (emulation.viewport) {
         await cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride(emulation.viewport));
+        if (emulation.viewport.mobile)
+            await emulatePhone(cdp, true);
     }
     if (emulation.colorScheme) {
         await cdp.send('Emulation.setEmulatedMedia', {
@@ -37,6 +49,55 @@ export async function applySessionEmulation(cdp, emulation) {
         });
     }
 }
+/**
+ * Turn the rest of a phone's emulation on or off: touch input (and
+ * `pointer: coarse`) and a mobile user agent derived from the browser's own
+ * (an Android one), or the browser's own back: the override cleared, or in
+ * headless Chrome its regular-Chrome identity ({@link hideHeadlessUserAgent}).
+ *
+ * @param cdp - Session connection
+ * @param on - Emulate a phone
+ */
+async function emulatePhone(cdp, on) {
+    await cdp.send('Emulation.setTouchEmulationEnabled', { enabled: on, maxTouchPoints: on ? 5 : 1 });
+    const { userAgent } = (await cdp.send('Browser.getVersion', {}));
+    if (!on) {
+        const headless = userAgent.includes('HeadlessChrome');
+        await cdp.send('Emulation.setUserAgentOverride', { userAgent: headless ? userAgent : '' });
+        if (headless)
+            await hideHeadlessUserAgent(cdp, log);
+        return;
+    }
+    const major = /Chrome\/(\d+)/.exec(userAgent)?.[1] ?? '';
+    await cdp.send('Emulation.setUserAgentOverride', {
+        userAgent: mobileUserAgent(userAgent.replace('HeadlessChrome/', 'Chrome/')),
+        platform: 'Android',
+        userAgentMetadata: {
+            brands: [
+                { brand: 'Google Chrome', version: major },
+                { brand: 'Chromium', version: major },
+            ],
+            platform: 'Android',
+            platformVersion: '10.0.0',
+            architecture: '',
+            model: 'K',
+            mobile: true,
+        },
+    });
+}
+/**
+ * A mobile user agent from a desktop one: an Android platform, `Mobile`
+ * before `Safari`, and `Chrome` for `HeadlessChrome`.
+ *
+ * @param desktop - The browser's user agent
+ * @returns Mobile user agent
+ */
+export function mobileUserAgent(desktop) {
+    return desktop
+        .replace(/\([^)]*\)/, '(Linux; Android 10; K)')
+        .replace('HeadlessChrome/', 'Chrome/')
+        .replace(/ (Mobile )?Safari\//, ' Mobile Safari/');
+}
 /**
  * Change the page emulation mid-session (`bdg page emulate`): set the
  * viewport or the color scheme, or clear both (back to the browser window
@@ -58,6 +119,8 @@ export async function emulatePage(cdp, current, change, record) {
     };
     const { viewport: _viewport, colorScheme, ...rest } = state;
     if (change.reset || change.viewport) {
+        const wasPhone = current.viewport?.mobile === true;
+        const isPhone = change.viewport?.mobile === true;
         await step(() => change.viewport
             ? cdp.send('Emulation.setDeviceMetricsOverride', viewportOverride(change.viewport))
             : cdp.send('Emulation.clearDeviceMetricsOverride', {}), {
@@ -65,6 +128,8 @@ export async function emulatePage(cdp, current, change, record) {
             ...(colorScheme && { colorScheme }),
             ...(change.viewport && { viewport: change.viewport }),
         });
+        if (wasPhone !== isPhone)
+            await step(() => emulatePhone(cdp, isPhone), state);
     }
     if (change.reset || change.colorScheme) {
         const { colorScheme: _scheme, ...withoutScheme } = state;

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

@@ -0,0 +1,28 @@
+/**
+ * Which browser built-ins a page replaced (polyfills, old frameworks,
+ * anti-bot scripts). Scripts that must run in the page's own world (actions,
+ * `dom eval` results) depend on them.
+ *
+ * The check does not trust the page: a small page script only collects the
+ * functions (plain property reads and the page's
+ * `Object.getOwnPropertyDescriptor`, itself checked), and whether each is
+ * native comes from the description CDP gives a function, which V8 builds
+ * itself, so a replaced `Function.prototype.toString` or `.call` changes
+ * nothing. A getter or setter counts as the property (a page-defined getter
+ * on `window.getComputedStyle`, a replaced `value` setter); a property that
+ * throws or is gone counts as replaced. An iterator is not checked when the
+ * page replaced `Symbol` (iteration does not use it).
+ */
+import type { CDPSender } from '../../telemetry/objectExpander.js';
+/**
+ * The built-ins of a list that the page replaced.
+ *
+ * @param cdp - CDP connection (or session) of the page
+ * @param names - Dotted paths, e.g. `Element.prototype.matches`,
+ *   `window.getComputedStyle`, `NodeList.prototype[Symbol.iterator]`
+ * @param objectId - An object of the realm to check (e.g. a frame's eval
+ *   result); default: the page's main world
+ * @returns The replaced ones, in list order (empty when the check failed)
+ */
+export declare function findReplacedBuiltins(cdp: CDPSender, names: readonly string[], objectId?: string): Promise<string[]>;
+//# sourceMappingURL=replacedBuiltins.d.ts.map

package/dist/runtime/page/replacedBuiltins.js

@@ -0,0 +1,136 @@
+/**
+ * Which browser built-ins a page replaced (polyfills, old frameworks,
+ * anti-bot scripts). Scripts that must run in the page's own world (actions,
+ * `dom eval` results) depend on them.
+ *
+ * The check does not trust the page: a small page script only collects the
+ * functions (plain property reads and the page's
+ * `Object.getOwnPropertyDescriptor`, itself checked), and whether each is
+ * native comes from the description CDP gives a function, which V8 builds
+ * itself, so a replaced `Function.prototype.toString` or `.call` changes
+ * nothing. A getter or setter counts as the property (a page-defined getter
+ * on `window.getComputedStyle`, a replaced `value` setter); a property that
+ * throws or is gone counts as replaced. An iterator is not checked when the
+ * page replaced `Symbol` (iteration does not use it).
+ */
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+const log = createLogger('dom');
+/** Description V8 gives a native function, e.g. `function querySelector() { [native code] }` */
+const NATIVE_FUNCTION = /\{\s*\[native code\]\s*\}$/;
+/** Suffix naming a prototype's iterator, e.g. `NodeList.prototype[Symbol.iterator]` */
+const ITERATOR_SUFFIX = '[Symbol.iterator]';
+/** Path segment the collector reads as `Symbol.iterator` */
+const ITERATOR_KEY = '@@iterator';
+/** Object group of the collected functions (released after each check) */
+const OBJECT_GROUP = 'bdg-builtins';
+/**
+ * Page-side collector: for each name, the function(s) behind it, as a flat
+ * list of `index, function` pairs (`undefined` for one that throws or is
+ * gone). Uses no array or object helpers of the page.
+ *
+ * @param names - Dotted paths from the global object (a leading `window.` is
+ *   skipped; a trailing `[Symbol.iterator]` names the iterator)
+ * @returns Function declaration
+ */
+function collectorFunction(names) {
+    const paths = names.map((name) => name
+        .replace(/^window\./, '')
+        .replace(ITERATOR_SUFFIX, `.${ITERATOR_KEY}`)
+        .split('.'));
+    return `function () {
+  const paths = ${JSON.stringify(paths)};
+  const describe = Object.getOwnPropertyDescriptor;
+  const found = [];
+  const add = (i, value) => { found[found.length] = i; found[found.length] = value; };
+  for (let i = 0; i < paths.length; i++) {
+    const path = paths[i];
+    let key = path[path.length - 1];
+    let owner = window;
+    try {
+      for (let j = 0; j < path.length - 1; j++) owner = owner[path[j]];
+    } catch (e) { add(i, undefined); continue; }
+    if (key === '${ITERATOR_KEY}') {
+      try { key = Symbol.iterator; } catch (e) { continue; }
+      if (typeof key !== 'symbol') continue;
+    }
+    let own;
+    try { own = describe(owner, key); } catch (e) { own = undefined; }
+    if (own && (own.get || own.set)) {
+      if (own.get) add(i, own.get);
+      if (own.set) add(i, own.set);
+    } else if (own) {
+      add(i, own.value);
+    } else {
+      try { add(i, owner[key]); } catch (e) { continue; }
+    }
+  }
+  return found;
+}`;
+}
+/**
+ * The built-ins of a list that the page replaced.
+ *
+ * @param cdp - CDP connection (or session) of the page
+ * @param names - Dotted paths, e.g. `Element.prototype.matches`,
+ *   `window.getComputedStyle`, `NodeList.prototype[Symbol.iterator]`
+ * @param objectId - An object of the realm to check (e.g. a frame's eval
+ *   result); default: the page's main world
+ * @returns The replaced ones, in list order (empty when the check failed)
+ */
+export async function findReplacedBuiltins(cdp, names, objectId) {
+    const functionDeclaration = collectorFunction(names);
+    try {
+        const collected = (await (objectId
+            ? cdp.send('Runtime.callFunctionOn', {
+                objectId,
+                functionDeclaration,
+                objectGroup: OBJECT_GROUP,
+            })
+            : cdp.send('Runtime.evaluate', {
+                expression: `(${functionDeclaration})()`,
+                objectGroup: OBJECT_GROUP,
+            })));
+        const listId = collected.result.objectId;
+        if (collected.exceptionDetails || !listId)
+            return [];
+        const { result } = (await cdp.send('Runtime.getProperties', {
+            objectId: listId,
+            ownProperties: true,
+        }));
+        return replacedNames(names, result);
+    }
+    catch (error) {
+        log.debug(`Built-ins not checked: ${getErrorMessage(error)}`);
+        return [];
+    }
+    finally {
+        await cdp
+            .send('Runtime.releaseObjectGroup', { objectGroup: OBJECT_GROUP })
+            .catch((error) => log.debug(`Built-ins not released: ${getErrorMessage(error)}`));
+    }
+}
+/**
+ * Names whose collected function is not native.
+ *
+ * @param names - The names checked
+ * @param properties - Properties of the collected `index, function` list
+ * @returns Replaced names, in list order
+ */
+function replacedNames(names, properties) {
+    const entries = new Map();
+    for (const property of properties) {
+        if (/^\d+$/.test(property.name))
+            entries.set(Number(property.name), property.value);
+    }
+    const replaced = new Set();
+    for (let i = 0; entries.has(i); i += 2) {
+        const index = entries.get(i)?.value;
+        const value = entries.get(i + 1);
+        const native = value?.type === 'function' && NATIVE_FUNCTION.test(value.description ?? '');
+        if (typeof index === 'number' && !native)
+            replaced.add(index);
+    }
+    return names.filter((_name, i) => replaced.has(i));
+}
+//# sourceMappingURL=replacedBuiltins.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * The session's user agent in headless Chrome: regular Chrome's string and
+ * client hints, so sites serve the page a user sees.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Send the user agent and client hints of regular Chrome from headless
+ * Chrome: sites serve "HeadlessChrome" a different page (or a bot
+ * challenge), so the page would not be the one a user sees. Not for a
+ * session emulating a phone, whose emulation sets a mobile user agent.
+ *
+ * @param cdp - CDP connection
+ * @param logger - Logger for failures (the session works without it)
+ */
+export declare function hideHeadlessUserAgent(cdp: CDPConnection, logger: Logger): Promise<void>;
+//# sourceMappingURL=userAgent.d.ts.map

package/dist/runtime/page/userAgent.js

@@ -0,0 +1,57 @@
+/**
+ * The session's user agent in headless Chrome: regular Chrome's string and
+ * client hints, so sites serve the page a user sees.
+ */
+import { getErrorMessage } from '../../utils/errors.js';
+/** Reads the client hints Chrome reports, renaming the HeadlessChrome brand */
+const USER_AGENT_METADATA_SCRIPT = `(async () => {
+  const data = navigator.userAgentData;
+  if (!data) return null;
+  const values = await data.getHighEntropyValues(
+    ['architecture', 'bitness', 'model', 'platformVersion', 'fullVersionList', 'wow64']
+  );
+  const rename = (list) => (list || []).map((entry) => ({
+    brand: entry.brand.replace('HeadlessChrome', 'Google Chrome'),
+    version: entry.version,
+  }));
+  return {
+    brands: rename(values.brands),
+    fullVersionList: rename(values.fullVersionList),
+    platform: values.platform,
+    platformVersion: values.platformVersion,
+    architecture: values.architecture,
+    model: values.model,
+    mobile: values.mobile,
+    bitness: values.bitness,
+    wow64: values.wow64,
+  };
+})()`;
+/**
+ * Send the user agent and client hints of regular Chrome from headless
+ * Chrome: sites serve "HeadlessChrome" a different page (or a bot
+ * challenge), so the page would not be the one a user sees. Not for a
+ * session emulating a phone, whose emulation sets a mobile user agent.
+ *
+ * @param cdp - CDP connection
+ * @param logger - Logger for failures (the session works without it)
+ */
+export async function hideHeadlessUserAgent(cdp, logger) {
+    try {
+        const { userAgent } = (await cdp.send('Browser.getVersion'));
+        if (!userAgent.includes('HeadlessChrome'))
+            return;
+        const metadata = (await cdp.send('Runtime.evaluate', {
+            expression: USER_AGENT_METADATA_SCRIPT,
+            awaitPromise: true,
+            returnByValue: true,
+        }));
+        await cdp.send('Emulation.setUserAgentOverride', {
+            userAgent: userAgent.replace('HeadlessChrome', 'Chrome'),
+            ...(metadata.result?.value ? { userAgentMetadata: metadata.result.value } : {}),
+        });
+    }
+    catch (error) {
+        logger.debug(`User agent left as is: ${getErrorMessage(error)}`);
+    }
+}
+//# sourceMappingURL=userAgent.js.map

package/dist/session/QueryCacheManager.d.ts

@@ -71,8 +71,11 @@ export declare class QueryCacheManager {
      * Store a query result.
      *
      * @param result - Query result whose nodes carry backend node ids
+     * @param document - Identity of the page document queried
+     *   ({@link pageDocumentId}): backend node ids are only meaningful in it, and
+     *   a page in a new renderer process reuses them for other elements
      */
-    set(result: DomQueryResult): Promise<void>;
+    set(result: DomQueryResult, document?: string): Promise<void>;
     /**
      * Read the cache and check that it can be used.
      *

package/dist/session/QueryCacheManager.js

@@ -88,11 +88,14 @@ export class QueryCacheManager {
      * Store a query result.
      *
      * @param result - Query result whose nodes carry backend node ids
+     * @param document - Identity of the page document queried
+     *   ({@link pageDocumentId}): backend node ids are only meaningful in it, and
+     *   a page in a new renderer process reuses them for other elements
      */
-    async set(result) {
+    async set(result, document) {
         try {
             const cachePath = this.getCachePath();
-            await writeFile(cachePath, JSON.stringify({ version: CACHE_VERSION, ...result }), 'utf-8');
+            await writeFile(cachePath, JSON.stringify({ version: CACHE_VERSION, ...result, ...(document && { document }) }), 'utf-8');
             log.debug(`Cached ${result.nodes.length} query results to ${cachePath}`);
         }
         catch (error) {

package/dist/session/chrome.d.ts

@@ -41,8 +41,11 @@ export declare function readChromePid(): number | null;
  * Remove Chrome PID from persistent cache.
  *
  * Safe to call multiple times (idempotent).
+ *
+ * @param expectedPid - Remove it only while it still names this Chrome (a
+ *   daemon clearing its own, which another daemon may have replaced)
  */
-export declare function clearChromePid(): void;
+export declare function clearChromePid(expectedPid?: number): void;
 /** What `status --verbose` shows about the session's Chrome */
 export interface RunningChromeInfo {
     /** Executable the process was started from */

package/dist/session/chrome.js

@@ -10,6 +10,7 @@ import { AtomicFileWriter } from '../utils/atomicFile.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { getProcessCommand, isProcessAlive } from '../utils/process.js';
 import { getSessionFilePath, ensureSessionDir } from './paths.js';
+import { readPidFromFile } from './pid.js';
 const log = createLogger('chrome');
 /**
  * Parse Chrome PID from cache file content.
@@ -100,9 +101,14 @@ export function readChromePid() {
  * Remove Chrome PID from persistent cache.
  *
  * Safe to call multiple times (idempotent).
+ *
+ * @param expectedPid - Remove it only while it still names this Chrome (a
+ *   daemon clearing its own, which another daemon may have replaced)
  */
-export function clearChromePid() {
+export function clearChromePid(expectedPid) {
     const cachePath = getSessionFilePath('CHROME_PID');
+    if (expectedPid !== undefined && readPidFromFile(cachePath) !== expectedPid)
+        return;
     try {
         fs.rmSync(cachePath, { force: true });
     }