@surea11y/core 1.3.0 → 1.4.0

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

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-no-duplicate-contentinfo
  * @atomic true
  * @summary A page must not have more than one contentinfo 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 landmark
  *   (explicit role="contentinfo", or an implicit, non-nested <footer>).
@@ -16,11 +18,8 @@
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - 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))`) — same fix applied to the sibling
- *   banner/main rules after finding real hidden-duplicate false positives
- *   on Trello and Zoom.
+ *   same as the sibling banner/main rules, avoiding hidden-duplicate false
+ *   positives.
  */
 
 const id = 'landmark-no-duplicate-contentinfo';
@@ -55,9 +54,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') {
@@ -80,10 +78,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 })
@@ -97,11 +93,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' : '';
     }
@@ -129,9 +123,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 =

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

@@ -1,29 +1,27 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-no-duplicate-main
  * @atomic true
  * @summary A page must not have more than one main 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>).
  * @expectation
  *   At most one main landmark exists on the page. Distinct, atomic
  *   decision from landmark-one-main (that rule flags zero
- *   mains too; this one only flags more than one) — matches a widely-used
- *   reference engine shipping both as separate rules with some overlap by design.
+ *   mains too; this one only flags more than one).
  * @implementation-notes
  * - Not WCAG-normative — authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
- * - 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 `<main>` (found on
- *   a real site — Zoom's homepage) 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 `<main>` is flagged as a duplicate landmark even
+ *   though the hidden copy is never reachable by AT.
  */
 
 const id = 'landmark-no-duplicate-main';
@@ -70,9 +68,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 =

package/src/checks/manual/landmark-one-main-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-one-main
  * @atomic true
  * @summary The page should have a main 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
  *   Always applicable to any HTML document with a <body> element —
  *   "does the page have a main landmark" is a whole-page concern,
@@ -18,27 +20,15 @@
  * - Not WCAG-normative — authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
- * - Presence-only, matching a widely-used reference engine's real
- *   `landmark-one-main` scope exactly (confirmed 2026-07-22 by reading that
- *   engine's source directly: its `page-has-main` check is a plain
- *   descendant-exists test, `has-descendant-evaluate` — it does NOT flag
- *   more than one). This rule previously ALSO flagged "more than one main,"
- *   which was both a real scope mismatch against that reference engine (it
- *   ships that as a fully separate rule, `landmark-no-duplicate-main` /
- *   `page-no-duplicate-main`, already correctly implemented here as
- *   `landmark-no-duplicate-main`) and missing that sibling rule's
- *   accessibility-tree visibility filter, so it double-flagged cases the
- *   sibling rule already handles correctly — found via a real page
- *   (2026-07-22, live-DOM corpus): Resy's and DuckDuckGo's homepages each
- *   genuinely have two visible `<main>` elements, which that reference
- *   engine's `landmark-one-main` doesn't flag at all (out of its scope) but
- *   this rule wrongly did, disagreeing with it for a
- *   reason that wasn't a real coverage gap on either side — just a
- *   redundant, incorrectly-scoped extra branch here.
+ * - Presence-only: a plain descendant-exists test. It does NOT flag more
+ *   than one main. "More than one main" is a separate rule,
+ *   `landmark-no-duplicate-main`, already implemented — deliberately not
+ *   duplicated here, since a page can genuinely have two visible `<main>`
+ *   elements, which is out of scope for "does a main landmark exist," not
+ *   a violation this rule should report.
  * - Filters candidates through `isAccTreeEligible` (hidden/aria-hidden/
  *   display:none/inert elements don't count as "a main landmark exists"),
- *   matching `landmark-no-duplicate-main`'s own precedent and
- *   that reference engine's own accessibility-tree-scoped matching.
+ *   matching `landmark-no-duplicate-main`'s own precedent.
  */
 
 const id = 'landmark-one-main';
@@ -106,9 +96,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 =

package/src/checks/manual/landmark-unique-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check landmark-unique
  * @atomic true
  * @summary Landmarks sharing the same role must have unique accessible names
- * @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 two or more landmark regions on the page share the
  *   same landmark role (banner, contentinfo, main, navigation,
@@ -59,9 +61,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') {
@@ -81,27 +81,21 @@ function runInPage(ctx) {
   // Delegates to the shared helpers.hasLandmarkScopingAncestor (role-aware:
   // an ancestor's bare TAG only counts when it carries no role attribute at
   // all; an explicit role="dialog"-style override no longer suppresses —
-  // see that function's header comment in src/core/aria-helpers.js) rather
-  // than the two local tag-only Sets this file used to carry. Two distinct
-  // ancestor scopes, verified 2026-07-20 against a widely-used reference
-  // engine's own implicit-role functions directly rather than assumed from
-  // one shared list: <header>/<footer> use "sectioning content PLUS <main>"
-  // (includeMain: true) to decide banner/contentinfo suppression, but
-  // <aside> uses PLAIN sectioning content only — NOT main (includeMain:
-  // false) — to decide complementary suppression. The old single
-  // SECTIONING_ANCESTORS set (which included 'main') was correct for
-  // header/footer but wrong for aside — found via a real page: Know Your
-  // Meme's two unnamed <aside class="extra-large-only"> elements are direct
-  // children of <main>, which incorrectly suppressed their implicit
-  // "complementary" role entirely, hiding a real duplicate-landmark
-  // violation that reference engine correctly flags. The tag-only
-  // (non-role-aware) half of this bug was separately found and fixed
-  // 2026-07-30 via the cross-engine comparisons project, on
-  // handsontable.com's docs-assistant side panel: an <aside role="dialog">
-  // containing its own <header> — role="dialog" isn't one of the four
-  // scoping roles, so the nested <header> keeps "banner" per spec, but a
-  // tag-only check unconditionally suppressed it just because the ancestor
-  // TAG was <aside>.
+  // see that function's header comment in src/core/aria-helpers.js), using
+  // two distinct ancestor scopes rather than one shared list: <header>/
+  // <footer> use "sectioning content PLUS <main>" (includeMain: true) to
+  // decide banner/contentinfo suppression, but <aside> uses PLAIN
+  // sectioning content only — NOT main (includeMain: false) — to decide
+  // complementary suppression. A single shared sectioning-ancestors set
+  // that includes 'main' is correct for header/footer but wrong for aside:
+  // e.g. two unnamed <aside> elements that are direct children of <main>
+  // would have their implicit "complementary" role incorrectly suppressed,
+  // hiding a real duplicate-landmark violation. The role-aware half matters
+  // too: e.g. an <aside role="dialog"> containing its own <header> —
+  // role="dialog" isn't one of the four scoping roles, so the nested
+  // <header> keeps "banner" per spec, but a tag-only (non-role-aware)
+  // check would unconditionally suppress it just because the ancestor TAG
+  // was <aside>.
   function hasSectioningAncestor(el, includeMain) {
     return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
       ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
@@ -115,10 +109,9 @@ function runInPage(ctx) {
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
-      // Per a widely-used reference engine's own `aside` implicit-role function: suppressed by a
-      // sectioning-content ancestor ONLY when the <aside> also has no
-      // accessible name — a named <aside> is never suppressed, even when
-      // nested.
+      // An <aside> is suppressed by a sectioning-content ancestor ONLY
+      // when it also has no accessible name — a named <aside> is never
+      // suppressed, even when nested.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
       return getAccessibleLandmarkName(el) ? 'complementary' : '';
     }
@@ -146,15 +139,12 @@ function runInPage(ctx) {
       // <form>/<section> only count as landmarks when they have an
       // accessible name — a property of the ELEMENT, not of how the role
       // got there. This applies whether the role is implicit (already
-      // handled in getImplicitLandmarkRole below) or explicit, but an
-      // explicit role bypassed the check entirely before this fix. Verified
-      // against a widely-used reference engine's isLandmarkVirtual (checks
-      // nodeName === 'section' || 'form' unconditionally, regardless of role source) and the W3C
+      // handled in getImplicitLandmarkRole below) or explicit. Per the W3C
       // ARIA-in-HTML spec ("a form is not exposed as a landmark region
-      // unless it has been provided an accessible name"). Found via a real
-      // page: europa.eu's unnamed <form role="search"> nested inside an
-      // unnamed <div role="search"> was wrongly counted as a second
-      // distinct "search" landmark.
+      // unless it has been provided an accessible name"). Otherwise an
+      // unnamed <form role="search"> nested inside an unnamed
+      // <div role="search"> gets wrongly counted as a second distinct
+      // "search" landmark.
       const tag = el.tagName ? el.tagName.toLowerCase() : '';
       if (tag === 'form' || tag === 'section') {
         return getAccessibleLandmarkName(el) ? explicit : '';
@@ -179,12 +169,10 @@ function runInPage(ctx) {
   }
 
   // queryAllSmart (shadow-DOM-aware, includeShadowDom defaults true) instead of a plain
-  // document.querySelectorAll -- a real page (Airtable's homepage, 2026-07-23) has a
-  // third-party Transcend cookie-consent widget rendering its own unnamed <nav>/<footer>
-  // inside a shadow root (#transcend-shadow-root), which a widely-used reference engine's
-  // own landmark-unique (a real browser DOM, shadow roots included by design) correctly sees as colliding
-  // with the page's own unnamed header <nav>/page <footer> -- a real, confirmed surea11y
-  // false-negative miss, invisible to plain querySelectorAll's light-DOM-only reach.
+  // document.querySelectorAll -- a third-party widget rendering its own
+  // unnamed <nav>/<footer> inside a shadow root collides with the page's
+  // own unnamed header <nav>/page <footer>, but is invisible to plain
+  // querySelectorAll's light-DOM-only reach.
   let nodes;
   try {
     nodes =
@@ -195,15 +183,12 @@ function runInPage(ctx) {
     nodes = [];
   }
 
-  // Only landmarks actually exposed to assistive technology can collide —
-  // matches a widely-used reference engine's own `landmarkUniqueMatches` gate
-  // (`_isVisibleToScreenReaders`), confirmed by reading its source
-  // directly. Without this, responsive layouts that render both a
-  // desktop and a mobile copy of the same named nav (one hidden via CSS
-  // at any given viewport — found on real sites: BuzzFeed, Kraken,
-  // weather.com) were wrongly flagged as duplicate landmarks, since the
-  // hidden copy is never actually reachable by AT and can't really
-  // collide with the visible one.
+  // Only landmarks actually exposed to assistive technology can collide.
+  // Without this, responsive layouts that render both a desktop and a
+  // mobile copy of the same named nav (one hidden via CSS at any given
+  // viewport) are wrongly flagged as duplicate landmarks, since the hidden
+  // copy is never reachable by AT and can't really collide with the
+  // visible one.
   const byRole = new Map(); // role -> [{el, name}]
   const seen = new Set();
   for (const el of nodes) {

package/src/checks/manual/link-name-quality-manual.js

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

package/src/checks/manual/media-transcript-present-manual.js

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

package/src/checks/manual/meta-viewport-large-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check meta-viewport-large
  * @atomic true
  * @summary Viewport meta tag should allow zooming up to 500% (AAA-level)
- * @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 <meta name="viewport"> elements that carry a non-empty
  *   content attribute.

package/src/checks/manual/mouse-only-event-handlers-manual.js

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

package/src/checks/manual/no-autoplay-audio-manual.js

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

package/src/checks/manual/object-text-alternative-quality-manual.js

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

package/src/checks/manual/p-as-heading-manual.js

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

package/src/checks/manual/page-has-heading-one-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check page-has-heading-one
  * @atomic true
  * @summary The page should have at least one level-one heading
- * @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
  *   Always applicable to any HTML document with a <body> element —
  *   "does the page have an h1" is a whole-page concern, matching
@@ -21,16 +23,15 @@
  *   header comment for the shared rationale/precedent.
  * - Filters candidates through `isAccTreeEligible` (hidden/aria-hidden/
  *   display:none/inert elements don't count as "the page has a heading
- *   one"), matching `landmark-one-main`'s own precedent. Found via a real
- *   page (CDC's flu page, 2026-07-30): its only `<h1>` sits inside a
- *   `display:none` ancestor — genuinely unreachable by sighted and screen
- *   reader users alike — and a raw `document.querySelectorAll` credited it
- *   anyway, incorrectly reporting `notApplicable`. This
- *   does NOT regress purely-visually-clipped-but-AT-exposed headings (e.g.
- *   eBay's homepage `<h1>` hidden via clip-path/off-screen positioning,
- *   `visibility:visible`, no `aria-hidden`) — `isAccTreeEligible` only
- *   excludes elements actually removed from the accessibility tree, not
- *   ones merely clipped from the visual viewport.
+ *   one"), matching `landmark-one-main`'s own precedent — a raw
+ *   `document.querySelectorAll` would wrongly credit an `<h1>` that sits
+ *   inside a `display:none` ancestor, genuinely unreachable by sighted and
+ *   screen reader users alike, as satisfying this check. This does NOT
+ *   regress purely-visually-clipped-but-AT-exposed headings (e.g. an `<h1>`
+ *   hidden via clip-path/off-screen positioning, `visibility:visible`, no
+ *   `aria-hidden`) — `isAccTreeEligible` only excludes elements actually
+ *   removed from the accessibility tree, not ones merely clipped from the
+ *   visual viewport.
  */
 
 const id = 'page-has-heading-one';

package/src/checks/manual/page-title-patterns-manual.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'page-title-patterns';

package/src/checks/manual/presentation-role-conflict-manual.js

@@ -1,16 +1,17 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check presentation-role-conflict
  * @atomic true
  * @summary role="presentation"/"none" must not be combined with a global ARIA naming attribute or focusability
- * @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 elements with an explicit role="presentation" or
  *   role="none", OR an <img alt=""> (empty alt gives an <img> an implicit
  *   presentation role per HTML-AAM, even with no explicit role attribute
- *   at all — verified against a widely-used reference engine's own selector
- *   for this exact check, `img[alt=''], [role="none"], [role="presentation"]`).
+ *   at all — `img[alt=''], [role="none"], [role="presentation"]`).
  * @expectation
  *   The element does not also carry a WAI-ARIA *global* state/property
  *   (aria-label, aria-hidden, aria-describedby, aria-live, aria-current,
@@ -25,32 +26,27 @@
  * - Not WCAG-normative — authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
- * - The conflicting-attribute set matches a widely-used reference engine's
- *   own `none: ['is-element-focusable', 'has-global-aria-attribute']` condition
- *   exactly — `has-global-aria-attribute` checks against the full list of
- *   ARIA attributes marked `global: true` in that engine's own standards data
- *   (confirmed by reading `standards.ariaAttrs` directly at runtime, not
- *   guessed), which is much broader than the 3-attribute naming-only list
- *   this rule originally checked (added 2026-07-20, then widened
- *   2026-07-20 after a real page — Slack's homepage has
- *   `<img alt="" aria-hidden="">`, both gaps at once: the img[alt=''] case
- *   wasn't in the applicability selector at all, and aria-hidden wasn't in
- *   the conflicting-attribute set even if it had been).
- * - Deliberately NOT replicating that reference engine's
- *   `hasImplicitChromiumRoleMatches` applicability gate, which (per direct
- *   probing of the reference engine's runtime) makes its own check
- *   inapplicable to role="presentation" on elements with no
- *   native implicit role to suppress in the first place (e.g.
- *   `<div role="presentation" aria-hidden="true">` — a <div> has no native
- *   role, so there's nothing for the presentational role to "conflict"
- *   with per that engine's own scope decision). surea11y stays
- *   broader/more cautious here rather than narrower, which is the safer
- *   direction to diverge in, and no real false positive from staying
- *   broad has surfaced in any corpus round to date.
- * - The native-implicit-role table needed to replicate that gate (if this
- *   scope decision is ever revisited) has since been produced — see
- *   ROADMAP.md §7 item 9 (2026-07-31) for the full table and the open
- *   maintainer decision; not implemented here pending that call.
+ * - `aria-hidden="true"` (the exact valid truthy value) on the
+ *   presentational element itself is deliberately EXCLUDED as a trigger,
+ *   even though it's a global ARIA attribute: it removes the element from
+ *   the accessibility tree unconditionally, so the "role restoration"
+ *   this rule warns about never actually reaches assistive tech, making a
+ *   flag misleading. Any OTHER conflicting attribute present alongside
+ *   `aria-hidden="true"` is equally inert for the same reason and is not
+ *   flagged either. An `aria-hidden=""` (empty/invalid value, does NOT
+ *   hide) still triggers normally. Focusability is unaffected by this
+ *   exemption (see the code comment at the check site).
+ * - The conflicting-attribute set is the full list of ARIA attributes
+ *   marked `global: true`, not a narrower naming-only list.
+ * - Deliberately NOT applying an implicit-role applicability gate that
+ *   would make the check inapplicable to role="presentation" on elements
+ *   with no native implicit role to suppress (e.g. `<div
+ *   role="presentation" aria-hidden="true">` — a <div> has no native role,
+ *   so there's nothing for the presentational role to "conflict" with).
+ *   surea11y stays broader/more cautious here rather than narrower, which
+ *   is the safer direction to diverge in. The native-implicit-role table
+ *   needed to add that gate, if this scope decision is ever revisited, is
+ *   in ROADMAP.md §7 item 9.
  * - Focusability is computed via helpers.getFocusableInfo (native +
  *   tabindex), same helper aria-hidden-focus already relies on — a
  *   `:disabled` or otherwise non-focusable element is not flagged.
@@ -81,9 +77,8 @@ function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
   // The full set of ARIA attributes marked `global: true` per the WAI-ARIA
-  // spec (confirmed against a widely-used reference engine's own
-  // `standards.ariaAttrs` data at runtime, 2026-07-20) — any of these present on a presentational
-  // element restores its implicit role, not just the naming ones.
+  // spec — any of these present on a presentational element restores its
+  // implicit role, not just the naming ones.
   const CONFLICTING_ATTRS = [
     'aria-atomic',
     'aria-braillelabel',
@@ -128,14 +123,33 @@ function runInPage(ctx) {
 
     // Presence, not value truthiness: the WAI-ARIA role-conflict-resolution
     // rule triggers on a global ARIA attribute being SPECIFIED at all, even
-    // with an empty value — found on a real site, Slack's homepage has
-    // <img alt="" aria-hidden="">, where aria-hidden="" (empty string) is
-    // still a specified attribute. A truthy-value check would have missed
-    // this even after aria-hidden was added to CONFLICTING_ATTRS above.
-    const present = CONFLICTING_ATTRS.filter((attr) =>
+    // with an empty value — e.g. <img alt="" aria-hidden="">, where
+    // aria-hidden="" (empty string) is still a specified attribute. A
+    // truthy-value check would miss this.
+    let present = CONFLICTING_ATTRS.filter((attr) =>
       el.hasAttribute ? el.hasAttribute(attr) : el.getAttribute(attr) != null
     );
 
+    // aria-hidden="true" (the exact, valid truthy value — not the
+    // empty-string case above, which never actually hides anything) is a
+    // special case: it removes the element and its subtree from the
+    // accessibility tree unconditionally, independent of role. That makes
+    // the "role restoration" this rule warns about ("...which restores its
+    // implicit role and cancels the presentational intent") factually
+    // inert — no AT will ever expose the restored role OR any of the other
+    // conflicting attributes (aria-label, aria-describedby, ...) present
+    // alongside it, since the whole element stays out of the tree
+    // regardless. This pattern is extremely common (e.g. <svg
+    // role="presentation" aria-hidden="true"> decorative icons — a
+    // defensive belt-and-suspenders double-hide, not an authoring mistake).
+    // Focusability is NOT covered by this exemption — a keyboard user can
+    // still tab onto an aria-hidden="true" focusable element (the
+    // aria-hidden-focus anti-pattern), a real, independent hazard
+    // aria-hidden does nothing to prevent.
+    if (el.getAttribute('aria-hidden') === 'true') {
+      present = [];
+    }
+
     let isFocusable = false;
     if (getFocusableInfo) {
       try {