@surea11y/core 1.4.1 → 1.6.0

package/src/checks/automatic/link-name-present.js

@@ -2,6 +2,27 @@
 
 'use strict';
 
+/**
+ * @check link-name-present
+ * @atomic true
+ * @summary Links must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to <a href>, <area href> and elements with role="link" that are
+ *   included in the accessibility tree. An <a> without an href is not a link
+ *   and is not matched.
+ * @expectation
+ *   The element has a non-empty accessible name. A programmatic name is
+ *   taken first (aria-labelledby, aria-label, an associated <label>, title),
+ *   and failing that the element falls back to its own subtree text,
+ *   counting each descendant's own name (an <img alt>, aria-label or title),
+ *   the shape behind the common <a><img alt="..."></a> logo link. The
+ *   content fallback is suppressed when an explicit, known role that is not
+ *   name-from-content is present; an unrecognized role token falls back to
+ *   the implicit role.
+ */
+
 const id = 'link-name-present';
 
 const meta = {
@@ -38,7 +59,7 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   function getConservativeSubtreeText(container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -139,39 +160,34 @@ function runInPage(ctx) {
         ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
         : null;
 
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
       const tag = (el.tagName || '').toLowerCase();
 
-      occurrences.push({
-        selector: stableSelector,
-        html,
-
-        // Human fallbacks (allowed)
-        summary: 'This link has no accessible name.',
-        hint: 'Provide link text or an accessible-name mechanism (for example aria-label) so assistive technologies can identify the link.',
-
-        // Validator requires these keys to exist in the English dictionary
-        i18n: {
-          summaryKey: 'linkNamePresent_summary_fail',
-          hintKey: 'linkNamePresent_hint_fail',
-          params: { element: tag }
-        },
-
-        data: {
-          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-          details: {
-            reasonCode: 'name_missing',
-            metrics: {
-              programmaticNameLength: programmaticName.trim().length,
-              contentNameLength: contentName.trim().length
-            },
-            refs: { accessibleName: nameInfo || null }
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          // Human fallbacks (allowed)
+          summary: 'This link has no accessible name.',
+          hint: 'Provide link text or an accessible-name mechanism (for example aria-label) so assistive technologies can identify the link.',
+
+          // Validator requires these keys to exist in the English dictionary
+          i18n: {
+            summaryKey: 'linkNamePresent_summary_fail',
+            hintKey: 'linkNamePresent_hint_fail',
+            params: { element: tag }
+          },
+
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: {
+              reasonCode: 'name_missing',
+              metrics: {
+                programmaticNameLength: programmaticName.trim().length,
+                contentNameLength: contentName.trim().length
+              },
+              refs: { accessibleName: nameInfo || null }
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

package/src/checks/automatic/list-children-valid.js

@@ -12,7 +12,7 @@
  *   Applies to <ul>/<ol> elements that have at least one direct element
  *   child.
  * @expectation
- *   Every direct element child is <li>, <script>, or <template> — UNLESS it
+ *   Every direct element child is <li>, <script>, or <template>. UNLESS it
  *   has an explicit `role` attribute, in which case the explicit role wins
  *   over the tag entirely: a child is valid iff that role is "listitem"
  *   (so `<li role="presentation">`/`<li role="menuitem">` are invalid
@@ -20,19 +20,19 @@
  *   given `role="listitem"` is valid). A wrapper <div> used for styling
  *   (no role at all) still breaks list semantics the same as before.
  * @implementation-notes
- * - Checked via el.children, which already excludes text/comment nodes —
+ * - Checked via el.children, which already excludes text/comment nodes,
  *   no whitespace-node filtering needed.
  * - Distinct, atomic decision from listitem-parent-valid (the
  *   inverse relationship: does a given <li> have a valid parent).
  * - Direct children that are not exposed to the accessibility tree (e.g.
  *   display:none, [hidden], aria-hidden="true") are excluded from
- *   consideration entirely — an element not reachable by assistive
+ *   consideration entirely. An element not reachable by assistive
  *   technology can't break the list semantics a screen reader announces.
  *   Common cases: a stray `<input type="hidden">` as a direct <ul> child
  *   (UA-stylesheet display:none by spec), or `<span style="display:none">`
  *   hydration markers interleaved with real `<li>`s.
  * - Explicit-role-overrides-tag: if a child has an explicit role, only
- *   `['listitem']` is consulted — the tag name is never checked. Only
+ *   `['listitem']` is consulted, the tag name is never checked. Only
  *   without an explicit role does the tag name matter. Catches cases a
  *   tag-only check misses: `<li role="none">` hosting a list's own
  *   visually-hidden label, `<li role="menuitem">` menu items, or a real
@@ -71,7 +71,7 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const ALLOWED_CHILD_TAGS = new Set(['li', 'script', 'template']);
 
@@ -111,7 +111,7 @@ function runInPage(ctx) {
       const roleAttr = child.getAttribute ? String(child.getAttribute('role') || '').trim() : '';
       const explicitRole = roleAttr ? (roleAttr.split(/\s+/)[0] || '').toLowerCase() : '';
 
-      // An explicit role always wins over the tag — see header comment.
+      // An explicit role always wins over the tag, see header comment.
       const valid = explicitRole ? explicitRole === 'listitem' : ALLOWED_CHILD_TAGS.has(tag);
 
       if (!valid) invalidTags.push(tag);
@@ -122,23 +122,21 @@ function runInPage(ctx) {
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This list contains a direct child that is not a list item.',
-      hint: 'Only use <li> (or <script>/<template>) as direct children of <ul>/<ol>; move other markup inside an <li>.',
-      i18n: {
-        summaryKey: 'listChildrenValid_summary_fail',
-        hintKey: 'listChildrenValid_hint_fail',
-        params: { element: tag, invalidChildren: dedupedInvalidTags.join(', ') }
-      },
-      data: {
-        details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This list contains a direct child that is not a list item.',
+        hint: 'Only use <li> (or <script>/<template>) as direct children of <ul>/<ol>; move other markup inside an <li>.',
+        i18n: {
+          summaryKey: 'listChildrenValid_summary_fail',
+          hintKey: 'listChildrenValid_hint_fail',
+          params: { element: tag, invalidChildren: dedupedInvalidTags.join(', ') }
+        },
+        data: {
+          details: { reasonCode: 'LIST_INVALID_CHILD', element: tag, invalidChildren: invalidTags }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/listbox-name-present.js

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check listbox-name-present
+ * @atomic true
+ * @summary Elements with role="listbox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="listbox" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title.
+ *   role="listbox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom listbox widget is not reliably
+ *   exposed as its name. On a labelable element (<select multiple
+ *   role="listbox">) an associated <label> counts as well.
+ */
+
 const id = 'listbox-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Listboxes have an accessible name',
+  description: 'Checks that elements with role="listbox" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'listboxNamePresent_title',
     descriptionKey: 'listboxNamePresent_description'
@@ -51,7 +71,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -68,7 +88,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -83,10 +103,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -96,7 +116,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -227,24 +247,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This element has no accessible name.',
-      hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this listbox's accessible name.",
-      i18n: {
-        summaryKey: 'listboxNamePresent_summary_fail',
-        hintKey: 'listboxNamePresent_hint_fail',
-        params: { controlType: 'listbox' }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: 'listbox', methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This element has no accessible name.',
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this listbox's accessible name.",
+        i18n: {
+          summaryKey: 'listboxNamePresent_summary_fail',
+          hintKey: 'listboxNamePresent_hint_fail',
+          params: { controlType: 'listbox' }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: 'listbox', methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/listitem-parent-valid.js

@@ -24,16 +24,16 @@
  *   e.g. aria-helpers.js getExplicitRole).
  * - An explicit role on the parent WINS over its tag name, in either
  *   direction: a <ul role="menu"> no longer exposes role "list" (its own
- *   native role is fully replaced by the explicit one — the same "any
+ *   native role is fully replaced by the explicit one, the same "any
  *   explicit role overrides the element's native role" ARIA principle
  *   applied elsewhere in this engine), so an <li> inside it is invalid
  *   despite the <ul> tag (e.g. `<ul role="menu"><li>...`). Conversely
  *   role="presentation"/"none" on the parent is still a valid
- *   (list-semantics-suppressing) parent — the accepted parent roles are
+ *   (list-semantics-suppressing) parent, the accepted parent roles are
  *   presentation, none, and list.
  * - The SAME "explicit role wins" principle applies to the <li> ELEMENT
  *   ITSELF: an <li role="tab">/role="menuitem">/role="presentation"> etc.
- *   is exposed to AT with that role, never "listitem" — the whole point
+ *   is exposed to AT with that role, never "listitem". The whole point
  *   of this check (list items need a valid list-container parent) doesn't
  *   apply when the element isn't claiming listitem semantics in the first
  *   place. Any `<li>` with an explicit `role` attribute is excluded from
@@ -108,7 +108,7 @@ function runInPage(ctx) {
     let valid;
     if (explicitRole) {
       // An explicit role always wins over the tag's native role, in either
-      // direction — see the header comment.
+      // direction, see the header comment.
       valid = explicitRole === 'list' || explicitRole === 'presentation' || explicitRole === 'none';
     } else {
       valid = parentTag === 'ul' || parentTag === 'ol';
@@ -116,23 +116,20 @@ function runInPage(ctx) {
 
     if (valid) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This list item is not contained by a list container.',
-      hint: 'Place this <li> inside a <ul>/<ol>, or give its parent role="list".',
-      i18n: {
-        summaryKey: 'listitemParentValid_summary_fail',
-        hintKey: 'listitemParentValid_hint_fail',
-        params: { parentElement: parentTag }
-      },
-      data: {
-        details: { reasonCode: 'LISTITEM_INVALID_PARENT', parentElement: parentTag }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This list item is not contained by a list container.',
+        hint: 'Place this <li> inside a <ul>/<ol>, or give its parent role="list".',
+        i18n: {
+          summaryKey: 'listitemParentValid_summary_fail',
+          hintKey: 'listitemParentValid_hint_fail',
+          params: { parentElement: parentTag }
+        },
+        data: {
+          details: { reasonCode: 'LISTITEM_INVALID_PARENT', parentElement: parentTag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/menuitem-name-present.js

@@ -2,6 +2,24 @@
 
 'use strict';
 
+/**
+ * @check menuitem-name-present
+ * @atomic true
+ * @summary Menu items must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="menuitem", role="menuitemcheckbox" or
+ *   role="menuitemradio" (the attribute must name one of those roles alone,
+ *   not a fallback list) that are included in the accessibility tree.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or, all
+ *   three roles being name-from-content, from its own subtree text, where a
+ *   descendant's own name (an <img alt>, aria-label or title) counts as that
+ *   descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'menuitem-name-present';
 
 const meta = {
@@ -52,7 +70,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -71,7 +89,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -150,24 +168,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This menu item has no accessible name.',
-      hint: 'Provide visible text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
-      i18n: {
-        summaryKey: 'menuitemNamePresent_summary_fail',
-        hintKey: 'menuitemNamePresent_hint_fail',
-        params: { role }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: role, methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This menu item has no accessible name.',
+        hint: 'Provide visible text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
+        i18n: {
+          summaryKey: 'menuitemNamePresent_summary_fail',
+          hintKey: 'menuitemNamePresent_hint_fail',
+          params: { role }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: role, methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/meta-refresh-no-exceptions.js

@@ -9,20 +9,24 @@
  * @standard WCAG 2.2
  * @sc 2.2.4, 3.2.5
  * @applicability
- *   Applies to any <meta http-equiv="refresh"> element with a non-empty
- *   content attribute.
+ *   Applies to the first <meta http-equiv="refresh"> element, in document
+ *   order, with a valid content attribute, per HTML's shared declarative
+ *   refresh steps, a document only ever acts on its first valid meta
+ *   refresh, so a later one (valid or not) is inert and out of scope.
  * @expectation
- *   No meta refresh is present, regardless of delay. This is the
- *   stricter AAA-level counterpart of meta-refresh-timing-absent
- *   (the A-level rule, which only forbids a positive delay and allows
- *   delay="0" as an immediate redirect). At AAA, WCAG 2.2.4
- *   (Interruptions) and 3.2.5 (Change on Request) require that automatic
- *   context changes — including an immediate meta-refresh redirect —
- *   happen only at the user's request, with no exception for a zero
- *   delay.
+ *   Running the shared declarative refresh steps against that element's
+ *   content value results in a delay of exactly 0. An immediate (delay=0)
+ *   redirect still passes at AAA, same as the A-level rule. There is
+ *   nothing for a user to be interrupted mid-read by when nothing is
+ *   displayed first. Any positive delay fails, with none of the A-level
+ *   rule's >20-hour exemption: at AAA, WCAG 2.2.4 (Interruptions) and
+ *   3.2.5 (Change on Request) require that a *timed* automatic context
+ *   change happen only at the user's request, regardless of how long the
+ *   timer is.
  * @implementation-notes
- * - Distinct, atomic decision from meta-refresh-timing-absent:
- *   that rule's delay="0" pass case is this rule's fail case.
+ * - Distinct, atomic decision from meta-refresh-timing-absent: that
+ *   rule's >20-hour exemption for a positive delay is this rule's fail
+ *   case (no exemption at AAA), but delay=0 passes in both rules.
  * - A <meta> nested inside <noscript> is excluded: it only ever takes
  *   effect when scripting is disabled, which is never the case for any
  *   context capable of running accessibility tooling in the first place
@@ -35,7 +39,7 @@ const id = 'meta-refresh-no-exceptions';
 const meta = {
   title: 'Page must not use a meta refresh at all (AAA)',
   description:
-    'Checks that <meta http-equiv="refresh"> is not present at all, regardless of delay — the stricter AAA-level counterpart of the A-level positive-delay-only check.',
+    'Checks that <meta http-equiv="refresh"> is not present at all, regardless of delay. This is the stricter AAA-level counterpart of the A-level positive-delay-only check.',
   i18n: {
     titleKey: 'metaRefreshNoExceptions_title',
     descriptionKey: 'metaRefreshNoExceptions_description'
@@ -122,28 +126,32 @@ function runInPage(ctx) {
     if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled
     const raw = String(el.getAttribute('content') || '').trim();
     if (!raw) continue;
-    if (parseRefreshDelay(raw) === null) continue;
+    const delay = parseRefreshDelay(raw);
+    if (delay === null) continue;
 
+    // Only the first valid meta refresh in document order is ever acted
+    // on by a browser -- any later one is inert and stops being evaluated
+    // entirely once a winner has been found.
     applicableCount += 1;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
+    if (delay === 0) break; // an immediate redirect is not a timed interruption
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This page uses a meta refresh, which is an automatic context change not initiated by the user.',
-      hint: 'Remove the meta refresh; trigger the redirect/refresh only in response to a user action instead.',
-      i18n: {
-        summaryKey: 'metaRefreshNoExceptions_summary_fail',
-        hintKey: 'metaRefreshNoExceptions_hint_fail',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'META_REFRESH_PRESENT' }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This page uses a meta refresh, which is an automatic context change not initiated by the user.',
+        hint: 'Remove the meta refresh; trigger the redirect/refresh only in response to a user action instead.',
+        i18n: {
+          summaryKey: 'metaRefreshNoExceptions_summary_fail',
+          hintKey: 'metaRefreshNoExceptions_hint_fail',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'META_REFRESH_PRESENT' }
+        }
+      })
+    );
+    break;
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/meta-refresh-timing-absent.js

@@ -9,8 +9,11 @@
  * @standard WCAG 2.2
  * @sc 2.2.1
  * @applicability
- *   Applies to <meta http-equiv="refresh"> elements that carry a non-empty
- *   content attribute with a parseable leading delay value.
+ *   Applies to the first <meta http-equiv="refresh"> element, in document
+ *   order, whose content attribute has a parseable leading delay value.
+ *   Per HTML's shared declarative refresh steps, a document only ever
+ *   acts on its first valid meta refresh; any later one (valid or not)
+ *   is inert markup a browser never processes, so it is not evaluated.
  * @expectation
  *   The delay is 0 (an immediate redirect, which users cannot be caught by
  *   mid-read), or exceeds 20 hours. Any other positive delay refreshes or
@@ -19,13 +22,13 @@
  *   be possible.
  * @implementation-notes
  * - An unparseable content value (no leading numeric delay) is not
- *   flagged — this rule only reports a clearly-detected timed refresh,
+ *   flagged, this rule only reports a clearly-detected timed refresh,
  *   matching this engine's no-false-positives policy.
  * - WCAG 2.2.1 Exception 3 exempts time limits longer than 20 hours (the
  *   rationale being that a delay this long gives users enough real-world
  *   time to act, so "adjustable" ceases to be a meaningful requirement).
  *   A delay over 72000 seconds is therefore not flagged.
- * - A <meta> nested inside <noscript> is excluded — see
+ * - A <meta> nested inside <noscript> is excluded, see
  *   meta-refresh-no-exceptions's header comment for why.
  */
 
@@ -109,35 +112,36 @@ function runInPage(ctx) {
 
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
-    if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled — see meta-refresh-no-exceptions.js's header comment
+    if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled, see meta-refresh-no-exceptions.js's header comment
     const raw = String(el.getAttribute('content') || '').trim();
     if (!raw) continue;
 
     const delay = parseRefreshDelay(raw);
     if (delay === null) continue;
 
+    // Only the first valid meta refresh in document order is ever acted
+    // on by a browser -- any later one is inert and stops being evaluated
+    // entirely once a winner has been found.
     applicableCount += 1;
 
-    if (!(delay > 0)) continue;
-    if (delay > EXEMPT_DELAY_SECONDS) continue; // WCAG 2.2.1 Exception 3 (>20 hours)
-
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This page refreshes itself automatically after a delay.',
-      hint: 'Remove the timed meta refresh, or provide a way for users to turn it off, extend it, or pause it before it triggers.',
-      i18n: {
-        summaryKey: 'metaRefreshTimingAbsent_summary_fail',
-        hintKey: 'metaRefreshTimingAbsent_hint_fail',
-        params: { delay: String(delay) }
-      },
-      data: {
-        details: { reasonCode: 'META_REFRESH_DELAYED', delay }
-      }
-    });
+    if (!(delay > 0)) break;
+    if (delay > EXEMPT_DELAY_SECONDS) break; // WCAG 2.2.1 Exception 3 (>20 hours)
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This page refreshes itself automatically after a delay.',
+        hint: 'Remove the timed meta refresh, or provide a way for users to turn it off, extend it, or pause it before it triggers.',
+        i18n: {
+          summaryKey: 'metaRefreshTimingAbsent_summary_fail',
+          hintKey: 'metaRefreshTimingAbsent_hint_fail',
+          params: { delay: String(delay) }
+        },
+        data: {
+          details: { reasonCode: 'META_REFRESH_DELAYED', delay }
+        }
+      })
+    );
+    break;
   }
 
   if (applicableCount === 0) {