@surea11y/core 1.3.0 → 1.4.1

package/src/checks/automatic/iframe-focusable-content.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -62,10 +64,141 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { helpers, rule } = ctx;
+  const { helpers, rule, document } = ctx;
+
+  // Self-contained rendering check for the embedded document (a distinct
+  // realm — see this rule's own header comment on why the outer
+  // document's shared eligibility helpers can't be reused here).
+  // Deliberately checks only genuine non-rendering (display:none,
+  // visibility:hidden, the hidden attribute) via the ancestor chain, NOT
+  // aria-hidden: aria-hidden alone does not remove an element from a real
+  // browser's native tab order (the same anti-pattern this engine's own
+  // aria-hidden-focus rule exists to catch), so an aria-hidden-but-
+  // visually-rendered focusable element inside the frame is still
+  // genuinely reachable by keyboard and must stay flagged.
+  function isRenderedInDoc(doc, el) {
+    try {
+      const view = doc.defaultView;
+      if (!view || typeof view.getComputedStyle !== 'function') return true;
+      let node = el;
+      while (node && node.nodeType === 1) {
+        if (node.hasAttribute && node.hasAttribute('hidden')) return false;
+        const cs = view.getComputedStyle(node);
+        if (cs) {
+          if (cs.display === 'none') return false;
+          if (cs.visibility === 'hidden' || cs.visibility === 'collapse') return false;
+        }
+        node = node.parentElement;
+      }
+      return true;
+    } catch {
+      return true;
+    }
+  }
+
+  function getDeepActiveElement(docRef) {
+    let cur = docRef && docRef.activeElement ? docRef.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 runFocusObservationWindow(win, fn) {
+    if (!win || typeof fn !== 'function') return;
+    const originalSetTimeout =
+      typeof win.setTimeout === 'function' ? win.setTimeout.bind(win) : null;
+    const originalRequestAnimationFrame =
+      typeof win.requestAnimationFrame === 'function' ? win.requestAnimationFrame.bind(win) : null;
+    const originalQueueMicrotask =
+      typeof win.queueMicrotask === 'function' ? win.queueMicrotask.bind(win) : 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(win, args) });
+        return fakeTimerId++;
+      }
+      if (originalSetTimeout) return originalSetTimeout.apply(win, arguments);
+      return fakeTimerId++;
+    };
+
+    const patchedRaf = function (cb) {
+      if (typeof cb === 'function') {
+        queuedRaf.push(cb);
+        return fakeTimerId++;
+      }
+      if (originalRequestAnimationFrame) return originalRequestAnimationFrame.apply(win, arguments);
+      return fakeTimerId++;
+    };
+
+    const patchedQueueMicrotask = function (cb) {
+      if (typeof cb === 'function') queuedMicrotasks.push(cb);
+    };
+
+    try {
+      if (originalSetTimeout) win.setTimeout = patchedSetTimeout;
+      if (originalRequestAnimationFrame) win.requestAnimationFrame = patchedRaf;
+      if (originalQueueMicrotask) win.queueMicrotask = patchedQueueMicrotask;
+      fn();
 
-  function hasFocusableCandidate(doc) {
-    if (!doc || !doc.querySelectorAll) return false;
+      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) win.setTimeout = originalSetTimeout;
+      if (originalRequestAnimationFrame) win.requestAnimationFrame = originalRequestAnimationFrame;
+      if (originalQueueMicrotask) win.queueMicrotask = originalQueueMicrotask;
+    }
+  }
+
+  function getFocusableCandidates(doc) {
+    if (!doc || !doc.querySelectorAll) return [];
     let els;
     try {
       els = doc.querySelectorAll(
@@ -73,8 +206,9 @@ function runInPage(ctx) {
           'select:not([disabled]), textarea:not([disabled]), iframe, [contenteditable="true"], [tabindex]'
       );
     } catch {
-      return false;
+      return [];
     }
+    const candidates = [];
     for (const el of els) {
       if (!el || !el.getAttribute) continue;
       const raw = el.getAttribute('tabindex');
@@ -82,9 +216,77 @@ function runInPage(ctx) {
         const n = Number(String(raw).trim());
         if (!Number.isNaN(n) && n < 0) continue; // explicitly removed from tab order
       }
-      return true;
+      if (!isRenderedInDoc(doc, el)) continue; // display:none/visibility:hidden/[hidden]: never reachable at all
+      candidates.push(el);
     }
-    return false;
+    return candidates;
+  }
+
+  function probeImmediateFocusRedirect(frameEl, embeddedDoc, candidate) {
+    if (!frameEl || !embeddedDoc || !candidate) return null;
+    const embeddedWindow = embeddedDoc.defaultView;
+    if (!embeddedWindow) return null;
+
+    let focusedByEvent = false;
+    const onFocusCapture = () => {
+      focusedByEvent = true;
+    };
+    try {
+      candidate.addEventListener('focus', onFocusCapture, true);
+    } catch {}
+
+    const innerFocusTrace = [];
+    const outerFocusTrace = [];
+    const onInnerFocusIn = (ev) => {
+      if (ev && ev.target) innerFocusTrace.push(ev.target);
+    };
+    const onOuterFocusIn = (ev) => {
+      if (ev && ev.target) outerFocusTrace.push(ev.target);
+    };
+    try {
+      embeddedDoc.addEventListener('focusin', onInnerFocusIn, true);
+      document.addEventListener('focusin', onOuterFocusIn, true);
+    } catch {}
+
+    const beforeInner = getDeepActiveElement(embeddedDoc);
+    const beforeOuter = getDeepActiveElement(document);
+    let focused = false;
+    runFocusObservationWindow(embeddedWindow, () => {
+      focused = focusElementSafe(candidate);
+    });
+    try {
+      embeddedDoc.removeEventListener('focusin', onInnerFocusIn, true);
+      document.removeEventListener('focusin', onOuterFocusIn, true);
+    } catch {}
+    try {
+      candidate.removeEventListener('focus', onFocusCapture, true);
+    } catch {}
+
+    if (!focused) return null;
+
+    const afterInner = getDeepActiveElement(embeddedDoc);
+    const afterOuter = getDeepActiveElement(document);
+    const sawRedirectedInnerTrace = innerFocusTrace.some((n) => n && n !== candidate);
+    const sawRedirectedOuterTrace = outerFocusTrace.some(
+      (n) => n && n !== frameEl && n !== candidate
+    );
+    const redirectedWithinFrame =
+      !!(afterInner && afterInner !== candidate) || sawRedirectedInnerTrace;
+    const redirectedOutOfFrame =
+      !!(afterOuter && afterOuter !== frameEl) || sawRedirectedOuterTrace;
+    const sawCandidateFocus = focusedByEvent || innerFocusTrace.some((n) => n === candidate);
+
+    if (beforeInner && beforeInner !== afterInner) focusElementSafe(beforeInner);
+    if (beforeOuter && beforeOuter !== afterOuter) focusElementSafe(beforeOuter);
+
+    if (!sawCandidateFocus) return null;
+    if (!redirectedWithinFrame && !redirectedOutOfFrame) return null;
+
+    return {
+      redirected: true,
+      redirectedWithinFrame,
+      redirectedOutOfFrame
+    };
   }
 
   function getNegativeTabIndex(el) {
@@ -98,7 +300,8 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart('iframe, frame')
     : helpers.queryAll('iframe, frame');
 
-  const occurrences = [];
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
@@ -115,13 +318,37 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    if (!hasFocusableCandidate(contentDoc)) continue;
+    const candidates = getFocusableCandidates(contentDoc);
+    if (!candidates.length) continue;
 
     const tag = el.tagName.toLowerCase();
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
     const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
+    const shouldProbe = candidates.length === 1;
+    const runtimeProbe = shouldProbe
+      ? probeImmediateFocusRedirect(el, contentDoc, candidates[0])
+      : null;
+
+    if (runtimeProbe && runtimeProbe.redirected) {
+      cantTellOccurrences.push({
+        selector: stableSelector,
+        html,
+        summary:
+          'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
+        hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
+        i18n: null,
+        data: {
+          details: {
+            reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',
+            element: tag,
+            runtimeProbe
+          }
+        }
+      });
+      continue;
+    }
 
-    occurrences.push({
+    failOccurrences.push({
       selector: stableSelector,
       html,
       summary:
@@ -141,15 +368,16 @@ function runInPage(ctx) {
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  // helpers.resolveTieredOutcome is unconditionally provided by dom-helpers.js
+  // (see its own header comment) -- no fallback needed, matching the same
+  // cleanup already applied to aria-hidden-focus.js/aria-prohibited-attr.js/
+  // target-size-minimum.js.
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'moderate'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/iframe-name-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

package/src/checks/automatic/iframe-title-unique.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,7 +20,7 @@
  *   a frame can have a non-empty title while still failing uniqueness.
  * - Compares the title ATTRIBUTE specifically, not the full computed
  *   accessible name (aria-label could legitimately differ in wording even
- *   when title happens to collide) — matches a widely-used reference engine's frame-title-unique.
+ *   when title happens to collide).
  * - Not rule-gated on isAccTreeEligible: duplicate titles are a static
  *   markup property. Engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.

package/src/checks/automatic/img-alt-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -7,10 +9,10 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to <img> elements that are exposed to assistive technologies.
- *   Images with role="presentation" or role="none" are excluded only when they are not focusable.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to <img> elements included in the accessibility tree.
+ *   Images with role="presentation" or role="none" are excluded only when they are not focusable,
+ *   since a focusable one reverts to the img role under presentational roles conflict resolution.
+ *   Hidden images are excluded whether or not they are focusable.
  * @expectation
  *   Each applicable <img> element has an alt attribute.
  *   The alt attribute may be empty (alt="").
@@ -58,8 +60,15 @@ function runInPage(ctx) {
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // ACT 23a2a8 exempts programmatically hidden images, and that glossary term
+  // has no focusability carve-out, so an aria-hidden image stays out of scope
+  // even when tabbable; aria-hidden-focus reports that markup instead.
+  const isEligibleHelper =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
   const getFocusableInfo =
     helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
   const getAriaNameInfo =
@@ -111,11 +120,11 @@ function runInPage(ctx) {
     const el = imgs[i];
     if (!el || !el.getAttribute) continue;
 
-    // Eligibility: only imgs exposed to assistive tech (with focusable/IDREF exceptions handled by helper)
-    if (isAccTreeEligible) {
+    // Eligibility: only imgs exposed to assistive tech.
+    if (isEligibleHelper) {
       let elig;
       try {
-        elig = isAccTreeEligible(el, ctx);
+        elig = isEligibleHelper(el, ctx);
       } catch {
         elig = null;
       }
@@ -172,15 +181,11 @@ function runInPage(ctx) {
       if (ariaName && ariaName.present) continue;
     }
 
-    // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source for <img> once alt is entirely absent (not merely alt="",
-    // which explicitly marks decorative and stays excluded from this
-    // branch since hasAlt already short-circuited above) -- confirmed
-    // against a widely-used reference engine's own image-alt rule, which lists a non-empty
-    // title as one of its "any" satisfying conditions alongside has-alt/
-    // aria-label/aria-labelledby. Found via a real page (AliExpress's
-    // logo, 2026-07-23): <img src="..." title="...">, no alt attribute
-    // at all -- a real false positive, not a missing text alternative.
+    // A non-empty title attribute is HTML-AAM's next fallback naming source
+    // for <img> once alt is entirely absent (not merely alt="", which
+    // explicitly marks decorative and stays excluded from this branch since
+    // hasAlt already short-circuited above). An `<img src="..." title="...">`
+    // with no alt attribute at all is not missing a text alternative.
     const title = trim(el.getAttribute('title'));
     if (title) continue;
 

package/src/checks/automatic/input-image-alt-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -7,11 +9,10 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to <input type="image"> elements that are exposed to assistive technologies.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to <input type="image"> elements included in the accessibility tree.
  * @expectation
- *   Each applicable <input type="image"> element has an alt attribute.
+ *   Each applicable <input type="image"> element has an alt attribute, and its
+ *   accessible name is not the browser default for an image button.
  *   The alt attribute may be empty (alt="").
  */
 
@@ -70,8 +71,14 @@ function runInPage(ctx) {
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // ACT 59796f applies to image buttons included in the accessibility tree,
+  // which excludes focusable content inside aria-hidden.
+  const isEligibleHelper =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
 
   const getAriaNameInfo =
     helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
@@ -97,67 +104,109 @@ function runInPage(ctx) {
   for (const el of inputs) {
     if (!el || !el.getAttribute) continue;
 
-    // Applicability: eligible in the acc tree (with helper exceptions).
-    if (isAccTreeEligible) {
+    if (isEligibleHelper) {
       const elig = (() => {
         try {
-          return isAccTreeEligible(el, ctx);
+          return isEligibleHelper(el, ctx);
         } catch {
-          return { eligible: true, reasons: [] };
+          return true;
         }
       })();
-      if (elig && elig.eligible === false) continue;
+      const eligible = typeof elig === 'boolean' ? elig : !(elig && elig.eligible === false);
+      if (!eligible) continue;
     }
 
     applicableCount += 1;
 
-    const hasAlt = el.getAttribute('alt') !== null;
-    if (hasAlt) continue;
-
-    // aria-label / aria-labelledby is also a valid, standards-recognized
-    // text-alternative mechanism for <input type="image"> (HTML-AAM
-    // accessible name computation includes ARIA naming before falling
-    // back to alt).
-    if (getAriaNameInfo) {
-      let ariaName;
-      try {
-        ariaName = getAriaNameInfo(el, ctx);
-      } catch {
-        ariaName = null;
+    // The browser's own fallback name for an image button carries no
+    // information, so an author-supplied name equal to it is treated as no
+    // name at all (ACT 59796f). Only the English defaults are recognised:
+    // "Submit Query" from HTML-AAM, "Submit" from Chrome.
+    const effectiveName = (() => {
+      let v = '';
+      if (getAriaNameInfo) {
+        try {
+          const aria = getAriaNameInfo(el, ctx);
+          if (aria && aria.present && aria.value) v = String(aria.value);
+        } catch {
+          v = '';
+        }
       }
-      if (ariaName && ariaName.present) continue;
-    }
-
-    // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source once alt is entirely absent -- also accepted by a widely-used
-    // reference engine's equivalent input-image-alt rule (non-empty-title, same "any" list
-    // as non-empty-alt/aria-label/aria-labelledby). See img-alt-present's
-    // sibling fix (2026-07-23, AliExpress's title-only logo <img>) for
-    // the real page this was found via -- same gap, same fix, different
-    // element.
-    const titleRaw = (() => {
-      try {
-        return el.getAttribute('title');
-      } catch {
-        return null;
+      if (!v) {
+        const alt = el.getAttribute('alt');
+        if (alt != null && String(alt).trim()) v = String(alt);
+      }
+      if (!v) {
+        const t = el.getAttribute('title');
+        if (t != null && String(t).trim()) v = String(t);
       }
+      return v.trim().toLowerCase();
     })();
-    if (titleRaw !== null && String(titleRaw).trim()) continue;
+
+    if (effectiveName === 'submit query' || effectiveName === 'submit') {
+      const eligInfoDefault = getEligibilityInfo
+        ? getEligibilityInfo(el, ctx, { targetSet: 'acc' })
+        : null;
+      const defaultNameOccurrence = {
+        summary:
+          'Accessible name is the browser default for an image button, which conveys nothing.',
+        hint: 'Replace it with text describing what the button does, for example "Search".',
+        i18n: {
+          summaryKey: 'inputImage_altPresent_summary_defaultName',
+          hintKey: 'inputImage_altPresent_hint_defaultName',
+          params: { element: 'input[type=image]' }
+        },
+        data: {
+          visibilityFilter: eligInfoDefault || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: { reasonCode: 'default_name' }
+        }
+      };
+      occurrences.push(
+        helpers && typeof helpers.reportOccurrence === 'function'
+          ? helpers.reportOccurrence(el, defaultNameOccurrence)
+          : { selector: '', html: '', ...defaultNameOccurrence }
+      );
+      continue;
+    }
+
+    // effectiveName already covers the naming sources HTML-AAM allows here,
+    // in order: aria-label/aria-labelledby, then alt, then title.
+    if (effectiveName) continue;
+
+    // An image button is a control, so an empty name fails whether alt is
+    // absent or present-but-empty. alt="" marks a decorative image, and an
+    // image button is never decorative.
+    const emptyAlt = el.getAttribute('alt') !== null;
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
-    const baseOccurrence = {
-      summary: 'Missing alt attribute on <input type="image">.',
-      hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
-      i18n: {
-        summaryKey: 'inputImage_altPresent_summary_fail',
-        hintKey: 'inputImage_altPresent_hint_fail',
-        params: { element: 'input[type=image]' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    };
+    const baseOccurrence = emptyAlt
+      ? {
+          summary: 'Empty alt="" on <input type="image"> leaves the control unnamed.',
+          hint: 'Describe the action in alt, or name the control with aria-label or aria-labelledby.',
+          i18n: {
+            summaryKey: 'inputImage_altPresent_summary_emptyAlt',
+            hintKey: 'inputImage_altPresent_hint_emptyAlt',
+            params: { element: 'input[type=image]' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode: 'empty_alt' }
+          }
+        }
+      : {
+          summary: 'Missing alt attribute on <input type="image">.',
+          hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
+          i18n: {
+            summaryKey: 'inputImage_altPresent_summary_fail',
+            hintKey: 'inputImage_altPresent_hint_fail',
+            params: { element: 'input[type=image]' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode: 'missing_alt' }
+          }
+        };
 
     if (helpers && typeof helpers.reportOccurrence === 'function') {
       occurrences.push(helpers.reportOccurrence(el, baseOccurrence));