@surea11y/core 1.1.1 → 1.1.2

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

@@ -1092,7 +1092,8 @@ function createDomHelpers(opts) {
         'templateContent',
         'nonRenderedElement',
         'inputHidden',
-        'visibilityHidden'
+        'visibilityHidden',
+        'contentVisibilityHidden'
     ]);
 
     function queryAllSmart(sel) {
@@ -1109,6 +1110,23 @@ function createDomHelpers(opts) {
                     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;
@@ -3685,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;
 
@@ -3724,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;
             }
 
@@ -3743,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

package/src/core/dom-runner.js

@@ -61,6 +61,21 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
             ? engineOptionsResolved.timestamp.trim()
             : null;
 
+    // createDomHelpers()/createContrastHelpers() persist their element-keyed
+    // caches (outerHtmlCache, selectorCache, etc.) on window.__a11ycoreSharedCache
+    // so multiple helper instances created *within this run* can share them
+    // deterministically. But a window/document is frequently reused across
+    // SEPARATE runs -- e.g. Jest's jsdom environment creates one window per
+    // test file, and mutating document.body between it() blocks is standard.
+    // Those caches are keyed by element reference, not content, so a run that
+    // reuses an already-cached element (document.body never changes identity)
+    // would otherwise read stale data cached by an earlier, unrelated run on
+    // the same window. Clearing at the start of every run keeps sharing scoped
+    // to "this run" as intended, without leaking across runs.
+    try {
+        if (window && window.__a11ycoreSharedCache) window.__a11ycoreSharedCache = {};
+    } catch {}
+
     const sharedHelpers = createDomHelpers({
         document,
         window,