@surea11y/core 1.4.1 → 1.6.0

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

@@ -10,17 +10,34 @@
  * @sc 4.1.2
  * @applicability
  *   Applies to <iframe>/<frame> elements that are eligible for the
- *   accessibility tree (isAccTreeEligible).
+ *   accessibility tree (isAccTreeEligible) AND reachable by sequential
+ *   focus navigation, both conditions required, regardless of role.
  * @expectation
  *   The element has a non-empty accessible name via aria-labelledby,
  *   aria-label, or the title attribute. Unlike most interactive elements,
  *   an iframe's name is never derived from its rendered content (the
- *   embedded document is a separate browsing context) — this mirrors
+ *   embedded document is a separate browsing context), this mirrors
  *   dialog-name-present's "name-from-author-only" reasoning.
  * @implementation-notes
  * - Uses helpers.getAccessibleNameInfo, which already stops at
  *   aria-label/aria-labelledby/label[for]/title without falling back to
- *   subtree text content — the right shape for this element.
+ *   subtree text content, the right shape for this element.
+ * - Per ACT cae760's own Applicability text, an iframe is only in scope
+ *   when it is BOTH accessibility-tree-eligible AND reachable by
+ *   sequential focus navigation, unconditionally, not only as a
+ *   role="none"/"presentation" exception. Unlike most elements,
+ *   <iframe>/<frame> are natively focusable by default (no tabindex
+ *   needed), so `tabindex="-1"` (or any negative tabindex) exempts a
+ *   frame regardless of whether it also carries a role, a plain
+ *   `<iframe tabindex="-1">` with no role at all is just as out of scope
+ *   as `<iframe role="none" tabindex="-1">`; ACT cae760's own passed
+ *   example is the roleless case. (The role="none" reasoning, "because
+ *   iframe elements are part of sequential focus navigation, the
+ *   explicit semantic role of none will be ignored, due to Presentational
+ *   Roles Conflict Resolution", is *why* a focusable role="none" iframe
+ *   still needs a name, not a separate applicability path of its own.)
+ *   helpers.getFocusableInfo doesn't model iframe/frame's native
+ *   focusability at all, so it's computed locally here instead.
  */
 
 const id = 'iframe-name-present';
