@surea11y/core 1.4.1 → 1.5.0

package/docs/OUTPUT_SCHEMA.md

@@ -15,7 +15,11 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
 
 ```ts
 {
-  engine: { tag: string, schemaVersion: string },
+  engine: {
+    tag: string,
+    schemaVersion: string,
+    locale: { requested: string, resolved: string, reason: string }
+  },
   url: string | null,
   title: string | null,
   timestamp: string | null,
@@ -31,6 +35,8 @@ This is the exact shape of the object returned by `runDomRulesInPage(...)` / `ru
 |---|---|
 | `engine.tag` | The engine's own identity tag, currently `"a11ycore"`. Every rule (built-in or custom) carries it in `meta.tags` — rule `ruleId`s themselves are bare (no prefix). |
 | `engine.schemaVersion` | The result-schema version (`"1.0.0"`). Bump-worthy if this document's shape ever changes incompatibly — pin to it if you're parsing output programmatically. See [`API_STABILITY.md`](./API_STABILITY.md) for the full stable/unstable field list and version-bump policy. |
+| `engine.locale` | Which dictionary the run actually used. `requested` is your `engineOptions.locale` after trimming (`"en"` if you passed nothing or a non-string); `resolved` is the locale whose dictionary was used; `reason` explains the pairing. Because locale fallback is graceful and per-string, asking for a language the build does not carry produces English text rather than an error — this field is how you find that out without reading the strings. Reported once per result: a run uses one dictionary throughout. |
+| `engine.locale.reason` | `"ok"` — you got the dictionary you asked for, and it carries every key. `"primary-subtag"` — your code had a subtag with no dictionary of its own, so its base language was used: `"de-DE"` resolves to `"de"`. `"dictionary-not-loaded"` — the project ships that language, but this build does not carry it and none was supplied (the standalone browser bundle, without its locale side file). `"unknown-locale"` — the project has no such translation at all. `"partial-dictionary"` — the dictionary was used but is missing keys English has, so those strings fell back to English. Treat the set as open; later releases can add to it. |
 | `url` | The `pageUrl` argument you passed in, or `document.location.href` if you passed `null`/omitted it, or `null` if neither is available. |
 | `title` | `document.title` at scan time, or `null`. |
 | `timestamp` | **Not auto-generated.** Only set if you pass `engineOptions.timestamp` as a non-empty string — the engine has no built-in clock (deterministic-by-design). If you want a scan timestamp in the result, supply it yourself. |
@@ -97,7 +103,7 @@ Notes:
 
 - **`outcome` vs `outcomeNormalized`**: identical except `notApplicable` becomes `"inapplicable"` in `outcomeNormalized`. Both are provided so you can match either your own vocabulary or the engine's internal one.
 - **`type: "manual"` rules can never report `outcome: "fail"`.** If a manual rule's own logic would have said `fail`, the engine coerces it to `cantTell` and appends an explanatory note to `error` — this is enforced centrally (`policy.coerceManualFailToCantTell`, on by default under the `a11y` policy contract; see [`POLICY.md`](./POLICY.md)), not something each rule has to remember. `fail` is reserved for deterministic, high-confidence, `type: "automatic"` findings only.
