@surea11y/core 1.5.0 → 1.7.0

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.
  */

package/src/checks/manual/aria-checked-state-mismatch-manual.js

@@ -14,13 +14,13 @@
  * @expectation
  *   `aria-checked` is redundant on a native checkbox/radio (the role's
  *   checked state is already exposed natively), but when an author sets
- *   it explicitly it should agree with the element's actual state —
+ *   it explicitly it should agree with the element's actual state,
  *   otherwise assistive technology is told something different from what
  *   a sighted user perceives.
  * @implementation-notes
- * - Deliberately authored as `type: 'manual'` (cantTell-capped, never
- *   fail), unlike most ARIA-validity rules in this file family. This
- *   engine analyzes STATIC markup only (no script execution) — `.checked`
+ * - Authored as `type: 'manual'` (cantTell-capped, never fail), unlike
+ *   most ARIA-validity rules in this file family. This engine analyzes
+ *   STATIC markup only (no script execution), so `.checked`
  *   reliably reflects the static `checked` attribute for freshly-parsed
  *   markup, but a very common, entirely legitimate real-world pattern is a
  *   JS-hydrated widget whose server-rendered HTML intentionally ships
@@ -118,7 +118,7 @@ function runInPage(ctx) {
       helpers.reportOccurrence(el, {
         summary:
           'This element’s aria-checked value does not match its actual checked/indeterminate state.',
-        hint: 'Set aria-checked to match the element’s real state, or remove it — a native checkbox/radio already exposes this state without it.',
+        hint: 'Set aria-checked to match the element’s real state, or remove it; a native checkbox/radio already exposes this state without it.',
         i18n: {
           summaryKey: 'ariaCheckedStateMismatch_summary_cantTell',
           hintKey: 'ariaCheckedStateMismatch_hint_cantTell',

package/src/checks/manual/aria-text-manual.js

@@ -6,7 +6,7 @@
  * @check aria-text
  * @atomic true
  * @summary role="text" elements should have no focusable descendants
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Elements with an explicit `role="text"`.
  * @expectation
@@ -14,10 +14,10 @@
  *   subtree as a single unit of plain text (e.g. text visually split
  *   across multiple `<span>`s by styling). Per the WAI-ARIA Authoring
  *   Practices, this only makes sense when that subtree contains no
- *   focusable content — a focusable descendant inside a "this is just
+ *   focusable content: a focusable descendant inside a "this is just
  *   text" region is unreachable or confusing for keyboard/AT users.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule, matching the Tier 1b precedent (see
  *   `landmark-unique`'s header comment for the shared rationale).
  * - "Focusable descendant" is a presence check (link/button/form
@@ -80,7 +80,7 @@ function runInPage(ctx) {
       selector: stableSelector,
       html,
       summary: 'This role="text" element contains a focusable descendant.',
-      hint: 'Remove role="text" (or remove the focusable descendant) — a "plain text" region should not contain focusable content.',
+      hint: 'Remove role="text" (or remove the focusable descendant); a "plain text" region should not contain focusable content.',
       i18n: {
         summaryKey: 'ariaText_summary_cantTell',
         hintKey: 'ariaText_hint_cantTell',

package/src/checks/manual/bypass-blocks-present-manual.js

@@ -9,31 +9,36 @@
  * @standard WCAG 2.2
  * @sc 2.4.1
  * @applicability
- *   Always applicable to any HTML document with a <body> element —
+ *   Always applicable to any HTML document with a <body> element:
  *   "bypass blocks" is a whole-page concern, matching
  *   aria-hidden-body / page-title-present's pattern of
  *   evaluating the document directly rather than a scoped root.
  * @expectation
  *   At least one of the following recognized WCAG 2.4.1 techniques is
  *   present:
- *   (a) a main landmark (<main> or [role="main"]) — technique ARIA11: a
+ *   (a) a main landmark (<main> or [role="main"]), technique ARIA11: a
  *       screen reader user can jump straight to it, bypassing everything
  *       before it (nav, header, repeated blocks) in one step;
- *   (b) a working same-page anchor link — technique G1/G123: an
+ *   (b) a working same-page anchor link, technique G1/G123: an
  *       <a href="#id"> (or legacy <a name="id">) whose target resolves to
  *       a real element in the link's own tree (light DOM or the same shadow
- *       root). Deliberately NOT required to be positioned before a <nav> or
- *       be keyboard-focus-order-first — see implementation notes;
- *   (c) at least one heading (<h1>-<h6> or [role="heading"]) — technique
- *       H69: heading navigation is itself a standards-recognized bypass
- *       mechanism (e.g. a screen reader's "jump by heading" command).
+ *       root). Not required to be positioned before a <nav> or be
+ *       keyboard-focus-order-first (see implementation notes);
+ *   (c) at least one heading (<h1>-<h6> or [role="heading"]) that is both
+ *       included in the accessibility tree AND visible (not off-screen,
+ *       clipped, opacity:0, or zero-size-overflow-hidden), technique H69:
+ *       heading navigation is itself a standards-recognized bypass
+ *       mechanism (e.g. a screen reader's "jump by heading" command), but
+ *       ACT 047fe0's own Expectation requires visibility too, since a
+ *       screen-reader-only heading leaves sighted keyboard users with no
+ *       equivalent way to locate the start of non-repeated content.
  * @implementation-notes
  * - Outcome model: this rule is `type: 'manual'` (cantTell-capped, never
  *   `fail`). When a recognized mechanism is found the page has nothing to
  *   review here → `notApplicable` (matching page-has-heading-one-manual /
  *   skip-link-manual's "nothing to flag" convention). When none is found we
- *   return `cantTell` — "we could not detect a bypass mechanism, please
- *   verify" — rather than a hard `fail`. The absence of a *detectable*
+ *   return `cantTell`: "we could not detect a bypass mechanism, please
+ *   verify," rather than a hard `fail`. The absence of a *detectable*
  *   mechanism is NOT high-confidence evidence that 2.4.1 is violated, for
  *   several reasons the engine cannot resolve from a single static snapshot:
  *     • Applicability itself is undecidable in-page. 2.4.1 governs blocks of
@@ -45,7 +50,7 @@
  *       rest of the page is routinely made `inert` or `aria-hidden="true"`,
  *       so the page's real <main>/headings are (correctly) filtered out by
  *       isAccTreeEligible for the duration of that state and only the dialog
- *       is exposed — a snapshot taken then would see "no mechanism" though
+ *       is exposed, so a snapshot taken then would see "no mechanism" though
  *       the page has one once the dialog closes. The same applies to content
  *       that is display:none until revealed by script (tabs, accordions, an
  *       unmounted SPA view).
@@ -54,23 +59,19 @@
  *   human review instead. No ACT rule hard-fails 2.4.1 by presence alone,
  *   for the same reason.
  * - This rule intentionally checks presence, not position, for the
- *   same-page-anchor condition (b): a full bypass algorithm is heuristic
- *   (see ROADMAP.md's Tier 1a note on why this rule was
- *   deferred from the rest of that batch), and getting DOM-order /
- *   keyboard-focus-order positioning exactly right without introducing
- *   false positives is materially harder than the rest of Tier 1a. Being
- *   lenient about condition (b) can only make us *miss* a review prompt
- *   (a page whose only anchor link isn't a real skip mechanism, e.g. a
- *   "back to top" link) — never raise a spurious one.
+ *   same-page-anchor condition (b): a full bypass algorithm is heuristic,
+ *   and getting DOM-order / keyboard-focus-order positioning exactly right
+ *   without introducing false positives is materially harder than checking
+ *   presence alone. Being lenient about condition (b) can only make us
+ *   *miss* a review prompt (a page whose only anchor link isn't a real
+ *   skip mechanism, e.g. a "back to top" link), never raising a spurious one.
  * - Shadow DOM: all three conditions use `helpers.queryAllSmart`, which is
  *   shadow-DOM-aware (when the run enables includeShadowDom) and applies the
  *   engine's hidden-content policy. The same-page-anchor target is resolved
- *   in the link's own root (`getRootNode()` — the document, or the shadow
+ *   in the link's own root (`getRootNode()`: the document, or the shadow
  *   root the link lives in) before falling back to the document, so a skip
  *   link encapsulated in a web component is credited the same as one in the
- *   light DOM. (Previously the anchor path used raw
- *   `document.querySelectorAll`/`getElementById`, which never pierced shadow
- *   roots — a genuine gap now closed.)
+ *   light DOM.
  */
 
 const id = 'bypass-blocks-present';
@@ -227,9 +228,26 @@ function runInPage(ctx) {
     return false;
   }
 
+  // ACT 047fe0's own Expectation requires the heading to be visible, not
+  // only included in the accessibility tree: a screen-reader-only heading
+  // still leaves sighted keyboard users with no way to locate the start of
+  // non-repeated content. "Visible" per ACT's own glossary: making it fully
+  // transparent would change rendered pixels, which every CSS-only hiding
+  // technique (off-screen positioning, clip/clip-path, opacity:0, a
+  // zero-size overflow:hidden box) fails.
+  function isCssHidden(el) {
+    if (!helpers || typeof helpers.getVisibilityHintsInfo !== 'function') return false;
+    try {
+      const info = helpers.getVisibilityHintsInfo(el, ctx, {});
+      return !!(info && Array.isArray(info.hints) && info.hints.length > 0);
+    } catch {
+      return false;
+    }
+  }
+
   function hasHeading() {
     for (const el of queryAll('h1, h2, h3, h4, h5, h6, [role="heading"]')) {
-      if (el && isExposedToAt(el)) return true;
+      if (el && isExposedToAt(el) && !isCssHidden(el)) return true;
     }
     return false;
   }
@@ -246,8 +264,8 @@ function runInPage(ctx) {
   const occurrences = [
     helpers.reportOccurrence(body, {
       summary:
-        'No recognized way to bypass repeated blocks of content was detected on this page — verify a bypass mechanism exists.',
-      hint: 'Confirm the page offers a bypass mechanism: a main landmark (<main> or role="main"), a working "skip to content" link, or heading elements that assistive technology can use to jump past repeated content. (A mechanism may be temporarily hidden — e.g. while a modal dialog makes the page inert — or provided on a per-site basis; this needs human confirmation.)',
+        'No recognized way to bypass repeated blocks of content was detected on this page. Verify a bypass mechanism exists.',
+      hint: 'Confirm the page offers a bypass mechanism: a main landmark (<main> or role="main"), a working "skip to content" link, or heading elements that assistive technology can use to jump past repeated content. (A mechanism may be temporarily hidden, e.g. while a modal dialog makes the page inert, or provided on a per-site basis; this needs human confirmation.)',
       i18n: {
         summaryKey: 'bypassBlocksPresent_summary_cantTell',
         hintKey: 'bypassBlocksPresent_hint_cantTell',

package/src/checks/manual/canvas-text-alternative-quality-manual.js

@@ -9,6 +9,14 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <canvas> elements that already carry a text alternative:
+ *   fallback content inside the element, an ARIA name, or a title. A
+ *   <canvas> with none of those has no alternative whose quality could be
+ *   judged; that's canvas-text-alternative-present's failure. The element
+ *   must be included in the accessibility tree, and
+ *   role="presentation"/"none" takes it out of scope unless it is focusable,
+ *   which restores its role.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */