@surea11y/core 1.3.0 → 1.4.1

package/src/checks/manual/empty-table-header-manual.js

@@ -1,36 +1,30 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check empty-table-header
  * @atomic true
  * @summary Table header cells must not be empty
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies to <th> elements that don't carry a conflicting explicit role,
  *   plus any element (native <th> or not) with role="columnheader" or
- *   role="rowheader" — matches a widely-used reference engine's own
- *   `empty-table-header` selector exactly (`th:not([role]), [role="columnheader"], [role="rowheader"]`,
- *   verified directly against its rule descriptor): a <th> that explicitly
- *   restates role="columnheader"/"rowheader" is still covered via the second
- *   clause, but a <th role="presentation"> (no longer meaningfully a header)
- *   is correctly excluded, and an ARIA-role-only header (e.g. a <div
- *   role="columnheader"> in a role="grid"/role="table" widget) is caught too
- *   — found missing entirely via the cross-engine diff tool 2026-07-23.
+ *   role="rowheader" (`th:not([role]), [role="columnheader"], [role="rowheader"]`):
+ *   a <th> that explicitly restates role="columnheader"/"rowheader" is still
+ *   covered via the second clause, but a <th role="presentation"> (no longer
+ *   meaningfully a header) is correctly excluded, and an ARIA-role-only header
+ *   (e.g. a <div role="columnheader"> in a role="grid"/role="table" widget) is
+ *   caught too.
  * @expectation
  *   The header cell has visible text content. A <th> named only via
  *   aria-label/aria-labelledby (no visible text) is ALSO flagged, not
- *   treated as equivalent — real screen-reader/browser testing (found via
- *   a live-DOM cross-engine run 2026-07-21, verified against
- *   https://butterpep.com/table-header-naming.html and
- *   https://html5accessibility.com/stuff/2024/05/22/not-so-short-note-on-aria-label-usage-big-table-edition/)
- *   confirms aria-label support on <th> is genuinely inconsistent in
- *   practice: NVDA+Firefox and iOS VoiceOver+Safari ignore it entirely
- *   (only visible text is announced), JAWS+Chrome/IE11 also only announce
- *   visible text in the header cell itself. Visible text is the one
- *   mechanism confirmed to work across every tested combination. A widely-used
- *   reference engine's own equivalent check (`has-visible-text` only, no aria-label/
- *   aria-labelledby alternative — confirmed directly against its rule
- *   descriptor) reaches the same conclusion.
+ *   treated as equivalent — aria-label support on <th> is genuinely
+ *   inconsistent in practice: NVDA+Firefox and iOS VoiceOver+Safari ignore
+ *   it entirely (only visible text is announced), JAWS+Chrome/IE11 also only
+ *   announce visible text in the header cell itself. Visible text is the one
+ *   mechanism confirmed to work across every tested combination. See
+ *   https://html5accessibility.com/stuff/2024/05/22/not-so-short-note-on-aria-label-usage-big-table-edition/.
  * @implementation-notes
  * - Not WCAG-normative — authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
