@surea11y/core 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project are documented here, in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [1.1.2] - 2026-07-30
+
+### Fixed
+- `accesskeys` no longer over-reports duplicate `accesskey` values when one copy is structurally/CSS hidden by default (for example collapsed or `display:none` menu replicas). Candidate collection now follows the shared helper visibility policy, so only currently eligible elements are grouped unless `engineOptions.includeHiddenElements: true` is explicitly set.
+- `skip-link` no longer treats fragment-target existence alone as sufficient. It now also flags skip links whose target exists but is currently unusable (hidden from the accessibility tree), while keeping geometry-based target checks gated to environments that expose reliable layout metrics.
+- `page-has-heading-one` and `bypass-blocks-present` credited a fully non-rendered `<h1>`/`<main>`/heading (inside a `display:none` ancestor, or otherwise removed from the accessibility tree via `visibility:hidden`/`[hidden]`/`aria-hidden`/`inert`) as satisfying the check, since both queried the raw DOM (`document.querySelectorAll`) with no visibility/accessibility-tree filtering. Found via the cross-engine comparisons project on CDC's flu page: its only `<h1>` sits inside a `display:none` ancestor — unreachable by sighted and screen reader users alike — and `page-has-heading-one` reported `notApplicable` where axe-core correctly fails. `bypass-blocks-present`'s `<main>`/heading conditions had the identical gap, wrongly returning `pass` for a page with zero actual bypass mechanisms. Both now filter candidates through the existing `isAccTreeEligible` helper, matching `landmark-one-main`'s established precedent; confirmed this does not regress genuinely screen-reader-accessible but visually-clipped/off-screen headings and landmarks (e.g. eBay's homepage `<h1>`, hidden via clip-path with no `aria-hidden`), which `isAccTreeEligible` correctly continues to credit.
+- `button-name-present` and `link-name-present` credited a `<button>`/`<a href>` element's rendered content as its accessible name even when an explicit `role` overrode it to a role whose content represents a VALUE, not a NAME (`combobox`, `listbox`, `textbox`, `slider`, `spinbutton`, `progressbar`, `scrollbar` — name-from-author-only per the WAI-ARIA Accessible Name and Description Computation spec; mirrors axe-core's `controlValueRoles`, verified against its source). Both checks gated "is this a name-from-content candidate" on the native host tag alone, never checking whether `role` had overridden it. Found via the cross-engine comparisons project on Spotify's "Today's Top Hits" playlist page: `<button role="combobox">List</button>` (a "sort by" control, no `aria-label`/`aria-labelledby`) was credited with the name "List" — the combobox's currently selected *value*, not a label for what it is — and reported no issue at all, while axe-core's `button-name` correctly failed it. Both rules now exclude these value-roles from name-from-content; a programmatic name (`aria-label`/`aria-labelledby`/`title`/native `<label>`) still works normally. `combobox-name-present`, `listbox-name-present`, `textbox-name-present`, `spinbutton-name-present`, `progressbar-name-present`, `meter-name-present`, `searchbox-name-present`, `slider-name-present`, and `dialog-name-present` were audited against the same gap and were already correctly name-from-author-only.
+- `createDomHelpers()`'s element-keyed caches (`outerHtmlCache`, `selectorCache`, etc.) were persisted on `window.__a11ycoreSharedCache` and only initialized once per `window`/`document`, not once per run. A window/document reused across separate `runDomRulesInPage()`/`runa11yCoreInPage()` calls — e.g. Jest's `jsdom` environment, which creates one `window` per test file — could read back a previous run's stale cached value for an element that persists by reference across runs (like `document.body`) while its content changed via an in-place mutation (`innerHTML = ...`) in between. Rule pass/fail outcomes were always computed correctly against the live DOM; only cached diagnostic data such as `occurrences[].html` (via `bypass-blocks-present`, reported in #2) could go stale. `runCore()` (`src/core/dom-runner.js`) now resets `window.__a11ycoreSharedCache` at the start of every run, keeping the intended within-a-run sharing while preventing leakage across runs.
+- `buildSelector` could emit ambiguous selectors in multi-region scans when the target element was the last same-tag sibling, because the `:nth-of-type()` disambiguator could be omitted on that segment. Selector construction now consistently disambiguates those cases, so each occurrence maps back to the intended node.
+- `queryAllSmart` could retain elements that are structurally hard-hidden when `isAccTreeEligible` short-circuited on an `inert` ancestor before reaching an outer `display:none`/`visibility:hidden`/`content-visibility:hidden` ancestor. It now performs a style-only DOM visibility fallback in that path and excludes these hard-hidden nodes by default, preserving `includeHiddenElements: true` opt-in behavior.
+
+### Changed
+- Test coverage tightened for this release cycle: re-enabled and stabilized the previously skipped `role-img-text-alternative-present` i18n assertions (EN/FR exact strings and keys), and added regression coverage for the inert + outer hard-hidden filtering path in `queryAllSmart`.
+- Removed a dead `root`/`safeRoot` second argument passed to `helpers.queryAllSmart`/`helpers.queryAll` across 67 rule files: both helpers only ever accepted a single selector argument and scope internally via the run's resolved `contextSelector` roots, so the extra argument was silently ignored in every call. No behavior change — `ctx.root` was always identical to the roots already baked into `helpers` at run start. Also fixed `docs/RULE_TEMPLATE.md`, the copy/paste template most likely responsible for the pattern spreading, which declared `safeRoot` but never even referenced it.
+
+## [1.1.1] - 2026-07-29
+
+### Changed
+- **`engineOptions.includeHiddenElements` (default `false`)**: helper-driven rules now skip elements hidden by `display:none` (on the element or any ancestor), `visibility:hidden`/`collapse`, the `[hidden]` attribute, closed `<details>`, and other structurally-non-rendered content by default, matching the visibility-aware behavior of other established engines. Filtering happens upstream in the shared `queryAllSmart` helper, before a rule's own pass/fail logic runs, so it's a candidate-list exclusion, not a post-hoc annotation. Set `engineOptions.includeHiddenElements: true` to restore the previous behavior and evaluate hidden/collapsed subtrees anyway (e.g. to catch a markup defect, like a broken ARIA ID reference, before a `<dialog>` ever opens). 10 rule files whose own logic intentionally doesn't call the underlying eligibility check directly (static-markup-validity rules such as `aria-valid-attr`, `aria-valid-attr-value`, `aria-allowed-attr`, `aria-allowed-role`, `aria-prohibited-attr`, `table-headers-attr-valid`, `table-th-has-data-cells`, `deprecated-elements-not-used`, `iframe-title-unique`, `aria-checked-state-mismatch-manual`) still inherit this filtering through `queryAllSmart`; their doc comments were updated to say so. See `docs/ENGINE_OPTIONS.md` and `docs/LIMITATIONS.md`.
+
+### Fixed
+- `docs/LIMITATIONS.md`: the `<dialog>`/UA-stylesheet-hidden-content note was stale — it claimed static-markup-validity checks still evaluate hidden content, which this release's default change makes no longer true. Corrected to describe the current default and how to opt back in.
+
 ## [1.1.0] - 2026-07-28
 
 ### Added
