pour-engine 1.43.0 → 1.44.1

package/config/project.config.js

@@ -6,6 +6,6 @@
 export default {
   engine: {
     name: 'pour engine',
-    version: '1.43.0',
+    version: '1.44.1',
   },
 };

package/engine/lib/contrast.js

@@ -143,6 +143,8 @@ let firstLineRulesCache = new WeakMap();
 let chainEffectCache = new WeakMap();
 let uncoveredEffectCache = new WeakMap();
 let blendBackdropCache = new WeakMap();
+let labelReferrersCache = new WeakMap();
+let stackingContextCache = new WeakMap();
 const HAS_IMAGE = Symbol('background-image in chain');
 
 export function resetAuditCaches() {
@@ -157,6 +159,35 @@ export function resetAuditCaches() {
   chainEffectCache = new WeakMap();
   uncoveredEffectCache = new WeakMap();
   blendBackdropCache = new WeakMap();
+  labelReferrersCache = new WeakMap();
+  stackingContextCache = new WeakMap();
+}
+
+/**
+ * Who names themselves from each id through aria-labelledby, per root
+ * (document or shadow root): how many of the referrers are inactive widgets
+ * and how many are anything else. Counted once per audit, because the
+ * contrast rule asks for every element with text of its own and a query
+ * over the whole page for each would make that walk quadratic. `isInactive`
+ * is the rule's own reading of a switched-off widget, so this library does
+ * not carry a second one.
+ */
+export function labelReferrers(root, isInactive) {
+  let referrers = labelReferrersCache.get(root);
+  if (!referrers) {
+    referrers = new Map();
+    for (const referrer of root.querySelectorAll('[aria-labelledby]')) {
+      const inactive = isInactive(referrer);
+      for (const id of referrer.getAttribute('aria-labelledby').split(/\s+/)) {
+        if (!id) continue;
+        const count = referrers.get(id) ?? { inactive: 0, other: 0 };
+        count[inactive ? 'inactive' : 'other'] += 1;
+        referrers.set(id, count);
+      }
+    }
+    labelReferrersCache.set(root, referrers);
+  }
+  return referrers;
 }
 
 const flatParentOf = (node) => node.assignedSlot ?? node.parentElement ?? node.getRootNode()?.host ?? null;
@@ -778,6 +809,21 @@ function pseudoLayers(host) {
       continue;
     }
     if (rect.empty) continue; // placed, and covers nothing
+    // A mask or a clip-path cuts the box down to a shape, and how much of
+    // the box that shape leaves is not computed here. The box covering the
+    // text then proves nothing about the paint doing so: a struck-through
+    // price drawn as a text-sized red ::after masked to one diagonal stroke
+    // was read as black text on red, 3.21:1, where the pixels are black on
+    // white at 18.88:1 (twelve false failures on one retailer's home page,
+    // 2026-09-21). Where the box misses the text it still paints nothing
+    // there, so the rect is kept, and the walk turns the layer into a film
+    // only when it covers the sample point.
+    const mask = style.maskImage || style.webkitMaskImage;
+    if ((mask && mask !== 'none') || (style.clipPath && style.clipPath !== 'none')) {
+      const alphaBound = Math.min(1, opacityFactor * (style.backgroundImage !== 'none' ? 1 : color.a));
+      if (alphaBound > 0) layers.push({ rect, shaped: alphaBound });
+      continue;
+    }
     let layerColor = color;
     if (layerColor && opacityFactor < 1) layerColor = { ...layerColor, a: layerColor.a * opacityFactor };
     // Gradient and image paint rides along as CSS so callers can sample it,
@@ -829,6 +875,7 @@ export function pseudoBackdropForText(element) {
   let image = null;
   let settled = false; // an opaque colour or an image hit: deeper layers are covered
   let film = 0;
+  let shaped = false; // some of that film is a masked or clipped box over the text
   // Paint (an opaque background-color or a background-image) on an element
   // BETWEEN the text and a pseudo's host makes the pseudo's place in the
   // stack unprovable from here: CSS paint order can put an out-of-flow
@@ -859,6 +906,15 @@ export function pseudoBackdropForText(element) {
       if (settled) continue;
       const { rect, color, imageCss } = layer;
       if (point.x < rect.left || point.x > rect.right || point.y < rect.top || point.y > rect.bottom) continue;
+      // A masked or clipped box over the text: paint of unknown extent,
+      // bounded by its alpha like any other film. It is placed, so opaque
+      // paint nearer the text says nothing about it and `crossed` is not
+      // consulted.
+      if (layer.shaped) {
+        film = 1 - (1 - film) * (1 - layer.shaped);
+        shaped = true;
+        continue;
+      }
       // Gradient/image paint is bracketable by sampling, so hand it to the
       // caller rather than giving up on the whole element. The pseudo's box
       // and image geometry travel with it: covering the sample point is a
@@ -884,9 +940,10 @@ export function pseudoBackdropForText(element) {
         || (parseColor(style.backgroundColor)?.a ?? 0) >= 1) crossed = true;
     }
   }
-  if (image) return { image, ...(film > 0 && { film }), ...(beyondPaint && { beyondPaint }) };
-  if (acc) return { color: acc, ...(film > 0 && { film }), ...(beyondPaint && { beyondPaint }) };
-  return film > 0 ? { film } : null;
+  const filmed = film > 0 && { film, ...(shaped && { shaped }) };
+  if (image) return { image, ...filmed, ...(beyondPaint && { beyondPaint }) };
+  if (acc) return { color: acc, ...filmed, ...(beyondPaint && { beyondPaint }) };
+  return filmed || null;
 }
 
 /**
@@ -1221,7 +1278,7 @@ export function textShadowNegligible(cssText, fontSize) {
  * uncertain path keeps the FULL box, erring toward review, never past a
  * real overlap. Returns null when the clip leaves nothing paintable.
  */
