@surea11y/core 1.2.0 → 1.4.0

package/src/checks/automatic/aria-hidden-focus.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -12,7 +14,7 @@
  *   No element with aria-hidden="true" may itself be focusable, and no focusable element
  *   may exist within an aria-hidden="true" subtree.
  *
- * Notes on parity with a widely-used reference engine's aria-hidden-focus check:
+ * Notes:
  * - Focusability is computed via ctx.helpers.getFocusableInfo (native + tabindex + contenteditable).
  * - Elements that are not rendered (e.g., display:none, visibility:hidden, [hidden]) are excluded.
  * - Elements hidden via CSS in ways that still allow keyboard focus (e.g., opacity:0, off-screen, clip)
@@ -35,8 +37,20 @@ const meta = {
   tags: ['wcag2a', 'wcag2aa', 'wcag412', 'structure', 'aria', 'focus', 'atomic', 'automatic'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '2.4.7', title: 'Focus Visible', conformanceLevel: 'AA' },
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '2.4.7',
+      title: 'Focus Visible',
+      conformanceLevel: 'AA'
+    },
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'robust',
@@ -53,19 +67,24 @@ function runInPage(ctx) {
   const { document, root, helpers, rule } = ctx;
   const safeRoot = root || document;
 
-  const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
 
-  const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
   // Used only to exclude non-rendered elements; we explicitly DO NOT exclude opacity:0.
-  const isDomVisibleEligible = helpers && typeof helpers.isDomVisibleEligible === 'function' ? helpers.isDomVisibleEligible : null;
+  const isDomVisibleEligible =
+    helpers && typeof helpers.isDomVisibleEligible === 'function'
+      ? helpers.isDomVisibleEligible
+      : null;
 
-  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
   // Prefer helper occurrence wrapper so the engine can attach selector/snippet later.
-  const reportOccurrence = helpers && typeof helpers.reportOccurrence === 'function'
-    ? helpers.reportOccurrence
-    : null;
+  const reportOccurrence =
+    helpers && typeof helpers.reportOccurrence === 'function' ? helpers.reportOccurrence : null;
 
   const trim = (v) => (v == null ? '' : String(v)).trim();
   const lower = (v) => trim(v).toLowerCase();
@@ -81,7 +100,8 @@ function runInPage(ctx) {
       // fall through
     }
     try {
-      if (safeRoot && typeof safeRoot.querySelectorAll === 'function') return Array.from(safeRoot.querySelectorAll(sel));
+      if (safeRoot && typeof safeRoot.querySelectorAll === 'function')
+        return Array.from(safeRoot.querySelectorAll(sel));
     } catch {
       // fall through
     }
@@ -92,9 +112,12 @@ function runInPage(ctx) {
   // host) — shared with every other rule via ctx.helpers.composedParent
   // (src/core/dom-helpers.js), not reimplemented here, so a fix to the one
   // canonical definition can't drift out of sync with this rule's copy.
-  const composedParent = helpers && typeof helpers.composedParent === 'function'
-    ? helpers.composedParent
-    : function (n) { return n && n.parentElement ? n.parentElement : null; };
+  const composedParent =
+    helpers && typeof helpers.composedParent === 'function'
+      ? helpers.composedParent
+      : function (n) {
+          return n && n.parentElement ? n.parentElement : null;
+        };
 
   function closestAriaHiddenTrue(node) {
     let cur = node;
@@ -113,15 +136,249 @@ function runInPage(ctx) {
     return null;
   }
 
+  function isWithinComposedSubtree(node, ancestor) {
+    let cur = node;
+    let guard = 0;
+    while (cur && guard++ < 400) {
+      if (cur === ancestor) return true;
+      cur = composedParent(cur);
+    }
+    return false;
+  }
+
+  function getDeepActiveElement() {
+    let cur = document && document.activeElement ? document.activeElement : null;
+    let guard = 0;
+    while (cur && cur.shadowRoot && cur.shadowRoot.activeElement && guard++ < 20) {
+      cur = cur.shadowRoot.activeElement;
+    }
+    return cur;
+  }
+
+  function focusElementSafe(el) {
+    if (!el || typeof el.focus !== 'function') return false;
+    try {
+      el.focus({ preventScroll: true });
+      return true;
+    } catch {
+      try {
+        el.focus();
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+
+  function buildNodeRef(node, rootEl) {
+    if (!node) return null;
+    const tag = (() => {
+      try {
+        return lower(node.tagName || '');
+      } catch {
+        return '';
+      }
+    })();
+    const idVal = (() => {
+      try {
+        return trim(node.getAttribute && node.getAttribute('id'));
+      } catch {
+        return '';
+      }
+    })();
+    return {
+      tag: tag || null,
+      id: idVal || null,
+      withinRoot: !!(rootEl && isWithinComposedSubtree(node, rootEl))
+    };
+  }
+
+  function runFocusObservationWindow(fn) {
+    const w =
+      document && document.defaultView
+        ? document.defaultView
+        : typeof window !== 'undefined'
+          ? window
+          : null;
+    if (!w || typeof fn !== 'function') return;
+
+    const originalSetTimeout = typeof w.setTimeout === 'function' ? w.setTimeout.bind(w) : null;
+    const originalRequestAnimationFrame =
+      typeof w.requestAnimationFrame === 'function' ? w.requestAnimationFrame.bind(w) : null;
+    const originalQueueMicrotask =
+      typeof w.queueMicrotask === 'function' ? w.queueMicrotask.bind(w) : null;
+
+    const queuedMicrotasks = [];
+    const queuedRaf = [];
+    const queuedTimers = [];
+    let fakeTimerId = 1;
+
+    const patchedSetTimeout = function (cb, delay) {
+      const d = Number.isFinite(Number(delay)) ? Number(delay) : 0;
+      if (typeof cb === 'function' && d <= 200) {
+        const args = [];
+        for (let i = 2; i < arguments.length; i++) args.push(arguments[i]);
+        queuedTimers.push({ delay: d, cb: () => cb.apply(w, args) });
+        return fakeTimerId++;
+      }
+      if (originalSetTimeout) return originalSetTimeout.apply(w, arguments);
+      return fakeTimerId++;
+    };
+
+    const patchedRaf = function (cb) {
+      if (typeof cb === 'function') {
+        queuedRaf.push(cb);
+        return fakeTimerId++;
+      }
+      if (originalRequestAnimationFrame) return originalRequestAnimationFrame.apply(w, arguments);
+      return fakeTimerId++;
+    };
+
+    const patchedQueueMicrotask = function (cb) {
+      if (typeof cb === 'function') queuedMicrotasks.push(cb);
+    };
+
+    try {
+      if (originalSetTimeout) w.setTimeout = patchedSetTimeout;
+      if (originalRequestAnimationFrame) w.requestAnimationFrame = patchedRaf;
+      if (originalQueueMicrotask) w.queueMicrotask = patchedQueueMicrotask;
+      fn();
+
+      // Deterministic mini-window: microtasks -> rAF -> short timers (<=200ms).
+      let guard = 0;
+      while (
+        (queuedMicrotasks.length || queuedRaf.length || queuedTimers.length) &&
+        guard++ < 100
+      ) {
+        while (queuedMicrotasks.length) {
+          const mt = queuedMicrotasks.shift();
+          try {
+            mt();
+          } catch {}
+        }
+        while (queuedRaf.length) {
+          const rf = queuedRaf.shift();
+          try {
+            rf(16);
+          } catch {}
+        }
+        if (queuedTimers.length) {
+          queuedTimers.sort((a, b) => a.delay - b.delay);
+          const tt = queuedTimers.shift();
+          try {
+            tt.cb();
+          } catch {}
+        }
+      }
+    } finally {
+      if (originalSetTimeout) w.setTimeout = originalSetTimeout;
+      if (originalRequestAnimationFrame) w.requestAnimationFrame = originalRequestAnimationFrame;
+      if (originalQueueMicrotask) w.queueMicrotask = originalQueueMicrotask;
+    }
+  }
+
+  function probeImmediateFocusRedirect(entry) {
+    // Conservative downgrade gate:
+    // - only probe simple single-offender roots
+    // - only downgrade when focus moves immediately OUTSIDE the aria-hidden subtree
+    if (!entry || entry.count !== 1 || !entry.probeCandidates || !entry.probeCandidates.length)
+      return null;
+    const candidate = entry.probeCandidates[0];
+    if (!candidate) return null;
+
+    let focusedByEvent = false;
+    const onFocusCapture = () => {
+      focusedByEvent = true;
+    };
+    try {
+      candidate.addEventListener('focus', onFocusCapture, true);
+    } catch {
+      // ignore
+    }
+
+    const focusTrace = [];
+    const onFocusInCapture = (ev) => {
+      const n = ev && ev.target ? ev.target : null;
+      const ref = buildNodeRef(n, entry.rootEl);
+      if (ref) focusTrace.push(ref);
+    };
+    try {
+      document.addEventListener('focusin', onFocusInCapture, true);
+    } catch {
+      // ignore
+    }
+
+    const before = getDeepActiveElement();
+    const beforeRef = buildNodeRef(before, entry.rootEl);
+    if (beforeRef) focusTrace.push(beforeRef);
+
+    let focused = false;
+    runFocusObservationWindow(() => {
+      focused = focusElementSafe(candidate);
+    });
+
+    try {
+      document.removeEventListener('focusin', onFocusInCapture, true);
+    } catch {
+      // ignore
+    }
+
+    try {
+      candidate.removeEventListener('focus', onFocusCapture, true);
+    } catch {
+      // ignore
+    }
+    if (!focused || !focusedByEvent) return null;
+
+    const after = getDeepActiveElement();
+    const afterRef = buildNodeRef(after, entry.rootEl);
+    if (afterRef) focusTrace.push(afterRef);
+
+    // Best-effort restore to reduce side effects across checks.
+    if (before && before !== after) {
+      focusElementSafe(before);
+    }
+
+    if (!after || after === candidate) return null;
+    if (isWithinComposedSubtree(after, entry.rootEl)) return null;
+
+    const redirectedTag = (() => {
+      try {
+        return lower(after.tagName || '');
+      } catch {
+        return '';
+      }
+    })();
+    const redirectedId = (() => {
+      try {
+        return trim(after.getAttribute && after.getAttribute('id'));
+      } catch {
+        return '';
+      }
+    })();
+
+    return {
+      redirected: true,
+      redirectedToTag: redirectedTag || null,
+      redirectedToId: redirectedId || null,
+      focusTrace
+    };
+  }
+
   // Lightweight "invisible but still focusable" hints.
   // Only computed for a capped set of offenders per aria-hidden root.
   function getVisibilityHints(el) {
     const out = [];
     if (!el) return out;
 
-    let cs = null;
+    let cs;
     try {
-      const w = (document && document.defaultView) ? document.defaultView : (typeof window !== 'undefined' ? window : null);
+      const w =
+        document && document.defaultView
+          ? document.defaultView
+          : typeof window !== 'undefined'
+            ? window
+            : null;
       cs = w && w.getComputedStyle ? w.getComputedStyle(el) : null;
     } catch {
       cs = null;
@@ -146,11 +403,15 @@ function runInPage(ctx) {
       // Common visually-hidden patterns
       if (clipLow && clipLow !== 'auto') {
         // Examples: rect(0px, 0px, 0px, 0px) / rect(0,0,0,0)
-        if (clipLow.indexOf('rect(') !== -1 && clipLow.replace(/\s+/g, '').indexOf('rect(0') !== -1) out.push('clipped');
+        if (clipLow.indexOf('rect(') !== -1 && clipLow.replace(/\s+/g, '').indexOf('rect(0') !== -1)
+          out.push('clipped');
       }
       if (clipPathLow && clipPathLow !== 'none') {
         // Examples: inset(100%) / inset(50%)
-        if (clipPathLow.indexOf('inset(') !== -1 && (clipPathLow.indexOf('100%') !== -1 || clipPathLow.indexOf('50%') !== -1)) {
+        if (
+          clipPathLow.indexOf('inset(') !== -1 &&
+          (clipPathLow.indexOf('100%') !== -1 || clipPathLow.indexOf('50%') !== -1)
+        ) {
           out.push('clipped');
         }
       }
@@ -205,7 +466,10 @@ function runInPage(ctx) {
     const uniq = [];
     for (const k of out) {
       const kk = String(k);
-      if (!seen.has(kk)) { seen.add(kk); uniq.push(kk); }
+      if (!seen.has(kk)) {
+        seen.add(kk);
+        uniq.push(kk);
+      }
     }
     return uniq;
   }
@@ -223,16 +487,17 @@ function runInPage(ctx) {
     // An explicit negative tabindex removes the element from the keyboard
     // tab sequence entirely, regardless of tag — the standard, WAI-
     // recommended technique for safely hiding focusable content behind
-    // aria-hidden (verified against a widely-used reference engine's own aria-hidden-focus check,
-    // which requires tabbability — not raw focusability — via its
-    // `focusable-not-tabbable` sub-check; confirmed via a real page:
-    // Wikipedia's sticky header uses <button tabindex="-1">/<a tabindex="-1">
-    // inside aria-hidden divs, a correct pattern this rule was previously
-    // flagging as a false positive). Such an element is still
-    // programmatically focusable (script could call .focus()), but that's
-    // not what "no focusable content behind aria-hidden" cares about.
+    // aria-hidden (e.g. <button tabindex="-1"> / <a tabindex="-1"> inside
+    // an aria-hidden container). This cares about tabbability, not raw
+    // focusability. Such an element is still programmatically focusable
+    // (script could call .focus()), but that's not what "no focusable
+    // content behind aria-hidden" cares about.
     const explicitTabindex = trim(el.getAttribute('tabindex'));
-    if (explicitTabindex !== '' && !Number.isNaN(Number(explicitTabindex)) && Number(explicitTabindex) < 0) {
+    if (
+      explicitTabindex !== '' &&
+      !Number.isNaN(Number(explicitTabindex)) &&
+      Number(explicitTabindex) < 0
+    ) {
       return false;
     }
 
@@ -240,7 +505,11 @@ function runInPage(ctx) {
     // Prefer helper for broad coverage, but do not let aria-hidden flip focusable->false.
     let helperInfo = null;
     if (getFocusableInfo) {
-      try { helperInfo = getFocusableInfo(el, ctx); } catch { helperInfo = null; }
+      try {
+        helperInfo = getFocusableInfo(el, ctx);
+      } catch {
+        helperInfo = null;
+      }
     }
 
     // Local fallback that does NOT care about aria-hidden
@@ -257,7 +526,11 @@ function runInPage(ctx) {
       fallbackFocusable = type !== 'hidden';
     } else if (tag === 'iframe') {
       fallbackFocusable = true;
-    } else if ((tag === 'audio' || tag === 'video') && el.hasAttribute && el.hasAttribute('controls')) {
+    } else if (
+      (tag === 'audio' || tag === 'video') &&
+      el.hasAttribute &&
+      el.hasAttribute('controls')
+    ) {
       fallbackFocusable = true;
     } else if (el.hasAttribute && el.hasAttribute('contenteditable')) {
       // contenteditable="false" explicitly disables the editing host and
@@ -282,7 +555,10 @@ function runInPage(ctx) {
     // IMPORTANT: Do NOT exclude opacity-based invisibility; opacity:0 remains in-scope.
     if (isDomVisibleEligible) {
       try {
-        const vis = isDomVisibleEligible(el, ctx, { visibilityMode: 'styleOnly', disableGeometry: true });
+        const vis = isDomVisibleEligible(el, ctx, {
+          visibilityMode: 'styleOnly',
+          disableGeometry: true
+        });
         if (vis && vis.eligible === false) {
           const rs = Array.isArray(vis.reasons) ? vis.reasons : [];
           const nonOpacity = rs.filter((r) => String(r) !== 'opacityZero');
@@ -319,8 +595,16 @@ function runInPage(ctx) {
     }
     try {
       const tag = lower(el.tagName || '');
-      if ((tag === 'button' || tag === 'input' || tag === 'select' || tag === 'textarea' || tag === 'option' || tag === 'optgroup') &&
-          el.hasAttribute && el.hasAttribute('disabled')) {
+      if (
+        (tag === 'button' ||
+          tag === 'input' ||
+          tag === 'select' ||
+          tag === 'textarea' ||
+          tag === 'option' ||
+          tag === 'optgroup') &&
+        el.hasAttribute &&
+        el.hasAttribute('disabled')
+      ) {
         return true;
       }
     } catch {
@@ -341,8 +625,9 @@ function runInPage(ctx) {
     'a[href],area[href],button,input,select,textarea,summary,iframe,audio[controls],video[controls],[tabindex],[contenteditable]'
   );
 
-  const bucket = new Map(); // ariaHiddenRoot -> { rootEl, count, offenders: [], hints:Set, rootIsFocusable }
+  const bucket = new Map(); // ariaHiddenRoot -> { rootEl, count, offenders: [], hints:Set, rootIsFocusable, probeCandidates: [] }
   const maxOffendersPerRoot = 5;
+  const maxProbeCandidatesPerRoot = 3;
 
   for (let i = 0; i < focusableCandidates.length; i++) {
     const el = focusableCandidates[i];
@@ -354,10 +639,9 @@ function runInPage(ctx) {
     // cheaper first cannot change which elements end up in the bucket —
     // it only skips the expensive check for the (typically vast) majority
     // of focusable candidates that were never inside an aria-hidden root
-    // in the first place. On a real page with a large focusable-candidate
-    // count and a complex stylesheet (Daily Mail: ~1400 links, ~3600 CSS
-    // rules), this cut this check's runtime from ~30s to well under 1s —
-    // a pure ordering change, not a behavior change.
+    // in the first place. On pages with many focusable candidates and a
+    // large stylesheet this is a big speedup, and a pure ordering change,
+    // not a behavior change.
     const rootEl = closestAriaHiddenTrue(el);
     if (!rootEl) continue;
 
@@ -365,22 +649,46 @@ function runInPage(ctx) {
 
     let entry = bucket.get(rootEl);
     if (!entry) {
-      entry = { rootEl, count: 0, offenders: [], hints: new Set(), rootIsFocusable: false };
+      entry = {
+        rootEl,
+        count: 0,
+        offenders: [],
+        hints: new Set(),
+        rootIsFocusable: false,
+        probeCandidates: []
+      };
       bucket.set(rootEl, entry);
     }
     entry.count += 1;
+    if (entry.probeCandidates.length < maxProbeCandidatesPerRoot) entry.probeCandidates.push(el);
 
     // Capture a small, deterministic offender summary + visibility hints.
     if (entry.offenders.length < maxOffendersPerRoot) {
-      let tag = '';
-      let ti = null;
-      let href = null;
-      let type = null;
+      let tag;
+      let ti;
+      let href;
+      let type;
 
-      try { tag = lower(el.tagName || ''); } catch { tag = ''; }
-      try { ti = el.getAttribute('tabindex'); } catch { ti = null; }
-      try { href = (tag === 'a' || tag === 'area') ? trim(el.getAttribute('href')) : null; } catch { href = null; }
-      try { type = tag === 'input' ? lower(el.getAttribute('type') || '') : null; } catch { type = null; }
+      try {
+        tag = lower(el.tagName || '');
+      } catch {
+        tag = '';
+      }
+      try {
+        ti = el.getAttribute('tabindex');
+      } catch {
+        ti = null;
+      }
+      try {
+        href = tag === 'a' || tag === 'area' ? trim(el.getAttribute('href')) : null;
+      } catch {
+        href = null;
+      }
+      try {
+        type = tag === 'input' ? lower(el.getAttribute('type') || '') : null;
+      } catch {
+        type = null;
+      }
 
       const hints = getVisibilityHints(el);
       for (const h of hints) entry.hints.add(h);
@@ -406,12 +714,19 @@ function runInPage(ctx) {
   }
 
   // 3) Report one occurrence per aria-hidden root that contains focusable content.
-  const occurrences = [];
+  const failOccurrences = [];
+  const uncertainOccurrences = [];
   for (const [, entry] of bucket) {
     const el = entry.rootEl;
 
     const eligInfo = getEligibilityInfo
-      ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
+      ? (() => {
+          try {
+            return getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
       : null;
 
     // stable visibility hint ordering
@@ -419,7 +734,13 @@ function runInPage(ctx) {
     const hintsArr = [];
     for (const k of hintOrder) if (entry.hints.has(k)) hintsArr.push(k);
 
-    const tagName = (() => { try { return lower(el.tagName || ''); } catch { return ''; } })();
+    const tagName = (() => {
+      try {
+        return lower(el.tagName || '');
+      } catch {
+        return '';
+      }
+    })();
 
     // Split counts deterministically
     const selfFocusable = !!entry.rootIsFocusable;
@@ -427,36 +748,56 @@ function runInPage(ctx) {
     const descendantFocusable = selfFocusable ? Math.max(0, totalFocusable - 1) : totalFocusable;
 
     const summaryKey = selfFocusable
-      ? (descendantFocusable > 0
-          ? 'ariaHidden_focus_summary_fail_self_and_desc'
-          : 'ariaHidden_focus_summary_fail_self')
+      ? descendantFocusable > 0
+        ? 'ariaHidden_focus_summary_fail_self_and_desc'
+        : 'ariaHidden_focus_summary_fail_self'
       : 'ariaHidden_focus_summary_fail_desc';
 
     const reasonCode = selfFocusable
-      ? (descendantFocusable > 0 ? 'ariaHiddenSelfAndDescendantsFocusable' : 'ariaHiddenSelfFocusable')
+      ? descendantFocusable > 0
+        ? 'ariaHiddenSelfAndDescendantsFocusable'
+        : 'ariaHiddenSelfFocusable'
       : 'ariaHiddenContainsFocusable';
 
     const summaryText = selfFocusable
-      ? (descendantFocusable > 0
-          ? `aria-hidden ${tagName} is focusable and contains ${descendantFocusable} focusable descendant(s) (${totalFocusable} focusable element(s) total).`
-          : `aria-hidden ${tagName} is focusable (${totalFocusable} focusable element(s)).`)
+      ? descendantFocusable > 0
+        ? `aria-hidden ${tagName} is focusable and contains ${descendantFocusable} focusable descendant(s) (${totalFocusable} focusable element(s) total).`
+        : `aria-hidden ${tagName} is focusable (${totalFocusable} focusable element(s)).`
       : `aria-hidden ${tagName} contains ${totalFocusable} focusable element(s).`;
 
+    const runtimeProbe = probeImmediateFocusRedirect(entry);
+    const downgradedToCantTell = !!(runtimeProbe && runtimeProbe.redirected);
+
+    const cantTellSummary = `aria-hidden ${tagName} received focus but focus moved immediately to another element. Verify sentinel/focus-trap behavior.`;
+
     const baseOccurrence = {
-      summary: summaryText,
-      hint: 'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.',
+      summary: downgradedToCantTell ? cantTellSummary : summaryText,
+      hint: downgradedToCantTell
+        ? 'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on hidden focus targets.'
+        : 'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.',
+      occurrenceOutcome: downgradedToCantTell ? 'cantTell' : 'fail',
       i18n: {
-        summaryKey,
-        hintKey: 'ariaHidden_focus_hint_fail',
+        summaryKey: downgradedToCantTell
+          ? 'ariaHidden_focus_summary_cantTell_redirect'
+          : summaryKey,
+        hintKey: downgradedToCantTell
+          ? 'ariaHidden_focus_hint_cantTell_redirect'
+          : 'ariaHidden_focus_hint_fail',
         params: {
           element: tagName,
           focusableCount: String(totalFocusable),
-          descendantFocusableCount: String(descendantFocusable)
+          descendantFocusableCount: String(descendantFocusable),
+          redirectedToTag:
+            runtimeProbe && runtimeProbe.redirectedToTag ? runtimeProbe.redirectedToTag : '',
+          redirectedToId:
+            runtimeProbe && runtimeProbe.redirectedToId ? runtimeProbe.redirectedToId : ''
         }
       },
       data: {
         details: {
-          reasonCode,
+          reasonCode: downgradedToCantTell
+            ? 'ariaHiddenFocusable_runtimeRedirect_needsReview'
+            : reasonCode,
           metrics: {
             focusableTotal: totalFocusable,
             focusableDescendants: descendantFocusable,
@@ -464,17 +805,30 @@ function runInPage(ctx) {
             offendersCaptured: entry.offenders.length,
             visibilityHints: hintsArr.slice(0)
           },
+          runtimeProbe: runtimeProbe || null,
           offenders: entry.offenders.slice(0)
         },
         visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
       }
     };
 
-    if (reportOccurrence) occurrences.push(reportOccurrence(el, baseOccurrence));
-    else occurrences.push({ __node: el, selector: '', html: '', ...baseOccurrence });
+    const occurrence = reportOccurrence
+      ? reportOccurrence(el, baseOccurrence)
+      : { __node: el, selector: '', html: '', ...baseOccurrence };
+
+    if (downgradedToCantTell) uncertainOccurrences.push(occurrence);
+    else failOccurrences.push(occurrence);
   }
 
-  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+  // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
+  // a fail-tier finding never silently discards cantTell-tier findings from
+  // the same run — both are returned together when the outcome is 'fail'.
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    uncertainOccurrences,
+    rule.defaultSeverity || 'minor'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };