browser-debugger-cli 0.11.0 → 0.13.0

package/dist/runtime/dom/auditScripts.js

@@ -0,0 +1,148 @@
+/**
+ * Page-side part of `bdg dom audit`: one walk over the rendered elements of
+ * the page (open shadow roots and the light DOM slotted into them, at most
+ * {@link AUDIT_ELEMENT_CAP}; nothing inside a fixed element counts as making
+ * the page wider; SVG images and placeholders of 2px or less are skipped)
+ * that collects what each check needs. Colors and contrast are computed in
+ * the daemon ({@link buildAudit}), the same way `dom inspect` computes them.
+ */
+import { LABEL_CLASSES_JS } from './elementInfo.js';
+import { FLAT_TREE_JS, HIT_EVERYTHING_JS, PAINT_RISKS_JS, } from './inspectScripts.js';
+import { AUDIT_OUT_OF_VIEW_RISK } from '../../ui/messages/commands.js';
+/** Elements the walk looks at, at most */
+export const AUDIT_ELEMENT_CAP = 20000;
+/**
+ * Page-side audit walk. Arguments: the checks to collect for
+ * (`contrast`, `overflow`, `layers`, `animations`).
+ */
+export const AUDIT_PAGE_JS = `function (checks) {
+  const want = (name) => checks.includes(name);
+  const doc = document;
+  const view = window;
+  const style = (n) => view.getComputedStyle(n);
+  const scroller = doc.scrollingElement || doc.documentElement;
+  const viewport = { width: doc.documentElement.clientWidth, height: view.innerHeight };
+  const firstClass = (n) => (${LABEL_CLASSES_JS})(n)[0];
+  const label = (n) => n.localName + (n.id ? '#' + n.id : firstClass(n) ? '.' + firstClass(n) : '');
+  const parentOf = (n) => n.assignedSlot || n.parentElement || (n.parentNode && n.parentNode.host) || null;
+  const short = (text) => text.replace(/\\s+/g, ' ').trim().slice(0, 60);
+  const ownText = (n) => Array.from(n.childNodes).filter((c) => c.nodeType === 3).map((c) => c.data).join(' ').replace(/\\s+/g, ' ').trim();
+  const inView = (r) => r.bottom > 0 && r.right > 0 && r.top < viewport.height && r.left < viewport.width;
+  const meta = doc.querySelector('meta[name="color-scheme"]');
+  const rootScheme = style(doc.documentElement).colorScheme;
+  const scheme = rootScheme && rootScheme !== 'normal' ? rootScheme : (meta && meta.content) || '';
+  const canvasDark = /dark/.test(scheme) && (!/light/.test(scheme) || view.matchMedia('(prefers-color-scheme: dark)').matches);
+  const result = { viewport: viewport, pixelRatio: view.devicePixelRatio || 1, pageWidth: scroller.scrollWidth, canvasDark: canvasDark, walked: 0, capped: false };
+  const texts = [], wide = [], truncated = [], images = [], layers = [], scrollers = [];
+  let canvases = 0;
+  const tree = (${FLAT_TREE_JS})(view);
+  const paintRisks = ${PAINT_RISKS_JS};
+  const clear = (color) => color === 'transparent' || /^rgba\\(.*,\\s*0\\)$/.test(color) || /\\/\\s*0\\)$/.test(color);
+  const chainOf = (n) => {
+    const backgrounds = [];
+    const risks = [];
+    let opacity = 1;
+    let painted = false;
+    let solid = false;
+    for (let p = n; p && backgrounds.length < 60; p = parentOf(p)) {
+      const s = style(p);
+      const own = Number(s.opacity) || 0;
+      const background = { color: s.backgroundColor, image: s.backgroundImage !== 'none' };
+      backgrounds.push(own < 1 ? Object.assign(background, { opacity: own }) : background);
+      opacity *= own;
+      if (p !== doc.documentElement && p !== doc.body && (background.image || !clear(s.backgroundColor))) painted = true;
+      if (p !== doc.documentElement && p !== doc.body && !background.image && /^rgb\\(/.test(s.backgroundColor)) solid = true;
+      if (s.mixBlendMode !== 'normal') risks.push('mix-blend-mode ' + s.mixBlendMode + ' on ' + label(p));
+      if (s.filter !== 'none') risks.push('filter on ' + label(p));
+    }
+    return { backgrounds: backgrounds, risks: risks, opacity: opacity, painted: painted, solid: solid };
+  };
+  const unhit = [];
+  const painters = [];
+  const markPaintedBehind = () => {
+    for (const text of unhit) {
+      const painter = painters.find((p) => p.el !== text.el && !p.el.contains(text.el) && !text.el.contains(p.el) &&
+        text.x >= p.left && text.x <= p.right && text.y >= p.top && text.y <= p.bottom);
+      if (painter && !text.entry.risks.includes(${JSON.stringify(AUDIT_OUT_OF_VIEW_RISK)})) text.entry.risks.push(label(painter.el) + ' under or over it (out of view, not hit-tested)');
+    }
+  };
+  const risksOf = (n, slot, chain, shown) => {
+    if (!shown) return chain.painted ? chain.risks : chain.risks.concat(${JSON.stringify(AUDIT_OUT_OF_VIEW_RISK)});
+    const text = slot && n.assignedNodes({ flatten: true }).find((c) => c.nodeType === 3 && c.data.trim() !== '');
+    return paintRisks(n, tree, text ? text.parentElement || n : n);
+  };
+  const visit = (n, fixed) => {
+    if (result.walked >= ${AUDIT_ELEMENT_CAP}) { result.capped = true; return; }
+    if (/^(script|style|template|noscript|head|meta|link|title)$/.test(n.localName)) return;
+    const s = style(n);
+    if (s.display === 'none') return;
+    result.walked++;
+    const inFixed = fixed || s.position === 'fixed';
+    const kids = n.shadowRoot ? [...Array.from(n.shadowRoot.children), ...Array.from(n.children)] : Array.from(n.children);
+    const slot = n.localName === 'slot';
+    const box = slot && parentOf(n) ? parentOf(n) : n;
+    const r = box.getBoundingClientRect();
+    const shown = r.width > 0 && r.height > 0 && s.visibility === 'visible';
+    const gradientText = /rgba\\(0, 0, 0, 0\\)|transparent/.test(s.webkitTextFillColor);
+    if (shown && want('contrast') && !gradientText) {
+      const text = slot ? short(n.assignedNodes({ flatten: true }).filter((c) => c.nodeType === 3).map((c) => c.data).join(' ')) : n.shadowRoot ? '' : ownText(n);
+      if (text && Number(s.opacity) > 0 && r.width > 2 && r.height > 2) {
+        const chain = chainOf(n);
+        const seen = inView(r);
+        if (chain.opacity > 0) {
+          texts.push({ label: label(n), text: short(text), color: s.color, fontSize: s.fontSize, fontWeight: s.fontWeight, inView: seen, backgrounds: chain.backgrounds, opacity: chain.opacity, risks: risksOf(n, slot, chain, seen) });
+          if (!seen && !chain.solid) unhit.push({ entry: texts[texts.length - 1], el: box, x: (r.left + r.right) / 2 + view.scrollX, y: (r.top + r.bottom) / 2 + view.scrollY });
+        }
+      }
+    }
+    if (shown && want('contrast') && (/^(img|video|canvas|picture|iframe)$/.test(n.localName) || s.backgroundImage !== 'none')) {
+      painters.push({ el: n, left: r.left + view.scrollX, top: r.top + view.scrollY, right: r.right + view.scrollX, bottom: r.bottom + view.scrollY });
+    }
+    if (shown && want('overflow')) {
+      if (r.right > viewport.width + 1 && !inFixed) wide.push({ label: label(n), right: r.right + view.scrollX, width: r.width });
+      const cut = s.overflowX !== 'visible' && n.scrollWidth > n.clientWidth + 1 ? (s.textOverflow === 'ellipsis' ? 'ellipsis' : 'clip')
+        : s.webkitLineClamp !== 'none' && n.scrollHeight > n.clientHeight + 1 ? 'clamp' : null;
+      const textContent = cut && short(n.innerText || '');
+      const visuallyHidden = r.width <= 2 || r.height <= 2;
+      if (cut && textContent && !visuallyHidden) truncated.push({ label: label(n), text: textContent, kind: cut });
+      const vector = /\\.svg([?#]|$)|^data:image\\/svg/i.test(n.currentSrc || '');
+      if (n.localName === 'img' && n.naturalWidth > 2 && n.naturalHeight > 2 && n.complete && !vector) images.push({ label: label(n), natural: { w: n.naturalWidth, h: n.naturalHeight }, rendered: { w: r.width, h: r.height }, objectFit: s.objectFit });
+    }
+    if (shown && want('overflow') && /^(auto|scroll)$/.test(s.overflowX) && n !== doc.documentElement && n !== doc.body && n.scrollWidth > n.clientWidth + 1) {
+      scrollers.push({ label: label(n), scrollWidth: n.scrollWidth, width: n.clientWidth });
+    }
+    if (want('animations') && shown && n.localName === 'canvas') canvases++;
+    if (want('layers') && shown && (s.position === 'fixed' || s.position === 'sticky')) {
+      layers.push({ label: label(n), position: s.position, zIndex: s.zIndex, rect: { x: r.left, y: r.top, w: r.width, h: r.height }, inView: inView(r) });
+    }
+    if (s.overflowX !== 'visible' && s.overflowX !== 'clip' && n !== doc.documentElement && n !== doc.body) {
+      const wideBefore = wide.length;
+      for (const c of kids) visit(c, inFixed);
+      wide.length = wideBefore;
+      return;
+    }
+    for (const c of kids) visit(c, inFixed);
+  };
+  (${HIT_EVERYTHING_JS})([doc], () => visit(doc.documentElement, false));
+  markPaintedBehind();
+  if (want('contrast')) result.texts = texts;
+  if (want('overflow')) Object.assign(result, { wide: wide, truncated: truncated, images: images, scrollers: scrollers });
+  if (want('layers')) result.layers = layers;
+  if (want('animations')) {
+    result.canvases = canvases;
+    result.animations = doc.getAnimations().filter((a) => a.playState === 'running').slice(0, 200).map((a) => {
+      const timing = a.effect && a.effect.getTiming ? a.effect.getTiming() : {};
+      const target = a.effect && a.effect.target;
+      return {
+        label: target && target.localName ? label(target) : '(none)',
+        name: a.animationName || a.transitionProperty || a.id || 'animation',
+        type: a.constructor.name,
+        duration: typeof timing.duration === 'number' ? timing.duration : String(timing.duration),
+        iterations: timing.iterations === Infinity ? 'infinite' : timing.iterations,
+        scrollDriven: Boolean(a.timeline) && a.timeline !== doc.timeline
+      };
+    });
+  }
+  return result;
+}`;
+//# sourceMappingURL=auditScripts.js.map

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

