@surea11y/core 1.2.0 → 1.4.0

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'tab-name-present';
@@ -10,10 +12,16 @@ const meta = {
     descriptionKey: 'tabNamePresent_description'
   },
   helpUrl: null,
-  tags: ['wcag2a','wcag412','navigation','atomic','automatic','name','tab'],
+  tags: ['wcag2a', 'wcag412', 'navigation', 'atomic', 'automatic', 'name', 'tab'],
   wcagSc: ['4.1.2'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'robust',
@@ -24,53 +32,22 @@ const meta = {
 
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
-  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
-      ? helpers.getEligibilityInfo
-      : null;
-
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
   }
 
   function getAttr(el, name) {
     try {
       if (!el || !el.getAttribute) return '';
       return normalizeWs(el.getAttribute(name));
-    } catch { return ''; }
-  }
-
-  function hasAttr(el, name) {
-    try { return !!(el && el.hasAttribute && el.hasAttribute(name)); } catch { return false; }
-  }
-
-  function isExplicitProgrammatic(el) {
-    // Programmatic name mechanisms we treat as authoritative (presence-only):
-    // - aria-label (non-empty)
-    // - aria-labelledby (non-empty)
-    // - title (non-empty) [weak but allowed for presence]
-    const al = getAttr(el, 'aria-label');
-    if (al) return true;
-    const alb = getAttr(el, 'aria-labelledby');
-    if (alb) return true;
-    const t = getAttr(el, 'title');
-    if (t) return true;
-    return false;
-  }
-
-  function buildLabelForMap(doc) {
-    const map = new Map(); // id -> label element (first)
-    try {
-      const labels = doc && doc.getElementsByTagName ? doc.getElementsByTagName('label') : [];
-      for (let i = 0; i < labels.length; i += 1) {
-        const lab = labels[i];
-        if (!lab || !lab.getAttribute) continue;
-        const f = normalizeWs(lab.getAttribute('for'));
-        if (!f) continue;
-        if (!map.has(f)) map.set(f, lab);
-      }
-    } catch {}
-    return map;
+    } catch {
+      return '';
+    }
   }
 
   function getConservativeSubtreeText(document, container) {
@@ -85,7 +62,7 @@ function runInPage(ctx) {
       const info = helpers.getContentNameInfo(container, ctx);
       return info && info.present ? info.value : '';
     }
-    const t = (container && container.textContent) ? String(container.textContent) : '';
+    const t = container && container.textContent ? String(container.textContent) : '';
     return t.replace(/\s+/g, ' ').trim();
   }
 
@@ -106,17 +83,9 @@ function runInPage(ctx) {
     return '';
   }
 