@@ -62,9 +79,26 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
+  // <iframe>/<frame> are natively focusable by default (no tabindex
+  // needed), unlike most elements, only an explicit negative tabindex
+  // removes them from the tab order.
+  function isFrameFocusable(el) {
+    try {
+      const tabindexRaw = el.getAttribute ? el.getAttribute('tabindex') : null;
+      if (tabindexRaw == null) return true;
+      const n = Number(String(tabindexRaw).trim());
+      if (Number.isFinite(n) && n < 0) return false;
+      return true;
+    } catch {
+      return true;
+    }
+  }
+
   for (const el of nodes) {
     if (!el || !el.tagName) continue;
 
+    if (!isFrameFocusable(el)) continue;
+
     if (helpers.isAccTreeEligible) {
       const elig = helpers.isAccTreeEligible(el);
       const isEligible = typeof elig === 'boolean' ? elig : !!(elig && elig.eligible);
@@ -88,24 +122,22 @@ function runInPage(ctx) {
         })()
       : null;
     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 frame has no accessible name.',
-      hint: 'Add a title attribute (or aria-label/aria-labelledby) describing the frame’s content or purpose.',
-      i18n: {
-        summaryKey: 'iframeNamePresent_summary_fail',
-        hintKey: 'iframeNamePresent_hint_fail',
-        params: { element: tag }
-      },
-      data: {
-        details: { reasonCode: 'IFRAME_NAME_MISSING', element: tag },
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    });
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: 'This frame has no accessible name.',
+        hint: 'Add a title attribute (or aria-label/aria-labelledby) describing the frame’s content or purpose.',
+        i18n: {
+          summaryKey: 'iframeNamePresent_summary_fail',
+          hintKey: 'iframeNamePresent_hint_fail',
+          params: { element: tag }
+        },
+        data: {
+          details: { reasonCode: 'IFRAME_NAME_MISSING', element: tag },
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/iframe-title-unique.js

@@ -13,7 +13,7 @@
  *   attribute.
  * @expectation
  *   No two frames in scope share the same (trimmed, case-sensitive) title
- *   attribute value — a duplicate title prevents assistive technology
+ *   attribute value, a duplicate title prevents assistive technology
  *   users from telling frames apart when scanning by name.
  * @implementation-notes
  * - Distinct, atomic decision from iframe-name-present (presence):
@@ -89,30 +89,25 @@ function runInPage(ctx) {
 
     for (const el of els) {
       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 frame’s title is not unique among the frames on this page.',
-        hint: 'Give each frame a distinct title describing its specific content or purpose.',
-        i18n: {
-          summaryKey: 'iframeTitleUnique_summary_fail',
-          hintKey: 'iframeTitleUnique_hint_fail',
-          params: { element: tag, title }
-        },
-        data: {
-          details: {
-            reasonCode: 'IFRAME_TITLE_DUPLICATE',
-            element: tag,
-            title,
-            duplicateCount: els.length
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: 'This frame’s title is not unique among the frames on this page.',
+          hint: 'Give each frame a distinct title describing its specific content or purpose.',
+          i18n: {
+            summaryKey: 'iframeTitleUnique_summary_fail',
+            hintKey: 'iframeTitleUnique_hint_fail',
+            params: { element: tag, title }
+          },
+          data: {
+            details: {
+              reasonCode: 'IFRAME_TITLE_DUPLICATE',
+              element: tag,
+              title,
+              duplicateCount: els.length
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 

package/src/checks/automatic/img-alt-present.js

@@ -157,13 +157,21 @@ function runInPage(ctx) {
     // From here: applicable
     applicableCount += 1;
 
-    // alt attribute presence check (empty allowed)
-    let hasAlt;
+    // alt attribute presence check. A literally empty alt ("") is the
+    // HTML decorative marker and always satisfies this check. A present
+    // alt that is non-empty but trims to nothing (a lone space, a tab)
+    // does not get that treatment: per HTML-AAM the img-role conflict-
+    // resolution flip to presentation only triggers on the literal empty
+    // string, so the element keeps its img role while its computed
+    // accessible name is empty -- a real failure, not a decorative image.
+    let rawAlt;
     try {
-      hasAlt = el.getAttribute('alt') !== null;
+      rawAlt = el.getAttribute('alt');
     } catch {
-      hasAlt = false;
+      rawAlt = null;
     }
+    const isWhitespaceOnlyAlt = rawAlt !== null && rawAlt !== '' && trim(rawAlt) === '';
+    const hasAlt = rawAlt !== null && !isWhitespaceOnlyAlt;
     if (hasAlt) continue;
 
     // aria-label / aria-labelledby is also a valid, standards-recognized

package/src/checks/automatic/label-in-name.js

@@ -2,12 +2,45 @@
 
 'use strict';
 
+/**
+ * @check label-in-name
+ * @atomic true
+ * @summary A control's accessible name must contain its visible label text
+ * @standard WCAG 2.2
+ * @sc 2.5.3
+ * @applicability
+ *   Applies to controls that carry aria-label or aria-labelledby, are
+ *   visually rendered, and have visible label text this engine can extract
+ *   deterministically, from an associated <label>, from the control's own
+ *   rendered text, or from the elements aria-labelledby points at. The
+ *   candidates are <button>, <a href>, <summary>, non-hidden form controls,
+ *   and the button, link, checkbox, radio, switch, searchbox, tab, menuitem,
+ *   menuitemcheckbox, menuitemradio, option, treeitem and gridcell roles,
+ *   minus anything hidden or disabled. aria-hidden is not
+ *   excluded: it changes nothing about what is rendered on screen, which is
+ *   what this SC is about.
+ * @expectation
+ *   The accessible name contains the visible label's words, adjacent and in
+ *   order. The comparison is over words rather than characters:
+ *   parenthesised text is dropped, case is folded, text is NFKD-normalised,
+ *   and every non-letter/digit becomes a separator, so punctuation and
+ *   spacing differences never decide the outcome. Four shapes markup cannot
+ *   settle are reported as cantTell instead of fail: a word hyphenated
+ *   differently in the two places; a visible word the author may have
+ *   abbreviated, marked by its trailing period; visible text rendered
+ *   through a known icon font (the DOM text is real words, but nothing
+ *   readable actually renders); and a whole visible label of exactly one
+ *   character that doesn't even appear inside the accessible name, which
+ *   per ACT 2ee8b8 may be "non-text content" (e.g. "X" meaning "close")
+ *   rather than literal text.
+ */
+
 const id = 'label-in-name';
 
 const meta = {
   title: 'Label in Name: accessible name contains visible text',
   description:
-    'Checks that when a control has a visible text label, the accessible name (from aria-label/aria-labelledby) contains that visible label text (WCAG 2.5.3).',
+    'Checks that when a control has a visible text label, the accessible name contains that visible label text (WCAG 2.5.3).',
   i18n: {
     titleKey: 'labelInName_title',
     descriptionKey: 'labelInName_description'
@@ -147,7 +180,7 @@ function runInPage(ctx) {
   // rendering as "format_color_fill") is DOM-visible pixels but is never
   // perceived as literal readable words the way real visible text is.
   // Excluding aria-hidden content is a cheap static-markup signal that gets
-  // the common case (decorative icon fonts) right — an icon-only button
+  // the common case (decorative icon fonts) right. An icon-only button
   // named via aria-label shouldn't have its glyph name counted as text.
   function isAccEligible(el) {
     if (!el) return false;
@@ -273,7 +306,9 @@ function runInPage(ctx) {
   }
 
   function getVisibleTextLabelInfo(el) {
-    // Returns { text, source } where source helps reporting.
+    // Returns { text, source, sourceElements } where source helps reporting
+    // and sourceElements (the actual DOM nodes the visible text came from)
+    // lets the icon-font check below look at the right element's own style.
     // Source policy (deterministic):
     // 1) <label> association for form controls
     // 2) visible text inside the element
@@ -288,18 +323,22 @@ function runInPage(ctx) {
     if (isFormControl) {
       const labels = getAssociatedLabelElements(el);
       const labelParts = [];
+      const contributing = [];
       for (const l of labels) {
         if (!l || !isDomVisible(l)) continue;
         const t = collectVisibleTextUnder(l);
-        if (t) labelParts.push(t);
+        if (t) {
+          labelParts.push(t);
+          contributing.push(l);
+        }
       }
       const joined = labelParts.join(' ').replace(/\s+/g, ' ').trim();
-      if (joined) return { text: joined, source: 'label' };
+      if (joined) return { text: joined, source: 'label', sourceElements: contributing };
     }
 
     // 2) Text inside the control itself
     text = collectVisibleTextUnder(el);
-    if (text) return { text, source: 'self' };
+    if (text) return { text, source: 'self', sourceElements: [el] };
 
     // 3) aria-labelledby referenced visible text (only if refs exist and are visible)
     try {
@@ -307,20 +346,115 @@ function runInPage(ctx) {
       if (idrefs && helpers.resolveIdRefs) {
         const r = helpers.resolveIdRefs(idrefs, ctx, { maxRefs: 8 });
         const parts = [];
+        const contributing = [];
         for (const ref of r && Array.isArray(r.refs) ? r.refs : []) {
           if (!ref || !ref.tagName) continue;
           if (!isDomVisible(ref)) continue;
           const t = collectVisibleTextUnder(ref);
-          if (t) parts.push(t);
+          if (t) {
+            parts.push(t);
+            contributing.push(ref);
+          }
         }
         const joined = parts.join(' ').replace(/\s+/g, ' ').trim();
-        if (joined) return { text: joined, source: 'aria-labelledby' };
+        if (joined)
+          return { text: joined, source: 'aria-labelledby', sourceElements: contributing };
       }
     } catch {
       // ignore
     }
 
-    return { text: '', source };
+    return { text: '', source, sourceElements: [] };
+  }
+
+  // Curated real-world icon-font family names. These fonts remap ordinary
+  // word glyphs to unrelated symbols via ligatures/PUA codepoints, so the
+  // DOM text is real words but nothing readable actually renders, ACT
+  // 2ee8b8's own passed example is exactly this (a button's DOM text
+  // "search" rendered as a magnifying-glass icon by "Material Icons").
+  // Same curated-list tradeoff as link-name-quality's phrase list.
+  const ICON_FONT_FAMILIES = new Set([
+    'material icons',
+    'material icons outlined',
+    'material icons round',
+    'material icons sharp',
+    'material icons two tone',
+    'material symbols outlined',
+    'material symbols rounded',
+    'material symbols sharp',
+    'font awesome 5 free',
+    'font awesome 5 brands',
+    'font awesome 5 pro',
+    'font awesome 6 free',
+    'font awesome 6 brands',
+    'font awesome 6 pro',
+    'fontawesome',
+    'glyphicons halflings',
+    'ionicons',
+    'icomoon',
+    'bootstrap-icons',
+    'bootstrap icons',
+    'feather'
+  ]);
+
+  // Same two-tier lookup as avoid-inline-spacing.js's computedStyleOf:
+  // helpers.computedStyle isn't actually part of the public helpers API
+  // (it's internal to dom-helpers.js), so the realm's own getComputedStyle
+  // is what actually resolves a stylesheet-declared font-family.
+  function computedStyleOf(node) {
+    if (helpers && typeof helpers.computedStyle === 'function') {
+      try {
+        const cs = helpers.computedStyle(node);
+        if (cs) return cs;
+      } catch {
+        // fall through to the realm's own view
+      }
+    }
+    try {
+      const view = node.ownerDocument && node.ownerDocument.defaultView;
+      if (view && typeof view.getComputedStyle === 'function') return view.getComputedStyle(node);
+    } catch {
+      // no computed style available
+    }
+    return null;
+  }
+
+  function isIconFontElement(node) {
+    if (!node) return false;
+    const cs = computedStyleOf(node);
+    if (!cs) return false;
+    let family;
+    try {
+      family =
+        cs.fontFamily || (cs.getPropertyValue ? cs.getPropertyValue('font-family') : '') || '';
+    } catch {
+      family = '';
+    }
+    if (!family) return false;
+    const names = String(family)
+      .split(',')
+      .map((s) =>
+        s
+          .trim()
+          .replace(/^['"]|['"]$/g, '')
+          .toLowerCase()
+      );
+    return names.some((n) => ICON_FONT_FAMILIES.has(n));
+  }
+
+  // ACT 2ee8b8's own passed example `<button aria-label="close">X</button>`:
+  // a single character standing in for an icon ("x" meaning "close") is
+  // "non-text content" per the rule's own background text, which names no
+  // algorithmic test for it. Scoped narrowly to a whole visible label of
+  // exactly one character that doesn't even appear inside the accessible
+  // name: "x" has no relation at all to "close", which is the icon-glyph
+  // shape. A single character that DOES appear in the name (e.g. visible
+  // "1" against aria-label "1a") is a real word-boundary mismatch, not a
+  // symbol standing in for something else, and still fails outright.
+  function isSingleSymbolicCharacter(text, accessibleNameNorm) {
+    const t = norm(text);
+    if (!t || Array.from(t).length !== 1) return false;
+    return accessibleNameNorm.indexOf(t) === -1;
   }
 
   for (const el of nodes) {
@@ -351,58 +485,73 @@ function runInPage(ctx) {
     const nameTokens = tokenize(accName, false);
     const contains = containsWordRun(labelTokens, nameTokens, null);
 
-    // An abbreviation, or a word hyphenated differently in the two places, is
-    // not something markup settles: the author may have meant either. Report
-    // without asserting a defect instead of failing or staying silent.
+    // An abbreviation, a word hyphenated differently, or visible text that
+    // may not be literal text at all (an icon-font glyph, a single symbolic
+    // character) is not something markup settles: the author may have meant
+    // either. Report without asserting a defect instead of failing or
+    // staying silent.
     let uncertainty = '';
     if (!contains) {
       if (containsWordRun(tokenize(visibleLabel, true), tokenize(accName, true), null)) {
         uncertainty = 'HYPHENATION_DIFFERS';
       } else {
         const abbreviated = abbreviatedWords(visibleLabel);
-        if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated))
+        if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated)) {
           uncertainty = 'POSSIBLE_ABBREVIATION';
+        } else if ((labelInfo.sourceElements || []).some(isIconFontElement)) {
+          uncertainty = 'POSSIBLE_ICON_FONT_GLYPH';
+        } else if (isSingleSymbolicCharacter(visibleLabel, accNorm)) {
+          uncertainty = 'POSSIBLE_SYMBOLIC_CHARACTER';
+        }
       }
     }
 
+    const isSymbolicUncertainty =
+      uncertainty === 'POSSIBLE_ICON_FONT_GLYPH' || uncertainty === 'POSSIBLE_SYMBOLIC_CHARACTER';
+
     if (!contains) {
-      const selectorOut = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
-
-      occurrences.push({
-        selector: selectorOut,
-        html,
-        ...(uncertainty ? { outcome: 'cantTell' } : null),
-        summary: uncertainty
-          ? 'Accessible name may not contain the visible label text.'
-          : 'Accessible name does not contain the visible label text.',
-        hint: uncertainty
-          ? 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.'
-          : 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).',
-        i18n: {
-          summaryKey: uncertainty ? 'labelInName_summary_cantTell' : 'labelInName_summary_fail',
-          hintKey: uncertainty ? 'labelInName_hint_cantTell' : 'labelInName_hint_fail',
-          params: {
-            element: getElementDescriptor(el),
-            visibleLabel: clipForSummary(visibleLabel),
-            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
-            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          ...(uncertainty ? { outcome: 'cantTell' } : null),
+          summary: uncertainty
+            ? 'Accessible name may not contain the visible label text.'
+            : 'Accessible name does not contain the visible label text.',
+          hint: !uncertainty
+            ? 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).'
+            : isSymbolicUncertainty
+              ? 'Check by hand: the visible text may render as an icon or symbol rather than literal words, which markup cannot settle.'
+              : 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.',
+          i18n: {
+            summaryKey: !uncertainty
+              ? 'labelInName_summary_fail'
+              : isSymbolicUncertainty
+                ? 'labelInName_summary_cantTell_symbolic'
+                : 'labelInName_summary_cantTell',
+            hintKey: !uncertainty
+              ? 'labelInName_hint_fail'
+              : isSymbolicUncertainty
+                ? 'labelInName_hint_cantTell_symbolic'
+                : 'labelInName_hint_cantTell',
+            params: {
+              element: getElementDescriptor(el),
+              visibleLabel: clipForSummary(visibleLabel),
+              labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
+              nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+            }
+          },
+          data: {
+            details: {
+              reasonCode: uncertainty || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
+              visibleLabel,
+              accessibleName: accName,
+              normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },
+              tokenized: { visibleLabel: labelTokens, accessibleName: nameTokens },
+              labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
+              nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+            }
           }
-        },
-        data: {
-          details: {
-            reasonCode: uncertainty || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
-            visibleLabel,
-            accessibleName: accName,
-            normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },
-            tokenized: { visibleLabel: labelTokens, accessibleName: nameTokens },
-            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
-            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
-          }
-        }
-      });
+        })
+      );
     }
   }
 

package/src/checks/automatic/link-in-text-block.js

@@ -12,7 +12,7 @@
  *   Applies to <a href> elements whose immediate parent element also has
  *   at least one direct-child text node with non-whitespace content
  *   (i.e. the link sits inline within a run of plain text, not as a
- *   standalone item — e.g. not the sole content of a <li> nav item).
+ *   standalone item, e.g. not the sole content of a <li> nav item).
  * @expectation
  *   A link inside a text block must be visually distinguishable from the
  *   surrounding text by at least one non-color means:
@@ -20,29 +20,29 @@
  *     - a different font-weight than the surrounding text, OR
  *     - a different font-style than the surrounding text, OR
  *     - a contrast ratio of at least 3:1 between the link's text color and
- *       the surrounding text's color (WCAG technique G183's threshold —
+ *       the surrounding text's color (WCAG technique G183's threshold,
  *       sufficient contrast alone is an accepted alternative to underline).
  *   Fails only when none of the above hold AND the color contrast between
- *   link and surrounding text is confidently computable and below 3:1 —
+ *   link and surrounding text is confidently computable and below 3:1,
  *   i.e. color is demonstrably the only cue.
  * @implementation-notes
  * - "Surrounding text style" is approximated as the link's immediate
  *   parent element's own computed style, not a full inline-context walk
- *   of the actual adjacent text node(s) — a deliberate scope-down, since
+ *   of the actual adjacent text node(s), a deliberate scope-down, since
  *   plain text nodes inherit their rendering from the parent in the
  *   overwhelming majority of real markup.
  * - When contrast is not confidently computable (background image/
- *   gradient, blend mode, filter, non-opaque ancestor — same blockers
+ *   gradient, blend mode, filter, non-opaque ancestor, same blockers
  *   `contrast-minimum`/`contrast-computable` use), the link is silently
  *   skipped rather than flagged or reported as cantTell, to keep `fail`
  *   reserved for deterministic, high-confidence violations. This means
- *   the rule never emits cantTell — outcome is notApplicable/pass/fail
+ *   the rule never emits cantTell, outcome is notApplicable/pass/fail
  *   only, matching this repo's other Tier 2 mechanical rules.
  * - Reuses the shared `helpers.contrast` subsystem (same
  *   computeEffectiveForeground/Background, getComputabilityBlocker,
  *   contrastRatio helpers as `contrast-minimum`), rather than re-deriving
  *   color math independently.
- * - Scoped to `a[href]` only (not `area[href]` or `[role="link"]`) —
+ * - Scoped to `a[href]` only (not `area[href]` or `[role="link"]`),
  *   matches the common real-world shape of this issue (prose links).
  */
 
@@ -52,7 +52,7 @@ const meta = {
   title:
     'Links in text blocks must be distinguishable from surrounding text without relying on color alone',
   description:
-    'Checks that a link inside a run of text is visually distinguishable from the surrounding text by underline, a font-weight/style difference, or a sufficient (>=3:1) color-contrast difference — not by color alone.',
+    'Checks that a link inside a run of text is visually distinguishable from the surrounding text by underline, a font-weight/style difference, or a sufficient (>=3:1) color-contrast difference, not by color alone.',
   i18n: {
     titleKey: 'linkInTextBlock_title',
     descriptionKey: 'linkInTextBlock_description'
@@ -179,7 +179,7 @@ function runInPage(ctx) {
     try {
       const blocker = c.getComputabilityBlocker(el);
       if (blocker && blocker.ok === false) {
-        // Not confidently computable — skip (benefit of the doubt).
+        // Not confidently computable, skip (benefit of the doubt).
       } else {
         const bg = c.computeEffectiveBackground(el, {
           contrast: { mode, rootCanvasFallback },
@@ -204,7 +204,7 @@ function runInPage(ctx) {
 
           if (!(ratio >= 3)) flagged = true;
         }
-        // else: not confidently computable — skip.
+        // else: not confidently computable, skip.
       }
     } catch {
       // no-throw: treat as not computable, skip.
@@ -215,31 +215,29 @@ function runInPage(ctx) {
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const tag = (el.tagName || '').toLowerCase();
     const ratioStr = c.round2 ? c.round2(ratio) : String(ratio);
 
-    occurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This link in a block of text relies on color alone to be distinguished from the surrounding text.',
-      hint: 'Add an underline, a font-weight/style difference, or increase the color contrast between the link and surrounding text to at least 3:1.',
-      i18n: {
-        summaryKey: 'linkInTextBlock_summary_fail',
-        hintKey: 'linkInTextBlock_hint_fail',
-        params: { element: tag, ratio: String(ratioStr), threshold: '3' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-        details: {
-          reasonCode: 'COLOR_ONLY_DIFFERENTIATION',
-          metrics: { ratio, threshold: 3 },
-          colors: { linkForegroundHex: fgLinkHex, surroundingTextForegroundHex: fgParentHex }
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This link in a block of text relies on color alone to be distinguished from the surrounding text.',
+        hint: 'Add an underline, a font-weight/style difference, or increase the color contrast between the link and surrounding text to at least 3:1.',
+        i18n: {
+          summaryKey: 'linkInTextBlock_summary_fail',
+          hintKey: 'linkInTextBlock_hint_fail',
+          params: { element: tag, ratio: String(ratioStr), threshold: '3' }
+        },
+        data: {
+          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: {
+            reasonCode: 'COLOR_ONLY_DIFFERENTIATION',
+            metrics: { ratio, threshold: 3 },
+            colors: { linkForegroundHex: fgLinkHex, surroundingTextForegroundHex: fgParentHex }
+          }
         }
-      }
-    });
+      })
+    );
   }
 
   if (applicableCount === 0) {