@@ -28,7 +51,7 @@ All notable changes to this project are documented here, in [Keep a Changelog](h
 - README: the JSON output example referenced a nonexistent rule id (`link-name-quality`); corrected to the real id, `link-name-quality-manual`.
 - README: Quick Start code samples labeled the runner's four positional arguments as `url, ruleFilter, options, policy`; corrected to the actual names (`pageUrl, contextSelector, engineOptions, runOnly`) used consistently elsewhere in the docs.
 
-## [1.1.1] - 2026-07-24
+## [1.0.0] - 2026-07-26
 
 ### Added
 - 125 rules (77 automatic/`fail`-capable, 48 manual/advisory) — see `docs/RULE_CATALOG.md` for the full list.
@@ -61,7 +84,7 @@ See `docs/LIMITATIONS.md` — structural (keyboard-trap detection, reflow-at-zoo
 
 ---
 
-## How to add an entry
+# How to add an entry
 
 When you ship a change worth calling out to consumers (not every commit):
 1. Add a bullet under `[Unreleased]`, in the right subsection (`Added`, `Changed`, `Fixed`, `Deprecated`, `Removed`, `Security`) — create the subsection if it doesn't exist yet for this cycle.

package/docs/ENGINE_OPTIONS.md

@@ -72,6 +72,7 @@ runDomRulesInPage(url, null, {
 ```js
 const engineOptions = {
   locale: 'en',                    // default 'en'; falls back to 'en' per-string if a key is missing in the requested locale
+  includeHiddenElements: false,    // default false — set true to evaluate hidden/collapsed subtrees too
   includeShadowDom: true,          // default true — opt OUT with `false` to skip open shadow roots
   excludeSelectors: ['#cookie-banner', '.third-party-widget'],  // array or comma-separated string
   timestamp: '2026-07-20T12:00:00Z',  // optional — engine has no built-in clock, see OUTPUT_SCHEMA.md
@@ -114,6 +115,7 @@ const engineOptions = {
 | Option | Meaning |
 |---|---|
 | `locale` | Any string; resolution is per-string with graceful fallback (requested locale → `en` → the rule's literal English fallback text), so a partially-translated locale never produces missing text. See [`I18N.md`](./I18N.md) for current locale coverage. |
+| `includeHiddenElements` | Default `false`: helper queries exclude elements hidden by structural/CSS mechanisms such as `display:none`, `[hidden]`, closed `<details>`, and hidden rendering-only host elements (with descendants excluded too). Set `true` to include those hidden/collapsed subtrees in evaluation (legacy/static-markup behavior). |
 | `includeShadowDom` | Default `true`: rules using `helpers.queryAllSmart` traverse into open shadow roots. Set `false` to scan only the light DOM. Closed shadow roots are never reachable either way (no DOM API exposes them). |
 | `excludeSelectors` | Elements matching any of these selectors (and their descendants) are skipped entirely, for **every** rule — useful for cookie banners, third-party embeds, or known-noisy widgets you don't control. To exclude something from just one specific rule instead, use `rules[ruleId].excludeSelectors` below. |
 | `timestamp` | Passed straight through to the result's top-level `timestamp` field; the engine does not generate one itself (deterministic-by-design). |

package/docs/LIMITATIONS.md

@@ -13,7 +13,7 @@ surea11y is a **static DOM scan**: it reads the DOM tree and computed styles at
 ## Environment-dependent — depends on how you run it
 
 - **jsdom (Node, no real browser) has no CSS layout engine.** Rules needing real geometry — most notably `target-size-minimum` (WCAG 2.5.8, needs real `getBoundingClientRect()`) — report `notApplicable` under plain jsdom rather than guess. Run under a real browser (Puppeteer/Playwright — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2) to get real findings from these rules.
-- **`<dialog>` and other elements hidden by the default UA stylesheet** (no `open` attribute, `display: none` by spec) are skipped by most tools' visibility-aware checks, including other established engines — but surea11y's static-markup-validity checks (like ARIA ID-reference validity) still evaluate them, since a markup defect is still a defect even before the dialog opens. This is a deliberate surea11y choice that can occasionally make it *more* thorough than other engines on hidden content, not a bug — found and confirmed during internal cross-engine verification.
+- **`<dialog>` and other elements hidden by the default UA stylesheet** (no `open` attribute, `display: none` by spec), along with any other subtree hidden via `display:none`, `visibility:hidden`, `[hidden]`, or closed `<details>`, are **excluded from rule evaluation by default** — matching the visibility-aware behavior of other established engines. This is a deliberate default (`engineOptions.includeHiddenElements: false`), not an oversight: hidden content isn't reachable by assistive technology or keyboard until it's shown, so flagging a markup defect inside it by default would often be noise. Set `engineOptions.includeHiddenElements: true` to evaluate hidden/collapsed subtrees anyway — e.g. to catch a markup defect (like a broken ARIA ID reference) before a dialog ever opens. See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#engineoptions--the-rest) for the option and exactly which hiding mechanisms it covers.
 - **Static markup vs. live/post-hydration DOM state.** The rule logic itself is DOM-source-agnostic — it evaluates whatever DOM it's handed, whether that's jsdom-parsed static HTML (Pattern 1) or an already-loaded, already-hydrated real browser tab (Pattern 2, see [`INTEGRATION.md`](./INTEGRATION.md)). But the CLI (`npx @surea11y/core scan <url>`) specifically fetches static HTML only, with no JS execution — see [`CLI.md`](./CLI.md). For a JS-framework-hydrated widget whose server-rendered markup intentionally ships one state before client JS syncs it (e.g. `<input type="checkbox" aria-checked="true">` shipped before client JS sets the native `checked` property to match on hydration — an extremely common, entirely legitimate pattern), a CLI scan only sees the pre-hydration markup. Other engines running inside an actual loaded browser tab see the post-hydration state instead, so the two can disagree on exactly this class of element for reasons that have nothing to do with either engine's rule correctness. `aria-checked-state-mismatch` is deliberately `manual`/`cantTell`-capped for this exact reason rather than a hard `fail`. If you need live-DOM accuracy for hydration-sensitive checks, run the library directly against an already-loaded page via Pattern 2, not the static-fetch CLI.
 
 ## Deliberately not attempted — judgment calls, not automatable safely

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Lightweight DOM rules accessibility core with modular rules.",
   "main": "src/index.js",
   "bin": {

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

@@ -70,7 +70,9 @@
  *     menuitemcheckbox, menuitemradio. `aria-level` added to: tablist.
  *   - `tree`'s `aria-readonly` removed: not in aria-query's resolved
  *     props for `tree` (was an unverified carryover, not spec-backed).
- * - Not gated on isAccTreeEligible: this is a static markup property.
+ * - Not rule-gated on isAccTreeEligible: this remains a static-markup
+ *   property, while engine-level hidden-subtree filtering still applies
+ *   unless engineOptions.includeHiddenElements is true.
  */
 
 const id = 'aria-allowed-attr';
@@ -96,8 +98,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) {
@@ -161,7 +162,7 @@ function runInPage(ctx) {
   };
 
   const globalSet = new Set(GLOBAL_ATTRS);
-  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-allowed-role.js

@@ -18,7 +18,9 @@
  * - Deliberately scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
  *   elements without an asserted constraint are treated as "no constraint"
  *   (not flagged) rather than guessed at — see that table's header comment.
- * - Not gated on isAccTreeEligible: this is a static markup property.
+ * - Not rule-gated on isAccTreeEligible: this remains a static-markup
+ *   property, while engine-level hidden-subtree filtering still applies
+ *   unless engineOptions.includeHiddenElements is true.
  */
 
 const id = 'aria-allowed-role';
@@ -44,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('[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-braille-equivalent.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;
 
   function trim(v) { return (v == null ? '' : String(v)).trim(); }
 
@@ -74,8 +73,8 @@ function runInPage(ctx) {
   }
 
   const nodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('[aria-braillelabel], [aria-brailleroledescription]', safeRoot)
-    : helpers.queryAll('[aria-braillelabel], [aria-brailleroledescription]', safeRoot);
+    ? helpers.queryAllSmart('[aria-braillelabel], [aria-brailleroledescription]')
+    : helpers.queryAll('[aria-braillelabel], [aria-brailleroledescription]');
 
   const occurrences = [];
   let applicableCount = 0;

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

@@ -53,16 +53,15 @@ 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 TRUTHY_INVALID_VALUES = new Set(['true', 'grammar', 'spelling']);
 
   const nodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('[aria-errormessage]', safeRoot)
-    : helpers.queryAll('[aria-errormessage]', safeRoot);
+    ? helpers.queryAllSmart('[aria-errormessage]')
+    : helpers.queryAll('[aria-errormessage]');
 
   const occurrences = [];
   let applicableCount = 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-prohibited-attr.js

@@ -55,7 +55,9 @@
  *   `definition_role` page even demonstrates `aria-labelledby` usage on
  *   it directly. A real, confirmed documentation bug on MDN's side, not
  *   a gap here.
- * - Not gated on isAccTreeEligible: this is a static markup property.
+ * - Not rule-gated on isAccTreeEligible: this remains a static-markup
+ *   property, while engine-level hidden-subtree filtering still applies
+ *   unless engineOptions.includeHiddenElements is true.
  */
 
 const id = 'aria-prohibited-attr';
@@ -81,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) {
@@ -102,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

@@ -100,8 +100,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) {
@@ -190,7 +189,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;

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

@@ -17,7 +17,9 @@
  *   ID reference (list) that resolves to an existing element in the
  *   document.
  * @implementation-notes
- * - Not gated on isAccTreeEligible: this is a static markup property.
+ * - Not rule-gated on isAccTreeEligible: this remains a static-markup
+ *   property, while engine-level hidden-subtree filtering still applies
+ *   unless engineOptions.includeHiddenElements is true.
  * - ID-reference resolution (added 2026-07-20, see aria-helpers.js's
  *   idExists) only flags idref-list attributes (aria-labelledby,
  *   aria-describedby, aria-controls, aria-owns, etc.) when NONE of the
@@ -55,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

@@ -18,7 +18,9 @@
  * - Distinct from aria-valid-attr-value (which validates the VALUE
  *   of a recognized attribute) — this rule only validates the attribute
  *   NAME.
- * - Not gated on isAccTreeEligible: this is a static markup property.
+ * - Not rule-gated on isAccTreeEligible: this remains a static-markup
+ *   property, while engine-level hidden-subtree filtering still applies
+ *   unless engineOptions.includeHiddenElements is true.
  */
 
 const id = 'aria-valid-attr';
@@ -44,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

@@ -75,14 +75,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 +151,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();

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/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;