browser-debugger-cli 0.8.0 → 0.10.0

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

@@ -0,0 +1,103 @@
+/**
+ * Page-side descriptions of elements for DOM command output (`dom query`,
+ * `dom layout`, DOM context of console messages): their text as a user sees
+ * it and where they live (iframes, shadow roots).
+ */
+/** Length of the text `dom get` shows for an element. */
+export declare const ELEMENT_TEXT_LENGTH = 500;
+/**
+ * Page-side removal of decorations from an element's text: close buttons
+ * (`.close`, `aria-label="Close"` or `"Dismiss"`, a button or link showing
+ * just `×`) and `aria-hidden` icons (text without letters or digits), so a
+ * flash message does not end in "×". `aria-hidden` text with words is kept:
+ * it is often the visible twin of a screen-reader text. Each decoration's
+ * text is removed once, from the end.
+ */
+export declare const WITHOUT_DECORATIONS_JS = "(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}";
+/**
+ * Page-side text of an element as a user sees it: `innerText` for a rendered
+ * element (CSS-hidden parts left out, inline elements not split apart), none
+ * for an element that is not rendered, `textContent` for SVG and other
+ * elements without `innerText` and for `display: contents` wrappers (no box
+ * of their own, but their children are shown), and the label of an
+ * `<option>` (which its `<select>` renders). For large containers (more
+ * than 2000 characters of text) only the start is read, from the text nodes
+ * whose parent is rendered, so a preview never lays out a whole page's text,
+ * unless `full` is set. Decorations are left out ({@link WITHOUT_DECORATIONS_JS}).
+ */
+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 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  if (!rendered(el)) {\n    const boxless = el.ownerDocument.defaultView.getComputedStyle(el).display === 'contents';\n    return boxless ? withoutDecorations(el, full ? all : all.slice(0, 2000)) : '';\n  }\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";
+/**
+ * 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
+ * field shown masked by CSS (`-webkit-text-security` other than `none`),
+ * one whose `autocomplete` names a password, a payment card (`cc-*`) or a
+ * one-time code, or a field named like a password, one-time code or card code
+ * (`password`, `passwd`, `pwd`, `passcode`, `otp`, `cvv`, `cvc`), which
+ * covers a password field switched to text by a "show password" button.
+ */
+export declare const SENSITIVE_FIELD_JS = "(el) => {\n  const autocomplete = el.getAttribute('autocomplete') || '';\n  if (/(^|\\s)(cc-[a-z-]+|one-time-code|current-password|new-password)(\\s|$)/i.test(autocomplete)) return true;\n  if (el.type === 'password' || /^password$/i.test(el.getAttribute('type') || '')) return true;\n  const names = [el.getAttribute('name'), el.id, autocomplete].join(' ');\n  if (/passw|passwd|pwd|passcode|(^|[^a-z])otp([^a-z]|$)|cvv|cvc/i.test(names)) return true;\n  try {\n    const security = el.ownerDocument.defaultView.getComputedStyle(el).getPropertyValue('-webkit-text-security');\n    return Boolean(security) && security !== 'none';\n  } catch (e) {\n    return false;\n  }\n}";
+/**
+ * Page-side live state of a form control, which its attributes do not show:
+ * the type and current value of an `<input>` (for checkboxes and radios
+ * `checked` and their `value` attribute, not the default "on"), the value of
+ * a `<textarea>`, the labels of a `<select>`'s selected options and the type
+ * of a `<button>` in a form (`submit` when it has none; outside a form only
+ * a type attribute is shown). Empty for other elements.
+ *
+ * Secrets never leave the page: a hidden input's value is left out, and the
+ * value (or selected option) of a sensitive field ({@link SENSITIVE_FIELD_JS})
+ * is replaced by {@link MASKED_VALUE}, whatever its length, with
+ * `sensitive: true`.
+ */
+export declare const ELEMENT_STATE_JS = "(el) => {\n  const isSensitive = (el) => {\n  const autocomplete = el.getAttribute('autocomplete') || '';\n  if (/(^|\\s)(cc-[a-z-]+|one-time-code|current-password|new-password)(\\s|$)/i.test(autocomplete)) return true;\n  if (el.type === 'password' || /^password$/i.test(el.getAttribute('type') || '')) return true;\n  const names = [el.getAttribute('name'), el.id, autocomplete].join(' ');\n  if (/passw|passwd|pwd|passcode|(^|[^a-z])otp([^a-z]|$)|cvv|cvc/i.test(names)) return true;\n  try {\n    const security = el.ownerDocument.defaultView.getComputedStyle(el).getPropertyValue('-webkit-text-security');\n    return Boolean(security) && security !== 'none';\n  } catch (e) {\n    return false;\n  }\n};\n  const mask = (value) => (value ? '\u2022\u2022\u2022\u2022' : '');\n  const guarded = (state) => {\n    if (!isSensitive(el)) return state;\n    const result = { ...state, sensitive: true };\n    if ('value' in result) result.value = mask(result.value);\n    if ('selected' in result) result.selected = mask(result.selected);\n    return result;\n  };\n  switch (el.localName) {\n    case 'input':\n      if (el.type === 'hidden') return { type: 'hidden' };\n      return guarded(\n        /^(checkbox|radio)$/.test(el.type)\n          ? { type: el.type, checked: el.checked, value: el.getAttribute('value') || '' }\n          : { type: el.type, value: el.value }\n      );\n    case 'textarea':\n      return guarded({ value: el.value });\n    case 'select':\n      return guarded({ selected: Array.from(el.selectedOptions || [], (option) => option.label).join(', ') });\n    case 'button':\n      return el.form ? { type: el.type } : {};\n    default:\n      return {};\n  }\n}";
+/**
+ * Page-side short description of an element: tag, id and up to two classes,
+ * e.g. `button#save.primary.large`.
+ */
+export declare const ELEMENT_DESCRIPTION_JS = "(node) => node.tagName.toLowerCase() +\n  (node.id ? '#' + node.id : '') +\n  (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : '')";
+/**
+ * Page-side position of an element among its parent's children with the
+ * same short description ({@link ELEMENT_DESCRIPTION_JS}), e.g. `(2nd of 3)`;
+ * empty when it is the only one.
+ */
+export declare const SIBLING_POSITION_JS = "(el) => {\n  const describe = (node) => node.tagName.toLowerCase() +\n  (node.id ? '#' + node.id : '') +\n  (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : '');\n  const parent = el.parentElement;\n  if (!parent) return '';\n  const own = describe(el);\n  const same = Array.from(parent.children).filter((child) => describe(child) === own);\n  if (same.length < 2) return '';\n  const n = same.indexOf(el) + 1;\n  const teen = n % 100 >= 11 && n % 100 <= 13;\n  const suffix = teen ? 'th' : ({ 1: 'st', 2: 'nd', 3: 'rd' })[n % 10] || 'th';\n  return '(' + n + suffix + ' of ' + same.length + ')';\n}";
+/**
+ * Page-side identity of an element an action hit, so the output says which
+ * one it was, as one string: its short description
+ * ({@link ELEMENT_DESCRIPTION_JS}) and visible text (button value for button
+ * inputs, decorations left out), e.g. `button#add.btn "Add to cart"`. A
+ * `<select>` is named by its label, aria-label or name, else by its selected
+ * option, e.g. `select.sort "Sort products"`. An element without visible
+ * text is described by itself first: by its position among same-looking
+ * siblings ({@link SIBLING_POSITION_JS}), e.g. `div.figure (2nd of 3)`, with
+ * its aria-label, placeholder or title when it has one. Only an element
+ * without an id that is the only one of its kind is named by the nearest of
+ * three ancestors that has text, e.g.
+ * `input.toggle in div.view "Write report"` (rows of a list share their
+ * aria-label), leaving out the options
+ * of `<select>`s in it (read like `innerText`: CSS-hidden text is left out of
+ * a rendered ancestor; at most 500 text nodes; selects in shadow roots are
+ * not looked into), and never past an editable ancestor, whose text may be
+ * typed input; otherwise its aria-label, placeholder or title is used. Texts
+ * are cut at 40 characters. Contenteditable elements count as controls: what
+ * was typed into them is never echoed (nor their ancestors' text).
+ */
+export declare const ELEMENT_IDENTITY_JS = "(el) => {\n  const describe = (node) => node.tagName.toLowerCase() +\n  (node.id ? '#' + node.id : '') +\n  (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : '');\n  const siblingPosition = (el) => {\n  const describe = (node) => node.tagName.toLowerCase() +\n  (node.id ? '#' + node.id : '') +\n  (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : '');\n  const parent = el.parentElement;\n  if (!parent) return '';\n  const own = describe(el);\n  const same = Array.from(parent.children).filter((child) => describe(child) === own);\n  if (same.length < 2) return '';\n  const n = same.indexOf(el) + 1;\n  const teen = n % 100 >= 11 && n % 100 <= 13;\n  const suffix = teen ? 'th' : ({ 1: 'st', 2: 'nd', 3: 'rd' })[n % 10] || 'th';\n  return '(' + n + suffix + ' of ' + same.length + ')';\n};\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 clean = (text) => (text || '').replace(/\\s+/g, ' ').trim();\n  const cut = (text) => {\n    const characters = Array.from(text);\n    return characters.length > 40 ? characters.slice(0, 40).join('') + '\u2026' : text;\n  };\n  const isControl = (node) => /^(input|select|textarea)$/.test(node.localName) || node.isContentEditable;\n  const shownText = (node) =>\n    isControl(node) ? '' : clean(withoutDecorations(node, typeof node.innerText === 'string' ? node.innerText : node.textContent));\n  const buttonValue = (node) => (node.localName === 'input' && /^(submit|button|reset)$/i.test(node.type) ? clean(node.value) : '');\n  const attributeText = (node) =>\n    clean(node.getAttribute('aria-label')) || clean(node.getAttribute('placeholder')) || clean(node.getAttribute('title'));\n  const selectName = (node) =>\n    clean(node.labels && node.labels[0] && node.labels[0].innerText) ||\n    clean(node.getAttribute('aria-label')) ||\n    clean(node.getAttribute('name')) ||\n    clean(node.selectedOptions && node.selectedOptions[0] && node.selectedOptions[0].label);\n  const shown = (node, options) => !node.checkVisibility || node.checkVisibility(options);\n  const textOutsideSelects = (node) => {\n    if (!node.querySelector('select')) return shownText(node);\n    const hiddenLeftOut = shown(node);\n    const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_TEXT);\n    let text = '';\n    for (let visited = 0; visited < 500 && text.length < 200 && walker.nextNode(); visited++) {\n      const parent = walker.currentNode.parentElement;\n      if (!parent || parent.closest('select, textarea')) continue;\n      if (!hiddenLeftOut || shown(parent, { visibilityProperty: true })) text += ' ' + walker.currentNode.data;\n    }\n    return clean(text);\n  };\n  const quoted = (text) => (text ? ' \"' + cut(text) + '\"' : '');\n  const visible = shownText(el) || buttonValue(el) || (el.localName === 'select' ? selectName(el) : '');\n  if (visible) return describe(el) + quoted(visible);\n  const attribute = attributeText(el);\n  const position = siblingPosition(el);\n  if (position) return describe(el) + ' ' + position + quoted(attribute);\n  let ancestor = el.id || el.isContentEditable ? null : el.parentElement;\n  for (let depth = 0; ancestor && depth < 3; depth++, ancestor = ancestor.parentElement) {\n    if (isControl(ancestor)) break;\n    const text = textOutsideSelects(ancestor);\n    if (text) return describe(el) + ' in ' + describe(ancestor) + quoted(text);\n  }\n  return describe(el) + quoted(attribute);\n}";
+/**
+ * Page-side location of an element: the iframes it is in (outermost first)
+ * and the shadow root holding it, e.g. `iframe#pay > shadow root of <x-card>`;
+ * empty for the main document.
+ */
+export declare const ELEMENT_CONTEXT_JS = "(el) => {\n  const describe = (node) => node.tagName.toLowerCase() + (node.id ? '#' + node.id : '');\n  const parts = [];\n  for (let doc = el.ownerDocument; doc && doc.defaultView && doc.defaultView.frameElement; ) {\n    const frame = doc.defaultView.frameElement;\n    parts.unshift(describe(frame));\n    doc = frame.ownerDocument;\n  }\n  const root = el.getRootNode();\n  if (root.host) parts.push('shadow root of <' + describe(root.host) + '>');\n  return parts.join(' > ');\n}";
+/**
+ * Short text preview of an element's text: whitespace collapsed, cut on a
+ * whole character (an emoji is never split, which would make JSON invalid).
+ *
+ * @param text - Element text as the page renders it
+ * @param length - Characters kept
+ * @returns Collapsed text, truncated to `length` characters (followed by `...`)
+ */
+export declare function textPreview(text: string, length?: number): string;
+//# sourceMappingURL=elementInfo.d.ts.map

