automated-qa 0.11.0

package/bin/probe.js

@@ -0,0 +1,879 @@
+// frontend-verify in-page probe. Deterministic runtime invariants.
+//
+// Returns { findings: [{kind, severity, detail, at}], metrics: {...} }.
+//
+// HARD CONSTRAINT: no backticks, no dollar signs anywhere in this file. It is
+// passed through a double-quoted shell argument by playwright-cli; the shell
+// eats both. Use string concatenation. (Same rule as ui-stress/probe.js.)
+//
+// Everything here is decidable without vision. Screenshots are for the residual.
+
+async page => {
+  // Focus-visible depends on trusted keyboard modality, including after a journey clicked.
+  await page.keyboard.press('Tab');
+  const out = await page.evaluate(async () => {
+    // That opening Tab is the probe's own input, and it leaves a control
+    // FOCUSED before a single pixel is measured. A correct reveal-on-focus
+    // skip link then paints a 200x50 panel over the header, and the geometry
+    // rules below read an overlay the application never showed anyone --
+    // "clicks land on a.skip instead", a P1 against correct markup. Park the
+    // focus for the in-page pass and restore it before the Tab walk, which
+    // needs both the keyboard modality and the sequential-focus origin. #231
+    const probeFocused = document.activeElement;
+    if (probeFocused && probeFocused.blur) probeFocused.blur();
+    const V = [];
+    const add = (kind, severity, detail, at) => V.push({ kind, severity, detail, at: at || '(page)' });
+
+    const sel = el => {
+      if (!el || el.nodeType !== 1) return '(page)';
+      const t = el.getAttribute && el.getAttribute('data-testid');
+      if (t) return '[data-testid=' + t + ']';
+      if (el.id) return '#' + el.id;
+      const c = (el.className && String(el.className).split(/\s+/)[0]) || '';
+      return el.tagName.toLowerCase() + (c ? '.' + c : '');
+    };
+    const vis = el => {
+      if (!el || el.nodeType !== 1) return false;
+      const s = getComputedStyle(el);
+      if (s.display === 'none' || s.visibility === 'hidden' || Number(s.opacity) < 0.02) return false;
+      if (typeof el.checkVisibility === 'function' && !el.checkVisibility()) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    };
+    // Screen-reader-only elements are 1x1 by design. Measuring them as tap
+    // targets is how a ticket claims 103 failures and a browser finds one.
+    const srOnly = el => {
+      const s = getComputedStyle(el);
+      const r = el.getBoundingClientRect();
+      return (r.width <= 2 && r.height <= 2) || s.clip === 'rect(0px, 0px, 0px, 0px)' || s.clipPath === 'inset(50%)';
+    };
+
+    /* -- L5: values that leaked through formatting ------------------------ */
+
+    // A literal dollar sign is never typed in this file -- it is built at
+    // runtime instead, because probe.js is injected through a shell argument
+    // and a literal dollar sign or backtick here gets eaten before the
+    // browser ever sees it.
+    const DOLLAR = String.fromCharCode(36);
+    const TEMPLATE_VAR_RE = new RegExp('\\{\\{[\\w.]+\\}\\}|\\' + DOLLAR + '\\{[\\w.]+\\}');
+
+    // [object Object], a raw JS error, and an unresolved template variable are
+    // checked against the whole rendered page text, as before -- these
+    // multi-character shapes essentially never collide with ordinary prose.
+    const BODY_LEAKS = [
+      [/\[object Object\]/, '[object Object] rendered as text'],
+      [/\bTypeError\b|\bReferenceError\b|is not a function|Cannot read propert/, 'raw JS error text in the DOM'],
+      [TEMPLATE_VAR_RE, 'unresolved template variable in the DOM'],
+    ];
+    const bodyText = (document.body && document.body.innerText) || '';
+    for (const pair of BODY_LEAKS) {
+      const hit = bodyText.match(pair[0]);
+      if (!hit) continue;
+      const at = Math.max(0, (hit.index || 0) - 50);
+      add('value.leak', 'P1', pair[1] + ' -- ...' + bodyText.slice(at, at + 140).replace(/\s+/g, ' ') + '...');
+    }
+
+    // null/undefined/NaN/Invalid Date collide with ordinary prose on a bare
+    // word-boundary regex ("the null hypothesis"). These four are walked per
+    // text node and only counted when they look like a RENDERED VALUE rather
+    // than a word in a sentence: either the token is the entire trimmed text
+    // of the leaf element that holds it, or it is immediately preceded by a
+    // colon, equals sign, or hyphen -- the punctuation a template leaves
+    // right before a value.
+    const VALUE_TOKENS = [
+      [/\bNaN\b/, 'NaN rendered as text'],
+      [/\bundefined\b/, 'undefined rendered as text'],
+      [/\bInvalid Date\b/, 'Invalid Date rendered as text'],
+      [/\bnull\b/, 'the string "null" rendered as text'],
+    ];
+    const valueLeaksFound = new Set();
+    {
+      const w = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+      let n;
+      while ((n = w.nextNode())) {
+        const p = n.parentElement;
+        if (!p || p.closest('script,style,noscript,code,pre,kbd,samp')) continue;
+        if (!vis(p) || srOnly(p)) continue;
+        const text = n.textContent;
+        const leafText = p.children.length === 0 ? p.textContent.trim() : null;
+        for (const pair of VALUE_TOKENS) {
+          if (valueLeaksFound.has(pair[1])) continue;
+          const m = pair[0].exec(text);
+          if (!m) continue;
+          const isWholeLeaf = leafText !== null && leafText === m[0];
+          const before = text.slice(0, m.index).trimEnd();
+          const lastChar = before.slice(-1);
+          const isPunctuated = lastChar === ':' || lastChar === '=' || lastChar === '-';
+          if (!isWholeLeaf && !isPunctuated) continue;
+          valueLeaksFound.add(pair[1]);
+          const at = Math.max(0, m.index - 50);
+          add('value.leak', 'P1', pair[1] + ' -- ...' + text.slice(at, at + 140).trim().replace(/\s+/g, ' ') + '...', sel(p));
+        }
+      }
+    }
+
+    /* -- L4: states that were never built --------------------------------- */
+
+    const root = document.querySelector('#root,#__next,[data-reactroot],main') || document.body;
+    if (!root || (root.innerText || '').trim().length < 2)
+      add('render.empty', 'P0', 'page root rendered with no text content');
+
+    // A spinner still mounted after the settle loop is a query that never
+    // resolved -- the other half of "the data did not load".
+    // ARIA state is unconditional; a bare class name also catches decorative
+    // dots (an 8x8 animate-pulse status indicator is not a stuck loader), so
+    // those require a real spinner-sized box before they count.
+    const ariaSpinners = [...document.querySelectorAll('[aria-busy="true"],[role="progressbar"]:not([aria-valuenow])')].filter(vis);
+    const classSpinners = [...document.querySelectorAll('.spinner,.loading,.skeleton,[class*="skeleton" i],[class*="animate-pulse"]')].filter((el) => {
+      if (!vis(el)) return false;
+      const r = el.getBoundingClientRect();
+      return Math.min(r.width, r.height) >= 16;
+    });
+    const spinners = [...new Set(ariaSpinners.concat(classSpinners))];
+    if (spinners.length)
+      add('render.stuck-loading', 'P1', spinners.length + ' loading indicator(s) still visible after settle', sel(spinners[0]));
+
+    // An empty list with no empty state is indistinguishable from a failed fetch.
+    // NOT filtered by vis(): an empty list is zero-height by definition, so a
+    // visibility filter excludes precisely the case this rule exists to catch.
+    // Layout participation (offsetParent, or a fixed/sticky ancestor) is the
+    // right test -- it excludes display:none subtrees and keeps empty lists.
+    const inLayout = el => el.offsetParent !== null || getComputedStyle(el).position === 'fixed';
+    // Toast/notification regions are legitimately empty on almost every route:
+    // sonner and Radix mount an off-screen toaster/ToastViewport list even
+    // when nothing is toasting, and inLayout() keeps position:fixed elements
+    // on purpose. "Is or is inside" via closest() excludes the region and
+    // everything it contains, not just the region element itself.
+    const NOTICE_SEL = '[data-sonner-toaster],[data-radix-toast-viewport],[role="region"][aria-live],[aria-label*="notification" i],[role="status"],[aria-live]';
+    const lists = [...document.querySelectorAll('ul,ol,tbody,[role="list"],[role="table"],[role="grid"]')]
+      .filter(inLayout)
+      .filter(l => !l.closest(NOTICE_SEL));
+    for (const l of lists) {
+      const rows = [...l.children].filter(vis);
+      if (rows.length) continue;
+      const near = ((l.parentElement && l.parentElement.innerText) || '').toLowerCase();
+      if (!/no |empty|none |nothing|0 result|get started|add your first/.test(near))
+        add('render.empty-list-no-state', 'P1', 'list rendered with zero rows and no empty-state message', sel(l));
+    }
+
+    /* -- L8: layout under the real viewport ------------------------------- */
+
+    if (document.documentElement.scrollWidth > window.innerWidth + 1) {
+      const wide = [...document.querySelectorAll('body *')].filter(el => {
+        const r = el.getBoundingClientRect();
+        return r.width > 0 && (r.right > window.innerWidth + 1 || r.left < -1) && vis(el);
+      });
+      add('layout.h-scroll', 'P1',
+        'page scrolls horizontally at ' + window.innerWidth + 'px (content ' + document.documentElement.scrollWidth + 'px)',
+        wide.length ? sel(wide[0]) : '(page)');
+    }
+
+    const INTERACTIVE = 'a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"]';
+    // WCAG 2.5.8 exempts an inline target sitting inside a run of text -- a
+    // link in the middle of a sentence is sized by the surrounding text, not
+    // a deliberately small tap target, so it does not get measured as one.
+    const inlineInSentence = (el) => {
+      if (el.tagName !== 'A') return false;
+      if (getComputedStyle(el).display !== 'inline') return false;
+      const p = el.parentElement;
+      return !!p && [...p.childNodes].some((k) => k.nodeType === 3 && k.textContent.trim());
+    };
+    const small = [...document.querySelectorAll(INTERACTIVE)].filter(el => {
+      if (!vis(el) || srOnly(el) || inlineInSentence(el)) return false;
+      const r = el.getBoundingClientRect();
+      return Math.min(r.width, r.height) < 24;
+    });
+    if (small.length)
+      add('a11y.tap-target', 'P2', small.length + ' interactive element(s) under 24px (sr-only excluded)', sel(small[0]));
+
+    /* -- L6: a control that cannot be clicked ------------------------------ */
+
+    // elementFromPoint at the control's center must return the control or one
+    // of its own descendants/ancestors; anything else is sitting on top and
+    // eats the click. elementFromPoint already skips pointer-events:none, so a
+    // deliberate click-through overlay never fires this. An OPEN dialog
+    // legitimately occludes everything behind it, so any modal signal
+    // suppresses the whole rule for this capture rather than flagging the
+    // entire background surface.
+    const modalOpen = !!document.querySelector('dialog[open],[role="dialog"],[aria-modal="true"]');
+    if (!modalOpen) {
+      const occluded = [];
+      for (const el of document.querySelectorAll('a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"]')) {
+        if (!vis(el) || srOnly(el)) continue;
+        // A collapsed details lays its content out -- getBoundingClientRect
+        // keeps real width/height -- but content-visibility: hidden on its
+        // internal box skips it for paint AND hit-testing, so elementFromPoint
+        // at the control's own centre returns whatever the browser painted
+        // there instead: an ancestor cell, or a neighbouring row's own
+        // summary. That occluder sits in a subtree unrelated to the control,
+        // so a contains() guard cannot reach it. The details' OWN summary
+        // stays exempt -- it is always rendered and is exactly what a person
+        // clicks to reveal the rest. #81.
+        const closedDetails = el.closest('details:not([open])');
+        if (closedDetails && el !== closedDetails.querySelector('summary')) continue;
+        const r = el.getBoundingClientRect();
+        const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+        if (cx < 0 || cy < 0 || cx > window.innerWidth || cy > window.innerHeight) continue;
+        // Scrolled out of its own clipping ancestor is NOT occluded. A nav with
+        // overflow-y:auto still reports a layout rect for items below the fold,
+        // so elementFromPoint at that coordinate returns whatever is PAINTED
+        // there -- typically the footer sitting under the scroll box. The user
+        // scrolls and clicks the control fine.
+        //
+        // Measured, not theorised: a sidebar nav item one row past its
+        // container's bottom edge produced this on 37 of 51 routes in one run,
+        // every one reading "clicks land on span.block instead" -- the account
+        // name in the sign-out block below the nav. 37 P1s that are all one
+        // scrollable list is exactly the noise that stops a report being read.
+        let clipped = false;
+        for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
+          const s = getComputedStyle(a);
+          if (!/auto|scroll|hidden|clip/.test(s.overflowY + s.overflowX)) continue;
+          const ar = a.getBoundingClientRect();
+          if (cx < ar.left || cx > ar.right || cy < ar.top || cy > ar.bottom) { clipped = true; break; }
+        }
+        if (clipped) continue;
+        const hit = document.elementFromPoint(cx, cy);
+        if (!hit || hit === el || el.contains(hit) || hit.contains(el)) continue;
+        // A label wrapping its input is how custom checkboxes are built.
+        if (hit.closest && hit.closest('label') && hit.closest('label').contains(el)) continue;
+        // Some surfaces put a full-cover clause over a control and deliberately
+        // forward the click from the clause or one of its ancestors. A passive
+        // probe cannot click: that could submit a form or mutate production
+        // state. Keep the geometry rule, but recognize only an explicit native
+        // or React click handler on the actual hit path.
+        let forwardsClick = false;
+        const targetAncestors = new Set();
+        for (let a = el; a; a = a.parentElement) targetAncestors.add(a);
+        let sharedAncestor = hit;
+        while (sharedAncestor && !targetAncestors.has(sharedAncestor)) sharedAncestor = sharedAncestor.parentElement;
+        for (let a = hit; a; a = a.parentElement) {
+          if (a.hasAttribute && a.hasAttribute('onclick')) { forwardsClick = true; break; }
+          for (const key of Object.getOwnPropertyNames(a)) {
+            if (!new RegExp('^__reactProps\\' + DOLLAR).test(key)) continue;
+            const descriptor = Object.getOwnPropertyDescriptor(a, key);
+            if (!descriptor || !('value' in descriptor)) continue;
+            const props = descriptor.value;
+            if ((typeof props !== 'object' || props === null) && typeof props !== 'function') continue;
+            const onClick = Object.getOwnPropertyDescriptor(props, 'onClick');
+            if (onClick && 'value' in onClick && typeof onClick.value === 'function') {
+              forwardsClick = true; break;
+            }
+          }
+          if (forwardsClick) break;
+          if (a === sharedAncestor) break;
+        }
+        if (forwardsClick) continue;
+        occluded.push([el, hit]);
+      }
+      if (occluded.length)
+        add('interact.click-occluded', 'P1', occluded.length + ' interactive element(s) whose center is covered by another element -- clicks land on '
+          + sel(occluded[0][1]) + ' instead', sel(occluded[0][0]));
+    }
+
+    const noAria = el => !el.getAttribute('aria-label') && !el.getAttribute('aria-labelledby') && !el.getAttribute('title');
+    const unlabeled = [...document.querySelectorAll('button,[role="button"],a[href]')].filter(el =>
+      vis(el) && !(el.innerText || '').trim() && noAria(el)
+      && ![...el.querySelectorAll('img[alt],svg > title')].some((child) =>
+        !child.closest('[aria-hidden="true"]') && (child.getAttribute('alt') || child.textContent || '').trim()));
+    // Form fields get a name from a <label> (wrapping or for=), aria, or title.
+    // A placeholder is accepted here only because browsers fall back to it in
+    // accname computation -- it is still bad practice, but not nameless.
+    // Radix keeps a native select as a 1x1 aria-hidden tabindex=-1 form
+    // control behind its visible combobox. It is intentionally absent from
+    // the accessibility tree; visible or focusable controls still count.
+    const hiddenNativeSelect = el => el.tagName === 'SELECT'
+      && el.getAttribute('aria-hidden') === 'true'
+      && el.tabIndex === -1 && srOnly(el);
+    const unlabeledFields = [...document.querySelectorAll('input,select,textarea')].filter(el =>
+      vis(el) && el.type !== 'hidden' && noAria(el)
+      && !hiddenNativeSelect(el)
+      && !(el.labels && el.labels.length) && !el.closest('label') && !el.getAttribute('placeholder'));
+    const nameless = unlabeled.concat(unlabeledFields);
+    if (nameless.length)
+      add('a11y.unlabeled-control', 'P2', nameless.length + ' control(s) with no accessible name', sel(nameless[0]));
+
+    // L9.88's other half. The app DID write a visible label; a duplicate id
+    // broke the association. A responsive layout keeps the desktop copy of a
+    // form mounted at display:none and mounts a second copy for mobile, so
+    // both controls carry id="email". HTMLLabelElement.control resolves to
+    // the FIRST element in tree order with that id, which is the hidden one,
+    // and the visible field ends up with zero labels -- getByLabel() cannot
+    // reach it and a screen reader announces nothing. The placeholder the
+    // check above accepts is an example value, not the field's name, so that
+    // check stays silent here. Only a collision that ACTUALLY breaks the
+    // relationship counts: the label is visible, its resolved control is not
+    // (or does not exist), and a visible labelable control with no labels of
+    // its own carries the same id. #240
+    const byId = new Map();
+    for (const el of document.querySelectorAll('[id]')) {
+      const list = byId.get(el.id);
+      if (list) list.push(el); else byId.set(el.id, [el]);
+    }
+    const brokenLabels = [];
+    for (const label of document.querySelectorAll('label[for]')) {
+      if (!vis(label) || !(label.innerText || '').trim()) continue;
+      const target = label.control;
+      if (target && vis(target)) continue;
+      const orphan = (byId.get(label.htmlFor) || []).find((el) => el !== target
+        && vis(el) && !srOnly(el) && el.labels && el.labels.length === 0);
+      if (orphan) brokenLabels.push([label, orphan]);
+    }
+    if (brokenLabels.length)
+      add('a11y.label-association-broken', 'P3', brokenLabels.length
+        + ' visible label(s) whose for= resolves past a duplicate id to a hidden or absent control while a visible unlabelled control carries that id: '
+        + brokenLabels.slice(0, 5).map((p) => sel(p[0]) + ' -> ' + sel(p[1])).join(', '),
+        sel(brokenLabels[0][1]));
+
+    /* -- L9.94: an ARIA state attribute the element's role does not support --
+       A shared button/chip component emitting BOTH aria-pressed and
+       aria-selected is the reported shape (#287): aria-selected is not in the
+       button role's supported set, so assistive technology drops it and the
+       control's selected state is announced to nobody. Axe calls this
+       aria-allowed-attr.
+
+       Two things keep this precise rather than noisy. Only the two state
+       attributes whose supported-role sets are small and unambiguous are
+       measured -- a "selection attribute" is exactly what the report warns
+       must not be flagged everywhere. And a role is only judged when it is
+       KNOWN: an explicit role=, or a native element with one unambiguous
+       implicit role. An unmapped element is unmeasured, never guessed.
+       ponytail: two attributes, not the full aria-allowed-attr table --
+       widen it when a real run produces a class this misses, not before. */
+    const ARIA_ROLE_SUPPORT = [
+      ['aria-selected', ['columnheader', 'gridcell', 'option', 'row', 'rowheader', 'tab', 'treeitem']],
+      ['aria-pressed', ['button']],
+    ];
+    const INPUT_ROLE = { button: 'button', checkbox: 'checkbox', image: 'button', radio: 'radio',
+      range: 'slider', reset: 'button', submit: 'button' };
+    const implicitRole = (el) => {
+      const tag = el.tagName.toLowerCase();
+      if (tag === 'button') return 'button';
+      if (tag === 'a' || tag === 'area') return el.hasAttribute('href') ? 'link' : null;
+      if (tag === 'option') return 'option';
+      if (tag === 'select') return (el.multiple || el.size > 1) ? 'listbox' : 'combobox';
+      if (tag === 'textarea') return 'textbox';
+      if (tag !== 'input') return null;
+      return INPUT_ROLE[(el.getAttribute('type') || 'text').toLowerCase()] || 'textbox';
+    };
+    const ariaMisuse = [];
+    for (const el of document.querySelectorAll('[aria-selected],[aria-pressed]')) {
+      if (!vis(el) || el.getAttribute('aria-hidden') === 'true' || el.closest('[aria-hidden="true"]')) continue;
+      const declared = (el.getAttribute('role') || '').trim().split(/\s+/)[0].toLowerCase();
+      const role = declared || implicitRole(el);
+      if (!role) continue;
+      for (const pair of ARIA_ROLE_SUPPORT)
+        if (el.hasAttribute(pair[0]) && pair[1].indexOf(role) === -1) ariaMisuse.push([el, pair[0], role]);
+    }
+    if (ariaMisuse.length)
+      add('a11y.aria-attr-not-allowed', 'P3', ariaMisuse.length
+        + ' ARIA state attribute(s) the element role does not support: '
+        + ariaMisuse.slice(0, 5).map((t) => t[1] + ' on role=' + t[2] + ' (' + sel(t[0]) + ')').join(', '),
+        sel(ariaMisuse[0][0]));
+
+    /* -- L5: data arrived, page rendered none of it ------------------------ */
+
+    // The cardinality defect's strongest decidable form. The in-page network
+    // recorder captured a same-origin JSON array; if EVERY list on the page has
+    // zero visible rows, the data arrived and was never rendered. Requiring all
+    // lists empty (a populated nav suppresses it) keeps this near zero noise.
+    const net = (window.__fv_net || []).filter(r =>
+      r.method === 'GET' && r.ok && typeof r.arrayLen === 'number'
+      && (!/^https?:/.test(r.url) || r.url.indexOf(location.origin) === 0));
+    const maxLen = net.reduce((n, r) => Math.max(n, r.arrayLen), 0);
+    const totalRows = lists.reduce((n, l) => n + [...l.children].filter(vis).length, 0);
+    if (maxLen > 0 && lists.length && totalRows === 0)
+      add('data.rendered-zero-of-n', 'P1', 'a same-origin API response carried ' + maxLen
+        + ' record(s) but every list on the page rendered zero rows -- the data arrived and was never rendered');
+
+    /* -- L10: what the main thread actually did --------------------------- */
+
+    const metrics = { longTasks: 0, longestTaskMs: 0, cls: 0, lcpMs: null, forcedReflows: 0, resources: 0, transferKB: 0, perfObserved: false, contrastEligible: 0, contrastUnmeasured: 0 };
+
+    // longtask / layout-shift / LCP are ONLY visible to observers installed
+    // before navigation (the sweep's init script fills window.__fv_perf);
+    // performance.getEntriesByType returns nothing for them in Chromium. When
+    // the init script is absent (probe run standalone), the perf gates are
+    // marked unmeasured rather than silently reporting clean zeros.
+    const P = window.__fv_perf;
+    if (P) {
+      if (P.flush) try { P.flush(); } catch (e) { /* drained what we could */ }
+      metrics.perfObserved = true;
+      metrics.longTasks = P.longTasks; metrics.longestTaskMs = P.longestTaskMs;
+      metrics.cls = P.cls; metrics.lcpMs = P.lcpMs; metrics.forcedReflows = P.thrashReads;
+    }
+    try { performance.getEntriesByType('resource').forEach(e => { metrics.resources++; metrics.transferKB += (e.transferSize || 0) / 1024; }); } catch (e) { /* unsupported */ }
+    metrics.cls = Math.round(metrics.cls * 1000) / 1000;
+    metrics.transferKB = Math.round(metrics.transferKB);
+
+    // Thresholds are the published Core Web Vitals "needs improvement" line, so
+    // a finding here means something a real user feels, not a preference. All
+    // gated on perfObserved: an unmeasured metric must never read as a clean one.
+    if (metrics.perfObserved) {
+      if (metrics.longestTaskMs > 200)
+        add('perf.long-task', 'P2', 'longest main-thread task ' + metrics.longestTaskMs + 'ms (' + metrics.longTasks + ' over 50ms) -- input is blocked for that whole window');
+      if (metrics.cls > 0.1)
+        add('perf.layout-shift', 'P2', 'cumulative layout shift ' + metrics.cls + ' (over the 0.1 threshold) -- content moves under the cursor');
+      if (metrics.lcpMs !== null && metrics.lcpMs > 2500)
+        add('perf.lcp', 'P2', 'largest contentful paint at ' + metrics.lcpMs + 'ms (over 2500ms)');
+      // Forced synchronous layout, counted since before app JS ran: a geometry
+      // read after a DOM write in the same frame makes the browser lay out again.
+      if (metrics.forcedReflows > 20)
+        add('perf.layout-thrash', 'P2', metrics.forcedReflows + ' geometry reads interleaved with DOM writes in one frame -- forced synchronous layout');
+    }
+
+    /* -- L4: hydration and boundaries ------------------------------------- */
+
+    // React marks a hydration-mismatched root; the visible symptom is content
+    // that renders then silently swaps or disappears.
+    if (document.querySelector('[data-nextjs-error],[data-nextjs-dialog]'))
+      add('render.dev-overlay', 'P0', 'a framework error overlay is present on the page');
+
+    /* -- L23 probe atlas classes -------------------------------------------
+       Eleven new runtime invariants. Each excludes sr-only elements and
+       display:none/visibility:hidden ancestors the same way every check
+       above does (via vis()/srOnly()), and never guesses at a value it did
+       not actually observe -- an unresolvable background or an unreadable
+       color skips the node rather than reporting a fabricated ratio. */
+
+    /* -- L8.83: broken image, no fallback dimension ------------------------ */
+    const brokenImages = [...document.querySelectorAll('img[src]')].filter((img) => {
+      if (!img.src || !img.complete || img.naturalWidth !== 0) return false;
+      if (!vis(img) || srOnly(img)) return false;
+      if (img.getAttribute('aria-hidden') === 'true' || (img.closest && img.closest('[aria-hidden="true"]'))) return false;
+      return true;
+    });
+    if (brokenImages.length)
+      add('render.broken-image', 'P2', brokenImages.length + ' image(s) whose src failed to load (naturalWidth 0)', sel(brokenImages[0]));
+
+    /* -- L4.44: a virtualised container rendering zero rows -----------------
+       Two ways a list identifies itself as virtualised: an explicit marker
+       (data-virtualized, a testid/class naming the library), or role=grid/
+       list with an inner absolutely-positioned spacer taller than the
+       container -- the standard react-window/react-virtuoso shape. "Zero
+       rendered children" for the spacer shape excludes the spacer itself
+       and looks inside it, or every virtualised list would trivially count
+       its own sizer div as a rendered row. */
+    const virtFindings = [];
+    for (const el of document.querySelectorAll('[data-virtualized],[data-testid*="virtual" i],[class*="virtual" i],[class*="react-window" i],[class*="react-virtuoso" i]')) {
+      if (!vis(el) || srOnly(el)) continue;
+      const r = el.getBoundingClientRect();
+      if (r.height <= 100) continue;
+      if ([...el.children].filter(vis).length === 0) virtFindings.push(el);
+    }
+    for (const el of document.querySelectorAll('[role="grid"],[role="list"]')) {
+      if (!vis(el) || srOnly(el)) continue;
+      const r = el.getBoundingClientRect();
+      if (r.height <= 100) continue;
+      const spacer = [...el.children].find((k) => {
+        const ks = getComputedStyle(k);
+        return ks.position === 'absolute' && k.getBoundingClientRect().height > r.height;
+      });
+      if (!spacer) continue;
+      const others = [...el.children].filter((k) => k !== spacer).filter(vis);
+      const spacerRows = [...spacer.children].filter(vis);
+      if (others.length === 0 && spacerRows.length === 0) virtFindings.push(el);
+    }
+    const virtCapped = [...new Set(virtFindings)];
+    if (virtCapped.length)
+      add('render.virtualized-empty', 'P2', virtCapped.length + ' virtualised-looking container(s) taller than 100px rendering zero children', sel(virtCapped[0]));
+
+    /* -- L5.56: truncated with no way to read the rest ---------------------- */
+    const truncFindings = [...document.querySelectorAll('body *')].filter((el) => {
+      if (!vis(el) || srOnly(el)) return false;
+      if (!(el.textContent || '').trim()) return false;
+      const s = getComputedStyle(el);
+      if (s.overflow !== 'hidden' && s.overflowX !== 'hidden') return false;
+      if (el.scrollWidth <= el.clientWidth + 2) return false;
+      if (s.textOverflow === 'ellipsis') return false;
+      if (el.getAttribute('title') || el.getAttribute('aria-label')) return false;
+      return true;
+    }).slice(0, 10);
+    if (truncFindings.length)
+      add('layout.truncated-no-title', 'P3', truncFindings.length + ' element(s) truncated by overflow:hidden with no ellipsis styling and no title/aria-label', sel(truncFindings[0]));
+
+    /* -- L8.86: a fixed pixel height clipping real content ------------------
+       "Explicit" is read from the inline style only -- a class-based height
+       cannot be told apart from an incidental one without walking every
+       stylesheet rule, and a miss here is cheaper than guessing wrong. */
+    const fixedClipFindings = [...document.querySelectorAll('body *')].filter((el) => {
+      if (!vis(el) || srOnly(el)) return false;
+      const styleHeight = el.style && el.style.height;
+      // No trailing anchor: an end-of-string dollar sign is itself banned
+      // from this file, so a full-string match is proven by length instead.
+      const pxMatch = styleHeight && /^\d+(\.\d+)?px/.exec(styleHeight);
+      if (!pxMatch || pxMatch[0].length !== styleHeight.length) return false;
+      const s = getComputedStyle(el);
+      if (s.overflow !== 'hidden' && s.overflowY !== 'hidden') return false;
+      if (el.scrollHeight <= el.clientHeight + 4) return false;
+      if (!(el.textContent || '').trim()) return false;
+      return true;
+    }).slice(0, 10);
+    if (fixedClipFindings.length)
+      add('layout.fixed-height-clip', 'P3', fixedClipFindings.length + ' element(s) with an explicit pixel height and overflow:hidden clipping their own text content', sel(fixedClipFindings[0]));
+
+    /* -- L6.67: disabled-looking control that is not actually disabled ------ */
+    const disabledNotConveyed = [...document.querySelectorAll('button,a[href],[role="button"]')].filter((el) => {
+      if (!vis(el) || srOnly(el)) return false;
+      if (el.disabled) return false;
+      if (el.getAttribute('aria-disabled') === 'true') return false;
+      const s = getComputedStyle(el);
+      return s.pointerEvents === 'none' || Number(s.opacity) < 0.5;
+    }).slice(0, 10);
+    if (disabledNotConveyed.length)
+      add('interact.disabled-not-conveyed', 'P3', disabledNotConveyed.length + ' control(s) styled as disabled (pointer-events:none or opacity < 0.5) without a disabled or aria-disabled attribute', sel(disabledNotConveyed[0]));
+
+    /* -- L5.57: a raw snake_case enum rendered without display formatting --- */
+    // No trailing anchor here either, for the same reason as the pixel-height
+    // check above: full-string match is proven by length, not a dollar sign.
+    const rawEnumRe = /^[a-z]+(?:_[a-z]+)+/;
+    const isRawEnum = (text) => { const m = rawEnumRe.exec(text); return !!m && m[0].length === text.length; };
+    const enumFindings = [];
+    {
+      const w = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+      let n;
+      while ((n = w.nextNode())) {
+        const text = n.textContent.trim();
+        if (!isRawEnum(text)) continue;
+        const p = n.parentElement;
+        if (!p) continue;
+        if (!['TD', 'LI', 'SPAN', 'DIV'].includes(p.tagName)) continue;
+        if (p.closest('script,style,noscript,code,pre,kbd,samp')) continue;
+        if (p.closest('input,textarea,select,option')) continue;
+        if (!vis(p) || srOnly(p)) continue;
+        const words = (p.textContent || '').trim().split(/\s+/).filter(Boolean);
+        if (words.length > 3) continue;
+        enumFindings.push(p);
+      }
+    }
+    const enumCapped = [...new Set(enumFindings)].slice(0, 10);
+    if (enumCapped.length)
+      add('value.raw-enum', 'P3', enumCapped.length + ' element(s) rendering a raw snake_case value with no display formatting', sel(enumCapped[0]));
+
+    /* -- L9.91: focusing a control produces no visible change ---------------
+       Programmatic .focus()/.blur() is enough here -- :focus applies
+       regardless of how focus arrived, unlike the real Tab walk below which
+       needs a trusted input event to drive native focus advancement. */
+    const FOCUSABLE_SEL = 'a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[tabindex]:not([tabindex="-1"])';
+    const focusables = [...document.querySelectorAll(FOCUSABLE_SEL)].filter((el) => vis(el) && !srOnly(el) && !el.disabled);
+    if (focusables.length >= 3) {
+      const sample = focusables.slice(0, 25);
+      const noRing = [];
+      const prevActive = document.activeElement;
+      // Real-repo evidence: a search input styled with a border-color change
+      // on focus (no outline, no box-shadow) is a legitimate indicator, and
+      // reading only outline/box-shadow filed it as having none. Compare
+      // every property browsers commonly use for a focus indicator; only
+      // "every one of these is unchanged" earns the finding.
+      const focusKey = (s) => [s.outlineStyle, s.outlineWidth, s.outlineColor, s.boxShadow, s.borderColor, s.borderStyle, s.backgroundColor].join('|');
+      let measured = 0;
+      const probeStyle = document.createElement('style');
+      probeStyle.textContent = '*,*::before,*::after{transition:none!important}';
+      (document.head || document.documentElement).appendChild(probeStyle);
+      try {
+        for (const el of sample) {
+          try {
+            if (!el.isConnected) continue;
+            el.blur();
+            const beforeKey = focusKey(getComputedStyle(el));
+            el.focus({ preventScroll: true });
+            if (document.activeElement !== el || !el.isConnected) continue;
+            const afterKey = focusKey(getComputedStyle(el));
+            el.blur();
+            measured++;
+            if (beforeKey === afterKey) noRing.push(el);
+          } catch (e) { /* not focusable in practice */ }
+        }
+      } finally {
+        probeStyle.remove();
+        try { if (prevActive && prevActive !== document.body && prevActive.focus) prevActive.focus({ preventScroll: true }); } catch (e) { /* best effort restore */ }
+      }
+      if (noRing.length)
+        add('a11y.no-focus-ring', 'P2', noRing.length + ' of ' + measured + ' focused control(s) showed no visible outline, shadow, border, or background change: ' + noRing.slice(0, 5).map(sel).join(', '));
+    }
+
+    /* -- L9.87: text contrast against a provably opaque background ----------
+       "Provably" is load-bearing: the effective background is the first
+       ancestor with an opaque solid background-color, and any image or
+       gradient in the way -- on any element, at any point in the chain --
+       aborts the search for that node rather than assuming white. A node
+       under an opacity < 1 ancestor is skipped the same way; a rendered
+       ratio there would be a guess, not a measurement. */
+    const relLum = (c) => {
+      const chan = (v) => { v = v / 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+      return 0.2126 * chan(c.r) + 0.7152 * chan(c.g) + 0.0722 * chan(c.b);
+    };
+    const contrastRatio = (fg, bg) => {
+      const l1 = relLum(fg), l2 = relLum(bg);
+      const lighter = Math.max(l1, l2), darker = Math.min(l1, l2);
+      return (lighter + 0.05) / (darker + 0.05);
+    };
+    // Canvas rasterisation is the browser's color engine: unlike reading
+    // ctx.fillStyle, drawing an oklch()/lab()/color() value produces sRGB
+    // pixels and applies alpha compositing. Unknown CSS colors stay unmeasured.
+    const canvas = document.createElement('canvas'); canvas.width = canvas.height = 1;
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    const drawColor = (layers) => {
+      if (!ctx) return null;
+      ctx.clearRect(0, 0, 1, 1);
+      for (const color of layers) {
+        if (!color) continue;
+        if (!globalThis.CSS?.supports?.('color', color)) return null;
+        ctx.fillStyle = color;
+        ctx.fillRect(0, 0, 1, 1);
+      }
+      const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+      return { r, g, b, a: a / 255 };
+    };
+    const findOpaqueBg = (el) => {
+      const chain = [];
+      for (let a = el; a; a = a.parentElement) {
+        const s = getComputedStyle(a);
+        if (s.backgroundImage && s.backgroundImage !== 'none') return null;
+        chain.unshift(s.backgroundColor);
+        // Stop at the nearest FULLY OPAQUE background-color: nothing painted
+        // behind it can reach the text, so a gradient further out is not a
+        // reason to abandon the sample. Walking past it lost a measurable
+        // 1.09 ratio on an opaque white card because the body had a gradient.
+        // The image check above still runs first, so an image on this same
+        // element (which paints over its own color) keeps aborting. #277
+        const solid = drawColor([s.backgroundColor]);
+        if (solid && solid.a >= 0.999) break;
+        if (a === document.documentElement) break;
+      }
+      const bg = drawColor(chain);
+      return bg && bg.a >= 0.999 ? bg : null;
+    };
+    const opacityChainOk = (el) => {
+      for (let a = el; a; a = a.parentElement) {
+        if (Number(getComputedStyle(a).opacity) < 1) return false;
+        if (a === document.documentElement) break;
+      }
+      return true;
+    };
+    const contrastHits = [];
+    const contrastSeen = new Set();
+    {
+      const w = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+      let n;
+      while ((n = w.nextNode())) {
+        const text = n.textContent.trim();
+        if (text.length < 3) continue;
+        const p = n.parentElement;
+        if (!p || contrastSeen.has(p)) continue;
+        contrastSeen.add(p);
+        if (!vis(p) || srOnly(p)) continue;
+        if (p.closest('script,style,noscript,code,pre')) continue;
+        metrics.contrastEligible++;
+        try {
+          if (!opacityChainOk(p)) { metrics.contrastUnmeasured++; continue; }
+          const bg = findOpaqueBg(p);
+          if (!bg) { metrics.contrastUnmeasured++; continue; }
+          const s = getComputedStyle(p);
+          const fg = drawColor(['rgb(' + bg.r + ' ' + bg.g + ' ' + bg.b + ')', s.color]);
+          if (!fg) { metrics.contrastUnmeasured++; continue; }
+          const fontSize = parseFloat(s.fontSize) || 16;
+          const weight = parseInt(s.fontWeight, 10) || 400;
+          const large = fontSize >= 24 || (fontSize >= 18.66 && weight >= 700);
+          const ratio = contrastRatio(fg, bg);
+          const threshold = large ? 3 : 4.5;
+          if (ratio < threshold) { contrastHits.push({ el: p, ratio }); contrastSeen.add(p); }
+        } catch (e) { metrics.contrastUnmeasured++; /* color unreadable: skip rather than guess */ }
+      }
+    }
+    if (contrastHits.length) {
+      contrastHits.sort((a, b) => a.ratio - b.ratio);
+      add('a11y.contrast', 'P3', contrastHits.length + ' text node(s) below the WCAG contrast threshold, worst ratio '
+        + contrastHits[0].ratio.toFixed(2) + ': ' + contrastHits.slice(0, 10).map((h) => sel(h.el)).join(', '));
+    }
+
+    /* -- L8.80: text overflowing its nearest overflow:hidden ancestor ------- */
+    const isScrollable = (el) => { const s = getComputedStyle(el); return /auto|scroll/.test(s.overflowX + s.overflowY); };
+    const clippedText = [];
+    for (const el of document.querySelectorAll('body *')) {
+      if (!vis(el) || srOnly(el)) continue;
+      if (!(el.textContent || '').trim()) continue;
+      if (isScrollable(el)) continue;
+      const r = el.getBoundingClientRect();
+      let blockedX = false, blockedY = false;
+      for (let a = el.parentElement; a && a !== document.body; a = a.parentElement) {
+        const s = getComputedStyle(a);
+        const ar = a.getBoundingClientRect();
+        const outsideX = r.left < ar.left - 4 || r.right > ar.right + 4;
+        const outsideY = r.top < ar.top - 4 || r.bottom > ar.bottom + 4;
+        const scrollX = /auto|scroll/.test(s.overflowX) && outsideX;
+        const scrollY = /auto|scroll/.test(s.overflowY) && outsideY;
+        blockedX ||= scrollX; blockedY ||= scrollY;
+        const hiddenX = (s.overflow === 'hidden' || s.overflowX === 'hidden') && outsideX && !blockedX;
+        const hiddenY = (s.overflow === 'hidden' || s.overflowY === 'hidden') && outsideY && !blockedY;
+        if (hiddenX || hiddenY) {
+          clippedText.push(el);
+          break;
+        }
+        if (blockedX && blockedY) break;
+      }
+    }
+    const clippedCapped = clippedText.slice(0, 10);
+    if (clippedCapped.length)
+      add('layout.clipped-text', 'P3', clippedCapped.length + ' text element(s) extending beyond an overflow boundary by more than 4px', sel(clippedCapped[0]));
+
+    try {
+      if (probeFocused && probeFocused.isConnected && probeFocused !== document.body && probeFocused.focus)
+        probeFocused.focus({ preventScroll: true });
+    } catch (e) { /* best effort restore */ }
+    return { findings: V, metrics };
+  });
+
+  // -- L9.89 / L9.90: a real Tab-key walk. Focus advancement on Tab is native
+  // input behaviour -- Chromium does not move focus for a script-dispatched
+  // KeyboardEvent, only for a trusted one -- so this drives page.keyboard
+  // directly instead of staying inside the evaluate() above. Both findings
+  // come from the same 60-press walk, so they share one pass.
+  try {
+    const focusCount = await page.evaluate(() => {
+      const vis = (el) => {
+        if (!el || el.nodeType !== 1) return false;
+        const s = getComputedStyle(el);
+        if (s.display === 'none' || s.visibility === 'hidden' || Number(s.opacity) < 0.02) return false;
+        const r = el.getBoundingClientRect();
+        return r.width > 0 && r.height > 0;
+      };
+      const SEL = 'a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[tabindex]:not([tabindex="-1"])';
+      return [...document.querySelectorAll(SEL)].filter((el) => vis(el) && !el.disabled).length;
+    });
+    if (focusCount >= 3) {
+      // Read per stop: a DISPLAY selector for reporting, an INDEX into the
+      // live focusable-element query for IDENTITY, and whether focus sits
+      // inside a widget that is allowed to hold Tab on purpose. Real-repo
+      // evidence (Profectus, a shadcn/Tailwind app): comparing the display
+      // selector for identity reads a Tab walk through N different icon
+      // buttons that all share one class (button.inline-flex) as "cycling
+      // between 2 elements" -- the string collides, the elements do not.
+      // The index into a live query is not that; two different nodes can
+      // never share a position in the same NodeList.
+      const readStop = () => page.evaluate(() => {
+        const el = document.activeElement;
+        if (!el || el === document.body || el === document.documentElement) return null;
+        const SEL = 'a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[tabindex]:not([tabindex="-1"])';
+        const idx = [...document.querySelectorAll(SEL)].indexOf(el);
+        const r = el.getBoundingClientRect();
+        const t = el.getAttribute && el.getAttribute('data-testid');
+        const c = (el.className && String(el.className).split(/\s+/)[0]) || '';
+        const s = t ? ('[data-testid=' + t + ']') : (el.id ? ('#' + el.id) : el.tagName.toLowerCase() + (c ? '.' + c : ''));
+        // A roving-tabindex widget (menu/toolbar/tablist), an open dialog, an
+        // expanded combobox/listbox, or anything marked open is CORRECTLY
+        // allowed to hold Tab -- that is the widget doing its job, not a trap.
+        const openWidget = !!el.closest('[role="dialog"],[aria-modal="true"],[role="menu"],[role="listbox"],[role="combobox"][aria-expanded="true"],[data-state="open"],[popover]');
+        // Page coordinates, not viewport: focusing an element below the fold
+        // scrolls it into view, so its viewport top is routinely SMALLER than
+        // the previous stop's -- and a perfectly ordered page read as "jumped
+        // 300px above" on every route long enough to scroll. A fixed/sticky
+        // element has no page position of its own (it rides the viewport), so
+        // it keeps viewport coordinates; otherwise the fixed menu button at the
+        // top-left of a scrolled page lands "below" everything.
+        //
+        // window.scrollY does that job only for stops the WINDOW scrolls. An
+        // element inside an overflow-y:auto pane is positioned by that pane's
+        // scrollTop instead -- on an app shell whose body never scrolls,
+        // scrollY stays 0 and adding it changes nothing, so every stop reads
+        // as wherever the pane happens to have scrolled it. Adding the
+        // scrollTop of each scrolling ancestor puts those stops back in the
+        // pane's own content space, and the nearest such ancestor is recorded
+        // so two stops in DIFFERENT panes are never subtracted from each
+        // other -- that is two coordinate spaces, not a jump. #284
+        let pinned = false, scrollTop = 0, scrollLeft = 0, frame = -1;
+        for (let n = el; n && n !== document.body; n = n.parentElement) {
+          const st = getComputedStyle(n);
+          if (st.position === 'fixed' || st.position === 'sticky') { pinned = true; break; }
+          if (n === el || !/auto|scroll/.test(st.overflowY + st.overflowX)) continue;
+          if (frame === -1) frame = [...document.querySelectorAll('*')].indexOf(n);
+          scrollTop += n.scrollTop; scrollLeft += n.scrollLeft;
+        }
+        const top = (pinned ? r.top : r.top + (window.scrollY || 0)) + scrollTop;
+        const left = (pinned ? r.left : r.left + (window.scrollX || 0)) + scrollLeft;
+        return { sel: s, top, left, idx, openWidget, pinned, frame };
+      });
+      // The probe's opening trusted Tab establishes :focus-visible and may
+      // already be the first stop. Preserve it: blurring here loses the
+      // browser's sequential-focus origin, and a later keyboard trap can make
+      // that first -> second ordering edge impossible to observe again.
+      const initialStop = await readStop();
+      const stops = initialStop ? [initialStop] : [];
+      for (let i = stops.length; i < 60; i++) {
+        await page.keyboard.press('Tab');
+        stops.push(await readStop());
+      }
+      // A keyboard trap: the LAST 10 presses of the walk drawn from 2 or
+      // fewer distinct elements -- requiring the tail (not any window) means
+      // this is still stuck when the walk ends, not a stall it recovered
+      // from, and keeps the verification below acting on the actual current
+      // state rather than a moment already left behind.
+      const tail = stops.slice(-10);
+      let trapWin = null;
+      if (tail.length === 10 && !tail.some((x) => !x)) {
+        const uniq = new Set(tail.map((x) => x.idx));
+        if (uniq.size <= 2 && !tail.some((x) => x.openWidget)) trapWin = tail;
+      }
+      if (trapWin) {
+        const cyclingIdx = new Set(trapWin.map((x) => x.idx));
+        const reachedIdx = new Set(stops.filter(Boolean).map((x) => x.idx));
+        const neverReached = focusCount - reachedIdx.size;
+        // Require the trap to have actually cost something: at least 3 other
+        // focusables on the page were never reached across the whole walk.
+        // A brief stall a user tabs straight through reaches the rest of the
+        // page fine and fails this gate.
+        if (neverReached >= 3) {
+          // Final check, cheap and decisive: press Escape once, then Tab
+          // again. A widget legitimately holding focus (menu, combobox,
+          // popover without the ARIA markers above) releases it on Escape;
+          // a real trap does not move.
+          await page.keyboard.press('Escape');
+          await page.keyboard.press('Tab');
+          const afterIdx = await page.evaluate(() => {
+            const el = document.activeElement;
+            if (!el || el === document.body || el === document.documentElement) return -1;
+            const SEL = 'a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[tabindex]:not([tabindex="-1"])';
+            return [...document.querySelectorAll(SEL)].indexOf(el);
+          });
+          const escaped = afterIdx === -1 || !cyclingIdx.has(afterIdx);
+          if (!escaped)
+            out.findings.push({ kind: 'a11y.keyboard-trap', severity: 'P2', at: trapWin[trapWin.length - 1].sel,
+              detail: 'keyboard focus cycled among 2 or fewer elements for 10 consecutive Tab presses and did not release on Escape -- a keyboard user cannot reach the rest of the page' });
+        }
+      }
+
+      // Focus order: a stop landing more than 300px ABOVE the previous one in
+      // roughly the same column. The column check ("previous was not the last
+      // element of its row") is what keeps a normal row-wrap -- rightmost item
+      // of one row, next stop starts a new row well to the left -- silent;
+      // that shape moves DOWN and sideways, not straight up.
+      const pairs = [];
+      const firstStop = stops.find(Boolean);
+      for (let i = 1; i < stops.length && pairs.length < 5; i++) {
+        const prev = stops[i - 1], cur = stops[i];
+        if (!prev || !cur) continue;
+        // Focus moving BACKWARDS in DOM order is the walk wrapping from the
+        // last focusable element back to the FIRST one (through the browser
+        // UI), or a roving widget -- neither is the page's tab order. Only
+        // those two are skipped: a blanket "backwards in DOM order" skip also
+        // hid a positive tabindex sending focus backwards, which is the
+        // classic focus-order defect this rule exists to catch. #284
+        if (cur.idx <= prev.idx && (!firstStop || cur.idx === firstStop.idx || prev.openWidget || cur.openWidget)) continue;
+        // Different coordinate spaces are not comparable: a stop pinned to the
+        // viewport, or two stops inside different scrolling panes.
+        if (prev.pinned || cur.pinned || prev.frame !== cur.frame) continue;
+        // The 60-press walk laps a short page several times, so one defective
+        // transition is met once per lap. Counting it once keeps the reported
+        // number of jumps equal to the number of defects.
+        const pair = prev.sel + ' -> ' + cur.sel;
+        if (prev.top - cur.top > 300 && Math.abs(cur.left - prev.left) < 150 && !pairs.includes(pair))
+          pairs.push(pair);
+      }
+      if (pairs.length)
+        out.findings.push({ kind: 'a11y.focus-order', severity: 'P3', at: '(page)',
+          detail: pairs.length + ' Tab stop(s) jumped more than 300px above the previous stop in roughly the same column: ' + pairs.join(', ') });
+    }
+  } catch (e) { /* keyboard walk unavailable in this context */ }
+
+  return out;
+}