@surea11y/core 1.4.1 → 1.6.0

package/src/checks/automatic/css-orientation-lock.js

@@ -9,13 +9,13 @@
  * @standard WCAG 2.2
  * @sc 1.3.4
  * @applicability
- *   Any accessible (same-document, non-cross-origin) stylesheet — inline
+ *   Any accessible (same-document, non-cross-origin) stylesheet, inline
  *   `<style>` blocks and same-origin `<link>` stylesheets already loaded
  *   into `document.styleSheets`.
  * @expectation
  *   No `@media (orientation: portrait)` or `@media (orientation:
  *   landscape)` block sets a `transform`/`-webkit-transform`/`rotate`
- *   rotation of approximately 90 degrees (mod 180, i.e. ~90 or ~270) —
+ *   rotation of approximately 90 degrees (mod 180, i.e. ~90 or ~270),
  *   the well-known technique for visually forcing one orientation
  *   regardless of the device's actual orientation, which defeats WCAG
  *   1.3.4's requirement that content not restrict its view to a single
@@ -27,14 +27,15 @@
  *   lock. Compute the actual rotation angle and only flag ~90/~270 degrees,
  *   excluding ~0/~180 (a no-op or a flip, neither of which changes
  *   portrait<->landscape).
- * - Only `rotate`/`rotateZ` (transform functions) and the standalone CSS
- *   `rotate` property are parsed for degrees, from the two sources
- *   `style.transform`/`style.rotate`; `matrix()`/`matrix3d()`/`rotate3d()`
- *   are not decomposed into an equivalent angle (deliberately deferred as
- *   the same class of higher-complexity/lower-value work deferred elsewhere,
- *   e.g. `table-th-has-data-cells`'s narrower positional-header algorithm).
+ * - `rotate`/`rotateZ`, the standalone CSS `rotate` property, and
+ *   `rotate3d(x, y, z, angle)`/`matrix()`/`matrix3d()` are all parsed for
+ *   degrees. The matrix forms only yield an angle when they resolve to a
+ *   pure rotation about the Z axis (no scale, skew, translation, or
+ *   rotation combined with another axis). Anything else contributes 0,
+ *   same as an unrecognized value, rather than guessing at an angle a
+ *   general 3D matrix doesn't uniquely have.
  * - Cross-origin stylesheets throw on `.cssRules` access (browser
- *   security model) and are skipped — same class of limitation as any
+ *   security model) and are skipped, same class of limitation as any
  *   check that can only see same-origin/inspectable content (compare
  *   `iframe-focusable-content`).
  * - Not per-element: this is a whole-document/whole-stylesheet concern,
@@ -107,25 +108,98 @@ function runInPage(ctx) {
     return value; // deg
   }
 
