@surea11y/core 1.0.0 → 1.1.0

package/docs/ENGINE_OPTIONS.md

@@ -82,6 +82,7 @@ const engineOptions = {
     mode: 'strictConformance',     // 'strictConformance' (default) | 'auditorAssist'
     rootCanvasFallback: '#ffffff'  // background assumed when the true root background isn't computable
   },
+  visibilityMode: 'styleOnly',     // 'styleOnly' (default) | 'styleAndGeometry' — see below; scoped to the contrast rules only
 
   policyContract: 'a11y',          // 'a11y' (default) | 'generic' | inline contract object — see POLICY.md
   policy: {                        // optional overrides on top of policyContract
@@ -94,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 */ },
@@ -112,17 +115,107 @@ 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 123) 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. |
+| `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`, 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.
+
+**CI gate: WCAG 2.2 AA only, ignore a third-party widget you don't control**
+
+```js
+runDomRulesInPage(url, null, {
+  excludeSelectors: ['#cookie-banner', '.intercom-launcher'],
+  tags: { include: 'wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22a,wcag22aa' }
+}, null);
+```
+
+**Human auditor doing a deep contrast pass in a real browser** — trade some false-positive protection for more findings, and check real layout (not just computed style) since a real page is being driven. Shown with Puppeteer's `page.evaluate` (accepts multiple args); if you're on Playwright, wrap the four positional args into a single object first — see [`INTEGRATION.md`](./INTEGRATION.md):
+
+```js
+const result = await page.evaluate(runa11yCoreInPage, url, null, {
+  contrast: { mode: 'auditorAssist' },
+  visibilityMode: 'styleAndGeometry'
+}, null);
+```
+
+**Scoped re-scan of one region after a UI change, skipping shadow DOM** — useful in a component-level test where you only care about the widget you just changed:
+
+```js
+runDomRulesInPage(url, '#checkout-form', {
+  includeShadowDom: false
+}, { includeRuleIds: ['form-control-programmatic-label-present', 'button-name-present'] });
+```
+
+**Reproducible output for snapshot testing** — pin a `timestamp` so two runs of the same HTML produce byte-identical JSON, and request the debug timing breakdown:
+
+```js
+runDomRulesInPage(url, null, {
+  timestamp: '2026-01-01T00:00:00Z',
+  perfStats: true,
+  profileRules: true
+}, null);
+```
+
+**A custom, org-specific rule alongside the built-ins**, only for this one call:
+
+```js
+runDomRulesInPage(url, null, {
+  customRules: [{
+    id: 'org-no-inline-onclick',
+    meta: { title: 'No inline onclick handlers', defaultSeverity: 'moderate' },
+    runInPage(ctx) {
+      const els = ctx.helpers.queryAll('[onclick]');
+      const occurrences = els.map((el) => ({
+        selector: ctx.helpers.buildSelector(el),
+        html: el.outerHTML,
+        summary: 'Inline onclick handler found.',
+        hint: 'Move event handling into an external script.'
+      }));
+      return { ruleId: ctx.rule.ruleId, outcome: occurrences.length ? 'fail' : 'pass', severity: 'moderate', occurrences };
+    }
+  }]
+}, null);
+```
+
+See the option-by-option table above for anything not shown here, and the `customRules` section immediately below for the full descriptor contract.
+
 ## `customRules` — runtime-registered rules (equivalent to the rule/check registration pattern used by other engines)
 
 Every shipped rule is baked into `src/core.js` at build time. `engineOptions.customRules` is the runtime escape hatch: an array of rule descriptors registered for that one call only — nothing is added to the static catalog (`getRulesCatalog()`/`getChecksCatalog()`), and nothing persists between calls. This is deliberate, not a limitation to work around: surea11y already takes fresh `engineOptions` per call with no mutable global config (unlike some other engines, which need a `configure()`/`reset()` step against a shared runtime), and custom rules follow that same per-call model.

package/docs/I18N.md

@@ -6,10 +6,10 @@ Every rule's title/description, and every occurrence's summary/hint, is localize
 
 | Locale | File | Keys | Coverage vs. English |
 |---|---|---|---|
-| `en` (English) | `src/i18n/en.js` | 590 | 100% (the canonical/fallback set) |
-| `fr` (French) | `src/i18n/fr.js` | 287 | ~49% — **partial**, not every string is translated yet |
+| `en` (English) | `src/i18n/en.js` | 600 | 100% (the canonical/fallback set) |
+| `fr` (French) | `src/i18n/fr.js` | 600 | 100% |
 