-- **`meta.normativeMappings`** is how a check result ties back to a WCAG Success Criterion — `[]` for rules with no formal WCAG mapping (other engines call these "Best Practices"; this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up.
+- **`meta.normativeMappings`** is how a check result ties back to a WCAG Success Criterion — `[]` for rules with no formal WCAG mapping (this engine calls them advisory `type: "manual"` rules). See [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md) for how these roll up.
 - **`error`**: only present if the rule implementation threw an uncaught exception, or if the manual-fail coercion above fired. A thrown rule always surfaces as `outcome: "cantTell"` with `occurrences: []` and `error` set to the exception message — the engine never lets one broken rule crash the whole scan.
 - **`engineOptions`** on each result is the *resolved* options object (after locale/contrast defaults were applied), not literally what you passed in — useful for confirming what a given rule actually saw, especially the resolved `locale` and `contrast.mode`/`contrast.rootCanvasFallback`.
 
@@ -185,7 +191,11 @@ const result = runDomRulesInPage(
 
 ```json
 {
-  "engine": { "tag": "a11ycore", "schemaVersion": "1.0.0" },
+  "engine": {
+    "tag": "a11ycore",
+    "schemaVersion": "1.0.0",
+    "locale": { "requested": "en", "resolved": "en", "reason": "ok" }
+  },
   "url": "https://example.test/",
   "title": "Example",
   "timestamp": null,

package/docs/REPORT.md

@@ -15,6 +15,8 @@ Open `report.html` directly from disk. Works alongside any other output mode —
 - **WCAG rollup**: grouped by conformance level (A / AA / AAA), sourced directly from the engine's own `rulesResults[]` composite rollups (`docs/WCAG_CONFORMANCE.md`) — one row per Success Criterion, its outcome, a pass/fail/needs-review/n/a breakdown, and which atomic rules contributed. This is real engine data, not an invented grouping — the same rollup you'd get from the raw JSON's `rulesResults`.
 - **Full technical data** (collapsed by default): a scorecard (tiles per outcome) and a searchable, filterable (by outcome), paginated table of every individual occurrence across the whole scan.
 
+The meta bar under the header carries the rule count, occurrence count, engine tag, schema version, and the locale the scan resolved to. Locale fallback is per-string and invisible in the text itself, so a report requested in a language the engine does not carry reads as an ordinary English one — the chip names the requested locale alongside the resolved one when the two differ. See [`I18N.md`](./I18N.md).
+
 ## Library usage
 
 ```js

package/docs/RULE_AUTHORING.md

@@ -132,6 +132,10 @@ The build/runtime resolves i18n by:
 2) falling back to `en` if missing,
 3) falling back to the literal `title`/`description` strings if still missing.
 
+Add the key and its English text to `src/i18n/en.json`, then run
+`npm run i18n:sync` so every other locale picks it up. `npm test` fails if you
+forget. See [`I18N.md`](./I18N.md).
+
 #### `meta.tags`
 Tags are used for grouping/filtering. Typical tag families in this ruleset include:
 - WCAG tagging: `wcag2a`, `wcag111`
