@surea11y/core 1.0.0

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

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * @check embed-text-alternative-quality
+ * @atomic true
+ * @summary Manual review: text alternative appropriateness (WCAG 1.1.1)
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @type manual
+ * @expectation
+ *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
+ */
+
+const id = "embed-text-alternative-quality";
+
+const meta = {
+    title: "<embed> text alternative must be appropriate (manual review)",
+    description: "Flags <embed> elements with a detected name for human review of appropriateness.",
+    i18n: {
+        titleKey: "embed_textAltQuality_title",
+        descriptionKey: "embed_textAltQuality_description"
+    },
+    helpUrl: null,
+    tags: ["wcag2a", "wcag111", "nontext", "embed", "manual", "atomic"],
+    wcagSc: ['1.1.1'],
+    normativeMappings: [
+        {standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A'}
+    ],
+    defaultSeverity: 'minor',
+    category: 'perceivable',
+    type: 'manual',
+    defaultConfidence: 'medium',
+    coverage: {
+        facetsBySc: {
+            '1.1.1': ['text-alternative-quality']
+        }
+    }
+};
+
+function runInPage(ctx) {
+    const {document, root, helpers, rule} = ctx;
+    const safeRoot = root || document;
+
+    const trim = (v) => (v == null ? '' : String(v)).trim();
+    const getTextFromIdRefs =
+        helpers && typeof helpers.getTextFromIdRefs === 'function' ? helpers.getTextFromIdRefs : null;
+
+    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+    const queryAll = helpers && typeof helpers.queryAll === 'function'
+        ? helpers.queryAll
+        : (sel) => {
+            try {
+                return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : [];
+            } catch {
+                return [];
+            }
+        };
+
+    const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+        ? helpers.getEligibilityInfo
+        : null;
+
+    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
+
+    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
+        ? helpers.getFocusableInfo
+        : null;
+
+    function isRolePresentationExcluded(el) {
+        const role = (() => {
+            try {
+                return String(el.getAttribute('role') || '').trim().toLowerCase();
+            } catch {
+                return '';
+            }
+        })();
+        if (role !== 'presentation' && role !== 'none') return false;
+
+        // Exclude only when NOT focusable (mirrors img-alt-present policy)
+        let focusable = false;
+        if (getFocusableInfo) {
+            const fi = (() => {
+                try {
+                    return getFocusableInfo(el, ctx);
+                } catch {
+                    return null;
+                }
+            })();
+            focusable = !!(fi && fi.focusable);
+        } else {
+            const tabindex = el.getAttribute('tabindex');
+            focusable = tabindex != null && String(tabindex).trim() !== '' && !Number.isNaN(Number(String(tabindex).trim()));
+        }
+        return !focusable;
+    }
+
+
+    const els = (() => {
+        try {
+            return Array.from((queryAllSmart ? queryAllSmart('embed') : queryAll('embed')) || []);
+        } catch {
+            return queryAll('embed');
+        }
+    })();
+
+    if (!els.length) {
+        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    }
+
+    const occurrences = [];
+    let applicableCount = 0;
+
+    for (const el of els) {
+        if (!el || !el.getAttribute) continue;
+
+        if (isAccTreeEligible) {
+            const elig = (() => {
+                try {
+                    return isAccTreeEligible(el, ctx);
+                } catch {
+                    return {eligible: true, reasons: []};
+                }
+            })();
+            if (elig && elig.eligible === false) continue;
+        }
+
+        if (isRolePresentationExcluded(el)) continue;
+
+        let ariaLabel = '';
+        let ariaLabelledBy = '';
+        let title = '';
+        try {
+            ariaLabel = trim(el.getAttribute('aria-label'));
+            ariaLabelledBy = trim(el.getAttribute('aria-labelledby'));
+            title = trim(el.getAttribute('title'));
+        } catch {
+            ariaLabel = '';
+            ariaLabelledBy = '';
+            title = '';
+        }
+
+        // Only resolve IDREF text if aria-labelledby is present and aria-label is not already sufficient
+        let labelledByText = '';
+        let hasLabelledByMechanism = false;
+
+        if (!ariaLabel && ariaLabelledBy) {
+            hasLabelledByMechanism = true;
+
+            if (getTextFromIdRefs) {
+                try {
+                    const t = getTextFromIdRefs(ariaLabelledBy, ctx);
+                    labelledByText = trim(t && t.text);
+                    // If it resolves to empty, still treat as a mechanism present for manual review.
+                } catch {
+                    labelledByText = '';
+                }
+            }
+        }
+
+        const hasNameMechanism = !!(ariaLabel || title || hasLabelledByMechanism);
+        if (!hasNameMechanism) continue;
+
+        const details = {
+            ariaLabel: ariaLabel || null,
+            ariaLabelledBy: ariaLabelledBy || null,
+            ariaLabelledByText: labelledByText || null,
+            title: title || null
+        };
+
+        applicableCount += 1;
+
+        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, {targetSet: 'acc'}) : null;
+
+        const baseOccurrence = {
+            summary: 'Review text alternative for <embed> for accuracy and appropriateness.',
+            hint: 'Confirm the ARIA name or title accurately identifies the embedded content in context.',
+            i18n: {
+                summaryKey: 'embed_textAltQuality_summary_cantTell',
+                hintKey: 'embed_textAltQuality_hint_cantTell',
+                params: {element: (el.tagName || '').toLowerCase()}
+            },
+            data: {
+                visibilityFilter: eligInfo || {targetSet: 'acc', accEligible: null, reasons: []},
+                details
+            }
+        };
+
+        if (helpers && typeof helpers.reportOccurrence === 'function') {
+            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+        } else {
+            occurrences.push({selector: '', html: '', ...baseOccurrence});
+        }
+    }
+
+    if (applicableCount === 0) {
+        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    }
+
+    return {ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences};
+}
+
+module.exports = {id, meta, runInPage};

