browser-debugger-cli 0.8.0 → 0.10.0

package/dist/runtime/dom/layout.js

@@ -0,0 +1,340 @@
+/**
+ * Positions, sizes and visibility of elements (`bdg dom layout`).
+ *
+ * One page-side pass per command measures every match: its box in page and
+ * viewport coordinates (iframe offsets included), what clips it, whether it
+ * is rendered, what covers its center and the styles that decide how it
+ * shows. The measurements are classified outside the page
+ * ({@link classifyViewportPosition}).
+ */
+import { CommandError } from '../../errors/index.js';
+import { operationFailedError } from '../../errors/messages.js';
+import { ELEMENT_GEOMETRY_JS, FRAME_OFFSET_JS, VIEWPORT_SIZE_JS, classifyViewportPosition, } from './elementGeometry.js';
+import { ELEMENT_CONTEXT_JS, ELEMENT_DESCRIPTION_JS, ELEMENT_TEXT_JS, textPreview, } from './elementInfo.js';
+import { throwIfInvalidSelector } from './formFillHelpers/shared.js';
+import { findFrameOwner, placeInOwnerFrame } from './frameLayout.js';
+import { measureFrameMapping } from './frameScopedConnection.js';
+import { DEEP_QUERY_JS, missingElementError, selectorArgsJS } from './targetNode.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+const log = createLogger('dom');
+/** Matches measured per command (the rest are counted as omitted) */
+export const LAYOUT_ELEMENT_LIMIT = 100;
+/**
+ * Page-side end of a visible span kept clear of an overlay scrollbar along
+ * an edge (16 CSS px wide): overlay scrollbars (macOS, mobile) show for about a
+ * second after a scroll and catch hit tests, which then return the scroller.
+ * The span ends before the strip when it reaches into it and also shows
+ * outside it; without overlay scrollbars along the edge it is unchanged.
+ * Arguments: span start and end, the edge, whether overlay scrollbars show there.
+ */
+export const CLEAR_OF_SCROLLBAR_JS = `(start, end, edge, overlay) =>
+  overlay && end > edge - 16 && edge - 16 > start ? edge - 16 : end`;
+/**
+ * Page-side edges of the top-level viewport with overlay scrollbars: the page
+ * scrolls along an axis while its scrollbar takes no space (the window is as
+ * wide or tall as the viewport).
+ */
+const VIEWPORT_OVERLAY_JS = `(view, viewport) => {
+  const scroller = view.document.scrollingElement || view.document.documentElement;
+  return {
+    right: scroller.scrollHeight > viewport.height && view.innerWidth - viewport.width < 1,
+    bottom: scroller.scrollWidth > viewport.width && view.innerHeight - viewport.height < 1
+  };
+}`;
+/** Elements a click on any of their content activates */
+const CLICK_TARGET_SELECTOR = 'a[href], button, [role="button"], [role="link"], label, summary, input, select, textarea';
+/**
+ * Page-side test of whether an element on top of another one is part of the
+ * same click target, so a click there does what a click on the element
+ * would: both are in the same link, button or label (an overlay span inside
+ * the card's link), or in links to the same URL (a card's overlay link next
+ * to its headline link), or the element is plain content (in no link or
+ * button) of a card covered by its "faux block link" (news sites): an
+ * absolutely positioned `<a href>` without visible text of its own (empty,
+ * or an aria-label only), directly in the card (not `<body>`) and spanning
+ * it. Dismiss buttons, promo links with text and `[role=button]` overlays
+ * still count as covers.
+ */
+const SAME_CLICK_TARGET_JS = `(node, hit) => {
+  const parentOf = (n) => n.parentElement || (n.parentNode && n.parentNode.host) || null;
+  const targetOf = (n) => {
+    for (let p = n; p; p = parentOf(p)) {
+      if (p.matches && p.matches(${JSON.stringify(CLICK_TARGET_SELECTOR)})) return p;
+    }
+    return null;
+  };
+  const theirs = targetOf(hit);
+  if (!theirs) return false;
+  const mine = targetOf(node);
+  if (mine) return mine === theirs || (mine.localName === 'a' && theirs.localName === 'a' && mine.href === theirs.href);
+  const card = theirs.parentElement;
+  if (theirs.localName !== 'a' || theirs.hasAttribute('role')) return false;
+  if (!card || card === node.ownerDocument.body || !card.contains(node)) return false;
+  const style = theirs.ownerDocument.defaultView.getComputedStyle(theirs);
+  if (style.position !== 'absolute' || (theirs.innerText || '').trim() !== '') return false;
+  const outer = theirs.getBoundingClientRect();
+  const inner = card.getBoundingClientRect();
+  return outer.left <= inner.left + 1 && outer.top <= inner.top + 1 && outer.right >= inner.right - 1 && outer.bottom >= inner.bottom - 1;
+}`;
+/**
+ * Page function: layout of the matches in `found` (all up to `limit`, or the
+ * one at `index`) and of the top-level page. An element covers another when
+ * it is the topmost element at the center of the largest visible part of the
+ * other's boxes (a wrapped link has one per line; the strip where overlay
+ * scrollbars show is avoided when possible, {@link CLEAR_OF_SCROLLBAR_JS}) and does not lie inside it,
+ * nor part of the element's own click target ({@link SAME_CLICK_TARGET_JS}: the link, button
+ * or label it is in, or the overlay link of its card; a click there does the same). An
+ * ancestor covers it only when the ancestor is painted above it there (its
+ * `::before`/`::after` overlay, or its background over a negative
+ * `z-index`), as `dom click` finds: the element is in the hit-test stack below
+ * the ancestor. Hit-testing goes up through the iframes, so an overlay over
+ * an iframe covers the elements in it. Elements hit-testing skips
+ * (`pointer-events: none`, also through an iframe) get no cover.
+ */
+const LAYOUT_JS = `function (found, index, limit) {
+  const geometryOf = ${ELEMENT_GEOMETRY_JS};
+  const viewportSize = ${VIEWPORT_SIZE_JS};
+  const frameOffset = ${FRAME_OFFSET_JS};
+  const describe = ${ELEMENT_DESCRIPTION_JS};
+  const contextOf = ${ELEMENT_CONTEXT_JS};
+  const textOf = ${ELEMENT_TEXT_JS};
+  const clearOfScrollbar = ${CLEAR_OF_SCROLLBAR_JS};
+  const viewportOverlay = ${VIEWPORT_OVERLAY_JS};
+  const picked = index === null
+    ? found.slice(0, limit).map((el, i) => [i, el])
+    : (found[index] ? [[index, found[index]]] : []);
+  if (picked.length === 0) return { count: found.length, elements: [] };
+  let top = picked[0][1].ownerDocument.defaultView;
+  while (top.frameElement) top = top.parent;
+  const scroller = top.document.scrollingElement || top.document.documentElement;
+  const page = {
+    viewport: viewportSize(top),
+    scroll: { x: top.scrollX, y: top.scrollY },
+    document: { width: scroller.scrollWidth, height: scroller.scrollHeight },
+    colorScheme: top.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+  };
+  const pageOverlay = viewportOverlay(top, page.viewport);
+  const encloses = (outer, node) => {
+    for (let n = node; n; n = n.parentNode || n.host) if (n === outer) return true;
+    return false;
+  };
+  const sameTarget = ${SAME_CLICK_TARGET_JS};
+  const coverAt = (node, x, y) => {
+    const root = node.getRootNode();
+    const scope = typeof root.elementFromPoint === 'function' ? root : node.ownerDocument;
+    const hit = scope.elementFromPoint(x, y);
+    if (!hit || encloses(node, hit) || sameTarget(node, hit)) return null;
+    if (!encloses(hit, node)) return hit;
+    return scope.elementsFromPoint(x, y).indexOf(node) > 0 ? hit : null;
+  };
+  const visibleCenter = (el, g) => {
+    const bounds = [{ x: 0, y: 0, width: page.viewport.width, height: page.viewport.height }].concat(g.clip ? [g.clip] : []);
+    let best = null;
+    for (const r of Array.from(el.getClientRects())) {
+      const boxes = bounds.concat([{ x: r.left + g.offset.x, y: r.top + g.offset.y, width: r.width, height: r.height }]);
+      const left = Math.max(...boxes.map((b) => b.x));
+      const top = Math.max(...boxes.map((b) => b.y));
+      const right = Math.min(...boxes.map((b) => b.x + b.width));
+      const bottom = Math.min(...boxes.map((b) => b.y + b.height));
+      const area = (right - left) * (bottom - top);
+      if (!(right > left && bottom > top) || (best && area <= best.area)) continue;
+      let clearRight = clearOfScrollbar(left, right, page.viewport.width, pageOverlay.right);
+      let clearBottom = clearOfScrollbar(top, bottom, page.viewport.height, pageOverlay.bottom);
+      if (g.clip) {
+        clearRight = clearOfScrollbar(left, clearRight, g.clip.x + g.clip.width, g.clipOverlay.right);
+        clearBottom = clearOfScrollbar(top, clearBottom, g.clip.y + g.clip.height, g.clipOverlay.bottom);
+      }
+      best = { area: area, x: (left + clearRight) / 2, y: (top + clearBottom) / 2 };
+    }
+    return best;
+  };
+  const paintsNothing = (node) => {
+    const s = node.ownerDocument.defaultView.getComputedStyle(node);
+    const clearColor = (c) => c === 'transparent' || /^rgba\\(.*,\\s*0\\)$/.test(c);
+    const ownText = Array.from(node.childNodes).some((n) => n.nodeType === 3 && n.data.trim() !== '');
+    return clearColor(s.backgroundColor) && s.backgroundImage === 'none' && s.boxShadow === 'none' && !ownText;
+  };
+  const hitTestable = (node) => node.ownerDocument.defaultView.getComputedStyle(node).pointerEvents !== 'none';
+  const coveredBy = (el, g) => {
+    const center = hitTestable(el) && visibleCenter(el, g);
+    if (!center) return null;
+    let x = center.x - g.offset.x;
+    let y = center.y - g.offset.y;
+    let cover = coverAt(el, x, y);
+    for (let view = el.ownerDocument.defaultView; !cover && view.frameElement; view = view.parent) {
+      if (!hitTestable(view.frameElement)) return null;
+      const offset = frameOffset(view.frameElement);
+      x += offset.x;
+      y += offset.y;
+      cover = coverAt(view.frameElement, x, y);
+    }
+    return cover ? { element: describe(cover), transparent: paintsNothing(cover) } : null;
+  };
+  const elements = picked.map(([i, el]) => {
+    const style = el.ownerDocument.defaultView.getComputedStyle(el);
+    const geometry = geometryOf(el);
+    return {
+      index: i,
+      tag: el.tagName.toLowerCase(),
+      element: describe(el),
+      text: String(textOf(el)).replace(/\\s+/g, ' ').trim().slice(0, 1000),
+      context: contextOf(el),
+      geometry: geometry,
+      cover: geometry.hidden ? null : coveredBy(el, geometry),
+      computed: { display: style.display, visibility: style.visibility, position: style.position, opacity: style.opacity, zIndex: style.zIndex }
+    };
+  });
+  return { count: found.length, page: page, elements: elements, crossOriginFrame: top.parent !== top };
+}`;
+/** Distinguishes the object groups of concurrent calls */
+let groupCounter = 0;
+/**
+ * Measure the elements a selector (or cached index) refers to.
+ *
+ * @param cdp - CDP connection
+ * @param params - Selector (and index) or backend node id
+ * @returns Layout report
+ * @throws CommandError (83) no match, (81) index out of range or invalid
+ *   selector, (87) the cached element left the page
+ */
+export async function inspectLayout(cdp, params) {
+    const objectGroup = `bdg-layout-${++groupCounter}`;
+    try {
+        const raw = params.backendNodeId === undefined
+            ? await measureSelector(cdp, params)
+            : await measureNode(cdp, params.backendNodeId, objectGroup);
+        if (!raw.page || raw.elements.length === 0)
+            throw missingElementError(params, raw.count);
+        return buildLayoutResult({ ...raw, page: raw.page }, params);
+    }
+    finally {
+        void cdp
+            .send('Runtime.releaseObjectGroup', { objectGroup })
+            .catch((error) => log.debug(`Object group not released: ${getErrorMessage(error)}`));
+    }
+}
+/**
+ * Measure the matches of a selector (searching open shadow roots and
+ * same-origin frames) in one page evaluation.
+ *
+ * @param cdp - CDP connection
+ * @param params - Selector and optional index
+ * @returns Measurements
+ * @throws CommandError (81) invalid selector, (91) page script failure
+ */
+async function measureSelector(cdp, params) {
+    const found = `(${DEEP_QUERY_JS})(${selectorArgsJS(params.selector)})`;
+    const response = (await cdp.send('Runtime.evaluate', {
+        expression: `(${LAYOUT_JS})(${found}, ${params.index ?? null}, ${LAYOUT_ELEMENT_LIMIT})`,
+        returnByValue: true,
+    }));
+    if (response.exceptionDetails) {
+        throwIfInvalidSelector(response.exceptionDetails, params.selector);
+        const err = operationFailedError('measure the elements', response.exceptionDetails.text);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SCRIPT_ERROR);
+    }
+    return response.result.value;
+}
+/**
+ * Measure one exact element (from the query cache).
+ *
+ * @param cdp - CDP connection
+ * @param backendNodeId - Backend node id
+ * @param objectGroup - Object group for the handle
+ * @returns Measurements; no elements when the node left the page. An element
+ *   of a cross-origin iframe (from an a11y query) is placed in the top-level
+ *   viewport through the iframe's own measurements.
+ */
+async function measureNode(cdp, backendNodeId, objectGroup) {
+    const resolved = (await cdp
+        .send('DOM.resolveNode', { backendNodeId, objectGroup })
+        .catch((error) => {
+        log.debug(`Node ${backendNodeId} not resolved: ${getErrorMessage(error)}`);
+        return {};
+    }));
+    const objectId = resolved.object?.objectId;
+    if (!objectId)
+        return { count: 0, elements: [] };
+    const response = (await cdp.send('Runtime.callFunctionOn', {
+        objectId,
+        functionDeclaration: `function () { return (${LAYOUT_JS})(this.isConnected ? [this] : [], null, 1); }`,
+        returnByValue: true,
+    }));
+    const raw = response.result.value ?? { count: 0, elements: [] };
+    if (!raw.crossOriginFrame)
+        return raw;
+    const owner = await findFrameOwner(cdp, objectId);
+    if (owner === undefined)
+        return raw;
+    const ownerLayout = await measureNode(cdp, owner, objectGroup);
+    return placeInOwnerFrame(raw, ownerLayout, await measureFrameMapping(cdp, objectId));
+}
+/**
+ * Turn page-side measurements into the layout report: rounded page and
+ * viewport coordinates, viewport position and text preview per element.
+ *
+ * @param raw - Measurements with at least one element
+ * @param params - Request (selector and index)
+ * @returns Layout report
+ */
+export function buildLayoutResult(raw, params) {
+    const omitted = params.index === undefined ? raw.count - raw.elements.length : 0;
+    return {
+        success: true,
+        selector: params.selector,
+        count: raw.count,
+        page: roundPage(raw.page),
+        elements: raw.elements.map((element) => elementLayout(element, raw.page)),
+        ...(omitted > 0 && { omitted }),
+    };
+}
+/**
+ * Page layout with whole pixels.
+ *
+ * @param page - Measured page layout
+ * @returns Rounded page layout
+ */
+function roundPage(page) {
+    return {
+        viewport: { width: Math.round(page.viewport.width), height: Math.round(page.viewport.height) },
+        scroll: { x: Math.round(page.scroll.x), y: Math.round(page.scroll.y) },
+        document: { width: Math.round(page.document.width), height: Math.round(page.document.height) },
+        ...(page.colorScheme && { colorScheme: page.colorScheme }),
+    };
+}
+/**
+ * Layout of one element.
+ *
+ * @param raw - Element measurements
+ * @param page - Page layout (viewport size and scroll position)
+ * @returns Element layout; `coveredBy` only for elements that are in view
+ */
+function elementLayout(raw, page) {
+    const { rect } = raw.geometry;
+    const placement = classifyViewportPosition(raw.geometry, page.viewport);
+    const inView = placement.inViewport === 'visible' || placement.inViewport === 'partly';
+    const text = textPreview(raw.text);
+    return {
+        index: raw.index,
+        tag: raw.tag,
+        element: raw.element,
+        ...(text && { text }),
+        ...(raw.context && { context: raw.context }),
+        bounds: {
+            x: Math.round(rect.x + page.scroll.x),
+            y: Math.round(rect.y + page.scroll.y),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+        },
+        viewport: { x: Math.round(rect.x), y: Math.round(rect.y) },
+        ...placement,
+        ...(inView && raw.cover && { coveredBy: raw.cover.element }),
+        ...(inView && raw.cover?.transparent && { coverTransparent: true }),
+        ...(raw.geometry.invisible && { invisible: raw.geometry.invisible }),
+        ...(raw.geometry.inert && { inert: true }),
+        computed: raw.computed,
+    };
+}
+//# sourceMappingURL=layout.js.map

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

