browser-debugger-cli 0.8.0 → 0.10.0

package/dist/runtime/dom/actionEffectsScripts.js

@@ -0,0 +1,426 @@
+/**
+ * Page scripts behind the "what changed" part of DOM action results: one
+ * snapshot before the action ({@link EFFECTS_START_SCRIPT}) and one read after
+ * it ({@link EFFECTS_READ_SCRIPT}), plus the snapshot a hover takes of what
+ * is hidden around its target ({@link REVEAL_SNAPSHOT_JS}).
+ */
+import { ELEMENT_DESCRIPTION_JS } from './elementInfo.js';
+/** Class or id words that mark an element as a message (flash, toast, field error) */
+const MESSAGE_WORDS = [
+    'flash',
+    'alert',
+    'error',
+    'toast',
+    'notice',
+    'message',
+    'invalid',
+    'feedback',
+];
+/** Elements that show messages by role, plus a cheap prefilter for the class and id words */
+const MESSAGE_CANDIDATES = [
+    '[role="alert"]',
+    '[role="status"]',
+    '[aria-live]',
+    'output',
+    ...MESSAGE_WORDS.flatMap((word) => [`[class*="${word}" i]`, `[id*="${word}" i]`]),
+].join(', ');
+/** Class or id words that mark an element as a loading indicator */
+const LOADER_WORDS = ['loading', 'loader', 'spinner'];
+/** Loading indicators by state or role, plus a cheap prefilter for the class and id words */
+const LOADER_CANDIDATES = [
+    '[aria-busy="true"]',
+    '[role="progressbar"]',
+    ...['load', 'spinner'].flatMap((word) => [`[class*="${word}" i]`, `[id*="${word}" i]`]),
+].join(', ');
+/** Elements anywhere on the page a hover may show (tooltips, menus, popovers) */
+const REVEAL_GLOBAL_CANDIDATES = '[role="tooltip"], [role="menu"], [role="listbox"], [role="dialog"], [popover]';
+/** Elements a hover snapshot looks at, at most */
+const MAX_REVEAL_CANDIDATES = 1500;
+/** Time a hover snapshot may spend before it stops looking (ms) */
+const REVEAL_BUDGET_MS = 8;
+/**
+ * Containers that hold a target and the results of its key presses (a form,
+ * a search box, a dialog); without one, the target's grandparent is used
+ */
+const NEAR_CONTAINERS = 'form, [role="form"], [role="search"], dialog, [role="dialog"], [role="combobox"]';
+/** Added elements reported wherever they are: popups and messages */
+const POPUP_ROLES = /^(tooltip|menu|listbox|dialog|alert|alertdialog|status)$/;
+/** Messages kept per snapshot (after filtering) */
+const MAX_MESSAGES = 50;
+/** Time a message snapshot may spend before it stops looking (ms) */
+const MESSAGES_BUDGET_MS = 5;
+/** Time the list of shown elements may spend before it stops looking (ms) */
+const SHOWN_BUDGET_MS = 10;
+/** Shown elements a read returns at most */
+const MAX_SHOWN = 10;
+/** Added and removed elements a watch keeps */
+const MAX_TRACKED_NODES = 200;
+/** Longer texts are containers (a page, a form), not messages */
+const MAX_MESSAGE_TEXT = 300;
+/** How long a page keeps watching when no read or stop arrives (ms) */
+const MAX_WATCH_MS = 30000;
+/** Bursts of DOM changes a watch keeps (their times) */
+const MAX_BURSTS = 20;
+/**
+ * Page-side test whether an element is shown: rendered, not aria-hidden,
+ * not `visibility: hidden` and not fully transparent.
+ */
+const SHOWN_JS = `(el) => !el.closest('[aria-hidden="true"]') && el.getClientRects().length > 0 &&
+  (!el.checkVisibility || el.checkVisibility({ visibilityProperty: true, opacityProperty: true }))`;
+/**
+ * Page-side visible text of an element, whitespace collapsed: text in
+ * hidden elements, scripts and styles left out, and parts for which `skip`
+ * says so. Stops a little over {@link MAX_MESSAGE_TEXT} characters.
+ */
+const VISIBLE_TEXT_JS = `(el, skip) => {
+  let text = '';
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+  while (text.length <= ${MAX_MESSAGE_TEXT} && walker.nextNode()) {
+    const parent = walker.currentNode.parentElement;
+    if (!parent || /^(script|style|template|noscript)$/.test(parent.localName) || skip(parent)) continue;
+    if (parent.checkVisibility && !parent.checkVisibility({ visibilityProperty: true, opacityProperty: true })) continue;
+    text += ' ' + walker.currentNode.data;
+  }
+  return text.replace(/\\s+/g, ' ').trim();
+}`;
+/**
+ * Page-side test whether an element is part of a message's chrome rather
+ * than its text: aria-hidden parts, buttons, and elements whose class or
+ * aria-label names a close/dismiss control (`close`, `btn-close`, `close_x`;
+ * not `closeable`, `enclosed` or `disclosure`).
+ */
+export const MESSAGE_CHROME_JS = `(node) => {
+  const closer = /(^|[-_\\s])(close|dismiss)($|[-_\\s])/i;
+  return node.getAttribute('aria-hidden') === 'true' ||
+    /^(button|script|style|template)$/.test(node.localName) ||
+    node.getAttribute('role') === 'button' ||
+    closer.test(node.getAttribute('class') || '') ||
+    closer.test(node.getAttribute('aria-label') || '');
+}`;
+/**
+ * Page-side list of the messages a page shows: visible elements with an
+ * alert/status role, `aria-live`, `<output>`, or a class or id word from
+ * {@link MESSAGE_WORDS} (timers, marquees and progress bars left out), with
+ * their text (parts matching {@link MESSAGE_CHROME_JS}, such as the "×"
+ * close link, left out). Elements are filtered first, then the first
+ * {@link MAX_MESSAGES} kept, and the whole pass stops after
+ * {@link MESSAGES_BUDGET_MS}. Only the innermost of nested messages is kept,
+ * described by tag, id and classes (or its role when it has neither,
+ * `h3[role="alert"]`). Each element gets a number from `ids` that stays the
+ * same within the document, so a later snapshot can tell a new element from
+ * one that was there.
+ */
+const MESSAGES_JS = `(ids) => {
+  const deadline = performance.now() + ${MESSAGES_BUDGET_MS};
+  const description = ${ELEMENT_DESCRIPTION_JS};
+  const chrome = ${MESSAGE_CHROME_JS};
+  const shown = ${SHOWN_JS};
+  const visibleText = ${VISIBLE_TEXT_JS};
+  const describe = (el) => {
+    const text = description(el);
+    const role = el.getAttribute('role');
+    return text === el.localName && role ? text + '[role="' + role + '"]' : text;
+  };
+  const word = /\\b(${MESSAGE_WORDS.join('|')})\\b/i;
+  const named = (el) => !/^(timer|marquee|progressbar)$/.test(el.getAttribute('role') || '') &&
+    (el.matches('[role="alert"], [role="status"], [aria-live]:not([aria-live="off"]), output') ||
+      word.test(el.getAttribute('class') || '') || word.test(el.id || ''));
+  const inChrome = (node, el) => {
+    for (let n = node; n && n !== el; n = n.parentElement) if (chrome(n)) return true;
+    return false;
+  };
+  const found = [];
+  for (const el of document.querySelectorAll(${JSON.stringify(MESSAGE_CANDIDATES)})) {
+    if (found.length >= ${MAX_MESSAGES} || performance.now() > deadline) break;
+    if (!named(el) || !shown(el)) continue;
+    const text = visibleText(el, (node) => inChrome(node, el));
+    if (text !== '' && text.length <= ${MAX_MESSAGE_TEXT}) found.push({ el: el, text: text });
+  }
+  return found
+    .filter((m) => !found.some((other) => other !== m && m.el.contains(other.el)))
+    .map((m) => {
+      let id = ids.map.get(m.el);
+      if (id === undefined) {
+        id = ids.next++;
+        ids.map.set(m.el, id);
+      }
+      return { id: id, text: m.text, element: describe(m.el) };
+    });
+}`;
+/**
+ * Page-side list of the loading indicators shown: elements with
+ * `aria-busy="true"`, a progressbar role, or a class or id word from
+ * {@link LOADER_WORDS} (`is-loading`, `spinner`; not `lazyloading`).
+ */
+const LOADERS_JS = `() => {
+  const shown = ${SHOWN_JS};
+  const word = /\\b(${LOADER_WORDS.join('|')})\\b/i;
+  const loader = (el) => el.getAttribute('aria-busy') === 'true' || el.getAttribute('role') === 'progressbar' ||
+    word.test(el.getAttribute('class') || '') || word.test(el.id || '');
+  return Array.from(document.querySelectorAll(${JSON.stringify(LOADER_CANDIDATES)})).filter((el) => loader(el) && shown(el));
+}`;
+/**
+ * Page-side snapshot a hover takes right before the mouse moves (called by
+ * the click script with the hovered element): the elements around it (its
+ * parent and everything in it) and the tooltips, menus, listboxes, dialogs
+ * and popovers anywhere on the page that are hidden, at most
+ * {@link MAX_REVEAL_CANDIDATES} looked at within {@link REVEAL_BUDGET_MS}.
+ * They are kept by identity in the action's watch, so its read can tell
+ * which of them the hover revealed, also through CSS `:hover` rules that
+ * change no DOM, and elements moving in the page can't pass for revealed
+ * ones. Does nothing without a running watch (another frame).
+ */
+export const REVEAL_SNAPSHOT_JS = `(el) => {
+  const state = window.__bdgEffects;
+  if (!state || state.stopped) return;
+  const deadline = performance.now() + ${REVEAL_BUDGET_MS};
+  const shown = ${SHOWN_JS};
+  const parent = el.parentElement;
+  const scope = parent && !/^(body|html)$/.test(parent.localName) ? parent : el;
+  const hidden = [];
+  let looked = 0;
+  const room = () => looked < ${MAX_REVEAL_CANDIDATES} && performance.now() <= deadline;
+  const look = (candidate) => {
+    looked++;
+    if (!shown(candidate)) hidden.push(candidate);
+  };
+  for (const candidate of document.querySelectorAll(${JSON.stringify(REVEAL_GLOBAL_CANDIDATES)})) {
+    if (!room()) break;
+    look(candidate);
+  }
+  const walker = document.createTreeWalker(scope, NodeFilter.SHOW_ELEMENT);
+  for (let node = scope; node && room(); node = walker.nextNode()) look(node);
+  state.reveal = { target: el, hidden: hidden };
+}`;
+/**
+ * Page-side container whose added elements count as an action's result:
+ * the target's form, search box, dialog or combobox, else its grandparent
+ * (its parent when the grandparent is the body).
+ */
+const NEAR_SCOPE_JS = `(target) => {
+  const container = target.closest(${JSON.stringify(NEAR_CONTAINERS)});
+  if (container) return container;
+  const parent = target.parentElement || target;
+  const grandparent = parent.parentElement;
+  return grandparent && !/^(body|html)$/.test(grandparent.localName) ? grandparent : parent;
+}`;
+/**
+ * Page-side list of the elements an action showed: elements added during
+ * the watch inside the target's container ({@link NEAR_SCOPE_JS}) or, anywhere,
+ * popups and messages (tooltip, menu, listbox, dialog, alert and status
+ * roles, `aria-live`, message-like classes), plus, after a hover, the
+ * elements hidden before it that are shown now ({@link REVEAL_SNAPSHOT_JS}).
+ * Background widgets elsewhere on the page do not count. Only shown ones
+ * with visible text count, the outermost of nested ones, and not those
+ * whose text a removed element had (a re-render). At most
+ * {@link MAX_SHOWN}, within {@link SHOWN_BUDGET_MS}.
+ */
+export const SHOWN_ELEMENTS_JS = `(state) => {
+  const deadline = performance.now() + ${SHOWN_BUDGET_MS};
+  const describe = ${ELEMENT_DESCRIPTION_JS};
+  const shown = ${SHOWN_JS};
+  const visibleText = ${VISIBLE_TEXT_JS};
+  const word = /\\b(${MESSAGE_WORDS.join('|')})\\b/i;
+  const target = state.reveal ? state.reveal.target : state.keyTarget;
+  const scope = target && target.isConnected ? (${NEAR_SCOPE_JS})(target) : null;
+  const popup = (el) => ${POPUP_ROLES}.test(el.getAttribute('role') || '') || el.hasAttribute('popover') ||
+    (el.hasAttribute('aria-live') && el.getAttribute('aria-live') !== 'off') ||
+    word.test(el.getAttribute('class') || '') || word.test(el.id || '');
+  const near = (el) => (scope !== null && scope.contains(el)) || popup(el);
+  const contentOf = (node) => (node.textContent || '').replace(/\\s+/g, ' ').trim();
+  const removed = new Set(state.removed.map(contentOf));
+  const candidates = new Set(state.added.filter((node) => node.isConnected && near(node)));
+  if (state.reveal) for (const el of state.reveal.hidden) if (el.isConnected) candidates.add(el);
+  const found = [];
+  for (const el of candidates) {
+    if (performance.now() > deadline) break;
+    if (!shown(el) || removed.has(contentOf(el))) continue;
+    const text = visibleText(el, () => false);
+    if (text !== '') found.push({ el: el, text: text });
+  }
+  return found
+    .filter((m) => !found.some((other) => other !== m && other.el.contains(m.el)))
+    .slice(0, ${MAX_SHOWN})
+    .map((m) => ({ text: m.text, element: describe(m.el) }));
+}`;
+/**
+ * Page-side test whether a mutation is only focus/hover churn: a class
+ * change on an element the action's events hit (`targets`) that only adds
+ * or removes classes containing "focus" or "hover".
+ */
+export const CHURN_ONLY_JS = `(record, targets) => {
+  if (record.type !== 'attributes' || record.attributeName !== 'class' || !targets.has(record.target)) return false;
+  const tokens = (text) => new Set((text || '').split(/\\s+/).filter(Boolean));
+  const before = tokens(record.oldValue);
+  const after = tokens(record.target.getAttribute('class'));
+  const changed = [...before].filter((c) => !after.has(c)).concat([...after].filter((c) => !before.has(c)));
+  return changed.every((c) => /focus|hover/i.test(c));
+}`;
+/**
+ * Page-side test whether a mutation changes the page's structure or state
+ * rather than only animating it: elements added or removed, or an attribute
+ * other than `style` changed. Text-only changes (clocks, counters) and style
+ * changes (script-driven animations) do not count.
+ */
+export const STRUCTURAL_CHANGE_JS = `(record) => {
+  if (record.type === 'attributes') return record.attributeName !== 'style';
+  if (record.type !== 'childList') return false;
+  const element = (node) => node.nodeType === 1;
+  return Array.from(record.addedNodes).some(element) || Array.from(record.removedNodes).some(element);
+}`;
+/**
+ * Page-side reason why "no effect" can't be claimed even without DOM
+ * changes, or undefined: `clipboard` (a copy or cut happened), `no-event`
+ * (no event reached the page), `control` (form controls, labels, media,
+ * frames, popover/command buttons: their effect needs no DOM change),
+ * `new-window` (download or `target` links), `external-link` (mailto:, tel:,
+ * javascript: and other non-http links), `closed-shadow` (a custom element
+ * whose inside is not observed) or `focus` (focus moved to an element that
+ * may reveal content with CSS).
+ */
+export const UNCERTAIN_JS = `(state, active) => {
+  if (state.copied) return 'clipboard';
+  if (state.targets.size === 0) return 'no-event';
+  const controls = /^(input|select|textarea|option|label|canvas|video|audio|iframe|embed|object)$/;
+  for (const node of state.path) {
+    if (controls.test(node.localName) || node.isContentEditable) return 'control';
+    if (node.hasAttribute('popovertarget') || node.hasAttribute('commandfor')) return 'control';
+    if (node.localName === 'a' && node.hasAttribute('href')) {
+      if (node.hasAttribute('download') || (node.target && node.target !== '_self')) return 'new-window';
+      if (!/^https?:$/.test(node.protocol)) return 'external-link';
+    }
+  }
+  for (const node of state.targets) if (node.localName.includes('-') && !node.shadowRoot) return 'closed-shadow';
+  const plain = (node) => /^(body|button|summary)$/.test(node.localName) ||
+    (node.localName === 'a' && node.hasAttribute('href')) ||
+    (node.localName === 'input' && /^(button|submit|reset)$/i.test(node.type || ''));
+  if (active && active !== state.focus && !plain(active)) return 'focus';
+  return undefined;
+}`;
+/**
+ * Page-side signs, at a read, that the page is still working on the
+ * action's result: how long ago each recent burst of DOM changes was (ms,
+ * newest last), and a loading indicator shown since the start (described).
+ */
+const SETTLE_JS = `(state) => {
+  const now = performance.now();
+  const describe = ${ELEMENT_DESCRIPTION_JS};
+  const loader = (${LOADERS_JS})().find((el) => !state.loaders.has(el));
+  return {
+    burstAges: state.bursts.map((time) => Math.round(now - time)),
+    loading: loader ? describe(loader) : null
+  };
+}`;
+/**
+ * Snapshot before an action, left in `window.__bdgEffects`: the messages
+ * and loading indicators shown, and a MutationObserver (on the document,
+ * its open shadow roots and any shadow root attached while watching, which
+ * also counts as a change) counting changes other than
+ * {@link CHURN_ONLY_JS}, keeping the elements added and removed and the
+ * times of {@link STRUCTURAL_CHANGE_JS} bursts. Capture listeners record
+ * which elements the action's events reached, the first key press's target,
+ * copy/cut events and the scroll position at the first press (a click
+ * scrolls its target into view first). The watch stops itself after
+ * {@link MAX_WATCH_MS}, so a snapshot that ran late (after a navigation,
+ * with nobody reading it) leaves nothing behind. Evaluates to the URL and
+ * the messages.
+ */
+export const EFFECTS_START_SCRIPT = `(() => {
+  if (window.__bdgEffects) window.__bdgEffects.stop();
+  const churnOnly = ${CHURN_ONLY_JS};
+  const structural = ${STRUCTURAL_CHANGE_JS};
+  const ids = { map: new WeakMap(), next: 1 };
+  const state = {
+    ids: ids, changes: 0, targets: new Set(), path: new Set(), focus: document.activeElement,
+    pressScroll: null, copied: false, stopped: false, added: [], removed: [], bursts: [],
+    keyTarget: null, loaders: new Set((${LOADERS_JS})())
+  };
+  const keep = (list, nodes) => {
+    for (const node of nodes) if (node.nodeType === 1 && list.length < ${MAX_TRACKED_NODES}) list.push(node);
+  };
+  const count = (records) => {
+    let burst = false;
+    for (const record of records) {
+      if (churnOnly(record, state.targets)) continue;
+      state.changes++;
+      burst = burst || structural(record);
+      if (record.type === 'childList') {
+        keep(state.added, record.addedNodes);
+        keep(state.removed, record.removedNodes);
+      }
+    }
+    if (!burst) return;
+    state.bursts.push(performance.now());
+    if (state.bursts.length > ${MAX_BURSTS}) state.bursts.shift();
+  };
+  const observer = new MutationObserver(count);
+  const options = { subtree: true, childList: true, characterData: true, attributes: true, attributeOldValue: true };
+  const observe = (root) => {
+    observer.observe(root, options);
+    for (const el of root.querySelectorAll('*')) if (el.shadowRoot) observe(el.shadowRoot);
+  };
+  observe(document);
+  const attachShadow = Element.prototype.attachShadow;
+  const watchedAttach = function (init) {
+    const root = attachShadow.call(this, init);
+    state.changes++;
+    observer.observe(root, options);
+    return root;
+  };
+  Element.prototype.attachShadow = watchedAttach;
+  const types = ['pointerdown', 'mousedown', 'click', 'keydown', 'focusin', 'submit', 'mouseover', 'input', 'change', 'copy', 'cut'];
+  const pressTypes = ['pointerdown', 'mousedown', 'click', 'keydown', 'submit'];
+  const record = (event) => {
+    if (event.type === 'copy' || event.type === 'cut') state.copied = true;
+    const path = event.composedPath().filter((node) => node.nodeType === 1);
+    if (path[0]) state.targets.add(path[0]);
+    if (path[0] && !state.keyTarget && event.type === 'keydown') state.keyTarget = path[0];
+    path.forEach((node) => state.path.add(node));
+    if (!state.pressScroll && pressTypes.includes(event.type)) state.pressScroll = [scrollX, scrollY];
+  };
+  types.forEach((type) => window.addEventListener(type, record, true));
+  state.flush = () => count(observer.takeRecords());
+  state.stop = () => {
+    if (state.stopped) return;
+    state.stopped = true;
+    clearTimeout(expiry);
+    observer.disconnect();
+    if (Element.prototype.attachShadow === watchedAttach) Element.prototype.attachShadow = attachShadow;
+    types.forEach((type) => window.removeEventListener(type, record, true));
+  };
+  const expiry = setTimeout(state.stop, ${MAX_WATCH_MS});
+  window.__bdgEffects = state;
+  return { href: location.href, messages: (${MESSAGES_JS})(ids) };
+})()`;
+/**
+ * Read after an action, called with `(stop, shown)`: `stop` also stops
+ * watching, `shown` lists the elements the action showed
+ * ({@link SHOWN_ELEMENTS_JS}). Returns the URL, the messages shown and,
+ * when the snapshot is still there (same document), the number of changes
+ * counted (plus one when the page scrolled after the press), why "no
+ * effect" could not be claimed ({@link UNCERTAIN_JS}) and whether the page
+ * is still working ({@link SETTLE_JS}). `fresh` means a new document
+ * (everything shown is new).
+ */
+export const EFFECTS_READ_SCRIPT = `((stop, shown) => {
+  const state = window.__bdgEffects;
+  if (!state) return { href: location.href, fresh: true, messages: (${MESSAGES_JS})({ map: new WeakMap(), next: 1 }) };
+  if (!state.stopped) state.flush();
+  if (stop) {
+    state.stop();
+    delete window.__bdgEffects;
+  }
+  const scrolled = state.pressScroll !== null && (state.pressScroll[0] !== scrollX || state.pressScroll[1] !== scrollY);
+  return {
+    href: location.href,
+    fresh: false,
+    changes: state.changes + (scrolled ? 1 : 0),
+    uncertain: (${UNCERTAIN_JS})(state, document.activeElement),
+    messages: (${MESSAGES_JS})(state.ids),
+    settle: (${SETTLE_JS})(state),
+    shown: shown ? (${SHOWN_ELEMENTS_JS})(state) : undefined
+  };
+})`;
+/** Stops the watch {@link EFFECTS_START_SCRIPT} left (when no read stopped it) */
+export const EFFECTS_STOP_SCRIPT = 'if (window.__bdgEffects) { window.__bdgEffects.stop(); delete window.__bdgEffects; }';
+//# sourceMappingURL=actionEffectsScripts.js.map

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

