pour-engine 1.1.9 → 1.3.1

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -5,6 +5,8 @@ Generated by `node scripts/wcag-coverage.js` — do not edit by hand.
 All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 "Partially automated" means our rules catch common failures but cannot prove conformance;
 "Manual review" criteria need a human (most of the spec — true for every automated tool).
+No criterion is listed as fully "Automated": every one of them ends in a question about
+meaning that only a person can settle, even where a rule decides most real pages.
 
 ## Perceivable
 
@@ -58,7 +60,7 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 | 2.3.2 | [Three Flashes](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes.html) | AAA | Manual review | — |
 | 2.3.3 | [Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) | AAA | Manual review | — |
 | 2.4.1 | [Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html) | A | Partially automated | bypass-blocks |
-| 2.4.2 | [Page Titled](https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html) | A | Automated | document-title |
+| 2.4.2 | [Page Titled](https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html) | A | Partially automated | document-title |
 | 2.4.3 | [Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) | A | Manual review | — |
 | 2.4.4 | [Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) | A | Partially automated | area-alt, link-name |
 | 2.4.5 | [Multiple Ways](https://www.w3.org/WAI/WCAG22/Understanding/multiple-ways.html) | AA | Manual review | — |
@@ -83,7 +85,7 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 
 | SC | Name | Level | Coverage | Rules |
 |---|---|---|---|---|
-| 3.1.1 | [Language of Page](https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html) | A | Automated | html-lang |
+| 3.1.1 | [Language of Page](https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html) | A | Partially automated | html-lang |
 | 3.1.2 | [Language of Parts](https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html) | AA | Partially automated | valid-lang-parts |
 | 3.1.3 | [Unusual Words](https://www.w3.org/WAI/WCAG22/Understanding/unusual-words.html) | AAA | Manual review | — |
 | 3.1.4 | [Abbreviations](https://www.w3.org/WAI/WCAG22/Understanding/abbreviations.html) | AAA | Manual review | — |
@@ -112,4 +114,4 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 | 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-valid-refs, button-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
-**Totals:** 2 automated · 27 partially automated · 57 manual — with 72 rules.
+**Totals:** 29 partially automated · 57 manual — with 72 rules.

package/engine/README.md

@@ -108,7 +108,7 @@ Nothing in the spec is silently skipped — that claim is the product.
 
 ## Honest current state
 
-61 rules, hardened on real sites and the `testbeds/` pages. Known gaps:
+72 rules, hardened on real sites and the `testbeds/` pages. Known gaps:
 shadow DOM and iframe traversal, the full accname spec (ours is a close
 approximation), and the language subtag registry (BCP 47 shape check only).
 Grow it rule by rule; the test beds' `expect:` annotations are the

package/engine/lib/contrast.js

@@ -140,7 +140,7 @@ export function backgroundColorSource(element) {
   for (let node = element; node && node.nodeType === 1;
     node = node.parentElement ?? node.getRootNode()?.host) {
     const style = getComputedStyle(node);
-    if (style.backgroundImage !== 'none') return null;
+    if (style.backgroundImage !== 'none' && !paintsNothing(style.backgroundImage)) return null;
     const color = parseColor(style.backgroundColor);
     if (!color || color.a === 0) continue; // transparent: keep walking, as the resolver does
     return color.a >= 1 ? style.backgroundColor : null; // translucent: composited, no single source
@@ -148,6 +148,24 @@ export function backgroundColorSource(element) {
   return null;
 }
 
+/**
+ * Absolute URLs of images that sampling found to have no opaque pixels.
+ * Populated by imageLuminanceRange (async) and read by the background walk
+ * (sync): by the time a rule falls back to the walk, the image over that
+ * text has already been sampled, so the fact is in hand. Lives as long as
+ * the sample cache does — it describes the image, not the page.
+ */
+const transparentImages = new Set();
+
+/** True when every layer of this computed background-image is a url() known
+ *  to paint nothing — so the layer cannot change what is behind it. Any
+ *  gradient, or any unsampled image, makes that unknowable. */
+function paintsNothing(backgroundImage) {
+  if (backgroundImage.includes('gradient(')) return false;
+  const urls = [...backgroundImage.matchAll(/url\(["']?(.*?)["']?\)/g)].map((m) => m[1]);
+  return urls.length > 0 && urls.every((url) => transparentImages.has(url));
+}
+
 function canvasColor(doc) {
   // Pages using color-scheme: dark get a dark canvas from the browser even
   // with no author background — assuming white there inverts every result.
@@ -169,7 +187,7 @@ function resolveBackground(element, doc) {
   }
   let result;
   const style = getComputedStyle(element);
-  if (style.backgroundImage !== 'none') {
+  if (style.backgroundImage !== 'none' && !paintsNothing(style.backgroundImage)) {
     result = null;
   } else {
     const color = parseColor(style.backgroundColor);
@@ -762,23 +780,45 @@ export function mediaRects(doc) {
  * Returns { css, element } or null.
  */
 export function backgroundImageSource(element) {
+  // Translucent background colours passed on the way up are painted BETWEEN
+  // the image and the text: the scrim over a hero photo is the everyday case.
+  // They are collected nearest-text first, so folding them back over a sampled
+  // image pixel means walking this list in reverse (see applyOverlays).
+  const overlays = [];
   for (let current = element; current; current = current.parentElement) {
     const style = getComputedStyle(current);
-    if (style.backgroundImage !== 'none') return { css: style.backgroundImage, element: current };
+    // An element's own background-image paints ABOVE its own background
+    // colour, so the element carrying the image contributes no overlay.
+    if (style.backgroundImage !== 'none') return { css: style.backgroundImage, element: current, overlays };
     const color = parseColor(style.backgroundColor);
     if (color && color.a >= 1) return null;
+    if (color && color.a > 0) overlays.push(color);
   }
   return null;
 }
 
+/** Paint `overlays` (nearest-text first) back over a base colour. */
+export function applyOverlays(base, overlays) {
+  let result = base;
+  for (let i = overlays.length - 1; i >= 0; i--) result = composite(overlays[i], result);
+  return result;
+}
+
+const overlayKey = (overlays) =>
+  overlays.map((c) => `${c.r},${c.g},${c.b},${c.a}`).join(';');
+
 /**
  * Luminance range (min/max) of an image's pixels, downscaled for speed.
  * null when the image can't be read: cross-origin without CORS headers
- * (canvas tainting), load failure, or timeout. Cached per URL.
+ * (canvas tainting), load failure, or timeout. `{ transparent: true }` when
+ * the image reads fine but has no opaque pixels at all — it paints nothing,
+ * which is a very different fact from "unknown" and must not be reported as
+ * one. Cached per URL.
  */
 const imageRangeCache = new Map();
-export function imageLuminanceRange(url) {
-  if (imageRangeCache.has(url)) return imageRangeCache.get(url);
+export function imageLuminanceRange(url, overlays = []) {
+  const cacheKey = overlays.length ? `${url}|${overlayKey(overlays)}` : url;
+  if (imageRangeCache.has(cacheKey)) return imageRangeCache.get(cacheKey);
   const promise = new Promise((resolve) => {
     const img = new Image();
     img.crossOrigin = 'anonymous';
@@ -795,12 +835,33 @@ export function imageLuminanceRange(url) {
         const data = ctx.getImageData(0, 0, size, size).data;
         let min = 1;
         let max = 0;
+        let opaquePixels = 0;
         for (let i = 0; i < data.length; i += 4) {
           if (data[i + 3] < 128) continue; // mostly-transparent pixels reveal what's beneath — unknowable
-          const l = luminance({ r: data[i], g: data[i + 1], b: data[i + 2] });
+          opaquePixels += 1;
+          // Composite each pixel through anything painted between the image
+          // and the text before measuring: a photo under a 75% black scrim is
+          // seen as the blend, never as the photo.
+          const pixel = { r: data[i], g: data[i + 1], b: data[i + 2], a: 1 };
+          const l = luminance(overlays.length ? applyOverlays(pixel, overlays) : pixel);
           if (l < min) min = l;
           if (l > max) max = l;
         }
+        // Not one opaque pixel: a spacer, a cleared sprite, or a decorative
+        // layer left in place with nothing in it. It covers the background
+        // without changing a single one of its pixels.
+        if (!opaquePixels) {
+          transparentImages.add(url);
+          // Any background the walk already gave up on ("there's an image in
+          // the chain") may have been given up on because of THIS image.
+          // Those answers are now wrong, and which ones is not worth
+          // tracking: a page has a handful of transparent images at most, so
+          // the walk simply re-runs. Without this the verdict would depend
+          // on which rule happened to reach the element first.
+          backgroundCache = new WeakMap();
+          resolve({ transparent: true, width: img.naturalWidth, height: img.naturalHeight });
+          return;
+        }
         resolve(min <= max ? { min, max, width: img.naturalWidth, height: img.naturalHeight } : null);
       } catch {
         resolve(null); // tainted canvas: cross-origin image without CORS headers
@@ -809,7 +870,7 @@ export function imageLuminanceRange(url) {
     img.onerror = () => { clearTimeout(timer); resolve(null); };
     img.src = url;
   });
-  imageRangeCache.set(url, promise);
+  imageRangeCache.set(cacheKey, promise);
   return promise;
 }
 
@@ -857,10 +918,10 @@ export function backgroundImagePaintRect(element, intrinsic) {
  * Luminance range of a CSS gradient, from its colour stops. Interpolated
  * colours stay close enough to their stops' luminances to bracket.
  */
-export function gradientLuminanceRange(backgroundImageCss) {
+export function gradientLuminanceRange(backgroundImageCss, overlays = []) {
   const stops = (backgroundImageCss.match(/rgba?\([^)]+\)/g) ?? []).map(parseColor).filter(Boolean);
   if (!stops.length || stops.some((c) => c.a < 1)) return null; // translucent stops reveal what's beneath
-  const lums = stops.map(luminance);
+  const lums = stops.map((stop) => luminance(overlays.length ? applyOverlays(stop, overlays) : stop));
   return { min: Math.min(...lums), max: Math.max(...lums) };
 }
 

package/engine/rules/wcag/1.2.2-media-captions.js

@@ -8,7 +8,14 @@ export default {
   selector: 'video',
   visibleOnly: false,
   evaluate(element) {
-    if (element.querySelector('track[kind="captions"], track[kind="subtitles"]')) return { status: 'pass' };
+    // `kind` is an enumerated attribute: its values are ASCII
+    // case-insensitive, and the MISSING value default is the subtitles
+    // state — so a bare <track> is a subtitle track and counts. (An invalid
+    // value defaults to metadata, which does not, so `kind=""` and
+    // `kind="banana"` are deliberately left out.)
+    if (element.querySelector('track[kind="captions" i], track[kind="subtitles" i], track:not([kind])')) {
+      return { status: 'pass' };
+    }
     // Captions may be burned in or provided by the player — a human must check.
     return {
       status: 'incomplete',

package/engine/rules/wcag/1.3.1-form-label.js

@@ -40,10 +40,12 @@ export default {
 
     const id = element.id ? ` (it already has id="${element.id}")` : ' (give it an id first)';
 
-    // A title-only name is published sufficient technique H65 — conformant,
-    // but invisible until hover and ignored by some tools, so it's flagged
-    // for eyes rather than failed.
-    if (element.getAttribute('title') && !element.getAttribute('placeholder')) {
+    // A title name is published sufficient technique H65 — conformant, but
+    // invisible until hover and ignored by some tools, so it's flagged for
+    // eyes rather than failed. A placeholder alongside it is an example
+    // value, not a competing label: the title still names the field, so this
+    // check comes first and does not care whether one is present.
+    if (element.getAttribute('title')?.trim()) {
       return {
         status: 'incomplete',
         message: 'This field is named only by its title attribute (technique H65) — conformant, but the label is invisible until hover and some tools skip it. Check a visible label isn’t needed here.',

package/engine/rules/wcag/1.3.4-orientation.js

@@ -51,6 +51,10 @@ export default {
   help: 'Content must work in both portrait and landscape',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/orientation.html',
   selector: 'html',
+  // The evidence is in the stylesheet, not in the root's own rendering — and
+  // the lock hides the root exactly when it is in force, so a visibility
+  // filter here would silence the rule in the only state that matters.
+  visibleOnly: false,
   evaluate(element) {
     const findings = [];
     for (const sheet of element.ownerDocument.styleSheets) {

package/engine/rules/wcag/1.4.1-link-in-text-block.js

@@ -7,12 +7,18 @@ export default {
   tags: ['wcag2a', 'wcag141'],
   help: 'Links inside text must be distinguishable by more than colour',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html',
-  // Only running prose counts as a "text block" — lists of links (navs,
-  // blogrolls) are identified by their structure, not by colour.
-  selector: 'p a[href], dd a[href], blockquote a[href], td a[href]',
+  // Only running prose counts as a "text block". <li> is included because
+  // footers and credits routinely write sentences as list items ("built by
+  // the <a>team</a> with help from <a>contributors</a>"), and those links are
+  // embedded in prose exactly as 1.4.1 means it. Pure link lists (navs,
+  // blogrolls) are still excluded, but by the ownText guard below rather than
+  // by tag: in <li><a>Home</a></li> the item has no text of its own.
+  // <div> was measured too and added nothing on any test site, so it stays
+  // out rather than widening the blast radius for no gain.
+  selector: 'p a[href], dd a[href], blockquote a[href], td a[href], li a[href]',
   visibility: 'visual', // colour distinction is a purely visual concern
   evaluate(element, { ownText }) {
-    const parent = element.closest('p, dd, blockquote, td');
+    const parent = element.closest('p, dd, blockquote, td, li');
     if (!element.textContent.trim() || !parent) return { status: 'pass' };
     // Needs real surrounding text to blend into (1.4.1 is about links
     // embedded in prose, not a link that IS the content).
@@ -48,9 +54,17 @@ export default {
     // its own line (<br>-separated address blocks, one-link-per-line
     // footers) has no surrounding words to blend into — nothing is
     // conveyed by colour.
-    const rect = element.getBoundingClientRect();
-    if (rect.height) {
-      const mid = rect.top + rect.height / 2;
+    //
+    // Measured per LINE FRAGMENT, never on the bounding box. A link that
+    // wraps has one fragment per line, and the middle of the box that
+    // encloses them falls in the leading BETWEEN the lines, where no text
+    // can ever be — so a box-midpoint test exempts every wrapped link in
+    // prose, which is the opposite of what the check is for. F73 scopes
+    // this criterion by whether a link sits within text, and says nothing
+    // about lines: one fragment sharing its line with words is enough.
+    const fragments = [...element.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+    if (fragments.length) {
+      const mids = fragments.map((r) => r.top + r.height / 2);
       const walker = element.ownerDocument.createTreeWalker(parent, NodeFilter.SHOW_TEXT);
       const range = element.ownerDocument.createRange();
       let sharesLine = false;
@@ -58,7 +72,7 @@ export default {
         if (!node.textContent.trim() || element.contains(node)) continue;
         range.selectNodeContents(node);
         for (const r of range.getClientRects()) {
-          if (r.top <= mid && r.bottom >= mid && r.width > 0) { sharesLine = true; break; }
+          if (r.width > 0 && mids.some((mid) => r.top <= mid && r.bottom >= mid)) { sharesLine = true; break; }
         }
       }
       if (!sharesLine) return { status: 'pass' };

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

@@ -125,10 +125,68 @@ function verdictFromRange(range, foreground, required, what) {
   };
 }
 
+/**
+ * Is there translucent paint over the background image that the ancestor walk
+ * could NOT have collected? Two shapes dominate real hero banners: a
+ * ::before/::after scrim, and an absolutely-positioned sibling laid over the
+ * photo. Neither is on the text's ancestor chain, so backgroundImageSource
+ * never sees them, and judging the raw image pixels would describe a page the
+ * user is not looking at. Ancestor scrims are excluded here because they are
+ * already composited into the sampled pixels.
+ */
+function unaccountedScrim(element, imageCarrier) {
+  const pseudo = pseudoBackdropForText(element);
+  if (pseudo && pseudo !== 'unresolved' && pseudo.color?.a > 0) return true;
+  const doc = element.ownerDocument;
+  if (typeof doc.elementsFromPoint !== 'function') return false;
+  const rect = element.getBoundingClientRect();
+  const win = doc.defaultView;
+  const x = rect.left + rect.width / 2;
+  const y = rect.top + rect.height / 2;
+  if (x < 0 || y < 0 || x >= win.innerWidth || y >= win.innerHeight) return false;
+  const stack = doc.elementsFromPoint(x, y);
+  const start = stack.indexOf(element);
+  if (start === -1) return false;
+  return stack.slice(start + 1).some((layer) => {
+    if (layer.contains(element) || layer === imageCarrier) return false; // ancestor chain: already composited
+    const color = parseColor(getComputedStyle(layer).backgroundColor);
+    return color && color.a > 0;
+  });
+}
+
+/** An image layer with no opaque pixels: it covers the background without
+ *  changing it, so the callers step over it rather than reporting on it. */
+const PAINTS_NOTHING = Symbol('fully transparent image layer');
+
 // Bracket the verdict by sampling what's actually painted: image pixels
-// (same-origin/CORS only) or gradient colour stops.
-async function sampledVerdict(source, foreground, required, doc) {
+// (same-origin/CORS only) or gradient colour stops. Returns an outcome,
+// PAINTS_NOTHING, or null when nothing here can be sampled at all (stacked
+// layers, translucent gradient stops) and the caller must say so itself.
+async function sampledVerdict(source, foreground, required, doc, overlays = []) {
   if (!source) return null;
+  let range = null;
+  let what = 'image';
+  if (source.tagName === 'IMG') {
+    range = await imageLuminanceRange(source.currentSrc || source.src, overlays);
+  } else {
+    const css = source.css ?? getComputedStyle(source).backgroundImage;
+    if (!css || css === 'none') return null;
+    if ((css.match(/url\(/g) ?? []).length + (css.match(/gradient\(/g) ?? []).length > 1) return null; // stacked layers: too complex
+    const url = css.match(/url\(["']?(.*?)["']?\)/)?.[1];
+    if (url) {
+      let absolute;
+      try { absolute = new URL(url, doc.baseURI).href; } catch { return null; }
+      range = await imageLuminanceRange(absolute, overlays);
+    } else if (css.includes('gradient(')) {
+      range = gradientLuminanceRange(css, overlays);
+      what = 'gradient';
+    } else {
+      return null;
+    }
+  }
+  // Checked before the text's own alpha: there is no blend to reason about
+  // when the layer paints nothing.
+  if (range?.transparent) return PAINTS_NOTHING;
   // Translucent text takes its presented colour from the very pixels
   // beneath it — a luminance range of the backdrop cannot bracket the
   // blend (dimmed white over a dark photo reads mid-grey, not white).
@@ -139,22 +197,15 @@ async function sampledVerdict(source, foreground, required, doc) {
       message: 'This text is translucent over an image or gradient, so its presented colour depends on the pixels beneath — contrast must be checked by eye.',
     };
   }
-  if (source.tagName === 'IMG') {
-    return verdictFromRange(await imageLuminanceRange(source.currentSrc || source.src), foreground, required, 'image');
-  }
-  const css = source.css ?? getComputedStyle(source).backgroundImage;
-  if (!css || css === 'none') return null;
-  if ((css.match(/url\(/g) ?? []).length + (css.match(/gradient\(/g) ?? []).length > 1) return null; // stacked layers: too complex
-  const url = css.match(/url\(["']?(.*?)["']?\)/)?.[1];
-  if (url) {
-    let absolute;
-    try { absolute = new URL(url, doc.baseURI).href; } catch { return null; }
-    return verdictFromRange(await imageLuminanceRange(absolute), foreground, required, 'image');
-  }
-  if (css.includes('gradient(')) {
-    return verdictFromRange(gradientLuminanceRange(css), foreground, required, 'gradient');
+  // An image we tried to read and couldn't: that is a specific, reportable
+  // fact, and the only one of these paths where cross-origin is the cause.
+  if (!range && what === 'image') {
+    return {
+      status: 'incomplete',
+      message: 'The image painted behind this text can’t be read: it is cross-origin, or it failed to load, so a script can’t sample its colours. Check the contrast by eye.',
+    };
   }
-  return null;
+  return verdictFromRange(range, foreground, required, what);
 }
 
 /**
@@ -248,27 +299,44 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     if (imageSource) {
       const { relation, intrinsic, dimensionless } = await imageVsText(imageSource, element, doc);
       if (relation !== 'clear') {
-        const sampled = await sampledVerdict(imageSource, foreground, required, doc);
-        // Icon-scale images: bullets, arrows, and decorations painted
-        // beside or beneath a corner of the text — their pixels may flag
-        // for eyes, never assert a failure. Icon-scale means: no reliable
-        // intrinsic size, an intrinsically tiny image, OR a background
-        // carrier whose own box is line-height-sized (contain/cover paint
-        // can never exceed the carrier — a 512px nominal SVG painted on an
-        // inline link is still an icon). Only backdrop-scale images earn a
-        // definite fail from sampling.
-        const carrierBox = imageSource.element.getBoundingClientRect();
-        if (sampled?.status === 'fail'
-          && (dimensionless || (intrinsic.width <= 32 && intrinsic.height <= 32) || carrierBox.height <= 40)) {
-          return {
+        // imageSource.overlays are the translucent layers painted between the
+        // image and this text (hero scrims, tint panels). Judging the raw
+        // image pixels would describe a page the user never sees.
+        let sampled = await sampledVerdict(imageSource, foreground, required, doc, imageSource.overlays);
+        // A layer with no opaque pixels changes nothing about what is behind
+        // the glyphs, so it must not block the verdict: fall through and
+        // judge the background that actually paints.
+        if (sampled !== PAINTS_NOTHING) {
+          // Scrims the ancestor walk cannot reach (pseudo-elements, positioned
+          // siblings) leave the sampled range describing the wrong pixels, so
+          // neither verdict is safe to assert from it.
+          if (sampled && unaccountedScrim(element, imageSource.element)) {
+            sampled = {
+              status: 'incomplete',
+              message: 'This text sits over a background image with a translucent overlay painted on top of it (a pseudo-element or positioned scrim), so the colour behind the glyphs is the blend of the two — check the contrast by eye.',
+            };
+          }
+          // Icon-scale images: bullets, arrows, and decorations painted
+          // beside or beneath a corner of the text — their pixels may flag
+          // for eyes, never assert a failure. Icon-scale means: no reliable
+          // intrinsic size, an intrinsically tiny image, OR a background
+          // carrier whose own box is line-height-sized (contain/cover paint
+          // can never exceed the carrier — a 512px nominal SVG painted on an
+          // inline link is still an icon). Only backdrop-scale images earn a
+          // definite fail from sampling.
+          const carrierBox = imageSource.element.getBoundingClientRect();
+          if (sampled?.status === 'fail'
+            && (dimensionless || (intrinsic.width <= 32 && intrinsic.height <= 32) || carrierBox.height <= 40)) {
+            return {
+              status: 'incomplete',
+              message: 'A small background icon is painted on this element — if it sits beside the text rather than under it, judge the contrast against the plain background by eye.',
+            };
+          }
+          return sampled ?? {
             status: 'incomplete',
-            message: 'A small background icon is painted on this element — if it sits beside the text rather than under it, judge the contrast against the plain background by eye.',
+            message: 'The background here is several stacked image or gradient layers, which a script can’t sample. Contrast must be checked by eye.',
           };
         }
-        return sampled ?? {
-          status: 'incomplete',
-          message: 'The background here is an image that can’t be read (cross-origin) — contrast must be checked by eye.',
-        };
       }
     }
 
@@ -319,17 +387,23 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // exactly as an element's own background-image is bracketed.
     if (pseudoBack?.image) {
       const sampled = await sampledVerdict(pseudoBack.image, foreground, required, doc);
-      return sampled ?? {
-        status: 'incomplete',
-        message: 'A pseudo-element paints an image or gradient behind this text, so its real background isn’t the computed colour — contrast must be checked by eye.',
-      };
+      // PAINTS_NOTHING: the pseudo-element's image is fully transparent, so
+      // it never displaced the background the walk resolved.
+      if (sampled !== PAINTS_NOTHING) {
+        return sampled ?? {
+          status: 'incomplete',
+          message: 'A pseudo-element paints an image or gradient behind this text, so its real background isn’t the computed colour — contrast must be checked by eye.',
+        };
+      }
     }
     if (painted?.image && !pseudoBack) {
       const sampled = await sampledVerdict(painted.image, foreground, required, doc);
-      return sampled ?? {
-        status: 'incomplete',
-        message: 'An image or overlapping element is painted behind this text, so its real background isn’t the computed colour — contrast must be checked by eye.',
-      };
+      if (sampled !== PAINTS_NOTHING) {
+        return sampled ?? {
+          status: 'incomplete',
+          message: 'An image or overlapping element is painted behind this text, so its real background isn’t the computed colour — contrast must be checked by eye.',
+        };
+      }
     }
     // Only a hit-test-resolved backdrop is VERIFIED paint truth. Anything
     // else (offscreen sample point, element invisible to its own hit-test —
@@ -346,10 +420,12 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
       const obscuring = backgroundObscured(element);
       if (obscuring && obscuring !== 'unverifiable') {
         const sampled = await sampledVerdict(obscuring, foreground, required, doc);
-        return sampled ?? {
-          status: 'incomplete',
-          message: 'An image or overlapping element is painted behind this text, so its real background isn’t the computed colour — contrast must be checked by eye.',
-        };
+        if (sampled !== PAINTS_NOTHING) {
+          return sampled ?? {
+            status: 'incomplete',
+            message: 'An image or overlapping element is painted behind this text, so its real background isn’t the computed colour — contrast must be checked by eye.',
+          };
+        }
       }
     }
     if (pseudoBack?.color) {

package/engine/rules/wcag/2.2.1-meta-refresh.js

@@ -8,9 +8,23 @@ export default {
   selector: 'meta[http-equiv="refresh" i]',
   visibleOnly: false,
   evaluate(element) {
-    const delay = parseInt(element.getAttribute('content') ?? '', 10);
-    if (!(delay > 0)) return { status: 'pass' }; // 0 = immediate redirect, allowed
-    if (delay >= 72000) return { status: 'pass' }; // 2.2.1 exempts limits over 20 hours
+    const content = element.getAttribute('content') ?? '';
+    const delay = parseInt(content, 10);
+    // A refresh with no destination reloads THIS page. At zero seconds that
+    // is not the allowed instant redirect — it is a loop that throws the
+    // user back to the top of the page over and over (failure F41).
+    const hasDestination = /;\s*url\s*=/i.test(content);
+    if (delay === 0 && !hasDestination) {
+      return {
+        status: 'fail',
+        message: 'The page reloads itself immediately and has no destination to move on to, so the reload repeats for as long as the page is open. Nobody can read or complete anything on it.',
+        fix: 'Remove the timed refresh. If this is meant to be a redirect, give it a url (content="0; url=…"); if the content needs updating, update it in place instead of reloading.',
+      };
+    }
+    if (!(delay > 0)) return { status: 'pass' }; // 0 with a url = immediate redirect, allowed
+    // 2.2.1 exempts a time limit "longer than 20 hours" — 20 hours exactly
+    // is still inside the criterion.
+    if (delay > 72000) return { status: 'pass' };
     return {
       status: 'fail',
       message: `The page refreshes/redirects after ${delay}s — slow readers lose their place (or the whole page) with no control.`,

package/engine/rules/wcag/2.2.2-pause-stop-hide.js

@@ -1,25 +1,117 @@
 // WCAG SC 2.2.2 Pause, Stop, Hide (Level A)
+// "For any moving, blinking or scrolling information that (1) starts
+// automatically, (2) lasts more than five seconds, and (3) is presented in
+// parallel with other content, there is a mechanism for the user to pause,
+// stop, or hide it…"
+//
+// Two shapes are checkable, and they need different verdicts.
+//
+// <marquee> and <blink> exist only to move, ship no control of their own,
+// and are obsolete: a definite failure.
+//
+// A CSS animation set to repeat for ever is the modern ticker. Clauses 1
+// and 2 are settled by the CSS itself — it starts with the page and never
+// ends — but clause 3's "mechanism" may be any button anywhere on the page,
+// and no static pass can tell a pause control from any other button. So the
+// finding goes to a human with the evidence attached, never asserted.
+//
+// Only motion carrying TEXT is reported. Spinners, drifting decorative
+// blobs and shimmer effects move too, and flagging every loading indicator
+// on the web would bury the finding that matters. Silence there is
+// abstaining, not clearing.
+const MOTION_PROPERTIES = new Set([
+  'transform', 'translate', 'rotate', 'scale', 'offsetDistance', 'offsetPath', 'offsetRotate',
+  'left', 'right', 'top', 'bottom',
+  'marginLeft', 'marginRight', 'marginTop', 'marginBottom',
+  'backgroundPosition', 'backgroundPositionX', 'backgroundPositionY', 'objectPosition',
+]);
+
+/** Does this keyframe set move the element around, rather than merely
+ *  restyle it? A hue cycle is not movement; a translate is. */
+function keyframesMove(keyframes) {
+  return keyframes.some((frame) => Object.keys(frame).some((property) => MOTION_PROPERTIES.has(property)));
+}
+
+/** Blinking: the element is repeatedly taken away and put back. A gentle
+ *  breathing pulse (0.6 → 1) is not what the criterion is about, so an
+ *  opacity cycle only counts when it reaches near-invisible AND near-full. */
+function keyframesBlink(keyframes) {
+  if (keyframes.some((frame) => frame.visibility === 'hidden')) return true;
+  const opacities = keyframes
+    .map((frame) => parseFloat(frame.opacity))
+    .filter((value) => !Number.isNaN(value));
+  return opacities.some((value) => value <= 0.25) && opacities.some((value) => value >= 0.75);
+}
+
+/**
+ * Elements that an endlessly repeating animation is currently moving,
+ * mapped to the evidence. One document-wide getAnimations() call, never one
+ * per element: per-node getAnimations() filters every animation on the page
+ * each time, which turns animation-heavy pages quadratic.
+ */
+function endlesslyMoving(doc) {
+  const moving = new Map();
+  if (typeof doc.getAnimations !== 'function') return moving;
+  let animations;
+  try { animations = doc.getAnimations(); } catch { return moving; }
+  for (const animation of animations) {
+    // Paused, finished, or reversed-to-a-stop animations move nothing.
+    if (animation.playState !== 'running' || !animation.playbackRate) continue;
+    // Scroll- and view-driven animations advance only as the user scrolls,
+    // so they do not "start automatically" in the sense of the criterion.
+    if (animation.timeline && animation.timeline !== doc.timeline) continue;
+    const effect = animation.effect;
+    const target = effect?.target;
+    if (!target || target.nodeType !== 1) continue;
+    const timing = effect.getComputedTiming?.() ?? {};
+    if (timing.iterations !== Infinity || !(timing.duration > 0)) continue;
+    let keyframes;
+    try { keyframes = effect.getKeyframes(); } catch { continue; }
+    const moves = keyframesMove(keyframes);
+    if (!moves && !keyframesBlink(keyframes)) continue;
+    // A pseudo-element's motion is still the host element's motion.
+    if (!moving.has(target)) {
+      moving.set(target, { name: animation.animationName, verb: moves ? 'moves' : 'blinks' });
+    }
+  }
+  return moving;
+}
+
 export default {
   id: 'pause-stop-hide',
   impact: 'serious',
   tags: ['wcag2a', 'wcag222'],
   help: 'Moving content must be pausable',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html',
-  selector: 'marquee, blink',
+  selector: '*',
   // The criterion is about VISIBLE movement — a display:none marquee moves
   // nothing. aria-hidden content still moves on screen, so the rendered
   // check (not the AT-exposure check) is the right filter.
   visibility: 'visual',
-  evaluate(element) {
-    // scrollamount="0" is the documented way to ship a <marquee> that
-    // doesn't actually move.
-    if (element.tagName === 'MARQUEE' && element.getAttribute('scrollamount') === '0') {
-      return { status: 'pass' };
-    }
-    return {
-      status: 'fail',
-      message: `<${element.tagName.toLowerCase()}> scrolls or blinks with no way to pause it, which is unusable for people with attention or vestibular conditions.`,
-      fix: 'Replace it with static content, or a CSS animation with a pause control that honours prefers-reduced-motion.',
-    };
+  // One getAnimations() call for the whole page, then a lookup per element.
+  evaluateAll(elements) {
+    if (!elements.length) return [];
+    const moving = endlesslyMoving(elements[0].ownerDocument);
+    return elements.map((element) => {
+      if (element.tagName === 'MARQUEE' || element.tagName === 'BLINK') {
+        // scrollamount="0" is the documented way to ship a <marquee> that
+        // doesn't actually move.
+        if (element.tagName === 'MARQUEE' && element.getAttribute('scrollamount') === '0') {
+          return { status: 'pass' };
+        }
+        return {
+          status: 'fail',
+          message: `<${element.tagName.toLowerCase()}> scrolls or blinks with no way to pause it, which is unusable for people with attention or vestibular conditions.`,
+          fix: 'Replace it with static content, or a CSS animation with a pause control that honours prefers-reduced-motion.',
+        };
+      }
+      const animation = moving.get(element);
+      if (!animation || !element.textContent.trim()) return { status: 'pass' };
+      const named = animation.name ? ` (the “${animation.name}” animation)` : '';
+      return {
+        status: 'incomplete',
+        message: `This content ${animation.verb} continuously${named}: the animation repeats for ever, so it runs well past the five seconds at which WCAG 2.2.2 requires a way to pause, stop or hide it. Check the page offers one, and that it reaches this content.`,
+      };
+    });
   },
 };

package/engine/rules/wcag/2.4.2-document-title.js

@@ -1,4 +1,33 @@
 // WCAG SC 2.4.2 Page Titled (Level A)
+// "Web pages have titles that describe topic or purpose." A title that is
+// merely PRESENT satisfies the markup, not the criterion, so the two
+// well-known undescriptive shapes are checked as well.
+//
+// Tier one, failed: strings that are a stand-in under every reading.
+// "Untitled Document" is what an editor writes when the author wrote
+// nothing, and no page is ever about that.
+// Tier two, sent to a human: single generic words and framework scaffold
+// defaults. Almost always a leftover, but a gallery page really can be about
+// an artwork called "Untitled", and "Example Domain" really is the subject
+// of example.com. Those are somebody's call to make, not the engine's.
+//
+// Deliberately NOT judged: whether a real-looking title matches the page it
+// sits on. That needs someone who can read the page, and guessing at it
+// would produce exactly the confident-but-wrong findings this engine avoids.
+const PLACEHOLDER = new Set([
+  'untitled document', 'untitled page', 'untitled-1', 'untitled 1',
+  'new document', 'new page', 'new tab', 'no title',
+  'insert title here', 'title here', 'page title', 'document title',
+  'web page', 'webpage',
+]);
+const UNDESCRIPTIVE = new Set([
+  'untitled', 'document', 'page', 'title', 'default', 'index',
+  'react app', 'create react app', 'vite app', 'vite + react', 'vite + vue', 'vite + svelte',
+  'next app', 'create next app', 'vue app', 'nuxt app', 'svelte app', 'angular app',
+  'my app', 'my site', 'my website', 'site title', 'your site title',
+  'example domain', 'hello world',
+]);
+
 export default {
   id: 'document-title',
   impact: 'serious',
@@ -8,11 +37,29 @@ export default {
   selector: 'html',
   visibleOnly: false,
   evaluate(element) {
-    if (element.ownerDocument.title.trim()) return { status: 'pass' };
-    return {
-      status: 'fail',
-      message: 'The page has no title, so users of screen readers and browser tabs cannot tell what it is.',
-      fix: 'Add <title>Page name — Site name</title> inside <head>.',
-    };
+    const title = element.ownerDocument.title.trim();
+    if (!title) {
+      return {
+        status: 'fail',
+        message: 'The page has no title, so users of screen readers and browser tabs cannot tell what it is.',
+        fix: 'Add <title>Page name — Site name</title> inside <head>.',
+      };
+    }
+    // Collapsed and lowercased so "Untitled   Document" is caught too.
+    const normalized = title.replace(/\s+/g, ' ').toLowerCase();
+    if (PLACEHOLDER.has(normalized) || /^untitled[\s-]*\d+$/.test(normalized)) {
+      return {
+        status: 'fail',
+        message: `“${title}” is a placeholder left by an editor or template. It gives no topic and no purpose, so a screen reader announces nothing useful when the page loads, and a row of open tabs, bookmarks or history entries becomes impossible to tell apart.`,
+        fix: 'Put this page\'s own subject in the title first, then the site name.',
+      };
+    }
+    if (UNDESCRIPTIVE.has(normalized)) {
+      return {
+        status: 'incomplete',
+        message: `“${title}” is a generic title, and usually a default nobody replaced. Unless the page really is about that, it describes neither topic nor purpose and 2.4.2 is not met. Check whether it was meant to be filled in.`,
+      };
+    }
+    return { status: 'pass' };
   },
 };

package/engine/rules/wcag/2.4.7-focus-visible.js

@@ -5,19 +5,43 @@
 // rule entirely — so this flags for review, it never asserts a fail.
 function focusSuppressors(doc) {
   const suspects = [];
+  const replacementIn = (style) => style.getPropertyValue('box-shadow') || style.getPropertyValue('border')
+    || style.getPropertyValue('border-color') || style.getPropertyValue('background')
+    || style.getPropertyValue('background-color') || style.getPropertyValue('text-decoration');
+
+  const inspect = (rule) => {
+    if (!rule.selectorText || !/:focus/.test(rule.selectorText)) return;
+    // `:focus:not(:focus-visible) { outline: none }` is the PUBLISHED pattern
+    // for showing the ring to keyboard users only: it strips the indicator
+    // precisely in the state where the browser has decided not to show focus,
+    // and leaves the keyboard state alone. Flagging it fails the pattern the
+    // guidance recommends, and it ships in most modern CSS resets.
+    if (/:not\(\s*:focus-visible\s*\)/.test(rule.selectorText)) return;
+    const style = rule.style;
+    if (!style) return;
+    const outline = `${style.getPropertyValue('outline')} ${style.getPropertyValue('outline-style')} ${style.getPropertyValue('outline-width')}`;
+    const removesOutline = /\bnone\b/.test(outline) || /(^|\s)0(px)?(\s|$)/.test(outline);
+    if (!removesOutline) return;
+    // A replacement indicator may not sit in the rule's own style block: any
+    // declaration written AFTER a nested rule is parsed into a separate
+    // CSSNestedDeclarations child (a style-bearing rule with no selector), so
+    // reading only rule.style would report a suppressor that is in fact
+    // replaced two lines further down.
+    const nested = [...(rule.cssRules ?? [])]
+      .filter((child) => child.style && !child.selectorText);
+    if (replacementIn(style) || nested.some((child) => replacementIn(child.style))) return;
+    suspects.push(rule.selectorText);
+  };
+  // Inspect each rule, THEN descend into any children. Testing `rule.cssRules`
+  // first and skipping used to walk straight past every plain style rule:
+  // since CSS Nesting shipped, a CSSStyleRule carries its own cssRules list,
+  // and an empty CSSRuleList is still a truthy object, so the check meant for
+  // @media/@supports swallowed the whole sheet and the rule could never fire.
+  // A style rule can both declare and nest, so both halves have to run.
   const scan = (rules) => {
     for (const rule of rules) {
-      if (rule.cssRules) { scan(rule.cssRules); continue; } // @media/@supports
-      if (!rule.selectorText || !/:focus/.test(rule.selectorText)) continue;
-      const style = rule.style;
-      if (!style) continue;
-      const outline = `${style.getPropertyValue('outline')} ${style.getPropertyValue('outline-style')} ${style.getPropertyValue('outline-width')}`;
-      const removesOutline = /\bnone\b/.test(outline) || /(^|\s)0(px)?(\s|$)/.test(outline);
-      if (!removesOutline) continue;
-      const replaced = style.getPropertyValue('box-shadow') || style.getPropertyValue('border')
-        || style.getPropertyValue('border-color') || style.getPropertyValue('background')
-        || style.getPropertyValue('background-color') || style.getPropertyValue('text-decoration');
-      if (!replaced) suspects.push(rule.selectorText);
+      inspect(rule);
+      if (rule.cssRules?.length) scan(rule.cssRules); // @media/@supports/nesting
     }
   };
   for (const sheet of doc.styleSheets) {

package/engine/rules/wcag/3.1.1-html-lang.js

@@ -1,6 +1,14 @@
 // WCAG SC 3.1.1 Language of Page (Level A)
-// Rough BCP 47 shape: primary subtag + optional extras ("en", "en-GB", "zh-Hans").
-const LANG_PATTERN = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+// Rough BCP 47 shape: primary subtag + optional extras ("en", "en-GB",
+// "zh-Hans"). Subtags may be a SINGLE character: BCP 47 extension and
+// private-use singletons are exactly that ("de-DE-u-co-phonebk",
+// "zh-CN-x-private"), so a 2-character floor rejects legal tags. The second
+// branch covers private-use-only and grandfathered tags ("x-klingon",
+// "i-klingon"), whose primary subtag is itself one character.
+// A 5-8 letter primary subtag is legal BCP 47 but unassigned in the IANA
+// registry, so it stays rejected: that is what catches lang="english".
+// Keep this in step with 3.1.2-valid-lang-parts.js.
+const LANG_PATTERN = /^([a-zA-Z]{2,3}(-[a-zA-Z0-9]{1,8})*|[xXiI](-[a-zA-Z0-9]{1,8})+)$/;
 
 export default {
   id: 'html-lang',

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

@@ -1,5 +1,8 @@
 // WCAG SC 3.1.2 Language of Parts (Level AA)
-const LANG_PATTERN = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+// 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.
+const LANG_PATTERN = /^([a-zA-Z]{2,3}(-[a-zA-Z0-9]{1,8})*|[xXiI](-[a-zA-Z0-9]{1,8})+)$/;
 
 export default {
   id: 'valid-lang-parts',

package/engine/rules/wcag/4.1.2-aria-hidden-focus.js

@@ -1,4 +1,6 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
+import { cumulativeOpacity } from '../../lib/contrast.js';
+
 const FOCUSABLE = 'a[href], area[href], button, input, select, textarea, summary, iframe, '
   + 'audio[controls], video[controls], [contenteditable]:not([contenteditable="false"]), [tabindex]';
 
@@ -17,12 +19,15 @@ export default {
     // focus lands there, so the harm this rule describes (sighted keyboard
     // users interacting with SR-invisible content) doesn't materialise —
     // an invisible tab stop is a focus-order/visible-focus concern instead.
+    // Transparency is measured up the flat tree: opacity is not an inherited
+    // property, so a faded WRAPPER (the standard off-canvas drawer) leaves
+    // every control inside it computing opacity: 1 while none of them paint.
     const focusable = [element, ...element.querySelectorAll(FOCUSABLE)].filter(
       (el) => el.matches?.(FOCUSABLE) && el.getAttribute('tabindex') !== '-1' && !el.disabled
         // `inert` removes focusability outright — aria-hidden + inert is
         // the CORRECT modern pattern for off-canvas content, not a defect.
         && !el.closest('[inert]')
-        && isRendered(el) && getComputedStyle(el).opacity !== '0',
+        && isRendered(el) && cumulativeOpacity(el) > 0,
     );
     if (!focusable.length) return { status: 'pass' };
     // While a modal dialog is open, the page behind it is DELIBERATELY

package/engine/wcag22.js

@@ -68,7 +68,7 @@ export default [
   sc('2.3.2', 'Three Flashes', 'AAA', 'manual'),
   sc('2.3.3', 'Animation from Interactions', 'AAA', 'manual', '2.1'),
   sc('2.4.1', 'Bypass Blocks', 'A', 'partial'), // partial: "repeated across pages" can't be established from one page
-  sc('2.4.2', 'Page Titled', 'A', 'auto'),
+  sc('2.4.2', 'Page Titled', 'A', 'partial'), // partial: document-title proves a title exists and catches known placeholders; whether a real one DESCRIBES the page needs a reader
   sc('2.4.3', 'Focus Order', 'A', 'manual'), // no rule automates this yet; order judgment needs humans
   sc('2.4.4', 'Link Purpose (In Context)', 'A', 'partial'),
   sc('2.4.5', 'Multiple Ways', 'AA', 'manual'),
@@ -89,7 +89,7 @@ export default [
   sc('2.5.7', 'Dragging Movements', 'AA', 'manual', '2.2'),
   sc('2.5.8', 'Target Size (Minimum)', 'AA', 'partial', '2.2'), // partial: size/spacing are computable; the equivalent-control and essential exceptions need judgment
   // 3. Understandable
-  sc('3.1.1', 'Language of Page', 'A', 'auto'),
+  sc('3.1.1', 'Language of Page', 'A', 'partial'), // partial: html-lang proves the tag is present and well-formed; whether it names the language actually written needs a reader
   sc('3.1.2', 'Language of Parts', 'AA', 'partial'), // partial: invalid lang values are provable; UNMARKED foreign passages need language identification
   sc('3.1.3', 'Unusual Words', 'AAA', 'manual'),
   sc('3.1.4', 'Abbreviations', 'AAA', 'manual'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pour-engine",
-  "version": "1.1.9",
+  "version": "1.3.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",