package/dist/runtime/dom/elementInfo.js

@@ -0,0 +1,256 @@
+/**
+ * Page-side descriptions of elements for DOM command output (`dom query`,
+ * `dom layout`, DOM context of console messages): their text as a user sees
+ * it and where they live (iframes, shadow roots).
+ */
+/** Length of the text preview shown for elements. */
+const PREVIEW_LENGTH = 80;
+/** Length of the text `dom get` shows for an element. */
+export const ELEMENT_TEXT_LENGTH = 500;
+/**
+ * Page-side removal of decorations from an element's text: close buttons
+ * (`.close`, `aria-label="Close"` or `"Dismiss"`, a button or link showing
+ * just `×`) and `aria-hidden` icons (text without letters or digits), so a
+ * flash message does not end in "×". `aria-hidden` text with words is kept:
+ * it is often the visible twin of a screen-reader text. Each decoration's
+ * text is removed once, from the end.
+ */
+export const WITHOUT_DECORATIONS_JS = `(el, text) => {
+  if (!text || typeof el.querySelectorAll !== 'function') return text;
+  const glyph = /^\\s*[×✕✖✗⨯]\\s*$/;
+  const textOf = (node) => (typeof node.innerText === 'string' ? node.innerText : node.textContent || '').trim();
+  const closer = '.close, [aria-label="close" i], [aria-label="dismiss" i]';
+  const rendered = (node) => !node.checkVisibility || node.checkVisibility();
+  const found = Array.from(el.querySelectorAll(closer + ', [aria-hidden="true"]'))
+    .filter((node) => rendered(node) && (node.matches(closer) || !/[\\p{L}\\p{N}]/u.test(textOf(node))));
+  if (/[×✕✖✗⨯]/.test(text)) {
+    found.push(...Array.from(el.querySelectorAll('button, a, [role="button"]')).filter((node) => glyph.test(node.textContent || '')));
+  }
+  const unique = Array.from(new Set(found));
+  const outermost = unique.filter((node) => !unique.some((other) => other !== node && other.contains(node)));
+  let result = text;
+  for (const node of outermost) {
+    const part = textOf(node);
+    const at = part ? result.lastIndexOf(part) : -1;
+    if (at >= 0) result = result.slice(0, at) + result.slice(at + part.length);
+  }
+  return result;
+}`;
+/**
+ * Page-side text of an element as a user sees it: `innerText` for a rendered
+ * element (CSS-hidden parts left out, inline elements not split apart), none
+ * for an element that is not rendered, `textContent` for SVG and other
+ * elements without `innerText` and for `display: contents` wrappers (no box
+ * of their own, but their children are shown), and the label of an
+ * `<option>` (which its `<select>` renders). For large containers (more
+ * than 2000 characters of text) only the start is read, from the text nodes
+ * whose parent is rendered, so a preview never lays out a whole page's text,
+ * unless `full` is set. Decorations are left out ({@link WITHOUT_DECORATIONS_JS}).
+ */
+export const ELEMENT_TEXT_JS = `(el, full) => {
+  const withoutDecorations = ${WITHOUT_DECORATIONS_JS};
+  const all = el.textContent || '';
+  if (el.tagName === 'OPTION') return el.label;
+  if (typeof el.innerText !== 'string') return full ? all : all.slice(0, 2000);
+  const rendered = (node) => !node.checkVisibility || node.checkVisibility();
+  if (!rendered(el)) {
+    const boxless = el.ownerDocument.defaultView.getComputedStyle(el).display === 'contents';
+    return boxless ? withoutDecorations(el, full ? all : all.slice(0, 2000)) : '';
+  }
+  if (full || all.length <= 2000) return withoutDecorations(el, el.innerText);
+  const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  let start = '';
+  while (start.length < 1000 && walker.nextNode()) {
+    const parent = walker.currentNode.parentElement;
+    if (!parent || rendered(parent)) start += walker.currentNode.data;
+  }
+  return withoutDecorations(el, start);
+}`;
+/** Shown instead of a secret field value (the same for every length) */
+export const MASKED_VALUE = '••••';
+/**
+ * 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
+ * field shown masked by CSS (`-webkit-text-security` other than `none`),
+ * one whose `autocomplete` names a password, a payment card (`cc-*`) or a
+ * one-time code, or a field named like a password, one-time code or card code
+ * (`password`, `passwd`, `pwd`, `passcode`, `otp`, `cvv`, `cvc`), which
+ * covers a password field switched to text by a "show password" button.
+ */
+export const SENSITIVE_FIELD_JS = `(el) => {
+  const autocomplete = el.getAttribute('autocomplete') || '';
+  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;
+  try {
+    const security = el.ownerDocument.defaultView.getComputedStyle(el).getPropertyValue('-webkit-text-security');
+    return Boolean(security) && security !== 'none';
+  } catch (e) {
+    return false;
+  }
+}`;
+/**
+ * Page-side live state of a form control, which its attributes do not show:
+ * the type and current value of an `<input>` (for checkboxes and radios
+ * `checked` and their `value` attribute, not the default "on"), the value of
+ * a `<textarea>`, the labels of a `<select>`'s selected options and the type
+ * of a `<button>` in a form (`submit` when it has none; outside a form only
+ * a type attribute is shown). Empty for other elements.
+ *
+ * Secrets never leave the page: a hidden input's value is left out, and the
+ * value (or selected option) of a sensitive field ({@link SENSITIVE_FIELD_JS})
+ * is replaced by {@link MASKED_VALUE}, whatever its length, with
+ * `sensitive: true`.
+ */
+export const ELEMENT_STATE_JS = `(el) => {
+  const isSensitive = ${SENSITIVE_FIELD_JS};
+  const mask = (value) => (value ? '${MASKED_VALUE}' : '');
+  const guarded = (state) => {
+    if (!isSensitive(el)) return state;
+    const result = { ...state, sensitive: true };
+    if ('value' in result) result.value = mask(result.value);
+    if ('selected' in result) result.selected = mask(result.selected);
+    return result;
+  };
+  switch (el.localName) {
+    case 'input':
+      if (el.type === 'hidden') return { type: 'hidden' };
+      return guarded(
+        /^(checkbox|radio)$/.test(el.type)
+          ? { type: el.type, checked: el.checked, value: el.getAttribute('value') || '' }
+          : { type: el.type, value: el.value }
+      );
+    case 'textarea':
+      return guarded({ value: el.value });
+    case 'select':
+      return guarded({ selected: Array.from(el.selectedOptions || [], (option) => option.label).join(', ') });
+    case 'button':
+      return el.form ? { type: el.type } : {};
+    default:
+      return {};
+  }
+}`;
+/**
+ * Page-side short description of an element: tag, id and up to two classes,
+ * e.g. `button#save.primary.large`.
+ */
+export const ELEMENT_DESCRIPTION_JS = `(node) => node.tagName.toLowerCase() +
+  (node.id ? '#' + node.id : '') +
+  (node.classList && node.classList.length ? '.' + Array.from(node.classList).slice(0, 2).join('.') : '')`;
+/**
+ * Page-side position of an element among its parent's children with the
+ * same short description ({@link ELEMENT_DESCRIPTION_JS}), e.g. `(2nd of 3)`;
+ * empty when it is the only one.
+ */
+export const SIBLING_POSITION_JS = `(el) => {
+  const describe = ${ELEMENT_DESCRIPTION_JS};
+  const parent = el.parentElement;
+  if (!parent) return '';
+  const own = describe(el);
+  const same = Array.from(parent.children).filter((child) => describe(child) === own);
+  if (same.length < 2) return '';
+  const n = same.indexOf(el) + 1;
+  const teen = n % 100 >= 11 && n % 100 <= 13;
+  const suffix = teen ? 'th' : ({ 1: 'st', 2: 'nd', 3: 'rd' })[n % 10] || 'th';
+  return '(' + n + suffix + ' of ' + same.length + ')';
+}`;
+/**
+ * Page-side identity of an element an action hit, so the output says which
+ * one it was, as one string: its short description
+ * ({@link ELEMENT_DESCRIPTION_JS}) and visible text (button value for button
+ * inputs, decorations left out), e.g. `button#add.btn "Add to cart"`. A
+ * `<select>` is named by its label, aria-label or name, else by its selected
+ * option, e.g. `select.sort "Sort products"`. An element without visible
+ * text is described by itself first: by its position among same-looking
+ * siblings ({@link SIBLING_POSITION_JS}), e.g. `div.figure (2nd of 3)`, with
+ * its aria-label, placeholder or title when it has one. Only an element
+ * without an id that is the only one of its kind is named by the nearest of
+ * three ancestors that has text, e.g.
+ * `input.toggle in div.view "Write report"` (rows of a list share their
+ * aria-label), leaving out the options
+ * of `<select>`s in it (read like `innerText`: CSS-hidden text is left out of
+ * a rendered ancestor; at most 500 text nodes; selects in shadow roots are
+ * not looked into), and never past an editable ancestor, whose text may be
+ * typed input; otherwise its aria-label, placeholder or title is used. Texts
+ * are cut at 40 characters. Contenteditable elements count as controls: what
+ * was typed into them is never echoed (nor their ancestors' text).
+ */
+export const ELEMENT_IDENTITY_JS = `(el) => {
+  const describe = ${ELEMENT_DESCRIPTION_JS};
+  const siblingPosition = ${SIBLING_POSITION_JS};
+  const withoutDecorations = ${WITHOUT_DECORATIONS_JS};
+  const clean = (text) => (text || '').replace(/\\s+/g, ' ').trim();
+  const cut = (text) => {
+    const characters = Array.from(text);
+    return characters.length > 40 ? characters.slice(0, 40).join('') + '…' : text;
+  };
+  const isControl = (node) => /^(input|select|textarea)$/.test(node.localName) || node.isContentEditable;
+  const shownText = (node) =>
+    isControl(node) ? '' : clean(withoutDecorations(node, typeof node.innerText === 'string' ? node.innerText : node.textContent));
+  const buttonValue = (node) => (node.localName === 'input' && /^(submit|button|reset)$/i.test(node.type) ? clean(node.value) : '');
+  const attributeText = (node) =>
+    clean(node.getAttribute('aria-label')) || clean(node.getAttribute('placeholder')) || clean(node.getAttribute('title'));
+  const selectName = (node) =>
+    clean(node.labels && node.labels[0] && node.labels[0].innerText) ||
+    clean(node.getAttribute('aria-label')) ||
+    clean(node.getAttribute('name')) ||
+    clean(node.selectedOptions && node.selectedOptions[0] && node.selectedOptions[0].label);
+  const shown = (node, options) => !node.checkVisibility || node.checkVisibility(options);
+  const textOutsideSelects = (node) => {
+    if (!node.querySelector('select')) return shownText(node);
+    const hiddenLeftOut = shown(node);
+    const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_TEXT);
+    let text = '';
+    for (let visited = 0; visited < 500 && text.length < 200 && walker.nextNode(); visited++) {
+      const parent = walker.currentNode.parentElement;
+      if (!parent || parent.closest('select, textarea')) continue;
+      if (!hiddenLeftOut || shown(parent, { visibilityProperty: true })) text += ' ' + walker.currentNode.data;
+    }
+    return clean(text);
+  };
+  const quoted = (text) => (text ? ' "' + cut(text) + '"' : '');
+  const visible = shownText(el) || buttonValue(el) || (el.localName === 'select' ? selectName(el) : '');
+  if (visible) return describe(el) + quoted(visible);
+  const attribute = attributeText(el);
+  const position = siblingPosition(el);
+  if (position) return describe(el) + ' ' + position + quoted(attribute);
+  let ancestor = el.id || el.isContentEditable ? null : el.parentElement;
+  for (let depth = 0; ancestor && depth < 3; depth++, ancestor = ancestor.parentElement) {
+    if (isControl(ancestor)) break;
+    const text = textOutsideSelects(ancestor);
+    if (text) return describe(el) + ' in ' + describe(ancestor) + quoted(text);
+  }
+  return describe(el) + quoted(attribute);
+}`;
+/**
+ * Page-side location of an element: the iframes it is in (outermost first)
+ * and the shadow root holding it, e.g. `iframe#pay > shadow root of <x-card>`;
+ * empty for the main document.
+ */
+export const ELEMENT_CONTEXT_JS = `(el) => {
+  const describe = (node) => node.tagName.toLowerCase() + (node.id ? '#' + node.id : '');
+  const parts = [];
+  for (let doc = el.ownerDocument; doc && doc.defaultView && doc.defaultView.frameElement; ) {
+    const frame = doc.defaultView.frameElement;
+    parts.unshift(describe(frame));
+    doc = frame.ownerDocument;
+  }
+  const root = el.getRootNode();
+  if (root.host) parts.push('shadow root of <' + describe(root.host) + '>');
+  return parts.join(' > ');
+}`;
+/**
+ * Short text preview of an element's text: whitespace collapsed, cut on a
+ * whole character (an emoji is never split, which would make JSON invalid).
+ *
+ * @param text - Element text as the page renders it
+ * @param length - Characters kept
+ * @returns Collapsed text, truncated to `length` characters (followed by `...`)
+ */
+export function textPreview(text, length = PREVIEW_LENGTH) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    const characters = Array.from(collapsed);
+    return characters.length > length ? characters.slice(0, length).join('') + '...' : collapsed;
+}
+//# sourceMappingURL=elementInfo.js.map

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