@@ -163,6 +167,32 @@ const meta = {
 
 ---
 
+## 4.3 Reporting an occurrence
+
+Build occurrences with `helpers.reportOccurrence(element, { summary, hint, i18n, data })`
+rather than assembling the object by hand:
+
+```js
+occurrences.push(helpers.reportOccurrence(el, { summary: '…', hint: '…' }));
+```
+
+It attaches the element for the engine to finalize, which is how `selector`,
+`html` and `structuralPath` get filled in centrally instead of in each of the
+124 rules.
+
+**This is a performance contract, not just a convenience.** Every occurrence
+gets a `structuralPath`. Given the element, the engine computes it directly.
+Given only a hand-built occurrence, it re-finds the element with
+`document.querySelector(selector)` — one DOM query per occurrence. That is
+fine for a rule reporting a single document-level finding, and quadratic for
+one reporting many: `region` hand-built its occurrences and took four minutes
+on a thousand-element page, against under a second afterwards.
+
+`perfStats.counters['structuralPath.selectorFallback']` counts how often the
+engine had to re-find an element, so a slow rule can be spotted without
+guessing. `tests/structural-path-fallback.test.js` fails if that count starts
+growing with page size.
+
 ## 5) i18n in occurrences (repo reality)
 
 Occurrences also support i18n via keys + params.
@@ -189,6 +219,29 @@ At normalization time, the engine:
 Translation strings use `{{paramName}}` placeholders.
 `params` is shallow-copied and passed into interpolation.
 
+**A param carries a value, never prose.** Element names, roles, attribute names,
+selectors, ids, counts and ratios are values: they read the same in every
+language, because the author will search their own source for them. An English
+word or sentence is not, and passing one means it stays English in every locale
+— with nothing to reveal it, since the key is present everywhere and coverage
+reports look complete.
+
+When a message varies by case, give each case its own key rather than
+interpolating the differing text:
+
+```js
+// wrong: the sentence lives in the rule, so no locale can reach it
+i18n: { hintKey: 'myRule_hint_fail', params: { advice: 'Replace it with role="list".' } }
+
+// right: one key per case, each translatable on its own
+i18n: { hintKey: 'myRule_hint_fail_directory', params: { role } }
+```
+
+`tests/i18n/i18n-translatable-strings.test.js` fails any dictionary value with
+no translatable text of its own, which catches the `"{{advice}}"` shape above.
+It cannot catch a param carrying prose into an otherwise-normal sentence, so
+that one is on you.
+
 ---
 
 ## 6) Helpers contract used by rules (ctx.helpers)

package/docs/TROUBLESHOOTING.md

@@ -2,7 +2,7 @@
 
 ## "I passed `runOnly: ['some-rule-id']` but every rule still ran"
 
-`runOnly` must be an object, not a bare array — `runOnly: ['img-alt-present']` is silently ignored (the engine falls through to "run everything"), because that shape has none of the fields the engine actually checks (`includeRuleIds`, `tags`, etc.). This is easy to get wrong if you're coming from another engine that does accept a bare array.
+`runOnly` must be an object, not a bare array — `runOnly: ['img-alt-present']` is silently ignored (the engine falls through to "run everything"), because that shape has none of the fields the engine actually checks (`includeRuleIds`, `tags`, etc.). A bare array is easy to reach for, so this is worth checking first.
 
 Fix:
 
@@ -41,7 +41,7 @@ Treat it as "needs a human to look" — it's neither pass nor fail by design. Mo
 
 ## "What happens if a locale is only partially translated?"
 
-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.
+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. Key parity is enforced rather than hoped for: `npm run i18n:sync` carries any new or renamed `en.json` key into every other locale file, and the build fails if one is out of step. A key it adds holds the English text until someone translates it, so a locale can be behind on wording without ever being behind on keys.
 
 ## "`runDomRulesInPage` vs `runa11yCoreInPage` — which one do I want?"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surea11y/core",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Deterministic WCAG 2.2 accessibility engine that tells you what it can't tell you. Zero dependencies.",
   "keywords": [
     "accessibility",
@@ -61,6 +61,7 @@
     "src/checks/**/*.js",
     "bin/surea11y-core.js",
     "surea11y.browser.js",
+    "surea11y.i18n.*.js",
     "docs/**/*.md",
     "README.md",
     "LICENSE",
@@ -87,11 +88,15 @@
     "test:typography-helpers": "node tests/contrast-typography.test.js",
     "coverage": "node scripts/generate-wcag-coverage.js --rulesDir src/checks",
     "coverage:strict": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --strictFacets",
+    "coverage:check": "node scripts/generate-wcag-coverage.js --rulesDir src/checks --check",
     "fixtures:index": "node scripts/generate-fixture-index.js",
     "docs:rule-catalog": "npm run build && node scripts/generate-rule-catalog.js",
     "validate:automatic-rules": "npm run build && node scripts/validate-all-rules.js src/checks/automatic",
     "validate:manual-rules": "npm run build && node scripts/validate-all-rules.js src/checks/manual",
+    "validate:rules": "npm run validate:automatic-rules && npm run validate:manual-rules",
     "i18n:new": "node scripts/i18n-scaffold.js",
+    "i18n:sync": "node scripts/i18n-sync.js",
+    "i18n:check": "node scripts/i18n-sync.js --check",
     "i18n:report": "node scripts/i18n-report.js"
   },
   "devDependencies": {

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

@@ -858,9 +858,6 @@ function runInPage(ctx) {
 
     if (!disallowed || !disallowed.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     for (const name of disallowed) {
       // A property ARIA deprecated (rather than prohibited) on this role is
       // still allowed — surfaced as cantTell for the author to decide, not a
@@ -869,38 +866,38 @@ function runInPage(ctx) {
         typeof ariaHelpers.isDeprecatedAttr === 'function' &&
         ariaHelpers.isDeprecatedAttr(name, role);
       if (deprecated) {
-        cantTellOccurrences.push({
-          selector: stableSelector,
-          html,
-          summary: 'This ARIA attribute is deprecated for this element’s role.',
-          hint: 'It is still allowed but discouraged; remove it or use a role that supports it, as a future ARIA version may disallow it.',
-          occurrenceOutcome: 'cantTell',
+        cantTellOccurrences.push(
+          helpers.reportOccurrence(el, {
+            summary: 'This ARIA attribute is deprecated for this element’s role.',
+            hint: 'It is still allowed but discouraged; remove it or use a role that supports it, as a future ARIA version may disallow it.',
+            occurrenceOutcome: 'cantTell',
+            i18n: {
+              summaryKey: 'ariaAllowedAttr_summary_cantTell',
+              hintKey: 'ariaAllowedAttr_hint_cantTell',
+              params: { attr: name, role }
+            },
+            data: {
+              details: { reasonCode: 'ARIA_ATTR_DEPRECATED', attr: name, role }
+            }
+          })
+        );
+        continue;
+      }
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This ARIA attribute is not permitted for this element’s role.',
+          hint: 'Remove this attribute, or use a role that supports it.',
+          occurrenceOutcome: 'fail',
           i18n: {
-            summaryKey: 'ariaAllowedAttr_summary_cantTell',
-            hintKey: 'ariaAllowedAttr_hint_cantTell',
+            summaryKey: 'ariaAllowedAttr_summary_fail',
+            hintKey: 'ariaAllowedAttr_hint_fail',
             params: { attr: name, role }
           },
           data: {
-            details: { reasonCode: 'ARIA_ATTR_DEPRECATED', attr: name, role }
+            details: { reasonCode: 'ARIA_ATTR_NOT_ALLOWED', attr: name, role }
           }
-        });
-        continue;
-      }
-      failOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This ARIA attribute is not permitted for this element’s role.',
-        hint: 'Remove this attribute, or use a role that supports it.',
-        occurrenceOutcome: 'fail',
-        i18n: {
-          summaryKey: 'ariaAllowedAttr_summary_fail',
-          hintKey: 'ariaAllowedAttr_hint_fail',
-          params: { attr: name, role }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ATTR_NOT_ALLOWED', attr: name, role }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -82,24 +82,22 @@ function runInPage(ctx) {
 
     if (info.allowed) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This role is not permitted on this element.',
-      hint: 'Use a role permitted for this element, or change the host element.',
-      i18n: {
-        summaryKey: 'ariaAllowedRole_summary_fail',
-        hintKey: 'ariaAllowedRole_hint_fail',
-        params: { role, element: tag }
-      },
-      data: {
-        details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This role is not permitted on this element.',
+        hint: 'Use a role permitted for this element, or change the host element.',
+        i18n: {
+          summaryKey: 'ariaAllowedRole_summary_fail',
+          hintKey: 'ariaAllowedRole_hint_fail',
+          params: { role, element: tag }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/aria-braille-equivalent.js

@@ -119,29 +119,27 @@ function runInPage(ctx) {
 
     if (!missing.length) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
     for (const m of missing) {
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
-        hint: `${m.attr} is a Braille-specific supplement, not a replacement — also provide ${m.requires}.`,
-        i18n: {
-          summaryKey: 'ariaBrailleEquivalent_summary_fail',
-          hintKey: 'ariaBrailleEquivalent_hint_fail',
-          params: { element: tag, attr: m.attr, requires: m.requires }
-        },
-        data: {
-          details: {
-            reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
-            attr: m.attr,
-            requires: m.requires
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
+          hint: `${m.attr} is a Braille-specific supplement, not a replacement — also provide ${m.requires}.`,
+          i18n: {
+            summaryKey: 'ariaBrailleEquivalent_summary_fail',
+            hintKey: 'ariaBrailleEquivalent_hint_fail',
+            params: { element: tag, attr: m.attr, requires: m.requires }
+          },
+          data: {
+            details: {
+              reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT',
+              attr: m.attr,
+              requires: m.requires
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

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

@@ -86,28 +86,26 @@ function runInPage(ctx) {
     const invalidValue = trim(el.getAttribute('aria-invalid')).toLowerCase();
     if (TRUTHY_INVALID_VALUES.has(invalidValue)) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This element has aria-errormessage but aria-invalid is missing or "false", so the error message is not exposed.',
-      hint: 'Set aria-invalid to "true" (or "grammar"/"spelling") whenever aria-errormessage should be exposed to assistive technology.',
-      i18n: {
-        summaryKey: 'ariaConditionalAttr_summary_fail',
-        hintKey: 'ariaConditionalAttr_hint_fail',
-        params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
-      },
-      data: {
-        details: {
-          reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
-          ariaInvalid: invalidValue
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This element has aria-errormessage but aria-invalid is missing or "false", so the error message is not exposed.',
+        hint: 'Set aria-invalid to "true" (or "grammar"/"spelling") whenever aria-errormessage should be exposed to assistive technology.',
+        i18n: {
+          summaryKey: 'ariaConditionalAttr_summary_fail',
+          hintKey: 'ariaConditionalAttr_hint_fail',
+          params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
+        },
+        data: {
+          details: {
+            reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID',
+            ariaInvalid: invalidValue
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/aria-deprecated-role.js

@@ -81,8 +81,20 @@ function runInPage(ctx) {
       if (typeof helpers.isDomVisibleEligible === 'function') {
         if (!helpers.isDomVisibleEligible(el, ctx)) return true;
       }
-      for (let n = el; n && n.getAttribute; n = n.parentElement) {
+      // Walk the composed tree, not parentElement: that stops at a shadow
+      // root, so a host carrying aria-hidden or inert would never be seen
+      // from inside its own shadow content.
+      const up =
+        typeof helpers.composedParent === 'function'
+          ? helpers.composedParent
+          : (n) => n.parentElement;
+
+      // A shadow root has no getAttribute, so skip past it rather than
+      // stopping: the host one step further up is the node that matters.
+      for (let n = el; n; n = up(n)) {
+        if (!n.getAttribute) continue;
         if (String(n.getAttribute('aria-hidden') || '').toLowerCase() === 'true') return true;
+        if (n.hasAttribute && n.hasAttribute('inert')) return true;
       }
     } catch {
       return false;
@@ -113,63 +125,64 @@ function runInPage(ctx) {
       ariaHelpers.isAuthorProhibitedRole(role);
     if (!deprecated && !discouraged && !prohibited) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const guidance = ariaHelpers.getDeprecatedRoleGuidance
       ? ariaHelpers.getDeprecatedRoleGuidance(role)
-      : 'Replace the deprecated role with its recommended replacement.';
+      : {
+          key: 'ariaDeprecatedRole_guidance_default',
+          text: 'Replace the deprecated role with its recommended replacement.'
+        };
 
     if (prohibited) {
       // Author MUST NOT: the usage is non-conforming, not merely discouraged.
-      failOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element uses role="${role}", which authors must not explicitly declare.`,
-        hint: guidance,
-        occurrenceOutcome: 'fail',
-        i18n: {
-          summaryKey: 'ariaDeprecatedRole_summary_fail',
-          hintKey: 'ariaDeprecatedRole_hint_fail',
-          params: { role, guidance }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ROLE_AUTHOR_PROHIBITED', role, guidance }
-        }
-      });
+      failOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which authors must not explicitly declare.`,
+          hint: guidance.text,
+          occurrenceOutcome: 'fail',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_fail',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_AUTHOR_PROHIBITED', role, guidance: guidance.text }
+          }
+        })
+      );
     } else if (discouraged) {
       // Reserved for user-agent-internal use, at SHOULD NOT strength.
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element uses role="${role}", which is reserved for user agents (still valid, but discouraged).`,
-        hint: guidance,
-        occurrenceOutcome: 'cantTell',
-        i18n: {
-          summaryKey: 'ariaDeprecatedRole_summary_cantTell_discouraged',
-          hintKey: 'ariaDeprecatedRole_hint_cantTell',
-          params: { role, guidance }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance }
-        }
-      });
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which is reserved for user agents (still valid, but discouraged).`,
+          hint: guidance.text,
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_cantTell_discouraged',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_AUTHOR_DISCOURAGED', role, guidance: guidance.text }
+          }
+        })
+      );
     } else {
       // Deprecated but still valid: surfaced for the author to decide.
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary: `This element uses role="${role}", which is deprecated in WAI-ARIA.`,
-        hint: guidance,
-        occurrenceOutcome: 'cantTell',
-        i18n: {
-          summaryKey: 'ariaDeprecatedRole_summary_cantTell',
-          hintKey: 'ariaDeprecatedRole_hint_cantTell',
-          params: { role, guidance }
-        },
-        data: {
-          details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance }
-        }
-      });
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element uses role="${role}", which is deprecated in WAI-ARIA.`,
+          hint: guidance.text,
+          occurrenceOutcome: 'cantTell',
+          i18n: {
+            summaryKey: 'ariaDeprecatedRole_summary_cantTell',
+            hintKey: guidance.key,
+            params: { role }
+          },
+          data: {
+            details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance: guidance.text }
+          }
+        })
+      );
     }
   }
 

package/src/checks/automatic/aria-hidden-body.js

@@ -86,15 +86,8 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(body)
-    : (body.outerHTML || '').slice(0, 200);
-
   const occurrences = [
-    {
-      selector: stableSelector,
-      html,
+    helpers.reportOccurrence(body, {
       summary:
         'The document body has aria-hidden="true", which hides the entire page from assistive technologies.',
       hint: 'Remove aria-hidden from <body>. Hide specific elements instead, if that was the intent.',
@@ -106,7 +99,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'ARIA_HIDDEN_BODY' }
       }
-    }
+    })
   ];
 
   return {