@@ -0,0 +1,170 @@
+/**
+ * Where elements are relative to the viewport of the top-level page.
+ *
+ * The page-side scripts measure an element in top-level viewport coordinates
+ * (adding the offsets of the same-origin iframes it is in) together with what
+ * clips it: the viewports of those iframes and ancestors that cut off
+ * overflowing content (scroll containers, `overflow: hidden`). Classifying the
+ * measurements is done here, outside the page, so `dom query` and `dom layout`
+ * agree and the rules can be tested without a browser.
+ */
+import type { LayoutBox, LayoutPoint, LayoutSize } from '../../ipc/protocol/domTypes.js';
+import type { ViewportPosition } from '../../types.js';
+/** Measurements of one element ({@link ELEMENT_GEOMETRY_JS}). */
+export interface ElementGeometry {
+    /** Border box in top-level viewport coordinates */
+    rect: LayoutBox;
+    /** Area its iframes and overflow-clipping ancestors leave visible, in the same coordinates */
+    clip: LayoutBox | null;
+    /** Whether overlay scrollbars of the clipping containers show along the clip's right and bottom edges */
+    clipOverlay: OverlayEdges;
+    /** Innermost ancestor or iframe cutting off part of it, e.g. `ul#list` */
+    clipper: string | null;
+    /** Why it cannot be seen regardless of position, e.g. `display: none`, `clipped by div#acc: zero height` */
+    hidden: string | null;
+    /**
+     * Why it cannot be seen although it is rendered ({@link INVISIBLE_REASON_JS}),
+     * e.g. `opacity: 0 on div#menu`
+     */
+    invisible: string | null;
+    /** Inside an `inert` element: shown, but not interactive */
+    inert: boolean;
+    /** Fixed to the top-level viewport (it or a container is `position: fixed`): page scroll does not move it */
+    fixed: boolean;
+    /** It or an ancestor is `position: sticky`: page scroll moves it only until it sticks */
+    sticky?: boolean;
+    /** How far the top-level page can scroll from where it is now */
+    pageScroll: ScrollRange;
+    /**
+     * Why the top-level page cannot scroll although content is below the fold
+     * ({@link SCROLL_LOCK_JS}); null when it is not locked
+     */
+    scrollLock?: ScrollLock | null;
+    /** Offset of its document's viewport within the top-level viewport (iframes) */
+    offset: LayoutPoint;
+}
+/** What keeps the top-level page from scrolling ({@link SCROLL_LOCK_JS}). */
+export interface ScrollLock {
+    /** The styles locking it, e.g. `position: fixed, overflow: hidden on body` */
+    by: string;
+    /** A visible dialog that is likely the reason, e.g. `div#consent`; null when there is none */
+    dialog: string | null;
+}
+/** Edges of a viewport or clip along which overlay scrollbars (that take no space) show after a scroll. */
+export interface OverlayEdges {
+    right: boolean;
+    bottom: boolean;
+}
+/** Distances (CSS px, never negative) a page can scroll in each direction. */
+export interface ScrollRange {
+    left: number;
+    up: number;
+    right: number;
+    down: number;
+}
+/** How an element relates to the viewport ({@link classifyViewportPosition}). */
+export interface ViewportPlacement {
+    inViewport: ViewportPosition;
+    /** Share in view (1-99), for `partly` */
+    percentVisible?: number;
+    /** Why it is `hidden` */
+    hiddenReason?: string;
+    /**
+     * Page scroll that brings it fully into view, when the page can scroll there:
+     * the smallest one for an element partly in view, centring it for one out of view
+     */
+    scrollBy?: LayoutPoint;
+    /** Ancestor or iframe cutting it off (page scroll alone does not show it) */
+    clippedBy?: string;
+    /** Why page scroll cannot bring it fully into view ({@link OFF_SCREEN_REASONS}) */
+    offScreenReason?: string;
+}
+/** Why page scroll cannot bring an element that is not fully in view into view. */
+export declare const OFF_SCREEN_REASONS: {
+    readonly fixed: "fixed position, page scroll does not move it";
+    readonly sticky: "sticky position, page scroll moves it only until it sticks";
+    readonly outOfRange: "beyond the page's scroll range";
+};
+/**
+ * Page-side size of a window's viewport without scrollbars (the window size
+ * for quirks-mode documents, whose root element is as large as the content).
+ */
+export declare const VIEWPORT_SIZE_JS = "(view) => {\n  const root = view.document.documentElement;\n  const standards = view.document.compatMode === 'CSS1Compat' && root;\n  return {\n    width: standards ? root.clientWidth : view.innerWidth,\n    height: standards ? root.clientHeight : view.innerHeight\n  };\n}";
+/**
+ * Page-side distances a window's page can scroll in each direction from its
+ * current position. Right-to-left pages scroll to negative `scrollX`. Content
+ * that a scrolling body cuts off is reported through the body as a clipper.
+ */
+export declare const SCROLL_RANGE_JS = "(view) => {\n  const doc = view.document;\n  const scroller = doc.scrollingElement || doc.documentElement;\n  const maxX = Math.max(0, scroller.scrollWidth - scroller.clientWidth);\n  const maxY = Math.max(0, scroller.scrollHeight - scroller.clientHeight);\n  const rtl = view.scrollX < 0 || view.getComputedStyle(doc.documentElement).direction === 'rtl';\n  const left = rtl ? maxX + view.scrollX : view.scrollX;\n  return { left: Math.max(0, left), up: Math.max(0, view.scrollY), right: Math.max(0, maxX - left), down: Math.max(0, maxY - view.scrollY) };\n}";
+/**
+ * Page-side offset of an iframe's content (inside its border and padding)
+ * within the viewport of the document holding the iframe.
+ */
+export declare const FRAME_OFFSET_JS = "(frame) => {\n  const rect = frame.getBoundingClientRect();\n  const style = frame.ownerDocument.defaultView.getComputedStyle(frame);\n  return {\n    x: rect.left + frame.clientLeft + parseFloat(style.paddingLeft),\n    y: rect.top + frame.clientTop + parseFloat(style.paddingTop)\n  };\n}";
+/**
+ * Page-side test of computed styles: true when they only scale or move the
+ * box (no `rotate`, and a 2D `transform` matrix without rotation or skew), so
+ * its bounding box is the box itself, scaled.
+ */
+export declare const SCALES_ONLY_JS = "(style) => {\n  if (style.rotate && style.rotate !== 'none') return false;\n  if (!style.transform || style.transform === 'none') return true;\n  const matrix = /^matrix\\(([^)]*)\\)$/.exec(style.transform);\n  if (!matrix) return false;\n  const values = matrix[1].split(',').map(parseFloat);\n  return Math.abs(values[1]) < 1e-6 && Math.abs(values[2]) < 1e-6;\n}";
+/** Page-side test of a `clip-path` that cuts everything away: `inset()` with percentages leaving no area. */
+export declare const CLIP_PATH_CUTS_ALL_JS = "(clipPath) => {\n  const inset = /^inset\\(([^)]*)\\)/.exec(clipPath || '');\n  const values = inset ? inset[1].split(' round ')[0].trim().split(/\\s+/) : [];\n  if (values.length === 0 || values.some((v) => !/%$/.test(v))) return false;\n  const [top, right = top, bottom = top, left = right] = values.map(parseFloat);\n  return top + bottom >= 100 || left + right >= 100;\n}";
+/**
+ * Page-side test of a `clip` that cuts everything away: `rect()` with no area
+ * on an absolutely positioned or fixed element (the "visually hidden"
+ * pattern; `clip` applies to no other element).
+ */
+export declare const CLIP_RECT_CUTS_ALL_JS = "(position, clip) => {\n  if ((position !== 'absolute' && position !== 'fixed') || !/^rect\\(/.test(clip || '')) return false;\n  const edges = (clip.match(/-?[\\d.]+/g) || []).map(Number);\n  return edges.length === 4 && (edges[1] <= edges[3] || edges[2] <= edges[0]);\n}";
+/**
+ * Page-side measurement of an element ({@link ElementGeometry}): its box in
+ * top-level viewport coordinates, its clip by ancestors
+ * ({@link ANCESTOR_CLIP_JS}) and by the viewports of its iframes, why it
+ * cannot be seen at all (not rendered, or inside a clipping container
+ * collapsed to zero size), why a rendered one is still invisible
+ * ({@link INVISIBLE_REASON_JS}), whether it is inert (an `inert` element
+ * around it, through shadow roots) or fixed to the top-level viewport, and how
+ * far the top-level page can scroll ({@link SCROLL_RANGE_JS}) or what locks
+ * its scrolling ({@link SCROLL_LOCK_JS}). Content of a body fixed to lock the
+ * page is not counted as fixed: it is in-flow content the lock holds in place.
+ *
+ * Rendering is decided by `checkVisibility()`, so content Chrome skips
+ * (inside a closed `<details>`, under `content-visibility: hidden`) is hidden
+ * although it still has a box. Content skipped by `content-visibility: auto`
+ * is not: it is rendered once scrolled near the viewport.
+ */
+export declare const ELEMENT_GEOMETRY_JS: string;
+/**
+ * How a scroll brings an element into view: `centre` it (an element out of
+ * view, like `bdg dom scroll <selector>`, so sticky headers and fixed footers
+ * at the edges do not cover it), or the `minimal` scroll that shows all of
+ * it (an element partly in view: the part cut off at one edge).
+ */
+export type ScrollAim = 'centre' | 'minimal';
+/**
+ * Where along one axis a scroll should bring a span's start (in the current
+ * viewport coordinates): centred, or just inside the edge cutting it off; a
+ * span larger than the viewport gets its start aligned either way.
+ *
+ * @param start - Start of the span in viewport coordinates
+ * @param size - Length of the span
+ * @param viewSize - Length of the viewport
+ * @param aim - Centre it, or the smallest scroll showing all of it
+ * @returns Scroll that would do it (negative: back), before limiting it to the page
+ */
+export declare function scrollTarget(start: number, size: number, viewSize: number, aim: ScrollAim): number;
+/**
+ * Classify where an element is relative to the top-level viewport.
+ *
+ * Visible parts are what lies inside the viewport and the element's clip
+ * (iframes, overflow containers). An element with no visible part is `above`,
+ * `below`, `left` or `right` of the viewport (or of its clip, e.g. scrolled
+ * out of a list), and `hidden` when it is not rendered at all. Being inert
+ * does not change the position: inert elements are shown.
+ *
+ * @param geometry - Page-side measurements
+ * @param viewport - Top-level viewport size
+ * @returns Position, with the visible share, hidden reason, clipping
+ *   ancestor or page scroll when relevant
+ */
+export declare function classifyViewportPosition(geometry: ElementGeometry, viewport: LayoutSize): ViewportPlacement;
+//# sourceMappingURL=elementGeometry.d.ts.map