@surea11y/core 1.5.0 → 1.6.0

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

@@ -8,6 +8,24 @@
  * @summary Pointer-operable targets should be at least 24×24 CSS px (or meet an exception)
  * @standard WCAG 2.2
  * @sc 2.5.8
+ * @applicability
+ *   Applies to <button>, <summary>, <a href>, <area href>, <input>,
+ *   <select>, <textarea> and elements with role="button"/"link" that are
+ *   pointer-reachable: rendered, not suppressed by pointer-events:none, and
+ *   with a measurable box of non-zero size. Accessibility-tree exclusion isn't
+ *   a filter here: an aria-hidden control is still a target a pointer can hit.
+ *   <area> is matched but never actually evaluated, for the reason given below.
+ * @expectation
+ *   Each target is at least 24 by 24 CSS pixels, or meets one of the SC
+ *   2.5.8 exceptions this rule can establish from geometry: spacing (a
+ *   24px-diameter circle centred on the target reaches no unrelated target),
+ *   the inline exception for a link inside a run of text, or user-agent
+ *   sizing (an unstyled native checkbox or radio, detected by appearance not
+ *   having been reset to none). An undersized target too close to a
+ *   neighbour fails. Where an exception may apply but geometry cannot
+ *   confirm it (two inline links in one run of text, or a target inside an
+ *   SVG, canvas or image map that may be essential), the result is cantTell
+ *   rather than a guess.
  *
  * Notes (engine intent):
  * - This rule is DOM-based and measures pointer hit regions available to sighted pointer users.
@@ -19,42 +37,43 @@
  * - Spacing: a 24px-diameter circle centered on an undersized target must not
  *   intersect another (unrelated) target's box or another undersized
  *   target's own circle. Two passes: a fast center-distance check (exact for
- *   undersized-vs-undersized; a reasonable proxy otherwise) and a 16-point
+ *   undersized-vs-undersized, a reasonable proxy otherwise) and a 16-point
  *   perimeter sample via elementFromPoint as a more precise fallback for
  *   cases the distance check under-detects (e.g. a small target adjacent to
  *   a large, elongated neighbor). Ancestor/descendant relationships between
- *   the target and the "other" element are never treated as a conflict —
- *   see isRelated — since a nested-interactive shape (a small control inside
- *   its own wrapping link/button) is one visual region, not two independent
- *   targets; that pattern is nested-interactive-controls-absent's
- *   concern, not a spacing one.
+ *   the target and the "other" element are never treated as a conflict (see
+ *   isRelated): a nested-interactive shape, a small control inside its own
+ *   wrapping link/button, is one visual region, not two independent targets.
+ *   That pattern is nested-interactive-controls-absent's concern, not a
+ *   spacing one.
  * - Inline: a link inside a text-block container passes outright
  *   (isInlineTextExceptionTarget). An inline link whose only spacing conflict
  *   is another inline link in the same run is reported as cantTell
- *   (isInlineLinkTarget) — the inline exception may cover it, but geometry
- *   can't confirm that.
+ *   (isInlineLinkTarget), since the inline exception may cover it but
+ *   geometry can't confirm that.
  * - User Agent Control: an unstyled native checkbox/radio, detected via
- *   `appearance` not being reset to `none` (see isUserAgentSizedControl) —
- *   scoped narrowly to checkbox/radio specifically, not every form control,
+ *   `appearance` not being reset to `none` (see isUserAgentSizedControl).
+ *   Scoped narrowly to checkbox/radio specifically, not every form control,
  *   since those are the only types with unambiguous native rendering.
  * - Essential/Equivalent: only a narrow, high-confidence subset is asserted
- *   (SVG/canvas/map-embedded controls) — see isPlausiblyEssentialOrEquivalent;
+ *   (SVG/canvas/map-embedded controls, see isPlausiblyEssentialOrEquivalent);
  *   anything else defers to cantTell rather than guessing "essential" from a
  *   layout container.
  *