-  // Sums the degrees of every rotate()/rotateZ() function found in a
-  // transform value (a real transform can legitimately compose more than
-  // one, e.g. "translate(-50%) rotate(90deg)").
+  function parseNumberList(argsStr) {
+    return trim(argsStr)
+      .split(',')
+      .map((s) => parseFloat(s.trim()));
+  }
+
+  // A 2D linear map (a, b, c, d) -- the first four arguments of
+  // `matrix(a, b, c, d, e, f)`, or the top-left of `matrix3d`'s 4x4 --
+  // is a pure rotation only when its columns are unit length and
+  // orthogonal (no scale/skew/reflection): a = cos(theta), b = sin(theta),
+  // c = -sin(theta), d = cos(theta). Returns degrees, or null when the
+  // map isn't a pure rotation.
+  function decomposeMatrix2dRotation(a, b, c, d) {
+    const EPS = 1e-3;
+    if (Math.abs(a - d) > EPS || Math.abs(b + c) > EPS) return null;
+    if (Math.abs(a * a + b * b - 1) > EPS) return null;
+    if (Math.abs(a * d - b * c - 1) > EPS) return null;
+    return (Math.atan2(b, a) * 180) / Math.PI;
+  }
+
+  // The 16 column-major values of `matrix3d(...)` represent a pure Z-axis
+  // rotation only when the 3rd/4th columns still match the identity (no
+  // translation, perspective, or rotation around another axis) and the
+  // top-left 2x2 block is a pure 2D rotation.
+  function decomposeMatrix3dZRotation(v) {
+    if (v.length !== 16 || !v.every(Number.isFinite)) return null;
+    const EPS = 1e-3;
+    const near = (x, t) => Math.abs(x - t) < EPS;
+    if (!(near(v[2], 0) && near(v[3], 0) && near(v[6], 0) && near(v[7], 0))) return null;
+    if (!(near(v[8], 0) && near(v[9], 0) && near(v[10], 1) && near(v[11], 0))) return null;
+    if (!(near(v[12], 0) && near(v[13], 0) && near(v[14], 0) && near(v[15], 1))) return null;
+    return decomposeMatrix2dRotation(v[0], v[1], v[4], v[5]);
+  }
+
+  // Sums the degrees of every rotate()/rotateZ()/rotate3d()/matrix()/
+  // matrix3d() function found in a transform value (a real transform can
+  // legitimately compose more than one, e.g. "translate(-50%)
+  // rotate(90deg)"). The matrix forms only contribute when they decompose
+  // to a pure Z rotation; anything else contributes 0, same as no match.
   function rotateDegreesFromTransform(t) {
     if (!t) return 0;
     let total = 0;
-    const re = /rotate(?:Z)?\s*\(([^)]*)\)/gi;
     let m;
-    while ((m = re.exec(t)) !== null) {
+
+    const rotateRe = /rotate(?:Z)?\s*\(([^)]*)\)/gi;
+    while ((m = rotateRe.exec(t)) !== null) {
       total += angleToDegrees(m[1]);
     }
+
+    const rotate3dRe = /rotate3d\s*\(([^)]*)\)/gi;
+    while ((m = rotate3dRe.exec(t)) !== null) {
+      const parts = m[1].split(',');
+      if (parts.length !== 4) continue;
+      const x = parseFloat(parts[0]);
+      const y = parseFloat(parts[1]);
+      const z = parseFloat(parts[2]);
+      const deg = angleToDegrees(parts[3]);
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z) || !deg) continue;
+      const EPS = 1e-3;
+      if (Math.abs(x) < EPS && Math.abs(y) < EPS && Math.abs(Math.abs(z) - 1) < EPS) {
+        total += z < 0 ? -deg : deg;
+      }
+    }
+
+    const matrixRe = /matrix\s*\(([^)]*)\)/gi;
+    while ((m = matrixRe.exec(t)) !== null) {
+      const vals = parseNumberList(m[1]);
+      if (vals.length === 6 && vals.every(Number.isFinite)) {
+        const deg = decomposeMatrix2dRotation(vals[0], vals[1], vals[2], vals[3]);
+        if (deg != null) total += deg;
+      }
+    }
+
+    const matrix3dRe = /matrix3d\s*\(([^)]*)\)/gi;
+    while ((m = matrix3dRe.exec(t)) !== null) {
+      const deg = decomposeMatrix3dZRotation(parseNumberList(m[1]));
+      if (deg != null) total += deg;
+    }
+
     return total;
   }
 
   // Whole-page-orientation-lock detection (see @implementation-notes): a
   // rotation near 0 or 180 degrees (mod 180) is a no-op or a flip, neither
   // of which changes portrait<->landscape, so it's NOT a lock; only a
