@surea11y/core 1.4.1 → 1.6.0

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,33 +50,28 @@
  *       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).
  *   Both cases would produce false positives under a hard `fail`, which this
  *   engine reserves for high-confidence violations; `cantTell` routes them to
- *   human review instead. This mirrors how other tools treat 2.4.1 (e.g. axe
- *   marks the no-mechanism case "needs review" via reviewOnFail rather than
- *   failing it), and why no ACT rule hard-fails 2.4.1 by presence alone.
+ *   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';
@@ -228,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;
   }
@@ -244,18 +261,11 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
-  const html = helpers.getOuterHtmlSnippet
-    ? helpers.getOuterHtmlSnippet(body)
-    : (body.outerHTML || '').slice(0, 200);
-
   const occurrences = [
-    {
-      selector: stableSelector,
-      html,
+    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',
@@ -265,7 +275,7 @@ function runInPage(ctx) {
         details: { reasonCode: 'BYPASS_MECHANISM_ABSENT' },
         visibilityFilter: { targetSet: 'acc', accEligible: null, reasons: [] }
       }
-    }
+    })
   ];
 
   return {

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

package/src/checks/manual/css-focus-indicator-suppressed-manual.js

@@ -0,0 +1,444 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check css-focus-indicator-suppressed
+ * @atomic true
+ * @summary CSS must not remove the focus indicator without drawing a replacement
+ * @standard WCAG 2.2
+ * @sc 2.4.7
+ * @applicability
+ *   Elements in sequential focus navigation (tabbable and rendered) on a
+ *   page whose accessible stylesheets contain at least one `:focus` or
+ *   `:focus-visible` rule. With no focus rule anywhere, every element
+ *   keeps the user agent's own indicator and there is nothing to check.
+ * @expectation
+ *   No element is matched by a `:focus`/`:focus-visible` rule that removes
+ *   the outline (`outline: none`, `outline: 0`, `outline-color:
+ *   transparent`, ...) unless some other focus rule matching it draws a
+ *   replacement: a border, box-shadow, background, color change, a
+ *   positive outline of its own, or a `::before`/`::after` decoration.
+ * @implementation-notes
+ * - Authored as `type: 'manual'` (cantTell-capped, never fail). CSS is
+ *   only one of the ways a page can indicate focus: ACT oj04fd's own
+ *   passed examples suppress the outline in CSS and then paint an
+ *   indicator from an `onfocus` handler, on a sibling element. Static
+ *   markup cannot see that, so a suppressed outline is a strong review
+ *   signal rather than a proven failure.
+ * - Suppression is only read off the rule's SUBJECT: in `.a:focus .b`,
+ *   the declarations apply to `.b` while `.a` has focus, so it says
+ *   nothing about `.b`'s own focus indicator. A replacement, by contrast,
+ *   is accepted from any rule whose focused compound matches the element:
+ *   that's exactly the "focus me, paint something elsewhere" pattern
+ *   (`#link:focus + .indicator { background: navy }`), which does give
+ *   the user a visible change.
+ * - Replacement properties are a curated list of the ones that change
+ *   pixels (border, box-shadow, background, color, text-decoration,
+ *   filter, opacity, transform, and `content` for a pseudo-element
+ *   part), matching this engine's other curated-list checks. A rule
+ *   setting only `outline-offset` alongside `outline: none` is not a
+ *   replacement: it offsets an outline that is no longer drawn.
+ * - Cross-origin stylesheets throw on `.cssRules` access and are skipped,
+ *   same limitation as `css-orientation-lock`. A page whose only focus
+ *   styles live in one of those is reported as having no focus rules at
+ *   all, so it is not flagged.
+ * - Selector matching goes through `el.matches()` on the focus pseudo
+ *   stripped out of the selector. A selector the engine cannot parse
+ *   (vendor pseudo-elements, `:host`, unsupported `:is()` forms) throws
+ *   there and is skipped rather than guessed at.
+ */
+
+const id = 'css-focus-indicator-suppressed';
+
+const meta = {
+  title: 'Focus indicator must not be removed without a replacement',
+  description:
+    'Flags elements in the tab order whose focus outline is removed by a :focus/:focus-visible rule with no replacement indicator (border, box-shadow, background, ...) in any other focus rule matching them.',
+  i18n: {
+    titleKey: 'cssFocusIndicatorSuppressed_title',
+    descriptionKey: 'cssFocusIndicatorSuppressed_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2aa', 'wcag247', 'navigation', 'focus', 'css', 'atomic', 'manual'],
+  wcagSc: ['2.4.7'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '2.4.7',
+      title: 'Focus Visible',
+      conformanceLevel: 'AA'
+    }
+  ],
+  defaultSeverity: 'serious',
+  category: 'operable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: { facetsBySc: { '2.4.7': ['focus-indicator-not-suppressed'] } }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  // Declared inside runInPage; see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const CSS_STYLE_RULE = 1;
+
+  // Properties whose presence in a focus rule changes what the user sees.
+  // `outline` is handled separately, since the same property is both the
+  // suppression and the most common replacement.
+  const REPLACEMENT_PROPS = [
+    'background',
+    'background-color',
+    'background-image',
+    'border',
+    'border-color',
+    'border-style',
+    'border-width',
+    'border-top',
+    'border-right',
+    'border-bottom',
+    'border-left',
+    'border-radius',
+    'box-shadow',
+    'color',
+    'content',
+    'filter',
+    'font-weight',
+    'opacity',
+    'text-decoration',
+    'text-decoration-line',
+    'text-decoration-color',
+    'text-shadow',
+    'transform'
+  ];
+
+  const MAX_DEPTH = 10;
+
+  function trim(v) {
+    return (v == null ? '' : String(v)).trim();
+  }
+
+  function lower(v) {
+    return trim(v).toLowerCase();
+  }
+
+  function getProp(style, name) {
+    if (!style) return '';
+    try {
+      if (typeof style.getPropertyValue === 'function') return lower(style.getPropertyValue(name));
+    } catch {
+      return '';
+    }
+    return '';
+  }
+
+  function isZeroLength(v) {
+    return /^0(\.0+)?(px|em|rem|pt|pc|in|cm|mm|ex|ch|vw|vh|vmin|vmax|%)?$/.test(v);
+  }
+
+  // outline: none | 0 | transparent, in shorthand or longhand form.
+  function suppressesOutline(style) {
+    const outlineStyle = getProp(style, 'outline-style');
+    if (outlineStyle === 'none' || outlineStyle === 'hidden') return true;
+
+    const outlineWidth = getProp(style, 'outline-width');
+    if (outlineWidth && isZeroLength(outlineWidth)) return true;
+
+    if (getProp(style, 'outline-color') === 'transparent') return true;
+
+    const outline = getProp(style, 'outline');
+    if (outline) {
+      const tokens = outline.split(/\s+/).filter(Boolean);
+      for (const token of tokens) {
+        if (token === 'none' || token === 'hidden' || token === 'transparent') return true;
+        if (isZeroLength(token)) return true;
+      }
+    }
+    return false;
+  }
+
+  // A positive outline counts as a replacement: `*:focus { outline: none }`
+  // followed by `a:focus { outline: 2px solid }` leaves links indicated.
+  function drawsOutline(style) {
+    if (suppressesOutline(style)) return false;
+    return !!(
+      getProp(style, 'outline') ||
+      getProp(style, 'outline-style') ||
+      getProp(style, 'outline-width') ||
+      getProp(style, 'outline-color')
+    );
+  }
+
+  function providesReplacement(style) {
+    if (drawsOutline(style)) return true;
+    for (const prop of REPLACEMENT_PROPS) {
+      if (getProp(style, prop)) return true;
+    }
+    return false;
+  }
+
+  // Splits a selector list on top-level commas only, so a comma inside
+  // :not(...)/:is(...) does not break a selector in half.
+  function splitSelectorList(selectorText) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of String(selectorText || '')) {
+      if (ch === '(') depth += 1;
+      if (ch === ')') depth = Math.max(0, depth - 1);
+      if (ch === ',' && depth === 0) {
+        parts.push(current);
+        current = '';
+        continue;
+      }
+      current += ch;
+    }
+    if (trim(current)) parts.push(current);
+    return parts.map(trim).filter(Boolean);
+  }
+
+  // :focus and :focus-visible, but never :focus-within: that one fires on
+  // an ancestor of the focused element and says nothing about whether the
+  // element itself is indicated.
+  const FOCUS_PSEUDO = /:focus(-visible)?(?![-\w])/g;
+
+  function hasFocusPseudo(part) {
+    FOCUS_PSEUDO.lastIndex = 0;
+    return FOCUS_PSEUDO.test(part);
+  }
+
+  // Splits a complex selector into its compounds, keeping the combinators
+  // out: "a:focus + .indicator" -> ["a:focus", ".indicator"]. Descendant
+  // combinators inside :not(...)/:is(...) are left alone.
+  function splitCompounds(part) {
+    const compounds = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of part) {
+      if (ch === '(') depth += 1;
+      if (ch === ')') depth = Math.max(0, depth - 1);
+      if (depth === 0 && (ch === ' ' || ch === '>' || ch === '+' || ch === '~')) {
+        if (trim(current)) compounds.push(trim(current));
+        current = '';
+        continue;
+      }
+      current += ch;
+    }
+    if (trim(current)) compounds.push(trim(current));
+    return compounds;
+  }
+
+  function stripFocusPseudo(compound) {
+    const stripped = trim(String(compound).replace(FOCUS_PSEUDO, ''));
+    return stripped || '*';
+  }
+
+  // A pseudo-element part styles generated content rather than the element,
+  // so it can draw a replacement but can never be the thing suppressing the
+  // element's own outline.
+  function hasPseudoElement(part) {
+    return /::[a-z-]+/.test(part) || /:(before|after)\b/.test(part);
+  }
+
+  function matchesSafe(el, selector) {
+    if (!el || typeof el.matches !== 'function' || !selector) return false;
+    try {
+      return el.matches(selector);
+    } catch {
+      return false; // selector this engine cannot parse, skip rather than guess
+    }
+  }
+
+  function closestSafe(el, selector) {
+    if (!el || typeof el.closest !== 'function' || !selector) return false;
+    try {
+      return !!el.closest(selector);
+    } catch {
+      return false;
+    }
+  }
+
+  const suppressors = []; // { selector, base }
+  const providers = []; // { base, subject }
+
+  function collectFromStyleRule(cssRule) {
+    const style = cssRule.style;
+    if (!style) return;
+
+    const suppresses = suppressesOutline(style);
+    const provides = providesReplacement(style);
+    if (!suppresses && !provides) return;
+
+    for (const part of splitSelectorList(cssRule.selectorText)) {
+      if (!hasFocusPseudo(part)) continue;
+
+      const compounds = splitCompounds(part);
+      let focusIndex = -1;
+      for (let i = 0; i < compounds.length; i++) {
+        if (hasFocusPseudo(compounds[i])) {
+          focusIndex = i;
+          break;
+        }
+      }
+      if (focusIndex === -1) continue;
+
+      const isSubject = focusIndex === compounds.length - 1;
+      const focusedBase =
+        stripFocusPseudo(compounds[focusIndex]).replace(/::?[a-z-]+$/i, '') || '*';
+
+      if (suppresses && isSubject && !hasPseudoElement(part)) {
+        suppressors.push({ selector: trim(part), base: stripFocusPseudo(part) });
+      }
+
+      // A replacement is credited to the element that takes focus, wherever
+      // the rule paints it: on the element itself, its pseudo-element, a
+      // sibling, or a descendant.
+      if (provides) providers.push({ base: focusedBase, subject: isSubject });
+    }
+  }
+
+  function walkRules(rules, depth) {
+    if (!rules || depth > MAX_DEPTH) return;
+    for (const cssRule of rules) {
+      if (!cssRule) continue;
+      if (cssRule.type === CSS_STYLE_RULE && cssRule.selectorText) {
+        collectFromStyleRule(cssRule);
+        continue;
+      }
+      // @media, @supports, @layer, ...: recurse into grouping rules.
+      let nested;
+      try {
+        nested = cssRule.cssRules || null;
+      } catch {
+        nested = null;
+      }
+      if (nested) walkRules(nested, depth + 1);
+    }
+  }
+
+  let sheetCount = 0;
+  try {
+    const sheets = document.styleSheets || [];
+    for (const sheet of sheets) {
+      let rules = null;
+      try {
+        rules = sheet && sheet.cssRules ? sheet.cssRules : null;
+      } catch {
+        continue; // cross-origin stylesheet, not inspectable
+      }
+      if (!rules) continue;
+      sheetCount += 1;
+      walkRules(rules, 0);
+    }
+  } catch {
+    // no-throw: treat as no accessible stylesheets
+  }
+
+  if (sheetCount === 0 || !suppressors.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+  const isDomVisibleEligible =
+    helpers && typeof helpers.isDomVisibleEligible === 'function'
+      ? helpers.isDomVisibleEligible
+      : null;
+
+  function isTabbable(el) {
+    if (!getFocusableInfo) return false;
+    try {
+      const info = getFocusableInfo(el, ctx);
+      return !!(info && info.tabbable);
+    } catch {
+      return false;
+    }
+  }
+
+  function isRendered(el) {
+    if (!isDomVisibleEligible) return true;
+    try {
+      const vis = isDomVisibleEligible(el, ctx, {
+        visibilityMode: 'styleOnly',
+        disableGeometry: true
+      });
+      return !(vis && vis.eligible === false);
+    } catch {
+      return true;
+    }
+  }
+
+  const CANDIDATE_SELECTOR =
+    'a[href],area[href],button,input,select,textarea,summary,[tabindex],[contenteditable]';
+  const candidates = helpers.queryAllSmart
+    ? helpers.queryAllSmart(CANDIDATE_SELECTOR)
+    : helpers.queryAll(CANDIDATE_SELECTOR);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of candidates) {
+    if (!el || el.nodeType !== 1) continue;
+    if (!isTabbable(el)) continue;
+    if (!isRendered(el)) continue;
+
+    applicableCount += 1;
+
+    const suppressing = suppressors.filter((s) => matchesSafe(el, s.base));
+    if (!suppressing.length) continue;
+
+    const indicated = providers.some((p) =>
+      p.subject ? matchesSafe(el, p.base) : matchesSafe(el, p.base) || closestSafe(el, p.base)
+    );
+    if (indicated) continue;
+
+    const selectors = [...new Set(suppressing.map((s) => s.selector))];
+    const eligInfo = helpers.getEligibilityInfo
+      ? (() => {
+          try {
+            return helpers.getEligibilityInfo(el, ctx, { targetSet: 'dom' });
+          } catch {
+            return null;
+          }
+        })()
+      : null;
+
+    occurrences.push(
+      helpers.reportOccurrence(el, {
+        summary: `This element takes a tab stop, and "${selectors.join(', ')}" removes its focus outline with no replacement indicator in any other focus rule matching it.`,
+        hint: 'Draw a replacement indicator in the same rule (a visible outline, border, box-shadow, or background change), or drop the outline reset. If the indicator is applied from script instead, confirm it appears for keyboard users.',
+        i18n: {
+          summaryKey: 'cssFocusIndicatorSuppressed_summary_cantTell',
+          hintKey: 'cssFocusIndicatorSuppressed_hint_cantTell',
+          params: { selectors: selectors.join(', ') }
+        },
+        data: {
+          details: {
+            reasonCode: 'FOCUS_INDICATOR_SUPPRESSED',
+            suppressingSelectors: selectors
+          },
+          visibilityFilter: eligInfo || { targetSet: 'dom', accEligible: null, reasons: [] }
+        }
+      })
+    );
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  if (occurrences.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'serious',
+      occurrences
+    };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

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

@@ -9,6 +9,14 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <embed> elements that already carry a text alternative: a
+ *   non-empty aria-label, an aria-labelledby that resolves to non-empty
+ *   text, or a non-empty title. An aria-labelledby pointing at a missing id
+ *   resolves to nothing and so is not a text alternative to review; that
+ *   element is embed-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.
  */