package/src/checks/manual/empty-heading-manual.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * @check empty-heading
+ * @atomic true
+ * @summary Heading elements must not be empty
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to elements with a heading role: native <h1>-<h6>, or any
+ *   element with explicit role="heading" (unless overridden by another
+ *   explicit role).
+ * @expectation
+ *   The heading has a non-empty accessible name: aria-label,
+ *   aria-labelledby, visible text content not hidden from assistive
+ *   technology, or (as a last resort) a title attribute. An empty
+ *   heading is announced as "heading, level N" with nothing else, which
+ *   is confusing when navigating by heading.
+ * @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.
+ * - This is also the reconciliation point for the "heading-name-present"
+ *   gap surfaced by the 2026-07-19 ACT-rules research pass (see
+ *   ROADMAP.md "Tier 5 candidates"): that gap was already closed by this
+ *   pre-existing rule under a different name, not a real gap. Fixed two
+ *   real false-positive bugs found while confirming that (2026-07-19):
+ *   `title` wasn't accepted as a naming fallback, and hidden/aria-hidden/
+ *   display:none headings weren't excluded (not gated on
+ *   `isAccTreeEligible`), so an empty heading no AT user could ever
+ *   reach was still flagged.
+ * - 2026-07-21: the subtree-text walker's own hand-rolled descendant
+ *   handling (aria-label/aria-labelledby only) never checked an `<img>`
+ *   descendant's `alt` text — found via Party City's
+ *   `<h1><a><div><img alt="..."></div></a></h1>` logo header, a false
+ *   "empty heading" cantTell. Replaced with the shared, accname-aligned
+ *   `helpers.getContentNameInfo` (see dom-helpers.js) — the same "name
+ *   from content" implementation the 19 `-name-present` rules already use
+ *   — instead of maintaining a third, narrower copy of this logic here.
+ */
+
+const id = 'empty-heading';
+
+const meta = {
+  title: 'Headings must not be empty',
+  description: 'Checks that heading elements (<h1>-<h6> or role="heading") have a non-empty accessible name.',
+  i18n: {
+    titleKey: 'emptyHeading_title',
+    descriptionKey: 'emptyHeading_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'headings', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function getExplicitRoleToken(el) {
+    const raw = normalizeWs(el.getAttribute && el.getAttribute('role'));
+    if (!raw) return '';
+    return raw.split(/\s+/)[0].toLowerCase();
+  }
+
+  function isHeading(el) {
+    const explicit = getExplicitRoleToken(el);
+    if (explicit) return explicit === 'heading';
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    return /^h[1-6]$/.test(tag);
+  }
+
+  function getAccessibleNameText(el) {
+    const al = normalizeWs(el.getAttribute && el.getAttribute('aria-label'));
+    if (al) return al;
+    const alb = normalizeWs(el.getAttribute && el.getAttribute('aria-labelledby'));
+    if (alb) {
+      const parts = [];
+      for (const refId of alb.split(/\s+/).filter(Boolean)) {
+        try {
+          const ref = document.getElementById(refId);
+          if (ref) {
+            const t = normalizeWs(ref.textContent);
+            if (t) parts.push(t);
+          }
+        } catch {}
+      }
+      const joined = normalizeWs(parts.join(' '));
+      if (joined) return joined;
+    }
+    // Shared, accname-aligned "name from content" implementation (see
+    // dom-helpers.js's getContentNameInfo header comment) — resolves an
+    // <img> descendant's own alt text, an aria-label/aria-labelledby'd
+    // descendant's own name, etc., and already gates every descendant on
+    // full accessibility-tree eligibility (aria-hidden, display:none,
+    // visibility:hidden, [hidden], inert, ...) the same way this rule
+    // needs. Used instead of a fourth hand-rolled subtree walker here.
+    if (helpers && typeof helpers.getContentNameInfo === 'function') {
+      try {
+        const info = helpers.getContentNameInfo(el, ctx);
+        if (info && info.present && info.value) return info.value;
+      } catch {}
+    }
+    return normalizeWs(el.getAttribute && el.getAttribute('title'));
+  }
+
+  let nodes = [];
+  try {
+    nodes = document.querySelectorAll('h1, h2, h3, h4, h5, h6, [role]');
+  } catch {
+    nodes = [];
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+  const seen = new Set();
+
+  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  function isEligible(el) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  for (const el of nodes) {
+    if (!el || seen.has(el)) continue;
+    seen.add(el);
+    if (!isHeading(el)) continue;
+    if (!isEligible(el)) continue;
+
+    applicableCount += 1;
+
+    const name = getAccessibleNameText(el);
+    if (name) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const eligInfo = helpers.getEligibilityInfo
+      ? (() => { try { return helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
+      : null;
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This heading has no accessible name.',
+      hint: 'Add text content (or aria-label/aria-labelledby) to this heading, or remove it if it is not needed.',
+      i18n: {
+        summaryKey: 'emptyHeading_summary_cantTell',
+        hintKey: 'emptyHeading_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'HEADING_EMPTY' },
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/empty-table-header-manual.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * @check empty-table-header
+ * @atomic true
+ * @summary Table header cells must not be empty
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Applies to <th> elements that don't carry a conflicting explicit role,
+ *   plus any element (native <th> or not) with role="columnheader" or
+ *   role="rowheader" — matches a widely-used reference engine's own
+ *   `empty-table-header` selector exactly (`th:not([role]), [role="columnheader"], [role="rowheader"]`,
+ *   verified directly against its rule descriptor): a <th> that explicitly
+ *   restates role="columnheader"/"rowheader" is still covered via the second
+ *   clause, but a <th role="presentation"> (no longer meaningfully a header)
+ *   is correctly excluded, and an ARIA-role-only header (e.g. a <div
+ *   role="columnheader"> in a role="grid"/role="table" widget) is caught too
+ *   — found missing entirely via the cross-engine diff tool 2026-07-23.
+ * @expectation
+ *   The header cell has visible text content. A <th> named only via
+ *   aria-label/aria-labelledby (no visible text) is ALSO flagged, not
+ *   treated as equivalent — real screen-reader/browser testing (found via
+ *   a live-DOM cross-engine run 2026-07-21, verified against
+ *   https://butterpep.com/table-header-naming.html and
+ *   https://html5accessibility.com/stuff/2024/05/22/not-so-short-note-on-aria-label-usage-big-table-edition/)
+ *   confirms aria-label support on <th> is genuinely inconsistent in
+ *   practice: NVDA+Firefox and iOS VoiceOver+Safari ignore it entirely
+ *   (only visible text is announced), JAWS+Chrome/IE11 also only announce
+ *   visible text in the header cell itself. Visible text is the one
+ *   mechanism confirmed to work across every tested combination. A widely-used
+ *   reference engine's own equivalent check (`has-visible-text` only, no aria-label/
+ *   aria-labelledby alternative — confirmed directly against its rule
+ *   descriptor) reaches the same conclusion.
+ * @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.
+ * - Two distinct reasonCodes: TABLE_HEADER_EMPTY (no accessible name at
+ *   all) vs. TABLE_HEADER_NAME_NOT_VISIBLE_TEXT (has aria-label/
+ *   aria-labelledby but no visible text) — the latter gets a different
+ *   summary/hint explaining the AT-support gap, since the header isn't
+ *   literally nameless, just unreliably named in practice.
+ */
+
+const id = 'empty-table-header';
+
+const meta = {
+  title: 'Table header cells must not be empty',
+  description: 'Checks that table header cells (<th>, or any element with role="columnheader"/"rowheader") have visible text content — a header named only via aria-label/aria-labelledby is also flagged, since real screen-reader/browser support for that is inconsistent.',
+  i18n: {
+    titleKey: 'emptyTableHeader_title',
+    descriptionKey: 'emptyTableHeader_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'tables', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function getVisibleText(el) {
+    return normalizeWs(el.textContent);
+  }
+
+  function getAriaOnlyName(el) {
+    const al = normalizeWs(el.getAttribute && el.getAttribute('aria-label'));
+    if (al) return al;
+    const alb = normalizeWs(el.getAttribute && el.getAttribute('aria-labelledby'));
+    if (alb) {
+      const parts = [];
+      for (const refId of alb.split(/\s+/).filter(Boolean)) {
+        try {
+          const ref = document.getElementById(refId);
+          if (ref) {
+            const t = normalizeWs(ref.textContent);
+            if (t) parts.push(t);
+          }
+        } catch {}
+      }
+      const joined = normalizeWs(parts.join(' '));
+      if (joined) return joined;
+    }
+    return '';
+  }
+
+  let nodes = [];
+  try {
+    // Matches a widely-used reference engine's own empty-table-header selector exactly: a <th> with
+    // no conflicting explicit role, plus any element carrying an explicit
+    // columnheader/rowheader role (native or not).
+    nodes = document.querySelectorAll('th:not([role]), [role="columnheader"], [role="rowheader"]');
+  } catch {
+    nodes = [];
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el) continue;
+    applicableCount += 1;
+
+    if (getVisibleText(el)) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    const ariaName = getAriaOnlyName(el);
+    if (ariaName) {
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This table header cell has no visible text — its only accessible name comes from aria-label/aria-labelledby, which real screen-reader/browser combinations (e.g. NVDA+Firefox, iOS VoiceOver+Safari) are known to ignore on <th> elements.',
+        hint: 'Add visible text content to this header cell (in addition to, or instead of, aria-label/aria-labelledby) — visible text is the only naming mechanism confirmed to work across tested screen readers.',
+        i18n: {
+          summaryKey: 'emptyTableHeader_summary_cantTell_ariaOnly',
+          hintKey: 'emptyTableHeader_hint_cantTell_ariaOnly',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'TABLE_HEADER_NAME_NOT_VISIBLE_TEXT', ariaName }
+        }
+      });
+      continue;
+    }
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This table header cell has no accessible name.',
+      hint: 'Add text content (or aria-label/aria-labelledby) to this header cell, or remove it if it is not needed.',
+      i18n: {
+        summaryKey: 'emptyTableHeader_summary_cantTell',
+        hintKey: 'emptyTableHeader_hint_cantTell',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'TABLE_HEADER_EMPTY' }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/focus-order-semantics-manual.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * @check focus-order-semantics
+ * @atomic true
+ * @summary Elements added to the tab order should have interactive semantics
+ * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @applicability
+ *   Elements with an explicit `tabindex` of `0` or greater (in the tab
+ *   order) AND an explicit `role` attribute that is one of a curated set
+ *   of clearly non-interactive, structural/document roles.
+ * @expectation
+ *   An element deliberately placed in the tab order should communicate
+ *   why it's focusable — a role like `heading`, `list`, `region`, or
+ *   `presentation` gives assistive technology no interactive semantic to
+ *   announce, which is confusing for keyboard users who land on it and
+ *   get no indication of what activating it (if anything) would do.
+ * @implementation-notes
+ * - Not WCAG-normative by a widely-used reference engine's own classification — authored as an
+ *   advisory, cantTell-capped `type: 'manual'` rule.
+ * - The non-interactive role list is deliberately curated and
+ *   conservative (structural/document roles only) — legitimate custom
+ *   widget patterns using `tabindex` with a genuinely interactive role
+ *   (`option`, `tab`, `menuitem`, etc.) are never flagged. Elements with
+ *   `tabindex` and NO role at all are also not flagged: native semantics
+ *   or an intentionally generic custom-interactive pattern cannot be
+ *   distinguished from markup alone with the same confidence.
+ */
+
+const id = 'focus-order-semantics';
+
+const meta = {
+  title: 'Elements added to the tab order should have interactive semantics',
+  description: 'Flags elements with tabindex >= 0 whose explicit role is a non-interactive structural/document role (e.g. heading, list, region, presentation), for manual review.',
+  i18n: {
+    titleKey: 'focusOrderSemantics_title',
+    descriptionKey: 'focusOrderSemantics_description'
+  },
+  helpUrl: null,
+  tags: ['best-practice', 'aria', 'structure', 'atomic', 'manual'],
+  wcagSc: [],
+  normativeMappings: [],
+  defaultSeverity: 'minor',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {}
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const NON_INTERACTIVE_ROLES = new Set([
+    'generic', 'group', 'text', 'presentation', 'none', 'img', 'heading',
+    'region', 'article', 'banner', 'contentinfo', 'main', 'navigation',
+    'complementary', 'document', 'note', 'list', 'listitem', 'table',
+    'row', 'cell', 'columnheader', 'rowheader', 'figure', 'term',
+    'definition', 'paragraph', 'caption', 'status', 'alert', 'log', 'tooltip'
+  ]);
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[tabindex][role]', safeRoot) : helpers.queryAll('[tabindex][role]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const tabindexAttr = el.getAttribute('tabindex');
+    const tabindex = Number.parseInt(tabindexAttr, 10);
+    if (!Number.isFinite(tabindex) || tabindex < 0) continue;
+
+    const role = (el.getAttribute('role') || '').trim().toLowerCase();
+    if (!role) continue;
+
+    applicableCount += 1;
+
+    if (!NON_INTERACTIVE_ROLES.has(role)) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    const baseOccurrence = {
+      selector: stableSelector,
+      html,
+      summary: `This element is in the tab order (tabindex="${tabindex}") but has a non-interactive role ("${role}").`,
+      hint: 'Remove tabindex if this element is not meant to be interactive, or use an interactive role that matches its actual behavior.',
+      i18n: {
+        summaryKey: 'focusOrderSemantics_summary_cantTell',
+        hintKey: 'focusOrderSemantics_hint_cantTell',
+        params: { tabindex: String(tabindex), role }
+      },
+      data: {
+        details: { reasonCode: 'TABBABLE_WITH_NON_INTERACTIVE_ROLE', tabindex, role }
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push(baseOccurrence);
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };