browser-debugger-cli 0.14.0 → 0.15.0

package/dist/ipc/client.d.ts

@@ -208,8 +208,13 @@ export declare function callCDP(method: string, params?: Record<string, unknown>
 export declare function callBdgScript(method: string, params?: Record<string, unknown>): Promise<ClientResponse<'cdp_call'>>;
 /**
  * Evaluate a JavaScript expression in the active page (or one of its iframes) via the daemon.
+ *
+ * @param script - JavaScript expression
+ * @param frame - Iframe to evaluate in
+ * @param full - `--full`: copy an object or array result with every entry
+ * @returns The daemon's response
  */
-export declare function domEval(script: string, frame?: string): Promise<ClientResponse<'dom_eval'>>;
+export declare function domEval(script: string, frame?: string, full?: boolean): Promise<ClientResponse<'dom_eval'>>;
 /**
  * List the page's iframes via the daemon.
  */

package/dist/ipc/client.js

@@ -292,9 +292,18 @@ export function callBdgScript(method, params) {
 }
 /**
  * Evaluate a JavaScript expression in the active page (or one of its iframes) via the daemon.
+ *
+ * @param script - JavaScript expression
+ * @param frame - Iframe to evaluate in
+ * @param full - `--full`: copy an object or array result with every entry
+ * @returns The daemon's response
  */
-export async function domEval(script, frame) {
-    return sendCommand('dom_eval', { script, ...(frame !== undefined && { frame }) });
+export async function domEval(script, frame, full) {
+    return sendCommand('dom_eval', {
+        script,
+        ...(frame !== undefined && { frame }),
+        ...(full && { full }),
+    });
 }
 /**
  * List the page's iframes via the daemon.

package/dist/ipc/protocol/commands.d.ts

@@ -187,6 +187,8 @@ export interface DomEvalCommand {
     script: string;
     /** Iframe to evaluate in: index, name/id attribute, or URL substring */
     frame?: string;
+    /** `--full`: copy an object or array result with every entry */
+    full?: boolean;
 }
 export interface DomEvalData {
     /** JSON value, or a readable description for values JSON cannot represent */
@@ -195,6 +197,8 @@ export interface DomEvalData {
     type: string;
     /** Object subtype (node, date, array, ...) */
     subtype?: string;
+    /** Elements of an array result in the page (`value` holds at most 1000 unless `full`) */
+    length?: number;
     /** URL of the iframe the script ran in (with `frame`; empty when it has none) */
     frame?: string;
     /** Set when the page replaced built-ins bdg's copy of the result uses */

package/dist/ipc/transport/index.d.ts

@@ -18,6 +18,12 @@ type WithTypeAndSession = {
  * @param timeoutMs - How long to wait for the response (default: IPC timeout)
  * @param socketPath - Daemon socket (default: the selected session's)
  * @returns The daemon's response
+ * @throws CommandError (103) before connecting when the socket's session
+ *   directory cannot be trusted (see {@link secureSessionDir}): a socket
+ *   planted there by another user would receive the request. The check runs
+ *   just before connecting, by path; replacing the socket in that window
+ *   needs write access to a directory of the chain, which the check has
+ *   just found only the user has
  */
 export declare function sendRequest<TRequest extends WithTypeAndSession, TResponse extends WithTypeAndSession>(request: TRequest, requestName: string, expectedType?: string, timeoutMs?: number, socketPath?: string): Promise<TResponse>;
 //# sourceMappingURL=index.d.ts.map

package/dist/ipc/transport/index.js

@@ -3,9 +3,13 @@
  *
  * Handles Unix domain socket communication with JSONL protocol.
  */
+import * as path from 'path';
 import { getIPCRequestTimeout } from '../../constants.js';
-import { getDaemonSocketPath } from '../../session/paths.js';
+import { CommandError } from '../../errors/index.js';
+import { untrustedSessionDirError } from '../../errors/messages.js';
+import { getDaemonSocketPath, secureSessionDir } from '../../session/paths.js';
 import { createLogger } from '../../ui/logging/index.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { formatConnectionError, formatEarlyCloseError, formatParseError, formatTimeoutError, } from './errors.js';
 import { JSONLBuffer, parseJSONLFrame, toJSONLFrame } from './jsonl.js';
 import { createSocket } from './socket.js';
@@ -22,8 +26,19 @@ const log = createLogger('client');
  * @param timeoutMs - How long to wait for the response (default: IPC timeout)
  * @param socketPath - Daemon socket (default: the selected session's)
  * @returns The daemon's response
+ * @throws CommandError (103) before connecting when the socket's session
+ *   directory cannot be trusted (see {@link secureSessionDir}): a socket
+ *   planted there by another user would receive the request. The check runs
+ *   just before connecting, by path; replacing the socket in that window
+ *   needs write access to a directory of the chain, which the check has
+ *   just found only the user has
  */
 export async function sendRequest(request, requestName, expectedType, timeoutMs = getIPCRequestTimeout(), socketPath = getDaemonSocketPath()) {
+    const untrusted = secureSessionDir(path.dirname(socketPath));
+    if (untrusted) {
+        const err = untrustedSessionDirError(untrusted);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SESSION_FILE_ERROR);
+    }
     return new Promise((resolve, reject) => {
         const buffer = new JSONLBuffer();
         let resolved = false;

package/dist/runtime/dom/elementInfo.d.ts

@@ -70,6 +70,13 @@ export declare const FLAT_TEXT_JS = "(el, limit, fields) => {\n  const composed
 export declare const ELEMENT_TEXT_JS = "(el, full) => {\n  const withoutDecorations = (el, text) => {\n  if (!text || typeof el.querySelectorAll !== 'function') return text;\n  const glyph = /^\\s*[\u00D7\u2715\u2716\u2717\u2A2F]\\s*$/;\n  const textOf = (node) => (typeof node.innerText === 'string' ? node.innerText : node.textContent || '').trim();\n  const closer = '.close, [aria-label=\"close\" i], [aria-label=\"dismiss\" i]';\n  const rendered = (node) => !node.checkVisibility || node.checkVisibility();\n  const found = Array.from(el.querySelectorAll(closer + ', [aria-hidden=\"true\"]'))\n    .filter((node) => rendered(node) && (node.matches(closer) || !/[\\p{L}\\p{N}]/u.test(textOf(node))));\n  if (/[\u00D7\u2715\u2716\u2717\u2A2F]/.test(text)) {\n    found.push(...Array.from(el.querySelectorAll('button, a, [role=\"button\"]')).filter((node) => glyph.test(node.textContent || '')));\n  }\n  const unique = Array.from(new Set(found));\n  const outermost = unique.filter((node) => !unique.some((other) => other !== node && other.contains(node)));\n  let result = text;\n  for (const node of outermost) {\n    const part = textOf(node);\n    const at = part ? result.lastIndexOf(part) : -1;\n    if (at >= 0) result = result.slice(0, at) + result.slice(at + part.length);\n  }\n  return result;\n};\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit, fields) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea)$/.test(node.localName)) return;\n    if (!fields && (node.localName === 'select' || node.isContentEditable)) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const all = el.textContent || '';\n  if (el.tagName === 'OPTION') return el.label;\n  if (typeof el.innerText !== 'string') return full ? all : all.slice(0, 2000);\n  const rendered = (node) => !node.checkVisibility || node.checkVisibility();\n  const shown = rendered(el);\n  const boxless = !shown && el.ownerDocument.defaultView.getComputedStyle(el).display === 'contents';\n  if (!shown && !boxless) return '';\n  if (composed(el)) return withoutDecorations(el, flatText(el, full ? Infinity : 2000));\n  if (boxless) return withoutDecorations(el, full ? all : all.slice(0, 2000));\n  if (full || all.length <= 2000) return withoutDecorations(el, el.innerText);\n  const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_TEXT);\n  let start = '';\n  while (start.length < 1000 && walker.nextNode()) {\n    const parent = walker.currentNode.parentElement;\n    if (!parent || rendered(parent)) start += walker.currentNode.data;\n  }\n  return withoutDecorations(el, start);\n}";
 /** Shown instead of a secret field value (the same for every length) */
 export declare const MASKED_VALUE = "\u2022\u2022\u2022\u2022";
+/**
+ * Regular expression source (case-insensitive) matching names of fields that
+ * hold a password, one-time code or card code: `password`, `passwd`, `pwd`,
+ * `passcode`, `otp`, `cvv`, `cvc`. Shared by the page-side
+ * {@link SENSITIVE_FIELD_JS} and HAR sanitization.
+ */
+export declare const SENSITIVE_NAME_SOURCE = "passw|passwd|pwd|passcode|(^|[^a-z])otp([^a-z]|$)|cvv|cvc";
 /**
  * Page-side check whether a form control holds a secret whose value must
  * never leave the page: a password field (live type or type attribute), a

package/dist/runtime/dom/elementInfo.js

@@ -157,6 +157,13 @@ export const ELEMENT_TEXT_JS = `(el, full) => {
 }`;
 /** Shown instead of a secret field value (the same for every length) */
 export const MASKED_VALUE = '••••';
+/**
+ * Regular expression source (case-insensitive) matching names of fields that
+ * hold a password, one-time code or card code: `password`, `passwd`, `pwd`,
+ * `passcode`, `otp`, `cvv`, `cvc`. Shared by the page-side
+ * {@link SENSITIVE_FIELD_JS} and HAR sanitization.
+ */
+export const SENSITIVE_NAME_SOURCE = 'passw|passwd|pwd|passcode|(^|[^a-z])otp([^a-z]|$)|cvv|cvc';
 /**
  * Page-side check whether a form control holds a secret whose value must
  * never leave the page: a password field (live type or type attribute), a
@@ -171,7 +178,7 @@ export const SENSITIVE_FIELD_JS = `(el) => {
   if (/(^|\\s)(cc-[a-z-]+|one-time-code|current-password|new-password)(\\s|$)/i.test(autocomplete)) return true;
   if (el.type === 'password' || /^password$/i.test(el.getAttribute('type') || '')) return true;
   const names = [el.getAttribute('name'), el.id, autocomplete].join(' ');
-  if (/passw|passwd|pwd|passcode|(^|[^a-z])otp([^a-z]|$)|cvv|cvc/i.test(names)) return true;
+  if (/${SENSITIVE_NAME_SOURCE}/i.test(names)) return true;
   try {
     const security = el.ownerDocument.defaultView.getComputedStyle(el).getPropertyValue('-webkit-text-security');
     return Boolean(security) && security !== 'none';

package/dist/runtime/dom/evalHelpers.d.ts

@@ -26,6 +26,8 @@ export interface EvalResult {
     type: string;
     /** Object subtype (`node`, `date`, `map`, `array`, ...) */
     subtype?: string;
+    /** Elements of an array result in the page (its copy holds at most 1000 unless `full`) */
+    length?: number;
     /** Set when the page replaced built-ins bdg's copy of the result uses, so the browser copied it */
     warning?: string;
 }
@@ -36,11 +38,27 @@ export interface EvalResult {
  * dates ISO strings, maps and sets entries, errors their message, BigInts
  * `12n`, functions `function name()`, and cycles `[Circular]` (an object
  * shared by two properties is copied twice). Works for objects of iframes
- * (other realms); lists and objects are cut after 1000 entries, and a
- * throwing getter becomes `[Error: …]`. It uses the page's built-ins
- * ({@link COPY_BUILTINS}), so it only runs when the page left them alone.
+ * (other realms); lists and objects are cut after 1000 entries and levels
+ * below the 20th become `[…]` (with `full`: no entries are cut, levels
+ * below the 100th), and a throwing getter becomes `[Error: …]`. It uses the
+ * page's built-ins ({@link COPY_BUILTINS}), so it only runs when the page
+ * left them alone.
+ *
+ * @param full - `--full`: copy every entry
+ * @returns Function declaration for Runtime.callFunctionOn
+ */
+export declare function jsonSafeCopyFunction(full?: boolean): string;
+/**
+ * Elements of an array result (also a node list or typed array), read from
+ * its description (`Array(20000)`, `NodeList(5)`), since its copy holds
+ * at most 1000 unless `--full`.
+ *
+ * @param remote - Remote object returned by Runtime.evaluate
+ * @returns `length`, when the result is an array
  */
-export declare const JSON_SAFE_COPY_FUNCTION = "function () {\n  const MAX_ITEMS = 1000;\n  const ancestors = new Set();\n  const kind = (value) => Object.prototype.toString.call(value).slice(8, -1);\n  const isNode = (value) => typeof value.nodeType === 'number' && typeof value.nodeName === 'string';\n  const describeNode = (node) => {\n    if (node.nodeType !== 1) return node.nodeName.toLowerCase();\n    return node.tagName.toLowerCase() + (node.id ? '#' + node.id : '') +\n      (node.classList && node.classList.length ? '.' + Array.from(node.classList).join('.') : '');\n  };\n  const items = (list, next) => {\n    const result = [];\n    if (typeof list.length === 'number') {\n      for (let i = 0; i < list.length; i++) {\n        if (i === MAX_ITEMS) { result.push('\u2026'); break; }\n        result.push(next(list[i]));\n      }\n      return result;\n    }\n    let count = 0;\n    for (const item of list) {\n      if (count++ === MAX_ITEMS) { result.push('\u2026'); break; }\n      result.push(next(item));\n    }\n    return result;\n  };\n  const leaf = (value) => {\n    if (value === undefined) return null;\n    if (typeof value === 'number') {\n      if (Number.isNaN(value) || !Number.isFinite(value)) return String(value);\n      return Object.is(value, -0) ? '-0' : value;\n    }\n    if (typeof value === 'bigint') return value + 'n';\n    if (typeof value === 'symbol') return value.toString();\n    if (typeof value === 'function') return 'function ' + (value.name || '(anonymous)') + '()';\n    return value;\n  };\n  const copy = (value, depth) => {\n    if (value === null || typeof value !== 'object') return leaf(value);\n    if (ancestors.has(value)) return '[Circular]';\n    if (depth > 20) return '[\u2026]';\n    const next = (item) => copy(item, depth + 1);\n    const type = kind(value);\n    if (isNode(value)) return describeNode(value);\n    if (value.window === value) return 'Window';\n    if (type === 'Date') return isNaN(value) ? 'Invalid Date' : value.toISOString();\n    if (type === 'RegExp') return String(value);\n    if (type === 'Error' || value instanceof Error) return value.name + ': ' + value.message;\n    ancestors.add(value);\n    try {\n      if (type === 'Map') return items(value, ([k, v]) => [next(k), next(v)]);\n      if (type === 'Set' || type === 'NodeList' || type === 'HTMLCollection') return items(value, next);\n      if (ArrayBuffer.isView(value) && type !== 'DataView') return items(value, next);\n      if (Array.isArray(value)) return items(value, next);\n      const result = {};\n      const keys = Object.keys(value);\n      for (const key of keys.slice(0, MAX_ITEMS)) {\n        try { result[key] = next(value[key]); } catch (e) { result[key] = '[Error: ' + (e && e.message) + ']'; }\n      }\n      if (keys.length > MAX_ITEMS) result['\u2026'] = (keys.length - MAX_ITEMS) + ' more keys';\n      return result;\n    } finally {\n      ancestors.delete(value);\n    }\n  };\n  return copy(this, 0);\n}";
+export declare function arrayLength(remote: Protocol.Runtime.RemoteObject): {
+    length?: number;
+};
 /** What a busy target is called in messages: the page, or an iframe (`--frame`) */
 export type BusyScope = 'page' | 'frame';
 /** When {@link withBusyPageRecovery} checks the target, and what it calls it */
@@ -100,6 +118,8 @@ export interface EvalTarget {
     recovery?: CDPSender;
     /** Execution context of a frame (`ExecutionContextDescription.uniqueId`) */
     uniqueContextId?: string;
+    /** `--full`: copy the result with every entry */
+    full?: boolean;
 }
 /**
  * Whether the page still answers. A page that does not answer in time is

package/dist/runtime/dom/evalHelpers.js

@@ -156,6 +156,10 @@ const DESCRIBED_SUBTYPES = new Set([
     'iterator',
     'generator',
 ]);
+/** Entries per list or object, and levels, of a copied eval result */
+const COPY_LIMITS = { maxItems: 1000, maxDepth: 20 };
+/** Limits of a copied eval result with `--full`: every entry, levels deep enough for real data */
+const FULL_COPY_LIMITS = { maxItems: Infinity, maxDepth: 100 };
 /** Object subtypes shown by their short description (`button#submit`, `ArrayBuffer(8)`). */
 const BRIEF_SUBTYPES = new Set(['node', 'arraybuffer', 'dataview']);
 /**
@@ -165,12 +169,19 @@ const BRIEF_SUBTYPES = new Set(['node', 'arraybuffer', 'dataview']);
  * dates ISO strings, maps and sets entries, errors their message, BigInts
  * `12n`, functions `function name()`, and cycles `[Circular]` (an object
  * shared by two properties is copied twice). Works for objects of iframes
- * (other realms); lists and objects are cut after 1000 entries, and a
- * throwing getter becomes `[Error: …]`. It uses the page's built-ins
- * ({@link COPY_BUILTINS}), so it only runs when the page left them alone.
+ * (other realms); lists and objects are cut after 1000 entries and levels
+ * below the 20th become `[…]` (with `full`: no entries are cut, levels
+ * below the 100th), and a throwing getter becomes `[Error: …]`. It uses the
+ * page's built-ins ({@link COPY_BUILTINS}), so it only runs when the page
+ * left them alone.
+ *
+ * @param full - `--full`: copy every entry
+ * @returns Function declaration for Runtime.callFunctionOn
  */
-export const JSON_SAFE_COPY_FUNCTION = `function () {
-  const MAX_ITEMS = 1000;
+export function jsonSafeCopyFunction(full = false) {
+    const limits = full ? FULL_COPY_LIMITS : COPY_LIMITS;
+    return `function () {
+  const MAX_ITEMS = ${limits.maxItems};
   const ancestors = new Set();
   const kind = (value) => Object.prototype.toString.call(value).slice(8, -1);
   const isNode = (value) => typeof value.nodeType === 'number' && typeof value.nodeName === 'string';
@@ -209,7 +220,7 @@ export const JSON_SAFE_COPY_FUNCTION = `function () {
   const copy = (value, depth) => {
     if (value === null || typeof value !== 'object') return leaf(value);
     if (ancestors.has(value)) return '[Circular]';
-    if (depth > 20) return '[…]';
+    if (depth > ${limits.maxDepth}) return '[…]';
     const next = (item) => copy(item, depth + 1);
     const type = kind(value);
     if (isNode(value)) return describeNode(value);
@@ -236,6 +247,7 @@ export const JSON_SAFE_COPY_FUNCTION = `function () {
   };
   return copy(this, 0);
 }`;
+}
 /** Built-ins {@link JSON_SAFE_COPY_FUNCTION} uses (it runs in the page's world, next to the result) */
 const COPY_BUILTINS = [
     'Object.keys',
@@ -284,9 +296,10 @@ function isTerminated(details) {
  *
  * @param cdp - CDP connection
  * @param remote - Remote object returned by Runtime.evaluate
+ * @param full - `--full`: copy every entry ({@link jsonSafeCopyFunction})
  * @returns Value and type
  */
-async function toEvalResult(cdp, remote) {
+async function toEvalResult(cdp, remote, full) {
     const kind = { type: remote.type, ...(remote.subtype && { subtype: remote.subtype }) };
     if (remote.unserializableValue !== undefined)
         return { value: remote.unserializableValue, ...kind };
@@ -301,12 +314,27 @@ async function toEvalResult(cdp, remote) {
         return { value: formatRemoteObject(remote), ...kind };
     }
     const replaced = await findReplacedBuiltins(cdp, COPY_BUILTINS, remote.objectId);
-    const copy = await copyByValue(cdp, remote.objectId, replaced.length === 0 ? JSON_SAFE_COPY_FUNCTION : SELF_FUNCTION);
+    const copy = await copyByValue(cdp, remote.objectId, replaced.length === 0 ? jsonSafeCopyFunction(full) : SELF_FUNCTION);
     const value = copy ? copy.value : formatRemoteObject(remote);
+    const copied = { value, ...kind, ...arrayLength(remote) };
     if (replaced.length === 0)
-        return { value, ...kind };
+        return copied;
     const warning = copy ? evalCopiedByBrowserWarning(replaced) : evalPreviewWarning(replaced);
-    return { value, ...kind, warning };
+    return { ...copied, warning };
+}
+/**
+ * Elements of an array result (also a node list or typed array), read from
+ * its description (`Array(20000)`, `NodeList(5)`), since its copy holds
+ * at most 1000 unless `--full`.
+ *
+ * @param remote - Remote object returned by Runtime.evaluate
+ * @returns `length`, when the result is an array
+ */
+export function arrayLength(remote) {
+    if (remote.subtype !== 'array' && remote.subtype !== 'typedarray')
+        return {};
+    const match = /\((\d+)\)$/.exec(remote.description ?? '');
+    return match ? { length: Number(match[1]) } : {};
 }
 /**
  * Copy a result by value: what a function called on it returns, which the
@@ -314,7 +342,7 @@ async function toEvalResult(cdp, remote) {
  *
  * @param cdp - CDP connection
  * @param objectId - The result
- * @param functionDeclaration - {@link JSON_SAFE_COPY_FUNCTION}, or
+ * @param functionDeclaration - {@link jsonSafeCopyFunction}'s, or
  *   {@link SELF_FUNCTION} for the browser's plain copy (it fails on cycles
  *   and BigInts)
  * @returns The copy, or undefined when it failed
@@ -560,7 +588,7 @@ export async function evaluateScript(cdp, script, target = {}) {
     try {
         const response = await withDeadline(executeScript(session, script, evaluateOptions(target)), EVAL_TIMEOUT_MS + TERMINATION_GRACE_MS, () => evaluationTimeoutError(target.recovery ?? session, scope));
         const settled = await withDeadline(settlePromise(session, response.result, script), EVAL_TIMEOUT_MS, promiseTimeout);
-        return await toEvalResult(session, settled);
+        return await toEvalResult(session, settled, target.full ?? false);
     }
     catch (error) {
         throw scope === 'page' && isContextLostError(error)

package/dist/runtime/dom/frames.d.ts

@@ -84,11 +84,12 @@ export declare function frameContextLostError(conn: Pick<CDPConnection, 'send'>,
  * @param script - JavaScript expression
  * @param query - Requested frame (index, name/id attribute, or part of the name, id or URL)
  * @param listedIds - Frame id behind each index of the last `dom frames` listing, if any
+ * @param full - `--full`: copy the result with every entry
  * @returns Value, type and the frame's URL
  * @throws CommandError (81/83) when the frame is ambiguous or missing, (87)
  *   when an index names another frame than when it was listed, (83) when it
  *   navigated or was removed while the script ran, else as evaluateScript
  */
-export declare function evaluateInFrame(page: CDPConnection, wsUrl: string, script: string, query: string, listedIds?: string[]): Promise<DomEvalData>;
+export declare function evaluateInFrame(page: CDPConnection, wsUrl: string, script: string, query: string, listedIds?: string[], full?: boolean): Promise<DomEvalData>;
 export {};
 //# sourceMappingURL=frames.d.ts.map

package/dist/runtime/dom/frames.js

@@ -529,12 +529,13 @@ export async function frameContextLostError(conn, page, frame) {
  * @param script - JavaScript expression
  * @param query - Requested frame (index, name/id attribute, or part of the name, id or URL)
  * @param listedIds - Frame id behind each index of the last `dom frames` listing, if any
+ * @param full - `--full`: copy the result with every entry
  * @returns Value, type and the frame's URL
  * @throws CommandError (81/83) when the frame is ambiguous or missing, (87)
  *   when an index names another frame than when it was listed, (83) when it
  *   navigated or was removed while the script ran, else as evaluateScript
  */
-export async function evaluateInFrame(page, wsUrl, script, query, listedIds) {
+export async function evaluateInFrame(page, wsUrl, script, query, listedIds, full = false) {
     return withFrameConnection(page, wsUrl, async (fc) => {
         const { frame, uniqueContextId } = await resolveFrame(fc, query, listedIds);
         try {
@@ -542,6 +543,7 @@ export async function evaluateInFrame(page, wsUrl, script, query, listedIds) {
                 ...(frame.sessionId && { sessionId: frame.sessionId }),
                 uniqueContextId,
                 recovery: recoverySender(fc, frame.sessionId),
+                full,
             });
             return { ...result, frame: frame.info.url };
         }

package/dist/runtime/page/emulation.js

@@ -60,12 +60,13 @@ export async function applySessionEmulation(cdp, emulation) {
  */
 async function emulatePhone(cdp, on) {
     await cdp.send('Emulation.setTouchEmulationEnabled', { enabled: on, maxTouchPoints: on ? 5 : 1 });
-    const { userAgent } = (await cdp.send('Browser.getVersion', {}));
+    const version = (await cdp.send('Browser.getVersion', {}));
+    const { userAgent } = version;
     if (!on) {
-        const headless = userAgent.includes('HeadlessChrome');
-        await cdp.send('Emulation.setUserAgentOverride', { userAgent: headless ? userAgent : '' });
-        if (headless)
-            await hideHeadlessUserAgent(cdp, log);
+        if (userAgent.includes('HeadlessChrome'))
+            await hideHeadlessUserAgent(cdp, log, version);
+        else
+            await cdp.send('Emulation.setUserAgentOverride', { userAgent: '' });
         return;
     }
     const major = /Chrome\/(\d+)/.exec(userAgent)?.[1] ?? '';

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

@@ -3,15 +3,99 @@
  * 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';
+import { type Logger } from '../../ui/logging/index.js';
+/** A brand in the client hints (`Sec-CH-UA`, `navigator.userAgentData.brands`) */
+export interface BrandVersion {
+    brand: string;
+    version: string;
+}
+/** CDP `Emulation.UserAgentMetadata`: the client hints Chrome sends and reports */
+export interface UserAgentMetadata {
+    brands: BrandVersion[];
+    fullVersionList: BrandVersion[];
+    fullVersion: string;
+    platform: string;
+    platformVersion: string;
+    architecture: string;
+    bitness: string;
+    model: string;
+    mobile: boolean;
+    wow64: boolean;
+    formFactors: string[];
+}
+/** The machine the daemon runs on, as client hints name it */
+export interface HostPlatform {
+    /** Client-hint platform (`macOS`, `Windows`, `Linux`) */
+    platform: string;
+    /** OS version as Chrome reports it */
+    platformVersion: string;
+    /** `arm` or `x86` */
+    architecture: string;
+    /** `64` or `32` */
+    bitness: string;
+}
+/** `Browser.getVersion` fields the metadata is built from */
+export interface BrowserVersion {
+    product: string;
+    userAgent: string;
+}
+/**
+ * Chrome's brand list for a version, built the way Chrome builds it
+ * (`GenerateBrandVersionList` in Chromium's `user_agent_utils.cc`): a
+ * made-up brand, Chromium and the browser's brand, in an order and with a
+ * made-up name and version that depend on the major version.
+ *
+ * @param major - Major version (the seed)
+ * @param chromium - Chromium version to list
+ * @param browser - Browser brand and version
+ * @param greaseSuffix - Appended to the made-up version (`.0.0.0` in full versions)
+ * @returns Brand list
+ */
+export declare function chromeBrandList(major: number, chromium: string, browser: BrandVersion, greaseSuffix?: string): BrandVersion[];
+/**
+ * The client hints regular Chrome sends, for the browser `Browser.getVersion`
+ * describes. The browser brand is Microsoft Edge when the user agent says
+ * `Edg/`, Google Chrome otherwise (Chromium and Chrome for Testing look the
+ * same over CDP). Edge's Chromium version is only known to the major
+ * version. The OS version, architecture and bitness are the host's when it
+ * runs the platform the user agent names, empty otherwise (a remote Chrome).
+ *
+ * @param version - `Browser.getVersion` product and user agent
+ * @param host - The daemon's machine
+ * @returns Metadata for `Emulation.setUserAgentOverride`
+ */
+export declare function regularChromeMetadata(version: BrowserVersion, host: HostPlatform): UserAgentMetadata;
+/**
+ * The OS version Chrome reports on Linux or Windows, from `os.release()`:
+ * the kernel version's first three numbers on Linux, and on Windows `13.0.0`
+ * for Windows 11 and `10.0.0` before it (Chrome reports a Windows API
+ * version there, not the OS build).
+ *
+ * @param platform - `process.platform`
+ * @param release - `os.release()`
+ * @returns OS version, or empty when unknown
+ */
+export declare function releasePlatformVersion(platform: string, release: string): string;
+/**
+ * The daemon's machine as client hints describe it.
+ *
+ * @returns Platform, OS version, architecture and bitness
+ */
+export declare function hostPlatform(): HostPlatform;
 /**
  * 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.
  *
+ * The client hints are built from `Browser.getVersion` and the host
+ * ({@link regularChromeMetadata}) rather than read from the page: the page is
+ * still `about:blank`, which has no `navigator.userAgentData`, and an
+ * override without metadata empties the client hints.
+ *
  * @param cdp - CDP connection
  * @param logger - Logger for failures (the session works without it)
+ * @param known - `Browser.getVersion` result, when the caller has it
  */
-export declare function hideHeadlessUserAgent(cdp: CDPConnection, logger: Logger): Promise<void>;
+export declare function hideHeadlessUserAgent(cdp: CDPConnection, logger: Logger, known?: BrowserVersion): Promise<void>;
 //# sourceMappingURL=userAgent.d.ts.map