@@ -0,0 +1,72 @@
+/**
+ * Page-side functions of `bdg dom listeners`: what only the page can tell
+ * about an element's listeners (handler names and identities, React root
+ * containers, the handlers behind jQuery's dispatcher and Preact's event
+ * proxy, React's `on…` props of the element and its ancestors, the
+ * element's iframe).
+ *
+ * Each piece is a function expression in a string, combined into
+ * {@link ELEMENT_INFO_JS}; every lookup of page globals is guarded, so a
+ * page with odd globals (a throwing `jQuery` getter) only loses that detail.
+ */
+/** Most jQuery handlers resolved per call; the rest keep jQuery's dispatcher */
+export declare const MAX_JQUERY_HANDLERS = 50;
+/** Most React prop handlers resolved per call; the rest are counted */
+export declare const MAX_REACT_HANDLERS = 50;
+/**
+ * Page function, called on the element with the listeners (position in the
+ * chain, event type and capture flag of each), the requested event types (null for all;
+ * React props are filtered before the limit), then the chain's objects, then each
+ * listener's handler, then the function each handler calls (a bound
+ * function's target, else null).
+ *
+ * Returns `[info, ...jQueryAndPreactHandlers, ...reactHandlers]`. `info` has the
+ * iframe element holding the element's document (`frame`), a framework
+ * label per chain entry (`roots`), per listener the handler's name, the
+ * identity and name of the function it calls (equal identities are the same
+ * function object) and, for jQuery's dispatcher, the jQuery handlers that
+ * run for the element, for Preact's event proxy the handler Preact runs
+ * (`preact`); then the React `on…` props that run for the
+ * element's events (`react`, see {@link REACT_HANDLERS_JS}). Their functions follow `info` in the same order.
+ * After {@link MAX_JQUERY_HANDLERS}, dispatchers stay unresolved and are
+ * counted in `jquerySkipped`; after {@link MAX_REACT_HANDLERS}, React props
+ * are counted in `reactSkipped`.
+ */
+export declare const ELEMENT_INFO_JS: string;
+/** What {@link ELEMENT_INFO_JS} reports, by value */
+export interface ElementInfo {
+    frame: string | null;
+    roots: Array<string | null>;
+    listeners: Array<{
+        name: string | null;
+        identity: number | null;
+        targetName: string | null;
+        jquery?: Array<{
+            type: string;
+            selector: string | null;
+            name: string;
+        }>;
+        /** The handler Preact runs from this listener (set when it is Preact's event proxy) */
+        preact?: {
+            name: string;
+        };
+    }>;
+    /** jQuery handlers left unresolved (over the limit) */
+    jquerySkipped: number;
+    /** React `on…` props that run for the element's events, nearest first */
+    react: Array<{
+        /** Position of the element the prop is on in the chain (0 = the inspected element); null outside it (a portal's React parent) */
+        position: number | null;
+        /** Description of that element when it is outside the chain */
+        node?: string;
+        /** Prop name, e.g. `onClickCapture` */
+        prop: string;
+        /** DOM event type, e.g. `click` */
+        type: string;
+        capture: boolean;
+        name: string;
+    }>;
+    /** React props left unresolved (over the limit) */
+    reactSkipped: number;
+}
+//# sourceMappingURL=listenerPageScripts.d.ts.map