@surea11y/core 1.1.0 → 1.1.2

package/src/checks/automatic/treeitem-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) {
@@ -91,7 +90,7 @@ function runInPage(ctx) {
   let applicableCount = 0;
 
   const selector = "[role=\"treeitem\"]";
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
 
   function hasName(el) {

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

@@ -47,12 +47,11 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const BCP47_RE = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[lang]', safeRoot) : helpers.queryAll('[lang]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[lang]') : helpers.queryAll('[lang]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/accesskeys-manual.js

@@ -41,13 +41,7 @@ const meta = {
 
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
-
-  let nodes = [];
-  try {
-    nodes = document.querySelectorAll('[accesskey]');
-  } catch {
-    nodes = [];
-  }
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[accesskey]') : helpers.queryAll('[accesskey]');
 
   const groups = new Map(); // normalized key -> elements[]
   for (const el of nodes) {

package/src/checks/manual/aria-checked-state-mismatch-manual.js

@@ -42,8 +42,10 @@
  * - Any `aria-checked` value other than "true"/"false"/"mixed" (checkbox)
  *   or "true"/"false" (radio) is treated as equivalent to "false" — also
  *   matches that reference engine's own normalization exactly.
- * - Not gated on isAccTreeEligible: whether the accessible state matches
- *   is a markup-correctness property independent of current visibility.
+ * - Not rule-gated on isAccTreeEligible: whether the accessible state
+ *   matches is still a markup-correctness property, while engine-level
+ *   hidden-subtree filtering applies unless engineOptions.includeHiddenElements
+ *   is true.
  */
 
 const id = 'aria-checked-state-mismatch';
@@ -69,14 +71,13 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   function trim(v) { return (v == null ? '' : String(v)).trim(); }
 
   const nodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('input[type="checkbox"][aria-checked], input[type="radio"][aria-checked]', safeRoot)
-    : helpers.queryAll('input[type="checkbox"][aria-checked], input[type="radio"][aria-checked]', safeRoot);
+    ? helpers.queryAllSmart('input[type="checkbox"][aria-checked], input[type="radio"][aria-checked]')
+    : helpers.queryAll('input[type="checkbox"][aria-checked], input[type="radio"][aria-checked]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/aria-text-manual.js

@@ -46,13 +46,12 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const FOCUSABLE_DESCENDANT_SELECTOR =
     'a[href], button, input, select, textarea, [tabindex], iframe, [contenteditable]:not([contenteditable="false"])';
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role="text"]', safeRoot) : helpers.queryAll('[role="text"]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role="text"]') : helpers.queryAll('[role="text"]');
 
   const occurrences = [];
   let applicableCount = 0;

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

@@ -48,8 +48,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const NON_INTERACTIVE_ROLES = new Set([
     'generic', 'group', 'text', 'presentation', 'none', 'img', 'heading',
@@ -59,7 +58,7 @@ function runInPage(ctx) {
     'definition', 'paragraph', 'caption', 'status', 'alert', 'log', 'tooltip'
   ]);
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[tabindex][role]', safeRoot) : helpers.queryAll('[tabindex][role]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[tabindex][role]') : helpers.queryAll('[tabindex][role]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/identical-links-same-purpose-manual.js

@@ -52,14 +52,13 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   function normName(s) {
     return (s == null ? '' : String(s)).replace(/\s+/g, ' ').trim().toLowerCase();
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('a[href]', safeRoot) : helpers.queryAll('a[href]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('a[href]') : helpers.queryAll('a[href]');
 
   const groups = new Map(); // normName -> [{ el, href }]
   let applicableCount = 0;

package/src/checks/manual/image-redundant-alt-manual.js

@@ -47,8 +47,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   function normalizeWs(s) {
     return String(s || '').replace(/\s+/g, ' ').trim();
@@ -67,7 +66,7 @@ function runInPage(ctx) {
     return normalizeWs(text);
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('img[alt]', safeRoot) : helpers.queryAll('img[alt]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('img[alt]') : helpers.queryAll('img[alt]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/label-title-only-manual.js

@@ -45,11 +45,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);
 
   const labelsByFor = new Map();
   const allLabels = document.getElementsByTagName ? document.getElementsByTagName('label') : [];

package/src/checks/manual/link-name-quality-manual.js

@@ -60,8 +60,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const GENERIC_LINK_TEXT = new Set([
     'click here', 'here', 'click', 'more', 'more info', 'more information',
@@ -80,7 +79,7 @@ function runInPage(ctx) {
   }
 
   const selector = 'a[href]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/mouse-only-event-handlers-manual.js

@@ -67,8 +67,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const MOUSE_ONLY_ATTRS = [
     'onmouseover', 'onmouseout', 'onmousedown', 'onmouseup',
@@ -79,7 +78,7 @@ function runInPage(ctx) {
   function trim(v) { return (v == null ? '' : String(v)).trim(); }
 
   const selector = MOUSE_ONLY_ATTRS.map((a) => `[${a}]`).join(', ');
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/no-autoplay-audio-manual.js

@@ -58,10 +58,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('audio[autoplay], video[autoplay]', safeRoot) : helpers.queryAll('audio[autoplay], video[autoplay]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('audio[autoplay], video[autoplay]') : helpers.queryAll('audio[autoplay], video[autoplay]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/p-as-heading-manual.js

@@ -53,8 +53,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   const MAX_HEADING_LIKE_CHARS = 120;
   const MIN_FONT_SIZE_PX = 18;
@@ -106,7 +105,7 @@ function runInPage(ctx) {
     return Number.isFinite(px) ? px : 0;
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('p', safeRoot) : helpers.queryAll('p', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('p') : helpers.queryAll('p');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/page-has-heading-one-manual.js

@@ -19,6 +19,18 @@
  * - 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.
+ * - Filters candidates through `isAccTreeEligible` (hidden/aria-hidden/
+ *   display:none/inert elements don't count as "the page has a heading
+ *   one"), matching `landmark-one-main`'s own precedent. Found via a real
+ *   page (CDC's flu page, 2026-07-30): its only `<h1>` sits inside a
+ *   `display:none` ancestor — genuinely unreachable by sighted and screen
+ *   reader users alike — and a raw `document.querySelectorAll` credited it
+ *   anyway, reporting `notApplicable` where axe-core correctly fails. This
+ *   does NOT regress purely-visually-clipped-but-AT-exposed headings (e.g.
+ *   eBay's homepage `<h1>` hidden via clip-path/off-screen positioning,
+ *   `visibility:visible`, no `aria-hidden`) — `isAccTreeEligible` only
+ *   excludes elements actually removed from the accessibility tree, not
+ *   ones merely clipped from the visual viewport.
  */
 
 const id = 'page-has-heading-one';
@@ -70,14 +82,31 @@ function runInPage(ctx) {
     return tag === 'h1';
   }
 
+  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;
+    }
+  }
+
+  // queryAllSmart (shadow-DOM-aware) instead of plain document.querySelectorAll -- see
+  // landmark-one-main-manual.js's identical precedent.
   let nodes = [];
   try {
-    nodes = document.querySelectorAll('h1, [role]');
+    nodes = helpers && typeof helpers.queryAllSmart === 'function'
+      ? helpers.queryAllSmart('h1, [role]')
+      : document.querySelectorAll('h1, [role]');
   } catch {
     nodes = [];
   }
 
-  const hasH1 = Array.from(nodes).some((el) => el && isLevelOneHeading(el));
+  const hasH1 = Array.from(nodes).some((el) => el && isLevelOneHeading(el) && isExposedToAt(el));
 
   if (hasH1) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };

package/src/checks/manual/presentation-role-conflict-manual.js

@@ -73,8 +73,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   // The full set of ARIA attributes marked `global: true` per the WAI-ARIA
   // spec (confirmed against a widely-used reference engine's own
@@ -91,8 +90,8 @@ function runInPage(ctx) {
   const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
   const nodes = helpers.queryAllSmart
-      ? helpers.queryAllSmart('[role="presentation"], [role="none"], img[alt=""]', safeRoot)
-      : helpers.queryAll('[role="presentation"], [role="none"], img[alt=""]', safeRoot);
+      ? helpers.queryAllSmart('[role="presentation"], [role="none"], img[alt=""]')
+      : helpers.queryAll('[role="presentation"], [role="none"], img[alt=""]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/scrollable-region-focusable-manual.js

@@ -64,8 +64,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   function safeComputedStyle(el) {
     try {
@@ -110,7 +109,7 @@ function runInPage(ctx) {
   }
 
   const CANDIDATE_SELECTOR = 'div, section, article, aside, main, nav, pre, table, blockquote, ul, ol, textarea';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(CANDIDATE_SELECTOR, safeRoot) : helpers.queryAll(CANDIDATE_SELECTOR, safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(CANDIDATE_SELECTOR) : helpers.queryAll(CANDIDATE_SELECTOR);
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/skip-link-manual.js

@@ -3,7 +3,7 @@
 /**
  * @check skip-link
  * @atomic true
- * @summary A "skip" link must resolve to a real, focusable target
+ * @summary A "skip" link must resolve to a real, usable target
  * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies to <a href="#fragment"> elements whose accessible name
@@ -18,8 +18,11 @@
  *   implementation-notes) — this only widens the known-convention list.
  * @expectation
  *   The link's fragment resolves to a real element in the document
- *   (via a matching id, or a legacy <a name="...">). A skip link whose
- *   target does not exist silently does nothing when activated.
+ *   (via a matching id, or a legacy <a name="...">), and that target is
+ *   currently usable (not hidden from the accessibility tree; and, when
+ *   browser geometry is available, not zero-area/no-rects). A skip link
+ *   whose target is missing or effectively unusable does not provide a
+ *   reliable bypass destination.
  * @implementation-notes
  * - Not WCAG-normative — authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
@@ -33,8 +36,8 @@
 const id = 'skip-link';
 
 const meta = {
-  title: 'Skip link must have a resolvable target',
-  description: 'Checks that a "skip to ..." link\'s href fragment resolves to a real element in the document.',
+  title: 'Skip link must have a resolvable, usable target',
+  description: 'Checks that a "skip to ..." link\'s href fragment resolves to a real, currently usable element in the document.',
   i18n: {
     titleKey: 'skipLink_title',
     descriptionKey: 'skipLink_description'
@@ -51,8 +54,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   function normalizeWs(s) {
     return String(s || '').replace(/\s+/g, ' ').trim();
@@ -79,7 +81,31 @@ function runInPage(ctx) {
     return normalizeWs(el.textContent);
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('a[href]', safeRoot) : helpers.queryAll('a[href]', safeRoot);
+  function hasReliableGeometrySupport() {
+    const probe = document.documentElement || document.body || null;
+    if (!probe || !probe.getClientRects || !probe.getBoundingClientRect) return false;
+    try {
+      const rects = probe.getClientRects();
+      const rectCount = rects ? rects.length : 0;
+      const r = probe.getBoundingClientRect();
+      const w = r && Number.isFinite(r.width) ? r.width : 0;
+      const h = r && Number.isFinite(r.height) ? r.height : 0;
+      return rectCount > 0 && (w > 0 || h > 0);
+    } catch {
+      return false;
+    }
+  }
+
+  function toEligibility(info) {
+    return {
+      eligible: !!(info && info.eligible),
+      reasons: info && Array.isArray(info.reasons) ? info.reasons.slice(0) : []
+    };
+  }
+
+  const geometrySupported = hasReliableGeometrySupport();
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('a[href]') : helpers.queryAll('a[href]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -117,7 +143,63 @@ function runInPage(ctx) {
       }
     }
 
-    if (target) continue;
+    if (target) {
+      const accEligibility = toEligibility(
+        helpers.getEligibilityInfo
+          ? helpers.getEligibilityInfo(target, ctx, { targetSet: 'acc' })
+          : (helpers.isAccTreeEligible ? helpers.isAccTreeEligible(target, ctx) : { eligible: true, reasons: [] })
+      );
+
+      let geometryEligibility = null;
+      let geometryReasonCode = null;
+      if (geometrySupported && helpers.isDomVisibleEligible) {
+        geometryEligibility = toEligibility(
+          helpers.isDomVisibleEligible(target, ctx, { visibilityMode: 'styleAndGeometry', ignoreOpacity: true })
+        );
+        if (!geometryEligibility.eligible && geometryEligibility.reasons.includes('noClientRects')) {
+          geometryReasonCode = 'NO_CLIENT_RECTS';
+        } else if (!geometryEligibility.eligible && geometryEligibility.reasons.includes('zeroArea')) {
+          geometryReasonCode = 'ZERO_AREA_TARGET';
+        }
+      }
+
+      const unusableByAcc = !accEligibility.eligible;
+      const unusableByGeometry = !!geometryReasonCode;
+      if (!unusableByAcc && !unusableByGeometry) continue;
+
+      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This skip link points to a target that exists but is not currently usable.',
+        hint: 'Point this skip link to a target that is exposed and usable as a navigation destination.',
+        i18n: {
+          summaryKey: 'skipLink_summary_unusableTarget_cantTell',
+          hintKey: 'skipLink_hint_unusableTarget_cantTell',
+          params: { href }
+        },
+        data: {
+          details: {
+            reasonCode: 'SKIP_LINK_TARGET_UNUSABLE',
+            href,
+            unusableReasonCode: unusableByAcc ? 'ACC_TREE_INELIGIBLE' : geometryReasonCode,
+            targetSelector: helpers.buildSelector ? helpers.buildSelector(target) : null,
+            geometryCheckEnabled: geometrySupported
+          },
+          visibilityFilter: {
+            targetSet: 'acc',
+            accEligible: accEligibility.eligible,
+            reasons: accEligibility.reasons
+          },
+          targetGeometry: geometryEligibility
+            ? { eligible: geometryEligibility.eligible, reasons: geometryEligibility.reasons }
+            : { eligible: null, reasons: [] }
+        }
+      });
+      continue;
+    }
 
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
     const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');

package/src/checks/manual/table-duplicate-name-manual.js

@@ -43,14 +43,13 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   function normalizeWs(s) {
     return String(s || '').replace(/\s+/g, ' ').trim();
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table[summary]', safeRoot) : helpers.queryAll('table[summary]', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table[summary]') : helpers.queryAll('table[summary]');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/table-fake-caption-manual.js

@@ -51,12 +51,11 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, root, helpers, rule } = ctx;
-  const safeRoot = root || document;
+  const { document, helpers, rule } = ctx;
 
   function trim(v) { return (v == null ? '' : String(v)).trim(); }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table', safeRoot) : helpers.queryAll('table', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table') : helpers.queryAll('table');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/checks/manual/video-caption-manual.js

@@ -51,10 +51,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('video', safeRoot) : helpers.queryAll('video', safeRoot);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('video') : helpers.queryAll('video');
 
   const occurrences = [];
   let applicableCount = 0;

package/src/core/dom-helpers.js

@@ -115,6 +115,10 @@ function createDomHelpers(opts) {
     })();
     // Default on: opt OUT with `includeShadowDom: false`, not opt in.
     const includeShadowDom = !(opts && opts.includeShadowDom === false);
+    // Default off: by default, helper queries skip structurally/CSS-hidden
+    // subtrees (display:none, [hidden], closed <details>, etc.). Callers can
+    // opt out with includeHiddenElements:true.
+    const includeHiddenElements = !!(opts && opts.includeHiddenElements === true);
     const excludeSelectors = Array.isArray(opts && opts.excludeSelectors) ? opts.excludeSelectors : [];
 
     // Rule-scoped excludes (engineOptions.rules[ruleId].excludeSelectors), set
@@ -1081,8 +1085,55 @@ function createDomHelpers(opts) {
         return results;
     }
 
+    const HARD_HIDDEN_REASONS = new Set([
+        'displayNone',
+        'hiddenAttr',
+        'detailsClosed',
+        'templateContent',
+        'nonRenderedElement',
+        'inputHidden',
+        'visibilityHidden',
+        'contentVisibilityHidden'
+    ]);
+
     function queryAllSmart(sel) {
-        const list = includeShadowDom ? queryAllDeep(sel) : queryAll(sel);
+        let list = includeShadowDom ? queryAllDeep(sel) : queryAll(sel);
+
+        // Global hidden-content policy: skip nodes that are fully excluded from
+        // rendered visibility by default (unless includeHiddenElements:true).
+        if (!includeHiddenElements) {
+            list = list.filter((el) => {
+                try {
+                    const vis = isAccTreeEligible(el);
+                    if (!vis || vis.eligible !== false) return true;
+                    const reasons = Array.isArray(vis.reasons) ? vis.reasons : [];
+                    for (const r of reasons) {
+                        if (HARD_HIDDEN_REASONS.has(r)) return false;
+                    }
+
+                    // `isAccTreeEligible` can short-circuit on an inert ancestor
+                    // before it reaches an outer hard-hidden ancestor (e.g.
+                    // display:none wrapper). In that case the node is still
+                    // structurally hidden and should be excluded by the default
+                    // hidden-content policy.
+                    if (reasons.includes('inert')) {
+                        const domVis = isDomVisibleEligible(el, null, {
+                            visibilityMode: 'styleOnly',
+                            disableGeometry: true,
+                            ignoreOpacity: true
+                        });
+                        const domReasons = Array.isArray(domVis && domVis.reasons) ? domVis.reasons : [];
+                        for (const r of domReasons) {
+                            if (HARD_HIDDEN_REASONS.has(r)) return false;
+                        }
+                    }
+                    return true;
+                } catch {
+                    return true;
+                }
+            });
+        }
+
         return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
@@ -3652,6 +3703,36 @@ function createDomHelpers(opts) {
             let node = el;
             let safety = 0;
 
+            // Only apply the "stop climbing once we reach a contextSelector-
+            // matched root" shortcut when there's a single (or no) matched
+            // root -- resolveContextRoots() falls back to `[documentElement]`
+            // when no contextSelector is given, so this is the overwhelmingly
+            // common case and behaves exactly as before.
+            //
+            // With MULTIPLE matched roots (multi-region contextSelector
+            // scans), stopping there without recording anything about which
+            // root produced an ambiguous, non-unique selector string for two
+            // structurally-identical regions -- a real, confirmed bug (found
+            // 2026-07-29 via the cross-engine comparisons project): two
+            // wrapper <div>s, each containing two identical ".widget"
+            // sections scanned via `contextSelector: '.widget'`, produced the
+            // *same* selector string ("section:nth-of-type(1) > div > div >
+            // button") for the equivalent button in each wrapper --
+            // resolving to 2 elements instead of 1 when queried, and pointing
+            // at the wrong one for at least one of the two occurrences. The
+            // existing `el.matches(candidate)` safety check below couldn't
+            // catch this: it only verifies THIS element matches the string,
+            // never that the string is unique document-wide.
+            //
+            // Fix: when multiple roots are in play, don't stop early --
+            // keep climbing (same as the always-correct no-contextSelector
+            // path) until finding a genuinely unique anchor or reaching the
+            // true document root, which is always singular. That restores
+            // the invariant the final safety-check comment below relies on,
+            // rather than needing a separate (more expensive) document-wide
+            // uniqueness re-check.
+            const stopAtMatchedRoot = roots.length <= 1;
+
             while (node && node.nodeType === 1 && safety++ < 20) {
                 let anchor = null;
 
@@ -3691,7 +3772,7 @@ function createDomHelpers(opts) {
                     parts.unshift(nthOfType(node));
                 }
 
-                if (!node.parentElement || roots.includes(node)) break;
+                if (!node.parentElement || (stopAtMatchedRoot && roots.includes(node))) break;
                 node = node.parentElement;
             }
 
@@ -3710,7 +3791,12 @@ function createDomHelpers(opts) {
             // position relative to its own parent via `>` (child, not
             // descendant) combinators, so a correctly-matching chain can
             // only resolve to one element short of a malformed document
-            // (e.g. two <html> roots). Re-deriving that guarantee via a
+            // (e.g. two <html> roots) -- true as long as the walk above
+            // never stops short of a genuinely unique anchor/root, which is
+            // exactly what `stopAtMatchedRoot` now guarantees (see its own
+            // comment above; a multi-root contextSelector scan stopping
+            // early used to violate this invariant silently). Re-deriving
+            // that guarantee via a
             // document-wide :nth-of-type scan was measured to cost O(total
             // same-tag siblings) per call — pathological on pages with many
             // flat, unidentified siblings (e.g. hundreds of unlabeled