@surea11y/core 1.4.1 → 1.6.0

package/src/checks/automatic/aria-deprecated-role.js

@@ -11,7 +11,7 @@
  * @applicability
  *   Applies to any element whose role attribute's first (used) token is a
  *   valid, non-abstract ARIA role that authors should not explicitly
- *   declare — either because WAI-ARIA has deprecated it (e.g. "directory",
+ *   declare, either because WAI-ARIA has deprecated it (e.g. "directory",
  *   superseded by role="list") or because it is reserved for user-agent-
  *   internal use (role="generic", which ARIA 1.2 §5.4 says authors SHOULD
  *   NOT use in content).
@@ -81,8 +81,20 @@ function runInPage(ctx) {
       if (typeof helpers.isDomVisibleEligible === 'function') {
         if (!helpers.isDomVisibleEligible(el, ctx)) return true;
       }
-      for (let n = el; n && n.getAttribute; n = n.parentElement) {
+      // Walk the composed tree, not parentElement: that stops at a shadow
+      // root, so a host carrying aria-hidden or inert would never be seen
+      // from inside its own shadow content.
+      const up =
+        typeof helpers.composedParent === 'function'
+          ? helpers.composedParent
+          : (n) => n.parentElement;
+
+      // A shadow root has no getAttribute, so skip past it rather than
+      // stopping: the host one step further up is the node that matters.
+      for (let n = el; n; n = up(n)) {
+        if (!n.getAttribute) continue;
         if (String(n.getAttribute('aria-hidden') || '').toLowerCase() === 'true') return true;
+        if (n.hasAttribute && n.hasAttribute('inert')) return true;
       }
     } catch {
       return false;
@@ -113,63 +125,64 @@ function runInPage(ctx) {
       ariaHelpers.isAuthorProhibitedRole(role);
     if (!deprecated && !discouraged && !prohibited) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const guidance = ariaHelpers.getDeprecatedRoleGuidance
       ? ariaHelpers.getDeprecatedRoleGuidance(role)
-      : 'Replace the deprecated role with its recommended replacement.';
+      : {
+          key: 'ariaDeprecatedRole_guidance_default',
+          text: 'Replace the deprecated role with its recommended replacement.'
+        };
 
     if (prohibited) {
       // Author MUST NOT: the usage is non-conforming, not merely discouraged.
-      failOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element uses role="${role}", which authors must not explicitly declare.`,
-        hint: guidance,
-        occurrenceOutcome: 'fail',
-        i18n: {
-          summaryKey: 'ariaDeprecatedRole_summary_fail',
-          hintKey: 'ariaDeprecatedRole_hint_fail',
-          params: { role, guidance }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ROLE_AUTHOR_PROHIBITED', role, guidance }
-        }
-      });
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which authors must not explicitly declare.`,
+          hint: guidance.text,
+          occurrenceOutcome: 'fail',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_fail',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_AUTHOR_PROHIBITED', role, guidance: guidance.text }
+          }
+        })
+      );
     } else if (discouraged) {
       // Reserved for user-agent-internal use, at SHOULD NOT strength.
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element uses role="${role}", which is reserved for user agents (still valid, but discouraged).`,
-        hint: guidance,
-        occurrenceOutcome: 'cantTell',
-        i18n: {
-          summaryKey: 'ariaDeprecatedRole_summary_cantTell_discouraged',
-          hintKey: 'ariaDeprecatedRole_hint_cantTell',
-          params: { role, guidance }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance }
-        }
-      });
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which is reserved for user agents (still valid, but discouraged).`,
+          hint: guidance.text,
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_cantTell_discouraged',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance: guidance.text }
+          }
+        })
+      );
     } else {
       // Deprecated but still valid: surfaced for the author to decide.
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element uses role="${role}", which is deprecated in WAI-ARIA.`,
-        hint: guidance,
-        occurrenceOutcome: 'cantTell',
-        i18n: {
-          summaryKey: 'ariaDeprecatedRole_summary_cantTell',
-          hintKey: 'ariaDeprecatedRole_hint_cantTell',
-          params: { role, guidance }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance }
-        }
-      });
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which is deprecated in WAI-ARIA.`,
+          hint: guidance.text,
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_cantTell',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance: guidance.text }
+          }
+        })
+      );
     }
   }
 