@@ -31,6 +31,25 @@ export interface EvalResult {
  * throwing getter becomes `[Error: …]`.
  */
 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    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}";
+/** 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 */
+export interface BusyRecoveryOptions {
+    /** Time after which a command that has not answered gets the target checked */
+    busyAfterMs?: number;
+    /** How long the target gets to answer the check */
+    livenessMs?: number;
+    /** The page (default) or an iframe, for messages */
+    scope?: BusyScope;
+}
+/**
+ * Whether Chrome failed a command because the document it ran in went away
+ * (navigation, a removed iframe).
+ *
+ * @param error - Error thrown by a CDP command
+ * @returns True for a lost context
+ */
+export declare function isContextLostError(error: unknown): boolean;
 /**
  * Run a CDP command on the page, recovering a page kept busy by its own
  * scripts. If the command has not answered when a script would have been
@@ -41,21 +60,45 @@ export declare const JSON_SAFE_COPY_FUNCTION = "function () {\n  const MAX_ITEMS
  *
  * @param cdp - CDP connection
  * @param command - The pending command
- * @param limits - When to check the page, and how long it gets to answer
+ * @param options - When to check the page, how long it gets to answer, what to call it
  * @returns The command's result
  * @throws CommandError (102) when the page was busy
  */
-export declare function withBusyPageRecovery<T>(cdp: CDPSender, command: Promise<T>, limits?: {
-    busyAfterMs: number;
-    livenessMs: number;
-}): Promise<T>;
+export declare function withBusyPageRecovery<T>(cdp: CDPSender, command: Promise<T>, options?: BusyRecoveryOptions): Promise<T>;
+/**
+ * The work's value if it settles within `ms` (its rejection is passed on).
+ *
+ * @param work - Pending work
+ * @param ms - Time limit
+ * @returns `{ settled: true, value }`, or `{ settled: false }` when time ran out
+ */
+export declare function settledWithin<T>(work: Promise<T>, ms: number): Promise<{
+    settled: true;
+    value: T;
+} | {
+    settled: false;
+}>;
 /** Where a `bdg dom eval` script runs (default: the page's main frame) */
 export interface EvalTarget {
     /** Session of an attached target (out-of-process iframe) */
     sessionId?: string;
+    /**
+     * Where to check and recover the target when it does not answer (default:
+     * the session itself); a session attached while the target was busy gets
+     * no answer at all
+     */
+    recovery?: CDPSender;
     /** Execution context of a frame (`ExecutionContextDescription.uniqueId`) */
     uniqueContextId?: string;
 }
+/**
+ * Whether the page still answers. A page that does not answer in time is
+ * taken as open: commands wait while a navigation is pending.
+ *
+ * @param cdp - CDP connection of the page
+ * @returns False when the page (tab) was closed
+ */
+export declare function pageStillOpen(cdp: CDPSender): Promise<boolean>;
 /**
  * Evaluate a `bdg dom eval` script.
  *
@@ -70,7 +113,9 @@ export interface EvalTarget {
  * @param script - JavaScript expression
  * @param target - Session and execution context to run in (default: the page)
  * @returns Value and type
- * @throws CommandError (102) when the script was terminated, (91) when it threw
+ * @throws CommandError (102) when the script was terminated or a promise did
+ *   not settle, (91) when it threw, (83) when the page navigated while it ran
+ *   (in a frame, Chrome's context-lost error is passed on for the caller to explain)
  */
 export declare function evaluateScript(cdp: CDPConnection, script: string, target?: EvalTarget): Promise<EvalResult>;
 //# sourceMappingURL=evalHelpers.d.ts.map