@surea11y/core 1.4.0 → 1.5.0

package/src/checks/automatic/html-xml-lang-mismatch.js

@@ -84,15 +84,8 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(html) : 'html';
-  const htmlSnippet = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(html)
-    : (html.outerHTML || '').slice(0, 200);
-
   const occurrences = [
-    {
-      selector: stableSelector,
-      html: htmlSnippet,
+    helpers.reportOccurrence(html, {
       summary: `The lang ("${lang}") and xml:lang ("${xmlLang}") attributes declare different languages.`,
       hint: 'Make lang and xml:lang declare the same primary language, or remove the deprecated xml:lang attribute.',
       i18n: {
@@ -103,7 +96,7 @@ function runInPage(ctx) {
       data: {
         details: { reasonCode: 'HTML_XML_LANG_MISMATCH', lang, xmlLang }
       }
-    }
+    })
   ];
 
   return {

package/src/checks/automatic/iframe-focusable-content.js

@@ -322,47 +322,45 @@ function runInPage(ctx) {
     if (!candidates.length) continue;
 
     const tag = el.tagName.toLowerCase();
-    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
     const shouldProbe = candidates.length === 1;
     const runtimeProbe = shouldProbe
       ? probeImmediateFocusRedirect(el, contentDoc, candidates[0])
       : null;
 
     if (runtimeProbe && runtimeProbe.redirected) {
-      cantTellOccurrences.push({
-        selector: stableSelector,
-        html,
-        summary:
-          'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
-        hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
-        i18n: null,
-        data: {
-          details: {
-            reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',
-            element: tag,
-            runtimeProbe
+      cantTellOccurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
+          hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
+          i18n: null,
+          data: {
+            details: {
+              reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',
+              element: tag,
+              runtimeProbe
+            }
           }
-        }
-      });
+        })
+      );
       continue;
     }
 
-    failOccurrences.push({
-      selector: stableSelector,
-      html,
-      summary:
-        'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
-      hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
-      i18n: {
-        summaryKey: 'iframeFocusableContent_summary_fail',
-        hintKey: 'iframeFocusableContent_hint_fail',
-        params: { element: tag }
-      },
-      data: {
-        details: { reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_FOCUSABLE', element: tag }
-      }
-    });
+    failOccurrences.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This frame has tabindex="-1" but its content contains focusable elements, which remain reachable by keyboard.',
+        hint: 'Remove focusable content from the frame, or remove tabindex="-1" if the frame is meant to be reachable.',
+        i18n: {
+          summaryKey: 'iframeFocusableContent_summary_fail',
+          hintKey: 'iframeFocusableContent_hint_fail',
+          params: { element: tag }
+        },
+        data: {
+          details: { reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_FOCUSABLE', element: tag }
+        }
+      })
+    );
   }
 
   if (applicableCount === 0) {

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

@@ -88,24 +88,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

@@ -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

@@ -9,10 +9,10 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to <img> elements that are exposed to assistive technologies.
- *   Images with role="presentation" or role="none" are excluded only when they are not focusable.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to <img> elements included in the accessibility tree.
+ *   Images with role="presentation" or role="none" are excluded only when they are not focusable,
+ *   since a focusable one reverts to the img role under presentational roles conflict resolution.
+ *   Hidden images are excluded whether or not they are focusable.
  * @expectation
  *   Each applicable <img> element has an alt attribute.
  *   The alt attribute may be empty (alt="").
@@ -60,8 +60,15 @@ function runInPage(ctx) {
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // ACT 23a2a8 exempts programmatically hidden images, and that glossary term
+  // has no focusability carve-out, so an aria-hidden image stays out of scope
+  // even when tabbable; aria-hidden-focus reports that markup instead.
+  const isEligibleHelper =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
   const getFocusableInfo =
     helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
   const getAriaNameInfo =
@@ -113,11 +120,11 @@ function runInPage(ctx) {
     const el = imgs[i];
     if (!el || !el.getAttribute) continue;
 
-    // Eligibility: only imgs exposed to assistive tech (with focusable/IDREF exceptions handled by helper)
-    if (isAccTreeEligible) {
+    // Eligibility: only imgs exposed to assistive tech.
+    if (isEligibleHelper) {
       let elig;
       try {
-        elig = isAccTreeEligible(el, ctx);
+        elig = isEligibleHelper(el, ctx);
       } catch {
         elig = null;
       }

package/src/checks/automatic/input-image-alt-present.js

@@ -9,11 +9,10 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @applicability
- *   Applies to <input type="image"> elements that are exposed to assistive technologies.
- *   Elements otherwise hidden from the accessibility tree remain applicable
- *   if they are focusable or referenced by IDREF relationships (per engine eligibility checks).
+ *   Applies to <input type="image"> elements included in the accessibility tree.
  * @expectation
- *   Each applicable <input type="image"> element has an alt attribute.
+ *   Each applicable <input type="image"> element has an alt attribute, and its
+ *   accessible name is not the browser default for an image button.
  *   The alt attribute may be empty (alt="").
  */
 
@@ -72,8 +71,14 @@ function runInPage(ctx) {
   const getEligibilityInfo =
     helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
-  const isAccTreeEligible =
-    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  // ACT 59796f applies to image buttons included in the accessibility tree,
+  // which excludes focusable content inside aria-hidden.
+  const isEligibleHelper =
+    helpers && typeof helpers.isIncludedInAccessibilityTree === 'function'
+      ? helpers.isIncludedInAccessibilityTree
+      : helpers && typeof helpers.isAccTreeEligible === 'function'
+        ? helpers.isAccTreeEligible
+        : null;
 
   const getAriaNameInfo =
     helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
@@ -99,63 +104,109 @@ function runInPage(ctx) {
   for (const el of inputs) {
     if (!el || !el.getAttribute) continue;
 
-    // Applicability: eligible in the acc tree (with helper exceptions).
-    if (isAccTreeEligible) {
+    if (isEligibleHelper) {
       const elig = (() => {
         try {
-          return isAccTreeEligible(el, ctx);
+          return isEligibleHelper(el, ctx);
         } catch {
-          return { eligible: true, reasons: [] };
+          return true;
         }
       })();
-      if (elig && elig.eligible === false) continue;
+      const eligible = typeof elig === 'boolean' ? elig : !(elig && elig.eligible === false);
+      if (!eligible) continue;
     }
 
     applicableCount += 1;
 
-    const hasAlt = el.getAttribute('alt') !== null;
-    if (hasAlt) continue;
-
-    // aria-label / aria-labelledby is also a valid, standards-recognized
-    // text-alternative mechanism for <input type="image"> (HTML-AAM
-    // accessible name computation includes ARIA naming before falling
-    // back to alt).
-    if (getAriaNameInfo) {
-      let ariaName;
-      try {
-        ariaName = getAriaNameInfo(el, ctx);
-      } catch {
-        ariaName = null;
+    // The browser's own fallback name for an image button carries no
+    // information, so an author-supplied name equal to it is treated as no
+    // name at all (ACT 59796f). Only the English defaults are recognised:
+    // "Submit Query" from HTML-AAM, "Submit" from Chrome.
+    const effectiveName = (() => {
+      let v = '';
+      if (getAriaNameInfo) {
+        try {
+          const aria = getAriaNameInfo(el, ctx);
+          if (aria && aria.present && aria.value) v = String(aria.value);
+        } catch {
+          v = '';
+        }
       }
-      if (ariaName && ariaName.present) continue;
-    }
-
-    // A non-empty title attribute is HTML-AAM's own next fallback naming
-    // source once alt is entirely absent. Same gap img-alt-present handles
-    // for <img title="..."> with no alt.
-    const titleRaw = (() => {
-      try {
-        return el.getAttribute('title');
-      } catch {
-        return null;
+      if (!v) {
+        const alt = el.getAttribute('alt');
+        if (alt != null && String(alt).trim()) v = String(alt);
       }
+      if (!v) {
+        const t = el.getAttribute('title');
+        if (t != null && String(t).trim()) v = String(t);
+      }
+      return v.trim().toLowerCase();
     })();
-    if (titleRaw !== null && String(titleRaw).trim()) continue;
+
+    if (effectiveName === 'submit query' || effectiveName === 'submit') {
+      const eligInfoDefault = getEligibilityInfo
+        ? getEligibilityInfo(el, ctx, { targetSet: 'acc' })
+        : null;
+      const defaultNameOccurrence = {
+        summary:
+          'Accessible name is the browser default for an image button, which conveys nothing.',
+        hint: 'Replace it with text describing what the button does, for example "Search".',
+        i18n: {
+          summaryKey: 'inputImage_altPresent_summary_defaultName',
+          hintKey: 'inputImage_altPresent_hint_defaultName',
+          params: { element: 'input[type=image]' }
+        },
+        data: {
+          visibilityFilter: eligInfoDefault || { targetSet: 'acc', accEligible: null, reasons: [] },
+          details: { reasonCode: 'default_name' }
+        }
+      };
+      occurrences.push(
+        helpers && typeof helpers.reportOccurrence === 'function'
+          ? helpers.reportOccurrence(el, defaultNameOccurrence)
+          : { selector: '', html: '', ...defaultNameOccurrence }
+      );
+      continue;
+    }
+
+    // effectiveName already covers the naming sources HTML-AAM allows here,
+    // in order: aria-label/aria-labelledby, then alt, then title.
+    if (effectiveName) continue;
+
+    // An image button is a control, so an empty name fails whether alt is
+    // absent or present-but-empty. alt="" marks a decorative image, and an
+    // image button is never decorative.
+    const emptyAlt = el.getAttribute('alt') !== null;
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
 
-    const baseOccurrence = {
-      summary: 'Missing alt attribute on <input type="image">.',
-      hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
-      i18n: {
-        summaryKey: 'inputImage_altPresent_summary_fail',
-        hintKey: 'inputImage_altPresent_hint_fail',
-        params: { element: 'input[type=image]' }
-      },
-      data: {
-        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
-      }
-    };
+    const baseOccurrence = emptyAlt
+      ? {
+          summary: 'Empty alt="" on <input type="image"> leaves the control unnamed.',
+          hint: 'Describe the action in alt, or name the control with aria-label or aria-labelledby.',
+          i18n: {
+            summaryKey: 'inputImage_altPresent_summary_emptyAlt',
+            hintKey: 'inputImage_altPresent_hint_emptyAlt',
+            params: { element: 'input[type=image]' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode: 'empty_alt' }
+          }
+        }
+      : {
+          summary: 'Missing alt attribute on <input type="image">.',
+          hint: 'Add an alt attribute (use alt="" only when a separate accessible name is provided).',
+          i18n: {
+            summaryKey: 'inputImage_altPresent_summary_fail',
+            hintKey: 'inputImage_altPresent_hint_fail',
+            params: { element: 'input[type=image]' }
+          },
+          data: {
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+            details: { reasonCode: 'missing_alt' }
+          }
+        };
 
     if (helpers && typeof helpers.reportOccurrence === 'function') {
       occurrences.push(helpers.reportOccurrence(el, baseOccurrence));

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

@@ -52,6 +52,56 @@ function runInPage(ctx) {
     return v.replace(/\s+/g, ' ').trim().toLowerCase();
   }
 
+  // WCAG 2.5.3's label-in-name comparison is over words, not characters: drop
+  // parenthesised text, case-fold and NFKD-normalise, then reduce every
+  // non-letter/digit to a space. `hyphensJoin` deletes hyphens instead of
+  // splitting on them, which distinguishes a real mismatch from one that is
+  // only a hyphenation difference.
+  function tokenize(s, hyphensJoin) {
+    let v = (s == null ? '' : String(s)).replace(/\([^)]*\)/g, ' ').toLowerCase();
+    try {
+      v = v.normalize('NFKD');
+    } catch {
+      // Realm without String#normalize: the word comparison below still holds.
+    }
+    if (hyphensJoin) v = v.replace(/[-‐-―−]/g, '');
+    return v
+      .replace(/[^\p{L}\p{N}]+/gu, ' ')
+      .split(' ')
+      .filter(Boolean);
+  }
+
+  // The label's words must appear adjacent and in order inside the name, so a
+  // scattered subsequence does not count. Words in `prefixable` may match a
+  // longer name word they start.
+  function containsWordRun(needle, hay, prefixable) {
+    if (!needle.length) return true;
+    for (let i = 0; i + needle.length <= hay.length; i++) {
+      let ok = true;
+      for (let j = 0; j < needle.length; j++) {
+        const want = needle[j];
+        const got = hay[i + j];
+        if (got === want) continue;
+        if (prefixable && prefixable.has(want) && got.indexOf(want) === 0) continue;
+        ok = false;
+        break;
+      }
+      if (ok) return true;
+    }
+    return false;
+  }
+
+  // A trailing period marks a word the author may have shortened ("Ave." for
+  // "Avenue"). Tokenizing removes the period, so collect these beforehand.
+  function abbreviatedWords(s) {
+    const out = new Set();
+    for (const w of (s == null ? '' : String(s)).split(/\s+/)) {
+      const m = /^([\p{L}\p{N}]+)\.$/u.exec(w);
+      if (m) out.add(m[1].toLowerCase());
+    }
+    return out;
+  }
+
   function getElementDescriptor(el) {
     const tag = el && el.tagName ? String(el.tagName).toLowerCase() : 'element';
     let role;
@@ -297,52 +347,71 @@ function runInPage(ctx) {
     const accName = acc && acc.value != null ? String(acc.value) : '';
     const accNorm = norm(accName);
 
-    const contains = !!(accNorm && visibleNorm && accNorm.indexOf(visibleNorm) !== -1);
+    const labelTokens = tokenize(visibleLabel, false);
+    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.
+    let uncertainty = '';
     if (!contains) {
-      const selectorOut = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet
-        ? helpers.getOuterHtmlSnippet(el)
-        : el.outerHTML || '';
-
-      occurrences.push({
-        selector: selectorOut,
-        html,
-        summary: 'Accessible name does not contain the visible label text.',
-        hint: 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).',
-        i18n: {
-          summaryKey: 'labelInName_summary_fail',
-          hintKey: 'labelInName_hint_fail',
-          params: {
-            element: getElementDescriptor(el),
-            visibleLabel: clipForSummary(visibleLabel),
-            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
-            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
-          }
-        },
-        data: {
-          details: {
-            reasonCode: 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
-            visibleLabel,
-            accessibleName: accName,
-            normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },
-            labelSource: labelInfo && labelInfo.source ? labelInfo.source : 'none',
-            nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
+      if (containsWordRun(tokenize(visibleLabel, true), tokenize(accName, true), null)) {
+        uncertainty = 'HYPHENATION_DIFFERS';
+      } else {
+        const abbreviated = abbreviatedWords(visibleLabel);
+        if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated))
+          uncertainty = 'POSSIBLE_ABBREVIATION';
+      }
+    }
+
+    if (!contains) {
+      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
+            ? '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'
+            }
+          },
+          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'
+            }
           }
-        }
-      });
+        })
+      );
     }
   }
 
   if (applicableCount === 0)
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
-  if (occurrences.length)
+  if (occurrences.length) {
+    const anyFail = occurrences.some((o) => o.outcome !== 'cantTell');
     return {
       ruleId: rule.ruleId,
-      outcome: 'fail',
+      outcome: anyFail ? 'fail' : 'cantTell',
       severity: rule.defaultSeverity || 'minor',
       occurrences
     };
+  }
   return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
 }
 

package/src/checks/automatic/language-page-present.js

@@ -144,7 +144,11 @@ function runInPage(ctx) {
   }
 
   // Minimal BCP47 primary subtag check
-  if (!/^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(lang)) {
+  const isValidTag =
+    helpers && typeof helpers.isValidLanguageTag === 'function'
+      ? helpers.isValidLanguageTag
+      : (v) => /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(String(v || ''));
+  if (!isValidTag(lang)) {
     return {
       ruleId: rule.ruleId,
       outcome: 'fail',