-function paintableRect(element, rect) {
+export function paintableRect(element, rect) {
   let { left, top, right, bottom } = rect;
   let mode = getComputedStyle(element).position;
   for (let a = element.parentElement; a; a = a.parentElement) {
@@ -1270,6 +1327,163 @@ export function mediaRects(doc) {
   return mediaRectsCache;
 }
 
+/** Properties whose non-initial value makes a stacking context, and which
+ *  will-change makes one for by being named. */
+const CONTEXT_PROPERTIES = ['transform', 'translate', 'rotate', 'scale', 'filter', 'backdropFilter', 'perspective',
+  'clipPath', 'maskImage', 'webkitMaskImage', 'maskBorderSource', 'viewTransitionName'];
+const WILL_CHANGE_CONTEXTS = /(^|,\s*)(transform|translate|rotate|scale|opacity|filter|backdrop-filter|perspective|clip-path|mask|mask-image|mask-border|isolation|mix-blend-mode|z-index|contain|view-transition-name)\s*(,|$)/;
+
+/**
+ * Does this element create a stacking context? The list is CSS's own (CSS
+ * Positioned Layout 3, and the properties that say so in their own
+ * specifications): the root; fixed and sticky; a positioned element, or a
+ * flex or grid item, with a z-index; opacity under 1; a transform, filter,
+ * perspective, clip-path or mask; a blend mode or isolation; containment
+ * of layout or paint, a container, content-visibility; a view transition
+ * name; and will-change naming any of those. It is kept complete on
+ * purpose: missing one and inventing one both put an element in the wrong
+ * layer, so beneathOpaqueAncestor asks for a whole chain it can read.
+ */
+function createsStackingContext(element) {
+  let known = stackingContextCache.get(element);
+  if (known !== undefined) return known;
+  const parent = element.parentElement;
+  const style = getComputedStyle(element);
+  known = !parent
+    || style.position === 'fixed' || style.position === 'sticky'
+    || (style.zIndex !== 'auto' && (style.position !== 'static'
+      || /flex|grid/.test(getComputedStyle(parent).display)))
+    || parseFloat(style.opacity) < 1
+    || CONTEXT_PROPERTIES.some((name) => style[name] && style[name] !== 'none')
+    || (style.mixBlendMode && style.mixBlendMode !== 'normal')
+    || style.isolation === 'isolate'
+    || /layout|paint|strict|content/.test(style.contain ?? '')
+    || (style.containerType && style.containerType !== 'normal')
+    || (style.contentVisibility && style.contentVisibility !== 'visible')
+    || WILL_CHANGE_CONTEXTS.test(style.willChange ?? '');
+  stackingContextCache.set(element, known);
+  return known;
+}
+
+/** The top layer paints over every stacking context and is outside the
+ *  ordering read below. */
+function inTopLayer(element) {
+  for (const selector of [':modal', ':popover-open', ':fullscreen']) {
+    try { if (element.closest(selector)) return true; }
+    catch { /* a selector this browser does not know matches nothing */ }
+  }
+  return false;
+}
+
+/**
+ * Where an element paints within the stacking context `root`, as a rank to
+ * compare (CSS 2.1 Appendix E): child contexts with a negative z-index,
+ * then in-flow content, then positioned content and z-index 0 contexts in
+ * tree order, then positive z-index contexts. A context nested in another
+ * is carried by the outermost, which is the one `root` orders; with no
+ * context between, a positioned box is ordered by itself, so the nearest
+ * positioned ancestor speaks for its in-flow content. Null when the walk
+ * leaves the tree before reaching `root` (a shadow boundary).
+ */
+function paintRank(element, root) {
+  let context = null;
+  let positioned = null;
+  let node = element;
+  for (; node && node !== root; node = node.parentElement) {
+    if (createsStackingContext(node)) context = node;
+    else if (!positioned && getComputedStyle(node).position !== 'static') positioned = node;
+  }
+  if (node !== root) return null;
+  if (context) {
+    // z-index orders only a positioned box or a flex or grid item. A
+    // context made some other way (a transform, say) sits at zero.
+    const style = getComputedStyle(context);
+    const applies = style.zIndex !== 'auto' && (style.position !== 'static'
+      || /flex|grid/.test(getComputedStyle(context.parentElement ?? context).display));
+    const z = applies ? parseInt(style.zIndex, 10) || 0 : 0;
+    return { node: context, layer: z < 0 ? 0 : z > 0 ? 3 : 2, z };
+  }
+  return positioned ? { node: positioned, layer: 2, z: 0 } : { node: null, layer: 1, z: 0 };
+}
+
+/** Is the whole box inside the ancestor's border box, rounded corners
+ *  allowed for? Null radii that cannot be read are taken as not inside. */
+function insideRoundedBox(box, outer, style) {
+  if (box.left < outer.left || box.right > outer.right || box.top < outer.top || box.bottom > outer.bottom) return false;
+  const radius = (css, width) => {
+    const first = (css ?? '').split(' ')[0];
+    const value = parseFloat(first);
+    if (!Number.isFinite(value)) return null;
+    return first.endsWith('%') ? (value / 100) * width : value;
+  };
+  const corners = [
+    [style.borderTopLeftRadius, box.left - outer.left, box.top - outer.top],
+    [style.borderTopRightRadius, outer.right - box.right, box.top - outer.top],
+    [style.borderBottomLeftRadius, box.left - outer.left, outer.bottom - box.bottom],
+    [style.borderBottomRightRadius, outer.right - box.right, outer.bottom - box.bottom],
+  ];
+  for (const [css, dx, dy] of corners) {
+    const r = radius(css, outer.width);
+    if (r === null) return false;
+    // The box's corner lies in this corner's square and outside its arc.
+    if (dx < r && dy < r && (r - dx) ** 2 + (r - dy) ** 2 > r ** 2) return false;
+  }
+  return true;
+}
+
+/**
+ * Can this media not be the text's backdrop, because an opaque ancestor of
+ * the text provably paints over it? Hit-test-blind media (pointer-events:
+ * none) sharing the text's space is a hazard the browser cannot be asked
+ * about, and the rule abstains on it. But a solid card laid over a
+ * decorative graphic in a z-index -1 layer sent every line of the card to a
+ * person (a consultancy's landing page, fifteen reviews that all pass by
+ * eye, 2026-09-21). Two facts of CSS paint order settle it:
+ *   - an ancestor that creates a stacking context paints as one unit, its
+ *     background first and its descendants over it, so nothing from
+ *     outside can come between that background and the text;
+ *   - media outside that ancestor is then wholly over it or wholly under
+ *     it, and which is read from their ranks in the lowest stacking
+ *     context they share.
+ * Under it, and with the ancestor's background opaque, unclipped, at full
+ * opacity, unblended and covering the text's box, the media cannot show
+ * behind the text. Everything else (media inside the ancestor, an order
+ * that comes down to in-flow interleaving, the top layer, a shadow
+ * boundary, a radius that cannot be read) is left unproven, and the rule
+ * abstains as before.
+ */
+export function beneathOpaqueAncestor(element, media) {
+  if (inTopLayer(element) || inTopLayer(media)) return false;
+  const box = element.getBoundingClientRect();
+  for (let ancestor = element; ancestor; ancestor = ancestor.parentElement) {
+    if (ancestor.contains(media)) return false; // from here up the media is inside
+    if (!createsStackingContext(ancestor)) continue;
+    const style = getComputedStyle(ancestor);
+    const color = parseColor(style.backgroundColor);
+    if (!color || color.a < 1) continue;
+    if (cumulativeOpacity(ancestor) < 1) continue;
+    if (style.mixBlendMode !== 'normal') continue;
+    if ((style.clipPath && style.clipPath !== 'none')
+      || [style.maskImage, style.webkitMaskImage].some((mask) => mask && mask !== 'none')) continue;
+    if (!/^(border-box|padding-box)$/.test(style.backgroundClip)) continue;
+    if (!insideRoundedBox(box, ancestor.getBoundingClientRect(), style)) continue;
+    // The lowest stacking context holding both.
+    let shared = ancestor.parentElement;
+    while (shared && !(createsStackingContext(shared) && shared.contains(media))) shared = shared.parentElement;
+    if (!shared) return false;
+    const over = paintRank(ancestor, shared);
+    const under = paintRank(media, shared);
+    if (!over || !under || !over.node || over.node === under.node) return false;
+    if (under.layer !== over.layer) return under.layer < over.layer;
+    if (under.layer === 1) return false; // both in flow: interleaving, unproven
+    if (under.z !== over.z) return under.z < over.z;
+    // Same layer and z-index: tree order, earlier paints first.
+    return Boolean(under.node.compareDocumentPosition(over.node) & 4 /* FOLLOWING */)
+      && !under.node.contains(over.node);
+  }
+  return false;
+}
+
 /**
  * The nearest background-image being painted behind this element (walking
  * up until an opaque background colour would hide anything deeper).

package/engine/rules/wcag/1.4.3-color-contrast.js

@@ -6,7 +6,7 @@ import {
   opacityAnimating, restingOpacity, mediaRects, inZeroClipSubtree,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
-  showRatio, asRgb, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors, BOLD_WEIGHT, hasPaintEffects, isolatedBlendBackdrop } from '../../lib/contrast.js';
+  showRatio, asRgb, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors, BOLD_WEIGHT, hasPaintEffects, isolatedBlendBackdrop, labelReferrers, beneathOpaqueAncestor } from '../../lib/contrast.js';
 
 /** The first url() among a background-image list's layers, or null. */
 const firstLayerUrl = (css) => splitBackgroundLayers(css ?? '').map(backgroundLayerUrl).find(Boolean) ?? null;
@@ -74,6 +74,116 @@ function inactiveComponentText(element) {
   return Boolean(ariaDisabled && ariaDisabled.matches(ARIA_DISABLED_HOSTS));
 }
 
+/** A widget switched off: natively disabled, which :disabled sees through
+ *  an ancestor <fieldset disabled> where .disabled does not, or
+ *  aria-disabled="true" on a role that honours it. Groups are left out: a
+ *  disabled fieldset keeps its first legend active (above), and a caption
+ *  it takes through aria-labelledby is read the same way. */
+function inactiveWidget(widget) {
+  if (widget.matches('fieldset, optgroup, [role="group"], [role="toolbar"], [role="application"]')) return false;
+  if (widget.matches(':disabled')) return true;
+  const ariaDisabled = widget.closest('[aria-disabled="true"]');
+  return Boolean(ariaDisabled && ariaDisabled.matches(ARIA_DISABLED_HOSTS));
+}
+
+/** What a label does not hold: blocks of content, or controls of its own. */
+const MORE_THAN_A_LABEL = 'p, div, ul, ol, dl, table, section, article, aside, nav, header, footer, form, '
+  + 'h1, h2, h3, h4, h5, h6, a[href], button, input, select, textarea';
+
+/**
+ * Is this text the label of an inactive control? The browser greys
+ * <label>My name <input disabled></label> as one unit, and that unit is
+ * what the glossary calls a user interface component: "a part of the
+ * content that is perceived by users as a single control for a distinct
+ * function". So the label is "part of an inactive user interface
+ * component" with its control. ACT afw4f7 and 09o5cg say so in their
+ * applicability, which leaves out text whose ancestor "is used in the
+ * accessible name of an inheriting semantic widget that is disabled"
+ * (engine repository issue #5, reported with the fixtures by Jeff Witt).
+ *
+ * A label reaches its widget two ways: the <label> element's own
+ * association, and aria-labelledby on the widget. Both are held to the
+ * same two limits, because the exemption is for a label and nothing wider:
+ *   - every widget that takes its name from this element is inactive. A
+ *     caption shared by a disabled field and a live one still labels the
+ *     live one, and a heading that also names a region is still a heading.
+ *   - a referenced ancestor must be label-sized. aria-labelledby aimed at a
+ *     whole card does not make the card's paragraphs part of the control.
+ * Text inside the widget itself is inactiveComponentText's, above.
+ */
+function labelsInactiveComponent(element) {
+  const referrers = labelReferrers(element.getRootNode(), inactiveWidget);
+  const sharedWithLive = (node) => Boolean(node.id && referrers.get(node.id)?.other);
+  const label = element.closest('label');
+  if (label?.control && inactiveWidget(label.control) && !sharedWithLive(label)) return true;
+  if (!referrers.size) return false;
+  for (let node = element; node; node = node.parentElement) {
+    const count = node.id && referrers.get(node.id);
+    if (!count || !count.inactive || count.other) continue;
+    if (node === element || !node.querySelector(MORE_THAN_A_LABEL)) return true;
+  }
+  return false;
+}
+
+/** User-perceived characters, so a flag or a skin-toned emoji counts as
+ *  one. Falls back to code points where Intl.Segmenter is missing. */
+function graphemes(text) {
+  if (typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function') {
+    return [...new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text)].map((part) => part.segment);
+  }
+  return [...text];
+}
+
+/** A character the browser draws from a colour font: one whose default
+ *  presentation is emoji, or any emoji asked for in colour with U+FE0F.
+ *  A check mark or a telephone with no selector is drawn as text, in the
+ *  element's colour, and is judged as text. */
+const drawnInColour = (grapheme) => /\p{Emoji_Presentation}/u.test(grapheme)
+  || (grapheme.includes('️') && /\p{Emoji}/u.test(grapheme));
+
+/** The controls a lone glyph stands in as an icon for. */
+const ICON_HOSTS = 'button, a[href], summary, [role="button"], [role="link"], [role="tab"], [role="menuitem"]';
+
+/**
+ * Is this text a glyph and not words? WCAG defines text as characters
+ * "expressing something in human language", and its note on non-text
+ * content names emoticons. Three shapes are provable from the markup, and
+ * no others are taken: punctuation and symbols are part of written
+ * language (a price band in pound signs, the asterisk on a required field,
+ * the prompt in a code sample), so text without a letter in it is still
+ * judged as text.
+ *   - colour emoji only. Beyond the definition, the measurement is void:
+ *     a colour glyph paints its own colours and ignores `color`, so the
+ *     ratio describes paint that is not there.
+ *   - private-use characters only: an icon-font glyph. Unicode gives these
+ *     no meaning in any language.
+ *   - a single Latin letter or symbol that is all a control shows, where
+ *     the author named the control through aria-label or aria-labelledby
+ *     and the name does not contain the character. The X in <button
+ *     aria-label="Close">X</button> is a drawn cross, and the author's own
+ *     name for it is the evidence (ACT afw4f7 Passed Example 7). A letter
+ *     from another script is left alone: one CJK character is a word.
+ * Returns what the glyph is, and whether it is the whole face of a
+ * control, which decides what it owes under 1.4.11 (see the wrapper).
+ */
+function glyphNotWords(element, text, accessibleName) {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  const parts = graphemes(trimmed).filter((part) => /\S/.test(part));
+  if (parts.every(drawnInColour)) return { emoji: true, what: 'this text is emoji, which the browser draws in its own colours whatever the text colour is' };
+  const host = element.closest(ICON_HOSTS);
+  const faceOfControl = Boolean(host && host.textContent.trim() === trimmed);
+  if (/^[\p{Co}\s]+$/u.test(trimmed)) {
+    return { faceOfControl, what: 'this text is an icon-font glyph (a private-use character), not words' };
+  }
+  if (parts.length !== 1 || !faceOfControl) return null;
+  if (!/^(\p{Script=Latin}|[^\p{L}\p{N}])/u.test(trimmed)) return null;
+  if (!host.hasAttribute('aria-label') && !host.hasAttribute('aria-labelledby')) return null;
+  const name = accessibleName(host);
+  if (!name || name.toLowerCase().includes(trimmed.toLowerCase())) return null;
+  return { faceOfControl, what: `the single character "${trimmed}" stands in for an icon: the ${host.tagName.toLowerCase()} is named "${name}", which does not contain it` };
+}
+
 /** A control the keyboard cannot reach either: with pointer-events: none
  *  on top, nothing can operate it, which is what "inactive" means. Native
  *  controls are focusable unless told otherwise; a role-only widget is
@@ -516,8 +626,9 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
   async evaluate(element, { ownText }) {
     if (!ownText(element)) return { status: 'pass' }; // no text of its own to judge
 
-    // The criterion exempts "inactive user interface components".
-    if (inactiveComponentText(element)) return { status: 'pass' };
+    // The criterion exempts "inactive user interface components": the text
+    // inside one, and the label that is greyed out with it.
+    if (inactiveComponentText(element) || labelsInactiveComponent(element)) return { status: 'pass' };
 
     // A shadow HOST's own text renders through its shadow tree: when a
     // <slot> projects it, the text inherits styles from the slot's
@@ -974,7 +1085,9 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     }
     const filmIncomplete = {
       status: 'incomplete',
-      message: 'A pseudo-element with its own background paints in this element\'s chain, but its position can\'t be computed — so whether it sits behind this text is unknown. Check the contrast by eye.',
+      message: pseudoResolved?.shaped
+        ? 'A pseudo-element with its own background covers this text, but a mask or clip-path cuts it down to a shape, so how much of it paints over or behind the text can\'t be computed. Check the contrast by eye.'
+        : 'A pseudo-element with its own background paints in this element\'s chain, but its position can\'t be computed — so whether it sits behind this text is unknown. Check the contrast by eye.',
     };
     // Sampled pixels, veils and text-shadow halos can't be film-bracketed
     // (the film may sit between the sample and the glyphs): those verdicts
@@ -1144,10 +1257,13 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
       const box = element.getBoundingClientRect();
       const near = (r) => Math.min(box.right, r.right) - Math.max(box.left, r.left) >= 3
         && Math.min(box.bottom, r.bottom) - Math.max(box.top, r.top) >= 3;
+      // Asked last, and only of media that would otherwise send this text
+      // to a person: can paint order prove an opaque ancestor lies over it?
       const overMedia = mediaRects(doc).some(({ element: media, rect: mediaRect, hitTestBlind }) =>
         (!blindOnly || hitTestBlind) && near(mediaRect)
         && !media.contains(element) && !element.contains(media)
-        && textIntersects(element, mediaRect));
+        && textIntersects(element, mediaRect)
+        && !beneathOpaqueAncestor(element, media));
       if (overMedia) {
         return {
           status: 'incomplete',
@@ -1388,7 +1504,30 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
   const judge = rule.evaluate.bind(rule);
   rule.evaluate = async (element, helpers) => {
     const verdict = await judge(element, helpers);
-    if (verdict.status === 'fail' && element.closest('[aria-hidden="true"]')) {
+    if (verdict.status !== 'fail') return verdict;
+    // A miss on a glyph that is not words: see glyphNotWords. Every fail
+    // path passes through here, so this is said once. A glyph still owes
+    // 3:1 under 1.4.11 when it is needed to identify a control, so one that
+    // is the whole face of a control and measures under 3:1 fails whichever
+    // criterion it is read under, and keeps its failure. Anything else is a
+    // question of which criterion applies, and goes to a person. Emoji
+    // always does, its ratio being a number for paint that is not there.
+    const glyph = glyphNotWords(element, helpers.ownText(element), helpers.accessibleName);
+    if (glyph) {
+      const ratio = verdict.data?.ratio;
+      if (!glyph.emoji && glyph.faceOfControl && ratio < 3) {
+        verdict.message += ' Read as an icon and not as text, it still falls short: 1.4.11 asks 3:1 of what identifies a control.';
+      }
+      else {
+        return {
+          status: 'incomplete',
+          message: glyph.emoji
+            ? `The text colour misses the contrast minimum, but ${glyph.what}, so that ratio does not describe what is seen. If the emoji carries meaning, judge it by eye against 1.4.11 non-text contrast (3:1).`
+            : `Contrast is ${ratio ? `${ratio}:1, below the ${verdict.data.required}:1 minimum for text` : 'below the minimum for text'}, but ${glyph.what}. 1.4.3 covers text in a human language; a glyph that works as a graphic is judged under 1.4.11 non-text contrast (3:1) where it is needed to understand the content. Decide by eye which this is.`,
+        };
+      }
+    }
+    if (element.closest('[aria-hidden="true"]')) {
       verdict.message += ' aria-hidden hides this from screen readers, not from sighted users; contrast is judged for the people who see it.';
     }
     return verdict;

package/engine/rules/wcag/3.1.2-valid-lang-parts.js

@@ -2,8 +2,135 @@
 // Same shape as 3.1.1-html-lang.js, and must stay in step with it: subtags
 // may be a single character, because BCP 47 extension and private-use
 // singletons ("-u-", "-t-", "-x-") are exactly one.
+import { paintableRect } from '../../lib/contrast.js';
+
 const LANG_PATTERN = /^([a-zA-Z]{2,3}(-[a-zA-Z0-9]{1,8})*|[xXiI](-[a-zA-Z0-9]{1,8})+)$/;
 
+/** Attributes whose value is spoken and never shown. */
+const SPOKEN_ATTRIBUTES = ['aria-label', 'aria-description', 'aria-placeholder', 'aria-valuetext', 'aria-roledescription'];
+
+/** Attributes whose value is shown, and spoken too. */
+const SHOWN_ATTRIBUTES = ['title', 'placeholder'];
+
+/** Input types whose value attribute is words the page wrote. Submit and
+ *  reset are here without one too: the browser writes their label. */
+const WORDED_INPUT_TYPES = new Set(['', 'text', 'search', 'email', 'url', 'tel', 'button', 'submit', 'reset']);
+
+const spoken = (node, name) => Boolean(node.getAttribute(name)?.trim());
+
+/**
+ * Does this element carry words of its own, outside its text nodes? The
+ * accessible name and description count as much as visible text: a
+ * placeholder or a title is a phrase, and it is spoken in whatever
+ * language the nearest lang says. Inside aria-hidden content (`unspoken`)
+ * nothing is spoken, so only the words that are shown count there: an alt
+ * or an aria-label under aria-hidden reaches no one.
+ */
+function ownWords(node, unspoken) {
+  if (!unspoken) {
+    if (SPOKEN_ATTRIBUTES.some((name) => spoken(node, name))) return true;
+    if (node.matches('img, area, input[type="image"]') && spoken(node, 'alt')) return true;
+    if (node.matches('optgroup, track') && spoken(node, 'label')) return true;
+  }
+  if (SHOWN_ATTRIBUTES.some((name) => spoken(node, name))) return true;
+  if (node.tagName === 'OPTION' && spoken(node, 'label')) return true;
+  if (node.tagName === 'INPUT') {
+    const type = (node.getAttribute('type') ?? '').trim().toLowerCase();
+    if (type === 'submit' || type === 'reset') return true;
+    if (WORDED_INPUT_TYPES.has(type) && spoken(node, 'value')) return true;
+  }
+  // A nested document with no lang of its own takes this one, and what it
+  // holds cannot always be read from here, so it counts as words.
+  if (node.matches('iframe, frame, object, embed')) return true;
+  for (const pseudo of ['::before', '::after']) {
+    const content = getComputedStyle(node, pseudo).content;
+    if (/"[^"]*\S[^"]*"/.test(content)) return true;
+  }
+  return false;
+}
+
+/**
+ * Can this box be seen? Asked only inside aria-hidden content, where being
+ * seen is the one way left for words to reach anyone: a carousel slide that
+ * is aria-hidden and clipped out of its strip is neither spoken nor seen,
+ * and the tag on it misleads no one. Outside aria-hidden the question is
+ * never put, since off-screen text is still spoken. The clip walk keeps the
+ * whole box wherever it is unsure, so a doubtful case counts as seen and
+ * keeps its failure; so does everything where there is no layout to ask
+ * (the editor's static lane), which the root's empty box gives away.
+ */
+function seen(box, element) {
+  const view = element.ownerDocument.defaultView;
+  if (!element.ownerDocument.documentElement.getBoundingClientRect().width) return true;
+  if (!box.width || !box.height) return false;
+  if (box.right + view.scrollX <= 0 || box.bottom + view.scrollY <= 0) return false;
+  return Boolean(paintableRect(element, box));
+}
+
+/**
+ * Does any text take its language from this element? 3.1.2 asks that "the
+ * human language of each passage or phrase in the content can be
+ * programmatically determined", so a lang value can only fail it through a
+ * passage it governs. A lang governs its subtree down to the next element
+ * with a non-empty lang of its own. When every word beneath an invalid tag
+ * is re-tagged (<article lang="invalid"><div lang="en">...</div></article>),
+ * or there are no words at all (an empty element, a decorative image, text
+ * that is display:none), each passage on the page still has a language and
+ * the criterion is met. ACT de46e4 draws the same line in its
+ * applicability: "some text inheriting its programmatic language from the
+ * element which is neither empty nor only whitespace" (issue #6 on the
+ * engine repository, reported with the fixtures by Jeff Witt).
+ *
+ * Words are rendered text nodes and everything ownWords() counts. The walk
+ * is over the flat tree: shadow content in place of a host's light
+ * children, assigned nodes in place of a slot. display:none ends a branch.
+ * visibility:hidden silences that level only, since a descendant can turn
+ * itself back on. aria-hidden text still counts where it is seen, and
+ * off-screen text where it is spoken; text that is both aria-hidden and out
+ * of sight reaches no one and does not. Anything the walk cannot rule on counts as
+ * words, so a doubtful case keeps its failure.
+ */
+function governsText(element) {
+  // The rule is handed every [lang] element, rendered or not, so nothing
+  // beneath an ancestor that is display:none counts: the walk below only
+  // looks down.
+  for (let node = element.parentElement ?? element.getRootNode()?.host; node; node = node.parentElement ?? node.getRootNode()?.host) {
+    if (getComputedStyle(node).display === 'none') return false;
+  }
+  const stack = [[element, Boolean(element.closest('[aria-hidden="true"]'))]];
+  while (stack.length) {
+    const [node, above] = stack.pop();
+    const unspoken = above || node.getAttribute('aria-hidden') === 'true';
+    if (node !== element && spoken(node, 'lang')) continue;
+    if (node.matches('script, style, noscript, template')) continue;
+    const style = getComputedStyle(node);
+    if (style.display === 'none') continue;
+    const shown = style.visibility !== 'hidden' && style.visibility !== 'collapse';
+    if (shown && ownWords(node, unspoken) && (!unspoken || seen(node.getBoundingClientRect(), node))) return true;
+    let children = node.childNodes;
+    if (node.tagName === 'SLOT') {
+      const assigned = node.assignedNodes?.() ?? [];
+      if (assigned.length) children = assigned;
+    }
+    else if (node.shadowRoot) children = node.shadowRoot.childNodes;
+    for (const child of children) {
+      if (child.nodeType === 3 /* TEXT_NODE */) {
+        if (!shown || !/\S/.test(child.textContent)) continue;
+        if (!unspoken) return true;
+        // A range's box is the text's own, where the parent's may be a
+        // block far wider than its words. Where ranges have no geometry
+        // (the static lane) the parent's box is asked, and says "seen".
+        const range = node.ownerDocument.createRange();
+        range.selectNodeContents(child);
+        const box = typeof range.getBoundingClientRect === 'function' ? range.getBoundingClientRect() : node.getBoundingClientRect();
+        if (seen(box, node)) return true;
+      }
+      else if (child.nodeType === 1 /* ELEMENT_NODE */) stack.push([child, unspoken]);
+    }
+  }
+  return false;
+}
+
 export default {
   id: 'valid-lang-parts',
   name: 'Part language tags',
@@ -12,12 +139,28 @@ export default {
   help: 'lang attributes on page parts must be valid',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html',
   selector: '[lang]:not(html)',
+  // Not the default filter, which drops an element that is aria-hidden or
+  // has no box of its own. Neither settles whether words inherit the tag:
+  // aria-hidden text is still seen, and the language of seen text is used
+  // by more than screen readers (hyphenation, font choice, translation,
+  // spelling); visibility:hidden on the element leaves a descendant free to
+  // show itself. governsText rules on all of it (ACT de46e4 Failed
+  // Example 4 generalised to the element itself).
+  visibleOnly: false,
   evaluate(element) {
     const lang = element.getAttribute('lang').trim();
     if (lang === '' || LANG_PATTERN.test(lang)) return { status: 'pass' }; // empty resets to page language
+    // An invalid tag no passage inherits leaves every passage with a
+    // language. Asked after the syntax test, so only invalid tags pay for
+    // the walk.
+    if (!governsText(element)) return { status: 'pass' };
+    // Where no screen reader will read it, say who else the tag is for.
+    const unspoken = element.closest('[aria-hidden="true"]');
     return {
       status: 'fail',
-      message: `lang="${lang}" is not a valid language tag, so screen readers may switch to the wrong pronunciation.`,
+      message: unspoken
+        ? `lang="${lang}" is not a valid language tag. aria-hidden keeps this text from screen readers, but it is still seen, and browsers and translation tools use the tag to hyphenate, pick fonts and translate it.`
+        : `lang="${lang}" is not a valid language tag, so screen readers may switch to the wrong pronunciation.`,
       fix: 'Use a BCP 47 tag such as lang="fr" or lang="de-AT".',
     };
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pour-engine",
-  "version": "1.43.0",
+  "version": "1.44.1",
   "description": "Accessibility (WCAG 2.2) audit engine written from the W3C specifications — runs entirely in the browser, no dependencies.",
   "type": "module",
   "main": "engine/index.js",