- * Known, deliberately unimplemented gap: `<area>` (image-map hotspot)
+ * Known gap, left unimplemented on purpose: `<area>` (image-map hotspot)
  * elements are not evaluated at all. `area[href]` is in CANDIDATE_SELECTOR
- * for forward-compatibility, but it's currently a no-op: `<area>` has no
+ * for forward-compatibility, but it's currently a no-op. `<area>` has no
  * CSS box of its own (`display: none` by the HTML spec's default UA
- * stylesheet — verified, not a jsdom quirk), so `getBoundingClientRect()`
- * always reports zero geometry and `isPointerReachable`'s existing
- * `display:none` check rejects it before any size/exception logic runs. A
- * real `<area>` hit-region is computed by the browser from its `shape`/
- * `coords` attributes against the associated `<img>`'s *rendered* size —
- * an entirely different measurement path than every other candidate here.
- * Implementing that properly (parsing `coords`, resolving the owning
- * `<img>` via its `usemap`, accounting for the image's CSS-scaled render
- * size) is a separate, larger feature, not attempted in this pass.
+ * stylesheet, confirmed against the spec rather than a jsdom quirk), so
+ * `getBoundingClientRect()` always reports zero geometry and
+ * `isPointerReachable`'s existing `display:none` check rejects it before any
+ * size/exception logic runs. A real `<area>` hit-region is computed by the
+ * browser from its `shape`/`coords` attributes against the associated
+ * `<img>`'s *rendered* size, an entirely different measurement path than
+ * every other candidate here. Implementing that properly (parsing `coords`,
+ * resolving the owning `<img>` via its `usemap`, accounting for the image's
+ * CSS-scaled render size) is a separate, larger feature, not attempted in
+ * this pass.
  *
  * This is an automatic, deterministic approximation intended to be:
  * - strict on clear failures,
