scenescout 3.15.0 → 3.17.0

package/dist/engine/collector.js

@@ -47,6 +47,11 @@ export const XPATH_OF_SRC = `(el) => {
  * A label's text is read without the control's own text: a wrapping label
  * holds the control, and a select's options or a textarea's contents are not
  * its label.
+ *
+ * `content` is what the element's image content says, which the text cannot
+ * hold: the alt text of the first descendant <img>, else the aria-label or
+ * <title> of a descendant <svg> or role="img", in document order, skipping
+ * anything inside an aria-hidden part of the element.
  */
 export const NAME_FACTS_SRC = `(el) => {
     const tag = el.tagName.toLowerCase();
@@ -58,6 +63,17 @@ export const NAME_FACTS_SRC = `(el) => {
       const own = label.contains(el) ? el.textContent || "" : "";
       labels.push((label.textContent || "").replace(own, ""));
     }
+    let content = "";
+    for (const d of el.querySelectorAll("img, svg, [role='img']")) {
+      const hidden = d.closest('[aria-hidden="true"]');
+      if (hidden && el.contains(hidden)) continue;
+      const title = d.tagName.toLowerCase() === "svg" ? d.querySelector(":scope > title") : null;
+      const said = (d.tagName === "IMG" ? d.getAttribute("alt") : d.getAttribute("aria-label") || (title ? title.textContent : "")) || "";
+      if (said.trim()) {
+        content = said;
+        break;
+      }
+    }
     const live = /^(status|alert|log|timer|marquee)$/.test(role) || tag === "output" ||
       (el.hasAttribute("aria-live") && el.getAttribute("aria-live") !== "off");
     return {
@@ -74,6 +90,7 @@ export const NAME_FACTS_SRC = `(el) => {
       alt: el.getAttribute("alt") || "",
       live,
       text: el.innerText || el.textContent || "",
+      content,
     };
   }`;
 /**
@@ -88,8 +105,15 @@ export const NAME_FACTS_SRC = `(el) => {
  * fallback stays.
  *
  * - A select is never named by its options: their text is its value, not its name.
- * - Other elements are named by their text, and by title when they have none
- *   (an icon-only button with a tooltip).
+ * - Other elements are named by their text; with none, by their image content
+ *   (a link holding only a logo with alt text, a button holding only an svg
+ *   with a <title>); and with neither, by title (an icon-only button with a
+ *   tooltip). Text and image content are not joined: a control with both is
+ *   named by its text, as it was before image content counted.
+ * - A name taken from image content carries `prior`, the name the rule gave
+ *   before image content counted (the title, or nothing). The name is half of
+ *   the coverage key, so the key under the earlier rule is kept beside the new
+ *   one and coverage recorded under it carries over (memory.ts keyAliases).
  * - A live region (status, alert, log, timer, an aria-live region, <output>)
  *   is named by the text it announces, which is what matters after an action.
  * - A whitespace-only aria-label ends the name with nothing, as it always has
@@ -121,6 +145,7 @@ export const PICK_NAME_SRC = `(f) => {
       return { name: (clean(f.nameAttr) || t || f.tag).slice(0, 80), from: "fallback" };
     }
     if (clean(f.text)) return named(clean(f.text));
+    if (clean(f.content)) return { ...named(clean(f.content)), prior: clean(f.title).slice(0, 80) };
     return named(clean(f.title));
   }`;
 /**
@@ -138,6 +163,49 @@ export const NAME_SRC = `(el) => (${PICK_NAME_SRC})((${NAME_FACTS_SRC})(el))`;
  * must name it exactly as the snapshot did, or the two cannot be compared.
  */
 export const ACCESSIBLE_NAME_SRC = `(el) => (${NAME_SRC})(el).name`;
+/**
+ * What the label policy reads of an element besides its name (policy.ts
+ * destructiveLabelOf), as page-side source shared by the snapshot and the
+ * live re-check before an action, so the two cannot judge differently.
+ *
+ * `ownText`: the label the element is given (aria-label, aria-labelledby),
+ * then its text without the text of the controls inside it.
+ * `centre`: the labels of the controls inside it whose boxes cover the
+ * element's centre point, which is where a click on the element lands. Boxes,
+ * not a hit test, so it reads the same whether or not the element is scrolled
+ * into view, and every covering control is named, not only the topmost.
+ */
+export const POLICY_TEXT_SRC = `(el) => {
+    const CONTROL = 'a[href], button, input, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], ' +
+      '[role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="combobox"], [role="listbox"], [onclick]';
+    const parts = [];
+    const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      const owner = node.parentElement && node.parentElement.closest(CONTROL);
+      if (owner && owner !== el && el.contains(owner)) continue;
+      const t = (node.textContent || "").trim();
+      if (t) parts.push(t);
+      if (parts.join(" ").length > 400) break;
+    }
+    // A label the element is given (aria-label, aria-labelledby) is its own: an icon-only control's only name.
+    const given = [el.getAttribute("aria-label") || ""].concat((el.getAttribute("aria-labelledby") || "").split(/\\s+/).filter(Boolean).map((id) => {
+      const n = document.getElementById(id);
+      return n ? n.textContent || "" : "";
+    })).join(" ").trim();
+    const ownText = (given + " " + parts.join(" ")).replace(/\\s+/g, " ").trim().slice(0, 400);
+    const r = el.getBoundingClientRect();
+    const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+    const centre = [];
+    for (const c of Array.from(el.querySelectorAll(CONTROL))) {
+      const b = c.getBoundingClientRect();
+      if (b.width === 0 || b.height === 0 || cx < b.left || cx > b.right || cy < b.top || cy > b.bottom) continue;
+      const label = (c.getAttribute("aria-label") || c.innerText || c.textContent || c.getAttribute("value") || "").trim().replace(/\\s+/g, " ").slice(0, 120);
+      if (label && centre.length < 10) centre.push(label);
+      const tid = c.getAttribute("data-testid");
+      if (tid && centre.length < 10) centre.push(tid);
+    }
+    return { ownText, centre };
+  }`;
 /**
  * Anything that plausibly presents as a modal/dialog panel. Deliberately wider
  * than the ARIA set: a hand-rolled role-less modal must still count as "an
@@ -146,6 +214,63 @@ export const ACCESSIBLE_NAME_SRC = `(el) => (${NAME_SRC})(el).name`;
  */
 export const DIALOG_LIKE_SEL = '[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"], [class*="modal" i], [class*="dialog" i]';
 // Declared above the collector script because that script interpolates it.
+/**
+ * The accessible name of a control that pages a clipping container: next and
+ * previous arrows, numbered slide or page buttons, scroll-left and
+ * scroll-right. Content clipped inside a container such a control sits beside
+ * is revealed by it, so it is not unreachable. The page-side walk carries a
+ * literal copy (no value is spliced into page code); oracle-test holds the two
+ * equal.
+ */
+export const PAGER_NAME = /^(?:[‹›«»<>←→⟨⟩❮❯]|(?:go to |show )?(?:next|previous|prev)(?:\s+\w+)?|(?:go to |show )?(?:slide|page|image|item|step)\s*\d+.*|scroll (?:left|right|up|down)\b.*)$/i;
+/** Whether a control's name says it pages a container (see PAGER_NAME). */
+export function isPagerName(name) {
+    return PAGER_NAME.test(name.trim());
+}
+/**
+ * An href that points at a place in this same document: "#main". Not a bare
+ * "#", and not a hash route ("#/reports", "#!/reports"), which is navigation.
+ * The collector carries a literal copy; oracle-test holds the two equal.
+ */
+export const IN_PAGE_ANCHOR = /^#(?![/!])./;
+/**
+ * Style properties that can bring a box parked off the page back into it. A
+ * :focus rule that sets one of these is how a skip link is revealed; a :focus
+ * rule that only draws an outline is not. The collector carries a literal
+ * copy; oracle-test holds the two equal.
+ */
+export const FOCUS_MOVES_PROPS = [
+    "position",
+    "top",
+    "left",
+    "right",
+    "bottom",
+    "inset",
+    "transform",
+    "translate",
+    "clip",
+    "clip-path",
+    "margin",
+    "margin-top",
+    "margin-left",
+    "width",
+    "height",
+];
+/** The most elements a snapshot lists in full; past it, what is left is counted (cutSummary). */
+export const COLLECTOR_CAP = 150;
+/** Pager and "load more" controls listed past the cap, so a lane can still reach the rest of a long list. */
+export const MAX_KEPT_PAST_CAP = 10;
+/** How many elements past the cap are looked at, to keep them or count them, before the rest goes uncounted. */
+export const MAX_SCANNED_PAST_CAP = 2000;
+/**
+ * A control that pages a list or loads more of it, by its name: "Next",
+ * "Previous page", "Page 3", "»", "Load more", "Show 20 more", "More results".
+ * Narrower than PAGER_NAME, which also takes "Item 4" and "Step 2" for a
+ * carousel's slides: past the cap, those are the list itself.
+ */
+export const LIST_PAGER_NAME = /^(?:[‹›«»<>←→]|(?:go to )?(?:next|previous|prev|first|last)(?: page)?|(?:go to )?page \d+|(?:load|show|see|view) (?:\d+ )?more\b.*|more results)$/i;
+/** A test id that names a pager or a "load more" control: "pager-next", "pagination", "load-more", "next-page". */
+export const PAGER_TESTID = /(?:^|[-_.:])(?:pager|pagination|paginator|load-?more|show-?more|(?:next|prev|previous)-?page|page-?(?:next|prev|previous))(?:$|[-_.:])/i;
 /**
  * Page-side interactable collector. Shipped as a STRING, not a function:
  * loader transforms (tsx/vitest esbuild hooks inject a `__name` helper) break
@@ -156,6 +281,7 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
   const xpathOf = ${XPATH_OF_SRC};
   const visible = ${VISIBLE_SRC};
   const nameOf = ${NAME_SRC};
+  const policyText = ${POLICY_TEXT_SRC};
   // What the collector lists before anything else: controls, and anything the
   // app tagged with a test id so it can be targeted.
   const controlSelector =
@@ -173,18 +299,29 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
   // Everything else listed is here for its test id or its text, and is neither
   // an unnamed control nor a gap in coverage.
   const CONTROL_ROLES = /^(button|link|tab|menuitem|menuitemcheckbox|menuitemradio|checkbox|radio|switch|combobox|textbox|searchbox|slider|spinbutton|option|treeitem)$/;
-  const isInteractive = (el) => {
-    if (el.matches('a[href], button, input, select, textarea, summary, [contenteditable="true"], [contenteditable=""]')) return true;
-    if (CONTROL_ROLES.test(el.getAttribute("role") || "")) return true;
+  // For an element that is neither a native control nor in a control role:
+  // what alone makes it actionable (affordanceFlags). Null for a control.
+  const affordancesOf = (el) => {
+    if (el.matches('a[href], button, input, select, textarea, summary, [contenteditable="true"], [contenteditable=""]')) return null;
+    if (CONTROL_ROLES.test(el.getAttribute("role") || "")) return null;
     const tabindex = el.getAttribute("tabindex");
-    if (tabindex !== null && tabindex.trim() !== "" && Number(tabindex) >= 0) return true;
-    if (el.hasAttribute("onclick") || typeof el.onclick === "function") return true;
+    const tabStop = tabindex !== null && tabindex.trim() !== "" && Number(tabindex) >= 0;
+    const clickHandler = el.hasAttribute("onclick") || typeof el.onclick === "function";
+    let pointer = false;
     if (window.getComputedStyle(el).cursor === "pointer") {
       const parent = el.parentElement;
-      return !parent || window.getComputedStyle(parent).cursor !== "pointer";
+      pointer = !parent || window.getComputedStyle(parent).cursor !== "pointer";
     }
-    return false;
+    return { tabStop, clickHandler, pointer };
   };
+  const isInteractive = (aff) => aff === null || aff.tabStop || aff.clickHandler || aff.pointer;
+  // Past the element cap, a control that pages the list or loads more of it
+  // is still listed (up to MAX_KEPT_PAST_CAP), and the rest is only counted.
+  const LIST_PAGER = ${String(LIST_PAGER_NAME)};
+  const PAGER_TID = ${String(PAGER_TESTID)};
+  let keptPastCap = 0;
+  let scannedPastCap = 0;
+  const cut = [];
   // A horizontally scrolling container a control sits outside of: the control
   // is reachable, by a sideways scroll of that container, but nothing on screen
   // shows it is there. Carousels (scroll-snap) page sideways by design and are
@@ -300,6 +437,39 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
     const text = (node.innerText || node.textContent || "").trim().replace(/\\s+/g, " ").slice(0, 40);
     return "<" + node.tagName.toLowerCase() + ">" + (text ? ' "' + text + '"' : "");
   };
+  /** A link to a place in this same document (a skip link's shape): "#main", never a bare "#" or a hash route ("#/reports"). */
+  const inPageAnchor = (node) => node.tagName === "A" && /^#(?![/!])./.test(node.getAttribute("href") || "");
+  // The page's :focus rules that move a box (FOCUS_MOVES_PROPS), as selectors
+  // with the :focus part removed: an element they match is shown when it takes
+  // focus. Read once, only when an element sits off the page.
+  let focusMoveSelectors = null;
+  const FOCUS_MOVES = ["position", "top", "left", "right", "bottom", "inset", "transform", "translate", "clip", "clip-path", "margin", "margin-top", "margin-left", "width", "height"];
+  const readFocusRules = (rules, out) => {
+    for (const rule of Array.from(rules || [])) {
+      if (out.length >= 500) return;
+      if (rule.cssRules && !rule.selectorText) { readFocusRules(rule.cssRules, out); continue; }
+      const sel = rule.selectorText || "";
+      if (!/:focus/.test(sel) || !rule.style) continue;
+      const props = Array.from(rule.style);
+      if (!props.some((p) => FOCUS_MOVES.indexOf(p) >= 0 || /^(inset|margin)-/.test(p))) continue;
+      for (const part of sel.split(",")) {
+        if (/:focus/.test(part)) out.push(part.replace(/:focus(-visible|-within)?/g, "").trim() || "*");
+      }
+    }
+  };
+  const focusMoves = (el) => {
+    if (focusMoveSelectors === null) {
+      focusMoveSelectors = [];
+      for (const sheet of Array.from(document.styleSheets)) {
+        // Reading another origin's stylesheet throws by design; its rules stay unknown.
+        try { readFocusRules(sheet.cssRules, focusMoveSelectors); } catch (e) { continue; }
+      }
+    }
+    return focusMoveSelectors.some((sel) => {
+      // Removing :focus can leave an invalid selector (":not()"), which matches nothing.
+      try { return el.matches(sel); } catch (e) { return false; }
+    });
+  };
   const coveredByPinnedChrome = (el, rect, role) => {
     if (INTERACTIVE_ROLES.indexOf(role) === -1) return null;
     const cx = rect.left + rect.width / 2, cy = rect.top + rect.height / 2;
@@ -308,6 +478,11 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
     if (!ownRoot || insideScrollablePane(el)) return null;
     const top = document.elementFromPoint(cx, cy);
     if (!top || top === el || el.contains(top) || top.contains(el)) return null;
+    // A skip link is pinned out of sight until it takes focus, then shown over
+    // the header. While focused it covers whatever is under it, by design, and
+    // it leaves again as soon as focus moves on.
+    const active = document.activeElement;
+    if (active && inPageAnchor(active) && (top === active || active.contains(top))) return null;
     const coverRoot = pinnedRootOf(top);
     if (!coverRoot || coverRoot === ownRoot || coverRoot.contains(ownRoot) || ownRoot.contains(coverRoot)) return null;
     // A dialog's fixed wrapper often carries no role or class itself; the
@@ -319,6 +494,63 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
     return describe(coverRoot);
   };
 
+  const PAGER = /^(?:[‹›«»<>←→⟨⟩❮❯]|(?:go to |show )?(?:next|previous|prev)(?:\\s+\\w+)?|(?:go to |show )?(?:slide|page|image|item|step)\\s*\\d+.*|scroll (?:left|right|up|down)\\b.*)$/i;
+  // Per container and axis: a carousel clips every slide but one, and they share the answer.
+  const pagedClips = new Map();
+  const revealedByControl = (clip, axis) => {
+    const key = pagedClips.get(clip) || {};
+    if (key[axis] === undefined) { key[axis] = pagesClip(clip, axis); pagedClips.set(clip, key); }
+    return key[axis];
+  };
+  // Content laid out as slides along the clipped axis: two or more children
+  // (of the clip, or of its single track) the clip's own size on that axis,
+  // at least one starting outside it. A table wider than its card, or a list
+  // longer than it, is not; a "Next page" in its footer pages rows, not them.
+  const slidesIn = (clip, axis) => {
+    const cr = clip.getBoundingClientRect();
+    const start = axis === "x" ? cr.left : cr.top;
+    const span = axis === "x" ? cr.width : cr.height;
+    const track = clip.children.length === 1 ? clip.children[0] : clip;
+    let size = 0, outside = 0;
+    for (const kid of Array.from(track.children).slice(0, 50)) {
+      const r = kid.getBoundingClientRect();
+      const s = axis === "x" ? r.width : r.height;
+      if (s < span * 0.9 || s > span * 1.1) continue;
+      size += 1;
+      const at = axis === "x" ? r.left : r.top;
+      if (at >= start + span - 1 || at + s <= start + 1) outside += 1;
+    }
+    return size >= 2 && outside >= 1;
+  };
+  /**
+   * Whether a control in or beside a clipping container pages it: a visible
+   * control within two levels above the container that names the container
+   * (or something in it) in aria-controls, or, when the container holds
+   * slides on the clipped axis, one whose name says next, previous, or a
+   * numbered slide or page.
+   */
+  const pagesClip = (clip, axis) => {
+    let region = clip;
+    for (let i = 0; i < 2 && region.parentElement && region.parentElement !== document.body; i++) region = region.parentElement;
+    const cr = clip.getBoundingClientRect();
+    let slides = null;
+    const controls = region.querySelectorAll('button, [role="button"], a[href], [role="tab"], input[type="button"]');
+    for (const c of Array.from(controls).slice(0, 200)) {
+      if (!visible(c)) continue;
+      // A control inside the clip must itself be showing: a button on another
+      // hidden slide (the clipped element among them) pages nothing.
+      if (clip.contains(c)) {
+        const r = c.getBoundingClientRect();
+        if (r.bottom <= cr.top || r.top >= cr.bottom || r.right <= cr.left || r.left >= cr.right) continue;
+      }
+      const controlled = (c.getAttribute("aria-controls") || "").split(/\\s+/).filter(Boolean);
+      if (controlled.some((id) => { const t = document.getElementById(id); return t && (t === clip || clip.contains(t) || t.contains(clip)); })) return true;
+      const name = (c.getAttribute("aria-label") || c.getAttribute("title") || c.textContent || "").trim().replace(/\\s+/g, " ");
+      if (PAGER.test(name) && (slides === null ? (slides = slidesIn(clip, axis)) : slides)) return true;
+    }
+    return false;
+  };
+
   for (const el of Array.from(document.querySelectorAll(selector))) {
     if (seen.has(el) || !visible(el)) continue;
     seen.add(el);
@@ -342,17 +574,30 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
         : tag === "output" ? "status"
         : el.hasAttribute("aria-live") && el.getAttribute("aria-live") !== "off" ? (el.getAttribute("aria-live") === "assertive" ? "alert" : "status")
         : "generic");
+    if (out.length >= ${COLLECTOR_CAP}) {
+      // Past the cap only a bounded number of elements is looked at at all.
+      if (++scannedPastCap > ${MAX_SCANNED_PAST_CAP}) { cut.push({ cut: true, uncounted: true }); break; }
+      const tid = el.getAttribute("data-testid");
+      const said = (el.getAttribute("aria-label") || el.textContent || "").trim().replace(/\\s+/g, " ").slice(0, 60);
+      const pages = LIST_PAGER.test(said) || (tid !== null && PAGER_TID.test(tid));
+      if (!pages || keptPastCap >= ${MAX_KEPT_PAST_CAP}) { cut.push({ cut: true, role, testid: tid }); continue; }
+      keptPastCap += 1;
+    }
     const rect = el.getBoundingClientRect();
+    const elStyle = window.getComputedStyle(el);
     // Below-the-fold is reachable (scroll); clipped INSIDE an overflow-hidden
     // ancestor is not — the container cannot scroll, so the control exists in
     // layout but no user can ever see or reach it. Out-of-flow boxes are only
     // clipped by their CONTAINING-BLOCK chain: position:fixed escapes ordinary
     // ancestors entirely, and position:absolute skips static ones — a dropdown
     // panel deliberately escaping its clipping wrapper is NOT unreachable.
-    const ePos = window.getComputedStyle(el).position;
+    // A scrolling ancestor reveals what it holds: past one, what the user can
+    // see is that scroller's box, so it is the scroller's box (not the
+    // element's) that the clipping ancestors above it are tested against.
     let clippedByAncestor = false;
-    if (ePos !== "fixed") {
-      let escaping = ePos === "absolute";
+    if (elStyle.position !== "fixed") {
+      let escaping = elStyle.position === "absolute";
+      const box = { top: rect.top, bottom: rect.bottom, left: rect.left, right: rect.right };
       let anc = el.parentElement;
       while (anc && anc !== document.body && anc.tagName !== "HTML") {
         const as = window.getComputedStyle(anc);
@@ -362,30 +607,59 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
           escaping = false;
         }
         const oy = as.overflowY, ox = as.overflowX;
-        const hidesY = oy === "hidden" || oy === "clip";
-        const hidesX = ox === "hidden" || ox === "clip";
-        if (hidesY || hidesX) {
-          const ar = anc.getBoundingClientRect();
-          if (ar.width > 0 && ar.height > 0) {
-            const outY = hidesY && (rect.bottom <= ar.top || rect.top >= ar.bottom);
-            const outX = hidesX && (rect.right <= ar.left || rect.left >= ar.right);
-            if (outY || outX) { clippedByAncestor = true; break; }
+        const ar = anc.getBoundingClientRect();
+        if (ar.width > 0 && ar.height > 0) {
+          let hidden = null;
+          let scrolls = false;
+          // A scroller reveals anything it holds on that axis. Not tested
+          // against its scroll range: reversed flex columns (chat logs) and
+          // right-to-left text scroll to negative offsets.
+          if (oy === "auto" || oy === "scroll") { box.top = ar.top; box.bottom = ar.bottom; scrolls = true; }
+          else if ((oy === "hidden" || oy === "clip") && (box.bottom <= ar.top || box.top >= ar.bottom)) hidden = "y";
+          if (ox === "auto" || ox === "scroll") { box.left = ar.left; box.right = ar.right; scrolls = true; }
+          else if ((ox === "hidden" || ox === "clip") && (box.right <= ar.left || box.left >= ar.right)) hidden = "x";
+          if (hidden) {
+            // A pager beside the container (next/previous, numbered slides, or
+            // a control naming it in aria-controls) reveals what it clips.
+            if (!revealedByControl(anc, hidden)) clippedByAncestor = true;
+            break;
+          }
+          // Above a scroller, clipping follows the SCROLLER's containing chain.
+          if (scrolls) {
+            if (as.position === "fixed") break;
+            if (as.position === "absolute") escaping = true;
           }
         }
         anc = anc.parentElement;
       }
     }
+    // Parked above or left of the page: can taking focus bring it back?
+    const docX = rect.x + window.scrollX, docY = rect.y + window.scrollY;
+    const offPage = docX + rect.width <= 0 || docY + rect.height <= 0;
+    const focusable = el.tabIndex >= 0 && el.disabled !== true;
     const named = nameOf(el);
-    const interactive = isInteractive(el);
+    const affords = affordancesOf(el);
+    const interactive = isInteractive(affords);
     const checkable = tag === "input" && (inputType === "checkbox" || inputType === "radio");
     out.push({
       coveredBy: coveredByPinnedChrome(el, rect, role),
+      focusable,
+      focusMoves: offPage && focusable ? focusMoves(el) : false,
+      // pointer-events:none lets every click through: it cannot take one meant for something else.
+      passThrough: elStyle.pointerEvents === "none",
+      // A text field's side padding, where an adornment (a clear button, an icon) is meant to sit.
+      fieldPad: tag === "textarea" || (tag === "input" && /^(textbox|combobox|searchbox|spinbutton)$/.test(role))
+        ? { l: parseFloat(elStyle.paddingLeft) || 0, r: parseFloat(elStyle.paddingRight) || 0 }
+        : null,
       tag,
       role,
       name: named.name,
+      ...policyText(el),
       nameFrom: named.from,
+      ...(named.prior !== undefined ? { priorName: named.prior } : {}),
       testid: el.getAttribute("data-testid"),
       interactive,
+      affords: affords && (affords.tabStop || affords.clickHandler || affords.pointer) ? affords : null,
       ariaHidden: el.closest('[aria-hidden="true"]') !== null,
       liveOnly: !el.matches(controlSelector),
       state: {
@@ -396,7 +670,7 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
         current: el.getAttribute("aria-current"),
       },
       // Only controls: a tagged cell or row out of view is not something the user has to reach.
-      scrolledOutIn: ePos === "fixed" || clippedByAncestor || !interactive ? null : scrolledOutIn(el, rect),
+      scrolledOutIn: elStyle.position === "fixed" || clippedByAncestor || !interactive ? null : scrolledOutIn(el, rect),
       xpath: xpathOf(el),
       disabled: el.disabled === true || el.getAttribute("aria-disabled") === "true",
       href: tag === "a" ? el.getAttribute("href") : null,
@@ -411,9 +685,8 @@ export const COLLECT_INTERACTABLES_SCRIPT = `(() => {
         h: Math.round(rect.height),
       },
     });
-    if (out.length >= 150) break;
   }
-  return out;
+  return cut.length > 0 ? out.concat(cut) : out;
 })()`;
 /**
  * Roles that announce content rather than take input: a live region is empty
@@ -508,6 +781,20 @@ export function placeholderOnly(el) {
 export function describeControl(el) {
     return `${el.role}${el.testid ? ` [testid=${el.testid}]` : ` at ${el.xpath}`}`;
 }
+/**
+ * What a forced click's note says about the element on top of its target:
+ * `covered by status "Could not save…" [testid=toast-error]`. With
+ * `afterBlock`, the write policy refused a request after the tester last
+ * looked at the page, so the covering element may be the app's response to
+ * the engine's own refusal (an error toast) and in no snapshot.
+ */
+export function describeCover(cover, afterBlock) {
+    const text = cover.text.replace(/\s+/g, " ").trim();
+    const shown = text.length > 60 ? `${text.slice(0, 59)}…` : text;
+    const who = cover.role ?? `<${cover.tag}>`;
+    return (`covered by ${who}${shown ? ` ${JSON.stringify(shown)}` : ""}${cover.testid ? ` [testid=${cover.testid}]` : ""}` +
+        (afterBlock ? " (after a write-policy block since the last snapshot: it may be the app's response to the engine's own refusal)" : ""));
+}
 /** A placeholder-only field's evidence: the control, then its placeholder, capped so a paragraph of hint text stays one line. */
 export function placeholderEvidence(el) {
     const text = el.name.length > 80 ? `${el.name.slice(0, 79)}…` : el.name;
@@ -527,6 +814,170 @@ export function displayName(el) {
         return el.name;
     return LIVE_REGION_ROLES.has(el.role) ? "(empty live region)" : "(unnamed)";
 }
+/**
+ * The snapshot's flags for an element listed without a control's role that a
+ * user can still act on: "clickable" for a click handler or its own pointer
+ * cursor, "focusable" for a tab stop. A row a click opens then reads apart
+ * from a wrapper listed only for its test id, which gets neither.
+ */
+export function affordanceFlags(el) {
+    const a = el.affords;
+    if (!a)
+        return [];
+    const flags = [];
+    if (a.clickHandler || a.pointer)
+        flags.push("clickable");
+    if (a.tabStop)
+        flags.push("focusable");
+    return flags;
+}
+/**
+ * A test id as a family: a trailing number or id after a separator becomes
+ * "*", so "row-12" and "row-13" read as "row-*" while "pager-next" stays itself.
+ */
+export function testidFamily(testid) {
+    return testid.replace(/([-_.:])(?:\d+|[0-9a-f]{8}(?:-?[0-9a-f]{4}){3}-?[0-9a-f]{12}|[0-9a-f]{12,})$/i, "$1*");
+}
+/**
+ * What a truncated snapshot left out, by role and test-id family, largest
+ * group first: "38 link [row-*], 1 button [pager-next], 12 generic". At most
+ * `groups` groups are named; the rest is counted together. "and more past
+ * those, not counted" when the collector stopped looking.
+ */
+export function cutSummary(cut, groups = 8) {
+    const counts = new Map();
+    let uncounted = false;
+    for (const c of cut) {
+        if (c.uncounted) {
+            uncounted = true;
+            continue;
+        }
+        const label = `${c.role ?? "element"}${c.testid ? ` [${testidFamily(c.testid)}]` : ""}`;
+        counts.set(label, (counts.get(label) ?? 0) + 1);
+    }
+    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const named = sorted.slice(0, groups).map(([label, n]) => `${n} ${label}`);
+    const rest = sorted.slice(groups).reduce((sum, [, n]) => sum + n, 0);
+    if (rest > 0)
+        named.push(`${rest} other`);
+    if (uncounted)
+        named.push("and more past those, not counted");
+    return named.join(", ");
+}
+/** A key without the ordinal the collector adds to the second and later elements sharing it ("tid:row~3" → "tid:row"). */
+export function keyFamily(key) {
+    return key.replace(/~\d+$/, "");
+}
+/**
+ * Which element of the previous snapshot each current element is, as that
+ * snapshot's key, or null for an element new since. Gives the ref an element
+ * keeps, and what the diff calls added, removed or changed.
+ *
+ * An element alone under its key is the one that held the key before, so its
+ * new text reads as a relabel. Elements sharing a key (rows tagged with one
+ * test id) are told apart by their own text and href, not their position: a
+ * filtered list then reads as the rows it lost and gained, where by position
+ * the first row "became" another record. A row that kept its link but changed
+ * its text is still matched by the link. `byPosition` keeps the position for
+ * elements whose text is meant to change, such as live regions.
+ */
+export function matchPrevious(prev, current) {
+    const prevByFamily = new Map();
+    for (const key of prev.keys()) {
+        const fam = keyFamily(key);
+        const list = prevByFamily.get(fam);
+        if (list)
+            list.push(key);
+        else
+            prevByFamily.set(fam, [key]);
+    }
+    const curByFamily = new Map();
+    current.forEach((el, i) => {
+        const fam = keyFamily(el.key);
+        const list = curByFamily.get(fam);
+        if (list)
+            list.push(i);
+        else
+            curByFamily.set(fam, [i]);
+    });
+    const out = current.map(() => null);
+    for (const [fam, idxs] of curByFamily) {
+        const prevKeys = prevByFamily.get(fam) ?? [];
+        const single = prevKeys.length <= 1 && idxs.length <= 1;
+        if (single || idxs.some((i) => current[i].byPosition)) {
+            for (const i of idxs)
+                out[i] = prev.has(current[i].key) ? current[i].key : null;
+            continue;
+        }
+        const free = new Set(prevKeys);
+        const take = (i, same) => {
+            for (const k of free) {
+                if (same(prev.get(k))) {
+                    out[i] = k;
+                    free.delete(k);
+                    return;
+                }
+            }
+        };
+        for (const i of idxs)
+            take(i, (p) => p.label === current[i].name && (p.href ?? null) === (current[i].href ?? null));
+        for (const i of idxs)
+            if (out[i] === null && current[i].href)
+                take(i, (p) => !!p.href && p.href === current[i].href);
+    }
+    return out;
+}
+/**
+ * Whether a box parked off the page comes back when it takes focus: a skip
+ * link. Either a link into this same document (the skip-link shape), or any
+ * focusable element a :focus rule moves. It must be reachable by Tab, or
+ * nothing ever brings it back.
+ */
+export function revealedOnFocus(el) {
+    if (!el.focusable)
+        return false;
+    return IN_PAGE_ANCHOR.test(el.href ?? "") || el.focusMoves === true;
+}
+/**
+ * Whether `other` is an adornment of the text field `field`: a clear button or
+ * icon lying wholly inside the padding the field reserves at its left or right
+ * edge. Text never runs under that padding, so nothing collides. An element
+ * that reaches into the text area is a real collision and is not an adornment.
+ */
+export function isFieldAdornment(field, other) {
+    const pad = field.fieldPad;
+    if (!pad)
+        return false;
+    const f = field.rect;
+    const r = other.rect;
+    const t = 4; // borders, and rounding to whole pixels
+    if (r.y < f.y - t || r.y + r.h > f.y + f.h + t)
+        return false;
+    const inLeft = pad.l > 0 && r.x >= f.x - t && r.x + r.w <= f.x + pad.l + t;
+    const inRight = pad.r > 0 && r.x >= f.x + f.w - pad.r - t && r.x + r.w <= f.x + f.w + t;
+    return inLeft || inRight;
+}
+/** Roles of the controls a click is aimed at; anything else with pointer-events:none is decoration. */
+const CONTROL_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "combobox",
+    "checkbox",
+    "radio",
+    "switch",
+    "tab",
+    "menuitem",
+    "file",
+    "searchbox",
+    "spinbutton",
+    "slider",
+    "option",
+]);
+/** Whether `overlay` is a decorative layer over `other` that lets clicks through to it. */
+export function isPassThroughOverlay(overlay, other) {
+    return overlay.passThrough === true && !CONTROL_ROLES.has(overlay.role) && overlay.rect.w * overlay.rect.h >= other.rect.w * other.rect.h;
+}
 /**
  * Deterministic geometry oracles — the checks people reach for screenshots to
  * do, computed from layout boxes instead: interactables rendered fully outside
@@ -539,8 +990,9 @@ export function geometryIssues(elements, viewport) {
         const { x, y, w, h } = el.rect;
         // Rects are DOCUMENT coords: below-the-fold content is normal; unreachable
         // means left/above the document origin, or absurdly far right (no page
-        // scrolls 3 viewports horizontally on purpose).
-        if (w > 0 && h > 0 && (x + w <= 0 || y + h <= 0 || x >= viewport.width * 3)) {
+        // scrolls 3 viewports horizontally on purpose). A skip link parked there
+        // until it takes focus is the accessibility pattern working.
+        if (w > 0 && h > 0 && (x + w <= 0 || y + h <= 0 || x >= viewport.width * 3) && !revealedOnFocus(el)) {
             issues.push(`${el.ref} ${el.role} "${el.name}" is rendered outside the reachable page area (${x},${y} ${w}×${h})`);
         }
         // Distinct from below-the-fold: this control's own container hides it and
@@ -608,6 +1060,15 @@ export function geometryIssues(elements, viewport) {
             // collision bugs that matter live in the content flow, not the chrome.
             if (a.chrome && b.chrome)
                 continue;
+            // An overlay with pointer-events:none cannot take a click meant for what
+            // it lies over. Only a non-control at least as large as the other counts:
+            // design systems also set it on disabled buttons, and a disabled button
+            // drawn over another is still a collision.
+            if (isPassThroughOverlay(a, b) || isPassThroughOverlay(b, a))
+                continue;
+            // A clear button or icon inside a text field's reserved padding.
+            if (isFieldAdornment(a, b) || isFieldAdornment(b, a))
+                continue;
             const area = overlapArea(a.rect, b.rect);
             const smaller = Math.min(a.rect.w * a.rect.h, b.rect.w * b.rect.h);
             if (smaller > 0 && area / smaller > 0.6) {
@@ -667,7 +1128,7 @@ export const MAIN_REGION_SCRIPT = `(() => {
   const landmarks = Array.from(document.querySelectorAll('main, [role="main"]')).filter(shown);
   const landmark = landmarks[0] || null;
   const region = landmark || document.body;
-  if (!region) return { landmark: false, heading: null, paragraphs: 0, chars: 0, controls: 0, media: 0 };
+  if (!region) return { landmark: false, heading: null, paragraphs: 0, chars: 0, controls: 0, media: 0, states: [], rest: 0, text: "" };
   const CHROME = 'header, nav, footer, aside, [role="banner"], [role="navigation"], [role="contentinfo"], [role="complementary"]';
   const outside = (n) => !landmark && !!n.closest(CHROME);
   const CONTROL = 'a[href], button, input, select, textarea, option, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [role="switch"], [role="combobox"]';
@@ -677,24 +1138,94 @@ export const MAIN_REGION_SCRIPT = `(() => {
   const level = h ? (/^H[1-6]$/.test(h.tagName) ? Number(h.tagName[1]) : Number(h.getAttribute("aria-level") || 2)) : 0;
   const heading = h ? { level, text: (h.textContent || "").replace(/\\s+/g, " ").trim().slice(0, 60) } : null;
   const paragraphs = inRegion("p").filter((n) => (n.textContent || "").trim()).length;
+  // Status regions: an alert, a live status, a busy or progress marker. What lies outside
+  // them is the page's own content; a main area with none is showing only its state.
+  const STATE = '[role="alert"], [role="status"], [aria-busy="true"], [role="progressbar"]';
+  const stateOf = (n) => {
+    const s = n.closest(STATE);
+    return s && (s === region || region.contains(s)) ? s : null;
+  };
+  const states = [];
+  for (const s of [region, ...inRegion(STATE)]) {
+    if (!s.matches(STATE)) continue;
+    const role = s.getAttribute("role");
+    const kind = role === "alert" || role === "status" || role === "progressbar" ? role : "busy";
+    if (!states.includes(kind)) states.push(kind);
+    if (s.getAttribute("aria-busy") === "true" && !states.includes("busy")) states.push("busy");
+  }
   let chars = 0;
+  let rest = 0;
+  let text = "";
   let seen = 0;
   const walker = document.createTreeWalker(region, NodeFilter.SHOW_TEXT);
   for (let t = walker.nextNode(); t && seen < 5000; t = walker.nextNode()) {
     seen += 1;
     const parent = t.parentElement;
     if (!parent || parent.closest('script, style, noscript, template, [aria-hidden="true"]') || parent.closest(CONTROL) || outside(parent) || !shown(parent)) continue;
-    chars += (t.textContent || "").replace(/\\s+/g, " ").trim().length;
+    const words = (t.textContent || "").replace(/\\s+/g, " ").trim();
+    chars += words.length;
+    if (!stateOf(parent)) rest += words.length;
+    if (words && text.length < 160) text = (text ? text + " " + words : words).slice(0, 160);
   }
+  const controls = inRegion(CONTROL);
+  const media = inRegion("img, svg, video, canvas, iframe, object, embed");
+  rest += [...headings, ...controls, ...media].filter((n) => !stateOf(n)).length;
   return {
     landmark: !!landmark,
     heading,
     paragraphs,
     chars,
-    controls: inRegion(CONTROL).length,
-    media: inRegion("img, svg, video, canvas, iframe, object, embed").length,
+    controls: controls.length,
+    media: media.length,
+    states,
+    rest,
+    text,
   };
 })()`;
+/**
+ * Whether text says only that something is on its way, e.g. "Loading…",
+ * "Loading orders...", "Please wait", once or repeated. Each sentence must
+ * open with the loading words and stay short.
+ */
+function isLoadingText(text) {
+    const parts = text
+        .split(/\.{1,3}|…/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return parts.length > 0 && parts.every((p) => /^(?:loading|please wait)\b[^!?]{0,30}$/i.test(p));
+}
+/**
+ * What a main area holding nothing but its state is showing, or null when it
+ * holds content of its own. A client-rendered app answers 200 for a path it
+ * does not have and draws its not-found or error view; a route still waiting
+ * on data after the page settled shows only a placeholder. Both read as a
+ * healthy page to a status code and an element count.
+ *
+ * - `error`: everything in the area is inside a `role="alert"` region that says something.
+ * - `loading`: everything is inside an `aria-busy="true"` region or a
+ *   progress bar, or inside a live status whose only words are a loading
+ *   message or that holds only a spinner, or (with no such marker at all)
+ *   the area's only words are a loading message.
+ *
+ * A live status saying anything else ("No orders yet") is an empty state,
+ * which is content, and so is an alert beside a heading or a control.
+ */
+export function mainState(m) {
+    const states = m.states ?? [];
+    const text = (m.text ?? "").trim();
+    if (states.length === 0) {
+        return !m.heading && m.controls === 0 && m.media === 0 && isLoadingText(text) ? "loading" : null;
+    }
+    if ((m.rest ?? 1) > 0)
+        return null;
+    // An alert with nothing in it is a live region waiting for a message, not a message.
+    if (states.includes("alert") && text !== "")
+        return "error";
+    if (states.includes("busy") || states.includes("progressbar"))
+        return "loading";
+    // A spinner inside a status, or a status saying it is loading; an empty one alone is just an empty main area.
+    return states.includes("status") && (isLoadingText(text) || (text === "" && m.media > 0)) ? "loading" : null;
+}
 /** Nothing at all in the region: no heading, no text, no control, no image or embed. */
 function mainIsEmpty(m) {
     return !m.heading && m.chars === 0 && m.controls === 0 && m.media === 0;