package/src/checks/automatic/aria-hidden-body.js

@@ -10,13 +10,13 @@
  * @sc 1.3.1, 4.1.2
  * @applicability
  *   Always applicable to any HTML document with a <body> element,
- *   independent of contextSelector/root scoping — this is a whole-
+ *   independent of contextSelector/root scoping, this is a whole-
  *   document concern, matching page-title-present's pattern of
  *   evaluating document.body directly rather than the scoped root.
  * @expectation
  *   <body> does not have aria-hidden="true". Hiding the document body
  *   removes the entire page's content and structure from the
- *   accessibility tree at once — both 1.3.1 (Info and Relationships: the
+ *   accessibility tree at once, both 1.3.1 (Info and Relationships: the
  *   page's structure becomes entirely non-determinable) and 4.1.2 (Name,
  *   Role, Value: nothing in the document exposes a role/name/value any
  *   longer) apply.
@@ -86,15 +86,8 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', 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,
+    helpers.reportOccurrence(body, {
       summary:
         'The document body has aria-hidden="true", which hides the entire page from assistive technologies.',
       hint: 'Remove aria-hidden from <body>. Hide specific elements instead, if that was the intent.',
@@ -106,7 +99,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'ARIA_HIDDEN_BODY' }
       }
-    }
+    })
   ];
 
   return {

package/src/checks/automatic/aria-hidden-focus.js

@@ -109,7 +109,7 @@ function runInPage(ctx) {
   }
 
   // Flat-tree ancestor walk (assignedSlot wins over parentNode, then shadow
-  // host) — shared with every other rule via ctx.helpers.composedParent
+  // host), shared with every other rule via ctx.helpers.composedParent
   // (src/core/dom-helpers.js), not reimplemented here, so a fix to the one
   // canonical definition can't drift out of sync with this rule's copy.
   const composedParent =
@@ -146,6 +146,54 @@ function runInPage(ctx) {
     return false;
   }
 
+  // An open modal is expected to trap focus, so a focusable background behind
+  // it may be unreachable; that can't be proven statically, so the finding is
+  // downgraded to cantTell instead of fail. A modal that is display:none is
+  // not open, so it does not count.
+  function isRenderedForModal(node) {
+    if (!node) return false;
+    if (!isDomVisibleEligible) return true;
+    try {
+      const vis = isDomVisibleEligible(node, ctx, {
+        visibilityMode: 'styleOnly',
+        disableGeometry: true
+      });
+      if (vis && vis.eligible === false) return false;
+    } catch {
+      // treat as rendered
+    }
+    return true;
+  }
+
+  // Native <dialog>, aria-modal="true", or a dialog/alertdialog role, so
+  // libraries that leave aria-modal off (e.g. Angular Material defaults to
+  // aria-modal="false") still count as an open modal.
+  function collectOpenModalCandidates() {
+    const nodes = qAll('dialog[open],[aria-modal="true"],[role="dialog"],[role="alertdialog"]');
+    const out = [];
+    for (let i = 0; i < nodes.length; i++) {
+      const n = nodes[i];
+      if (!n || !n.getAttribute) continue;
+      if (!isRenderedForModal(n)) continue;
+      out.push(n);
+    }
+    return out;
+  }
+
+  // Only a modal in a separate subtree is the "hidden background behind an
+  // open dialog" case. A modal inside the aria-hidden subtree (or an
+  // aria-hidden root inside the modal) is a genuine defect, so keep it a fail.
+  function hasSeparateOpenModal(rootEl, candidates) {
+    for (let i = 0; i < candidates.length; i++) {
+      const m = candidates[i];
+      if (!m || m === rootEl) continue;
+      if (isWithinComposedSubtree(m, rootEl)) continue;
+      if (isWithinComposedSubtree(rootEl, m)) continue;
+      return true;
+    }
+    return false;
+  }
+
   function getDeepActiveElement() {
     let cur = document && document.activeElement ? document.activeElement : null;
     let guard = 0;
@@ -485,8 +533,8 @@ function runInPage(ctx) {
     if (isDisabledFormControl(el)) return false;
 
     // An explicit negative tabindex removes the element from the keyboard
-    // tab sequence entirely, regardless of tag — the standard, WAI-
-    // recommended technique for safely hiding focusable content behind
+    // tab sequence entirely, regardless of tag. It's the standard,
+    // WAI-recommended technique for safely hiding focusable content behind
     // aria-hidden (e.g. <button tabindex="-1"> / <a tabindex="-1"> inside
     // an aria-hidden container). This cares about tabbability, not raw
     // focusability. Such an element is still programmatically focusable
@@ -636,7 +684,7 @@ function runInPage(ctx) {
     // Cheap check first: a plain ancestor-attribute walk with no CSS
     // computation, vs. isActuallyFocusable's getComputedStyle-per-ancestor
     // cost. Both conditions are required (AND), so checking whichever is
-    // cheaper first cannot change which elements end up in the bucket —
+    // cheaper first cannot change which elements end up in the bucket,
     // it only skips the expensive check for the (typically vast) majority
     // of focusable candidates that were never inside an aria-hidden root
     // in the first place. On pages with many focusable candidates and a
@@ -713,6 +761,8 @@ function runInPage(ctx) {
     entry.rootIsFocusable = isActuallyFocusable(el);
   }
 
+  const modalCandidates = collectOpenModalCandidates();
+
   // 3) Report one occurrence per aria-hidden root that contains focusable content.
   const failOccurrences = [];
   const uncertainOccurrences = [];
@@ -765,24 +815,56 @@ function runInPage(ctx) {
         : `aria-hidden ${tagName} is focusable (${totalFocusable} focusable element(s)).`
       : `aria-hidden ${tagName} contains ${totalFocusable} focusable element(s).`;
 
-    const runtimeProbe = probeImmediateFocusRedirect(entry);
-    const downgradedToCantTell = !!(runtimeProbe && runtimeProbe.redirected);
-
-    const cantTellSummary = `aria-hidden ${tagName} received focus but focus moved immediately to another element. Verify sentinel/focus-trap behavior.`;
+    // A modal takes precedence over the redirect probe; skip the probe when a
+    // modal already explains the background.
+    const modalOpenOutside = modalCandidates.length
+      ? hasSeparateOpenModal(el, modalCandidates)
+      : false;
+
+    const runtimeProbe = modalOpenOutside ? null : probeImmediateFocusRedirect(entry);
+    const downgradedByRedirect = !!(runtimeProbe && runtimeProbe.redirected);
+    const downgradedByModal = modalOpenOutside;
+    const downgradedToCantTell = downgradedByModal || downgradedByRedirect;
+
+    const cantTellRedirectSummary = `aria-hidden ${tagName} received focus but focus moved immediately to another element. Verify sentinel/focus-trap behavior.`;
+    const cantTellModalSummary = `aria-hidden ${tagName} contains ${totalFocusable} focusable element(s) while a modal dialog is open. If the modal keeps keyboard focus trapped they may be unreachable; verify focus cannot land on them.`;
+
+    let occSummary;
+    let occHint;
+    let occSummaryKey;
+    let occHintKey;
+    let occReasonCode;
+
+    if (downgradedByModal) {
+      occSummary = cantTellModalSummary;
+      occHint =
+        'A modal dialog appears to be open. Prefer making the background inert (or a native <dialog> opened with showModal()) so it leaves the tab order, then verify keyboard focus stays within the dialog.';
+      occSummaryKey = 'ariaHidden_focus_summary_cantTell_modal';
+      occHintKey = 'ariaHidden_focus_hint_cantTell_modal';
+      occReasonCode = 'ariaHiddenFocusable_modalOpen_needsReview';
+    } else if (downgradedByRedirect) {
+      occSummary = cantTellRedirectSummary;
+      occHint =
+        'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on hidden focus targets.';
+      occSummaryKey = 'ariaHidden_focus_summary_cantTell_redirect';
+      occHintKey = 'ariaHidden_focus_hint_cantTell_redirect';
+      occReasonCode = 'ariaHiddenFocusable_runtimeRedirect_needsReview';
+    } else {
+      occSummary = summaryText;
+      occHint =
+        'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.';
+      occSummaryKey = summaryKey;
+      occHintKey = 'ariaHidden_focus_hint_fail';
+      occReasonCode = reasonCode;
+    }
 
     const baseOccurrence = {
-      summary: downgradedToCantTell ? cantTellSummary : summaryText,
-      hint: downgradedToCantTell
-        ? 'Verify this is an intentional focus sentinel/focus-trap handoff and that keyboard users never remain on hidden focus targets.'
-        : 'Remove focusability from descendants or remove aria-hidden; ensure focus and accessibility trees stay aligned.',
+      summary: occSummary,
+      hint: occHint,
       occurrenceOutcome: downgradedToCantTell ? 'cantTell' : 'fail',
       i18n: {
-        summaryKey: downgradedToCantTell
-          ? 'ariaHidden_focus_summary_cantTell_redirect'
-          : summaryKey,
-        hintKey: downgradedToCantTell
-          ? 'ariaHidden_focus_hint_cantTell_redirect'
-          : 'ariaHidden_focus_hint_fail',
+        summaryKey: occSummaryKey,
+        hintKey: occHintKey,
         params: {
           element: tagName,
           focusableCount: String(totalFocusable),
@@ -795,15 +877,14 @@ function runInPage(ctx) {
       },
       data: {
         details: {
-          reasonCode: downgradedToCantTell
-            ? 'ariaHiddenFocusable_runtimeRedirect_needsReview'
-            : reasonCode,
+          reasonCode: occReasonCode,
           metrics: {
             focusableTotal: totalFocusable,
             focusableDescendants: descendantFocusable,
             rootIsFocusable: selfFocusable,
             offendersCaptured: entry.offenders.length,
-            visibilityHints: hintsArr.slice(0)
+            visibilityHints: hintsArr.slice(0),
+            modalOpen: !!downgradedByModal
           },
           runtimeProbe: runtimeProbe || null,
           offenders: entry.offenders.slice(0)
@@ -822,7 +903,7 @@ function runInPage(ctx) {
 
   // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
   // a fail-tier finding never silently discards cantTell-tier findings from
-  // the same run — both are returned together when the outcome is 'fail'.
+  // the same run, both are returned together when the outcome is 'fail'.
   const resolved = helpers.resolveTieredOutcome(
     failOccurrences,
     uncertainOccurrences,

package/src/checks/automatic/aria-prohibited-attr.js

@@ -14,20 +14,20 @@
  *   list for naming attributes (pure text-semantics / non-naming
  *   structural roles: caption, code, deletion, emphasis, generic,
  *   insertion, mark, none, paragraph, presentation, strong, subscript,
- *   suggestion, superscript, time), and (b) elements with no role at all —
+ *   suggestion, superscript, time), and (b) elements with no role at all:
  *   a curated set of native HTML tags verified to carry no implicit role
  *   (see ROLELESS_NATIVE_TAGS below), or any autonomous custom element (a
  *   hyphenated, author-defined tag per the Custom Elements spec; see
- *   isRolelessCustomElementTag below) — in both cases, only elements that
+ *   isRolelessCustomElementTag below). In both cases, only elements that
  *   also carry aria-label or aria-labelledby.
  * @expectation
  *   Prohibited attributes must not be present on (a); for (b), the naming
  *   attribute is at best unreliable (nothing accessible-name-aware to hang
- *   it off) and at worst silently ignored by assistive technology — see the
+ *   it off) and at worst silently ignored by assistive technology. See the
  *   roleless-branch implementation note below for the confidence split
  *   this produces.
  * @implementation-notes
- * - Deliberately scoped to the single, well-established prohibition class
+ * - Scoped to the single, well-established prohibition class
  *   (naming attributes on pure text-semantics roles) rather than an
  *   exhaustive per-role prohibited-attribute table; see
  *   src/core/aria-helpers.js file header for this engine's confidence-
@@ -41,7 +41,7 @@
  *   narrower, unambiguous naming-prohibition case fires as a hard,
  *   WCAG-normative fail instead, matching this engine's "one rule = one
  *   normative decision" pattern.
- * - Deliberately excludes `definition`/`term` despite both appearing on
+ * - Excludes `definition`/`term` on purpose, despite both appearing on
  *   MDN's aria-label "not supported" list: both support name from author
  *   (`nameFrom: ['author']` for definition, `['author', 'contents']` for
  *   term), and the W3C spec's §5.2.8.4 "Roles Supporting Name From Author"
@@ -50,9 +50,9 @@
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
  * - Second, independent branch: naming attributes on ROLELESS elements (no
- *   explicit role="", no implicit/native role either) — e.g. icon-only
+ *   explicit role="", no implicit/native role either), e.g. icon-only
  *   `<span aria-label="...">` tiles with no other accessible-name source.
- *   ROLELESS_NATIVE_TAGS below is a curated, deliberately conservative
+ *   ROLELESS_NATIVE_TAGS below is a curated, intentionally conservative
  *   list of native tags confirmed to carry no implicit role (common
  *   text-level tags like `<p>`/`<strong>`/`<em>`/`<code>`/`<mark>`/`<time>`
  *   resolve to role `null`, same as a bare `<div>`/`<span>`);
@@ -65,7 +65,7 @@
  *   already produces a non-empty accessible name from its content (via
  *   `helpers.getContentNameInfo`, same as
  *   link-name-present/button-name-present), the naming attribute might
- *   just be a redundant/intentional override — reported as `cantTell`, not
+ *   just be a redundant/intentional override, so it's reported as `cantTell`, not
  *   a hard fail. Only a roleless element with no other accessible-name
  *   source at all is a confident, deterministic `fail`. The
  *   widget-ancestor exemption (skip when the closest real ancestor role is
@@ -119,8 +119,8 @@ function runInPage(ctx) {
   // Roles whose WAI-ARIA 1.2 definition lists a "Prohibited ARIA States and
   // Properties" entry for naming attributes (these roles must never carry an
   // accessible name). Declared inside runInPage (rather than at module
-  // scope) because the build inlines only this function's own source text
-  // — see scripts/build-core.js header ("runInPage MUST be self-contained").
+  // scope) because the build inlines only this function's own source text.
+  // See scripts/build-core.js header ("runInPage MUST be self-contained").
   const ROLES_PROHIBITING_NAME = new Set([
     'caption',
     'code',
@@ -167,25 +167,22 @@ function runInPage(ctx) {
 
     if (!present.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const attr of present) {
-      failOccurrences.push({
-        selector: stableSelector,
-        html,
-        occurrenceOutcome: 'fail',
-        summary: 'This attribute is prohibited on this element’s role.',
-        hint: 'Remove this attribute; this role must not carry an accessible name.',
-        i18n: {
-          summaryKey: 'ariaProhibitedAttr_summary_fail',
-          hintKey: 'ariaProhibitedAttr_hint_fail',
-          params: { attr, role }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ATTR_PROHIBITED', attr, role }
-        }
-      });
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          occurrenceOutcome: 'fail',
+          summary: 'This attribute is prohibited on this element’s role.',
+          hint: 'Remove this attribute; this role must not carry an accessible name.',
+          i18n: {
+            summaryKey: 'ariaProhibitedAttr_summary_fail',
+            hintKey: 'ariaProhibitedAttr_hint_fail',
+            params: { attr, role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ATTR_PROHIBITED', attr, role }
+          }
+        })
+      );
     }
   }
 
@@ -193,7 +190,7 @@ function runInPage(ctx) {
   // and how ROLELESS_NATIVE_TAGS/WIDGET_TYPE_ROLES were derived) ---
 
   // Small, curated set of native tags verified to carry no explicit or
-  // implicit ARIA role. Deliberately excludes <section>/<form>/<a> — all
+  // implicit ARIA role. Excludes <section>/<form>/<a>, which are
   // conditionally roleless too, but already handled with more nuance
   // elsewhere in this engine (see header comment).
   const ROLELESS_NATIVE_TAGS = new Set([
@@ -271,7 +268,7 @@ function runInPage(ctx) {
         };
 
   // Nearest ancestor's real role (explicit-if-valid, else native/implicit),
-  // skipping roleless/presentation/none ancestors — used only to check
+  // skipping roleless/presentation/none ancestors. Used only to check
   // whether that role is a "widget"-type one (the roleless-branch
   // exemption). Not the same helper as aria-required-parent's containment
   // walk: this one also accepts non-required-context roles.
@@ -299,7 +296,7 @@ function runInPage(ctx) {
 
   // A small, spec-reserved set of hyphenated tag names that are NOT
   // autonomous custom elements despite containing a hyphen (legacy SVG/
-  // MathML tags predating the Custom Elements spec) — see
+  // MathML tags predating the Custom Elements spec). See
   // https://html.spec.whatwg.org/#valid-custom-element-name's own
   // exclusion list. Excluded so this doesn't misclassify them as
   // always-roleless the same way a real custom element is.
@@ -339,8 +336,8 @@ function runInPage(ctx) {
     const tag = String(el.tagName || '').toLowerCase();
     if (!ROLELESS_NATIVE_TAGS.has(tag) && !isRolelessCustomElementTag(tag)) continue;
     const explicitRole = ariaHelpers.getExplicitRole(el);
-    if (explicitRole && ariaHelpers.isValidConcreteRole(explicitRole)) continue; // has a real, recognized role — Tier 1's concern (if in ROLES_PROHIBITING_NAME) or a role this rule has no opinion on. An INVALID role token (e.g. a typo) is ignored per spec, same as no role attribute at all, and must still fall through to this branch.
-    if (ariaHelpers.getNativeRoleForElement(el)) continue; // has a real implicit role after all — not this branch's concern
+    if (explicitRole && ariaHelpers.isValidConcreteRole(explicitRole)) continue; // has a real, recognized role: Tier 1's concern (if in ROLES_PROHIBITING_NAME) or a role this rule has no opinion on. An INVALID role token (e.g. a typo) is ignored per spec, same as no role attribute at all, and must still fall through to this branch.
+    if (ariaHelpers.getNativeRoleForElement(el)) continue; // has a real implicit role after all, not this branch's concern
 
     const present = [];
     for (const attr of PROHIBITED_NAMING_ATTRS) {
@@ -352,7 +349,7 @@ function runInPage(ctx) {
     applicableCount += 1;
 
     const ancestorRole = getNearestAncestorRole(el);
-    if (ancestorRole && WIDGET_TYPE_ROLES.has(ancestorRole)) continue; // roleless helper node inside a real widget — not flagged
+    if (ancestorRole && WIDGET_TYPE_ROLES.has(ancestorRole)) continue; // roleless helper node inside a real widget, not flagged
 
     const nameInfo = helpers.getContentNameInfo ? helpers.getContentNameInfo(el, ctx) : null;
     const hasContentFallback = !!(
@@ -361,47 +358,49 @@ function runInPage(ctx) {
       String(nameInfo.value || '').trim() !== ''
     );
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const attr of present) {
       if (hasContentFallback) {
-        cantTellOccurrences.push({
-          selector: stableSelector,
-          html,
-          occurrenceOutcome: 'cantTell',
-          summary: `This ${tag} has no role, so ${attr} may not be exposed as its accessible name by assistive technology — but the element's own content already provides one.`,
-          hint: 'Verify whether the existing text content already serves as this element’s label; if so the naming attribute is redundant, otherwise give the element a role that supports naming (e.g. role="img").',
-          i18n: {
-            summaryKey: 'ariaProhibitedAttr_summary_cantTell_roleless',
-            hintKey: 'ariaProhibitedAttr_hint_cantTell_roleless',
-            params: { attr, element: tag }
-          },
-          data: {
-            details: {
-              reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS_NEEDS_REVIEW',
-              attr,
-              role: null,
-              element: tag
+        cantTellOccurrences.push(
+          helpers.reportOccurrence(el, {
+            occurrenceOutcome: 'cantTell',
+            summary: `This ${tag} has no role, so ${attr} may not be exposed as its accessible name by assistive technology, but the element's own content already provides one.`,
+            hint: 'Verify whether the existing text content already serves as this element’s label; if so the naming attribute is redundant, otherwise give the element a role that supports naming (e.g. role="img").',
+            i18n: {
+              summaryKey: 'ariaProhibitedAttr_summary_cantTell_roleless',
+              hintKey: 'ariaProhibitedAttr_hint_cantTell_roleless',
+              params: { attr, element: tag }
+            },
+            data: {
+              details: {
+                reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS_NEEDS_REVIEW',
+                attr,
+                role: null,
+                element: tag
+              }
             }
-          }
-        });
+          })
+        );
       } else {
-        failOccurrences.push({
-          selector: stableSelector,
-          html,
-          occurrenceOutcome: 'fail',
-          summary: `This ${tag} has no role and no other accessible-name source, so ${attr} is not reliably exposed to assistive technology.`,
-          hint: 'Give this element a role that supports an accessible name (e.g. role="img"/"button"), or remove this attribute if it serves no purpose without one.',
-          i18n: {
-            summaryKey: 'ariaProhibitedAttr_summary_fail_roleless',
-            hintKey: 'ariaProhibitedAttr_hint_fail_roleless',
-            params: { attr, element: tag }
-          },
-          data: {
-            details: { reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS', attr, role: null, element: tag }
-          }
-        });
+        failOccurrences.push(
+          helpers.reportOccurrence(el, {
+            occurrenceOutcome: 'fail',
+            summary: `This ${tag} has no role and no other accessible-name source, so ${attr} is not reliably exposed to assistive technology.`,
+            hint: 'Give this element a role that supports an accessible name (e.g. role="img"/"button"), or remove this attribute if it serves no purpose without one.',
+            i18n: {
+              summaryKey: 'ariaProhibitedAttr_summary_fail_roleless',
+              hintKey: 'ariaProhibitedAttr_hint_fail_roleless',
+              params: { attr, element: tag }
+            },
+            data: {
+              details: {
+                reasonCode: 'ARIA_ATTR_PROHIBITED_ROLELESS',
+                attr,
+                role: null,
+                element: tag
+              }
+            }
+          })
+        );
       }
     }
   }
@@ -412,7 +411,7 @@ function runInPage(ctx) {
 
   // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
   // a fail-tier finding never silently discards cantTell-tier findings from
-  // the same run — both are returned together when the outcome is 'fail'.
+  // the same run. Both are returned together when the outcome is 'fail'.
   const resolved = helpers.resolveTieredOutcome(
     failOccurrences,
     cantTellOccurrences,