@surea11y/core 1.3.0 → 1.4.1

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 {

package/src/checks/manual/region-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check region
  * @atomic true
  * @summary Page content should be contained within a landmark region
- * @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 any element under <body> that directly carries visible text
  *   (or other own content — see @implementation-notes) and is not itself a
@@ -20,18 +22,15 @@
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent and the landmark-
  *   detection model.
- * - Recursive tree walk, not a direct-<body>-children-only scan (that was
- *   this check's original scope, replaced 2026-08-01). The direct-children
- *   scope was originally chosen to keep this check quiet, but it turned out
- *   to be nearly inert on the single most common real-world page shape: a
- *   modern framework's single root mount div
- *   (`<body><div id="root">...everything...</div></body>`, confirmed
- *   present as the ONLY direct <body> child on 37 of ~90 pages in a
- *   real-world corpus). On that shape, the old scan had at most one
- *   candidate for the entire page and either missed every real gap inside
- *   it or collapsed the whole page into one undifferentiated report.
- * - Algorithm, using this engine's own (already more spec-correct in
- *   places — see hasLandmarkScopingAncestor's header comment) helpers:
+ * - Recursive tree walk, not a direct-<body>-children-only scan: a
+ *   direct-children-only scope is nearly inert on the single most common
+ *   real-world page shape, a modern framework's single root mount div
+ *   (`<body><div id="root">...everything...</div></body>`) — that shape
+ *   gives at most one candidate for the entire page and either misses
+ *   every real gap inside it or collapses the whole page into one
+ *   undifferentiated report.
+ * - Algorithm, using this engine's own helpers (see
+ *   hasLandmarkScopingAncestor's header comment):
  *     1. Depth-first walk from <body>'s children.
  *     2. At each node: if it's ineligible for the accessibility tree
  *        (helpers.isAccTreeEligible), OR is itself a "stopper" (landmark,
@@ -52,7 +51,7 @@
  *   contiguous unplaced content into one occurrence per real gap instead
  *   of reporting every individual text-bearing leaf — this is what keeps
  *   the walk from being noisy on ordinary pages that mix landmarked and
- *   stray content, not the old direct-children-only restriction.
+ *   stray content.
  * - "Stopper" exemptions (button, dialog, <svg>, resolvable skip-links)
  *   are a deliberate scope choice, not an oversight: these
  *   are extremely common real-world patterns (floating action buttons,
@@ -119,9 +118,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') {
@@ -144,10 +141,9 @@ function runInPage(ctx) {
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
-  // in src/core/aria-helpers.js for the full algorithm and the real page
-  // (handsontable.com's docs-assistant side panel, an
-  // <aside role="dialog"> containing its own <header>) that surfaced this
-  // rule's own former tag-only copy as a false negative.
+  // in src/core/aria-helpers.js for the full algorithm — e.g. an
+  // <aside role="dialog"> containing its own <header>, where the <header>
+  // keeps its banner role.
   function hasSectioningAncestor(el, includeMain) {
     return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
       ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
@@ -161,11 +157,9 @@ function runInPage(ctx) {
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
     if (tag === 'aside') {
-      // A named <aside> is never suppressed, even when nested — matches
-      // landmark-unique's own verified-against-reference-engine precedent
-      // (that engine's real `aside` implicit-role function keeps
+      // A named <aside> is never suppressed, even when nested: keeps
       // "complementary" when the element has an accessible name, even
-      // inside sectioning content); propagated here for consistency.
+      // inside sectioning content. See landmark-unique-manual.js.
       if (!hasSectioningAncestor(el, false)) return 'complementary';
       return getAccessibleLandmarkName(el) ? 'complementary' : '';
     }
@@ -196,8 +190,7 @@ function runInPage(ctx) {
 
   // Roles/attributes that make an element its own self-contained
   // announced area — not literally a WAI-ARIA landmark, but not "content
-  // that needs a landmark" either. Same live-region role list a widely-used
-  // reference engine's own region rule stops recursion at.
+  // that needs a landmark" either.
   const LIVE_REGION_ROLES = new Set(['alert', 'status', 'log', 'marquee', 'timer']);
 
   function isAriaLive(el) {
@@ -257,12 +250,11 @@ function runInPage(ctx) {
   const VISUAL_CONTENT_TAGS = new Set(['img', 'video', 'audio', 'canvas', 'object', 'embed']);
 
   // Non-recursive "does THIS element, on its own, carry content" check —
-  // deliberately mirrors only the direct-content half of getContentNameInfo/
-  // a widely-used reference engine's own has-content check, not a full
-  // name-from-content recursion: the whole point is to keep recursing
-  // through plain wrapper elements (a framework's root mount <div> included)
-  // until reaching the actual content-bearing node, rather than a coarse
-  // ancestor swallowing everything beneath it into one report.
+  // deliberately mirrors only the direct-content half of getContentNameInfo,
+  // not a full name-from-content recursion: the whole point is to keep
+  // recursing through plain wrapper elements (a framework's root mount
+  // <div> included) until reaching the actual content-bearing node, rather
+  // than a coarse ancestor swallowing everything beneath it into one report.
   function hasOwnContent(el) {
     const kids = el.childNodes || [];
     for (let i = 0; i < kids.length; i++) {
@@ -341,9 +333,8 @@ function runInPage(ctx) {
   // Collapse each candidate leaf upward through parents that have no OTHER
   // stopper anywhere in their subtree, so contiguous unplaced content
   // merges into ONE occurrence per real gap instead of one per text node --
-  // this collapsing, not the old direct-children-only scope, is what keeps
-  // ordinary pages (landmarked content mixed with a little stray content)
-  // from producing noisy, one-per-leaf reports.
+  // this collapsing is what keeps ordinary pages (landmarked content mixed
+  // with a little stray content) from producing noisy, one-per-leaf reports.
   const collapsed = [];
   const seen = new Set();
   for (const leaf of leaves) {

package/src/checks/manual/scope-attr-valid-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check scope-attr-valid
  * @atomic true
  * @summary The scope attribute must have a valid value
- * @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 a non-empty scope attribute.
  * @expectation

package/src/checks/manual/scrollable-region-focusable-manual.js

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

package/src/checks/manual/skip-link-manual.js

@@ -1,20 +1,21 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check skip-link
  * @atomic true
  * @summary A "skip" link must resolve to a real, usable target
- * @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 <a href="#fragment"> elements whose accessible name
  *   matches a common "skip to ..." / "jump to ..." authoring convention
  *   (case-insensitive "skip" or "jump to" in the name) — the recognizable
  *   pattern for a skip-navigation link, not every same-page anchor link
- *   on the page. "jump to" added 2026-07-23 after a real page (Wish.com)
- *   surfaced a skip link reading "Jump to section" with a genuinely
- *   missing target — invisible to the original "skip"-only pattern,
- *   while a widely-used reference engine's own (purely positional, not text-based) matching
- *   caught it. Text-pattern matching itself stays deliberate (see
+ *   on the page. "jump to" is included alongside "skip" since real skip
+ *   links use both conventions (e.g. a "Jump to section" link, which a
+ *   purely positional match would catch but a "skip"-only text pattern
+ *   would miss). Text-pattern matching itself stays deliberate (see
  *   implementation-notes) — this only widens the known-convention list.
  * @expectation
  *   The link's fragment resolves to a real element in the document

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

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

package/src/checks/manual/tabindex-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check tabindex
  * @atomic true
  * @summary tabindex should not be greater than 0
- * @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 a tabindex attribute whose value parses as
  *   a valid integer.

package/src/checks/manual/table-duplicate-name-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check table-duplicate-name
  * @atomic true
  * @summary A table's caption must not duplicate its summary attribute
- * @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 <table> elements that have both a <caption> with text
  *   content and a (deprecated but still encountered) summary attribute.
@@ -17,9 +19,8 @@
  * - 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.
- * - Narrowly scoped to caption-vs-summary duplication specifically
- *   (matching a reference engine's table-duplicate-name check), not a general "table
- *   name quality" check.
+ * - Narrowly scoped to caption-vs-summary duplication specifically, not a
+ *   general "table name quality" check.
  */
 
 const id = 'table-duplicate-name';