-That `fr` number is real and worth being honest about: about half of the engine's translatable strings don't have a French entry yet. That's not a bug — see the fallback behavior below, which means a missing `fr` key never produces broken or missing text, just an English string in the middle of otherwise-French output.
+Both locales are fully translated as of this writing. That won't stay automatically true — every time a new rule (or a new i18n key) is added to `en.js`, `fr.js` needs the same key added, or it silently falls back to English for that string (see the fallback behavior below). There's no automated check for this yet; diff `Object.keys(require('./src/i18n/en.js'))` against `fr.js` after adding a rule to catch drift before it ships.
 
 ## Selecting a locale
 

package/docs/OUTPUT_SCHEMA.md

@@ -103,7 +103,7 @@ Notes:
 
 ## An occurrence (`occurrences[i]`)
 
-Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` result has `occurrences: []` — this engine does not enumerate the elements it passed, only the ones it flagged; see the note in `docs/RULE_AUTHORING.md` on why "silence" from a `pass` rule is not the same as an enumerated list of passing elements).
+Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` result has `occurrences: []` — this engine does not enumerate the elements it passed, only the ones it flagged).
 
 ```ts
 {
@@ -114,7 +114,7 @@ Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` re
   hint: string,
   i18n: { summaryKey: string, hintKey: string, params: object } | null,
   data: {
-    visibilityFilter?: { targetSet: string, accEligible: boolean | null, reasons: string[] },
+    visibilityFilter?: { eligible: boolean, targetSet: string, accEligible: boolean | null, reasons: string[] },
     details?: object   // rule-specific, non-normative — see below
   }
 }