-  function getInputValueName(el) {
-    try {
-      const type = getAttr(el, 'type').toLowerCase();
-      if (type !== 'button' && type !== 'submit' && type !== 'reset') return '';
-      const v = getAttr(el, 'value');
-      return v;
-    } catch { return ''; }
-  }
-
   function isEligibleAcc(helpers, el, ctx) {
-    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    const fn =
+      helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
     if (!fn) return true;
     try {
       const r = fn(el, ctx);
@@ -127,13 +96,13 @@ function runInPage(ctx) {
     }
   }
 
-
   const occurrences = [];
   let applicableCount = 0;
 
   const selector = '[role="tab"]';
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector) : helpers.queryAll(selector);
-
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart(selector)
+    : helpers.queryAll(selector);
 
   function evaluate(el) {
     const ariaLabel = getAttr(el, 'aria-label');
@@ -164,10 +133,16 @@ function runInPage(ctx) {
     if (res.ok) continue;
 
     const eligInfo = getEligibilityInfo
-        ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
-        : null;
+      ? (() => {
+          try {
+            return getEligibilityInfo(el, ctx, { targetSet: 'acc' });
+          } catch {
+            return null;
+          }
+        })()
+      : null;
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     occurrences.push({
       selector: stableSelector,
@@ -186,12 +161,16 @@ function runInPage(ctx) {
     });
   }
 
-
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }

package/src/checks/automatic/table-headers-attr-valid.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -14,8 +16,7 @@
  *   the referencing cell, and (d) is not the cell itself.
  * @implementation-notes
  * - One occurrence per offending cell (not per bad token), listing every
- *   invalid reference — matches a widely-used reference engine's
- *   td-headers-attr reporting granularity.
+ *   invalid reference.
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
@@ -25,7 +26,8 @@ const id = 'table-headers-attr-valid';
 
 const meta = {
   title: 'Table cell "headers" attribute must reference valid header cells',
-  description: 'Checks that each id in a <td>/<th> headers attribute resolves to a <th> element within the same table (not missing, not a non-th element, not itself).',
+  description:
+    'Checks that each id in a <td>/<th> headers attribute resolves to a <th> element within the same table (not missing, not a non-th element, not itself).',
   i18n: {
     titleKey: 'tableHeadersAttrValid_title',
     descriptionKey: 'tableHeadersAttrValid_description'
@@ -34,7 +36,13 @@ const meta = {
   tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'table'],
   wcagSc: ['1.3.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'serious',
   category: 'perceivable',
@@ -46,7 +54,9 @@ const meta = {
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('td[headers], th[headers]') : helpers.queryAll('td[headers], th[headers]');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('td[headers], th[headers]')
+    : helpers.queryAll('td[headers], th[headers]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -65,7 +75,7 @@ function runInPage(ctx) {
     const invalid = [];
 
     for (const headerId of ids) {
-      let ref = null;
+      let ref;
       try {
         ref = document.getElementById(headerId);
       } catch {
@@ -91,9 +101,11 @@ function runInPage(ctx) {
 
     if (!invalid.length) continue;
 
+    const dedupedInvalidIds = [...new Set(invalid.map((i) => i.id))];
+
     const tag = el.tagName.toLowerCase();
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
     occurrences.push({
       selector: stableSelector,
@@ -103,7 +115,7 @@ function runInPage(ctx) {
       i18n: {
         summaryKey: 'tableHeadersAttrValid_summary_fail',
         hintKey: 'tableHeadersAttrValid_hint_fail',
-        params: { element: tag, invalidIds: invalid.map((i) => i.id).join(', ') }
+        params: { element: tag, invalidIds: dedupedInvalidIds.join(', ') }
       },
       data: {
         details: { reasonCode: 'TABLE_HEADERS_ATTR_INVALID', element: tag, invalid }
@@ -115,9 +127,14 @@ function runInPage(ctx) {
     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: 'fail',
+      severity: rule.defaultSeverity || 'serious',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/table-th-has-data-cells.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -37,7 +39,8 @@ const id = 'table-th-has-data-cells';
 
 const meta = {
   title: '<th> elements must describe at least one data cell',
-  description: 'Checks that a table containing <th> elements also contains at least one <td> data cell for those headers to describe.',
+  description:
+    'Checks that a table containing <th> elements also contains at least one <td> data cell for those headers to describe.',
   i18n: {
     titleKey: 'tableThHasDataCells_title',
     descriptionKey: 'tableThHasDataCells_description'
@@ -46,7 +49,13 @@ const meta = {
   tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'table'],
   wcagSc: ['1.3.1'],
   normativeMappings: [
-    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.3.1',
+      title: 'Info and Relationships',
+      conformanceLevel: 'A'
+    }
   ],
   defaultSeverity: 'moderate',
   category: 'perceivable',
@@ -56,7 +65,7 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   const tables = helpers.queryAllSmart ? helpers.queryAllSmart('table') : helpers.queryAll('table');
 
@@ -66,7 +75,7 @@ function runInPage(ctx) {
   for (const table of tables) {
     if (!table || !table.querySelectorAll) continue;
 
-    let ths = [];
+    let ths;
     try {
       ths = table.querySelectorAll('th');
     } catch {
@@ -76,7 +85,7 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    let hasDataCell = false;
+    let hasDataCell;
     try {
       hasDataCell = table.querySelectorAll('td').length > 0;
     } catch {
@@ -87,7 +96,9 @@ function runInPage(ctx) {
     for (const th of ths) {
       if (!th) continue;
       const stableSelector = helpers.buildSelector ? helpers.buildSelector(th) : 'html';
-      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(th) : (th.outerHTML || '');
+      const html = helpers.getOuterHtmlSnippet
+        ? helpers.getOuterHtmlSnippet(th)
+        : th.outerHTML || '';
 
       occurrences.push({
         selector: stableSelector,
@@ -110,9 +121,14 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'moderate', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'fail',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 
-module.exports = { id, meta, runInPage };
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/target-size-minimum.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -60,13 +62,23 @@ const id = 'target-size-minimum';
 const meta = {
   title: 'Pointer targets meet minimum size (AA)',
   description:
-      'Checks that pointer-operable targets have an effective hit region of at least 24 by 24 CSS pixels, or meet an allowed exception (e.g. sufficient spacing).',
+    'Checks that pointer-operable targets have an effective hit region of at least 24 by 24 CSS pixels, or meet an allowed exception (e.g. sufficient spacing).',
   i18n: {
     titleKey: 'targetSizeMinimum_title',
     descriptionKey: 'targetSizeMinimum_description'
   },
   helpUrl: null,
-  tags: ['wcag22aa', 'wcag258', 'navigation', 'operable', 'pointer', 'target-size', 'atomic', 'automatic', 'dom'],
+  tags: [
+    'wcag22aa',
+    'wcag258',
+    'navigation',
+    'operable',
+    'pointer',
+    'target-size',
+    'atomic',
+    'automatic',
+    'dom'
+  ],
   wcagSc: ['2.5.8'],
   normativeMappings: [
     {
@@ -115,8 +127,10 @@ function runInPage(ctx) {
   // with its own .querySelectorAll to call directly.
   function qsa(sel) {
     try {
-      if (helpers && typeof helpers.queryAllSmart === 'function') return Array.from(helpers.queryAllSmart(sel) || []);
-      if (helpers && typeof helpers.queryAll === 'function') return Array.from(helpers.queryAll(sel) || []);
+      if (helpers && typeof helpers.queryAllSmart === 'function')
+        return Array.from(helpers.queryAllSmart(sel) || []);
+      if (helpers && typeof helpers.queryAll === 'function')
+        return Array.from(helpers.queryAll(sel) || []);
       return [];
     } catch {
       return [];
@@ -135,10 +149,11 @@ function runInPage(ctx) {
 
   function htmlSnippet(el) {
     try {
-      if (helpers && typeof helpers.getOuterHtmlSnippet === 'function') return helpers.getOuterHtmlSnippet(el);
+      if (helpers && typeof helpers.getOuterHtmlSnippet === 'function')
+        return helpers.getOuterHtmlSnippet(el);
     } catch {}
     try {
-      return (el && el.outerHTML) ? String(el.outerHTML) : '';
+      return el && el.outerHTML ? String(el.outerHTML) : '';
     } catch {}
     return '';
   }
@@ -153,8 +168,14 @@ function runInPage(ctx) {
       if (!el || el.nodeType !== 1) return false;
 
       const tag = (el.tagName || '').toLowerCase();
-      const role = (el.getAttribute && String(el.getAttribute('role') || '').trim().toLowerCase()) || '';
-      const isLinkLike = (tag === 'a' && el.getAttribute && el.getAttribute('href')) || role === 'link';
+      const role =
+        (el.getAttribute &&
+          String(el.getAttribute('role') || '')
+            .trim()
+            .toLowerCase()) ||
+        '';
+      const isLinkLike =
+        (tag === 'a' && el.getAttribute && el.getAttribute('href')) || role === 'link';
       if (!isLinkLike) return false;
 
       const cs = getStyle(el);
@@ -164,11 +185,11 @@ function runInPage(ctx) {
       // Inline exception is for inline text runs; many design systems use inline-block for links,
       // so treat inline-block variants as eligible for this exception.
       const isInline =
-          display === 'inline' ||
-          display === 'inline-block' ||
-          display === 'inline-flex' ||
-          display === 'inline-grid' ||
-          display === 'inline-table';
+        display === 'inline' ||
+        display === 'inline-block' ||
+        display === 'inline-flex' ||
+        display === 'inline-grid' ||
+        display === 'inline-table';
 
       if (!isInline) return false;
 
@@ -182,7 +203,10 @@ function runInPage(ctx) {
       // Fallback: sometimes links are inside spans within a paragraph-like region
       const inlineContainer = closest(el, 'span, em, strong, small, label');
       if (inlineContainer) {
-        const outerTextBlock = closest(inlineContainer, 'p, li, dd, dt, blockquote, figcaption, caption, td, th');
+        const outerTextBlock = closest(
+          inlineContainer,
+          'p, li, dd, dt, blockquote, figcaption, caption, td, th'
+        );
         if (outerTextBlock) return true;
       }
 
@@ -234,7 +258,7 @@ function runInPage(ctx) {
     try {
       if (det.hasAttribute('open')) return false;
 
-      const tag = (el && el.tagName) ? String(el.tagName).toLowerCase() : '';
+      const tag = el && el.tagName ? String(el.tagName).toLowerCase() : '';
       // summary remains operable even when <details> is closed
       if (tag === 'summary') return false;
 
@@ -256,9 +280,9 @@ function runInPage(ctx) {
 
   function getStyle(el) {
     try {
-      return (document && document.defaultView && document.defaultView.getComputedStyle)
-          ? document.defaultView.getComputedStyle(el)
-          : null;
+      return document && document.defaultView && document.defaultView.getComputedStyle
+        ? document.defaultView.getComputedStyle(el)
+        : null;
     } catch {
       return null;
     }
@@ -288,7 +312,11 @@ function runInPage(ctx) {
 
     // aria-disabled elements are typically treated as not operable
     try {
-      const ad = el.getAttribute && String(el.getAttribute('aria-disabled') || '').trim().toLowerCase();
+      const ad =
+        el.getAttribute &&
+        String(el.getAttribute('aria-disabled') || '')
+          .trim()
+          .toLowerCase();
       if (ad === 'true') return false;
     } catch {}
 
@@ -321,7 +349,8 @@ function runInPage(ctx) {
 
   function elementFromPoint(x, y) {
     try {
-      if (document && typeof document.elementFromPoint === 'function') return document.elementFromPoint(x, y);
+      if (document && typeof document.elementFromPoint === 'function')
+        return document.elementFromPoint(x, y);
     } catch {}
     return null;
   }
@@ -347,7 +376,8 @@ function runInPage(ctx) {
     }
   }
 
-  const CANDIDATE_SELECTOR = 'button, summary, a[href], area[href], input, select, textarea, [role="button"], [role="link"]';
+  const CANDIDATE_SELECTOR =
+    'button, summary, a[href], area[href], input, select, textarea, [role="button"], [role="link"]';
 
   // --- candidate collection ---
   const candidates = qsa(CANDIDATE_SELECTOR);
@@ -481,14 +511,20 @@ function runInPage(ctx) {
       const tag = (el.tagName || '').toLowerCase();
       if (tag !== 'input') return false;
 
-      const type = (el.getAttribute && String(el.getAttribute('type') || '').trim().toLowerCase()) || '';
+      const type =
+        (el.getAttribute &&
+          String(el.getAttribute('type') || '')
+            .trim()
+            .toLowerCase()) ||
+        '';
       if (type !== 'checkbox' && type !== 'radio') return false;
 
       const cs = getStyle(el);
       let appearance = '';
       try {
         if (cs && typeof cs.getPropertyValue === 'function') {
-          appearance = cs.getPropertyValue('appearance') || cs.getPropertyValue('-webkit-appearance') || '';
+          appearance =
+            cs.getPropertyValue('appearance') || cs.getPropertyValue('-webkit-appearance') || '';
         } else if (cs) {
           appearance = cs.appearance || cs.webkitAppearance || '';
         }
@@ -528,8 +564,8 @@ function runInPage(ctx) {
     }
   }
 
-  const occurrences = [];
-  let hasUncertainConflicts = false;
+  const failOccurrences = [];
+  const cantTellOccurrences = [];
 
   for (const it of undersized) {
     // Inline-text exception: do not fail purely on size/spacing for inline links in text.
@@ -548,20 +584,69 @@ function runInPage(ctx) {
     const info = hasSpacingConflict(it);
 
     if (!info.conflict && info.confident === false) {
-      // Ambiguous perimeter-sampling result near the decision threshold.
-      hasUncertainConflicts = true;
+      // Ambiguous perimeter-sampling result near the decision threshold —
+      // previously recorded only as a page-level boolean with no per-target
+      // occurrence at all, so this specific target was unrecoverable from
+      // the result once any other target on the page had a confident
+      // fail (see helpers.resolveTieredOutcome's header comment). Now
+      // reported as its own cantTell-tier occurrence instead.
+      cantTellOccurrences.push({
+        selector: buildSelector(it.el),
+        html: htmlSnippet(it.el),
+        occurrenceOutcome: 'cantTell',
+        summary:
+          'Target may be too small and too close to another target, but the overlap is near the detection threshold and could not be confidently measured.',
+        hint: 'Manually verify the effective spacing between this target and its neighbor; increase target size or spacing if the overlap is real.',
+        i18n: {
+          summaryKey: 'targetSizeMinimum_summary_cantTell_ambiguousSpacing',
+          hintKey: 'targetSizeMinimum_hint_cantTell_ambiguousSpacing',
+          params: {}
+        },
+        data: {
+          details: {
+            measured: { width: it.rect.width, height: it.rect.height },
+            reasonCode: 'undersized-ambiguous-spacing',
+            conflictHitCount: info.hitCount,
+            conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
+          }
+        }
+      });
       continue;
     }
 
     if (info.conflict) {
       if (isPlausiblyEssentialOrEquivalent(it.el)) {
-        hasUncertainConflicts = true;
+        // Confident spacing conflict, but the target may be exempt as part
+        // of an essential graphic/image-map region — same "previously
+        // unrecoverable" gap as above, now reported instead of dropped.
+        cantTellOccurrences.push({
+          selector: buildSelector(it.el),
+          html: htmlSnippet(it.el),
+          occurrenceOutcome: 'cantTell',
+          summary:
+            'Target is too small and too close to another target, but may be exempt as part of an essential graphic or image-map region.',
+          hint: 'Verify whether this target’s size is genuinely essential to its function (e.g. part of an SVG/canvas/image map); if not, increase target size or spacing.',
+          i18n: {
+            summaryKey: 'targetSizeMinimum_summary_cantTell_plausiblyEssential',
+            hintKey: 'targetSizeMinimum_hint_cantTell_plausiblyEssential',
+            params: {}
+          },
+          data: {
+            details: {
+              measured: { width: it.rect.width, height: it.rect.height },
+              reasonCode: 'undersized-plausibly-essential',
+              conflictHitCount: info.hitCount,
+              conflictWith: info.conflictEl ? buildSelector(info.conflictEl) : null
+            }
+          }
+        });
         continue;
       }
 
-      occurrences.push({
+      failOccurrences.push({
         selector: buildSelector(it.el),
         html: htmlSnippet(it.el),
+        occurrenceOutcome: 'fail',
         summary: 'Target is too small and too close to another target.',
         hint: 'Increase target size to at least 24 by 24 CSS pixels, or add sufficient spacing.',
         i18n: {
@@ -581,25 +666,15 @@ function runInPage(ctx) {
     }
   }
 
-  if (occurrences.length > 0) {
-    return {
-      ruleId: RULE_ID,
-      outcome: 'fail',
-      severity: (rule && rule.defaultSeverity) || 'minor',
-      occurrences
-    };
-  }
-
-  if (hasUncertainConflicts) {
-    return {
-      ruleId: RULE_ID,
-      outcome: 'cantTell',
-      severity: 'minor',
-      occurrences: []
-    };
-  }
-
-  return { ruleId: RULE_ID, outcome: 'pass', severity: 'minor', occurrences: [] };
+  // See helpers.resolveTieredOutcome's own header comment (src/core/dom-helpers.js):
+  // a fail-tier finding never silently discards cantTell-tier findings from
+  // the same run — both are returned together when the outcome is 'fail'.
+  const resolved = helpers.resolveTieredOutcome(
+    failOccurrences,
+    cantTellOccurrences,
+    (rule && rule.defaultSeverity) || 'minor'
+  );
+  return { ruleId: RULE_ID, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };