@surea11y/core 1.1.1 → 1.2.0

package/src/checks/automatic/aria-deprecated-role.js

@@ -45,15 +45,14 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/aria-hidden-body.js

@@ -48,6 +48,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;
 
@@ -84,4 +92,4 @@ function runInPage(ctx) {
   return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'critical', occurrences };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage, applicability };

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

@@ -83,8 +83,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
@@ -104,7 +103,7 @@ function runInPage(ctx) {
 
   const PROHIBITED_NAMING_ATTRS = ['aria-label', 'aria-labelledby'];
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 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
@@ -100,8 +130,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
@@ -152,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) : [];
@@ -159,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
         }
       }
@@ -190,7 +230,7 @@ function runInPage(ctx) {
     }
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -220,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,
@@ -233,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/aria-required-attr.js

@@ -69,8 +69,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
@@ -94,7 +93,7 @@ function runInPage(ctx) {
     return v != null && String(v).trim().toLowerCase() === 'true';
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 0;

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

@@ -80,8 +80,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
@@ -112,7 +111,7 @@ function runInPage(ctx) {
   // ("runInPage MUST be self-contained").
   const CANDIDATE_SELECTOR = '[role], li, option, tr, td, th, thead, tbody, tfoot, ul, ol, table, select, input[type="radio"]';
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/aria-required-parent.js

@@ -66,8 +66,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
@@ -153,7 +152,7 @@ function runInPage(ctx) {
     const idTok = elId && String(elId).trim();
     if (!idTok) return false;
 
-    const owners = helpers.queryAllSmart ? helpers.queryAllSmart('[aria-owns]', safeRoot) : helpers.queryAll('[aria-owns]', safeRoot);
+    const owners = helpers.queryAllSmart ? helpers.queryAllSmart('[aria-owns]') : helpers.queryAll('[aria-owns]');
     for (const owner of owners) {
       if (!owner || !owner.getAttribute) continue;
       const ownsAttr = owner.getAttribute('aria-owns') || '';
@@ -166,7 +165,7 @@ function runInPage(ctx) {
     return false;
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/aria-roles-valid.js

@@ -44,15 +44,14 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]') : helpers.queryAll('[role]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/aria-valid-attr-value.js

@@ -57,15 +57,14 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*', safeRoot) : helpers.queryAll('*', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*') : helpers.queryAll('*');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/aria-valid-attr.js

@@ -46,15 +46,14 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
   if (!ariaHelpers) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*', safeRoot) : helpers.queryAll('*', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*') : helpers.queryAll('*');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/autocomplete-valid.js

@@ -52,8 +52,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   // Declared inside runInPage — see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
@@ -88,7 +87,7 @@ function runInPage(ctx) {
     return FIELD_NAMES.has(remaining[0]);
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('input, select, textarea', safeRoot) : helpers.queryAll('input, select, textarea', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('input, select, textarea') : helpers.queryAll('input, select, textarea');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/avoid-inline-spacing.js

@@ -46,12 +46,11 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const SPACING_PROPS = ['line-height', 'letter-spacing', 'word-spacing'];
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[style]', safeRoot) : helpers.queryAll('[style]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[style]') : helpers.queryAll('[style]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/binary-control-name-present.js

@@ -23,11 +23,10 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
+  const { document, helpers, rule } = ctx;
   const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
       ? helpers.getEligibilityInfo
       : null;
-  const safeRoot = root || document;
 
 
   function normalizeWs(s) {
@@ -159,7 +158,7 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   const selector = 'input[type="checkbox"], input[type="radio"], [role="checkbox"], [role="radio"], [role="switch"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
 
   // Precompute label[for] associations once for speed/determinism.

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

@@ -25,8 +25,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const occurrences = [];
   let applicableCount = 0;
@@ -63,7 +62,7 @@ function runInPage(ctx) {
   }
 
   const selector = 'button, input[type="button"], input[type="submit"], input[type="reset"], [role="button"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
   for (const el of nodes) {
     // isAccTreeEligible returns { eligible, reasons }, not a boolean.
@@ -75,6 +74,7 @@ function runInPage(ctx) {
 
     const tag = (el.tagName || '').toLowerCase();
     const role = el.getAttribute ? el.getAttribute('role') : null;
+    const roleNorm = normalizeWs(role).toLowerCase();
 
     const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
 
@@ -90,7 +90,17 @@ function runInPage(ctx) {
       inputValueName = getInputButtonValueName(el);
     }
 
-    const isContentNameCandidate = tag === 'button' || role === 'button';
+    // A native <button> (or [role="button"]) whose role has been overridden to
+    // one of these roles is no longer semantically a button — per the WAI-ARIA
+    // Accessible Name and Description Computation spec these roles are
+    // name-from-author-only, and their rendered content represents a VALUE,
+    // not a NAME (mirrors axe-core's controlValueRoles, verified against its
+    // source). Found on a real page (Spotify's "sort by" control): a
+    // <button role="combobox">List</button> where "List" is the combobox's
+    // currently selected value, not a label for what the combobox is —
+    // crediting it as the accessible name masked a real missing-name bug.
+    const VALUE_ROLES = ['textbox', 'progressbar', 'scrollbar', 'slider', 'spinbutton', 'combobox', 'listbox'];
+    const isContentNameCandidate = (tag === 'button' || role === 'button') && !VALUE_ROLES.includes(roleNorm);
     const contentName =
       (!trustedProgrammaticName && !inputValueName && isContentNameCandidate)
         ? getConservativeSubtreeText(el)

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;
 
@@ -75,14 +83,43 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  function hasMainLandmark() {
+  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  function isExposedToAt(el) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  function queryAll(selector) {
     try {
-      return !!document.querySelector('main, [role="main"]');
+      return helpers && typeof helpers.queryAllSmart === 'function'
+        ? helpers.queryAllSmart(selector)
+        : document.querySelectorAll(selector);
     } catch {
-      return false;
+      return [];
     }
   }
 
+  // Filters through isAccTreeEligible (hidden/aria-hidden/display:none/inert
+  // don't count as "a bypass mechanism is present") -- see page-has-heading-
+  // one-manual.js's identical fix for the real-world trigger (CDC's flu
+  // page, 2026-07-30: its only <h1> sits inside a display:none ancestor,
+  // unreachable by sighted and screen reader users alike). A fully
+  // non-rendered <main>/heading was previously credited here too, wrongly
+  // returning `pass` for a page with zero actual bypass mechanisms.
+  function hasMainLandmark() {
+    for (const el of queryAll('main, [role="main"]')) {
+      if (el && isExposedToAt(el)) return true;
+    }
+    return false;
+  }
+
   function hasWorkingAnchorLink() {
     let links = [];
     try {
@@ -122,11 +159,10 @@ function runInPage(ctx) {
   }
 
   function hasHeading() {
-    try {
-      return !!document.querySelector('h1, h2, h3, h4, h5, h6, [role="heading"]');
-    } catch {
-      return false;
+    for (const el of queryAll('h1, h2, h3, h4, h5, h6, [role="heading"]')) {
+      if (el && isExposedToAt(el)) return true;
     }
+    return false;
   }
 
   const mainLandmark = hasMainLandmark();
@@ -159,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/combobox-name-present.js

@@ -23,11 +23,10 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
+  const { document, helpers, rule } = ctx;
   const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
       ? helpers.getEligibilityInfo
       : null;
-  const safeRoot = root || document;
 
 
   function normalizeWs(s) {
@@ -159,7 +158,7 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   const selector = '[role="combobox"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
   // Precompute label[for] map for combobox elements that are labelable
   // native form controls (e.g. <input role="combobox">).

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/definition-list-children-valid.js

@@ -54,14 +54,13 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   // Declared inside runInPage — see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const PASSTHROUGH_TAGS = new Set(['dt', 'dd', 'script', 'template', 'style']);
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('dl', safeRoot) : helpers.queryAll('dl', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('dl') : helpers.queryAll('dl');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/deprecated-elements-not-used.js

@@ -48,10 +48,9 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('blink, marquee', safeRoot) : helpers.queryAll('blink, marquee', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('blink, marquee') : helpers.queryAll('blink, marquee');
 
   const occurrences = [];
   let applicableCount = 0;

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

@@ -23,11 +23,10 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
+  const { document, helpers, rule } = ctx;
   const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
       ? helpers.getEligibilityInfo
       : null;
-  const safeRoot = root || document;
 
 
   function normalizeWs(s) {
@@ -141,7 +140,7 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   const selector = '[role="dialog"],[role="alertdialog"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
 
   function evaluate(el) {

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

@@ -42,10 +42,9 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('dt, dd', safeRoot) : helpers.queryAll('dt, dd', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('dt, dd') : helpers.queryAll('dt, dd');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/automatic/form-control-single-label.js

@@ -46,11 +46,10 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const selector = 'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
   // Build a for-value -> label[] map once (avoids per-control dynamic
   // attribute-selector construction / CSS.escape, which is not guaranteed