@@ -128,7 +128,7 @@ Only present when `outcome` is `fail` or `cantTell` (a `pass`/`notApplicable` re
 | `summary` | Human-readable, already localized ("This button has no accessible name."). |
 | `hint` | Human-readable remediation guidance, already localized. |
 | `i18n` | The raw translation keys behind `summary`/`hint`, if you want to re-render them in a different locale yourself without re-running the scan. `null` if the occurrence didn't use key-based i18n. |
-| `data.visibilityFilter` | Present on most occurrences: why the engine considered this element eligible for accessibility-tree evaluation (or not). `reasons` is a list of machine-readable exclusion codes when `accEligible: false`. |
+| `data.visibilityFilter` | Present on most occurrences: why the engine considered this element eligible (or not) under whichever eligibility model the rule used. `eligible` is that result; `targetSet` says which model produced it (`'dom'`: raw DOM/CSS visibility — most rules; `'acc'`: accessibility-tree eligibility). `accEligible` mirrors `eligible` only when `targetSet` is `'acc'`, otherwise `null` — don't read it as a second, independent signal. `reasons` is a list of machine-readable exclusion codes when `eligible: false`. |
 | `data.details` | Rule-specific structured data (e.g. `reasonCode`, computed metrics, resolved references) — **non-normative**: useful for building richer UI or debugging, but never changes what `outcome`/`severity` mean. Shape varies per rule; treat as best-effort extra context, not a stable contract. |
 
 ## A composite result (`rulesResults[i]`)
@@ -202,7 +202,7 @@ const result = runDomRulesInPage(
         {
           "selector": "html > body > button",
           "html": "<button></button>",
-          "structuralPath": [1, 0],
+          "structuralPath": [1, 1],
           "summary": "This button has no accessible name.",
           "hint": "Provide visible button text or a programmatic accessible-name mechanism (for example aria-label) so assistive technologies can identify the button.",
           "data": {
@@ -222,7 +222,7 @@ const result = runDomRulesInPage(
         {
           "selector": "html > body > img",
           "html": "<img src=\"logo.png\">",
-          "structuralPath": [1, 1],
+          "structuralPath": [1, 0],
           "summary": "Missing alt attribute on <img>.",
           "hint": "Add an alt attribute (use alt=\"\" only for decorative images)."
         }

package/docs/RULE_TAXONOMY.md

@@ -12,7 +12,7 @@ Encoded by: `meta.type`
 
 - `automatic`
     - Rule makes a **normative decision**
-    - Allowed outcomes: `pass`, `fail`, `notApplicable`
+    - Allowed outcomes: `pass`, `fail`, `notApplicable`, and `cantTell` as a defensive fallback only (e.g. an internal-failure safety net, or a computability gate a rule can't resolve — see `contrast-minimum.js`/`contrast-enhanced.js`/`contrast-computable.js`/`target-size-minimum.js`), never as its primary intended path
 - `manual`
     - Rule signals **human review required**
     - Allowed outcomes: `cantTell`, `notApplicable`
@@ -24,7 +24,7 @@ Manual rules MUST NOT make normative failure decisions.
 ### 1.2 Intent
 Encoded by: **rule id suffix**
 
-Current intents:
+Illustrative intents (from the image-alternatives family used as the running example in §2, not an exhaustive list — the ruleset's 125 rules use dozens of distinct suffixes; `docs/RULE_CATALOG.md` is the generated, always-current list):
 
 - `present`
     - Verifies that a required **mechanism exists**
@@ -43,7 +43,7 @@ Intent determines whether a rule can be automatic.
 ### 1.3 Target Family
 Encoded by: **rule id prefix**
 
-Current families include:
+Illustrative families, from the image-alternatives cluster (WCAG 1.1.1) used as the running example in §2 — not an exhaustive list. The ruleset's 125 rules span dozens of families (`aria-*`, `contrast-*`, `dialog-*`, `iframe-*`, `label-*`, `link-*`, `list-*`, `landmark-*`, and more); see `docs/RULE_CATALOG.md` for the generated, always-current list:
 
 - `img`
 - `area`
@@ -67,12 +67,13 @@ Rules MUST NOT mix families.
 ### 1.4 Target Set (Tree Scope)
 Encoded by: `data.visibilityFilter.targetSet`
 
-Current value used by this ruleset:
-- `acc` (accessibility tree)
+Values used by this ruleset:
+- `acc` (accessibility tree) — most rules
+- `dom` (raw DOM/CSS visibility, no accessibility-tree computation) — e.g. `label-in-name.js`
 
-Rules explicitly log eligibility against the accessibility tree using:
-- `helpers.isAccTreeEligible`
-- `helpers.getEligibilityInfo(..., { targetSet: "acc" })`
+Rules log eligibility against whichever tree scope they target using:
+- `helpers.isAccTreeEligible` / `helpers.isDomVisibleEligible`
+- `helpers.getEligibilityInfo(..., { targetSet: "acc" | "dom" })`
 
 This is a semantic constraint, not logging noise.
 

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?"
 
@@ -39,9 +39,9 @@ No — see [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md). A `pass` means every
 
 Treat it as "needs a human to look" — it's neither pass nor fail by design. Most teams log `cantTell` findings without failing CI on them, since failing a build on something the engine explicitly couldn't determine tends to train people to ignore the gate. See [`POLICY.md`](./POLICY.md) if you want to reshape this behavior (e.g. via a custom policy contract), and [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result) for a concrete CI-gating example.
 
-## "Why is French only partially translated?"
+## "What happens if a locale is only partially translated?"
 
-It genuinely is — see [`I18N.md`](./I18N.md) for the exact current coverage. Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright.
+Missing keys fall back to English per-string (never a blank or broken result), so a partial locale degrades gracefully rather than failing outright — see [`I18N.md`](./I18N.md) for the mechanism and current coverage. Both shipped locales (`en`, `fr`) are at full parity as of this writing, but that's not guaranteed to stay true automatically: adding a new rule adds a new key to `en.js`, and unless the same key is added to `fr.js` (or any other locale file you maintain), that string falls back to English until it is.
 
 ## "`runDomRulesInPage` vs `runa11yCoreInPage` — which one do I want?"
 

package/docs/WCAG_CONFORMANCE.md

@@ -4,7 +4,7 @@ How individual rule results relate to a WCAG Success Criterion (SC), and what su
 
 ## The three layers
 
-1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 123.
+1. **Atomic rules** (`checksResults[]`) — one normative decision each, e.g. "does this `<img>` have an `alt` attribute." See [`RULE_CATALOG.md`](./RULE_CATALOG.md) for all 125.
 2. **Facets** — a WCAG SC is usually bigger than any one rule can decide deterministically. Internally, each SC is broken into named "facets" (e.g. 1.1.1 Non-text Content has facets like `img-alt-attr-present`, `text-alternative-quality`, `decorative-null`) tracked in `src/coverage/wcag-facets.js`, each marked `full` (a rule decides it with high confidence), `partial` (a rule decides *part* of it — see each rule's own scope notes), or `manual` (no safe automated heuristic exists at all). Run `npm run coverage` to regenerate `coverage/coverage-report.md`, the per-SC facet breakdown.
 3. **Composite (WCAG-SC rollup) rules** (`rulesResults[]`) — a generated aggregate of every atomic rule mapped to one SC, giving you one pass/fail/cantTell/notApplicable verdict per SC instead of having to roll up dozens of atomic results yourself. See [`RULE_CATALOG.md`](./RULE_CATALOG.md#composite-wcag-sc-rollup-rules-31) for the full list (e.g. `wcag-1.1.1-non-text-content` rolls up 22 atomic rules).
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@surea11y/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Lightweight DOM rules accessibility core with modular rules.",
   "main": "src/index.js",
   "bin": {
-    "surea11y": "./bin/core.js"
+    "surea11y": "bin/core.js"
   },
   "author": "Jorge Rumoroso",
   "license": "MIT",
@@ -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

@@ -22,12 +22,7 @@
  * - SUPPORTED_ATTRS_BY_ROLE widened 2026-07-21 (7 new roles), cross-checked
  *   against a widely-used reference engine's own per-role `allowedAttrs`
  *   table AND verified each addition is an unambiguous, well-established ARIA
- *   fact rather than a blind import — that engine's own table has ~68 roles,
- *   far more than were reconciled here; this pass deliberately took only the
- *   additions with clear, specific supported attributes (not just the
- *   near-universal, thin `aria-expanded` that engine allows on most roles), and
- *   left the rest for a dedicated future full-reconciliation pass rather
- *   than rushing all 68 through at lower confidence:
+ *   fact rather than a blind import:
  *   - `searchbox`: identical to the already-covered `textbox` (ARIA
  *     explicitly defines searchbox as textbox's subclass, same supported
  *     set).
@@ -47,6 +42,34 @@
  *   - `menu`/`menubar`/`toolbar`: activedescendant/orientation — standard
  *     composite-widget properties, same family as the already-covered
  *     `tablist`.
+ * - SUPPORTED_ATTRS_BY_ROLE full-reconciliation pass 2026-07-28: the
+ *   2026-07-21 pass deliberately deferred ~61 roles where the reference
+ *   engine (axe-core) allows `aria-expanded`, treating it as too thin/
+ *   near-universal to import blindly. Checked against `aria-query`
+ *   (tracks the published WAI-ARIA 1.2 Recommendation, 6 June 2023 — the
+ *   latest actually-published version, as opposed to the in-progress 1.3
+ *   Editor's Draft) instead of axe-core directly, because axe-core's own
+ *   source comments (`// Spec difference: Aria-expanded removed in 1.2`)
+ *   show that most of its `aria-expanded` allowances are deliberate
+ *   ARIA-1.1 legacy/AT-compat carryovers axe-core keeps on purpose, not
+ *   current-spec facts — importing them wholesale would have re-added
+ *   exactly the kind of unverified allowance the 07-21 pass was avoiding.
+ *   `aria-query`'s per-role tables (with superclass inheritance resolved,
+ *   e.g. `aria-activedescendant` via the abstract `composite` role) gave a
+ *   spec-grounded diff instead. Net changes from that diff:
+ *   - `aria-expanded` added to: checkbox, columnheader, gridcell, listbox,
+ *     menuitemcheckbox, menuitemradio, row, rowheader, switch, tab —
+ *     confirmed present in current spec for these roles specifically
+ *     (unlike e.g. `listitem`, `dialog`, `alertdialog`, `heading`, which
+ *     the spec does NOT list it for — those stay excluded).
+ *   - `aria-activedescendant` added to: combobox, grid, listbox,
+ *     radiogroup, row, spinbutton, tablist, treegrid (inherited from the
+ *     abstract `composite` role for any composite/managed-focus widget).
+ *   - `aria-readonly`/`aria-required` added to: switch, menuitemcheckbox,
+ *     menuitemradio. `aria-posinset`/`aria-setsize` added to: tab, radio,
+ *     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.
  */
 
@@ -101,39 +124,39 @@ function runInPage(ctx) {
   // role/attribute pairings from the WAI-ARIA role definitions are listed.
   const SUPPORTED_ATTRS_BY_ROLE = {
     alertdialog: ['aria-modal'],
-    checkbox: ['aria-checked', 'aria-readonly', 'aria-required'],
-    columnheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected'],
-    combobox: ['aria-expanded', 'aria-autocomplete', 'aria-readonly', 'aria-required'],
+    checkbox: ['aria-checked', 'aria-readonly', 'aria-required', 'aria-expanded'],
+    columnheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected', 'aria-expanded'],
+    combobox: ['aria-expanded', 'aria-autocomplete', 'aria-readonly', 'aria-required', 'aria-activedescendant'],
     dialog: ['aria-modal'],
-    grid: ['aria-multiselectable', 'aria-readonly', 'aria-colcount', 'aria-rowcount'],
-    gridcell: ['aria-selected', 'aria-readonly', 'aria-required', 'aria-colindex', 'aria-colspan', 'aria-rowindex', 'aria-rowspan'],
+    grid: ['aria-multiselectable', 'aria-readonly', 'aria-colcount', 'aria-rowcount', 'aria-activedescendant'],
+    gridcell: ['aria-selected', 'aria-readonly', 'aria-required', 'aria-colindex', 'aria-colspan', 'aria-rowindex', 'aria-rowspan', 'aria-expanded'],
     heading: ['aria-level'],
-    listbox: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation'],
+    listbox: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation', 'aria-expanded', 'aria-activedescendant'],
     listitem: ['aria-level', 'aria-posinset', 'aria-setsize'],
     menu: ['aria-activedescendant', 'aria-orientation'],
     menubar: ['aria-activedescendant', 'aria-orientation'],
-    menuitemcheckbox: ['aria-checked'],
-    menuitemradio: ['aria-checked'],
+    menuitemcheckbox: ['aria-checked', 'aria-expanded', 'aria-readonly', 'aria-required', 'aria-posinset', 'aria-setsize'],
+    menuitemradio: ['aria-checked', 'aria-expanded', 'aria-readonly', 'aria-required', 'aria-posinset', 'aria-setsize'],
     meter: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext'],
     option: ['aria-selected', 'aria-checked', 'aria-posinset', 'aria-setsize'],
     progressbar: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext'],
-    radio: ['aria-checked'],
-    radiogroup: ['aria-readonly', 'aria-required', 'aria-orientation'],
-    row: ['aria-selected', 'aria-level', 'aria-posinset', 'aria-setsize', 'aria-colindex', 'aria-rowindex'],
-    rowheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected'],
+    radio: ['aria-checked', 'aria-posinset', 'aria-setsize'],
+    radiogroup: ['aria-readonly', 'aria-required', 'aria-orientation', 'aria-activedescendant'],
+    row: ['aria-selected', 'aria-level', 'aria-posinset', 'aria-setsize', 'aria-colindex', 'aria-rowindex', 'aria-expanded', 'aria-activedescendant'],
+    rowheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected', 'aria-expanded'],
     scrollbar: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation', 'aria-controls'],
     searchbox: ['aria-activedescendant', 'aria-autocomplete', 'aria-multiline', 'aria-placeholder', 'aria-readonly', 'aria-required'],
     separator: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation'],
     slider: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation', 'aria-readonly'],
-    spinbutton: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-readonly', 'aria-required'],
-    switch: ['aria-checked'],
-    tab: ['aria-selected'],
+    spinbutton: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-readonly', 'aria-required', 'aria-activedescendant'],
+    switch: ['aria-checked', 'aria-expanded', 'aria-readonly', 'aria-required'],
+    tab: ['aria-selected', 'aria-expanded', 'aria-posinset', 'aria-setsize'],
     table: ['aria-colcount', 'aria-rowcount'],
-    tablist: ['aria-multiselectable', 'aria-orientation'],
+    tablist: ['aria-multiselectable', 'aria-orientation', 'aria-level', 'aria-activedescendant'],
     textbox: ['aria-activedescendant', 'aria-autocomplete', 'aria-multiline', 'aria-placeholder', 'aria-readonly', 'aria-required'],
     toolbar: ['aria-activedescendant', 'aria-orientation'],
-    tree: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation'],
-    treegrid: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation', 'aria-colcount', 'aria-rowcount'],
+    tree: ['aria-multiselectable', 'aria-required', 'aria-orientation', 'aria-activedescendant'],
+    treegrid: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation', 'aria-colcount', 'aria-rowcount', 'aria-activedescendant'],
     treeitem: ['aria-checked', 'aria-selected', 'aria-expanded', 'aria-level', 'aria-posinset', 'aria-setsize']
   };
 

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)
     // =========================