@@ -14,6 +14,13 @@ import type { ViewportPosition } from '../../types.js';
 export interface ElementGeometry {
     /** Border box in top-level viewport coordinates */
     rect: LayoutBox;
+    /**
+     * For a zero-size element whose children show (an inline list around
+     * floated items, a `display: contents` web component whose shadow root
+     * shows a dialog): the box around those children in the flat tree, which
+     * is what can be seen of it
+     */
+    content?: LayoutBox | null;
     /** 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 */
@@ -27,6 +34,11 @@ export interface ElementGeometry {
      * e.g. `opacity: 0 on div#menu`
      */
     invisible: string | null;
+    /**
+     * Masked by `mask-image` on it or an ancestor ({@link MASKED_BY_JS}), e.g.
+     * `mask-image on div.hero`: part or all of it may not show
+     */
+    masked?: 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 */
@@ -120,7 +132,8 @@ export declare const CLIP_RECT_CUTS_ALL_JS = "(position, clip) => {\n  if ((posi
  * 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
+ * collapsed to zero size; a `display: contents` element is measured by
+ * its children in the flat tree and is hidden only when none shows), 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
@@ -161,10 +174,10 @@ export declare function scrollTarget(start: number, size: number, viewSize: numb
  * 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 measured - Page-side measurements (a zero-size holder is placed by its children)
  * @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;
+export declare function classifyViewportPosition(measured: ElementGeometry, viewport: LayoutSize): ViewportPlacement;
 //# sourceMappingURL=elementGeometry.d.ts.map

package/dist/runtime/dom/elementGeometry.js

@@ -268,12 +268,28 @@ const INVISIBLE_REASON_JS = `(el, describe) => {
   }
   return null;
 }`;
+/**
+ * Page-side mask over an element: the nearest of it and its ancestors in the
+ * flat tree (slots, shadow hosts, iframes) with a `mask-image`. How much the
+ * mask hides is not evaluated. Null without one.
+ */
+const MASKED_BY_JS = `(el, describe) => {
+  const flatParent = ${FLAT_PARENT_JS};
+  const parentOf = (n) => flatParent(n) || n.ownerDocument.defaultView.frameElement || null;
+  for (let n = el; n; n = parentOf(n)) {
+    const style = n.ownerDocument.defaultView.getComputedStyle(n);
+    const mask = style.maskImage || style.webkitMaskImage;
+    if (mask && mask !== 'none') return n === el ? 'mask-image' : 'mask-image on ' + describe(n);
+  }
+  return null;
+}`;
 /**
  * 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
+ * collapsed to zero size; a `display: contents` element is measured by
+ * its children in the flat tree and is hidden only when none shows), 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
@@ -292,6 +308,7 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
   const scrollRange = ${SCROLL_RANGE_JS};
   const scrollLock = ${SCROLL_LOCK_JS};
   const invisibleReason = ${INVISIBLE_REASON_JS};
+  const maskedBy = ${MASKED_BY_JS};
   const describe = ${ELEMENT_DESCRIPTION_JS};
   const reasons = ${JSON.stringify(LAYOUT_REASONS)};
   const styleOf = (node) => node.ownerDocument.defaultView.getComputedStyle(node);
@@ -311,16 +328,34 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
     }
     return 'not rendered';
   };
-  const hiddenReason = (style, box) => {
+  const flatChildren = (node) =>
+    Array.from((node.shadowRoot || node).children).flatMap((c) => {
+      const shown = c.localName === 'slot' ? c.assignedElements({ flatten: true }) : [c];
+      return shown.flatMap((s) => (styleOf(s).display === 'contents' ? flatChildren(s) : [s]));
+    });
+  const shownChildren = (node) => {
+    const s = styleOf(node);
+    if (s.overflowX !== 'visible' || s.overflowY !== 'visible') return null;
+    let union = null;
+    for (const c of flatChildren(node).slice(0, 50)) {
+      const r = c.getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0 || styleOf(c).visibility !== 'visible') continue;
+      union = union
+        ? { left: Math.min(union.left, r.left), top: Math.min(union.top, r.top), right: Math.max(union.right, r.right), bottom: Math.max(union.bottom, r.bottom) }
+        : { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
+    }
+    return union;
+  };
+  const hiddenReason = (style, box, content) => {
     if (style.display === 'none') return 'display: none';
-    if (style.display === 'contents') return 'display: contents (no box of its own)';
+    if (style.display === 'contents') return content ? null : 'display: contents (no box of its own)';
     if (el.getClientRects().length === 0) {
       return el.tagName === 'OPTION' ? reasons.option : 'not rendered (an ancestor has display: none)';
     }
     const skipped = skippedReason(el);
     if (skipped) return skipped;
     if (style.visibility !== 'visible') return 'visibility: ' + style.visibility;
-    if (box.width === 0 || box.height === 0) return 'zero size';
+    if ((box.width === 0 || box.height === 0) && !content) return 'zero size';
     return null;
   };
   const isSticky = () => {
@@ -343,7 +378,8 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
   let clipper = own.clipper;
   let fixed = own.fixed;
   let fixedBy = own.fixedBy;
-  let hidden = hiddenReason(styleOf(el), box) || own.collapsed;
+  let content = box.width === 0 || box.height === 0 ? shownChildren(el) : null;
+  let hidden = hiddenReason(styleOf(el), box, content) || own.collapsed;
   let x = 0;
   let y = 0;
   for (let view = el.ownerDocument.defaultView; view && view.frameElement; view = view.parent) {
@@ -355,6 +391,7 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
     overlay = { right: !!unframed && unframed.right <= clip.right && overlay.right, bottom: !!unframed && unframed.bottom <= clip.bottom && overlay.bottom };
     const offset = frameOffset(frame);
     rect = shift(rect, offset.x, offset.y);
+    content = shift(content, offset.x, offset.y);
     const outer = ancestorClip(frame, rect, describe);
     const inner = shift(clip, offset.x, offset.y);
     clip = intersect(inner, outer.clip);
@@ -371,9 +408,10 @@ export const ELEMENT_GEOMETRY_JS = `(el) => {
   while (top.frameElement) top = top.parent;
   const toBox = (r) => r && { x: r.left, y: r.top, width: r.right - r.left, height: r.bottom - r.top };
   const invisible = hidden ? null : invisibleReason(el, describe);
+  const masked = hidden || invisible ? null : maskedBy(el, describe);
   const lock = scrollLock(top, describe);
   if (lock && fixedBy === top.document.body) fixed = false;
-  return { rect: toBox(rect), clip: toBox(clip), clipOverlay: overlay, clipper: clipper, hidden: hidden, invisible: invisible, inert: isInert(), fixed: fixed, sticky: !fixed && isSticky(), pageScroll: scrollRange(top), scrollLock: lock, offset: { x: x, y: y } };
+  return { rect: toBox(rect), content: toBox(content), clip: toBox(clip), clipOverlay: overlay, clipper: clipper, hidden: hidden, invisible: invisible, masked: masked, inert: isInert(), fixed: fixed, sticky: !fixed && isSticky(), pageScroll: scrollRange(top), scrollLock: lock, offset: { x: x, y: y } };
 }`;
 /**
  * Edges of a box.
@@ -481,14 +519,15 @@ function axisScroll(start, size, viewSize, range, aim) {
  * 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 measured - Page-side measurements (a zero-size holder is placed by its children)
  * @param viewport - Top-level viewport size
  * @returns Position, with the visible share, hidden reason, clipping
  *   ancestor or page scroll when relevant
  */
-export function classifyViewportPosition(geometry, viewport) {
-    if (geometry.hidden)
-        return { inViewport: 'hidden', hiddenReason: geometry.hidden };
+export function classifyViewportPosition(measured, viewport) {
+    if (measured.hidden)
+        return { inViewport: 'hidden', hiddenReason: measured.hidden };
+    const geometry = measured.content ? { ...measured, rect: measured.content } : measured;
     const rect = edgesOf(geometry.rect);
     const screen = edgesOf({ x: 0, y: 0, ...viewport });
     const view = geometry.clip ? overlap(screen, edgesOf(geometry.clip)) : screen;

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

@@ -3,6 +3,19 @@
  * `dom layout`, DOM context of console messages): their text as a user sees
  * it and where they live (iframes, shadow roots).
  */
+/**
+ * Whether a class name is shown in element labels: not empty and not a
+ * fragment of a declaration-like class attribute ({@link CLASS_FRAGMENT}).
+ *
+ * @param name - Class name
+ * @returns True to show it
+ */
+export declare function isLabelClass(name: string): boolean;
+/**
+ * Page-side `(node) => string[]`: the element's classes shown in labels
+ * ({@link isLabelClass}), read without array helpers a page may replace
+ */
+export declare const LABEL_CLASSES_JS: string;
 /** Length of the text `dom get` shows for an element. */
 export declare const ELEMENT_TEXT_LENGTH = 500;
 /**
@@ -14,18 +27,45 @@ export declare const ELEMENT_TEXT_LENGTH = 500;
  * 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 check whether `innerText` misses part of what an element shows:
+ * it is a `<slot>` or hosts an open shadow root, or one of its descendants
+ * is or does. `innerText` follows neither shadow roots nor slots.
+ */
+export declare const COMPOSED_JS = "(node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n}";
+/**
+ * Page-side text of an element as the flat tree renders it, for elements
+ * `innerText` cannot read ({@link COMPOSED_JS}): a shadow host is read from
+ * its open shadow root (its own labels and fallback content; light children
+ * only where a slot shows them), and each slot is replaced by what it
+ * shows, its assigned nodes flattened through nested slots (or its fallback
+ * content when nothing is assigned). Parts without slots or shadow roots
+ * are read with `innerText`; elements that are not rendered and text under
+ * `visibility: hidden` are left out, elements that are not inline are set
+ * apart by line breaks, as is a `<br>`. Fields and editable regions inside
+ * it (inputs, textareas, selects, a contenteditable editor) are skipped, so
+ * what a user typed is never read; raw text keeps `innerText`'s collapsed
+ * whitespace. The text is cut at `limit` characters, and a
+ * part whose text alone passes the limit is read from its text nodes
+ * (`textContent`) instead of `innerText`, which would lay out all of it.
+ */
+export declare const FLAT_TEXT_JS = "(el, limit) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea|select)$/.test(node.localName) || node.isContentEditable) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n}";
 /**
  * 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}).
+ * `<option>` (which its `<select>` renders). A web component, a slot, and
+ * an element holding either are read through the flat tree
+ * ({@link FLAT_TEXT_JS}): the text a component renders from its shadow
+ * root, slotted content in place of its slots, blocks set apart. 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}";
+export declare const ELEMENT_TEXT_JS = "(el, full) => {\n  const withoutDecorations = (el, text) => {\n  if (!text || typeof el.querySelectorAll !== 'function') return text;\n  const glyph = /^\\s*[\u00D7\u2715\u2716\u2717\u2A2F]\\s*$/;\n  const textOf = (node) => (typeof node.innerText === 'string' ? node.innerText : node.textContent || '').trim();\n  const closer = '.close, [aria-label=\"close\" i], [aria-label=\"dismiss\" i]';\n  const rendered = (node) => !node.checkVisibility || node.checkVisibility();\n  const found = Array.from(el.querySelectorAll(closer + ', [aria-hidden=\"true\"]'))\n    .filter((node) => rendered(node) && (node.matches(closer) || !/[\\p{L}\\p{N}]/u.test(textOf(node))));\n  if (/[\u00D7\u2715\u2716\u2717\u2A2F]/.test(text)) {\n    found.push(...Array.from(el.querySelectorAll('button, a, [role=\"button\"]')).filter((node) => glyph.test(node.textContent || '')));\n  }\n  const unique = Array.from(new Set(found));\n  const outermost = unique.filter((node) => !unique.some((other) => other !== node && other.contains(node)));\n  let result = text;\n  for (const node of outermost) {\n    const part = textOf(node);\n    const at = part ? result.lastIndexOf(part) : -1;\n    if (at >= 0) result = result.slice(0, at) + result.slice(at + part.length);\n  }\n  return result;\n};\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const flatText = (el, limit) => {\n  const composed = (node) => {\n  const composes = (n) => Boolean(n.shadowRoot) || n.localName === 'slot';\n  if (composes(node)) return true;\n  const walker = node.ownerDocument.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);\n  while (walker.nextNode()) if (composes(walker.currentNode)) return true;\n  return false;\n};\n  const view = el.ownerDocument.defaultView;\n  let text = '';\n  const nodesOf = (node) =>\n    node.localName === 'slot' ? node.assignedNodes({ flatten: true }) : Array.from((node.shadowRoot || node).childNodes);\n  const read = (node, visible) => {\n    if (text.length >= limit) return;\n    if (node.nodeType === 3 && visible) text += node.data.replace(/\\s+/g, ' ');\n    if (node.nodeType !== 1) return;\n    if (/^(input|textarea|select)$/.test(node.localName) || node.isContentEditable) return;\n    const style = view.getComputedStyle(node);\n    if (node.checkVisibility && !node.checkVisibility() && style.display !== 'contents') return;\n    if (node.localName === 'br') text += '\\n';\n    const apart = style.display.startsWith('inline') || style.display === 'contents' ? '' : '\\n';\n    text += apart;\n    const own = node.textContent || '';\n    if (composed(node)) nodesOf(node).forEach((child) => read(child, style.visibility === 'visible'));\n    else if (own.length > limit - text.length) text += own.slice(0, limit - text.length);\n    else text += typeof node.innerText === 'string' ? node.innerText : own;\n    text += apart;\n  };\n  const visible = view.getComputedStyle(el).visibility === 'visible';\n  nodesOf(el).forEach((child) => read(child, visible));\n  return text.slice(0, limit);\n};\n  const all = el.textContent || '';\n  if (el.tagName === 'OPTION') return el.label;\n  if (typeof el.innerText !== 'string') return full ? all : all.slice(0, 2000);\n  const rendered = (node) => !node.checkVisibility || node.checkVisibility();\n  const shown = rendered(el);\n  const boxless = !shown && el.ownerDocument.defaultView.getComputedStyle(el).display === 'contents';\n  if (!shown && !boxless) return '';\n  if (composed(el)) return withoutDecorations(el, flatText(el, full ? Infinity : 2000));\n  if (boxless) return withoutDecorations(el, full ? all : all.slice(0, 2000));\n  if (full || all.length <= 2000) return withoutDecorations(el, el.innerText);\n  const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_TEXT);\n  let start = '';\n  while (start.length < 1000 && walker.nextNode()) {\n    const parent = walker.currentNode.parentElement;\n    if (!parent || rendered(parent)) start += walker.currentNode.data;\n  }\n  return withoutDecorations(el, start);\n}";
 /** Shown instead of a secret field value (the same for every length) */
 export declare const MASKED_VALUE = "\u2022\u2022\u2022\u2022";
 /**
@@ -53,26 +93,40 @@ export declare const SENSITIVE_FIELD_JS = "(el) => {\n  const autocomplete = el.
  */
 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`.
+ * Page-side short description of an element: tag, id and up to two classes
+ * ({@link LABEL_CLASSES_JS}), e.g. `button#save.primary.large`.
+ */
+export declare const ELEMENT_DESCRIPTION_JS: string;
+/**
+ * Page-side reason an element is disabled, or null when it is not. A native
+ * control (`button`, `input`, `select`, `textarea`, `fieldset`, `optgroup`,
+ * `option`) is disabled by its `disabled attribute` or by being `inside a
+ * disabled <fieldset>` (not in its first `<legend>`), an `<option>` by
+ * being `inside a disabled <optgroup>`; any other element
+ * (e.g. a custom element) when its `disabled` property is set (empty
+ * reason). Reads the element's own attributes rather than
+ * `matches(':disabled')`, which pages replace.
  */
-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('.') : '')";
+export declare const DISABLED_CAUSE_JS = "(el) => {\n  if (!/^(button|input|select|textarea|fieldset|optgroup|option)$/.test(el.localName)) return el.disabled ? '' : null;\n  if (el.hasAttribute('disabled')) return 'disabled attribute';\n  if (el.localName === 'option') {\n    const group = el.parentElement;\n    return group && group.localName === 'optgroup' && group.hasAttribute('disabled') ? 'inside a disabled <optgroup>' : null;\n  }\n  for (let node = el.parentElement; node; node = node.parentElement) {\n    if (node.localName !== 'fieldset' || !node.hasAttribute('disabled')) continue;\n    let legend = node.firstElementChild;\n    while (legend && legend.localName !== 'legend') legend = legend.nextElementSibling;\n    if (!legend || !legend.contains(el)) return 'inside a disabled <fieldset>';\n  }\n  return null;\n}";
 /**
  * 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}";
+export declare const SIBLING_POSITION_JS: string;
 /**
  * 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
+ * inputs, decorations left out; read through the flat tree for web
+ * components and slots, {@link FLAT_TEXT_JS}), e.g.
+ * `button#add.btn "Add to cart"`. A `<select>` is named by its label
+ * (`aria-labelledby` or `<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
+ * its name when it has one: aria-label, label, placeholder, title, or the
+ * alt text of an image (in it). 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
@@ -80,17 +134,20 @@ export declare const SIBLING_POSITION_JS = "(el) => {\n  const describe = (node)
  * 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
+ * typed input; otherwise its name 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}";
+export declare const ELEMENT_IDENTITY_JS: string;
 /**
  * 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.
+ * and the shadow root holding it, with the host's first class and the text
+ * a user sees of it ({@link ELEMENT_TEXT_JS}, cut at 30 characters with
+ * `…`), e.g. `iframe#pay > shadow root of <sl-button.primary "Save">`;
+ * empty for the main document. Each host's text is read once per script
+ * run, as many matches share a host.
  */
-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}";
+export declare const ELEMENT_CONTEXT_JS: string;
 /**
  * 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).