@surea11y/core 1.1.2 → 1.2.0

package/src/checks/automatic/aria-prohibited-children.js

@@ -52,12 +52,42 @@
  *   focusability) are static, declarative markup facts with no live-DOM/
  *   hydration risk, unlike e.g. `aria-checked-state-mismatch`'s DOM-
  *   property comparison.
+ * - Fixed 2026-07-30: a roleless-but-focusable descendant's message and
+ *   `data.details.attr` used to always claim "carries tabindex" even when
+ *   the element had no tabindex attribute at all and was only focusable
+ *   natively (e.g. an <a href> link). `helpers.getFocusableInfo`'s
+ *   `mechanism` field ('tabindex' | 'native' | ...) is now used to tell
+ *   the two apart, with a distinct `nativeFocusable` attr/message for the
+ *   native case. Found via a real Angular app: a routerLink <a> inside a
+ *   role="list" was reported as "carries tabindex" though the rendered
+ *   markup had no such attribute.
  * - Recursion stops at the first non-transparent role boundary, same as
  *   that reference engine: a nested container with its own real role (e.g. a
  *   <div role="listbox"> inside a menubar) is evaluated as ITS OWN
  *   owned-role entry against the outer container (and, separately, gets
  *   its own applicability pass as a container in the same rule run) —
  *   its descendants are never misattributed to the outer container.
