pour-engine 1.1.9 → 1.2.0

package/config/project.config.js

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

package/engine/lib/contrast.js

@@ -762,23 +762,42 @@ 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.
  */
 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';
@@ -797,7 +816,11 @@ export function imageLuminanceRange(url) {
         let max = 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] });
+          // 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;
         }
@@ -809,7 +832,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 +880,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.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).

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

@@ -125,9 +125,38 @@ 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;
+  });
+}
+
 // 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) {
+async function sampledVerdict(source, foreground, required, doc, overlays = []) {
   if (!source) return null;
   // Translucent text takes its presented colour from the very pixels
   // beneath it — a luminance range of the backdrop cannot bracket the
@@ -140,7 +169,7 @@ async function sampledVerdict(source, foreground, required, doc) {
     };
   }
   if (source.tagName === 'IMG') {
-    return verdictFromRange(await imageLuminanceRange(source.currentSrc || source.src), foreground, required, 'image');
+    return verdictFromRange(await imageLuminanceRange(source.currentSrc || source.src, overlays), foreground, required, 'image');
   }
   const css = source.css ?? getComputedStyle(source).backgroundImage;
   if (!css || css === 'none') return null;
@@ -149,10 +178,10 @@ async function sampledVerdict(source, foreground, required, doc) {
   if (url) {
     let absolute;
     try { absolute = new URL(url, doc.baseURI).href; } catch { return null; }
-    return verdictFromRange(await imageLuminanceRange(absolute), foreground, required, 'image');
+    return verdictFromRange(await imageLuminanceRange(absolute, overlays), foreground, required, 'image');
   }
   if (css.includes('gradient(')) {
-    return verdictFromRange(gradientLuminanceRange(css), foreground, required, 'gradient');
+    return verdictFromRange(gradientLuminanceRange(css, overlays), foreground, required, 'gradient');
   }
   return null;
 }
@@ -248,7 +277,19 @@ 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);
+        // 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);
+        // 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

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/package.json

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