@@ -72,8 +66,36 @@ function runInPage(ctx) {
       .trim();
   }
 
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  function isEligible(node) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(node, ctx);
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  // Plain el.textContent includes text from aria-hidden descendants, which
+  // a real screen reader never announces. A <th> whose only text comes from
+  // an aria-hidden descendant (e.g. <th><span aria-hidden="true">Name</span
+  // ></th>) would otherwise be treated as having visible text, even though
+  // AT announces nothing for it.
   function getVisibleText(el) {
-    return normalizeWs(el.textContent);
+    function walk(node) {
+      if (node.nodeType === 3) return node.nodeValue || '';
+      if (node.nodeType !== 1) return '';
+      if (!isEligible(node)) return '';
+      let text = '';
+      for (const child of node.childNodes || []) text += walk(child);
+      return text;
+    }
+    let text = '';
+    for (const child of el.childNodes || []) text += walk(child);
+    return normalizeWs(text);
   }
 
   function getAriaOnlyName(el) {
@@ -97,9 +119,8 @@ function runInPage(ctx) {
     return '';
   }
 
-  // Matches a widely-used reference engine's own empty-table-header selector exactly: a <th> with
-  // no conflicting explicit role, plus any element carrying an explicit
-  // columnheader/rowheader role (native or not).
+  // A <th> with no conflicting explicit role, plus any element carrying an
+  // explicit columnheader/rowheader role (native or not).
   const selector = 'th:not([role]), [role="columnheader"], [role="rowheader"]';
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(selector)
@@ -110,6 +131,12 @@ function runInPage(ctx) {
 
   for (const el of nodes) {
     if (!el) continue;
+
+    // A fully aria-hidden header cell isn't part of the AT-perceived
+    // table structure at all -- queryAllSmart's default hidden-content
+    // policy only excludes "hard" CSS-based hiding, not aria-hidden.
+    if (!isEligible(el)) continue;
+
     applicableCount += 1;
 
     if (getVisibleText(el)) continue;

package/src/checks/manual/focus-order-semantics-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check focus-order-semantics
  * @atomic true
  * @summary Elements added to the tab order should have interactive semantics
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Elements with an explicit `tabindex` of `0` or greater (in the tab
  *   order) AND an explicit `role` attribute that is one of a curated set
@@ -16,8 +18,8 @@
  *   announce, which is confusing for keyboard users who land on it and
  *   get no indication of what activating it (if anything) would do.
  * @implementation-notes
- * - Not WCAG-normative by a widely-used reference engine's own classification — authored as an
- *   advisory, cantTell-capped `type: 'manual'` rule.
+ * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule.
  * - The non-interactive role list is deliberately curated and
  *   conservative (structural/document roles only) — legitimate custom
  *   widget patterns using `tabindex` with a genuinely interactive role
@@ -25,6 +27,17 @@
  *   `tabindex` and NO role at all are also not flagged: native semantics
  *   or an intentionally generic custom-interactive pattern cannot be
  *   distinguished from markup alone with the same confidence.
+ * - `region` is deliberately NOT in the non-interactive role list: a
+ *   tabbable `role="region"` is a real, WCAG 2.1.1/2.1.3-grounded pattern
+ *   this engine's own `scrollable-region-focusable` check exists to
+ *   RECOMMEND (a scrollable landmark with no other focusable content
+ *   needs `tabindex="0"` to be keyboard-reachable at all) — flagging it
+ *   here would be internally inconsistent with that sibling check. A
+ *   `role="region"` is also commonly made tabbable on its own merits
+ *   (e.g. a cookie-consent banner or notification/toast region a keyboard
+ *   user should be able to reach directly, as in
+ *   `<div role="region" tabindex="0">`). Scoped to `region` only;
+ *   navigation/status/tabpanel remain flagged pending their own evidence.
  */
 
 const id = 'focus-order-semantics';
@@ -59,7 +72,6 @@ function runInPage(ctx) {
     'none',
     'img',
     'heading',
-    'region',
     'article',
     'banner',
     'contentinfo',

package/src/checks/manual/form-control-programmatic-label-quality-manual.js

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

package/src/checks/manual/heading-order-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check heading-order
  * @atomic true
  * @summary Heading levels must not skip a level going deeper
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies whenever the page contains two or more heading elements
  *   (native <h1>-<h6>, or explicit role="heading" with aria-level —
@@ -83,6 +85,31 @@ function runInPage(ctx) {
   for (const el of nodes) {
     if (!el || seen.has(el)) continue;
     seen.add(el);
+
+    // queryAllSmart's default hidden-content policy only excludes "hard"
+    // CSS-based hiding (display:none, visibility:hidden, etc.) -- it does
+    // NOT exclude aria-hidden, a softer/semantic removal from the
+    // accessibility tree that still leaves an element visually rendered.
+    // A heading order rule whose whole premise is "the document outline
+    // assistive technology users rely on" (see this rule's own header
+    // comment) must not let an aria-hidden heading participate in that
+    // outline at all: it's invisible to exactly the users this rule
+    // exists to protect. Without this check an aria-hidden heading is both
+    // flagged itself (though it isn't part of the AT-perceived outline)
+    // and can mask a real skip immediately after it, by advancing the
+    // "highest level reached so far" tracker on a level no AT user
+    // actually encountered.
+    if (helpers.isAccTreeEligible) {
+      const elig = (() => {
+        try {
+          return helpers.isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
+
     const level = getHeadingLevel(el);
     if (level > 0) headings.push({ el, level });
   }

package/src/checks/manual/identical-links-same-purpose-manual.js

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

package/src/checks/manual/image-redundant-alt-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check image-redundant-alt
  * @atomic true
  * @summary An image's alt text must not duplicate adjacent visible text
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies to <img> elements with non-empty alt text whose immediate
  *   parent element also has other visible text content (i.e. text nodes
@@ -57,12 +59,30 @@ function runInPage(ctx) {
   }
 
   function getOwnTextExcludingImg(parent, imgEl) {
+    const isAccTreeEligible =
+      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
     let text = '';
     for (const child of parent.childNodes || []) {
       if (child === imgEl) continue;
       if (child.nodeType === 3) {
         text += ' ' + (child.nodeValue || '');
       } else if (child.nodeType === 1 && child !== imgEl) {
+        // An aria-hidden sibling is never actually announced to assistive
+        // technology, so its text can't cause the "same words twice"
+        // double-announcement this rule exists to catch -- counting it
+        // anyway flags a redundancy that doesn't exist in what AT users
+        // actually hear.
+        if (isAccTreeEligible) {
+          const elig = (() => {
+            try {
+              return isAccTreeEligible(child, ctx);
+            } catch {
+              return { eligible: true, reasons: [] };
+            }
+          })();
+          if (elig && elig.eligible === false) continue;
+        }
         text += ' ' + (child.textContent || '');
       }
     }

package/src/checks/manual/img-alt-decorative-manual.js

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

package/src/checks/manual/img-alt-quality-manual.js

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

package/src/checks/manual/input-image-alt-decorative-manual.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -69,6 +71,9 @@ function runInPage(ctx) {
   const isAccTreeEligible =
     helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+
   const getFocusableInfo =
     helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
@@ -105,6 +110,26 @@ function runInPage(ctx) {
     return !focusable;
   }
 
+  // alt="" plus a name from aria-label/aria-labelledby/title is the judgement
+  // call this rule reviews. alt="" with no other source leaves the control
+  // unnamed, which input-image-alt-present fails outright.
+  function hasNameFromOtherSource(el) {
+    if (getAriaNameInfo) {
+      try {
+        const aria = getAriaNameInfo(el, ctx);
+        if (aria && aria.present && String(aria.value || '').trim()) return true;
+      } catch {
+        // fall through to title
+      }
+    }
+    try {
+      const title = el.getAttribute('title');
+      return title != null && String(title).trim() !== '';
+    } catch {
+      return false;
+    }
+  }
+
   const els = (() => {
     try {
       return Array.from(
@@ -141,6 +166,7 @@ function runInPage(ctx) {
 
     // Rule-specific applicability (only elements that already have a text alternative mechanism)
     if (!(el.getAttribute('alt') != null && String(el.getAttribute('alt')).trim() === '')) continue;
+    if (!hasNameFromOtherSource(el)) continue;
 
     applicableCount += 1;
 

package/src/checks/manual/input-image-alt-quality-manual.js

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

package/src/checks/manual/label-title-only-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check label-title-only
  * @atomic true
  * @summary Form controls should not rely on the title attribute as their only label
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies to labelable form controls (input, excluding
  *   hidden/submit/reset/button/image; select; textarea) that have a
@@ -46,7 +48,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const selector =
     'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
@@ -54,37 +56,42 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
 
-  const labelsByFor = new Map();
-  const allLabels = document.getElementsByTagName ? document.getElementsByTagName('label') : [];
-  for (const lab of allLabels) {
-    if (!lab || !lab.getAttribute) continue;
-    const forValue = String(lab.getAttribute('for') || '').trim();
-    if (!forValue) continue;
-    if (!labelsByFor.has(forValue)) labelsByFor.set(forValue, []);
-    labelsByFor.get(forValue).push(lab);
-  }
-
   const occurrences = [];
   let applicableCount = 0;
 
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
 
+    if (helpers.isAccTreeEligible) {
+      const elig = (() => {
+        try {
+          return helpers.isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
+
     const title = String(el.getAttribute('title') || '').trim();
     if (!title) continue;
 
     applicableCount += 1;
 
-    const ariaLabel = String(el.getAttribute('aria-label') || '').trim();
-    if (ariaLabel) continue;
-    const ariaLabelledby = String(el.getAttribute('aria-labelledby') || '').trim();
-    if (ariaLabelledby) continue;
-
-    const wrappingLabel = el.closest ? el.closest('label') : null;
-    if (wrappingLabel) continue;
-
-    const controlId = String(el.getAttribute('id') || '').trim();
-    if (controlId && labelsByFor.has(controlId)) continue;
+    // Delegates to the shared helpers.getAccessibleNameInfo (aria ->
+    // native <label> -> title, the same precedence every other
+    // name-dependent rule in this engine uses) rather than a local,
+    // hand-rolled "does a <label for>/wrapping <label> exist" check. A
+    // structural-association-only check (for="..."/wrapping) never verifies
+    // the label actually contributes a name -- an empty <label for="x">
+    // </label> or empty wrapping <label> would exempt the control even
+    // though title is functionally its only real label (see
+    // dom-helpers.js's hasLabelAssociation/labelContributesAccessibleName).
+    // If the resolved mechanism isn't 'title', some higher-priority
+    // mechanism (aria-label/aria-labelledby/a real contributing label)
+    // already won and this control isn't title-only.
+    const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
+    if (!nameInfo || nameInfo.mechanism !== 'title') continue;
 
     const tag = el.tagName.toLowerCase();
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';

package/src/checks/manual/landmark-banner-is-top-level-manual.js

@@ -1,23 +1,25 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-banner-is-top-level
  * @atomic true
  * @summary The banner landmark must not be nested inside another landmark
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies whenever the page contains at least one banner candidate:
- *   explicit role="banner", OR a <header> with NO role attribute at all
- *   (regardless of nesting — see implementation notes' 2026-08-01 fix).
+ *   explicit role="banner", OR a <header> with NO role attribute at all,
+ *   regardless of nesting (see implementation notes on why candidate
+ *   selection is deliberately unconditional).
  * @expectation
  *   No banner candidate has an ancestor that is itself any landmark
  *   region. A banner nested inside another landmark is not a top-level,
  *   whole-page banner and confuses landmark-based navigation for
  *   assistive technology users.
  * @implementation-notes
- * - Not WCAG-normative (a widely-used reference engine classifies this as "Best Practices," no SC
- *   tag) — authored as an advisory, cantTell-capped `type: 'manual'`
- *   rule per ROADMAP.md Tier 1b and the design doc's policy model
+ * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ *   `type: 'manual'` rule per ROADMAP.md Tier 1b and the design doc's policy model
  *   ("Advisory / best-practice rules may exist, but must not produce
  *   `fail`"). Matches the existing `page-title-patterns-manual.js`
  *   precedent: deterministic DOM analysis, no human required, but
@@ -25,30 +27,14 @@
  * - Landmark detection here models WAI-ARIA APG landmark roles and the
  *   HTML-AAM implicit-role mapping (header→banner, footer→contentinfo,
  *   main→main, nav→navigation, aside→complementary, section/form→
- *   region/form only when accessibly named), not a byte-for-byte port
- *   of a widely-used reference engine's internal algorithm — verify against upstream if exact
- *   parity is ever required.
- * - **Fixed 2026-08-01, a self-defeating applicability bug found via the
- *   cross-engine comparisons project (verified live on TurboTax's real
- *   homepage, `<header>` nested inside a `<div id="main" role="main">`
- *   two levels up):** candidate selection used to run the *same*
- *   HTML-AAM sectioning-ancestor suppression used for the violation
- *   check itself (`getImplicitLandmarkRole`'s `hasSectioningAncestor`
- *   gate) — so the moment a `<header>` was nested inside another
- *   landmark, that same nesting made it stop counting as a banner
- *   candidate in the first place, and the rule could never flag the one
- *   case it exists to catch. A widely-used reference engine's own
- *   `landmark-banner-is-top-level` avoids this: its selector
- *   (`header:not([role]), [role=banner]`) is unconditional — it doesn't
- *   care whether the header *currently* carries the banner role, only
- *   whether it's a `<header>`/`role="banner"` with a landmark ancestor
- *   above it (verified by reading that engine's real
- *   `landmark-is-top-level-evaluate` source, not guessed). Candidate
- *   selection (`isBannerCandidate` below) now matches that unconditional
- *   selector shape; the ancestor walk (`hasLandmarkAncestor`) still uses
- *   the full suppression-aware `getLandmarkRole` for each ancestor,
- *   which is correct and unchanged — an ancestor genuinely needs its own
- *   real role to count as blocking.
+ *   region/form only when accessibly named).
+ * - Candidate selection (`isBannerCandidate`) requires the element to really
+ *   carry the banner role, via the suppression-aware `getLandmarkRole`. The
+ *   two ancestor sets differ, so this does not make the rule vacuous: the
+ *   suppression set is the sectioning tags plus `<main>`, while the blocking
+ *   set is any landmark role, so a `<header>` inside `role="region"`,
+ *   `<form>` or `<footer>` is still caught, and an explicit `role="banner"`
+ *   is a candidate wherever it sits.
  */
 
 const id = 'landmark-banner-is-top-level';
@@ -85,9 +71,8 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.getLandmarkNameInfo (aria-label -> aria-labelledby, via the
   // target's own accessible name, not raw textContent -> title attribute fallback) rather than a
-  // local copy -- see that function's header comment in src/core/dom-helpers.js for the real bug
-  // (missing title fallback) this replaced across all 7 landmark rule files that had their own
-  // copy of this logic.
+  // local copy -- see that function's header comment in src/core/dom-helpers.js. Sharing it keeps
+  // the title-attribute fallback consistent across the landmark rules.
   function getAccessibleLandmarkName(el) {
     try {
       if (helpers && typeof helpers.getLandmarkNameInfo === 'function') {
@@ -110,10 +95,8 @@ function runInPage(ctx) {
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
-  // in src/core/aria-helpers.js for the full algorithm and the real page
-  // (handsontable.com's docs-assistant side panel, an
-  // <aside role="dialog"> containing its own <header>) that surfaced this
-  // rule's own former tag-only copy as a false negative.
+  // in src/core/aria-helpers.js for the full algorithm. Example: an
+  // <aside role="dialog"> containing its own <header>.
   function hasSectioningAncestor(el, includeMain) {
     return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
       ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
@@ -127,11 +110,9 @@ function runInPage(ctx) {
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
-      // A named <aside> is never suppressed, even when nested — matches
-      // landmark-unique's own verified-against-reference-engine precedent
-      // (that engine's real `aside` implicit-role function keeps
-      // "complementary" when the element has an accessible name, even
-      // inside sectioning content); propagated here for consistency.
+      // A named <aside> is never suppressed, even when nested — it keeps
+      // "complementary" when it has an accessible name, even inside
+      // sectioning content. Matches landmark-unique's precedent.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
       return getAccessibleLandmarkName(el) ? 'complementary' : '';
     }
@@ -158,16 +139,11 @@ function runInPage(ctx) {
     return getImplicitLandmarkRole(el);
   }
 
-  // Candidate selection is deliberately NOT the same as getLandmarkRole()
-  // === 'banner' — see the 2026-08-01 fix note above. A <header> is a
-  // candidate purely by tag + absence of any role attribute, independent
-  // of whether sectioning-ancestor nesting would currently suppress its
-  // implicit role; an explicit role="banner" is always a candidate too.
+  // A candidate must actually have the banner role. Per HTML-AAM a <header>
+  // descended from article/aside/main/nav/section is not a banner at all, so
+  // flagging it as a nested banner reports a landmark that does not exist.
   function isBannerCandidate(el) {
-    if (!el || !el.getAttribute) return false;
-    const explicit = getExplicitRoleToken(el);
-    if (explicit) return explicit === 'banner';
-    return !!(el.tagName && el.tagName.toLowerCase() === 'header');
+    return getLandmarkRole(el) === 'banner';
   }
 
   function hasLandmarkAncestor(el) {
@@ -184,9 +160,8 @@ function runInPage(ctx) {
   }
 
   // queryAllSmart (shadow-DOM-aware) instead of plain document.querySelectorAll -- see
-  // landmark-unique-manual.js's header comment for the real page (Airtable, 2026-07-23)
-  // that surfaced this gap: a third-party shadow-DOM-hosted widget's own landmark is
-  // invisible to a light-DOM-only query.
+  // landmark-unique-manual.js's header comment. A third-party shadow-DOM-hosted
+  // widget's own landmark is invisible to a light-DOM-only query.
   let nodes;
   try {
     nodes =
@@ -202,7 +177,28 @@ function runInPage(ctx) {
   for (const el of nodes) {
     if (!el || seen.has(el)) continue;
     seen.add(el);
-    if (isBannerCandidate(el)) banners.push(el);
+    if (!isBannerCandidate(el)) continue;
+
+    // An aria-hidden banner candidate is removed from the accessibility
+    // tree entirely -- it isn't part of the landmark structure assistive
+    // technology users navigate at all, so it shouldn't be flagged as
+    // "nested inside another landmark" (there's no real landmark there to
+    // begin with, from AT's perspective). queryAllSmart's default hidden-
+    // content policy only excludes "hard" CSS-based hiding (display:none,
+    // etc.), not the softer aria-hidden exclusion, so this needs its own
+    // check.
+    if (helpers && typeof helpers.isAccTreeEligible === 'function') {
+      const elig = (() => {
+        try {
+          return helpers.isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
+
+    banners.push(el);
   }
 
   if (banners.length === 0) {