@surea11y/core 1.3.0 → 1.4.0

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,20 @@
  * - 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` below) is deliberately
+ *   unconditional — a `<header>`/`role="banner"` counts as a candidate
+ *   regardless of nesting — rather than reusing the same HTML-AAM
+ *   sectioning-ancestor suppression (`getImplicitLandmarkRole`'s
+ *   `hasSectioningAncestor` gate) that the violation check itself relies
+ *   on. Gating candidate selection on that suppression would be
+ *   self-defeating: the moment a `<header>` is nested inside another
+ *   landmark, that same nesting would make it stop counting as a banner
+ *   candidate in the first place, so the rule could never flag the one
+ *   case it exists to catch. The ancestor walk (`hasLandmarkAncestor`) is intentionally
+ *   asymmetric: it still uses the full suppression-aware
+ *   `getLandmarkRole` for each ancestor, since an ancestor genuinely
+ *   needs its own real role to count as blocking.
  */
 
 const id = 'landmark-banner-is-top-level';
@@ -85,9 +77,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 +101,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 +116,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' : '';
     }
@@ -159,7 +146,7 @@ function runInPage(ctx) {
   }
 
   // Candidate selection is deliberately NOT the same as getLandmarkRole()
-  // === 'banner' — see the 2026-08-01 fix note above. A <header> is a
+  // === 'banner' — see the 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.
@@ -184,9 +171,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 +188,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) {

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

@@ -1,15 +1,17 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-contentinfo-is-top-level
  * @atomic true
  * @summary The contentinfo 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 contentinfo
  *   candidate: explicit role="contentinfo", OR a <footer> with NO role
- *   attribute at all (regardless of nesting — see implementation notes'
- *   2026-08-01 fix).
+ *   attribute at all, regardless of nesting (see implementation notes on
+ *   why candidate selection is deliberately unconditional).
  * @expectation
  *   No contentinfo candidate has an ancestor that is itself any landmark
  *   region. A contentinfo nested inside another landmark is not a
@@ -20,13 +22,12 @@
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent (this rule mirrors
  *   its structure with contentinfo/footer in place of banner/header).
- * - **Fixed 2026-08-01, same self-defeating applicability bug as
+ * - Candidate selection (`isContentinfoCandidate` below) is deliberately
+ *   unconditional, instead of reusing the sectioning-ancestor suppression
+ *   that the violation check itself depends on — same
+ *   self-defeating-candidate-selection reasoning as
  *   landmark-banner-is-top-level (see that file's header comment for the
- *   full root cause and the TurboTax evidence) — candidate selection
- *   (`isContentinfoCandidate` below) now matches a widely-used reference
- *   engine's unconditional `footer:not([role]), [role=contentinfo]`
- *   selector shape instead of reusing the sectioning-ancestor
- *   suppression that the violation check itself depends on.
+ *   full root cause).
  */
 
 const id = 'landmark-contentinfo-is-top-level';
@@ -61,9 +62,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') {
@@ -86,10 +86,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 })
@@ -103,11 +101,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' : '';
     }
@@ -135,7 +131,7 @@ function runInPage(ctx) {
   }
 
   // Candidate selection is deliberately NOT the same as getLandmarkRole()
-  // === 'contentinfo' — see the 2026-08-01 fix note above. A <footer> is
+  // === 'contentinfo' — see the header comment above. A <footer> 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="contentinfo" is always a candidate too.
@@ -160,9 +156,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 =
@@ -178,7 +173,28 @@ function runInPage(ctx) {
   for (const el of nodes) {
     if (!el || seen.has(el)) continue;
     seen.add(el);
-    if (isContentinfoCandidate(el)) contentinfos.push(el);
+    if (!isContentinfoCandidate(el)) continue;
+
+    // An aria-hidden contentinfo 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;
+    }
+
+    contentinfos.push(el);
   }
 
   if (contentinfos.length === 0) {

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

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-main-is-top-level
  * @atomic true
  * @summary The main 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 main landmark
  *   (explicit role="main", or an implicit <main> element).
@@ -18,13 +20,13 @@
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent (this rule mirrors
  *   its structure with main in place of banner/header).
- * - Did NOT need the 2026-08-01 fix applied to
- *   landmark-banner-is-top-level/landmark-contentinfo-is-top-level (see
- *   that file's header comment): `<main>`'s implicit role is
- *   unconditional per HTML-AAM — unlike `<header>`/`<footer>`, nesting
- *   never suppresses it — so `getImplicitLandmarkRole`'s `main` branch
- *   was never subject to the same self-defeating candidate-selection
- *   bug. Confirmed by inspection, not just by absence of a bug report.
+ * - Unlike landmark-banner-is-top-level/landmark-contentinfo-is-top-level
+ *   (see that file's header comment), candidate selection here doesn't
+ *   need to be unconditional: `<main>`'s implicit role is unconditional
+ *   per HTML-AAM — unlike `<header>`/`<footer>`, nesting never suppresses
+ *   it — so `getImplicitLandmarkRole`'s `main` branch is never subject to
+ *   the self-defeating candidate-selection problem those two rules guard
+ *   against.
  */
 
 const id = 'landmark-main-is-top-level';
@@ -59,9 +61,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') {
@@ -84,10 +85,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 })
@@ -101,11 +100,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' : '';
     }
@@ -146,9 +143,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 =
@@ -164,7 +160,28 @@ function runInPage(ctx) {
   for (const el of nodes) {
     if (!el || seen.has(el)) continue;
     seen.add(el);
-    if (getLandmarkRole(el) === 'main') mains.push(el);
+    if (getLandmarkRole(el) !== 'main') continue;
+
+    // An aria-hidden main 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;
+    }
+
+    mains.push(el);
   }
 
   if (mains.length === 0) {

package/src/checks/manual/landmark-no-duplicate-banner-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-no-duplicate-banner
  * @atomic true
  * @summary A page must not have more than one banner 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 landmark
  *   (explicit role="banner", or an implicit, non-nested <header> — see
@@ -21,14 +23,11 @@
  *   header comment for the shared rationale/precedent.
  * - Flags every banner instance (not just the "extra" ones) when more
  *   than one exists, since which instance is "correct" is ambiguous.
- * - Only landmarks actually exposed to assistive technology can collide —
- *   matches a widely-used reference engine's own `page-no-duplicate` check (confirmed by reading
- *   its source directly: `query_selector_all_filter_default(..., elm =>
- *   _isVisibleToScreenReaders(elm))`). Without this, a responsive layout
- *   rendering both a visible and a CSS-hidden duplicate `<header>` (found
- *   on a real site — Trello's homepage, a desktop/mobile header pair) was
- *   wrongly flagged as a duplicate landmark; the hidden copy is never
- *   actually reachable by AT.
+ * - Only landmarks actually exposed to assistive technology can collide.
+ *   Without this, a responsive layout rendering both a visible and a
+ *   CSS-hidden duplicate `<header>` (a desktop/mobile header pair) is
+ *   flagged as a duplicate landmark even though the hidden copy is never
+ *   reachable by AT.
  */
 
 const id = 'landmark-no-duplicate-banner';
@@ -63,9 +62,7 @@ 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.
   function getAccessibleLandmarkName(el) {
     try {
       if (helpers && typeof helpers.getLandmarkNameInfo === 'function') {
@@ -88,10 +85,9 @@ 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 — e.g. an
+  // <aside role="dialog"> containing its own <header>, where the <header>
+  // keeps its banner role.
   function hasSectioningAncestor(el, includeMain) {
     return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
       ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
@@ -105,11 +101,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
+      // A named <aside> is never suppressed, even when nested: keeps
       // "complementary" when the element has an accessible name, even
-      // inside sectioning content); propagated here for consistency.
+      // inside sectioning content. See landmark-unique-manual.js.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
       return getAccessibleLandmarkName(el) ? 'complementary' : '';
     }
@@ -137,9 +131,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 =