@surea11y/core 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented here, in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [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 +36,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 +69,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.1",
   "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';

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

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

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

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

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

@@ -17,10 +17,12 @@
  *   rule has no partial-pass case, matching a widely-used reference engine's `blink`/`marquee`
  *   rules (which report only when the element is found).
  * @implementation-notes
- * - Not gated on isAccTreeEligible: presence in markup is itself the
+ * - Not rule-gated on isAccTreeEligible: presence in markup is itself the
  *   violation, independent of visibility (moving/blinking content inside a
  *   hidden ancestor could still become visible later without a code
  *   change, so hiding it today does not remove the underlying defect).
+ *   Engine-level hidden-subtree filtering still applies unless
+ *   engineOptions.includeHiddenElements is true.
  */
 
 const id = 'deprecated-elements-not-used';

package/src/checks/automatic/iframe-title-unique.js

@@ -19,8 +19,9 @@
  * - Compares the title ATTRIBUTE specifically, not the full computed
  *   accessible name (aria-label could legitimately differ in wording even
  *   when title happens to collide) — matches a widely-used reference engine's frame-title-unique.
- * - Not gated on isAccTreeEligible: a duplicate title is a static markup
- *   property independent of the frame's current visibility.
+ * - Not rule-gated on isAccTreeEligible: duplicate titles are a static
+ *   markup property. Engine-level hidden-subtree filtering still applies
+ *   unless engineOptions.includeHiddenElements is true.
  */
 
 const id = 'iframe-title-unique';

package/src/checks/automatic/table-headers-attr-valid.js

@@ -16,7 +16,9 @@
  * - One occurrence per offending cell (not per bad token), listing every
  *   invalid reference — matches a widely-used reference engine's
  *   td-headers-attr reporting granularity.
- * - 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 = 'table-headers-attr-valid';

package/src/checks/automatic/table-th-has-data-cells.js

@@ -28,7 +28,9 @@
  *   if some particular <th> in it doesn't actually describe any cell
  *   (false negative, not a false positive — acceptable under this
  *   engine's philosophy).
- * - 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 = 'table-th-has-data-cells';

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

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,37 @@ function createDomHelpers(opts) {
         return results;
     }
 
+    const HARD_HIDDEN_REASONS = new Set([
+        'displayNone',
+        'hiddenAttr',
+        'detailsClosed',
+        'templateContent',
+        'nonRenderedElement',
+        'inputHidden',
+        'visibilityHidden'
+    ]);
+
     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;
+                    }
+                    return true;
+                } catch {
+                    return true;
+                }
+            });
+        }
+
         return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 

package/src/core/dom-runner.js

@@ -48,6 +48,9 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
 
     // Default on: opt OUT with `includeShadowDom: false`, not opt in.
     const includeShadowDom = !(engineOptionsResolved && engineOptionsResolved.includeShadowDom === false);
+    // Default off: hidden/collapsed content is excluded from rule evaluation
+    // unless the caller explicitly opts in.
+    const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
     const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
 
     const url = pageUrl || (document.location && document.location.href) || null;
@@ -63,6 +66,7 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
         window,
         root: roots,
         includeShadowDom,
+        includeHiddenElements,
         excludeSelectors,
         // Optional perf counters (bench/debug only). Deterministic and per-run.
         perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)

package/src/core.js

@@ -10967,6 +10967,10 @@ const createDomHelpers = (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
@@ -11933,8 +11937,37 @@ const createDomHelpers = (function createDomHelpers(opts) {
         return results;
     }
 
+    const HARD_HIDDEN_REASONS = new Set([
+        'displayNone',
+        'hiddenAttr',
+        'detailsClosed',
+        'templateContent',
+        'nonRenderedElement',
+        'inputHidden',
+        'visibilityHidden'
+    ]);
+
     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;
+                    }
+                    return true;
+                } catch {
+                    return true;
+                }
+            });
+        }
+
         return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
@@ -15129,6 +15162,9 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
 
     // Default on: opt OUT with `includeShadowDom: false`, not opt in.
     const includeShadowDom = !(engineOptionsResolved && engineOptionsResolved.includeShadowDom === false);
+    // Default off: hidden/collapsed content is excluded from rule evaluation
+    // unless the caller explicitly opts in.
+    const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
     const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
 
     const url = pageUrl || (document.location && document.location.href) || null;
@@ -15144,6 +15180,7 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
         window,
         root: roots,
         includeShadowDom,
+        includeHiddenElements,
         excludeSelectors,
         // Optional perf counters (bench/debug only). Deterministic and per-run.
         perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)
@@ -43056,6 +43093,10 @@ const createDomHelpers = (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
@@ -44022,8 +44063,37 @@ const createDomHelpers = (function createDomHelpers(opts) {
         return results;
     }
 
+    const HARD_HIDDEN_REASONS = new Set([
+        'displayNone',
+        'hiddenAttr',
+        'detailsClosed',
+        'templateContent',
+        'nonRenderedElement',
+        'inputHidden',
+        'visibilityHidden'
+    ]);
+
     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;
+                    }
+                    return true;
+                } catch {
+                    return true;
+                }
+            });
+        }
+
         return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
@@ -47218,6 +47288,9 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
 
     // Default on: opt OUT with `includeShadowDom: false`, not opt in.
     const includeShadowDom = !(engineOptionsResolved && engineOptionsResolved.includeShadowDom === false);
+    // Default off: hidden/collapsed content is excluded from rule evaluation
+    // unless the caller explicitly opts in.
+    const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
     const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
 
     const url = pageUrl || (document.location && document.location.href) || null;
@@ -47233,6 +47306,7 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
         window,
         root: roots,
         includeShadowDom,
+        includeHiddenElements,
         excludeSelectors,
         // Optional perf counters (bench/debug only). Deterministic and per-run.
         perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)
@@ -75100,6 +75174,10 @@ const createDomHelpers = (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
@@ -76066,8 +76144,37 @@ const createDomHelpers = (function createDomHelpers(opts) {
         return results;
     }
 
+    const HARD_HIDDEN_REASONS = new Set([
+        'displayNone',
+        'hiddenAttr',
+        'detailsClosed',
+        'templateContent',
+        'nonRenderedElement',
+        'inputHidden',
+        'visibilityHidden'
+    ]);
+
     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;
+                    }
+                    return true;
+                } catch {
+                    return true;
+                }
+            });
+        }
+
         return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
@@ -79262,6 +79369,9 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
 
     // Default on: opt OUT with `includeShadowDom: false`, not opt in.
     const includeShadowDom = !(engineOptionsResolved && engineOptionsResolved.includeShadowDom === false);
+    // Default off: hidden/collapsed content is excluded from rule evaluation
+    // unless the caller explicitly opts in.
+    const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
     const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
 
     const url = pageUrl || (document.location && document.location.href) || null;
@@ -79277,6 +79387,7 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
         window,
         root: roots,
         includeShadowDom,
+        includeHiddenElements,
         excludeSelectors,
         // Optional perf counters (bench/debug only). Deterministic and per-run.
         perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)