@surea11y/core 1.4.0 → 1.5.0

package/src/checks/{automatic/bypass-blocks-present.js → manual/bypass-blocks-present-manual.js}

@@ -21,30 +21,56 @@
  *       before it (nav, header, repeated blocks) in one step;
  *   (b) a working same-page anchor link — technique G1/G123: an
  *       <a href="#id"> (or legacy <a name="id">) whose target resolves to
- *       a real element anywhere in the document. Deliberately NOT
- *       required to be positioned before a <nav> or be keyboard-focus-
- *       order-first — see implementation notes;
+ *       a real element in the link's own tree (light DOM or the same shadow
+ *       root). Deliberately NOT required to be positioned before a <nav> or
+ *       be keyboard-focus-order-first — see implementation notes;
  *   (c) at least one heading (<h1>-<h6> or [role="heading"]) — technique
  *       H69: heading navigation is itself a standards-recognized bypass
  *       mechanism (e.g. a screen reader's "jump by heading" command).
  * @implementation-notes
+ * - Outcome model: this rule is `type: 'manual'` (cantTell-capped, never
+ *   `fail`). When a recognized mechanism is found the page has nothing to
+ *   review here → `notApplicable` (matching page-has-heading-one-manual /
+ *   skip-link-manual's "nothing to flag" convention). When none is found we
+ *   return `cantTell` — "we could not detect a bypass mechanism, please
+ *   verify" — rather than a hard `fail`. The absence of a *detectable*
+ *   mechanism is NOT high-confidence evidence that 2.4.1 is violated, for
+ *   several reasons the engine cannot resolve from a single static snapshot:
+ *     • Applicability itself is undecidable in-page. 2.4.1 governs blocks of
+ *       content "repeated on multiple Web pages"; whether any block is
+ *       actually repeated across the site is not knowable from one document,
+ *       so a page that legitimately needs no bypass mechanism would be
+ *       indistinguishable from one that omits a required one.
+ *     • Transient accessibility-tree state. When a modal dialog is open the
+ *       rest of the page is routinely made `inert` or `aria-hidden="true"`,
+ *       so the page's real <main>/headings are (correctly) filtered out by
+ *       isAccTreeEligible for the duration of that state and only the dialog
+ *       is exposed — a snapshot taken then would see "no mechanism" though
+ *       the page has one once the dialog closes. The same applies to content
+ *       that is display:none until revealed by script (tabs, accordions, an
+ *       unmounted SPA view).
+ *   Both cases would produce false positives under a hard `fail`, which this
+ *   engine reserves for high-confidence violations; `cantTell` routes them to
+ *   human review instead. No ACT rule hard-fails 2.4.1 by presence alone,
+ *   for the same reason.
  * - This rule intentionally checks presence, not position, for the
  *   same-page-anchor condition (b): a full bypass algorithm is heuristic
  *   (see ROADMAP.md's Tier 1a note on why this rule was
  *   deferred from the rest of that batch), and getting DOM-order /
  *   keyboard-focus-order positioning exactly right without introducing
  *   false positives is materially harder than the rest of Tier 1a. Being
- *   lenient about condition (b) can only produce a false NEGATIVE (missing
- *   a page whose only anchor link isn't a real skip mechanism, e.g. a
- *   "back to top" link) — never a false positive — which matches this
- *   engine's non-negotiable "fail is reserved for high-confidence
- *   violations" policy. A future revision can tighten (b) once a
- *   positional heuristic has been validated against real pages without
- *   regressions.
- * - `fail` therefore means: no main landmark, no resolvable same-page
- *   anchor link anywhere, and no heading anywhere on the page. That is a
- *   strong, low-ambiguity signal that the page truly has zero recognized
- *   bypass mechanism.
+ *   lenient about condition (b) can only make us *miss* a review prompt
+ *   (a page whose only anchor link isn't a real skip mechanism, e.g. a
+ *   "back to top" link) — never raise a spurious one.
+ * - Shadow DOM: all three conditions use `helpers.queryAllSmart`, which is
+ *   shadow-DOM-aware (when the run enables includeShadowDom) and applies the
+ *   engine's hidden-content policy. The same-page-anchor target is resolved
+ *   in the link's own root (`getRootNode()` — the document, or the shadow
+ *   root the link lives in) before falling back to the document, so a skip
+ *   link encapsulated in a web component is credited the same as one in the
+ *   light DOM. (Previously the anchor path used raw
+ *   `document.querySelectorAll`/`getElementById`, which never pierced shadow
+ *   roots — a genuine gap now closed.)
  */
 
 const id = 'bypass-blocks-present';
@@ -58,7 +84,7 @@ const meta = {
     descriptionKey: 'bypassBlocksPresent_description'
   },
   helpUrl: null,
-  tags: ['wcag2a', 'wcag241', 'navigation', 'atomic', 'automatic'],
+  tags: ['wcag2a', 'wcag241', 'navigation', 'atomic', 'manual'],
   wcagSc: ['2.4.1'],
   normativeMappings: [
     {
@@ -69,9 +95,9 @@ const meta = {
       conformanceLevel: 'A'
     }
   ],
-  defaultSeverity: 'serious',
+  defaultSeverity: 'moderate',
   category: 'operable',
-  type: 'automatic',
+  type: 'manual',
   defaultConfidence: 'medium',
   coverage: { facetsBySc: { '2.4.1': ['bypass-blocks-present'] } }
 };
@@ -122,7 +148,8 @@ function runInPage(ctx) {
   // (e.g. a page whose only <h1> sits inside a display:none ancestor,
   // unreachable by sighted and screen reader users alike). A fully
   // non-rendered <main>/heading must not be credited here, since that would
-  // wrongly return `pass` for a page with zero actual bypass mechanisms.
+  // wrongly treat a page with zero currently-exposed bypass mechanisms as
+  // having one.
   function hasMainLandmark() {
     for (const el of queryAll('main, [role="main"]')) {
       if (el && isExposedToAt(el)) return true;
@@ -130,10 +157,41 @@ function runInPage(ctx) {
     return false;
   }
 
+  // Resolve a fragment id (or legacy <a name>) inside a specific root node
+  // (a Document or a ShadowRoot). Both expose getElementById; querySelector
+  // is used for the legacy anchor-name fallback.
+  function resolveInRoot(root, fragment) {
+    if (!root) return null;
+    let target;
+    try {
+      target = typeof root.getElementById === 'function' ? root.getElementById(fragment) : null;
+    } catch {
+      target = null;
+    }
+    if (target) return target;
+    try {
+      target =
+        typeof root.querySelector === 'function'
+          ? root.querySelector('a[name="' + fragment.replace(/"/g, '\\"') + '"]')
+          : null;
+    } catch {
+      target = null;
+    }
+    return target;
+  }
+
+  // Shadow-DOM-aware: gather anchors via queryAllSmart (pierces shadow roots
+  // when includeShadowDom is enabled, and drops hard-hidden links), and
+  // resolve each fragment in the link's own root before falling back to the
+  // document. This credits a skip link encapsulated in a web component the
+  // same way as one authored in the light DOM.
   function hasWorkingAnchorLink() {
     let links;
     try {
-      links = document.querySelectorAll('a[href]');
+      links =
+        helpers && typeof helpers.queryAllSmart === 'function'
+          ? helpers.queryAllSmart('a[href]')
+          : document.querySelectorAll('a[href]');
     } catch {
       links = [];
     }
@@ -150,18 +208,19 @@ function runInPage(ctx) {
       fragment = fragment.trim();
       if (!fragment) continue;
 
-      let target;
+      let root = document;
       try {
-        target = document.getElementById(fragment);
+        if (typeof a.getRootNode === 'function') {
+          const r = a.getRootNode();
+          if (r) root = r;
+        }
       } catch {
-        target = null;
+        root = document;
       }
-      if (!target) {
-        try {
-          target = document.querySelector('a[name="' + fragment.replace(/"/g, '\\"') + '"]');
-        } catch {
-          target = null;
-        }
+
+      let target = resolveInRoot(root, fragment);
+      if (!target && root !== document) {
+        target = resolveInRoot(document, fragment);
       }
       if (target) return true;
     }
@@ -179,37 +238,32 @@ function runInPage(ctx) {
   const anchorLink = mainLandmark ? false : hasWorkingAnchorLink();
   const heading = mainLandmark || anchorLink ? false : hasHeading();
 
+  // A recognized mechanism is present -> nothing to review on this page.
   if (mainLandmark || anchorLink || heading) {
-    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(body)
-    : (body.outerHTML || '').slice(0, 200);
-
   const occurrences = [
-    {
-      selector: stableSelector,
-      html,
-      summary: 'This page has no recognized way to bypass repeated blocks of content.',
-      hint: 'Add a main landmark (<main> or role="main"), a working "skip to content" link, or heading elements that assistive technology can use to jump past repeated content.',
+    helpers.reportOccurrence(body, {
+      summary:
+        'No recognized way to bypass repeated blocks of content was detected on this page — verify a bypass mechanism exists.',
+      hint: 'Confirm the page offers a bypass mechanism: a main landmark (<main> or role="main"), a working "skip to content" link, or heading elements that assistive technology can use to jump past repeated content. (A mechanism may be temporarily hidden — e.g. while a modal dialog makes the page inert — or provided on a per-site basis; this needs human confirmation.)',
       i18n: {
-        summaryKey: 'bypassBlocksPresent_summary_fail',
-        hintKey: 'bypassBlocksPresent_hint_fail',
+        summaryKey: 'bypassBlocksPresent_summary_cantTell',
+        hintKey: 'bypassBlocksPresent_hint_cantTell',
         params: {}
       },
       data: {
         details: { reasonCode: 'BYPASS_MECHANISM_ABSENT' },
         visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] }
       }
-    }
+    })
   ];
 
   return {
     ruleId: rule.ruleId,
-    outcome: 'fail',
-    severity: rule.defaultSeverity || 'serious',
+    outcome: 'cantTell',
+    severity: rule.defaultSeverity || 'moderate',
     occurrences
   };
 }

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

@@ -148,8 +148,6 @@ function runInPage(ctx) {
     const name = getAccessibleNameText(el);
     if (name) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const eligInfo = helpers.getEligibilityInfo
       ? (() => {
           try {
@@ -160,21 +158,21 @@ function runInPage(ctx) {
         })()
       : null;
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This heading has no accessible name.',
-      hint: 'Add text content (or aria-label/aria-labelledby) to this heading, or remove it if it is not needed.',
-      i18n: {
-        summaryKey: 'emptyHeading_summary_cantTell',
-        hintKey: 'emptyHeading_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'HEADING_EMPTY' },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This heading has no accessible name.',
+        hint: 'Add text content (or aria-label/aria-labelledby) to this heading, or remove it if it is not needed.',
+        i18n: {
+          summaryKey: 'emptyHeading_summary_cantTell',
+          hintKey: 'emptyHeading_hint_cantTell',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'HEADING_EMPTY' },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -141,43 +141,40 @@ function runInPage(ctx) {
 
     if (getVisibleText(el)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     const ariaName = getAriaOnlyName(el);
     if (ariaName) {
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary:
-          'This table header cell has no visible text — its only accessible name comes from aria-label/aria-labelledby, which real screen-reader/browser combinations (e.g. NVDA+Firefox, iOS VoiceOver+Safari) are known to ignore on <th> elements.',
-        hint: 'Add visible text content to this header cell (in addition to, or instead of, aria-label/aria-labelledby) — visible text is the only naming mechanism confirmed to work across tested screen readers.',
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This table header cell has no visible text — its only accessible name comes from aria-label/aria-labelledby, which real screen-reader/browser combinations (e.g. NVDA+Firefox, iOS VoiceOver+Safari) are known to ignore on <th> elements.',
+          hint: 'Add visible text content to this header cell (in addition to, or instead of, aria-label/aria-labelledby) — visible text is the only naming mechanism confirmed to work across tested screen readers.',
+          i18n: {
+            summaryKey: 'emptyTableHeader_summary_cantTell_ariaOnly',
+            hintKey: 'emptyTableHeader_hint_cantTell_ariaOnly',
+            params: {}
+          },
+          data: {
+            details: { reasonCode: 'TABLE_HEADER_NAME_NOT_VISIBLE_TEXT', ariaName }
+          }
+        })
+      );
+      continue;
+    }
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This table header cell has no accessible name.',
+        hint: 'Add text content (or aria-label/aria-labelledby) to this header cell, or remove it if it is not needed.',
         i18n: {
-          summaryKey: 'emptyTableHeader_summary_cantTell_ariaOnly',
-          hintKey: 'emptyTableHeader_hint_cantTell_ariaOnly',
+          summaryKey: 'emptyTableHeader_summary_cantTell',
+          hintKey: 'emptyTableHeader_hint_cantTell',
           params: {}
         },
         data: {
-          details: { reasonCode: 'TABLE_HEADER_NAME_NOT_VISIBLE_TEXT', ariaName }
+          details: { reasonCode: 'TABLE_HEADER_EMPTY' }
         }
-      });
-      continue;
-    }
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This table header cell has no accessible name.',
-      hint: 'Add text content (or aria-label/aria-labelledby) to this header cell, or remove it if it is not needed.',
-      i18n: {
-        summaryKey: 'emptyTableHeader_summary_cantTell',
-        hintKey: 'emptyTableHeader_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'TABLE_HEADER_EMPTY' }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -185,20 +185,13 @@ function runInPage(ctx) {
 
     const reasonCode =
       method === 'title' ? 'label_from_title_primary' : 'label_from_placeholder_primary';
-    const methodLabel =
-      method === 'title'
-        ? 'title'
-        : method === 'placeholder'
-          ? 'placeholder'
-          : 'title or placeholder';
-
     const baseOccurrence = {
-      summary: 'Form control’s primary label is derived from title or placeholder.',
+      summary: `Form control’s primary label is derived from ${method}.`,
       hint: 'Prefer a persistent <label> or aria-labelledby. Avoid relying on placeholder/title as the primary label.',
       i18n: {
         summaryKey: 'formControl_programmaticLabelQuality_summary_cantTell',
         hintKey: 'formControl_programmaticLabelQuality_hint_cantTell',
-        params: { element: (el.tagName || '').toLowerCase(), method, methodLabel }
+        params: { element: (el.tagName || '').toLowerCase(), method }
       },
       data: {
         visibilityFilter: vf || { targetSet: 'acc', accEligible: null, reasons: [] },

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

@@ -125,29 +125,24 @@ function runInPage(ctx) {
     const { el, level } = headings[i];
 
     if (level > highestSoFar + 1) {
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
-
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This heading jumps from level ${highestSoFar} to level ${level}, skipping a level.`,
-        hint: 'Use consecutive heading levels (do not skip a level when going deeper) so the document outline stays predictable.',
-        i18n: {
-          summaryKey: 'headingOrder_summary_cantTell',
-          hintKey: 'headingOrder_hint_cantTell',
-          params: { fromLevel: String(highestSoFar), toLevel: String(level) }
-        },
-        data: {
-          details: {
-            reasonCode: 'HEADING_ORDER_SKIPPED_LEVEL',
-            fromLevel: highestSoFar,
-            toLevel: level
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This heading jumps from level ${highestSoFar} to level ${level}, skipping a level.`,
+          hint: 'Use consecutive heading levels (do not skip a level when going deeper) so the document outline stays predictable.',
+          i18n: {
+            summaryKey: 'headingOrder_summary_cantTell',
+            hintKey: 'headingOrder_hint_cantTell',
+            params: { fromLevel: String(highestSoFar), toLevel: String(level) }
+          },
+          data: {
+            details: {
+              reasonCode: 'HEADING_ORDER_SKIPPED_LEVEL',
+              fromLevel: highestSoFar,
+              toLevel: level
+            }
           }
-        }
-      });
+        })
+      );
     }
 
     if (level > highestSoFar) highestSoFar = level;

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

@@ -111,23 +111,20 @@ function runInPage(ctx) {
 
     if (otherText.toLowerCase() !== alt.toLowerCase()) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: "This image's alt text duplicates other visible text right next to it.",
-      hint: 'Make the alt text empty (alt="") if the image is purely decorative alongside the text, or remove the redundant duplication.',
-      i18n: {
-        summaryKey: 'imageRedundantAlt_summary_cantTell',
-        hintKey: 'imageRedundantAlt_hint_cantTell',
-        params: { alt }
-      },
-      data: {
-        details: { reasonCode: 'IMAGE_ALT_REDUNDANT', alt }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: "This image's alt text duplicates other visible text right next to it.",
+        hint: 'Make the alt text empty (alt="") if the image is purely decorative alongside the text, or remove the redundant duplication.',
+        i18n: {
+          summaryKey: 'imageRedundantAlt_summary_cantTell',
+          hintKey: 'imageRedundantAlt_hint_cantTell',
+          params: { alt }
+        },
+        data: {
+          details: { reasonCode: 'IMAGE_ALT_REDUNDANT', alt }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -71,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;
 
@@ -107,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(
@@ -143,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/label-title-only-manual.js

@@ -94,23 +94,21 @@ function runInPage(ctx) {
     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 || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This form control relies on the title attribute as its only label.',
-      hint: 'Add a visible <label> (or aria-label/aria-labelledby) in addition to, or instead of, the title attribute.',
-      i18n: {
-        summaryKey: 'labelTitleOnly_summary_cantTell',
-        hintKey: 'labelTitleOnly_hint_cantTell',
-        params: { element: tag }
-      },
-      data: {
-        details: { reasonCode: 'LABEL_TITLE_ONLY', element: tag }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This form control relies on the title attribute as its only label.',
+        hint: 'Add a visible <label> (or aria-label/aria-labelledby) in addition to, or instead of, the title attribute.',
+        i18n: {
+          summaryKey: 'labelTitleOnly_summary_cantTell',
+          hintKey: 'labelTitleOnly_hint_cantTell',
+          params: { element: tag }
+        },
+        data: {
+          details: { reasonCode: 'LABEL_TITLE_ONLY', element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -28,19 +28,13 @@
  *   HTML-AAM implicit-role mapping (header→banner, footer→contentinfo,
  *   main→main, nav→navigation, aside→complementary, section/form→
  *   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.
+ * - 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';
@@ -145,16 +139,11 @@ 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.
+  // 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) {
@@ -220,23 +209,20 @@ function runInPage(ctx) {
   for (const el of banners) {
     if (!hasLandmarkAncestor(el)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This banner landmark is nested inside another landmark region.',
-      hint: 'Move the banner landmark (header/role="banner") so it is not contained by another landmark; a banner should be a top-level region of the page.',
-      i18n: {
-        summaryKey: 'landmarkBannerIsTopLevel_summary_cantTell',
-        hintKey: 'landmarkBannerIsTopLevel_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'LANDMARK_BANNER_NOT_TOP_LEVEL' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This banner landmark is nested inside another landmark region.',
+        hint: 'Move the banner landmark (header/role="banner") so it is not contained by another landmark; a banner should be a top-level region of the page.',
+        i18n: {
+          summaryKey: 'landmarkBannerIsTopLevel_summary_cantTell',
+          hintKey: 'landmarkBannerIsTopLevel_hint_cantTell',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'LANDMARK_BANNER_NOT_TOP_LEVEL' }
+        }
+      })
+    );
   }
 
   if (occurrences.length) {