+ * - Fixed 2026-07-31: child-role resolution used `ariaHelpers.getExplicitRole`
+ *   (explicit role="" attribute only), unlike aria-required-children's
+ *   descendant matching which uses `ariaHelpers.getContainmentRole` (explicit
+ *   role, falling back to the native-tag map — li/tr/td/th/tbody/ul/ol/
+ *   table/select/input[type=radio] — see that helper's own header comment).
+ *   A bare `<li>` with no role="" attribute — the common CSS-reset
+ *   workaround `<ul role="list"><li>...</li></ul>` that getContainmentRole
+ *   exists specifically to handle — was therefore read as roleless here,
+ *   making it structurally transparent: the walk recursed straight through
+ *   the listitem boundary into its subtree and could report a focusable
+ *   descendant several levels down as a disallowed owned child of the list,
+ *   instead of stopping at the (implicit) listitem the way
+ *   aria-required-children already does. Switched to getContainmentRole so
+ *   both rules resolve an owned child's role identically. This is a general
+ *   fix, not list/listitem-specific: it applies to every container role in
+ *   REQUIRED_OWNED_ROLES whose native-tag counterpart the child map covers
+ *   (e.g. a bare `<tr>`/`<td>` under a role="table"/"grid"/"row" container
+ *   with no explicit role="" was subject to the same flattening bug). Found
+ *   via a real Angular Material-style component library: an `<a routerlink>`
+ *   several DOM levels inside a bare `<li>` under `<ul role="list">` was
+ *   reported as an unallowed owned child of the list.
  * - Gated on isAccTreeEligible for the container itself, matching the fix
  *   applied to aria-required-children (see that rule's header): the
  *   original "not gated" note here just cited that rule's reasoning
@@ -151,6 +181,11 @@ function runInPage(ctx) {
   // entry with role: null, which can never satisfy a required-role set)
   // when it carries a global aria-* attribute or is focusable — matches
   // a widely-used reference engine's own getOwnedRoles exactly (see header comment).
+  // kidRole comes from getContainmentRole, not getExplicitRole (see header
+  // comment's 2026-07-31 fix): "roleless" here means neither an explicit
+  // role="" NOR one of the native containment tags (li, tr, td, ...), so a
+  // bare <li>/<tr>/... is a real listitem/row boundary, not a transparent
+  // wrapper the walk should pass through.
   function collectOwnedRoles(el, requiredSet, out, depth) {
     if (depth > MAX_DEPTH) return;
     const kids = el.children ? Array.prototype.slice.call(el.children) : [];
@@ -158,21 +193,27 @@ function runInPage(ctx) {
       if (!kid || kid.nodeType !== 1) continue;
       if (!isEligibleAcc(kid)) continue;
 
-      const kidRole = ariaHelpers.getExplicitRole(kid);
+      const kidRole = ariaHelpers.getContainmentRole(kid);
       const isPresentational = kidRole === 'presentation' || kidRole === 'none';
       const isTransparentGroup = (kidRole === 'group' || kidRole === 'rowgroup') && requiredSet.has(kidRole);
 
       if (!kidRole && !isPresentational) {
         const globalAttr = getGlobalAriaAttr(kid);
-        let focusable = false;
+        let mechanism = 'none';
         try {
           const fi = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo(kid, ctx) : null;
-          focusable = !!(fi && fi.focusable);
+          mechanism = (fi && fi.focusable && fi.mechanism) || 'none';
         } catch {
-          focusable = false;
+          mechanism = 'none';
         }
-        if (globalAttr || focusable) {
-          out.push({ el: kid, role: null, attr: globalAttr || 'tabindex' });
+        if (globalAttr || mechanism !== 'none') {
+          // `mechanism` distinguishes an actual tabindex="" attribute from
+          // native focusability (e.g. <a href>, <button>, <input>) — these
+          // are different facts and must not be reported as the same
+          // "carries tabindex" claim (a native anchor with no tabindex
+          // attribute at all is not "carrying tabindex").
+          const attr = globalAttr || (mechanism === 'tabindex' ? 'tabindex' : 'nativeFocusable');
+          out.push({ el: kid, role: null, attr });
           continue; // real accessible-tree node: stop here, do not recurse further
         }
       }
@@ -219,12 +260,28 @@ function runInPage(ctx) {
       const containerSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
 
       const isRoleless = !entry.role;
-      const summary = isRoleless
-        ? `This element has no explicit role but carries ${entry.attr}, making it a real accessible-tree node that is not an allowed owned child of the enclosing role="${role}" container.`
-        : `This element has role="${entry.role}", which is not an allowed owned child of the enclosing role="${role}" container.`;
-      const hint = isRoleless
-        ? `Remove ${entry.attr} (or the role="${role}" container ownership), or give this element role="presentation"/"none" if it isn't meant to be its own accessible-tree node.`
-        : `Remove or change this role so it matches one of the container's allowed owned roles (${requiredOwned.join(', ')}), or move this element outside the ${role} container.`;
+      const isNativeFocusable = entry.attr === 'nativeFocusable';
+
+      let summary;
+      let hint;
+      let summaryKey;
+      let hintKey;
+      if (isNativeFocusable) {
+        summary = `This element has no explicit role but is natively focusable, making it a real accessible-tree node that is not an allowed owned child of the enclosing role="${role}" container.`;
+        hint = `Give this element role="presentation"/"none", remove its native focusability (e.g. drop the href/tabindex-granting attribute), or move it outside the ${role} container.`;
+        summaryKey = 'ariaProhibitedChildren_summary_fail_native_focusable';
+        hintKey = 'ariaProhibitedChildren_hint_fail_native_focusable';
+      } else if (isRoleless) {
+        summary = `This element has no explicit role but carries ${entry.attr}, making it a real accessible-tree node that is not an allowed owned child of the enclosing role="${role}" container.`;
+        hint = `Remove ${entry.attr} (or the role="${role}" container ownership), or give this element role="presentation"/"none" if it isn't meant to be its own accessible-tree node.`;
+        summaryKey = 'ariaProhibitedChildren_summary_fail_roleless';
+        hintKey = 'ariaProhibitedChildren_hint_fail_roleless';
+      } else {
+        summary = `This element has role="${entry.role}", which is not an allowed owned child of the enclosing role="${role}" container.`;
+        hint = `Remove or change this role so it matches one of the container's allowed owned roles (${requiredOwned.join(', ')}), or move this element outside the ${role} container.`;
+        summaryKey = 'ariaProhibitedChildren_summary_fail';
+        hintKey = 'ariaProhibitedChildren_hint_fail';
+      }
 
       occurrences.push({
         selector: stableSelector,
@@ -232,8 +289,8 @@ function runInPage(ctx) {
         summary,
         hint,
         i18n: {
-          summaryKey: isRoleless ? 'ariaProhibitedChildren_summary_fail_roleless' : 'ariaProhibitedChildren_summary_fail',
-          hintKey: isRoleless ? 'ariaProhibitedChildren_hint_fail_roleless' : 'ariaProhibitedChildren_hint_fail',
+          summaryKey,
+          hintKey,
           params: isRoleless
             ? { attr: entry.attr, containerRole: role }
             : { childRole: entry.role, containerRole: role, allowedRoles: requiredOwned.join(', ') }

package/src/checks/automatic/bypass-blocks-present.js

@@ -67,6 +67,14 @@ const meta = {
   coverage: { facetsBySc: { '2.4.1': ['bypass-blocks-present'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -187,4 +195,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/automatic/css-orientation-lock.js

@@ -73,6 +73,14 @@ const meta = {
   coverage: { facetsBySc: { '1.3.4': ['css-orientation-lock'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -203,4 +211,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/automatic/html-xml-lang-mismatch.js

@@ -45,6 +45,14 @@ const meta = {
   coverage: { facetsBySc: { '3.1.1': ['html-xml-lang-mismatch'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -88,4 +96,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -63,6 +63,14 @@ const meta = {
     }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
     const { document, rule, helpers } = ctx;
     const html = document && document.documentElement;
@@ -156,4 +164,4 @@ function runInPage(ctx) {
     };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -58,6 +58,14 @@ const meta = {
   }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -102,4 +110,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -49,6 +49,14 @@ const meta = {
   coverage: { facetsBySc: { '2.2.1': ['meta-refresh-timing-absent'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -104,4 +112,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

package/src/checks/automatic/meta-viewport-zoom-enabled.js

@@ -42,6 +42,14 @@ const meta = {
   coverage: { facetsBySc: { '1.4.4': ['meta-viewport-zoom-enabled'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -115,4 +123,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -22,6 +22,14 @@ const meta = {
   coverage: { facetsBySc: { '2.4.2': ['page-title-present'] } }
 };
 
+// This check is inherently whole-document (does the PAGE have this
+// property?), not evaluable per-subtree -- notApplicable when contextSelector
+// scoped this run narrower than the whole document, or when
+// engineOptions.fragment:true was set (see helpers.isWholeDocumentScope).
+function applicability(ctx) {
+  return ctx.helpers.isWholeDocumentScope ? ctx.helpers.isWholeDocumentScope() : true;
+}
+
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
@@ -83,4 +91,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -112,12 +112,7 @@ function runInPage(ctx) {
     return normalizeWs(el.getAttribute && el.getAttribute('title'));
   }
 
-  let nodes = [];
-  try {
-    nodes = document.querySelectorAll('h1, h2, h3, h4, h5, h6, [role]');
-  } catch {
-    nodes = [];
-  }
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('h1, h2, h3, h4, h5, h6, [role]') : helpers.queryAll('h1, h2, h3, h4, h5, h6, [role]');
 
   const occurrences = [];
   let applicableCount = 0;

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

@@ -94,15 +94,11 @@ function runInPage(ctx) {
     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 = [];
-  }
+  // 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).
+  const selector = 'th:not([role]), [role="columnheader"], [role="rowheader"]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
   const occurrences = [];
   let applicableCount = 0;

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

@@ -72,12 +72,7 @@ function runInPage(ctx) {
     return m ? parseInt(m[1], 10) : 0;
   }
 
-  let nodes = [];
-  try {
-    nodes = document.querySelectorAll('h1, h2, h3, h4, h5, h6, [role]');
-  } catch {
-    nodes = [];
-  }
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('h1, h2, h3, h4, h5, h6, [role]') : helpers.queryAll('h1, h2, h3, h4, h5, h6, [role]');
 
   const headings = [];
   const seen = new Set();

package/src/checks/manual/landmark-banner-is-top-level-manual.js

@@ -52,7 +52,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { document, root, helpers, rule } = ctx;
 
   // Declared inside runInPage — see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
@@ -81,25 +81,37 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
-  const SECTIONING_ANCESTORS = new Set(['article', 'aside', 'main', 'nav', 'section']);
-
-  function isSuppressedBySectioningAncestor(el) {
-    let p = el.parentElement;
-    while (p) {
-      const tag = p.tagName ? p.tagName.toLowerCase() : '';
-      if (SECTIONING_ANCESTORS.has(tag)) return true;
-      p = p.parentElement;
-    }
-    return false;
+  // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
+  // question "does this element sit inside a sectioning-content/<main>
+  // ancestor that suppresses its conditional implicit role" — 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)
+  // 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.
+  function hasSectioningAncestor(el, includeMain) {
+    return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
+      ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
+      : false;
   }
 
   function getImplicitLandmarkRole(el) {
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    if (tag === 'header') return isSuppressedBySectioningAncestor(el) ? '' : 'banner';
-    if (tag === 'footer') return isSuppressedBySectioningAncestor(el) ? '' : 'contentinfo';
+    if (tag === 'header') return hasSectioningAncestor(el, true) ? '' : 'banner';
+    if (tag === 'footer') return hasSectioningAncestor(el, true) ? '' : 'contentinfo';
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
-    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'aside') {
+      // A named <aside> is never suppressed, even when nested — matches
+      // landmark-unique's own verified-against-reference-engine precedent
+      // (that engine's real `aside` implicit-role function keeps
+      // "complementary" when the element has an accessible name, even
+      // inside sectioning content); propagated here for consistency.
+      if (!hasSectioningAncestor(el, false)) return 'complementary';
+      return getAccessibleLandmarkName(el) ? 'complementary' : '';
+    }
     if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
     if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
     return '';
@@ -115,9 +127,13 @@ function runInPage(ctx) {
   }
 
   function hasLandmarkAncestor(el) {
+    const scopeRoots = Array.isArray(root) ? root : (root ? [root] : []);
     let p = el.parentElement;
     while (p) {
       if (getLandmarkRole(p)) return true;
+      // Don't climb past the scanned scope -- see aria-helpers.js's
+      // hasLandmarkScopingAncestor for the same fix and rationale.
+      if (scopeRoots.includes(p)) break;
       p = p.parentElement;
     }
     return false;

package/src/checks/manual/landmark-contentinfo-is-top-level-manual.js

@@ -43,7 +43,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { document, root, helpers, rule } = ctx;
 
   function normalizeWs(s) {
     return String(s || '').replace(/\s+/g, ' ').trim();
@@ -70,25 +70,37 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
-  const SECTIONING_ANCESTORS = new Set(['article', 'aside', 'main', 'nav', 'section']);
-
-  function isSuppressedBySectioningAncestor(el) {
-    let p = el.parentElement;
-    while (p) {
-      const tag = p.tagName ? p.tagName.toLowerCase() : '';
-      if (SECTIONING_ANCESTORS.has(tag)) return true;
-      p = p.parentElement;
-    }
-    return false;
+  // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
+  // question "does this element sit inside a sectioning-content/<main>
+  // ancestor that suppresses its conditional implicit role" — 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)
+  // 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.
+  function hasSectioningAncestor(el, includeMain) {
+    return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
+      ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
+      : false;
   }
 
   function getImplicitLandmarkRole(el) {
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    if (tag === 'header') return isSuppressedBySectioningAncestor(el) ? '' : 'banner';
-    if (tag === 'footer') return isSuppressedBySectioningAncestor(el) ? '' : 'contentinfo';
+    if (tag === 'header') return hasSectioningAncestor(el, true) ? '' : 'banner';
+    if (tag === 'footer') return hasSectioningAncestor(el, true) ? '' : 'contentinfo';
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
-    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'aside') {
+      // A named <aside> is never suppressed, even when nested — matches
+      // landmark-unique's own verified-against-reference-engine precedent
+      // (that engine's real `aside` implicit-role function keeps
+      // "complementary" when the element has an accessible name, even
+      // inside sectioning content); propagated here for consistency.
+      if (!hasSectioningAncestor(el, false)) return 'complementary';
+      return getAccessibleLandmarkName(el) ? 'complementary' : '';
+    }
     if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
     if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
     return '';
@@ -104,9 +116,13 @@ function runInPage(ctx) {
   }
 
   function hasLandmarkAncestor(el) {
+    const scopeRoots = Array.isArray(root) ? root : (root ? [root] : []);
     let p = el.parentElement;
     while (p) {
       if (getLandmarkRole(p)) return true;
+      // Don't climb past the scanned scope -- see aria-helpers.js's
+      // hasLandmarkScopingAncestor for the same fix and rationale.
+      if (scopeRoots.includes(p)) break;
       p = p.parentElement;
     }
     return false;

package/src/checks/manual/landmark-main-is-top-level-manual.js

@@ -41,7 +41,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { document, root, helpers, rule } = ctx;
 
   function normalizeWs(s) {
     return String(s || '').replace(/\s+/g, ' ').trim();
@@ -68,25 +68,37 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
-  const SECTIONING_ANCESTORS = new Set(['article', 'aside', 'main', 'nav', 'section']);
-
-  function isSuppressedBySectioningAncestor(el) {
-    let p = el.parentElement;
-    while (p) {
-      const tag = p.tagName ? p.tagName.toLowerCase() : '';
-      if (SECTIONING_ANCESTORS.has(tag)) return true;
-      p = p.parentElement;
-    }
-    return false;
+  // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
+  // question "does this element sit inside a sectioning-content/<main>
+  // ancestor that suppresses its conditional implicit role" — 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)
+  // 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.
+  function hasSectioningAncestor(el, includeMain) {
+    return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
+      ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
+      : false;
   }
 
   function getImplicitLandmarkRole(el) {
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    if (tag === 'header') return isSuppressedBySectioningAncestor(el) ? '' : 'banner';
-    if (tag === 'footer') return isSuppressedBySectioningAncestor(el) ? '' : 'contentinfo';
+    if (tag === 'header') return hasSectioningAncestor(el, true) ? '' : 'banner';
+    if (tag === 'footer') return hasSectioningAncestor(el, true) ? '' : 'contentinfo';
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
-    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'aside') {
+      // A named <aside> is never suppressed, even when nested — matches
+      // landmark-unique's own verified-against-reference-engine precedent
+      // (that engine's real `aside` implicit-role function keeps
+      // "complementary" when the element has an accessible name, even
+      // inside sectioning content); propagated here for consistency.
+      if (!hasSectioningAncestor(el, false)) return 'complementary';
+      return getAccessibleLandmarkName(el) ? 'complementary' : '';
+    }
     if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
     if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
     return '';
@@ -102,9 +114,13 @@ function runInPage(ctx) {
   }
 
   function hasLandmarkAncestor(el) {
+    const scopeRoots = Array.isArray(root) ? root : (root ? [root] : []);
     let p = el.parentElement;
     while (p) {
       if (getLandmarkRole(p)) return true;
+      // Don't climb past the scanned scope -- see aria-helpers.js's
+      // hasLandmarkScopingAncestor for the same fix and rationale.
+      if (scopeRoots.includes(p)) break;
       p = p.parentElement;
     }
     return false;

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

@@ -79,25 +79,37 @@ function runInPage(ctx) {
     return raw.split(/\s+/)[0].toLowerCase();
   }
 
-  const SECTIONING_ANCESTORS = new Set(['article', 'aside', 'main', 'nav', 'section']);
-
-  function isSuppressedBySectioningAncestor(el) {
-    let p = el.parentElement;
-    while (p) {
-      const tag = p.tagName ? p.tagName.toLowerCase() : '';
-      if (SECTIONING_ANCESTORS.has(tag)) return true;
-      p = p.parentElement;
-    }
-    return false;
+  // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
+  // question "does this element sit inside a sectioning-content/<main>
+  // ancestor that suppresses its conditional implicit role" — 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)
+  // 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.
+  function hasSectioningAncestor(el, includeMain) {
+    return helpers && typeof helpers.hasLandmarkScopingAncestor === 'function'
+      ? helpers.hasLandmarkScopingAncestor(el, { includeMain })
+      : false;
   }
 
   function getImplicitLandmarkRole(el) {
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
-    if (tag === 'header') return isSuppressedBySectioningAncestor(el) ? '' : 'banner';
-    if (tag === 'footer') return isSuppressedBySectioningAncestor(el) ? '' : 'contentinfo';
+    if (tag === 'header') return hasSectioningAncestor(el, true) ? '' : 'banner';
+    if (tag === 'footer') return hasSectioningAncestor(el, true) ? '' : 'contentinfo';
     if (tag === 'main') return 'main';
     if (tag === 'nav') return 'navigation';
-    if (tag === 'aside') return isSuppressedBySectioningAncestor(el) ? '' : 'complementary';
+    if (tag === 'aside') {
+      // A named <aside> is never suppressed, even when nested — matches
+      // landmark-unique's own verified-against-reference-engine precedent
+      // (that engine's real `aside` implicit-role function keeps
+      // "complementary" when the element has an accessible name, even
+      // inside sectioning content); propagated here for consistency.
+      if (!hasSectioningAncestor(el, false)) return 'complementary';
+      return getAccessibleLandmarkName(el) ? 'complementary' : '';
+    }
     if (tag === 'section') return getAccessibleLandmarkName(el) ? 'region' : '';
     if (tag === 'form') return getAccessibleLandmarkName(el) ? 'form' : '';
     return '';