@surea11y/core 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -4,7 +4,10 @@ All notable changes to this project are documented here, in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [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

package/docs/ENGINE_OPTIONS.md

@@ -95,7 +95,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 */ },
@@ -113,18 +115,44 @@ const engineOptions = {
 |---|---|
 | `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. |
 | `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/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.0",
   "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/core/dom-helpers.js

@@ -117,14 +117,35 @@ function createDomHelpers(opts) {
     const includeShadowDom = !(opts && opts.includeShadowDom === false);
     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 +907,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 +1005,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) {
@@ -1059,7 +1083,7 @@ function createDomHelpers(opts) {
 
     function queryAllSmart(sel) {
         const list = includeShadowDom ? queryAllDeep(sel) : queryAll(sel);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
     // -------------------------------------------------------------------------
@@ -1093,10 +1117,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 +3532,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 +3542,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 +4052,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

@@ -242,6 +242,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 +321,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

@@ -10969,14 +10969,35 @@ const createDomHelpers = (function createDomHelpers(opts) {
     const includeShadowDom = !(opts && opts.includeShadowDom === false);
     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 +11759,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 +11857,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) {
@@ -11911,7 +11935,7 @@ const createDomHelpers = (function createDomHelpers(opts) {
 
     function queryAllSmart(sel) {
         const list = includeShadowDom ? queryAllDeep(sel) : queryAll(sel);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
     // -------------------------------------------------------------------------
@@ -11945,10 +11969,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 +14384,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 +14394,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 +14904,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,
 
@@ -15291,6 +15323,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 +15402,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)
     // =========================
@@ -43009,14 +43058,35 @@ const createDomHelpers = (function createDomHelpers(opts) {
     const includeShadowDom = !(opts && opts.includeShadowDom === false);
     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 +43848,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 +43946,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) {
@@ -43951,7 +44024,7 @@ const createDomHelpers = (function createDomHelpers(opts) {
 
     function queryAllSmart(sel) {
         const list = includeShadowDom ? queryAllDeep(sel) : queryAll(sel);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
     // -------------------------------------------------------------------------
@@ -43985,10 +44058,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 +46473,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 +46483,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 +46993,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,
 
@@ -47331,6 +47412,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 +47491,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)
     // =========================
@@ -75004,14 +75102,35 @@ const createDomHelpers = (function createDomHelpers(opts) {
     const includeShadowDom = !(opts && opts.includeShadowDom === false);
     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 +75892,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 +75990,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) {
@@ -75946,7 +76068,7 @@ const createDomHelpers = (function createDomHelpers(opts) {
 
     function queryAllSmart(sel) {
         const list = includeShadowDom ? queryAllDeep(sel) : queryAll(sel);
-        return excludeSelectors.length ? list.filter((el) => !isExcluded(el)) : list;
+        return __getEffectiveExcludeSelectors().length ? list.filter((el) => !isExcluded(el)) : list;
     }
 
     // -------------------------------------------------------------------------
@@ -75980,10 +76102,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 +78517,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 +78527,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 +79037,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,
 
@@ -79326,6 +79456,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 +79535,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)
     // =========================