@surea11y/core 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -4,7 +4,18 @@ 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
+- `engineOptions.rules[ruleId].excludeSelectors`: rule-scoped exclusions, narrowing candidates for exactly one rule on top of (never instead of) the existing global `excludeSelectors`. Resolves the class of false positive where one rule misfires on a component (e.g. Angular Material's `mat-select` tripping `aria-required-children`) while every other rule still needs to see it. Filtering happens upstream of each rule's own outcome decision, so no rule files changed. See `docs/ENGINE_OPTIONS.md`'s "Rule-scoped `excludeSelectors`" section.
 - Completed French (`fr`) localization: translated the 313 remaining `src/i18n/fr.js` keys, bringing French to full parity with English (600/600 keys, up from 287/600). Verified against a live scan (`locale: 'fr'`) and confirmed no key/placeholder mismatches against `src/i18n/en.js`. Landmark terminology uses "point de repère" per MDN's French ARIA documentation.
 
 ### Fixed
@@ -25,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.
@@ -58,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
@@ -95,7 +96,9 @@ const engineOptions = {
   },
 
   rules: {
-    'some-rule-id': { /* per-rule config, currently unused — see note */ }
+    'some-rule-id': {
+      excludeSelectors: ['.some-noisy-widget']  // narrows candidates for THIS rule only — see note
+    }
   },
 
   probes: { /* optional host-supplied evidence, see note */ },
@@ -112,19 +115,46 @@ 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 — useful for cookie banners, third-party embeds, or known-noisy widgets you don't control. |
+| `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). |
 | `contrast.mode` | `strictConformance` (default): contrast rules stay silent (`notApplicable`/skip) whenever the true rendered background isn't confidently computable, to protect against false `fail`s. `auditorAssist`: trades some of that safety margin for more findings, intended for a human auditor who will double-check flagged cases, not for unattended CI gating. |
 | `contrast.rootCanvasFallback` | The assumed page background color when it's not computable at all — only matters in `auditorAssist` mode. |
 | `visibilityMode` | Controls how strict the three contrast rules (`contrast-minimum`, `contrast-enhanced`, `contrast-computable`) are about deciding a text node is actually eligible to check. **Not read by any other rule.** `'styleOnly'` (default): eligibility is CSS-only — `display`, `visibility`, `opacity`, ancestor-hiding, etc. `'styleAndGeometry'`: adds real layout checks (`getClientRects()`/`getBoundingClientRect()`) on top of that — text with no client rects, or zero width/height, is excluded too. Reach for `'styleAndGeometry'` when running under a real browser/Playwright-Puppeteer (`runa11yCoreInPage`) and you want contrast findings to reflect actual rendered layout rather than just computed style; under plain jsdom (`runDomRulesInPage`) there's no real layout engine, so `'styleAndGeometry'` mostly just adds `getBoundingClientRect()` zero-size checks, not true clipping/overflow detection — see [`LIMITATIONS.md`](./LIMITATIONS.md). |
 | `policyContract` / `policy` | See [`POLICY.md`](./POLICY.md) — controls which outcomes/confidence values are allowed and whether manual rules' would-be `fail`s get coerced to `cantTell`. |
 | `output.includeSelector` / `.includeHtml` | Only affects the small number of rules (currently 4 of 125) that rely on the engine's automatic selector/HTML fill-in rather than building their own — most rules set `selector`/`html` themselves inside `runInPage` and are unaffected by this option. Not a reliable way to strip selectors/HTML from all output. |
-| `rules[ruleId]` | Passed through to that rule as `ctx.config`. The plumbing exists end-to-end, but **no shipped rule currently reads `ctx.config`** — this is infrastructure for future per-rule configurability, not a lever that changes any of today's 123 rules' behavior. |
+| `rules[ruleId]` | Passed through to that rule as `ctx.config`, and — for `excludeSelectors` specifically — read by the engine itself before the rule ever runs. See "Rule-scoped `excludeSelectors`" below. Any other key is passthrough only: **no shipped rule currently reads `ctx.config`** for anything besides `excludeSelectors`. |
 | `probes` | An optional, JSON-safe evidence object your host application can supply (depth- and size-capped by the engine before rules see it, via `ctx.inputs.probes`) — for future rules that might accept externally-supplied signals (e.g. real layout measurements a static DOM scan can't compute itself). Not consumed by any current rule. |
 | `perfStats` / `profileRules` | Debug-only. `perfStats: true` returns internal counters on the result's `perfStats` field; `profileRules: true` additionally adds a per-rule timing breakdown. Shape is not part of the stable output contract — don't build on it. |
 | `pingWaitTime` / `frameWaitTime` | Only read by `runa11yCoreAcrossFrames` (see [`INTEGRATION.md`](./INTEGRATION.md#cross-frame-scanning-including-cross-origin)) — how long to wait for a child frame to answer a ping (default `500`ms) and a full run request (default `60000`ms) before treating it as unreachable. Ignored by `runDomRulesInPage`/`runa11yCoreInPage`. |
 
+### Rule-scoped `excludeSelectors`
+
+The top-level `excludeSelectors` applies to *every* rule — there's no way to exclude an element from just one rule while still running every other rule against it. `rules[ruleId].excludeSelectors` fills that gap: it narrows candidates for **that one rule only**, on top of (never instead of) the global list.
+
+```js
+const engineOptions = {
+  excludeSelectors: ['#cookie-banner'],   // applies to every rule, as always
+  rules: {
+    'aria-required-children': {
+      excludeSelectors: ['mat-select', 'mat-stepper', 'mat-horizontal-stepper', 'mat-vertical-stepper']
+    },
+    'aria-allowed-attr': {
+      excludeSelectors: ['mat-progress-spinner']
+    }
+  }
+};
+```
+
+Why you'd want this: Angular Material's `<mat-select>` builds its internal ARIA structure in a way that trips a false positive on `aria-required-children` specifically, even though the component is otherwise fine. With only the global `excludeSelectors`, the only way to silence that false positive is `excludeSelectors: ['mat-select']` — which also hides `mat-select` from *every other rule*, including `color-contrast` and `aria-allowed-attr`, silently dropping real coverage those checks never had a problem with. The example above keeps `mat-select` fully visible to every rule except the one that misfires on it.
+
+Effective exclusions for a given rule are the **union** of the global list and that rule's own list — an element matching either is dropped from that rule's candidates. A rule whose only would-be-failing elements are all excluded this way reports `outcome: 'pass'` or `'notApplicable'` (matching that rule's own no-candidates convention), with `occurrences: []` — never `outcome: 'fail'` with an empty `occurrences` array, since that exact shape is reserved elsewhere in the schema to mean "this rule threw" (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md)).
+
+Accepts the same forms as the global option: an array (`['mat-select', 'mat-stepper']`) or a comma-separated string (`'mat-select, mat-stepper'`).
+
+> If you're using a binding package (`@surea11y/binding-base` and its Playwright/Puppeteer wrappers), check that binding's own README for whether its `.exclude()` builder method has a rule-scoped form yet — this is an `engineOptions` shape documented here at the engine level; not every binding has picked it up.
+
 ## Recipes — composing options for real scenarios
 
 The reference above documents each option in isolation. These combine several at once, for scenarios you're likely to actually hit.

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/docs/TROUBLESHOOTING.md

@@ -29,7 +29,7 @@ By design, this engine never enumerates the elements a rule *passed* — only th
 Two common causes, in order of likelihood:
 
 1. **The element is excluded from the accessibility tree** — `aria-hidden="true"`, `display: none`, `visibility: hidden`, `hidden`, or an `inert` ancestor. Most rules deliberately skip content that's already invisible to assistive technology (checking a hidden element would be meaningless, and could produce a misleading `fail` on content no user encounters). Some rules explicitly opt out of this gating when it wouldn't make sense to (e.g. `no-autoplay-audio` — hidden audio still plays sound) — check the specific rule's file header comment (`@applicability`) in `src/checks/`.
-2. **`excludeSelectors`** — if you've configured this (directly or inherited from a shared config), confirm the element in question isn't matched by it.
+2. **`excludeSelectors`** — if you've configured this (directly or inherited from a shared config), confirm the element in question isn't matched by it. Remember this can also be scoped to a single rule via `engineOptions.rules[ruleId].excludeSelectors` (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#rule-scoped-excludeselectors)) — if a rule you expect to fire keeps coming back `notApplicable`/`pass` for one element only, check whether that rule specifically has its own exclude list configured, not just the global one.
 
 ## "Does a clean scan (`pass` everywhere) mean the page is WCAG conformant?"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Lightweight DOM rules accessibility core with modular rules.",
   "main": "src/index.js",
   "bin": {
@@ -37,6 +37,7 @@
   ],
   "scripts": {
     "build": "node scripts/build-core.js",
+    "pretest": "playwright install chromium",
     "test": "npm run build && node scripts/run-tests.js",
     "test:contrast-helpers": "node tests/contrast-helpers.test.js",
     "helpers-perf-bench": "node --expose-gc scripts/dom-helpers-perf-bench.js",

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,16 +115,41 @@ 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
+    // by dom-runner.js immediately before invoking each rule's applicability/
+    // run function via __setActiveRuleExcludeSelectors(). Safe as mutable
+    // closure state because rule execution is synchronous and single-rule-
+    // at-a-time: exactly one rule's excludes are ever "active" at once.
+    var __activeRuleExcludeSelectors = [];
+
+    function __getEffectiveExcludeSelectors() {
+        return __activeRuleExcludeSelectors.length
+            ? excludeSelectors.concat(__activeRuleExcludeSelectors)
+            : excludeSelectors;
+    }
+
+    function __setActiveRuleExcludeSelectors(list) {
+        __activeRuleExcludeSelectors = normalizeSelectorList(list);
+    }
+
     // Selector-related caches (selector uniqueness index, per-element built
-    // selector strings) depend on includeShadowDom/excludeSelectors, since
-    // those change which elements are considered when checking uniqueness.
-    // The underlying storage is shared across createDomHelpers() calls on
-    // the same window/document (see __domSharedCache below), so a run with
-    // different options must not read/write another run's cached selectors.
-    // This key partitions those caches per effective option set.
-    const __selectorOptsKey = (includeShadowDom ? 'sd1' : 'sd0') + '|' + excludeSelectors.slice().sort().join(',');
+    // selector strings) depend on includeShadowDom/the effective exclude
+    // list, since those change which elements are considered when checking
+    // uniqueness. The underlying storage is shared across createDomHelpers()
+    // calls on the same window/document (see __domSharedCache below), so a
+    // run -- or a rule with its own rule-scoped excludes -- must not
+    // read/write another run/rule's cached selectors. This key partitions
+    // those caches per effective option set; recomputed per call (not a
+    // constant) since the effective list changes as the active rule changes.
+    function __getSelectorOptsKey() {
+        return (includeShadowDom ? 'sd1' : 'sd0') + '|' + __getEffectiveExcludeSelectors().slice().sort().join(',');
+    }
 
     // -------------------------------------------------------------------------
     // Per-run shared caches (DOM helpers)
@@ -886,9 +911,10 @@ function createDomHelpers(opts) {
 
 
     function isExcluded(el) {
-        if (!excludeSelectors.length || !el || !el.closest) return false;
+        const eff = __getEffectiveExcludeSelectors();
+        if (!eff.length || !el || !el.closest) return false;
         try {
-            return excludeSelectors.some((sel) => !!el.closest(sel));
+            return eff.some((sel) => !!el.closest(sel));
         } catch {
             return false;
         }
@@ -983,8 +1009,10 @@ function createDomHelpers(opts) {
             if (!scope || !scope.querySelectorAll) return [];
 
             // Cache shadow root discovery per root to avoid repeated querySelectorAll('*') walks.
-            // IMPORTANT: do not cache when excludeSelectors is non-empty (different helpers may differ).
-            if (!excludeSelectors.length && __shadowRootsByRoot) {
+            // IMPORTANT: do not cache when the effective exclude list (global
+            // ∪ active rule-scoped excludes) is non-empty -- different rules
+            // may have different effective lists and must not share results.
+            if (!__getEffectiveExcludeSelectors().length && __shadowRootsByRoot) {
                 try {
                     const cached = __shadowRootsByRoot.get(scope);
                     if (cached) {
@@ -1057,9 +1085,38 @@ 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);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        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;
     }
 
     // -------------------------------------------------------------------------
@@ -1093,10 +1150,11 @@ function createDomHelpers(opts) {
     function __getSelectorCacheForOpts() {
         if (!__selectorCache) return null;
         try {
-            let wm = __selectorCache.get(__selectorOptsKey);
+            const key = __getSelectorOptsKey();
+            let wm = __selectorCache.get(key);
             if (!(wm instanceof WeakMap)) {
                 wm = new WeakMap();
-                __selectorCache.set(__selectorOptsKey, wm);
+                __selectorCache.set(key, wm);
             }
             return wm;
         } catch {
@@ -3507,7 +3565,8 @@ function createDomHelpers(opts) {
             return createSelectorUniqIndex();
         }
 
-        const cached = perScope.get(__selectorOptsKey);
+        const key = __getSelectorOptsKey();
+        const cached = perScope.get(key);
         if (cached) {
             __perfInc('uniqIndex.hit');
             return cached;
@@ -3516,7 +3575,7 @@ function createDomHelpers(opts) {
         __perfInc('uniqIndex.miss');
         const idx = createSelectorUniqIndex();
         try {
-            perScope.set(__selectorOptsKey, idx);
+            perScope.set(key, idx);
         } catch { /* ignore */
         }
         __perfInc('uniqIndex.build');
@@ -4026,6 +4085,12 @@ function createDomHelpers(opts) {
         isAccTreeEligible,
         isDomVisibleEligible,
 
+        // Engine-internal: sets which rule's rule-scoped excludeSelectors
+        // (engineOptions.rules[ruleId].excludeSelectors) are currently in
+        // effect. Called by dom-runner.js before each rule invocation, not
+        // intended for use by rule implementations.
+        __setActiveRuleExcludeSelectors,
+
         // Eligibility info wrapper
         getEligibilityInfo,
 

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)
@@ -242,6 +246,15 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
                 ? engineOptionsResolved.rules[defResolved.ruleId]
                 : null;
 
+        // Rule-scoped excludeSelectors (engineOptions.rules[ruleId].excludeSelectors)
+        // apply on top of the global excludeSelectors for exactly this rule's
+        // applicability check + run, then are cleared once this rule is done.
+        // Safe because rule execution below is synchronous and one rule at a
+        // time -- sharedHelpers is reused across all rules in this loop.
+        if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+            sharedHelpers.__setActiveRuleExcludeSelectors(ruleConfig && ruleConfig.excludeSelectors);
+        }
+
         const ctx = {
             document,
             window,
@@ -312,6 +325,14 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
         if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
     }
 
+    // Composite rollups below carry no occurrences/nodes of their own, so
+    // they never exercise rule-scoped excludes -- but clear the "active
+    // rule" state on sharedHelpers regardless, so nothing after this point
+    // (composite aggregation, perf stats) can observe a stale rule's excludes.
+    if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+        sharedHelpers.__setActiveRuleExcludeSelectors(null);
+    }
+
     // =========================
     // Composite rule aggregation (data-only rollups)
     // =========================

package/src/core.js

@@ -10967,16 +10967,41 @@ 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
+    // by dom-runner.js immediately before invoking each rule's applicability/
+    // run function via __setActiveRuleExcludeSelectors(). Safe as mutable
+    // closure state because rule execution is synchronous and single-rule-
+    // at-a-time: exactly one rule's excludes are ever "active" at once.
+    var __activeRuleExcludeSelectors = [];
+
+    function __getEffectiveExcludeSelectors() {
+        return __activeRuleExcludeSelectors.length
+            ? excludeSelectors.concat(__activeRuleExcludeSelectors)
+            : excludeSelectors;
+    }
+
+    function __setActiveRuleExcludeSelectors(list) {
+        __activeRuleExcludeSelectors = normalizeSelectorList(list);
+    }
+
     // Selector-related caches (selector uniqueness index, per-element built
-    // selector strings) depend on includeShadowDom/excludeSelectors, since
-    // those change which elements are considered when checking uniqueness.
-    // The underlying storage is shared across createDomHelpers() calls on
-    // the same window/document (see __domSharedCache below), so a run with
-    // different options must not read/write another run's cached selectors.
-    // This key partitions those caches per effective option set.
-    const __selectorOptsKey = (includeShadowDom ? 'sd1' : 'sd0') + '|' + excludeSelectors.slice().sort().join(',');
+    // selector strings) depend on includeShadowDom/the effective exclude
+    // list, since those change which elements are considered when checking
+    // uniqueness. The underlying storage is shared across createDomHelpers()
+    // calls on the same window/document (see __domSharedCache below), so a
+    // run -- or a rule with its own rule-scoped excludes -- must not
+    // read/write another run/rule's cached selectors. This key partitions
+    // those caches per effective option set; recomputed per call (not a
+    // constant) since the effective list changes as the active rule changes.
+    function __getSelectorOptsKey() {
+        return (includeShadowDom ? 'sd1' : 'sd0') + '|' + __getEffectiveExcludeSelectors().slice().sort().join(',');
+    }
 
     // -------------------------------------------------------------------------
     // Per-run shared caches (DOM helpers)
@@ -11738,9 +11763,10 @@ const createDomHelpers = (function createDomHelpers(opts) {
 
 
     function isExcluded(el) {
-        if (!excludeSelectors.length || !el || !el.closest) return false;
+        const eff = __getEffectiveExcludeSelectors();
+        if (!eff.length || !el || !el.closest) return false;
         try {
-            return excludeSelectors.some((sel) => !!el.closest(sel));
+            return eff.some((sel) => !!el.closest(sel));
         } catch {
             return false;
         }
@@ -11835,8 +11861,10 @@ const createDomHelpers = (function createDomHelpers(opts) {
             if (!scope || !scope.querySelectorAll) return [];
 
             // Cache shadow root discovery per root to avoid repeated querySelectorAll('*') walks.
-            // IMPORTANT: do not cache when excludeSelectors is non-empty (different helpers may differ).
-            if (!excludeSelectors.length && __shadowRootsByRoot) {
+            // IMPORTANT: do not cache when the effective exclude list (global
+            // ∪ active rule-scoped excludes) is non-empty -- different rules
+            // may have different effective lists and must not share results.
+            if (!__getEffectiveExcludeSelectors().length && __shadowRootsByRoot) {
                 try {
                     const cached = __shadowRootsByRoot.get(scope);
                     if (cached) {
@@ -11909,9 +11937,38 @@ 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);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        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;
     }
 
     // -------------------------------------------------------------------------
@@ -11945,10 +12002,11 @@ const createDomHelpers = (function createDomHelpers(opts) {
     function __getSelectorCacheForOpts() {
         if (!__selectorCache) return null;
         try {
-            let wm = __selectorCache.get(__selectorOptsKey);
+            const key = __getSelectorOptsKey();
+            let wm = __selectorCache.get(key);
             if (!(wm instanceof WeakMap)) {
                 wm = new WeakMap();
-                __selectorCache.set(__selectorOptsKey, wm);
+                __selectorCache.set(key, wm);
             }
             return wm;
         } catch {
@@ -14359,7 +14417,8 @@ const createDomHelpers = (function createDomHelpers(opts) {
             return createSelectorUniqIndex();
         }
 
-        const cached = perScope.get(__selectorOptsKey);
+        const key = __getSelectorOptsKey();
+        const cached = perScope.get(key);
         if (cached) {
             __perfInc('uniqIndex.hit');
             return cached;
@@ -14368,7 +14427,7 @@ const createDomHelpers = (function createDomHelpers(opts) {
         __perfInc('uniqIndex.miss');
         const idx = createSelectorUniqIndex();
         try {
-            perScope.set(__selectorOptsKey, idx);
+            perScope.set(key, idx);
         } catch { /* ignore */
         }
         __perfInc('uniqIndex.build');
@@ -14878,6 +14937,12 @@ const createDomHelpers = (function createDomHelpers(opts) {
         isAccTreeEligible,
         isDomVisibleEligible,
 
+        // Engine-internal: sets which rule's rule-scoped excludeSelectors
+        // (engineOptions.rules[ruleId].excludeSelectors) are currently in
+        // effect. Called by dom-runner.js before each rule invocation, not
+        // intended for use by rule implementations.
+        __setActiveRuleExcludeSelectors,
+
         // Eligibility info wrapper
         getEligibilityInfo,
 
@@ -15097,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;
@@ -15112,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)
@@ -15291,6 +15360,15 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
                 ? engineOptionsResolved.rules[defResolved.ruleId]
                 : null;
 
+        // Rule-scoped excludeSelectors (engineOptions.rules[ruleId].excludeSelectors)
+        // apply on top of the global excludeSelectors for exactly this rule's
+        // applicability check + run, then are cleared once this rule is done.
+        // Safe because rule execution below is synchronous and one rule at a
+        // time -- sharedHelpers is reused across all rules in this loop.
+        if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+            sharedHelpers.__setActiveRuleExcludeSelectors(ruleConfig && ruleConfig.excludeSelectors);
+        }
+
         const ctx = {
             document,
             window,
@@ -15361,6 +15439,14 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
         if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
     }
 
+    // Composite rollups below carry no occurrences/nodes of their own, so
+    // they never exercise rule-scoped excludes -- but clear the "active
+    // rule" state on sharedHelpers regardless, so nothing after this point
+    // (composite aggregation, perf stats) can observe a stale rule's excludes.
+    if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+        sharedHelpers.__setActiveRuleExcludeSelectors(null);
+    }
+
     // =========================
     // Composite rule aggregation (data-only rollups)
     // =========================
@@ -43007,16 +43093,41 @@ 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
+    // by dom-runner.js immediately before invoking each rule's applicability/
+    // run function via __setActiveRuleExcludeSelectors(). Safe as mutable
+    // closure state because rule execution is synchronous and single-rule-
+    // at-a-time: exactly one rule's excludes are ever "active" at once.
+    var __activeRuleExcludeSelectors = [];
+
+    function __getEffectiveExcludeSelectors() {
+        return __activeRuleExcludeSelectors.length
+            ? excludeSelectors.concat(__activeRuleExcludeSelectors)
+            : excludeSelectors;
+    }
+
+    function __setActiveRuleExcludeSelectors(list) {
+        __activeRuleExcludeSelectors = normalizeSelectorList(list);
+    }
+
     // Selector-related caches (selector uniqueness index, per-element built
-    // selector strings) depend on includeShadowDom/excludeSelectors, since
-    // those change which elements are considered when checking uniqueness.
-    // The underlying storage is shared across createDomHelpers() calls on
-    // the same window/document (see __domSharedCache below), so a run with
-    // different options must not read/write another run's cached selectors.
-    // This key partitions those caches per effective option set.
-    const __selectorOptsKey = (includeShadowDom ? 'sd1' : 'sd0') + '|' + excludeSelectors.slice().sort().join(',');
+    // selector strings) depend on includeShadowDom/the effective exclude
+    // list, since those change which elements are considered when checking
+    // uniqueness. The underlying storage is shared across createDomHelpers()
+    // calls on the same window/document (see __domSharedCache below), so a
+    // run -- or a rule with its own rule-scoped excludes -- must not
+    // read/write another run/rule's cached selectors. This key partitions
+    // those caches per effective option set; recomputed per call (not a
+    // constant) since the effective list changes as the active rule changes.
+    function __getSelectorOptsKey() {
+        return (includeShadowDom ? 'sd1' : 'sd0') + '|' + __getEffectiveExcludeSelectors().slice().sort().join(',');
+    }
 
     // -------------------------------------------------------------------------
     // Per-run shared caches (DOM helpers)
@@ -43778,9 +43889,10 @@ const createDomHelpers = (function createDomHelpers(opts) {
 
 
     function isExcluded(el) {
-        if (!excludeSelectors.length || !el || !el.closest) return false;
+        const eff = __getEffectiveExcludeSelectors();
+        if (!eff.length || !el || !el.closest) return false;
         try {
-            return excludeSelectors.some((sel) => !!el.closest(sel));
+            return eff.some((sel) => !!el.closest(sel));
         } catch {
             return false;
         }
@@ -43875,8 +43987,10 @@ const createDomHelpers = (function createDomHelpers(opts) {
             if (!scope || !scope.querySelectorAll) return [];
 
             // Cache shadow root discovery per root to avoid repeated querySelectorAll('*') walks.
-            // IMPORTANT: do not cache when excludeSelectors is non-empty (different helpers may differ).
-            if (!excludeSelectors.length && __shadowRootsByRoot) {
+            // IMPORTANT: do not cache when the effective exclude list (global
+            // ∪ active rule-scoped excludes) is non-empty -- different rules
+            // may have different effective lists and must not share results.
+            if (!__getEffectiveExcludeSelectors().length && __shadowRootsByRoot) {
                 try {
                     const cached = __shadowRootsByRoot.get(scope);
                     if (cached) {
@@ -43949,9 +44063,38 @@ 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);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        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;
     }
 
     // -------------------------------------------------------------------------
@@ -43985,10 +44128,11 @@ const createDomHelpers = (function createDomHelpers(opts) {
     function __getSelectorCacheForOpts() {
         if (!__selectorCache) return null;
         try {
-            let wm = __selectorCache.get(__selectorOptsKey);
+            const key = __getSelectorOptsKey();
+            let wm = __selectorCache.get(key);
             if (!(wm instanceof WeakMap)) {
                 wm = new WeakMap();
-                __selectorCache.set(__selectorOptsKey, wm);
+                __selectorCache.set(key, wm);
             }
             return wm;
         } catch {
@@ -46399,7 +46543,8 @@ const createDomHelpers = (function createDomHelpers(opts) {
             return createSelectorUniqIndex();
         }
 
-        const cached = perScope.get(__selectorOptsKey);
+        const key = __getSelectorOptsKey();
+        const cached = perScope.get(key);
         if (cached) {
             __perfInc('uniqIndex.hit');
             return cached;
@@ -46408,7 +46553,7 @@ const createDomHelpers = (function createDomHelpers(opts) {
         __perfInc('uniqIndex.miss');
         const idx = createSelectorUniqIndex();
         try {
-            perScope.set(__selectorOptsKey, idx);
+            perScope.set(key, idx);
         } catch { /* ignore */
         }
         __perfInc('uniqIndex.build');
@@ -46918,6 +47063,12 @@ const createDomHelpers = (function createDomHelpers(opts) {
         isAccTreeEligible,
         isDomVisibleEligible,
 
+        // Engine-internal: sets which rule's rule-scoped excludeSelectors
+        // (engineOptions.rules[ruleId].excludeSelectors) are currently in
+        // effect. Called by dom-runner.js before each rule invocation, not
+        // intended for use by rule implementations.
+        __setActiveRuleExcludeSelectors,
+
         // Eligibility info wrapper
         getEligibilityInfo,
 
@@ -47137,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;
@@ -47152,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)
@@ -47331,6 +47486,15 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
                 ? engineOptionsResolved.rules[defResolved.ruleId]
                 : null;
 
+        // Rule-scoped excludeSelectors (engineOptions.rules[ruleId].excludeSelectors)
+        // apply on top of the global excludeSelectors for exactly this rule's
+        // applicability check + run, then are cleared once this rule is done.
+        // Safe because rule execution below is synchronous and one rule at a
+        // time -- sharedHelpers is reused across all rules in this loop.
+        if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+            sharedHelpers.__setActiveRuleExcludeSelectors(ruleConfig && ruleConfig.excludeSelectors);
+        }
+
         const ctx = {
             document,
             window,
@@ -47401,6 +47565,14 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
         if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
     }
 
+    // Composite rollups below carry no occurrences/nodes of their own, so
+    // they never exercise rule-scoped excludes -- but clear the "active
+    // rule" state on sharedHelpers regardless, so nothing after this point
+    // (composite aggregation, perf stats) can observe a stale rule's excludes.
+    if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+        sharedHelpers.__setActiveRuleExcludeSelectors(null);
+    }
+
     // =========================
     // Composite rule aggregation (data-only rollups)
     // =========================
@@ -75002,16 +75174,41 @@ 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
+    // by dom-runner.js immediately before invoking each rule's applicability/
+    // run function via __setActiveRuleExcludeSelectors(). Safe as mutable
+    // closure state because rule execution is synchronous and single-rule-
+    // at-a-time: exactly one rule's excludes are ever "active" at once.
+    var __activeRuleExcludeSelectors = [];
+
+    function __getEffectiveExcludeSelectors() {
+        return __activeRuleExcludeSelectors.length
+            ? excludeSelectors.concat(__activeRuleExcludeSelectors)
+            : excludeSelectors;
+    }
+
+    function __setActiveRuleExcludeSelectors(list) {
+        __activeRuleExcludeSelectors = normalizeSelectorList(list);
+    }
+
     // Selector-related caches (selector uniqueness index, per-element built
-    // selector strings) depend on includeShadowDom/excludeSelectors, since
-    // those change which elements are considered when checking uniqueness.
-    // The underlying storage is shared across createDomHelpers() calls on
-    // the same window/document (see __domSharedCache below), so a run with
-    // different options must not read/write another run's cached selectors.
-    // This key partitions those caches per effective option set.
-    const __selectorOptsKey = (includeShadowDom ? 'sd1' : 'sd0') + '|' + excludeSelectors.slice().sort().join(',');
+    // selector strings) depend on includeShadowDom/the effective exclude
+    // list, since those change which elements are considered when checking
+    // uniqueness. The underlying storage is shared across createDomHelpers()
+    // calls on the same window/document (see __domSharedCache below), so a
+    // run -- or a rule with its own rule-scoped excludes -- must not
+    // read/write another run/rule's cached selectors. This key partitions
+    // those caches per effective option set; recomputed per call (not a
+    // constant) since the effective list changes as the active rule changes.
+    function __getSelectorOptsKey() {
+        return (includeShadowDom ? 'sd1' : 'sd0') + '|' + __getEffectiveExcludeSelectors().slice().sort().join(',');
+    }
 
     // -------------------------------------------------------------------------
     // Per-run shared caches (DOM helpers)
@@ -75773,9 +75970,10 @@ const createDomHelpers = (function createDomHelpers(opts) {
 
 
     function isExcluded(el) {
-        if (!excludeSelectors.length || !el || !el.closest) return false;
+        const eff = __getEffectiveExcludeSelectors();
+        if (!eff.length || !el || !el.closest) return false;
         try {
-            return excludeSelectors.some((sel) => !!el.closest(sel));
+            return eff.some((sel) => !!el.closest(sel));
         } catch {
             return false;
         }
@@ -75870,8 +76068,10 @@ const createDomHelpers = (function createDomHelpers(opts) {
             if (!scope || !scope.querySelectorAll) return [];
 
             // Cache shadow root discovery per root to avoid repeated querySelectorAll('*') walks.
-            // IMPORTANT: do not cache when excludeSelectors is non-empty (different helpers may differ).
-            if (!excludeSelectors.length && __shadowRootsByRoot) {
+            // IMPORTANT: do not cache when the effective exclude list (global
+            // ∪ active rule-scoped excludes) is non-empty -- different rules
+            // may have different effective lists and must not share results.
+            if (!__getEffectiveExcludeSelectors().length && __shadowRootsByRoot) {
                 try {
                     const cached = __shadowRootsByRoot.get(scope);
                     if (cached) {
@@ -75944,9 +76144,38 @@ 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);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        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;
     }
 
     // -------------------------------------------------------------------------
@@ -75980,10 +76209,11 @@ const createDomHelpers = (function createDomHelpers(opts) {
     function __getSelectorCacheForOpts() {
         if (!__selectorCache) return null;
         try {
-            let wm = __selectorCache.get(__selectorOptsKey);
+            const key = __getSelectorOptsKey();
+            let wm = __selectorCache.get(key);
             if (!(wm instanceof WeakMap)) {
                 wm = new WeakMap();
-                __selectorCache.set(__selectorOptsKey, wm);
+                __selectorCache.set(key, wm);
             }
             return wm;
         } catch {
@@ -78394,7 +78624,8 @@ const createDomHelpers = (function createDomHelpers(opts) {
             return createSelectorUniqIndex();
         }
 
-        const cached = perScope.get(__selectorOptsKey);
+        const key = __getSelectorOptsKey();
+        const cached = perScope.get(key);
         if (cached) {
             __perfInc('uniqIndex.hit');
             return cached;
@@ -78403,7 +78634,7 @@ const createDomHelpers = (function createDomHelpers(opts) {
         __perfInc('uniqIndex.miss');
         const idx = createSelectorUniqIndex();
         try {
-            perScope.set(__selectorOptsKey, idx);
+            perScope.set(key, idx);
         } catch { /* ignore */
         }
         __perfInc('uniqIndex.build');
@@ -78913,6 +79144,12 @@ const createDomHelpers = (function createDomHelpers(opts) {
         isAccTreeEligible,
         isDomVisibleEligible,
 
+        // Engine-internal: sets which rule's rule-scoped excludeSelectors
+        // (engineOptions.rules[ruleId].excludeSelectors) are currently in
+        // effect. Called by dom-runner.js before each rule invocation, not
+        // intended for use by rule implementations.
+        __setActiveRuleExcludeSelectors,
+
         // Eligibility info wrapper
         getEligibilityInfo,
 
@@ -79132,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;
@@ -79147,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)
@@ -79326,6 +79567,15 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
                 ? engineOptionsResolved.rules[defResolved.ruleId]
                 : null;
 
+        // Rule-scoped excludeSelectors (engineOptions.rules[ruleId].excludeSelectors)
+        // apply on top of the global excludeSelectors for exactly this rule's
+        // applicability check + run, then are cleared once this rule is done.
+        // Safe because rule execution below is synchronous and one rule at a
+        // time -- sharedHelpers is reused across all rules in this loop.
+        if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+            sharedHelpers.__setActiveRuleExcludeSelectors(ruleConfig && ruleConfig.excludeSelectors);
+        }
+
         const ctx = {
             document,
             window,
@@ -79396,6 +79646,14 @@ const runCore = (function runCore(pageUrl, contextSelector, engineOptions, runOn
         if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
     }
 
+    // Composite rollups below carry no occurrences/nodes of their own, so
+    // they never exercise rule-scoped excludes -- but clear the "active
+    // rule" state on sharedHelpers regardless, so nothing after this point
+    // (composite aggregation, perf stats) can observe a stale rule's excludes.
+    if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
+        sharedHelpers.__setActiveRuleExcludeSelectors(null);
+    }
+
     // =========================
     // Composite rule aggregation (data-only rollups)
     // =========================