-  // rotation near 90 or 270 degrees (mod 90, once the 0/180 case is
-  // excluded) is.
+  // rotation near 90 or 270 degrees is. "Near" is a tolerance window, not
+  // exact equality: a `rad`/`grad`/`turn` value converts to a 90-degree
+  // rotation with floating-point remainder (e.g. `1.5708rad` is
+  // 90.0000210...deg, never exactly 90), and ACT's own failed examples
+  // include a -inexact 92.5deg, both must still register as a
+  // lock, which exact-modulo-equality (`% 90 === 0`) never does.
+  const LOCK_TOLERANCE_DEG = 5;
   function isLockingRotation(styleDecl) {
     if (!styleDecl) return false;
     const transformVal =
@@ -141,9 +215,12 @@ function runInPage(ctx) {
 
     if (!degrees) return false;
 
-    const abs = Math.abs(degrees);
-    if (Math.abs(abs - 180) % 180 <= 0) return false; // near 0/180: not a lock
-    return Math.abs(abs - 90) % 90 <= 0; // near 90/270: a lock
+    // Normalize into [0, 180): a rotation and its mirror (rotation + 180)
+    // swap the same two axes, so only the position within one half-turn
+    // matters. A value near the 90-degree midpoint of that range is near
+    // 90 OR 270 in the original full-turn range.
+    const normalized = ((degrees % 180) + 180) % 180;
+    return Math.abs(normalized - 90) <= LOCK_TOLERANCE_DEG;
   }
 
   function isOrientationMedia(mediaText) {
@@ -156,7 +233,7 @@ function runInPage(ctx) {
     for (const r of rules) {
       if (!r) continue;
       if (r.type === CSS_STYLE_RULE && isLockingRotation(r.style)) {
-        findings.push({ mediaText, selectorText: trim(r.selectorText) || '(unknown selector)' });
+        findings.push({ mediaText, selectorText: trim(r.selectorText) });
       }
     }
   }
@@ -196,28 +273,28 @@ function runInPage(ctx) {
   }
 
   const target = document.documentElement || document.body || null;
-  const stableSelector = helpers.buildSelector && target ? helpers.buildSelector(target) : 'html';
-  const html =
-    helpers.getOuterHtmlSnippet && target ? helpers.getOuterHtmlSnippet(target) : '<html>';
-
-  const occurrences = findings.map((f) => ({
-    selector: stableSelector,
-    html,
-    summary: `A "${f.mediaText}" media query rotates "${f.selectorText}", locking the page to one orientation.`,
-    hint: 'Remove the rotate() transform from the orientation media query; let the page respond naturally to device orientation instead of forcing a visual rotation.',
-    i18n: {
-      summaryKey: 'cssOrientationLock_summary_fail',
-      hintKey: 'cssOrientationLock_hint_fail',
-      params: { mediaText: f.mediaText, selectorText: f.selectorText }
-    },
-    data: {
-      details: {
-        reasonCode: 'ORIENTATION_MEDIA_ROTATE_TRANSFORM',
-        mediaText: f.mediaText,
-        selectorText: f.selectorText
+  const occurrences = findings.map((f) =>
+    helpers.reportOccurrence(target, {
+      summary: f.selectorText
+        ? `A "${f.mediaText}" media query rotates "${f.selectorText}", locking the page to one orientation.`
+        : `A "${f.mediaText}" media query rotates an element with no readable selector, locking the page to one orientation.`,
+      hint: 'Remove the rotate() transform from the orientation media query; let the page respond naturally to device orientation instead of forcing a visual rotation.',
+      i18n: {
+        summaryKey: f.selectorText
+          ? 'cssOrientationLock_summary_fail'
+          : 'cssOrientationLock_summary_fail_unknownSelector',
+        hintKey: 'cssOrientationLock_hint_fail',
+        params: { mediaText: f.mediaText, selectorText: f.selectorText }
+      },
+      data: {
+        details: {
+          reasonCode: 'ORIENTATION_MEDIA_ROTATE_TRANSFORM',
+          mediaText: f.mediaText,
+          selectorText: f.selectorText
+        }
       }
-    }
-  }));
+    })
+  );
 
   return {
     ruleId: rule.ruleId,

package/src/checks/automatic/definition-list-children-valid.js

@@ -16,17 +16,16 @@
  *   level of wrapping div is allowed, matching how authors commonly group
  *   dt/dd pairs). If the flattened set contains any <dt> or <dd> at all, it
  *   must contain BOTH (an unbalanced dt-without-dd or dd-without-dt is
- *   invalid) — a flattened set with neither is vacuously fine, not a
+ *   invalid). A flattened set with neither is vacuously fine, not a
  *   violation (see implementation-notes). Any other direct or wrapped child
  *   breaks the description-list semantics assistive technologies rely on.
  * @implementation-notes
- * - Only one level of <div> wrapping is flattened — a <div> nested inside
+ * - Only one level of <div> wrapping is flattened, a <div> nested inside
  *   another wrapping <div> is not flattened further and its contents are
  *   reported invalid.
  * - The dt/dd pairing is only required "when not empty". A flattened set
- *   with NEITHER dt nor dd
- *   — whether from an empty wrapping <div>, only <script>/<template>/
- *   <style> content, or a genuinely childless <dl> — is not flagged; only
+ *   with NEITHER dt nor dd, whether from an empty wrapping <div>, only
+ *   <script>/<template>/<style> content, or a childless <dl>, is not flagged; only
  *   an unbalanced dt/dd pairing is a real structural problem.
  * - Distinct, atomic decision from dlitem-parent-valid (the
  *   inverse relationship: does a given <dt>/<dd> have a valid parent).
@@ -64,7 +63,7 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const PASSTHROUGH_TAGS = new Set(['dt', 'dd', 'script', 'template', 'style']);
 
@@ -109,8 +108,8 @@ function runInPage(ctx) {
     }
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
-    // The dt/dd pairing is only required "when not empty" — a <dl> with
-    // NEITHER dt nor dd (whether genuinely childless after flattening, only
+    // The dt/dd pairing is only required "when not empty", a <dl> with
+    // NEITHER dt nor dd (whether childless after flattening, only
     // passthrough script/template/style content, or an empty wrapping div)
     // is vacuously fine, not a violation. Only an UNBALANCED pairing (dt
     // present without any dd, or vice versa) is a real structural problem.
@@ -121,9 +120,6 @@ function runInPage(ctx) {
         : null;
     if (!reasonCode) continue;
 
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
     const summary = invalidTags.length
       ? 'This description list contains a direct or wrapped child that is not part of a dt/dd group.'
       : 'This description list has no <dt>/<dd> term-definition group.';
@@ -131,24 +127,24 @@ function runInPage(ctx) {
       ? 'Only use <dt>/<dd> (optionally wrapped in one <div>), <script>, <template>, or <style> inside <dl>.'
       : 'Add at least one <dt>/<dd> pair inside this <dl>.';
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary,
-      hint,
-      i18n: {
-        summaryKey: invalidTags.length
-          ? 'definitionListChildrenValid_summary_fail_invalidChild'
-          : 'definitionListChildrenValid_summary_fail_noDtDd',
-        hintKey: invalidTags.length
-          ? 'definitionListChildrenValid_hint_fail_invalidChild'
-          : 'definitionListChildrenValid_hint_fail_noDtDd',
-        params: { invalidChildren: dedupedInvalidTags.join(', ') }
-      },
-      data: {
-        details: { reasonCode, invalidChildren: invalidTags }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary,
+        hint,
+        i18n: {
+          summaryKey: invalidTags.length
+            ? 'definitionListChildrenValid_summary_fail_invalidChild'
+            : 'definitionListChildrenValid_summary_fail_noDtDd',
+          hintKey: invalidTags.length
+            ? 'definitionListChildrenValid_hint_fail_invalidChild'
+            : 'definitionListChildrenValid_hint_fail_noDtDd',
+          params: { invalidChildren: dedupedInvalidTags.join(', ') }
+        },
+        data: {
+          details: { reasonCode, invalidChildren: invalidTags }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -15,7 +15,7 @@
  *   or hide it.
  * @expectation
  *   Neither element is present. Since their movement can never be paused,
- *   stopped, or hidden by the user, presence is itself the violation — this
+ *   stopped, or hidden by the user, presence is itself the violation. This
  *   rule has no partial-pass case (it reports only when the element is
  *   found).
  * @implementation-notes
@@ -72,23 +72,21 @@ function runInPage(ctx) {
     applicableCount += 1;
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This element’s content cannot be paused, stopped, or hidden by the user.',
-      hint: 'Remove this element; use static content, or an animation with a user-facing pause/stop control, instead.',
-      i18n: {
-        summaryKey: 'deprecatedElements_summary_fail',
-        hintKey: 'deprecatedElements_hint_fail',
-        params: { element: tag }
-      },
-      data: {
-        details: { reasonCode: 'DEPRECATED_NON_STOPPABLE_ELEMENT', element: tag }
-      }
-    });
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This element’s content cannot be paused, stopped, or hidden by the user.',
+        hint: 'Remove this element; use static content, or an animation with a user-facing pause/stop control, instead.',
+        i18n: {
+          summaryKey: 'deprecatedElements_summary_fail',
+          hintKey: 'deprecatedElements_hint_fail',
+          params: { element: tag }
+        },
+        data: {
+          details: { reasonCode: 'DEPRECATED_NON_STOPPABLE_ELEMENT', element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/dialog-name-present.js

@@ -2,6 +2,24 @@
 
 'use strict';
 
+/**
+ * @check dialog-name-present
+ * @atomic true
+ * @summary Elements with role="dialog"/"alertdialog" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="dialog" or role="alertdialog" (the
+ *   attribute must name one of those roles alone, not a fallback list) that
+ *   are included in the accessibility tree. A native <dialog> without an
+ *   explicit role is out of scope.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, or from title. Both
+ *   roles are name-from-author-only, so the heading or body text inside the
+ *   dialog is not accepted as its name unless aria-labelledby points at it.
+ */
+
 const id = 'dialog-name-present';
 
 const meta = {
@@ -54,13 +72,13 @@ function runInPage(ctx) {
   function resolveAriaLabelledbyText(document, el, maxRefs) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
-    // Resolve via the shared getTextFromIdRefs helper — computes each
+    // Resolve via the shared getTextFromIdRefs helper, computes each
     // referenced element's own ACCESSIBLE NAME (aria-label, then
     // aria-labelledby, then a value-like name, then content, then title),
     // not just its content text. This matters when aria-labelledby points
     // at an <iframe title="..."> (e.g. BBC News' cookie-consent dialog,
     // pointing at an `<iframe title="SP Consent Message">`), whose only
-    // name source is its title attribute — an iframe's content is
+    // name source is its title attribute, an iframe's content is
     // opaque/cross-origin per HTML-AAM, so "name from content" is always
     // empty. Computing only name-from-content of the referenced node would
     // silently miss the title fallback and report no accessible name at
@@ -140,24 +158,22 @@ function runInPage(ctx) {
           }
         })()
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This dialog has no accessible name.',
-      hint: 'Provide aria-labelledby (preferred) or aria-label so assistive technologies can announce the dialog.',
-      i18n: {
-        summaryKey: 'dialogNamePresent_summary_fail',
-        hintKey: 'dialogNamePresent_hint_fail',
-        params: { role }
-      },
-      data: {
-        details: { reasonCode: 'name_missing', controlType: role, methodTried: res.method },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This dialog has no accessible name.',
+        hint: 'Provide aria-labelledby (preferred) or aria-label so assistive technologies can announce the dialog.',
+        i18n: {
+          summaryKey: 'dialogNamePresent_summary_fail',
+          hintKey: 'dialogNamePresent_hint_fail',
+          params: { role }
+        },
+        data: {
+          details: { reasonCode: 'name_missing', controlType: role, methodTried: res.method },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/dlitem-parent-valid.js

@@ -80,23 +80,21 @@ function runInPage(ctx) {
     if (valid) continue;
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
-
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary: 'This description-list item is not contained by a <dl>.',
-      hint: 'Place this <dt>/<dd> inside a <dl>, directly or wrapped in a single <div>.',
-      i18n: {
-        summaryKey: 'dlitemParentValid_summary_fail',
-        hintKey: 'dlitemParentValid_hint_fail',
-        params: { element: tag, parentElement: parentTag }
-      },
-      data: {
-        details: { reasonCode: 'DLITEM_INVALID_PARENT', element: tag, parentElement: parentTag }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This description-list item is not contained by a <dl>.',
+        hint: 'Place this <dt>/<dd> inside a <dl>, directly or wrapped in a single <div>.',
+        i18n: {
+          summaryKey: 'dlitemParentValid_summary_fail',
+          hintKey: 'dlitemParentValid_hint_fail',
+          params: { element: tag, parentElement: parentTag }
+        },
+        data: {
+          details: { reasonCode: 'DLITEM_INVALID_PARENT', element: tag, parentElement: parentTag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/duplicate-id-aria.js

@@ -15,15 +15,18 @@
  *   attribute (i.e. at least one ARIA ID reference exists to resolve).
  * @expectation
  *   For every id value referenced by one of those attributes, exactly one
- *   element in the document carries that id. A duplicated id referenced by
- *   ARIA is ambiguous: assistive technologies cannot reliably determine
- *   which element the reference resolves to (typically the first, silently
- *   dropping the others).
+ *   element in the document carries that id. A duplicate does not break the
+ *   reference: it resolves to the first element in tree order, so the name is
+ *   still computed. Whether that element is the intended target depends on
+ *   author intent, which markup does not carry, so the outcome is cantTell.
  * @implementation-notes
- * - Scoped deliberately to ids referenced by ARIA, not the broader/
- *   deprecated page-wide duplicate-id check (see ROADMAP.md's "Skip" list).
+ * - Scoped to ids referenced by ARIA. The page-wide check
+ *   lives in its own rule, `duplicate-id`, mapped to the WCAG 2.0/2.1 SC
+ *   4.1.1 that WCAG 2.2 removed; the two overlap on referenced ids and
+ *   answer different questions there (see that rule's header).
  * - Document-wide by design: id uniqueness and ARIA id references are a
- *   whole-document property, not scoped to a sub-root.
+ *   whole-document property, not scoped to a sub-root. Reported occurrences are
+ *   limited to the scanned scope.
  */
 
 const id = 'duplicate-id-aria';
@@ -58,7 +61,7 @@ const meta = {
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const IDREF_ATTRS = [
     'aria-labelledby',
@@ -95,51 +98,58 @@ function runInPage(ctx) {
     }
   }
 
-  const occurrences = [];
+  // Detection is document-wide; occurrences are limited to the scanned scope.
+  let inScope = null;
+  if (helpers && typeof helpers.queryAllSmart === 'function') {
+    try {
+      const scoped = helpers.queryAllSmart('[id]');
+      inScope = new Set(Array.isArray(scoped) ? scoped : Array.from(scoped || []));
+    } catch {
+      inScope = null;
+    }
+  }
+
+  const cantTellOccurrences = [];
 
   for (const refId of referencedIds) {
     const els = idMap.get(refId) || [];
     if (els.length <= 1) continue;
 
     for (const el of els) {
-      const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
-
-      occurrences.push({
-        selector: stableSelector,
-        html,
-        summary: 'This id is referenced by an ARIA attribute but is used by more than one element.',
-        hint: 'Make ids referenced by ARIA attributes unique within the document.',
-        i18n: {
-          summaryKey: 'duplicateIdAria_summary_fail',
-          hintKey: 'duplicateIdAria_hint_fail',
-          params: { id: refId, duplicateCount: String(els.length) }
-        },
-        data: {
-          details: {
-            reasonCode: 'DUPLICATE_ID_ARIA_REFERENCED',
-            id: refId,
-            duplicateCount: els.length
+      if (inScope && !inScope.has(el)) continue;
+
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This id is referenced by an ARIA attribute but is used by more than one element; the reference resolves to the first.',
+          hint: 'Confirm the first element carrying this id is the intended target, or make the id unique.',
+          i18n: {
+            summaryKey: 'duplicateIdAria_summary_cantTell',
+            hintKey: 'duplicateIdAria_hint_cantTell',
+            params: { id: refId, duplicateCount: String(els.length) }
+          },
+          data: {
+            details: {
+              reasonCode: 'DUPLICATE_ID_ARIA_REFERENCED',
+              id: refId,
+              duplicateCount: els.length
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 
   if (referencedIds.size === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+
+  const resolved = helpers.resolveTieredOutcome(
+    [],
+    cantTellOccurrences,
+    rule.defaultSeverity || 'serious'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };