@surea11y/core 1.5.0 → 1.7.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,10 +126,16 @@ 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;
 
+    if (delay === 0) break; // an immediate redirect is not a timed interruption
+
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary:
@@ -141,6 +151,7 @@ function runInPage(ctx) {
         }
       })
     );
+    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,17 +112,20 @@ 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)
+    if (!(delay > 0)) break;
+    if (delay > EXEMPT_DELAY_SECONDS) break; // WCAG 2.2.1 Exception 3 (>20 hours)
 
     occurrences.push(
       helpers.reportOccurrence(el, {
@@ -135,6 +141,7 @@ function runInPage(ctx) {
         }
       })
     );
+    break;
   }
 
   if (applicableCount === 0) {

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check meter-name-present
+ * @atomic true
+ * @summary Elements with role="meter" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to elements carrying role="meter" (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="meter" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom meter widget is not reliably
+ *   exposed as its name.
+ */
+
 const id = 'meter-name-present';
 
 const meta = {
@@ -54,7 +73,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).
@@ -106,8 +125,8 @@ function runInPage(ctx) {
     if (title) return { ok: true, method: 'title' };
 
     // role="meter" is name-from-author-only per WAI-ARIA: aria-label,
-    // aria-labelledby, or title — no content-based naming method at all.
-    // It must NOT fall back to subtree content — visible text near/inside a
+    // aria-labelledby, or title, no content-based naming method at all.
+    // It must NOT fall back to subtree content, visible text near/inside a
     // custom meter widget is not reliably exposed as its accessible name.
     return { ok: false, method: 'none' };
   }
@@ -137,7 +156,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This meter has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this meter's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this meter's accessible name.",
         i18n: {
           summaryKey: 'meterNamePresent_summary_fail',
           hintKey: 'meterNamePresent_hint_fail',

package/src/checks/automatic/nested-interactive-controls-absent.js

@@ -14,13 +14,13 @@
  *   ARIA widget role: button, link, checkbox, radio, switch, tab, textbox,
  *   combobox, listbox, menuitem, menuitemcheckbox, menuitemradio, option,
  *   slider, spinbutton, searchbox, treeitem). The container is applicable
- *   regardless of whether it is itself focusable — focusability is only
+ *   regardless of whether it is itself focusable, focusability is only
  *   used to decide whether a *descendant* nests an interactive control.
  * @expectation
  *   The element does not contain, as a descendant, another *operable*
  *   interactive control (e.g. a <button> wrapping a <select>, or a link
  *   containing a checkbox). Nested interactive controls are not reliably
- *   announced or operable via assistive technology — activating the outer
+ *   announced or operable via assistive technology, activating the outer
  *   control and the inner one become ambiguous, and some AT only exposes
  *   one of the two.
  * @implementation-notes
@@ -89,7 +89,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 INTERACTIVE_SELECTOR = [
     'a[href]',
@@ -228,8 +228,8 @@ function runInPage(ctx) {
         // A composite-owned child (option in a listbox/combobox, tab in a
         // tablist, ...) is not a nested interactive control: its container
         // owns it and drives its focus (roving tabindex or
-        // aria-activedescendant). Treat it as an attribution boundary — do not
-        // count it, and do not descend past it. Any control genuinely nested
+        // aria-activedescendant). Treat it as an attribution boundary, do not
+        // count it, and do not descend past it. Any control nested
         // inside it is attributed to the child itself (examined as its own
         // container in the main loop), keeping the report at the nearest
         // interactive ancestor rather than bubbling up to the composite.

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

@@ -2,11 +2,30 @@
 
 'use strict';
 
+/**
+ * @check option-name-present
+ * @atomic true
+ * @summary Elements with role="option" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="option" (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, from title, or,
+ *   role="option" 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 = 'option-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Options have an accessible name',
+  description: 'Checks that elements with role="option" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'optionNamePresent_title',
     descriptionKey: 'optionNamePresent_description'
@@ -51,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
@@ -70,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).

package/src/checks/automatic/page-title-present.js

@@ -2,11 +2,29 @@
 
 'use strict';
 
+/**
+ * @check page-title-present
+ * @atomic true
+ * @summary The document must have a non-empty title
+ * @standard WCAG 2.2
+ * @sc 2.4.2
+ * @applicability
+ *   Applies to a run over a whole document. A run narrowed by
+ *   contextSelector, or by engineOptions.fragment, is notApplicable: whether
+ *   the page has a title is not a property any subtree can answer.
+ * @expectation
+ *   The document has a <title> element, and document.title with whitespace
+ *   collapsed is non-empty. The element is looked for anywhere in the
+ *   document, not only inside <head>: a <title> the parser leaves outside
+ *   <head> is still the document title in every browser. Whether that title
+ *   describes the page is page-title-patterns' question.
+ */
+
 const id = 'page-title-present';
 
 const meta = {
-  title: 'Page title is present and non-empty',
-  description: 'Checks that the document has a non-empty <title> element (WCAG 2.2 SC 2.4.2).',
+  title: 'Page has a non-empty title',
+  description: 'Checks that the page includes a non-empty <title> element.',
   i18n: {
     titleKey: 'pageTitlePresent_title',
     descriptionKey: 'pageTitlePresent_description'
@@ -47,7 +65,7 @@ function runInPage(ctx) {
   // Not restricted to `head > title`: per HTML parsing, a <title> encountered
   // after <head> has closed is not re-parented into <head>, yet the browser
   // (and document.title, used below) still recognizes it as the document's
-  // title — matching that here avoids a false "missing title" report for a
+  // title, matching that here avoids a false "missing title" report for a
   // <title> that legitimately ended up outside <head>.
   const titleEl = document.querySelector('title');
   const titleText = (document.title || '').replace(/\s+/g, ' ').trim();

package/src/checks/automatic/presentational-children-focusable-absent.js

@@ -0,0 +1,330 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check presentational-children-focusable-absent
+ * @atomic true
+ * @summary A role whose children are presentational must not contain content in sequential focus navigation
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements whose semantic role is one of the WAI-ARIA roles
+ *   defined as having presentational children (button, checkbox, img,
+ *   menuitemcheckbox, menuitemradio, meter, option, progressbar, radio,
+ *   scrollbar, separator, slider, switch, tab, plus doc-pagebreak and
+ *   graphics-symbol from the DPUB-ARIA/Graphics-ARIA modules, which
+ *   inherit the same trait). The role can be explicit (role="tab") or
+ *   native (<button>, <meter>, <progress>, <option>).
+ * @expectation
+ *   No descendant of the element is part of sequential focus navigation.
+ *   The presentational-children mechanism removes every descendant from
+ *   the accessibility tree, so a descendant that still takes a tab stop
+ *   receives focus with no role and no name to announce.
+ * @implementation-notes
+ * - "Presentational children" is the implicit, role-driven mechanism from
+ *   WAI-ARIA §5.2.7, NOT an explicit role="presentation"/"none" attribute.
+ *   An element carrying that attribute has a semantic role of
+ *   presentation/none, which is not in the list above, so it is out of
+ *   scope here (presentation-role-conflict covers that case).
+ * - Only tab stops count, not everything focusable: a descendant with
+ *   tabindex="-1" is programmatically focusable but is not part of
+ *   sequential focus navigation, so it takes no tab stop and is not
+ *   reported. helpers.getFocusableInfo's `tabbable` flag is exactly this
+ *   distinction, and also accounts for :disabled, inert and invalid
+ *   tabindex values.
+ * - Native tags are mapped only where the element can actually have
+ *   descendants: <input type="checkbox">, <img> and <hr> also carry a
+ *   presentational-children role, but they are void, so no descendant can
+ *   ever exist to report. Including them would only inflate the applicable
+ *   count.
+ * - The walk stops at each reported tab stop, and at a nested element that
+ *   has a presentational-children role of its own without being a tab stop,
+ *   that one owns whatever is inside it, and is examined as its own
+ *   container. A tab stop therefore lands on the nearest role that dropped
+ *   it from the accessibility tree, the element an author would fix, rather
+ *   than on every enclosing one. A nested role that IS a tab stop
+ *   (role="button" tabindex="0" inside a <button>) is reported here: focus
+ *   lands inside this element.
+ * - Anything inside an aria-hidden="true" subtree is left to
+ *   aria-hidden-focus, which reports that exact defect (a tab stop with no
+ *   accessibility-tree node) as its own normative decision. Non-rendered
+ *   descendants (display:none, hidden, visibility:hidden) take no tab stop
+ *   at all and are skipped.
+ * - Browsers implement presentational children inconsistently, some
+ *   expose the descendants anyway, especially when they are focusable, so
+ *   the announced result varies by browser. The markup contradiction is
+ *   the same in every one of them, which is what this rule reports.
+ */
+
+const id = 'presentational-children-focusable-absent';
+
+const meta = {
+  title: 'Roles with presentational children must not contain focusable content',
+  description:
+    'Checks that an element whose role makes its children presentational (button, checkbox, img, option, radio, slider, switch, tab, ...) contains no descendant that takes a tab stop.',
+  i18n: {
+    titleKey: 'presentationalChildrenFocusableAbsent_title',
+    descriptionKey: 'presentationalChildrenFocusableAbsent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'focus', 'atomic', 'automatic'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['presentational-children-focusable-absent'] } }
+};
+
+function runInPage(ctx) {
+  const { helpers, rule } = ctx;
+
+  // Declared inside runInPage, see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  //
+  // WAI-ARIA roles with "Children Presentational: True", plus the two
+  // module roles that inherit the trait (doc-pagebreak from DPUB-ARIA,
+  // graphics-symbol from Graphics-ARIA).
+  const PRESENTATIONAL_CHILDREN_ROLES = [
+    'button',
+    'checkbox',
+    'doc-pagebreak',
+    'graphics-symbol',
+    'img',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'meter',
+    'option',
+    'progressbar',
+    'radio',
+    'scrollbar',
+    'separator',
+    'slider',
+    'switch',
+    'tab'
+  ];
+
+  // Native tags whose implicit role is in the set above and that can hold
+  // descendants, see the void-element note in the header comment.
+  const NATIVE_ROLE_BY_TAG = {
+    button: 'button',
+    meter: 'meter',
+    option: 'option',
+    progress: 'progressbar'
+  };
+
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+
+  const isDomVisibleEligible =
+    helpers && typeof helpers.isDomVisibleEligible === 'function'
+      ? helpers.isDomVisibleEligible
+      : null;
+
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  const roleSet = new Set(PRESENTATIONAL_CHILDREN_ROLES);
+
+  function lower(v) {
+    return (v == null ? '' : String(v)).trim().toLowerCase();
+  }
+
+  // The role attribute holds a fallback list; the first token that names a
+  // real role wins. A role="tab" resolves here, a role="figure tab" does
+  // not (figure wins and has no presentational children), and a list of
+  // nothing but unknown tokens falls back to the native role.
+  function getPresentationalChildrenRole(el) {
+    const raw = el.getAttribute ? el.getAttribute('role') : null;
+    if (raw) {
+      const tokens = lower(raw).split(/\s+/);
+      for (const token of tokens) {
+        if (!token) continue;
+        if (roleSet.has(token)) return token;
+        const known = ariaHelpers ? ariaHelpers.isValidConcreteRole(token) : true;
+        if (known) return '';
+      }
+    }
+    const tag = lower(el.tagName);
+    return Object.prototype.hasOwnProperty.call(NATIVE_ROLE_BY_TAG, tag)
+      ? NATIVE_ROLE_BY_TAG[tag]
+      : '';
+  }
+
+  function isExposed(node) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(node, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  // Flat-tree ancestor walk, shared with every other rule via
+  // ctx.helpers.composedParent so a shadow host is crossed the same way here
+  // as elsewhere.
+  const composedParent =
+    helpers && typeof helpers.composedParent === 'function'
+      ? helpers.composedParent
+      : function (n) {
+          return n && n.parentElement ? n.parentElement : null;
+        };
+
+  // isAccTreeEligible keeps an aria-hidden element that holds
+  // tabbable content in the accessibility tree (reason
+  // "ariaHiddenOverriddenTabbable", modelling the browsers that expose it
+  // anyway), which is precisely the shape aria-hidden-focus owns, so the
+  // attribute is checked on its own here rather than read off eligibility.
+  function inAriaHiddenSubtree(node) {
+    let cur = node;
+    let guard = 0;
+    while (cur && guard++ < 200) {
+      if (lower(cur.getAttribute && cur.getAttribute('aria-hidden')) === 'true') return true;
+      cur = composedParent(cur);
+    }
+    return false;
+  }
+
+  function isRendered(node) {
+    if (!isDomVisibleEligible) return true;
+    try {
+      const vis = isDomVisibleEligible(node, ctx, {
+        visibilityMode: 'styleOnly',
+        disableGeometry: true
+      });
+      return !(vis && vis.eligible === false);
+    } catch {
+      return true;
+    }
+  }
+
+  function isTabStop(node) {
+    if (!getFocusableInfo) return false;
+    try {
+      const info = getFocusableInfo(node, ctx);
+      return !!(info && info.tabbable);
+    } catch {
+      return false;
+    }
+  }
+
+  // Shallowest tab stops inside `root`, stopping at each one and at any
+  // nested presentational-children role, so every tab stop is attributed to
+  // the nearest role that removes it from the accessibility tree.
+  function collectTabStops(root) {
+    const out = [];
+    const top = root && root.children;
+    if (!top || !top.length) return out;
+    const stack = [];
+    for (let i = top.length - 1; i >= 0; i--) stack.push(top[i]);
+    while (stack.length) {
+      const node = stack.pop();
+      if (!node || node.nodeType !== 1) continue;
+      if (lower(node.getAttribute && node.getAttribute('aria-hidden')) === 'true') continue;
+      if (!isRendered(node)) continue;
+      if (isTabStop(node)) {
+        out.push(node);
+        continue;
+      }
+      // A nested role with presentational children owns whatever tab stops
+      // are inside it (it is examined as its own container in the main
+      // loop). It is only a boundary when it is not itself a tab stop,
+      // a focusable one lands focus inside THIS element and belongs here.
+      if (getPresentationalChildrenRole(node)) continue;
+      const kids = node.children;
+      if (kids && kids.length) {
+        for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+      }
+    }
+    return out;
+  }
+
+  const SELECTOR = '[role], button, meter, option, progress';
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(SELECTOR)
+    : helpers.queryAll(SELECTOR);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || el.nodeType !== 1) continue;
+
+    const role = getPresentationalChildrenRole(el);
+    if (!role) continue;
+    // A container that is hidden, or sits in an aria-hidden subtree, is
+    // aria-hidden-focus's concern, see the note on inAriaHiddenSubtree.
+    if (!isExposed(el) || inAriaHiddenSubtree(el)) continue;
+
+    applicableCount += 1;
+
+    const tabStops = collectTabStops(el);
+    if (!tabStops.length) continue;
+
+    const tabStopTags = tabStops.map((n) => (n && n.tagName ? lower(n.tagName) : 'unknown'));
+    const dedupedTabStopTags = [...new Set(tabStopTags)];
+
+    const eligInfo = getEligibilityInfo
+      ? (() => {
+          try {
+            return getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
+      : null;
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This role="${role}" element makes its children presentational, but it contains content that is still part of sequential focus navigation (${dedupedTabStopTags.join(', ')}).`,
+        hint: 'Move the focusable content outside this element, or remove the role that makes the children presentational, since focus landing inside it has no role or name to announce.',
+        i18n: {
+          summaryKey: 'presentationalChildrenFocusableAbsent_summary_fail',
+          hintKey: 'presentationalChildrenFocusableAbsent_hint_fail',
+          params: { role, focusableElements: dedupedTabStopTags.join(', ') }
+        },
+        data: {
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: {
+            reasonCode: 'PRESENTATIONAL_CHILDREN_FOCUSABLE_CONTENT',
+            role,
+            element: lower(el.tagName),
+            focusableElements: tabStopTags
+          }
+        }
+      })
+    );
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'serious',
+      occurrences
+    };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };