@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/critic-dom.ts

@@ -0,0 +1,951 @@
+// F126.1 — DOM/geometry composition critic (the deterministic half).
+//
+// Lens proves an element is in the DOM (expectVisible/expectText) and that a
+// surface matches a pixel baseline. Neither proves the layout HOLDS TOGETHER:
+// nothing overlapping, occluding, clipped, off-screen, or unreadable. A new
+// surface has no baseline at all, so first-render composition bugs are invisible.
+//
+// This engine answers "does this screen hold together?" with ZERO model calls —
+// one in-page measurement pass via document.elementFromPoint + getBoundingClientRect
+// + getComputedStyle. It is deterministic, millisecond-fast, names the exact
+// element (data-testid + selector + box), and is always on. The driver bug — a ✕
+// close-button painted ON TOP of a "shipped v0.2.0" badge, hiding its text, while
+// Lens reported green — is caught here as an `occlusion` finding.
+//
+// Vision (F126.2) is the complement for what geometry can't express ("looks
+// unbalanced / off-brand"). This file makes NO model calls.
+
+import type { Page } from 'playwright';
+
+export type CriticSeverity = 'high' | 'medium' | 'low';
+export type CriticKind =
+  | 'occlusion'
+  | 'overlap'
+  | 'clipped'
+  | 'off-viewport'
+  | 'zero-size'
+  | 'contrast'
+  | 'wiggle'
+  | 'unseen-before-action'
+  | 'nothing-to-judge';
+
+export interface CriticBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** A reference to the element that is covering another (occlusion findings). */
+export interface CriticRef {
+  testid: string | null;
+  selector: string;
+  tag: string;
+  label: string;
+}
+
+export interface DomFinding {
+  kind: CriticKind;
+  severity: CriticSeverity;
+  testid: string | null;
+  selector: string;
+  label: string;
+  box: CriticBox;
+  message: string;
+  /** Present on `occlusion` findings: what is painted on top. */
+  occludedBy?: CriticRef;
+}
+
+export interface DomCriticOptions {
+  /** Cap the scanned element set (bounds the O(n²) overlap pass). Default 1500. */
+  maxElements?: number;
+  /** Cap returned findings (highest-severity first). Default 120. */
+  maxFindings?: number;
+}
+
+/** Run the geometry critic against an already-navigated, settled page.
+ *  Returns findings sorted high→low severity. Makes no model calls. */
+export async function runDomCritic(page: Page, opts: DomCriticOptions = {}): Promise<DomFinding[]> {
+  const cfg = { maxElements: opts.maxElements ?? 1500 };
+  const raw = (await page.evaluate(inPageCritic, cfg).catch(() => [] as DomFinding[])) as DomFinding[];
+  const rank: Record<CriticSeverity, number> = { high: 0, medium: 1, low: 2 };
+  raw.sort((a, b) => rank[a.severity] - rank[b.severity]);
+  return raw.slice(0, opts.maxFindings ?? 120);
+}
+
+/** Rollup counts by severity — handy for the Review-AC gate (F126.4). */
+export function summarizeFindings(findings: DomFinding[]): {
+  total: number;
+  high: number;
+  medium: number;
+  low: number;
+} {
+  return {
+    total: findings.length,
+    high: findings.filter((f) => f.severity === 'high').length,
+    medium: findings.filter((f) => f.severity === 'medium').length,
+    low: findings.filter((f) => f.severity === 'low').length,
+  };
+}
+
+// ── The in-page measurement. Runs in the BROWSER (serialized by Playwright), so
+//    every helper is defined inside; no outer closure is available. ────────────
+
+/* eslint-disable */
+function inPageCritic(cfg: { maxElements: number }): DomFinding[] {
+  const W = window.innerWidth;
+  const H = window.innerHeight;
+  // The full scrollable page extent. An element below/beside the current fold
+  // but within this extent is reachable by scrolling (and shown whole in a
+  // fullPage capture), so it is NOT off-viewport — only elements off the
+  // reachable canvas are genuinely lost. F126.7.
+  // F126.8 — ask BOTH scrolling roots, because which one scrolls is a CSS choice.
+  //
+  // The original read only documentElement. Measured on xrt81.com 2026-08-17:
+  //
+  //     window.innerHeight                       800
+  //     documentElement.scrollHeight             800   ← what we asked
+  //     body.scrollHeight                       3180   ← where the page scrolls
+  //
+  // With `html { overflow-y: auto }` the document element does not grow; the body
+  // does. So docH came out 800, every element below the fold had zero overlap with
+  // the "reachable canvas", and the guard concluded a perfectly ordinary long page
+  // was off-viewport. xrt81 got 4 high + 57 medium findings on a healthy landing
+  // page — 3 of the 4 high ones false, all 57 medium false — and a high finding
+  // folds the gate to fail. `mode:'fullPage'` did not help, and could not: the rule
+  // never consulted the capture mode, it consulted the wrong element.
+  //
+  // That is worse than a noisy check. A gate that goes red on a sound page teaches
+  // people the red means nothing, and the one REAL finding then arrives as item 1
+  // of 61 with 60 false. The opposite end of the same failure as under-reporting,
+  // and it destroys the same signal.
+  const docW = Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0, W);
+  const docH = Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0, H);
+  const findings: DomFinding[] = [];
+
+  const INTERACTIVE_SEL =
+    'button,a[href],input:not([type=hidden]),select,textarea,[role=button],[role=link],' +
+    '[role=checkbox],[role=switch],[role=tab],[role=menuitem],[contenteditable=true],' +
+    '[tabindex]:not([tabindex="-1"])';
+  const OVERLAY_ROLES = new Set(['dialog', 'alertdialog', 'tooltip', 'menu', 'listbox']);
+
+  const isHidden = (el: Element, cs: CSSStyleDeclaration): boolean =>
+    cs.display === 'none' ||
+    cs.visibility === 'hidden' ||
+    cs.visibility === 'collapse' ||
+    parseFloat(cs.opacity || '1') < 0.02 ||
+    el.getAttribute('aria-hidden') === 'true' ||
+    (el as HTMLElement).hidden === true ||
+    // Not rendered at all — e.g. a descendant of a display:none ancestor, whose
+    // OWN computed display is still block but which is laid out nowhere. Without
+    // this it slips past the own-display check below and is mis-flagged as a
+    // high-severity zero-size defect (false RED). F126.6.
+    el.getClientRects().length === 0;
+
+  /** F074.35 — effectively invisible because an ANCESTOR is transparent.
+   *
+   *  isHidden already tests opacity, but on the element's OWN computed style —
+   *  and CSS opacity does NOT inherit, so a child of an opacity:0 parent
+   *  computes to 1 and sails past it. fd-sundhed's mobile compact bar is exactly
+   *  that: `fixed top-0` with `opacity-0 pointer-events-none` until you scroll,
+   *  and two of its children were reported as covered by the visible burger menu
+   *  on top of them (#18609). Nothing is taken from a user who cannot see it. */
+  const isTransparentThroughChain = (el: Element): boolean => {
+    let n: Element | null = el;
+    for (let d = 0; n && d < 12; d++) {
+      if (parseFloat(getComputedStyle(n).opacity || '1') < 0.02) return true;
+      n = n.parentElement;
+    }
+    return false;
+  };
+
+  /** F074.35 — nothing to lose behind this element.
+   *
+   *  Two rules with DIFFERENT scopes, deliberately, rather than one blanket skip:
+   *  invisible means nothing to read; unreachable means nothing to tap. A fully
+   *  visible paragraph with pointer-events:none that is covered still robs the
+   *  reader, so unreachability alone must not exempt text.
+   *
+   *  fd-sundhed's judgement, worth keeping: pointer-events is the strongest of
+   *  the signals, because it is the only one that directly says "a tap here does
+   *  not reach me" — opacity 0 can be one frame of a fade that is tappable a
+   *  moment later. Their bar carries both, so their data cannot separate them. */
+  const nothingToLose = (el: Element, cs: CSSStyleDeclaration, interactive: boolean): boolean =>
+    isTransparentThroughChain(el) || (interactive && cs.pointerEvents === 'none');
+
+  // Walk up: is this element (or an ancestor) an intentionally-stacked layer —
+  // a fixed/sticky bar, a modal, a tooltip, a menu? Those legitimately cover
+  // content; never flag them or treat them as bogus occluders.
+  const isIntentionalOverlay = (el: Element | null): boolean => {
+    let n: Element | null = el;
+    while (n && n !== document.body && n !== document.documentElement) {
+      const cs = getComputedStyle(n);
+      if (cs.position === 'fixed' || cs.position === 'sticky') return true;
+      const role = n.getAttribute('role');
+      if (role && OVERLAY_ROLES.has(role)) return true;
+      if (n.getAttribute('aria-modal') === 'true') return true;
+      if (n.hasAttribute('data-overlay')) return true;
+      n = n.parentElement;
+    }
+    return false;
+  };
+
+  const isInteractive = (el: Element): boolean => el.matches(INTERACTIVE_SEL);
+
+  // Element owns visible text if it has a direct non-whitespace text node.
+  const ownsText = (el: Element): boolean => {
+    for (const node of Array.from(el.childNodes)) {
+      if (node.nodeType === 3 && (node.textContent || '').trim().length > 0) return true;
+    }
+    return false;
+  };
+
+  const labelOf = (el: Element): string => {
+    const tid = el.getAttribute('data-testid');
+    if (tid) return tid;
+    const txt = (el.textContent || '').trim().replace(/\s+/g, ' ');
+    if (txt) return txt.slice(0, 40);
+    const id = (el as HTMLElement).id;
+    if (id) return '#' + id;
+    return el.tagName.toLowerCase();
+  };
+
+  /** One step of a positional path: tag, first class, and an nth-of-type index
+   *  when the parent holds more than one of that tag. */
+  const step = (el: Element): string => {
+    const tag = el.tagName.toLowerCase();
+    const cls = (el.getAttribute('class') || '').trim().split(/\s+/).filter(Boolean)[0];
+    const base = cls ? `${tag}.${cls}` : tag;
+    const parent = el.parentElement;
+    if (!parent) return base;
+    const sameTag = Array.from(parent.children).filter(
+      (c) => c.tagName === el.tagName,
+    );
+    if (sameTag.length < 2) return base;
+    return `${base}:nth-of-type(${sameTag.indexOf(el) + 1})`;
+  };
+
+  /** How a finding names its element.
+   *
+   *  F074.33: this used to fall back to the BARE TAG. A finding could read
+   *  '"a" is covered by "svg"' with no way to tell WHICH a and WHICH svg — two
+   *  unrelated links produced identical selectors, so a reader reasonably
+   *  assumed the nesting visible in their own markup and went looking at the
+   *  wrong element (fd-sundhed, #18602, twice). An unidentifiable finding is
+   *  worse than no finding: it costs someone an investigation and then costs
+   *  the tool its credibility.
+   *
+   *  A testid or id still wins outright — they are stable and human-meaningful.
+   *  Otherwise build a short positional path, which is ugly but unambiguous. */
+  const selectorOf = (el: Element): string => {
+    const tid = el.getAttribute('data-testid');
+    if (tid) return `[data-testid="${tid}"]`;
+    const id = (el as HTMLElement).id;
+    if (id) return `#${id}`;
+    const parts: string[] = [step(el)];
+    let n = el.parentElement;
+    // Up to three ancestors, stopping early at a testid/id — that anchor is far
+    // more useful to a human than another two tag names.
+    for (let d = 0; n && d < 3 && n.tagName !== 'BODY'; d++) {
+      const anchorTid = n.getAttribute('data-testid');
+      const anchorId = (n as HTMLElement).id;
+      if (anchorTid) {
+        parts.unshift(`[data-testid="${anchorTid}"]`);
+        break;
+      }
+      if (anchorId) {
+        parts.unshift(`#${anchorId}`);
+        break;
+      }
+      parts.unshift(step(n));
+      n = n.parentElement;
+    }
+    return parts.join(' > ');
+  };
+
+  const refOf = (el: Element): CriticRef => ({
+    testid: el.getAttribute('data-testid'),
+    selector: selectorOf(el),
+    tag: el.tagName.toLowerCase(),
+    label: labelOf(el),
+  });
+
+  const boxOf = (r: DOMRect): CriticBox => ({
+    x: Math.round(r.left),
+    y: Math.round(r.top),
+    w: Math.round(r.width),
+    h: Math.round(r.height),
+  });
+
+  // Off-screen positioning is often an intentional scroll/overflow container
+  // (carousel, virtualized list, off-canvas drawer). If an ancestor clips on the
+  // axis the element sits outside of, the element is deliberately out-of-view.
+  const isScrollClipped = (el: Element, r: DOMRect): boolean => {
+    let n = el.parentElement;
+    while (n && n !== document.body) {
+      const cs = getComputedStyle(n);
+      const clipsX = cs.overflowX === 'auto' || cs.overflowX === 'scroll' || cs.overflowX === 'hidden';
+      const clipsY = cs.overflowY === 'auto' || cs.overflowY === 'scroll' || cs.overflowY === 'hidden';
+      if (clipsX || clipsY) {
+        const a = n.getBoundingClientRect();
+        const cx = r.left + r.width / 2;
+        const cy = r.top + r.height / 2;
+        if (clipsX && (cx < a.left - 1 || cx > a.right + 1)) return true;
+        if (clipsY && (cy < a.top - 1 || cy > a.bottom + 1)) return true;
+      }
+      n = n.parentElement;
+    }
+    return false;
+  };
+
+  // The main document itself scrolls (a long page, or a fullPage capture) — an
+  // element within the page's scrollable extent is reachable, not off-viewport.
+  // isScrollClipped only covers nested scroll containers; this covers the page. F126.7.
+  const isReachableByPageScroll = (r: DOMRect): boolean => {
+    const dl = r.left + window.scrollX;
+    const dt = r.top + window.scrollY;
+    const dr = r.right + window.scrollX;
+    const db = r.bottom + window.scrollY;
+    const ix = Math.max(0, Math.min(dr, docW) - Math.max(dl, 0));
+    const iy = Math.max(0, Math.min(db, docH) - Math.max(dt, 0));
+    const area = r.width * r.height;
+    return area > 0 && (ix * iy) / area >= 0.25;
+  };
+
+  /** F126.22 — the part of the page an element can actually be SEEN through:
+   *  the viewport intersected with every ancestor that clips on that axis
+   *  (overflow auto / scroll / hidden / clip). A point outside it is scrolled
+   *  out of view, not covered — elementFromPoint there hits whatever is behind. */
+  const clipCache = new Map<Element, { l: number; t: number; r: number; b: number }>();
+  const clipOf = (el: Element) => {
+    const hit = clipCache.get(el);
+    if (hit) return hit;
+    let l = 0, t = 0, r = W, b = H;
+    const clips = (v: string) => v === 'auto' || v === 'scroll' || v === 'hidden' || v === 'clip';
+    for (let p = el.parentElement; p && p !== document.documentElement; p = p.parentElement) {
+      const pcs = getComputedStyle(p);
+      const cx = clips(pcs.overflowX), cy = clips(pcs.overflowY);
+      if (!cx && !cy) continue;
+      const pr = p.getBoundingClientRect();
+      if (cx) { l = Math.max(l, pr.left); r = Math.min(r, pr.right); }
+      if (cy) { t = Math.max(t, pr.top); b = Math.min(b, pr.bottom); }
+    }
+    const out = { l, t, r, b };
+    clipCache.set(el, out);
+    return out;
+  };
+
+  // ── Collect candidates ──────────────────────────────────────────────────
+  interface Cand {
+    el: Element;
+    r: DOMRect;
+    cs: CSSStyleDeclaration;
+    interactive: boolean;
+    text: boolean;
+  }
+  const cands: Cand[] = [];
+  const all = Array.from(document.querySelectorAll('body *')).slice(0, cfg.maxElements);
+  for (const el of all) {
+    const interactive = isInteractive(el);
+    const text = ownsText(el);
+    if (!interactive && !text) continue;
+    const cs = getComputedStyle(el);
+    const r = el.getBoundingClientRect();
+    cands.push({ el, r, cs, interactive, text });
+  }
+
+  // ── F074.31 — text placed just before an ALWAYS-VISIBLE control, rendered
+  //    below the fold. DOM order is not visual order when the control is fixed
+  //    or sticky: an author who writes the guidance immediately before the
+  //    approve button has stated an intent the layout then breaks, and the user
+  //    can act without ever reading it (fd-sundhed, 2026-08-04 — a manager could
+  //    press Approve having never seen the guidance; their own
+  //    indexOf(box) < indexOf(button) test was green throughout).
+  //
+  //    Deliberately NOT the broader rule that was proposed ("if any fixed/sticky
+  //    control is on screen, stop waiving below-fold findings on this page") —
+  //    that flags every below-fold element on any long page with a sticky nav,
+  //    and noise that trains people to ignore the critic costs more than the bug.
+  //    The DOM adjacency is what makes this specific and what carries the intent.
+  const inViewport = (r: DOMRect): boolean => {
+    const ix = Math.max(0, Math.min(r.right, W) - Math.max(r.left, 0));
+    const iy = Math.max(0, Math.min(r.bottom, H) - Math.max(r.top, 0));
+    return r.width > 0 && r.height > 0 && (ix * iy) / (r.width * r.height) >= 0.5;
+  };
+
+  /** A control is "always visible" when IT or an ancestor is fixed/sticky — in
+   *  real markup the buttons sit INSIDE a fixed action bar, so checking only the
+   *  button itself finds nothing (it is position:static). The bar is also the
+   *  right anchor for adjacency: the guidance is written before the BAR. */
+  const stickyHost = (el: Element): { host: Element; pos: string } | null => {
+    let n: Element | null = el;
+    for (let d = 0; n && d < 6; d++) {
+      const pos = getComputedStyle(n).position;
+      if (pos === 'fixed' || pos === 'sticky') return { host: n, pos };
+      n = n.parentElement;
+    }
+    return null;
+  };
+
+  /** What the author wrote IMMEDIATELY before this: its previous sibling, and its
+   *  parent's. Only the immediate one — "just above the button" is the intent we
+   *  can read from markup; anything looser starts matching unrelated content that
+   *  merely happens to appear earlier in the document. */
+  const domPredecessors = (start: Element): Element[] => {
+    const out: Element[] = [];
+    let node: Element | null = start;
+    for (let depth = 0; node && depth < 2; depth++) {
+      if (node.previousElementSibling) out.push(node.previousElementSibling);
+      node = node.parentElement;
+    }
+    return out;
+  };
+
+  const pushed = new Set<string>();
+  const push = (f: DomFinding) => {
+    const key = `${f.kind}|${f.selector}|${f.occludedBy?.selector ?? ''}`;
+    if (pushed.has(key)) return;
+    pushed.add(key);
+    findings.push(f);
+  };
+
+  // F074.31 — run before the per-element checks so the finding is reported
+  // against the CONTROL that stays visible, which is what a reader looks for.
+  const visibleTextCands = cands.filter((c) => c.text && !isHidden(c.el, c.cs));
+  for (const c of cands) {
+    if (!c.interactive || isHidden(c.el, c.cs)) continue;
+    // "Always visible" = it, or the bar it sits in, does not scroll away.
+    const anchored = stickyHost(c.el);
+    if (!anchored) continue;
+    const pos = anchored.pos;
+    if (!inViewport(c.r)) continue;
+
+    for (const p of domPredecessors(anchored.host)) {
+      const hit = visibleTextCands.find((t2) => t2.el === p || p.contains(t2.el));
+      if (!hit) continue;
+      // A whole page section is not "the guidance right above the button".
+      if (hit.r.height > H * 1.5) continue;
+      // The whole signal is "DOM adjacency implied visual adjacency, and the
+      // layout broke that". The implication only exists while the text is in
+      // NORMAL FLOW — an absolutely/fixed-positioned block was explicitly placed
+      // somewhere, so its position in the markup promised nothing and there is no
+      // contradicted intent. Without this, any fixed widget whose preceding
+      // sibling happens to be a positioned block far down the page fires.
+      const hp = hit.cs.position;
+      if (hp === 'absolute' || hp === 'fixed') continue;
+      // Below the fold specifically — scrolled-past content is a different case.
+      if (inViewport(hit.r) || hit.r.top < H * 0.9) continue;
+      push({
+        kind: 'unseen-before-action',
+        severity: 'high',
+        testid: hit.el.getAttribute('data-testid'),
+        selector: selectorOf(hit.el),
+        label: labelOf(hit.el),
+        box: boxOf(hit.r),
+        message:
+          `"${labelOf(hit.el)}" is written immediately before "${labelOf(c.el)}" in the DOM, but that ` +
+          `${pos} control is on screen while this text is ${Math.round(hit.r.top - H)}px below the fold — ` +
+          'the user can act without ever reading it.',
+      });
+      break; // one finding per always-visible control
+    }
+  }
+
+  // ── Per-element checks ──────────────────────────────────────────────────
+  for (const c of cands) {
+    const { el, r, cs } = c;
+
+    // Intentionally-hidden or not-rendered elements (incl. descendants of a
+    // display:none ancestor) are excluded BEFORE any severity is assigned —
+    // otherwise a laid-out-nowhere control is mis-flagged as a zero-size defect
+    // (the false RED this story fixes). F126.6.
+    if (isHidden(el, cs)) continue;
+
+    // zero-size interactive — rendered (in layout) but unclickable.
+    if (c.interactive && (r.width < 2 || r.height < 2)) {
+      push({
+        kind: 'zero-size',
+        severity: 'high',
+        testid: el.getAttribute('data-testid'),
+        selector: selectorOf(el),
+        label: labelOf(el),
+        box: boxOf(r),
+        message: `Interactive element "${labelOf(el)}" has ~zero size (${Math.round(r.width)}×${Math.round(r.height)}px) — present but unusable.`,
+      });
+      continue; // a 0-size element can't meaningfully overlap/occlude
+    }
+
+    if (r.width <= 0 || r.height <= 0) continue;
+
+    // off-viewport — substantially outside the viewport, not in a scroll container.
+    const ix = Math.max(0, Math.min(r.right, W) - Math.max(r.left, 0));
+    const iy = Math.max(0, Math.min(r.bottom, H) - Math.max(r.top, 0));
+    const onScreen = (ix * iy) / (r.width * r.height);
+    if (
+      onScreen < 0.25 &&
+      !isReachableByPageScroll(r) &&
+      !isScrollClipped(el, r) &&
+      !isIntentionalOverlay(el)
+    ) {
+      // F126.18 — SAY WHAT DECIDED IT. The gate above is `!isReachableByPageScroll`,
+      // which compares the element against the scrollable canvas (docW/docH, the
+      // documentElement ∪ body union F126.9 had to introduce). "Outside the viewport"
+      // is equally true of anything below the fold, so a reader who trusts the words
+      // reads a real finding as a fold — helpdesk did exactly that on 20 Sep 2026,
+      // waived it with evidence, then had to retract and correct two review rows on
+      // closed cards. The measurement was in hand and thrown away.
+      //
+      // Page coordinates, same basis as isReachableByPageScroll.
+      const pastRight = Math.round(r.right + window.scrollX - docW);
+      const pastBottom = Math.round(r.bottom + window.scrollY - docH);
+      const pastLeft = Math.round(0 - (r.left + window.scrollX));
+      const pastTop = Math.round(0 - (r.top + window.scrollY));
+      // Report the axis actually violated — a horizontally unreachable element must
+      // not be described with a vertical number.
+      const axes: Array<[number, string]> = [
+        [pastBottom, `its bottom is ${pastBottom}px past the scrollable canvas (${Math.round(r.bottom + window.scrollY)} vs ${Math.round(docH)})`],
+        [pastTop, `its top is ${pastTop}px above the scrollable canvas (${Math.round(r.top + window.scrollY)} vs 0)`],
+        [pastRight, `its right edge is ${pastRight}px past the scrollable canvas (${Math.round(r.right + window.scrollX)} vs ${Math.round(docW)})`],
+        [pastLeft, `its left edge is ${pastLeft}px before the scrollable canvas (${Math.round(r.left + window.scrollX)} vs 0)`],
+      ];
+      const worst = axes.reduce((a, b) => (b[0] > a[0] ? b : a));
+      // The deciding fact first; the percentage stays because it is true and useful,
+      // just not what gated the finding.
+      const why = worst[0] > 0
+        ? `cannot be reached by scrolling — ${worst[1]}`
+        : `cannot be reached by scrolling — less than 25% of it lies within the scrollable canvas (${Math.round(docW)}×${Math.round(docH)})`;
+      push({
+        kind: 'off-viewport',
+        severity: c.interactive ? 'high' : 'medium',
+        testid: el.getAttribute('data-testid'),
+        selector: selectorOf(el),
+        label: labelOf(el),
+        box: boxOf(r),
+        message: `${c.interactive ? 'Interactive element' : 'Content'} "${labelOf(el)}" ${why}. ${Math.round((1 - onScreen) * 100)}% outside the viewport.`,
+      });
+    }
+
+    // clipped text — hard clip with no ellipsis affordance (ellipsis = intentional).
+    if (c.text) {
+      const he = el as HTMLElement;
+      const overflowsX = he.scrollWidth > he.clientWidth + 1;
+      const overflowsY = he.scrollHeight > he.clientHeight + 1;
+      const hardClip =
+        (cs.overflowX === 'hidden' || cs.overflowX === 'clip' || cs.overflowY === 'hidden' || cs.overflowY === 'clip') &&
+        cs.textOverflow !== 'ellipsis';
+      if ((overflowsX || overflowsY) && hardClip) {
+        push({
+          kind: 'clipped',
+          severity: c.interactive ? 'high' : 'medium',
+          testid: el.getAttribute('data-testid'),
+          selector: selectorOf(el),
+          label: labelOf(el),
+          box: boxOf(r),
+          message: `Text in "${labelOf(el)}" is clipped (content ${overflowsX ? he.scrollWidth + '>' + he.clientWidth + 'px wide' : he.scrollHeight + '>' + he.clientHeight + 'px tall'}) with no ellipsis.`,
+        });
+      }
+    }
+
+    // contrast — text colour vs a resolvable SOLID background (skip gradients/images).
+    //
+    // ONE EXEMPTION, and it is WCAG's own, not ours (F280.16). SC 1.4.3 says in
+    // as many words: "Text that is part of a logo or brand name has no minimum
+    // contrast requirement." A wordmark is a picture that happens to be made of
+    // letters — its colours ARE the brand, and darkening them to pass a ratio
+    // changes the logo rather than fixing a readability problem.
+    //
+    // Deliberately NARROW so it cannot become a mute button:
+    //   · opt-in per element, never inferred from a class name or a testid;
+    //   · the value must be exactly "logotype" — any other value is ignored, so
+    //     `data-contrast-exempt="true"` does nothing;
+    //   · it exempts CONTRAST ONLY. Clipping, occlusion and the wiggle rule
+    //     still apply to a logo, because those are not about the standard's
+    //     logotype carve-out.
+    // It uses closest() because a wordmark is usually a link wrapping spans, and
+    // the finding lands on the innermost text node.
+    if (c.text && !el.closest('[data-contrast-exempt="logotype"]')) {
+      const fg = parseRGB(cs.color);
+      if (fg && fg.a >= 0.999 && !(el as HTMLElement).matches(':disabled') && el.getAttribute('aria-disabled') !== 'true') {
+        const bg = resolveSolidBg(el);
+        if (bg) {
+          const ratio = contrast(fg, bg);
+          const size = parseFloat(cs.fontSize || '16');
+          const bold = parseInt(cs.fontWeight || '400', 10) >= 700;
+          const large = size >= 24 || (size >= 18.66 && bold);
+          const min = large ? 3.0 : 4.5;
+          if (ratio < min) {
+            push({
+              kind: 'contrast',
+              severity: ratio < min - 1 ? 'high' : 'medium',
+              testid: el.getAttribute('data-testid'),
+              selector: selectorOf(el),
+              label: labelOf(el),
+              box: boxOf(r),
+              message: `Low contrast on "${labelOf(el)}": ${ratio.toFixed(2)}:1 (WCAG AA needs ${min}:1).`,
+            });
+          }
+        }
+      }
+    }
+
+    // occlusion — sample points; is the element's own area covered by a
+    // non-overlay, non-relative element? (elementFromPoint ignores
+    // pointer-events:none, so decorative overlays don't false-positive.)
+    const samples: Array<[number, number, boolean]> = [
+      [r.left + r.width / 2, r.top + r.height / 2, true], // centre (weighted)
+      [r.left + r.width * 0.2, r.top + r.height * 0.3, false],
+      [r.left + r.width * 0.8, r.top + r.height * 0.3, false],
+      [r.left + r.width * 0.2, r.top + r.height * 0.7, false],
+      [r.left + r.width * 0.8, r.top + r.height * 0.7, false],
+    ];
+    // F126.22 — a point SCROLLED OUT of a clipping ancestor is not covered, it is
+    // out of view: elementFromPoint there hits whatever is painted behind the
+    // scroller and reads as occlusion. Measured on a deliberate springlist
+    // (overflow-y:auto, max-height:60vh): items 26–31 below the fold gave 15 high
+    // findings on a list that looked right. So the sampled area is the element
+    // INTERSECTED with every clipping ancestor, the same way the viewport already is.
+    const { l: clipL, t: clipT, r: clipR, b: clipB } = clipOf(el);
+    let centreCovered = false;
+    let edgeCovered = 0;
+    let occluder: Element | null = null;
+    for (const [sx, sy, isCentre] of samples) {
+      if (sx < 0 || sy < 0 || sx > W || sy > H) continue;
+      if (sx < clipL || sx > clipR || sy < clipT || sy > clipB) continue;
+      const top = document.elementFromPoint(sx, sy);
+      if (!top || top === el || el.contains(top) || top.contains(el)) continue;
+      if (isIntentionalOverlay(top)) continue;
+      // F126.27 — elementFromPoint DOES return an opacity:0 / visibility:hidden
+      // layer, but a layer nobody can see covers nothing. trailmem's hero stacks
+      // two crossfading title spans on purpose; the transparent one was named as
+      // covering the visible one (run 758697dd, 7 high). Same test the covered
+      // side already uses (nothingToLose), now on the occluder side too.
+      if (getComputedStyle(top).visibility === 'hidden' || isTransparentThroughChain(top)) continue;
+      occluder = top;
+      if (isCentre) centreCovered = true;
+      else edgeCovered++;
+    }
+    if (occluder && (centreCovered || edgeCovered >= 1) && !nothingToLose(el, cs, c.interactive)) {
+      const coversMeaning = centreCovered || c.text; // text whose edge is covered loses content
+      push({
+        kind: 'occlusion',
+        severity: c.interactive || (c.text && centreCovered) ? 'high' : coversMeaning ? 'medium' : 'low',
+        testid: el.getAttribute('data-testid'),
+        selector: selectorOf(el),
+        label: labelOf(el),
+        box: boxOf(r),
+        message: `"${labelOf(el)}" is covered by "${labelOf(occluder)}"${centreCovered ? ' (its centre is hidden)' : ' (partly hidden)'}.`,
+        occludedBy: refOf(occluder),
+      });
+    }
+  }
+
+  // ── F074.33 — say so when there was nothing to judge. ─────────────────────
+  //    fd-sundhed's app has a 1.5s splash as `fixed inset-0 z-[100]`; the critic
+  //    returned pass with ZERO findings three times, because there was literally
+  //    nothing on screen. They caught it only by fetching the screenshot and
+  //    looking. A critic finding nothing behind a full-screen overlay is
+  //    indistinguishable from one finding nothing on a clean screen — and it is
+  //    the most convincing green run you can get.
+  //
+  //    ADVISORY on purpose ('low'), never a failure: covering the viewport is
+  //    exactly what a legitimate modal, splash or cookie wall does. The point is
+  //    that the report should not read as "we looked and it was fine".
+  for (const c of cands) {
+    if (isHidden(c.el, c.cs)) continue;
+    const pos = c.cs.position;
+    if (pos !== 'fixed' && pos !== 'absolute') continue;
+    const covers = (Math.min(c.r.right, W) - Math.max(c.r.left, 0)) *
+      (Math.min(c.r.bottom, H) - Math.max(c.r.top, 0));
+    if (covers < 0.9 * W * H) continue;
+    // Only when it is actually ON TOP — a full-bleed background container is not
+    // hiding anything.
+    const mid = document.elementFromPoint(W / 2, H / 2);
+    if (!mid || !(c.el === mid || c.el.contains(mid))) continue;
+    push({
+      kind: 'nothing-to-judge',
+      severity: 'low',
+      testid: c.el.getAttribute('data-testid'),
+      selector: selectorOf(c.el),
+      label: labelOf(c.el),
+      box: boxOf(c.r),
+      message:
+        `"${labelOf(c.el)}" covers ${Math.round((covers / (W * H)) * 100)}% of the viewport — ` +
+        'the critic judged this overlay, not the screen behind it. A run with no findings here ' +
+        'means "nothing was visible to judge", not "the screen is fine".',
+    });
+    break; // one is enough; it is a statement about the run, not a list
+  }
+
+  // ── Pairwise overlap — sibling/cousin collisions occlusion-sampling missed.
+  //    Conservative: real intersection of two non-nested, non-overlay elements
+  //    where at least one is interactive/text. Skipped if the pair already has an
+  //    occlusion finding. ───────────────────────────────────────────────────
+  const overlapSet = cands
+    .filter((c) => !isHidden(c.el, c.cs) && c.r.width > 0 && c.r.height > 0 && !isIntentionalOverlay(c.el))
+    .slice(0, 400);
+  for (let i = 0; i < overlapSet.length; i++) {
+    for (let j = i + 1; j < overlapSet.length; j++) {
+      const a = overlapSet[i]!;
+      const b = overlapSet[j]!;
+      if (a.el.contains(b.el) || b.el.contains(a.el)) continue;
+      // F074.35 — same rule as the sampler: an element the user can neither see
+      // nor reach has nothing to lose. Applied to BOTH so they cannot disagree.
+      if (nothingToLose(a.el, a.cs, a.interactive) || nothingToLose(b.el, b.cs, b.interactive)) continue;
+      // F126.22 — only the VISIBLE parts can collide: an item scrolled out of a
+      // list sits under whatever follows the list without anything being hidden.
+      const ca = clipOf(a.el), cb = clipOf(b.el);
+      const ox = Math.max(0, Math.min(a.r.right, b.r.right, ca.r, cb.r) - Math.max(a.r.left, b.r.left, ca.l, cb.l));
+      const oy = Math.max(0, Math.min(a.r.bottom, b.r.bottom, ca.b, cb.b) - Math.max(a.r.top, b.r.top, ca.t, cb.t));
+      const area = ox * oy;
+      if (area <= 0) continue;
+      const minArea = Math.min(a.r.width * a.r.height, b.r.width * b.r.height);
+      if (area < Math.max(64, 0.25 * minArea)) continue;
+      const key = `occlusion|${selectorOf(a.el)}|${selectorOf(b.el)}`;
+      const keyR = `occlusion|${selectorOf(b.el)}|${selectorOf(a.el)}`;
+      if (pushed.has(key) || pushed.has(keyR)) continue;
+      push({
+        kind: 'overlap',
+        severity: 'medium',
+        testid: a.el.getAttribute('data-testid'),
+        selector: selectorOf(a.el),
+        label: labelOf(a.el),
+        box: boxOf(a.r),
+        message: `"${labelOf(a.el)}" and "${labelOf(b.el)}" overlap by ${Math.round(area)}px² (${Math.round((area / minArea) * 100)}% of the smaller).`,
+        occludedBy: refOf(b.el),
+      });
+    }
+  }
+
+  // ── F074.70 — THE WIGGLE. At a phone width the page must not scroll sideways.
+  //
+  // Christian, 2026-08-28, on Settings → Secrets: "Vildeste wiggle jeg til dato
+  // har set dig lave". Measured on production at 393px:
+  //
+  //     secrets-table   overflow-x visible   width 547
+  //     secrets-root    overflow-x visible   clientWidth 359   scrollWidth 571
+  //     settings-root   overflow-x visible   clientWidth 393   scrollWidth 588
+  //
+  // 195px of page hanging past the viewport, and the critic said nothing.
+  //
+  // WHY IT SAID NOTHING, because the near-miss is the whole design of this rule:
+  // `isReachableByPageScroll` asks whether an element sits inside `docW` — and
+  // docW is grown BY the overflow. So a page you can drag sideways is, by that
+  // test, perfectly reachable. Reachability was never the question; whether the
+  // page should scroll sideways AT ALL is.
+  //
+  // ONE finding per run, never one per element. This file has already paid for
+  // the opposite (57 false mediums on a healthy xrt81 page, F126.8): a gate that
+  // goes red in bulk teaches people the red means nothing. So the page-level fact
+  // is the finding, and the worst offender is NAMED INSIDE it as the place to look.
+  //
+  // Phone widths only. A 1280px desktop with a wide table is a different design
+  // conversation; a phone that drags is simply broken.
+  if (W <= 820) {
+    // TWO WAYS A PHONE GOES WRONG, and the first version of this rule only had one.
+    //
+    // Measured on the very page that prompted it, AFTER the fix: docW read 393 on a
+    // 393px viewport BOTH before and after. The document never grew, because an
+    // ancestor was clipping with overflow-x:hidden — so a check keyed on docW alone
+    // would have reported this page clean while a column sat cut off at the edge.
+    // That is the same trap the fleet already has written down: scrollWidth cannot
+    // see clipped overflow. Building the check against only the half I had just
+    // measured would have shipped a guard blind to the defect that motivated it.
+    //
+    // So: the page GROWING is one signal, and content spilling past the viewport
+    // with nothing SCROLLABLE holding it is the other. `hidden` contains the drag
+    // and loses the content; `auto`/`scroll` is a scroller doing its job.
+    const firstOverflowAncestor = (el: Element): string | null => {
+      let p: Element | null = el.parentElement;
+      while (p && p !== document.body) {
+        const ox = getComputedStyle(p).overflowX;
+        if (ox === 'auto' || ox === 'scroll' || ox === 'hidden') return ox;
+        p = p.parentElement;
+      }
+      return null;
+    };
+    let clipped: { el: Element; r: DOMRect } | null = null;
+    for (const c of cands) {
+      if (c.r.width <= 0 || c.r.right <= W + 1) continue;
+      const ox = firstOverflowAncestor(c.el);
+      if (ox === 'auto' || ox === 'scroll') continue; // reachable by design
+      if (!clipped || c.r.right > clipped.r.right) clipped = { el: c.el, r: c.r };
+    }
+
+    // ── F126.16 — A THIRD SIGNAL: CONTENT SPILLING OUT OF ITS OWN BOX ─────
+    //
+    // Both signals above read `getBoundingClientRect()`, which is the element's
+    // BOX. Content can overflow its own box while the box stays comfortably
+    // inside the viewport, and a rect is structurally blind to that.
+    //
+    // Measured on /dashboard/resume at 393px, 11 Sep 2026 — the wiggle Christian
+    // reported for the FIFTH time, which this rule watched go past:
+    //
+    //     every element's right edge   inside 393px, in FOUR runs on TWO engines
+    //     resume-timeline-root         clientWidth 361   scrollWidth 507
+    //     its overflow-x               visible
+    //
+    // The comment at the top of this rule already quoted the correct measurement
+    // (`clientWidth 359 scrollWidth 571`) and the code below it asked about
+    // rects. It knew the right question and asked a different one.
+    //
+    // THE CONDITION IS "REACHES PAST THE VIEWPORT", NOT "IS WIDER THAN ITS BOX".
+    // That distinction is what keeps this from drowning the rule in furniture:
+    // a tooltip label inside a 14px icon is legitimately wider than its trigger.
+    // Measured on the same page after the fix — the three widest raw ratios were
+    // all `cm-tip` elements (71-in-14, 77-in-46, 56-in-32), none of which is
+    // anywhere near the edge. Laying the content out from the element's OWN left
+    // edge answers the question the owner is actually asking: does anything end
+    // up off the side of his phone.
+    //
+    // The usual cause, named in the message so the reader gets a mechanism and
+    // not just a number: a long unbroken token (a mail subject, an id, a URL) in
+    // a flex child. `min-width: 0` lets the BOX shrink and does nothing to the
+    // TEXT — `overflow-wrap: anywhere` is what wraps it, and `break-word` does
+    // not, because it leaves min-content width untouched.
+    let spilled: { el: Element; r: DOMRect; right: number; over: number } | null = null;
+    for (const c of cands) {
+      const el = c.el as HTMLElement;
+      const cw = el.clientWidth;
+      const sw = el.scrollWidth;
+      if (cw <= 0 || sw <= cw + 1) continue;
+
+      // ── F126.19 — A FORM CONTROL SCROLLS ITS OWN VALUE, AND `overflow-x`
+      //    DOES NOT SAY SO ────────────────────────────────────────────────
+      //
+      // The guard on the next line exists for exactly this case: "it holds its
+      // own overflow, so the page is not the one spilling." It cannot catch an
+      // input, because a text control's computed overflow-x is NOT `auto` — the
+      // scrolling is in the widget, not in the box model. So the one family of
+      // elements whose content is ALWAYS allowed to be wider than its box walked
+      // straight through the exemption written for it.
+      //
+      // Reported by sanneandersen on /da/admin/qigong/rejse at 393px:
+      //
+      //     widest offender "qigong-lesson-title" holds content 513px wide
+      //     inside a 235px box  →  wiggle, high, "reaches 120px past the viewport"
+      //
+      // The box is 235px. The 513px is the TITLE SOMEBODY TYPED. Nothing is off
+      // the side of the phone.
+      //
+      // WHY THIS ONE COULD NOT BE LEFT TO THE CONSUMER TO SILENCE: the message
+      // below prints its own remedy — `overflow-wrap: anywhere` — and an input
+      // value never wraps at any CSS setting. The only way to drive the number
+      // to zero is a field wider than its longest possible value, which is not a
+      // thing you can write for an arbitrary title. An unachievable finding is
+      // worse than a wrong one: a wrong one gets corrected, an unachievable one
+      // gets waived, and the waiver gets faster every time (F126.18, helpdesk).
+      //
+      // NARROW ON PURPOSE. This exempts the CONTROL, not the layout around it:
+      // a div with a long unbroken token is still a real spill, an input whose
+      // BOX overflows the viewport is still caught by the rect signal above, and
+      // the `clipped` rule is untouched.
+      const tag = el.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') continue;
+
+      const ox = getComputedStyle(el).overflowX;
+      if (ox === 'auto' || ox === 'scroll') continue; // it scrolls its own content
+      // F126.27 — it CLIPS its own content (a truncated label: nowrap + hidden +
+      // ellipsis). The content ends at the element's own box, so it cannot move
+      // the page; scrollWidth > clientWidth here is the truncation working.
+      // Reported by three sessions on 11 Oct 2026 (mockup-frame source line, a
+      // recent-project row). Text cut with NO ellipsis is still the `clipped`
+      // rule's finding; content clipped by an ANCESTOR (SPILL_ABSORBED) still
+      // passes through here, because its own overflow-x is visible.
+      if (ox === 'hidden' || ox === 'clip') continue;
+      const anc = firstOverflowAncestor(el);
+      if (anc === 'auto' || anc === 'scroll') continue; // reachable by design
+      const right = c.r.left + sw;
+      const over = right - W;
+      // NO `if (over <= 0) continue` HERE, and that absence is deliberate.
+      //
+      // I wrote one, and a mutation proved it could never fire: picking the
+      // LARGEST `over` already excludes anything that does not reach the edge,
+      // and `overBy > 1` below suppresses the finding when nothing does. Removing
+      // the guard reddened nothing — twice, including against a fixture built
+      // specifically to catch it (a tooltip beside a real spill).
+      //
+      // So it was dead code wearing a safeguard's clothes, which is worse than no
+      // guard at all: the next reader trusts it and stops looking for the real
+      // mechanism. The real mechanism is this max, and the tooltip control below
+      // is what proves the outcome.
+      if (!spilled || over > spilled.over) spilled = { el, r: c.r, right, over };
+    }
+
+    const overBy = Math.round(
+      Math.max(docW - W, clipped ? clipped.r.right - W : 0, spilled ? spilled.over : 0),
+    );
+    if (overBy > 1) {
+      // The actionable half: the widest thing sticking out that is NOT inside a
+      // container designed to scroll horizontally. A tab strip with
+      // `overflow-x:auto` is a scroller doing its job — reporting its children
+      // would bury the real offender under furniture. (Measured: on this page the
+      // naive count was 77 elements, of which 77 were the tab strip's.)
+      // Whichever reaches FURTHER is the place to look. A spill can beat a
+      // box overflow and vice versa; naming the smaller one sends the reader to
+      // the wrong element with a correct-looking number beside it.
+      const spillFurther = spilled && (!clipped || spilled.right > clipped.r.right);
+      const worst: { el: Element; r: DOMRect } | null = spillFurther ? spilled : clipped;
+      const tid = worst ? worst.el.getAttribute('data-testid') : null;
+      const where = worst
+        ? spillFurther
+          ? `widest offender "${labelOf(worst.el)}" holds content ${Math.round(spilled!.right)}px wide inside a ` +
+            `${Math.round((worst.el as HTMLElement).clientWidth)}px box — its CONTENT spills, its box does not. ` +
+            `Usually a long unbroken token in a flex child: min-width:0 shrinks the box, overflow-wrap:anywhere wraps the text ` +
+            `(break-word does not — it leaves min-content width untouched)`
+          : `widest offender "${labelOf(worst.el)}" reaches ${Math.round(worst.r.right)}px`
+        : 'no single element identified — the overflow comes from a container, not a leaf';
+      findings.push({
+        kind: 'wiggle',
+        severity: 'high',
+        testid: tid,
+        selector: worst ? selectorOf(worst.el) : 'body',
+        label: worst ? labelOf(worst.el) : 'page',
+        box: worst
+          ? { x: Math.round(worst.r.x), y: Math.round(worst.r.y), w: Math.round(worst.r.width), h: Math.round(worst.r.height) }
+          : { x: 0, y: 0, w: W, h: H },
+        message:
+          (docW > W + 1
+            ? `The page scrolls SIDEWAYS at ${W}px: content is ${Math.round(docW)}px wide, ${overBy}px past the viewport. `
+            : `Content is CUT OFF at ${W}px: it reaches ${overBy}px past the viewport and the only thing holding it is an ` +
+              `overflow-x:hidden ancestor, so it cannot be scrolled to — the page may still drag on a real phone. `) +
+          `${where}. Wide content must scroll inside its own overflow-x:auto container; the page body must never scroll horizontally.`,
+      });
+    }
+  }
+
+  return findings;
+
+  // ── colour helpers (WCAG) ──────────────────────────────────────────────
+  function parseRGB(s: string): { r: number; g: number; b: number; a: number } | null {
+    const m = s.match(/rgba?\(([^)]+)\)/);
+    if (!m || !m[1]) return null;
+    const p = m[1].split(',').map((x) => parseFloat(x.trim()));
+    if (p.length < 3) return null;
+    return { r: p[0]!, g: p[1]!, b: p[2]!, a: p.length >= 4 ? p[3]! : 1 };
+  }
+  function resolveSolidBg(el: Element): { r: number; g: number; b: number } | null {
+    let n: Element | null = el;
+    while (n) {
+      const cs = getComputedStyle(n);
+      if (cs.backgroundImage && cs.backgroundImage !== 'none') return null; // gradient/image → vision's job
+      const bg = parseRGB(cs.backgroundColor);
+      if (bg && bg.a >= 0.999) return { r: bg.r, g: bg.g, b: bg.b };
+      if (bg && bg.a > 0.001) return null; // semi-transparent layer → undeterminable
+      n = n.parentElement;
+    }
+    return null;
+  }
+  function lum(c: { r: number; g: number; b: number }): number {
+    const f = (v: number) => {
+      const s = v / 255;
+      return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b);
+  }
+  function contrast(a: { r: number; g: number; b: number }, b: { r: number; g: number; b: number }): number {
+    const l1 = lum(a);
+    const l2 = lum(b);
+    return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+  }
+}
+/* eslint-enable */