@@ -64,7 +83,8 @@
 const id = 'target-size-minimum';
 
 const meta = {
-  title: 'Pointer targets meet minimum size (AA)',
+  title:
+    'Pointer targets must be at least 24x24px large, or leave sufficient distance to other targets',
   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).',
   i18n: {
@@ -354,11 +374,11 @@ function runInPage(ctx) {
   // element, or either one is an ancestor of the other. A nested-interactive
   // pattern (e.g. a small <button> inside a wrapping <a href>, or vice
   // versa) is a single visual/interactive region, not two independently
-  // placed targets — the spacing exception's "does the circle intersect
+  // placed targets. The spacing exception's "does the circle intersect
   // ANOTHER target" language is about separate targets, not an element and
   // its own container. (Nested interactive controls are their own,
-  // separately-flagged anti-pattern — nested-interactive-controls-
-  // absent — not a target-size spacing concern.)
+  // separately-flagged anti-pattern, nested-interactive-controls-absent,
+  // not a target-size spacing concern.)
   function isRelated(a, b) {
     try {
       if (!a || !b) return false;
@@ -415,7 +435,7 @@ function runInPage(ctx) {
   function hasSpacingConflict(target) {
     // 0) Pure geometry: deterministic center-distance check against ANY
     // nearby target, not just other undersized ones. Per WCAG 2.5.8, the
-    // spacing exception depends on proximity to any adjacent target — an
+    // spacing exception depends on proximity to any adjacent target, so an
     // undersized target sitting flush against an adequately-sized one still
     // fails the exception, which an undersized-only comparison would miss.
     for (const other of items) {
@@ -439,8 +459,8 @@ function runInPage(ctx) {
     // as a confident conflict. Perimeter sampling is an approximation
     // (rounded corners, border-radius, and sub-pixel geometry can shift a
     // sample point in or out of a neighboring element), so a result that
-    // merely reaches HIT_THRESHOLD is not asserted as a deterministic
-    // fail — see the ambiguous band below.
+    // merely reaches HIT_THRESHOLD is not asserted as a deterministic fail.
+    // See the ambiguous band below.
     const CONFIDENT_THRESHOLD = 5;
     let hitCount = 0;
     let firstConflictEl = null;
@@ -486,20 +506,20 @@ function runInPage(ctx) {
 
   // WCAG 2.5.8 "User Agent Control" exception: the target's size requirement
   // does not apply at all when its size is determined by the user agent and
-  // not modified by the author — the canonical example being an unstyled
-  // native checkbox/radio (browsers render these well under 24px by
-  // default, and that's not the author's choice). Scoped narrowly to
-  // input[type=checkbox]/[type=radio] specifically (the only form-control
-  // types with a universally-recognized, unambiguous native rendering) —
-  // deliberately not extended to select/range/color/file, whose "default"
-  // sizing varies enough across browsers/OSes that a wrong exemption there
-  // risks masking a real author-introduced undersized target.
+  // not modified by the author. The canonical example is an unstyled native
+  // checkbox/radio (browsers render these well under 24px by default, and
+  // that's not the author's choice). Scoped narrowly to
+  // input[type=checkbox]/[type=radio] specifically, the only form-control
+  // types with a universally-recognized, unambiguous native rendering, and
+  // not extended to select/range/color/file, whose "default" sizing varies
+  // enough across browsers/OSes that a wrong exemption there risks masking a
+  // real author-introduced undersized target.
   //
   // Detection signal: `appearance` (or the legacy `-webkit-appearance`)
   // computed as `none` is the near-universal first step of custom
-  // checkbox/radio styling across every CSS framework/design system —
-  // if the author hasn't reset it, the browser is still rendering its own
-  // default control chrome, so the size is genuinely UA-determined.
+  // checkbox/radio styling across every CSS framework/design system. If the
+  // author hasn't reset it, the browser is still rendering its own default
+  // control chrome, so the size is UA-determined rather than authored.
   function isUserAgentSizedControl(el) {
     try {
       if (!el || el.nodeType !== 1) return false;
@@ -545,8 +565,8 @@ function runInPage(ctx) {
       // Image map targets are often constrained by the underlying image.
       // Currently unreachable in practice: <area> never becomes a
       // measurable candidate at all (see the file header's "Known,
-      // deliberately unimplemented gap" note) — kept for forward
-      // compatibility if that gap is closed later.
+      // unimplemented gap" note). Kept for forward compatibility if that
+      // gap is closed later.
       if (tag === 'area') return true;
 
       // Graphics / spatial interaction regions are commonly essential by design.
@@ -570,7 +590,7 @@ function runInPage(ctx) {
 
     // User Agent Control exception: size isn't the author's choice, so the
     // size requirement (and therefore any spacing conflict stemming from
-    // it) doesn't apply at all — skip straight to pass, no need to even
+    // it) doesn't apply at all. Skip straight to pass, no need to even
     // evaluate spacing.
     if (isUserAgentSizedControl(it.el)) {
       continue;
@@ -579,12 +599,10 @@ function runInPage(ctx) {
     const info = hasSpacingConflict(it);
 
     if (!info.conflict && info.confident === false) {
-      // 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.
+      // Ambiguous perimeter-sampling result near the decision threshold: report
+      // it as its own cantTell-tier occurrence for this target so it isn't lost
+      // once any other target on the page has a confident fail (see
+      // helpers.resolveTieredOutcome's header comment).
       cantTellOccurrences.push(
         helpers.reportOccurrence(it.el, {
           occurrenceOutcome: 'cantTell',
@@ -612,14 +630,14 @@ function runInPage(ctx) {
     if (info.conflict) {
       if (isPlausiblyEssentialOrEquivalent(it.el)) {
         // 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.
+        // of an essential graphic/image-map region, so report it as
+        // cantTell rather than dropping it.
         cantTellOccurrences.push(
           helpers.reportOccurrence(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.',
+            hint: 'Verify whether this target’s size is 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',
@@ -691,7 +709,7 @@ function runInPage(ctx) {
 
   // 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'.
+  // the same run. Both are returned together when the outcome is 'fail'.
   const resolved = helpers.resolveTieredOutcome(
     failOccurrences,
     cantTellOccurrences,

package/src/checks/automatic/td-has-header.js

@@ -11,7 +11,7 @@
  * @applicability
  *   `<table>` elements with at least 4 rows and at least 4 columns
  *   (a "large" table, where implicit row/column header association is
- *   genuinely useful — small tables are usually self-evident), and with
+ *   useful; small tables are usually self-evident), and with
  *   NO `colspan`/`rowspan` anywhere in the table.
  * @expectation
  *   Every `<td>` has an associated header, via one of:
@@ -22,14 +22,14 @@
  *       earlier row, OR
  *     - an implicit row header: some `<th>` earlier in the same row.
  * @implementation-notes
- * - Closes the gap `table-th-has-data-cells` deliberately deferred (see
+ * - Closes the gap `table-th-has-data-cells` deferred (see
  *   that rule's own implementation notes): this is the fuller positional
- *   header-association algorithm, but still intentionally scoped —
+ *   header-association algorithm, but still intentionally scoped,
  *   tables with any `colspan`/`rowspan` are skipped entirely (marked
  *   `notApplicable`) rather than risk a wrong column-index computation
  *   producing a false `fail`.
  * - The `headers`-attribute branch does not itself validate that the
- *   referenced ids exist or point at `<th>` elements — that's already
+ *   referenced ids exist or point at `<th>` elements, that's already
  *   `table-headers-attr-valid`'s job.
  */
 
@@ -38,7 +38,7 @@ const id = 'td-has-header';
 const meta = {
   title: 'Data cells in large tables must have an associated header',
   description:
-    'Checks that every <td> in a large, simple (no colspan/rowspan) table has an associated header — via a headers attribute, an implicit column <th> above it, or an implicit row <th> to its left.',
+    'Checks that every <td> in a large, simple (no colspan/rowspan) table has an associated header, via a headers attribute, an implicit column <th> above it, or an implicit row <th> to its left.',
   i18n: {
     titleKey: 'tdHasHeader_title',
     descriptionKey: 'tdHasHeader_description'

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

@@ -2,11 +2,31 @@
 
 'use strict';
 
+/**
+ * @check textbox-name-present
+ * @atomic true
+ * @summary Elements with role="textbox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="textbox" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute 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.
+ *   role="textbox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom textbox widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="textbox">) an
+ *   associated <label> counts as well.
+ */
+
 const id = 'textbox-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Textboxes have an accessible name',
+  description: 'Checks that elements with role="textbox" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'textboxNamePresent_title',
     descriptionKey: 'textboxNamePresent_description'
@@ -51,7 +71,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -68,7 +88,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -83,10 +103,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -96,7 +116,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).
@@ -231,7 +251,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This element has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this textbox's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this textbox's accessible name.",
         i18n: {
           summaryKey: 'textboxNamePresent_summary_fail',
           hintKey: 'textboxNamePresent_hint_fail',

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check tooltip-name-present
+ * @atomic true
+ * @summary Elements with role="tooltip" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="tooltip" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute 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, from title, or,
+ *   role="tooltip" being name-from-content, from its own subtree text,
+ *   where a descendant's own name (an <img alt>, aria-label or title) counts
+ *   as that descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'tooltip-name-present';
 
 const meta = {
@@ -51,7 +70,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +89,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).

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

@@ -2,11 +2,30 @@
 
 'use strict';
 
+/**
+ * @check treeitem-name-present
+ * @atomic true
+ * @summary Elements with role="treeitem" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="treeitem" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute 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, from title, or,
+ *   role="treeitem" being name-from-content, from its own subtree text,
+ *   where a descendant's own name (an <img alt>, aria-label or title) counts
+ *   as that descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'treeitem-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Tree items have an accessible name',
+  description: 'Checks that elements with role="treeitem" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'treeitemNamePresent_title',
     descriptionKey: 'treeitemNamePresent_description'
@@ -51,7 +70,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
     // it has one, not just literal text nodes. See getContentNameInfo's
     // header comment in src/core/dom-helpers.js for the full rationale
@@ -70,7 +89,7 @@ function runInPage(ctx) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
     // Delegates to the shared getTextFromIdRefs helper instead of computing
-    // name-from-content of the referenced element — see dialog-name-
+    // name-from-content of the referenced element, see dialog-name-
     // present.js's identical fix for the full rationale (an <iframe>
     // aria-labelledby target's only name source is its title attribute,
     // which name-from-content alone can never see).

package/src/checks/automatic/valid-lang.js

@@ -10,11 +10,23 @@
  * @sc 3.1.2
  * @applicability
  *   Applies to any element other than the root <html> with a non-empty
- *   lang attribute.
+ *   lang attribute AND at least some non-whitespace "governed text" that
+ *   actually inherits its language from that element, per ACT de46e4:
+ *   - Descendant text/alt is governed by the nearest lang-carrying
+ *     ancestor only, a nested descendant with its own non-empty lang
+ *     re-scopes everything inside it, so that subtree no longer counts
+ *     toward the outer element's applicability (it counts toward the
+ *     nested element's own, if that one is also being evaluated).
+ *   - A non-empty alt attribute on img/area/input[type=image] counts as
+ *     governed text, the same as a text node.
+ *   - Text (or alt) that CSS keeps out of the render tree (display:none,
+ *     the hidden attribute, ...) does not count. aria-hidden and
+ *     offscreen positioning do NOT exempt text, per ACT's own failed
+ *     examples for both, only actual non-rendering does.
  * @expectation
  *   The lang value matches a valid BCP47 language-tag syntax. WCAG 3.1.2
  *   (Language of Parts) requires that when a passage's language differs
- *   from the page's default, it is identified programmatically — an
+ *   from the page's default, it is identified programmatically. An
  *   invalid tag fails to identify a real language at all.
  * @implementation-notes
  * - Distinct, atomic decision from html-lang-attr-present (that
@@ -22,7 +34,7 @@
  *   covers every other element, for SC 3.1.2.
  * - Same minimal BCP47 *syntax* check as html-lang-attr-present (primary
  *   subtag + optional subtags), not IANA Language Subtag Registry
- *   validation — same documented scope limitation (syntactically
+ *   validation, same documented scope limitation (syntactically
  *   well-formed but unregistered tags like "xx-ZZ" are not flagged).
  */
 
@@ -66,6 +78,78 @@ function runInPage(ctx) {
       ? helpers.isValidLanguageTag
       : (v) => BCP47_RE.test(String(v || ''));
 
+  function isDomVisible(node) {
+    if (!node) return false;
+    if (helpers.isDomVisibleEligible)
+      return !!helpers.isDomVisibleEligible(node, ctx, { targetSet: 'dom' }).eligible;
+    if (helpers.getEligibilityInfo)
+      return !!helpers.getEligibilityInfo(node, ctx, { targetSet: 'dom' }).eligible;
+    return true;
+  }
+
+  function hasOwnNonEmptyLang(node) {
+    try {
+      const v = node.getAttribute ? node.getAttribute('lang') : null;
+      return v != null && v.trim() !== '';
+    } catch {
+      return false;
+    }
+  }
+
+  function isAltBearing(node) {
+    const tag = (node.tagName || '').toLowerCase();
+    if (tag === 'img' || tag === 'area') return true;
+    if (tag !== 'input') return false;
+    try {
+      return (node.getAttribute('type') || '').toLowerCase() === 'image';
+    } catch {
+      return false;
+    }
+  }
+
+  // "Governed text": non-whitespace text (or alt) that inherits its
+  // language from `root`, per ACT de46e4, see @applicability above. Walks
+  // the flat subtree, stopping at any descendant carrying its own non-empty
+  // lang (that subtree governs itself, not `root`), and treating
+  // display:none/hidden content as absent. Bails out as soon as any
+  // qualifying text is found; a node-visit budget guards pathological
+  // markup the same way other subtree walks in this engine do.
+  const MAX_VISITS = 5000;
+  function hasGovernedText(root) {
+    let found = false;
+    let visits = 0;
+
+    function walk(node, isRoot) {
+      if (found || visits++ > MAX_VISITS) return;
+      if (!node || node.nodeType !== 1) return;
+      if (!isRoot && hasOwnNonEmptyLang(node)) return; // re-scoped to itself
+
+      if (isAltBearing(node)) {
+        const alt = node.getAttribute ? node.getAttribute('alt') : null;
+        if (alt != null && alt.trim() !== '' && isDomVisible(node)) found = true;
+        return; // alt-bearing elements have no other text to walk into
+      }
+
+      if (!isDomVisible(node)) return;
+
+      const kids = node.childNodes ? Array.from(node.childNodes) : [];
+      for (const kid of kids) {
+        if (found) return;
+        if (kid.nodeType === 3) {
+          if (String(kid.nodeValue || '').trim()) {
+            found = true;
+            return;
+          }
+        } else if (kid.nodeType === 1) {
+          walk(kid, false);
+        }
+      }
+    }
+
+    walk(root, true);
+    return found;
+  }
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('[lang]')
     : helpers.queryAll('[lang]');
@@ -80,10 +164,11 @@ function runInPage(ctx) {
     const rawAttr = el.getAttribute('lang');
     if (rawAttr === null || rawAttr === '') continue; // ACT de46e4: empty is out of scope
 
-    // The rule applies only where text actually inherits the language, so an
-    // element with no text, or whose text reaches no one, has nothing to
-    // declare a language for.
-    if (!String(el.textContent || '').trim()) continue;
+    // The rule applies only where text actually inherits the language from
+    // THIS element specifically, not merely where the subtree has any text
+    // at all, which could all belong to a nested element's own (possibly
+    // valid) lang instead. See hasGovernedText's doc comment.
+    if (!hasGovernedText(el)) continue;
 
     applicableCount += 1;
 

package/src/checks/automatic/video-poster-text-alternative-present.js

@@ -87,7 +87,7 @@ function runInPage(ctx) {
 
   function computeNameInfo(el) {
     // <video> is not a labelable element (no browser computes an accessible
-    // name from <label for="...">), so only ARIA naming and title count —
+    // name from <label for="...">), so only ARIA naming and title count,
     // do not accept native <label> associations.
     const flags = [];
     let aria = null;

package/src/checks/manual/accesskeys-manual.js

@@ -6,17 +6,17 @@
  * @check accesskeys
  * @atomic true
  * @summary accesskey values must be unique on the page
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies whenever two or more elements share the same non-empty
  *   accesskey attribute value (case-insensitive).
  * @expectation
  *   Every accesskey value on the page is unique. Duplicate accesskeys
- *   make keyboard-shortcut activation ambiguous — only one of the
+ *   make keyboard-shortcut activation ambiguous: only one of the
  *   elements sharing the key can actually be reached by it, and which
  *   one is browser/platform-dependent.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  */

package/src/checks/manual/area-alt-decorative-manual.js

@@ -9,6 +9,13 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <area> elements whose alt attribute is present but empty once
+ *   trimmed, the markup that declares a hotspot decorative. The <area> must
+ *   belong to a <map> that an <img usemap> actually references, and both
+ *   that <img> and the <area> itself must be included in the accessibility
+ *   tree; an <area> in an unused map is out of scope.
+ *   role="presentation"/"none" takes an element out unless it is focusable.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

package/src/checks/manual/area-alt-quality-manual.js

@@ -9,6 +9,12 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <area> elements whose alt attribute is present and non-empty.
+ *   The <area> must belong to a <map> that an <img usemap> actually
+ *   references, and both that <img> and the <area> itself must be included
+ *   in the accessibility tree; an <area> in an unused map is out of scope.
+ *   role="presentation"/"none" takes an element out unless it is focusable.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */