browser-debugger-cli 0.9.0 → 0.10.0

package/dist/runtime/dom/inspectRules.js

@@ -0,0 +1,101 @@
+/**
+ * CDP side of `dom inspect`'s cascade: the stylesheet headers (where a rule
+ * comes from), the matched rules of an element with a time budget, and
+ * labels for a declaration's source.
+ */
+import { createLogger } from '../../ui/logging/index.js';
+import { raceTimeout } from '../../utils/async.js';
+const log = createLogger('dom');
+/** Stylesheet headers by id, per connection (from `CSS.styleSheetAdded`) */
+const headersByConnection = new WeakMap();
+/**
+ * Start collecting stylesheet headers. Call before `CSS.enable`, which
+ * reports every existing stylesheet; later ones arrive as they are added,
+ * removed ones (navigations) are dropped.
+ *
+ * @param cdp - CDP connection
+ */
+export function trackStyleSheets(cdp) {
+    if (headersByConnection.has(cdp))
+        return;
+    const headers = new Map();
+    headersByConnection.set(cdp, headers);
+    cdp.on('CSS.styleSheetAdded', ({ header }) => {
+        headers.set(header.styleSheetId, header);
+    });
+    cdp.on('CSS.styleSheetRemoved', ({ styleSheetId }) => {
+        headers.delete(styleSheetId);
+    });
+}
+/**
+ * The rules that match an element, with its inline style and what its
+ * ancestors pass down, or why they are missing.
+ *
+ * @param cdp - CDP connection
+ * @param nodeId - Node id of the element
+ * @param budgetMs - Time allowed
+ * @returns Matched styles, `timeout` (longer than the budget) or `failed` (CDP error)
+ */
+export async function matchedStyles(cdp, nodeId, budgetMs) {
+    const request = cdp
+        .send('CSS.getMatchedStylesForNode', { nodeId })
+        .then((response) => response)
+        .catch((error) => {
+        log.debug(`CSS.getMatchedStylesForNode failed: ${String(error)}`);
+        return 'failed';
+    });
+    return (await raceTimeout(request, budgetMs)) ?? 'timeout';
+}
+/**
+ * File name of a URL, without query or hash; the host for a site's root.
+ *
+ * @param url - Stylesheet (or page) URL
+ * @returns e.g. `bootstrap.min.css`, `localhost:8765`
+ */
+function fileName(url) {
+    const path = url.split(/[?#]/)[0] ?? url;
+    const segments = path.split('/').filter(Boolean);
+    return segments.at(-1) ?? path;
+}
+/**
+ * Where a declaration comes from, for people: the selector and the file
+ * with its line (and column, for single-line minified files), or what kind
+ * of style it is.
+ *
+ * @param declaration - Declaration
+ * @param cdp - CDP connection whose stylesheet headers to use
+ * @returns e.g. `.btn-primary (bootstrap.min.css:5:52628)`, `style attribute`, `browser default`
+ */
+export function sourceLabel(declaration, cdp) {
+    const { source } = declaration;
+    if (source.kind === 'inline')
+        return 'style attribute';
+    if (source.kind === 'attribute')
+        return 'HTML attribute';
+    if (source.origin === 'user-agent')
+        return `${source.selector ?? ''} (browser default)`.trim();
+    const header = source.styleSheetId
+        ? headersByConnection.get(cdp)?.get(source.styleSheetId)
+        : undefined;
+    return `${source.selector ?? ''} (${fileLabel(header, source.line, source.column)})`;
+}
+/**
+ * A stylesheet position as `file:line[:column]`.
+ *
+ * @param header - Stylesheet header (unknown: just the line)
+ * @param line - 0-based line within the stylesheet
+ * @param column - 0-based column
+ * @returns e.g. `app.css:12`, `bootstrap.min.css:5:52628`, `<style> in index.html:40`, `constructed stylesheet`
+ */
+function fileLabel(header, line, column) {
+    if (!header)
+        return line === undefined ? 'stylesheet' : `stylesheet:${line + 1}`;
+    if (header.isConstructed)
+        return 'constructed stylesheet';
+    const file = fileName(header.sourceURL) || 'page';
+    const absoluteLine = (line ?? 0) + (header.isInline ? header.startLine : 0) + 1;
+    const where = header.isInline ? `<style> in ${file}` : file;
+    const minified = header.endLine - header.startLine < 10 && (column ?? 0) > 200;
+    return minified ? `${where}:${absoluteLine}:${(column ?? 0) + 1}` : `${where}:${absoluteLine}`;
+}
+//# sourceMappingURL=inspectRules.js.map

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

@@ -0,0 +1,132 @@
+/**
+ * Page-side part of `bdg dom inspect`: one call on the element reads what
+ * computed styles do not say. Its text as a user sees it (`innerText`, form
+ * values, secrets masked), where it sits in its parent (distances to the
+ * parent's content edges and to its neighbouring siblings), the
+ * backgrounds behind it (for the contrast of its text), the computed (not
+ * resolved) width and height (`auto` vs a length, for hug/fill/fixed) and
+ * the child tree, all in one walk: children are never styled one CDP call at
+ * a time.
+ *
+ * Children are those of the flat tree: an open shadow root's children
+ * instead of the light DOM, slots replaced by what is assigned to them, and
+ * `display: contents` wrappers by their children.
+ */
+/** Elements walked for the child tree at most (the rest are counted) */
+export declare const TREE_NODE_CAP = 400;
+/** A child as the page-side walk reports it */
+export interface RawTreeNode {
+    /** `tag#id` or `tag.firstClass` */
+    label: string;
+    /** Position of the border box relative to the parent's */
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    display: string;
+    /** Text of an element without block-level children */
+    text?: string;
+    children?: RawTreeNode[];
+    /** Rendered element children (at the depth limit) */
+    childCount?: number;
+    /** Element children that are not rendered */
+    hidden?: number;
+}
+/** A background behind the element (the element's own first) */
+export interface RawBackground {
+    /** Computed `background-color` */
+    color: string;
+    /** Has a background image or gradient */
+    image: boolean;
+}
+/** What {@link INSPECT_PAGE_JS} returns */
+export interface RawInspect {
+    tag: string;
+    id: string;
+    classes: string[];
+    context: string;
+    /** Text (innerText) or form value, whitespace collapsed (at most 200 characters) */
+    content: string;
+    /** Placeholder of an empty text field */
+    placeholder?: string;
+    /** Computed color of its `::placeholder` */
+    placeholderColor?: string;
+    /** Font style and weight of the placeholder (they decide whether it is large text) */
+    placeholderFont?: {
+        style: string;
+        weight: string;
+    };
+    /** Has text to describe: own text, only inline content with text, or a form control */
+    textual: boolean;
+    formControl: boolean;
+    /** Replaced element (img, svg and its shapes, video, canvas, iframe, embed, object, form controls): sized by its content */
+    replaced?: boolean;
+    /** An SVG element (SVG properties are not noise for it) */
+    svg?: boolean;
+    /** A text node is a direct child (the rendered font is read from the element itself) */
+    ownText: boolean;
+    /** Computed (not resolved) width and height: `auto`, `200px`, `50%`, … */
+    typed: {
+        width: string;
+        height: string;
+    };
+    /** Short description of the parent that lays it out */
+    parent?: string;
+    /** Distances from that parent's content box edges */
+    inParent?: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /** Gaps to the previous and next rendered in-flow siblings, by the side they are on */
+    siblings?: {
+        top?: number;
+        bottom?: number;
+        left?: number;
+        right?: number;
+    };
+    /** Content size when it overflows the box */
+    scroll?: {
+        w: number;
+        h: number;
+        clientW: number;
+        clientH: number;
+    };
+    /** Backgrounds from the element up to the root */
+    backgrounds: RawBackground[];
+    /** The page canvas behind everything is dark (color-scheme) */
+    canvasDark: boolean;
+    /** Opacity of the element times that of its ancestors */
+    opacity?: number;
+    tree?: RawTreeNode[];
+    hiddenChildren: number;
+    /** Children the walk did not reach ({@link TREE_NODE_CAP}) */
+    treeSkipped: number;
+    /**
+     * `--props` values from `getComputedStyle` (shorthands and custom
+     * properties too); a shorthand whose sides differ (no single value) is
+     * given per side, e.g. `top 1px solid … / right 0px none …`
+     */
+    props?: Record<string, string>;
+    /** `--props` names the browser does not know as CSS properties */
+    unknownProps?: string[];
+    /** Properties of running CSS transitions, and names of running animations */
+    animating: string[];
+}
+/**
+ * Page-side function run on the element (`this`), see {@link RawInspect}.
+ * Arguments: tree depth, and the property names asked for with `--props`
+ * (or null).
+ */
+export declare const INSPECT_PAGE_JS = "function (depth, props) {\n  const el = this;\n  const view = el.ownerDocument.defaultView;\n  const tree = ((view) => {\n  const style = (n, pseudo) => view.getComputedStyle(n, pseudo);\n  const skipped = /^(script|style|template|link|meta|noscript|title|head|base)$/;\n  const flatParent = (n) => n.assignedSlot || n.parentElement || (n.parentNode && n.parentNode.host) || null;\n  const layoutParent = (n) => {\n    let p = flatParent(n);\n    while (p && style(p).display === 'contents') p = flatParent(p);\n    return p;\n  };\n  const children = (n) => {\n    const out = [];\n    const add = (c) => {\n      if (skipped.test(c.localName)) return;\n      if (c.localName === 'slot') {\n        const assigned = c.assignedElements({ flatten: true });\n        (assigned.length ? assigned : Array.from(c.children)).forEach(add);\n      } else if (style(c).display === 'contents') {\n        Array.from((c.shadowRoot || c).children).forEach(add);\n      } else {\n        out.push(c);\n      }\n    };\n    Array.from((n.shadowRoot || n).children).forEach(add);\n    return out;\n  };\n  const rendered = (n) => n.getClientRects().length > 0 &&\n    (!n.checkVisibility || n.checkVisibility({ visibilityProperty: true }));\n  const container = (n) => children(n).some((c) => rendered(c) && !/^inline/.test(style(c).display));\n  return { style, flatParent, layoutParent, children, rendered, container };\n})(view);\n  const textOf = (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 clean = (text) => String(text || '').replace(/\\s+/g, ' ').trim().slice(0, 200);\n  if (el.localName === 'input' && el.type === 'hidden') return '';\n  if (el.localName === 'input' || el.localName === 'textarea') {\n    return el.value && isSensitive(el) ? '\u2022\u2022\u2022\u2022' : clean(el.value);\n  }\n  if (el.localName === 'select') {\n    const chosen = clean(Array.from(el.selectedOptions || [], (o) => o.label).join(', '));\n    return chosen && isSensitive(el) ? '\u2022\u2022\u2022\u2022' : chosen;\n  }\n  const outsideControls = () => {\n    const parts = [];\n    const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_TEXT);\n    for (let n = walker.nextNode(); n && parts.length < 400; n = walker.nextNode()) {\n      const holder = n.parentElement;\n      if (!holder || holder.closest('select, textarea, script, style, template, noscript')) continue;\n      if (holder.checkVisibility && !holder.checkVisibility({ visibilityProperty: true })) continue;\n      parts.push(n.data);\n    }\n    return parts.join(' ');\n  };\n  const holdsControls = Boolean(el.querySelector && el.querySelector('select, textarea'));\n  const raw = holdsControls ? outsideControls() : typeof el.innerText === 'string' ? el.innerText : el.textContent;\n  const text = clean(raw);\n  const view = el.ownerDocument.defaultView;\n  const security = view ? view.getComputedStyle(el).getPropertyValue('-webkit-text-security') : '';\n  return text && security && security !== 'none' ? '\u2022\u2022\u2022\u2022' : text;\n};\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 s = tree.style(el);\n  const formControl = /^(input|textarea|select|button)$/.test(el.localName);\n  const content = textOf(el);\n  const parent = tree.layoutParent(el);\n  const typedMap = el.computedStyleMap ? el.computedStyleMap() : null;\n  const typed = (name) => { try { return typedMap ? String(typedMap.get(name)) : ''; } catch (e) { return ''; } };\n  const result = {\n    tag: el.localName,\n    id: el.id || '',\n    classes: el.classList ? Array.from(el.classList) : [],\n    context: ((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})(el),\n    content: content,\n    textual: formControl || (content !== '' && !tree.container(el)),\n    formControl: formControl,\n    replaced: el instanceof SVGElement || /^(img|video|canvas|iframe|embed|object|input|textarea|select|button|meter|progress)$/.test(el.localName),\n    svg: el.namespaceURI === 'http://www.w3.org/2000/svg',\n    ownText: Array.from(el.childNodes).some((n) => n.nodeType === 3 && n.data.trim() !== ''),\n    typed: { width: typed('width'), height: typed('height') },\n    parent: parent ? describe(parent) : undefined,\n    animating: el.getAnimations ? [...new Set(el.getAnimations().filter((a) => a.playState === 'running').map((a) => a.transitionProperty || a.animationName || 'animation'))] : []\n  };\n  if (/^(input|textarea)$/.test(el.localName) && el.placeholder && !el.value) {\n    result.placeholder = el.placeholder.replace(/\\s+/g, ' ').trim();\n    const placeholderStyle = tree.style(el, '::placeholder');\n    result.placeholderColor = placeholderStyle.color;\n    result.placeholderFont = { style: placeholderStyle.fontStyle, weight: placeholderStyle.fontWeight };\n  }\n  if (el.clientWidth > 0 && (el.scrollWidth > el.clientWidth + 1 || el.scrollHeight > el.clientHeight + 1)) {\n    result.scroll = { w: el.scrollWidth, h: el.scrollHeight, clientW: el.clientWidth, clientH: el.clientHeight };\n  }\n  if (props) {\n    const known = (name) => name.startsWith('--') || CSS.supports(name, 'inherit');\n    const valueOf = (name) => {\n      const value = s.getPropertyValue(name).trim();\n      if (value !== '' || name.startsWith('--')) return value;\n      const sides = ['top', 'right', 'bottom', 'left'].map((side) => name + '-' + side).filter(known);\n      return sides.map((side) => side.slice(name.length + 1) + ' ' + s.getPropertyValue(side).trim()).join(' / ');\n    };\n    result.props = Object.fromEntries(props.filter(known).map((name) => [name, valueOf(name)]));\n    result.unknownProps = props.filter((name) => !known(name));\n  }\n  return Object.assign(result,\n    ((el, tree) => {\n  const parent = tree.layoutParent(el);\n  if (!parent || tree.style(el).position === 'fixed' || !tree.rendered(el)) return {};\n  const r = el.getBoundingClientRect();\n  const p = parent.getBoundingClientRect();\n  const ps = tree.style(parent);\n  const edge = (side) => parseFloat(ps['border-' + side + '-width']) + parseFloat(ps['padding-' + side]);\n  const inParent = {\n    left: r.left - (p.left + edge('left')),\n    top: r.top - (p.top + edge('top')),\n    right: (p.right - edge('right')) - r.right,\n    bottom: (p.bottom - edge('bottom')) - r.bottom\n  };\n  const inFlow = (n) => n !== el && tree.rendered(n) && !/^(absolute|fixed)$/.test(tree.style(n).position);\n  const siblings = tree.children(parent);\n  const at = siblings.indexOf(el);\n  const before = siblings.slice(0, Math.max(at, 0)).reverse().find(inFlow);\n  const after = at < 0 ? undefined : siblings.slice(at + 1).find(inFlow);\n  const gaps = {};\n  for (const sibling of [before, after]) {\n    if (!sibling) continue;\n    const s = sibling.getBoundingClientRect();\n    if (s.bottom <= r.top + 0.5) gaps.top = r.top - s.bottom;\n    else if (s.top >= r.bottom - 0.5) gaps.bottom = s.top - r.bottom;\n    else if (s.right <= r.left + 0.5) gaps.left = r.left - s.right;\n    else if (s.left >= r.right - 0.5) gaps.right = s.left - r.right;\n  }\n  return { inParent: inParent, siblings: gaps };\n})(el, tree),\n    ((el, tree, view) => {\n  const backgrounds = [];\n  let opacity = 1;\n  for (let n = el; n && backgrounds.length < 60; n = tree.flatParent(n)) {\n    const s = tree.style(n);\n    backgrounds.push({ color: s.backgroundColor, image: s.backgroundImage !== 'none' });\n    opacity *= Number(s.opacity) || 0;\n  }\n  const doc = el.ownerDocument;\n  const meta = doc.querySelector('meta[name=\"color-scheme\"]');\n  const rootScheme = tree.style(doc.documentElement).colorScheme;\n  const scheme = rootScheme && rootScheme !== 'normal' ? rootScheme : (meta && meta.content) || '';\n  const prefersDark = view.matchMedia('(prefers-color-scheme: dark)').matches;\n  const canvasDark = /dark/.test(scheme) && (!/light/.test(scheme) || prefersDark);\n  return { backgrounds: backgrounds, canvasDark: canvasDark, opacity: opacity };\n})(el, tree, view),\n    ((el, tree, textOf, depth) => {\n  let budget = 400;\n  let skipped = 0;\n  const labelOf = (n) => n.localName + (n.id ? '#' + n.id : n.classList && n.classList.length ? '.' + n.classList[0] : '');\n  const walk = (kids, level, origin) => {\n    const shown = kids.filter(tree.rendered);\n    const nodes = [];\n    for (const k of shown) {\n      if (budget <= 0) { skipped++; continue; }\n      budget--;\n      nodes.push(nodeOf(k, level, origin));\n    }\n    return { nodes: nodes, hidden: kids.length - shown.length };\n  };\n  const nodeOf = (n, level, origin) => {\n    const r = n.getBoundingClientRect();\n    const node = { label: labelOf(n), x: r.left - origin.left, y: r.top - origin.top, w: r.width, h: r.height, display: tree.style(n).display };\n    const kids = tree.children(n);\n    if (!tree.container(n)) node.text = textOf(n).slice(0, 60);\n    if (level >= depth) {\n      node.childCount = kids.filter(tree.rendered).length;\n      return node;\n    }\n    const sub = walk(kids, level + 1, r);\n    node.children = sub.nodes;\n    node.hidden = sub.hidden;\n    return node;\n  };\n  if (depth <= 0) return { hiddenChildren: 0, treeSkipped: 0 };\n  const top = walk(tree.children(el), 1, el.getBoundingClientRect());\n  return { tree: top.nodes, hiddenChildren: top.hidden, treeSkipped: skipped };\n})(el, tree, textOf, depth));\n}";
+/**
+ * Page-side function run on the element (`this`) that returns another
+ * element whose styles CDP reads: `"parent"`, the parent that lays it out
+ * (`display: contents` skipped, through shadow roots and slots), or
+ * `"textHolder"`, for an element whose text is in a descendant
+ * (`<button><span>Buy</span></button>`), the first element holding text,
+ * whose rendered font is the one shown. Null when there is none.
+ */
+export declare const RELATED_NODE_JS = "function (which) {\n  const tree = ((view) => {\n  const style = (n, pseudo) => view.getComputedStyle(n, pseudo);\n  const skipped = /^(script|style|template|link|meta|noscript|title|head|base)$/;\n  const flatParent = (n) => n.assignedSlot || n.parentElement || (n.parentNode && n.parentNode.host) || null;\n  const layoutParent = (n) => {\n    let p = flatParent(n);\n    while (p && style(p).display === 'contents') p = flatParent(p);\n    return p;\n  };\n  const children = (n) => {\n    const out = [];\n    const add = (c) => {\n      if (skipped.test(c.localName)) return;\n      if (c.localName === 'slot') {\n        const assigned = c.assignedElements({ flatten: true });\n        (assigned.length ? assigned : Array.from(c.children)).forEach(add);\n      } else if (style(c).display === 'contents') {\n        Array.from((c.shadowRoot || c).children).forEach(add);\n      } else {\n        out.push(c);\n      }\n    };\n    Array.from((n.shadowRoot || n).children).forEach(add);\n    return out;\n  };\n  const rendered = (n) => n.getClientRects().length > 0 &&\n    (!n.checkVisibility || n.checkVisibility({ visibilityProperty: true }));\n  const container = (n) => children(n).some((c) => rendered(c) && !/^inline/.test(style(c).display));\n  return { style, flatParent, layoutParent, children, rendered, container };\n})(this.ownerDocument.defaultView);\n  if (which === 'parent') return tree.layoutParent(this);\n  const walker = this.ownerDocument.createTreeWalker(this, NodeFilter.SHOW_TEXT);\n  while (walker.nextNode()) {\n    if (walker.currentNode.data.trim() !== '') return walker.currentNode.parentElement;\n  }\n  return null;\n}";
+//# sourceMappingURL=inspectScripts.d.ts.map

package/dist/runtime/dom/inspectScripts.js

@@ -0,0 +1,263 @@
+/**
+ * Page-side part of `bdg dom inspect`: one call on the element reads what
+ * computed styles do not say. Its text as a user sees it (`innerText`, form
+ * values, secrets masked), where it sits in its parent (distances to the
+ * parent's content edges and to its neighbouring siblings), the
+ * backgrounds behind it (for the contrast of its text), the computed (not
+ * resolved) width and height (`auto` vs a length, for hug/fill/fixed) and
+ * the child tree, all in one walk: children are never styled one CDP call at
+ * a time.
+ *
+ * Children are those of the flat tree: an open shadow root's children
+ * instead of the light DOM, slots replaced by what is assigned to them, and
+ * `display: contents` wrappers by their children.
+ */
+import { ELEMENT_CONTEXT_JS, ELEMENT_DESCRIPTION_JS, MASKED_VALUE, SENSITIVE_FIELD_JS, } from './elementInfo.js';
+/** Elements walked for the child tree at most (the rest are counted) */
+export const TREE_NODE_CAP = 400;
+/**
+ * Page-side flat-tree helpers: the element's computed style, its flat-tree
+ * parent, the parent that lays it out (skipping `display: contents`), its
+ * element children in the flat tree and whether an element is rendered.
+ */
+const FLAT_TREE_JS = `(view) => {
+  const style = (n, pseudo) => view.getComputedStyle(n, pseudo);
+  const skipped = /^(script|style|template|link|meta|noscript|title|head|base)$/;
+  const flatParent = (n) => n.assignedSlot || n.parentElement || (n.parentNode && n.parentNode.host) || null;
+  const layoutParent = (n) => {
+    let p = flatParent(n);
+    while (p && style(p).display === 'contents') p = flatParent(p);
+    return p;
+  };
+  const children = (n) => {
+    const out = [];
+    const add = (c) => {
+      if (skipped.test(c.localName)) return;
+      if (c.localName === 'slot') {
+        const assigned = c.assignedElements({ flatten: true });
+        (assigned.length ? assigned : Array.from(c.children)).forEach(add);
+      } else if (style(c).display === 'contents') {
+        Array.from((c.shadowRoot || c).children).forEach(add);
+      } else {
+        out.push(c);
+      }
+    };
+    Array.from((n.shadowRoot || n).children).forEach(add);
+    return out;
+  };
+  const rendered = (n) => n.getClientRects().length > 0 &&
+    (!n.checkVisibility || n.checkVisibility({ visibilityProperty: true }));
+  const container = (n) => children(n).some((c) => rendered(c) && !/^inline/.test(style(c).display));
+  return { style, flatParent, layoutParent, children, rendered, container };
+}`;
+/**
+ * Page-side text of an element: a form control's value or a select's chosen
+ * options (masked for secrets, {@link SENSITIVE_FIELD_JS}), else its
+ * `innerText` (`textContent` for SVG), masked when CSS hides it as a secret
+ * (`-webkit-text-security`), whitespace collapsed. A container holding a
+ * select or textarea gets its visible text without theirs, so a form's text
+ * never carries a chosen option or typed text.
+ */
+const TEXT_JS = `(el) => {
+  const isSensitive = ${SENSITIVE_FIELD_JS};
+  const clean = (text) => String(text || '').replace(/\\s+/g, ' ').trim().slice(0, 200);
+  if (el.localName === 'input' && el.type === 'hidden') return '';
+  if (el.localName === 'input' || el.localName === 'textarea') {
+    return el.value && isSensitive(el) ? '${MASKED_VALUE}' : clean(el.value);
+  }
+  if (el.localName === 'select') {
+    const chosen = clean(Array.from(el.selectedOptions || [], (o) => o.label).join(', '));
+    return chosen && isSensitive(el) ? '${MASKED_VALUE}' : chosen;
+  }
+  const outsideControls = () => {
+    const parts = [];
+    const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    for (let n = walker.nextNode(); n && parts.length < 400; n = walker.nextNode()) {
+      const holder = n.parentElement;
+      if (!holder || holder.closest('select, textarea, script, style, template, noscript')) continue;
+      if (holder.checkVisibility && !holder.checkVisibility({ visibilityProperty: true })) continue;
+      parts.push(n.data);
+    }
+    return parts.join(' ');
+  };
+  const holdsControls = Boolean(el.querySelector && el.querySelector('select, textarea'));
+  const raw = holdsControls ? outsideControls() : typeof el.innerText === 'string' ? el.innerText : el.textContent;
+  const text = clean(raw);
+  const view = el.ownerDocument.defaultView;
+  const security = view ? view.getComputedStyle(el).getPropertyValue('-webkit-text-security') : '';
+  return text && security && security !== 'none' ? '${MASKED_VALUE}' : text;
+}`;
+/**
+ * Page-side position of the element in its layout parent: distances from
+ * the parent's content box edges and gaps to the previous and next rendered
+ * in-flow siblings (not absolutely positioned or fixed), named by the side
+ * the sibling is on. Not for fixed elements, whose box is not placed by
+ * the parent.
+ */
+const PLACEMENT_JS = `(el, tree) => {
+  const parent = tree.layoutParent(el);
+  if (!parent || tree.style(el).position === 'fixed' || !tree.rendered(el)) return {};
+  const r = el.getBoundingClientRect();
+  const p = parent.getBoundingClientRect();
+  const ps = tree.style(parent);
+  const edge = (side) => parseFloat(ps['border-' + side + '-width']) + parseFloat(ps['padding-' + side]);
+  const inParent = {
+    left: r.left - (p.left + edge('left')),
+    top: r.top - (p.top + edge('top')),
+    right: (p.right - edge('right')) - r.right,
+    bottom: (p.bottom - edge('bottom')) - r.bottom
+  };
+  const inFlow = (n) => n !== el && tree.rendered(n) && !/^(absolute|fixed)$/.test(tree.style(n).position);
+  const siblings = tree.children(parent);
+  const at = siblings.indexOf(el);
+  const before = siblings.slice(0, Math.max(at, 0)).reverse().find(inFlow);
+  const after = at < 0 ? undefined : siblings.slice(at + 1).find(inFlow);
+  const gaps = {};
+  for (const sibling of [before, after]) {
+    if (!sibling) continue;
+    const s = sibling.getBoundingClientRect();
+    if (s.bottom <= r.top + 0.5) gaps.top = r.top - s.bottom;
+    else if (s.top >= r.bottom - 0.5) gaps.bottom = s.top - r.bottom;
+    else if (s.right <= r.left + 0.5) gaps.left = r.left - s.right;
+    else if (s.left >= r.right - 0.5) gaps.right = s.left - r.right;
+  }
+  return { inParent: inParent, siblings: gaps };
+}`;
+/**
+ * Page-side backgrounds behind the element (its own first, then its flat-tree
+ * ancestors up to the root), the product of its and their opacity, and
+ * whether the page canvas is dark: the root's
+ * `color-scheme` (or the `color-scheme` meta tag) allows dark and either
+ * only dark or the page prefers dark.
+ */
+const BACKGROUNDS_JS = `(el, tree, view) => {
+  const backgrounds = [];
+  let opacity = 1;
+  for (let n = el; n && backgrounds.length < 60; n = tree.flatParent(n)) {
+    const s = tree.style(n);
+    backgrounds.push({ color: s.backgroundColor, image: s.backgroundImage !== 'none' });
+    opacity *= Number(s.opacity) || 0;
+  }
+  const doc = el.ownerDocument;
+  const meta = doc.querySelector('meta[name="color-scheme"]');
+  const rootScheme = tree.style(doc.documentElement).colorScheme;
+  const scheme = rootScheme && rootScheme !== 'normal' ? rootScheme : (meta && meta.content) || '';
+  const prefersDark = view.matchMedia('(prefers-color-scheme: dark)').matches;
+  const canvasDark = /dark/.test(scheme) && (!/light/.test(scheme) || prefersDark);
+  return { backgrounds: backgrounds, canvasDark: canvasDark, opacity: opacity };
+}`;
+/**
+ * Page-side child tree to `depth` levels: per element its label, size,
+ * display, position relative to its parent's border box (like Figma's x/y
+ * in a frame), text (only for elements without block-level children), and its
+ * rendered children (or their count at the depth limit) with a count of the
+ * hidden ones. Stops after {@link TREE_NODE_CAP} elements and counts the
+ * children it did not reach.
+ */
+const TREE_JS = `(el, tree, textOf, depth) => {
+  let budget = ${TREE_NODE_CAP};
+  let skipped = 0;
+  const labelOf = (n) => n.localName + (n.id ? '#' + n.id : n.classList && n.classList.length ? '.' + n.classList[0] : '');
+  const walk = (kids, level, origin) => {
+    const shown = kids.filter(tree.rendered);
+    const nodes = [];
+    for (const k of shown) {
+      if (budget <= 0) { skipped++; continue; }
+      budget--;
+      nodes.push(nodeOf(k, level, origin));
+    }
+    return { nodes: nodes, hidden: kids.length - shown.length };
+  };
+  const nodeOf = (n, level, origin) => {
+    const r = n.getBoundingClientRect();
+    const node = { label: labelOf(n), x: r.left - origin.left, y: r.top - origin.top, w: r.width, h: r.height, display: tree.style(n).display };
+    const kids = tree.children(n);
+    if (!tree.container(n)) node.text = textOf(n).slice(0, 60);
+    if (level >= depth) {
+      node.childCount = kids.filter(tree.rendered).length;
+      return node;
+    }
+    const sub = walk(kids, level + 1, r);
+    node.children = sub.nodes;
+    node.hidden = sub.hidden;
+    return node;
+  };
+  if (depth <= 0) return { hiddenChildren: 0, treeSkipped: 0 };
+  const top = walk(tree.children(el), 1, el.getBoundingClientRect());
+  return { tree: top.nodes, hiddenChildren: top.hidden, treeSkipped: skipped };
+}`;
+/**
+ * Page-side function run on the element (`this`), see {@link RawInspect}.
+ * Arguments: tree depth, and the property names asked for with `--props`
+ * (or null).
+ */
+export const INSPECT_PAGE_JS = `function (depth, props) {
+  const el = this;
+  const view = el.ownerDocument.defaultView;
+  const tree = (${FLAT_TREE_JS})(view);
+  const textOf = ${TEXT_JS};
+  const describe = ${ELEMENT_DESCRIPTION_JS};
+  const s = tree.style(el);
+  const formControl = /^(input|textarea|select|button)$/.test(el.localName);
+  const content = textOf(el);
+  const parent = tree.layoutParent(el);
+  const typedMap = el.computedStyleMap ? el.computedStyleMap() : null;
+  const typed = (name) => { try { return typedMap ? String(typedMap.get(name)) : ''; } catch (e) { return ''; } };
+  const result = {
+    tag: el.localName,
+    id: el.id || '',
+    classes: el.classList ? Array.from(el.classList) : [],
+    context: (${ELEMENT_CONTEXT_JS})(el),
+    content: content,
+    textual: formControl || (content !== '' && !tree.container(el)),
+    formControl: formControl,
+    replaced: el instanceof SVGElement || /^(img|video|canvas|iframe|embed|object|input|textarea|select|button|meter|progress)$/.test(el.localName),
+    svg: el.namespaceURI === 'http://www.w3.org/2000/svg',
+    ownText: Array.from(el.childNodes).some((n) => n.nodeType === 3 && n.data.trim() !== ''),
+    typed: { width: typed('width'), height: typed('height') },
+    parent: parent ? describe(parent) : undefined,
+    animating: el.getAnimations ? [...new Set(el.getAnimations().filter((a) => a.playState === 'running').map((a) => a.transitionProperty || a.animationName || 'animation'))] : []
+  };
+  if (/^(input|textarea)$/.test(el.localName) && el.placeholder && !el.value) {
+    result.placeholder = el.placeholder.replace(/\\s+/g, ' ').trim();
+    const placeholderStyle = tree.style(el, '::placeholder');
+    result.placeholderColor = placeholderStyle.color;
+    result.placeholderFont = { style: placeholderStyle.fontStyle, weight: placeholderStyle.fontWeight };
+  }
+  if (el.clientWidth > 0 && (el.scrollWidth > el.clientWidth + 1 || el.scrollHeight > el.clientHeight + 1)) {
+    result.scroll = { w: el.scrollWidth, h: el.scrollHeight, clientW: el.clientWidth, clientH: el.clientHeight };
+  }
+  if (props) {
+    const known = (name) => name.startsWith('--') || CSS.supports(name, 'inherit');
+    const valueOf = (name) => {
+      const value = s.getPropertyValue(name).trim();
+      if (value !== '' || name.startsWith('--')) return value;
+      const sides = ['top', 'right', 'bottom', 'left'].map((side) => name + '-' + side).filter(known);
+      return sides.map((side) => side.slice(name.length + 1) + ' ' + s.getPropertyValue(side).trim()).join(' / ');
+    };
+    result.props = Object.fromEntries(props.filter(known).map((name) => [name, valueOf(name)]));
+    result.unknownProps = props.filter((name) => !known(name));
+  }
+  return Object.assign(result,
+    (${PLACEMENT_JS})(el, tree),
+    (${BACKGROUNDS_JS})(el, tree, view),
+    (${TREE_JS})(el, tree, textOf, depth));
+}`;
+/**
+ * Page-side function run on the element (`this`) that returns another
+ * element whose styles CDP reads: `"parent"`, the parent that lays it out
+ * (`display: contents` skipped, through shadow roots and slots), or
+ * `"textHolder"`, for an element whose text is in a descendant
+ * (`<button><span>Buy</span></button>`), the first element holding text,
+ * whose rendered font is the one shown. Null when there is none.
+ */
+export const RELATED_NODE_JS = `function (which) {
+  const tree = (${FLAT_TREE_JS})(this.ownerDocument.defaultView);
+  if (which === 'parent') return tree.layoutParent(this);
+  const walker = this.ownerDocument.createTreeWalker(this, NodeFilter.SHOW_TEXT);
+  while (walker.nextNode()) {
+    if (walker.currentNode.data.trim() !== '') return walker.currentNode.parentElement;
+  }
+  return null;
+}`;
+//# sourceMappingURL=inspectScripts.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * The child tree of `bdg dom inspect`: the page-side walk's children
+ * ({@link RawTreeNode}) with sizes rounded, consecutive identical siblings
+ * (same label, size and layout) grouped into one row with a count
+ * (`li.card ×33 266x107`), and cut to a number of rows in document order.
+ */
+import type { InspectTreeNode } from '../../ipc/protocol/inspectTypes.js';
+import type { RawTreeNode } from './inspectScripts.js';
+/** Default depth of the tree */
+export declare const DEFAULT_TREE_DEPTH = 2;
+/** Default number of rows */
+export declare const DEFAULT_TREE_LIMIT = 20;
+/**
+ * Cut a row's text on a whole character.
+ *
+ * @param text - Text
+ * @returns At most {@link ROW_TEXT_LENGTH} characters, with `…` when cut
+ */
+export declare function rowText(text: string): string;
+/**
+ * Group runs of identical siblings into one row with a count. A group keeps
+ * its text only when every member has the same, and lists no children.
+ *
+ * @param nodes - Sibling rows
+ * @returns Rows with runs grouped
+ */
+export declare function groupSiblings(nodes: readonly InspectTreeNode[]): InspectTreeNode[];
+/**
+ * The child tree from the page-side walk: grouped, then cut to `limit` rows.
+ *
+ * @param raw - Children from the walk
+ * @param limit - Rows shown at most
+ * @param skipped - Children the walk did not reach (counted as left out)
+ * @returns Rows and the number of rows left out
+ */
+export declare function buildTree(raw: readonly RawTreeNode[], limit: number, skipped?: number): {
+    children: InspectTreeNode[];
+    moreRows: number;
+};
+//# sourceMappingURL=inspectTree.d.ts.map