@surea11y/core 1.2.0 → 1.4.0

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -11,20 +13,27 @@
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */
 
-const id = "input-image-alt-quality";
+const id = 'input-image-alt-quality';
 
 const meta = {
-  title: "<input type=\"image\"> alt text must be appropriate (manual review)",
-  description: "Flags <input type=\"image\"> elements with non-empty alt text for human review of appropriateness.",
+  title: '<input type="image"> alt text must be appropriate (manual review)',
+  description:
+    'Flags <input type="image"> elements with non-empty alt text for human review of appropriateness.',
   i18n: {
-    titleKey: "inputImage_altQuality_title",
-    descriptionKey: "inputImage_altQuality_description"
+    titleKey: 'inputImage_altQuality_title',
+    descriptionKey: 'inputImage_altQuality_description'
   },
   helpUrl: null,
-  tags: ["wcag2a", "wcag111", "forms", "images", "manual", "atomic"],
+  tags: ['wcag2a', 'wcag111', 'forms', 'images', 'manual', 'atomic'],
   wcagSc: ['1.1.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'minor',
   category: 'perceivable',
@@ -38,107 +47,133 @@ const meta = {
 };
 
 function runInPage(ctx) {
-
-    const { document, root, helpers, rule } = ctx;
-    const safeRoot = root || document;
-
-    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-    const queryAll = helpers && typeof helpers.queryAll === 'function'
-        ? helpers.queryAll
-        : (sel) => {
-            try { return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : []; }
-            catch { return []; }
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll =
+    helpers && typeof helpers.queryAll === 'function'
+      ? helpers.queryAll
+      : (sel) => {
+          try {
+            return safeRoot && safeRoot.querySelectorAll
+              ? Array.from(safeRoot.querySelectorAll(sel))
+              : [];
+          } catch {
+            return [];
+          }
         };
 
-    const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
-        ? helpers.getEligibilityInfo
-        : null;
-
-    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
-        ? helpers.isAccTreeEligible
-        : null;
-
-    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
-        ? helpers.getFocusableInfo
-        : null;
-
-    function isRolePresentationExcluded(el) {
-        const role = (() => {
-            try { return String(el.getAttribute('role') || '').trim().toLowerCase(); }
-            catch { return ''; }
-        })();
-        if (role !== 'presentation' && role !== 'none') return false;
-
-        // Exclude only when NOT focusable (mirrors img-alt-present policy)
-        let focusable = false;
-        if (getFocusableInfo) {
-            const fi = (() => { try { return getFocusableInfo(el, ctx); } catch { return null; } })();
-            focusable = !!(fi && fi.focusable);
-        } else {
-            const tabindex = el.getAttribute('tabindex');
-            focusable = tabindex != null && String(tabindex).trim() !== '' && !Number.isNaN(Number(String(tabindex).trim()));
-        }
-        return !focusable;
-    }
-
-
-    const els = (() => {
-        try { return Array.from((queryAllSmart ? queryAllSmart('input[type="image"]') : queryAll('input[type="image"]')) || []); }
-        catch { return queryAll('input[type="image"]'); }
-    })();
-
-    if (!els.length) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
-    }
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-    const occurrences = [];
-    let applicableCount = 0;
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
-    for (const el of els) {
-        if (!el || !el.getAttribute) continue;
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
-        if (isAccTreeEligible) {
-            const elig = (() => {
-                try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
-            })();
-            if (elig && elig.eligible === false) continue;
+  function isRolePresentationExcluded(el) {
+    const role = (() => {
+      try {
+        return String(el.getAttribute('role') || '')
+          .trim()
+          .toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
+    if (role !== 'presentation' && role !== 'none') return false;
+
+    // Exclude only when NOT focusable (mirrors img-alt-present policy)
+    let focusable;
+    if (getFocusableInfo) {
+      const fi = (() => {
+        try {
+          return getFocusableInfo(el, ctx);
+        } catch {
+          return null;
         }
+      })();
+      focusable = !!(fi && fi.focusable);
+    } else {
+      const tabindex = el.getAttribute('tabindex');
+      focusable =
+        tabindex != null &&
+        String(tabindex).trim() !== '' &&
+        !Number.isNaN(Number(String(tabindex).trim()));
+    }
+    return !focusable;
+  }
 
-        if (isRolePresentationExcluded(el)) continue;
-
-        // Rule-specific applicability (only elements that already have a text alternative mechanism)
-        if (!((el.getAttribute('alt') != null && String(el.getAttribute('alt')).trim() !== ''))) continue;
+  const els = (() => {
+    try {
+      return Array.from(
+        (queryAllSmart ? queryAllSmart('input[type="image"]') : queryAll('input[type="image"]')) ||
+          []
+      );
+    } catch {
+      return queryAll('input[type="image"]');
+    }
+  })();
 
-        applicableCount += 1;
+  if (!els.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+  const occurrences = [];
+  let applicableCount = 0;
 
-        const baseOccurrence = {
-            summary: 'Review alt text on <input type="image"> for accuracy and appropriateness.',
-            hint: 'Ensure the alt text describes the control’s action (e.g., “Search”, “Submit order”) in context.',
-            i18n: {
-                summaryKey: 'inputImage_altQuality_summary_cantTell',
-                hintKey: 'inputImage_altQuality_hint_cantTell',
-                params: { element: 'input[type=image]' }
-            },
-            data: {
-                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-                details: { alt: String(el.getAttribute('alt') || '') } // optional but useful
-            }
-        };
+  for (const el of els) {
+    if (!el || !el.getAttribute) continue;
 
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            occurrences.push({ selector: '', html: '', ...baseOccurrence });
+    if (isAccTreeEligible) {
+      const elig = (() => {
+        try {
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
         }
+      })();
+      if (elig && elig.eligible === false) continue;
     }
 
-    if (applicableCount === 0) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    if (isRolePresentationExcluded(el)) continue;
+
+    // Rule-specific applicability (only elements that already have a text alternative mechanism)
+    if (!(el.getAttribute('alt') != null && String(el.getAttribute('alt')).trim() !== '')) continue;
+
+    applicableCount += 1;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      summary: 'Review alt text on <input type="image"> for accuracy and appropriateness.',
+      hint: 'Ensure the alt text describes the control’s action (e.g., “Search”, “Submit order”) in context.',
+      i18n: {
+        summaryKey: 'inputImage_altQuality_summary_cantTell',
+        hintKey: 'inputImage_altQuality_hint_cantTell',
+        params: { element: 'input[type=image]' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        details: { alt: String(el.getAttribute('alt') || '') } // optional but useful
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push({ selector: '', html: '', ...baseOccurrence });
     }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences };
+  return { ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences };
 }
 
 module.exports = { id, meta, runInPage };

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
@@ -28,7 +30,8 @@ const id = 'label-title-only';
 
 const meta = {
   title: 'Form controls should not use title as their only label',
-  description: 'Checks that a form control with a title attribute also has a real label (label element, aria-label, or aria-labelledby).',
+  description:
+    'Checks that a form control with a title attribute also has a real label (label element, aria-label, or aria-labelledby).',
   i18n: {
     titleKey: 'labelTitleOnly_title',
     descriptionKey: 'labelTitleOnly_description'
@@ -45,20 +48,13 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
-
-  const selector = 'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
-  const nodes = helpers.queryAllSmart ? 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 { helpers, rule } = ctx;
+
+  const selector =
+    'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   const occurrences = [];
   let applicableCount = 0;
@@ -66,25 +62,40 @@ function runInPage(ctx) {
   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';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     occurrences.push({
       selector: stableSelector,
@@ -106,7 +117,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }

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

@@ -1,24 +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 landmark
- *   (explicit role="banner", or an implicit <header> that is not itself
- *   nested inside <article>/<aside>/<main>/<nav>/<section> — see
- *   implementation notes).
+ *   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 on why candidate
+ *   selection is deliberately unconditional).
  * @expectation
- *   No banner landmark has an ancestor that is itself any landmark
+ *   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
@@ -26,16 +27,28 @@
  * - 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.
+ *   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';
 
 const meta = {
   title: 'Banner landmark must be top-level',
-  description: 'Checks that the banner landmark (role="banner" or a non-nested <header>) is not nested inside another landmark region.',
+  description:
+    'Checks that the banner landmark (role="banner" or a non-nested <header>) is not nested inside another landmark region.',
   i18n: {
     titleKey: 'landmarkBannerIsTopLevel_title',
     descriptionKey: 'landmarkBannerIsTopLevel_description'
@@ -57,14 +70,15 @@ function runInPage(ctx) {
   // Declared inside runInPage — see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
   }
 
   // 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') {
@@ -87,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 })
@@ -104,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' : '';
     }
@@ -117,7 +127,16 @@ function runInPage(ctx) {
     return '';
   }
 
-  const LANDMARK_ROLES = new Set(['banner', 'contentinfo', 'main', 'navigation', 'complementary', 'region', 'form', 'search']);
+  const LANDMARK_ROLES = new Set([
+    'banner',
+    'contentinfo',
+    'main',
+    'navigation',
+    'complementary',
+    'region',
+    'form',
+    'search'
+  ]);
 
   function getLandmarkRole(el) {
     if (!el || !el.getAttribute) return '';
@@ -126,8 +145,20 @@ function runInPage(ctx) {
     return getImplicitLandmarkRole(el);
   }
 
+  // Candidate selection is deliberately NOT the same as getLandmarkRole()
+  // === '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.
+  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');
+  }
+
   function hasLandmarkAncestor(el) {
-    const scopeRoots = Array.isArray(root) ? root : (root ? [root] : []);
+    const scopeRoots = Array.isArray(root) ? root : root ? [root] : [];
     let p = el.parentElement;
     while (p) {
       if (getLandmarkRole(p)) return true;
@@ -140,14 +171,14 @@ 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.
-  let nodes = [];
+  // 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 = helpers && typeof helpers.queryAllSmart === 'function'
-      ? helpers.queryAllSmart('header, footer, main, nav, aside, section, form, [role]')
-      : document.querySelectorAll('header, footer, main, nav, aside, section, form, [role]');
+    nodes =
+      helpers && typeof helpers.queryAllSmart === 'function'
+        ? helpers.queryAllSmart('header, footer, main, nav, aside, section, form, [role]')
+        : document.querySelectorAll('header, footer, main, nav, aside, section, form, [role]');
   } catch {
     nodes = [];
   }
@@ -157,7 +188,28 @@ function runInPage(ctx) {
   for (const el of nodes) {
     if (!el || seen.has(el)) continue;
     seen.add(el);
-    if (getLandmarkRole(el) === 'banner') 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) {
@@ -169,7 +221,7 @@ function runInPage(ctx) {
     if (!hasLandmarkAncestor(el)) continue;
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     occurrences.push({
       selector: stableSelector,
@@ -188,7 +240,12 @@ function runInPage(ctx) {
   }
 
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }