pour-engine 1.9.0 → 1.11.0

package/config/project.config.js

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

package/engine/lib/contrast.js

@@ -373,9 +373,10 @@ function textSamplePoint(element) {
  *   'unresolved'       — in-viewport but unanswerable (shadow retargeting hid
  *                        the element from the stack, blend/filter layers…)
  *
- * `scrim` (when present) is a translucent viewport-scale layer painted ON TOP
- * of the text — a modal veil, loading overlay, consent dimmer. The text is
- * presented through it, so the resting colours are not what the user sees.
+ * `scrim` (when present) is the list of translucent viewport-scale layers
+ * painted ON TOP of the text — a modal veil, loading overlay, consent dimmer.
+ * The text is presented through them, so the resting colours are not what the
+ * user sees; scrimPaint() turns them into the paint that dims it.
  *
  * Known approximation: pointer-events:none layers paint but never appear in
  * hit-test stacks, so a decorative tint above the resolved colour can be
@@ -564,9 +565,13 @@ export function pseudoBackdropForText(element) {
 
 /** A layer qualifies as a scrim over `element` when it is translucent paint
  *  (or a backdrop-filter) covering most of the viewport and the whole
- *  element — the shape of a modal/loading veil, not a badge or header. */
+ *  element — the shape of a modal/loading veil, not a badge or header.
+ *  Returns EVERY such layer, topmost first: consent flows routinely stack a
+ *  dimmer under a banner container, and the dimmed state the user sees is
+ *  all of them composited, not just the first one found. */
 function scrimIn(layersAbove, element, win) {
   const rect = element.getBoundingClientRect();
+  const found = [];
   for (const layer of layersAbove) {
     if (layer.contains(element) || element.contains(layer)) continue;
     const style = getComputedStyle(layer);
@@ -582,9 +587,33 @@ function scrimIn(layersAbove, element, win) {
       >= 0.6 * win.innerWidth * win.innerHeight;
     const coversElement = r.left <= rect.left + 1 && r.top <= rect.top + 1
       && r.right >= rect.right - 1 && r.bottom >= rect.bottom - 1;
-    if (coversViewport && coversElement) return layer;
+    if (coversViewport && coversElement) found.push(layer);
   }
-  return null;
+  return found.length ? found : null;
+}
+
+/**
+ * The flat paint of scrim layers (topmost first, as `scrimIn` returns them),
+ * ready for applyOverlays — or null when the dimmed state can't be computed
+ * as flat colour at all. A backdrop-filter resamples the pixels beneath it
+ * (blur, saturate, invert) and a blend mode or filter rewrites them: no
+ * colour arithmetic reproduces either, so those veils stay a human call.
+ */
+export function scrimPaint(layers) {
+  const paints = [];
+  for (const layer of layers) {
+    const style = getComputedStyle(layer);
+    if (style.backdropFilter && style.backdropFilter !== 'none') return null;
+    if (style.filter && style.filter !== 'none') return null;
+    if (style.mixBlendMode && style.mixBlendMode !== 'normal') return null;
+    if (style.backgroundImage !== 'none') return null;
+    const color = parseColor(style.backgroundColor);
+    if (!color) return null;
+    const alpha = color.a * (parseFloat(style.opacity) || 1);
+    if (alpha <= 0) continue;
+    paints.push({ ...color, a: alpha });
+  }
+  return paints.length ? paints : null;
 }
 
 export function paintedBackdrop(element) {
@@ -621,7 +650,24 @@ export function paintedBackdrop(element) {
     if ((style.mixBlendMode && style.mixBlendMode !== 'normal')
       || (style.filter && style.filter !== 'none')
       || (style.backdropFilter && style.backdropFilter !== 'none')) return 'unresolved';
-    if (style.backgroundImage !== 'none') return { image: layer, scrim };
+    // An ancestor carrying a background-image is only this text's backdrop if
+    // that image actually paints where the text is. The element's own image is
+    // adjudicated upstream against its paint rect; ancestors were not, so a
+    // decorative 4px accent stripe down a callout's left edge counted as the
+    // backdrop for text sitting 44px to its right, and the stripe's colour
+    // then failed the whole paragraph. Adjudicate at the same point the hit
+    // test used: if the rect resolves and does not cover it, this image is not
+    // what is behind the glyphs, so fall through to the layer's own colour.
+    // An unresolvable rect keeps the old behaviour, which errs toward asking a
+    // human rather than asserting from geometry we could not compute.
+    if (style.backgroundImage !== 'none') {
+      const rects = backgroundImagePaintRects(layer);
+      // An unresolvable layer (null) counts as covering: not knowing where a
+      // layer paints is a reason to ask a human, never to rule it out.
+      const covers = (r) => !r
+        || (point.x >= r.left && point.x < r.right && point.y >= r.top && point.y < r.bottom);
+      if (!rects.length || rects.some(covers)) return { image: layer, scrim };
+    }
     let color = parseColor(style.backgroundColor);
     if (!color) return 'unresolved';
     // A layer's own opacity thins its paint. (Group opacity shared with the
@@ -889,6 +935,100 @@ export function imageLuminanceRange(url, overlays = []) {
  * clear text that never overlaps the image — e.g. external-link icons
  * painted in a link's right padding (Wikipedia-style).
  */
+/**
+ * Paint rect for EVERY layer of a background-image list, one entry per layer,
+ * null where a layer's geometry cannot be resolved.
+ *
+ * background-size/position/repeat are comma-separated lists that pair up with
+ * the image list, so a four-layer background can be four separate 1px lines —
+ * which is how design systems draw a tile's border without a border. Judging
+ * such a background as one blob meant text in the middle of a tile was ruled
+ * unjudgeable because of four hairlines around its edge.
+ *
+ * A layer resolves to null (unknown, treat as covering) when it tiles, when
+ * cover/contain hands sizing to an intrinsic this function does not have, or
+ * when its position is not a plain length or percentage.
+ */
+export function backgroundImagePaintRects(element) {
+  const style = getComputedStyle(element);
+  const images = splitLayers(style.backgroundImage);
+  if (!images.length) return [];
+  const box = element.getBoundingClientRect();
+  const sizes = splitLayers(style.backgroundSize);
+  const positions = splitLayers(style.backgroundPosition);
+  const repeats = splitLayers(style.backgroundRepeat);
+  const per = (list, i) => (list.length ? list[i % list.length] : undefined);
+
+  return images.map((image, i) => {
+    if (image === 'none') return { left: 0, top: 0, right: 0, bottom: 0 }; // paints nothing
+    const repeat = per(repeats, i) ?? 'repeat';
+    if (repeat !== 'no-repeat') return null; // may tile under the text
+    const size = per(sizes, i) ?? 'auto';
+    if (size === 'cover' || size === 'contain') return null;
+    const parts = splitParts(size);
+    const extent = (value, total) => {
+      if (value?.endsWith('px')) return parseFloat(value);
+      if (value?.endsWith('%')) return (parseFloat(value) / 100) * total;
+      return null; // 'auto' on a gradient means the full box, but only for a
+      // single-layer background; per-layer we decline rather than guess.
+    };
+    const width = extent(parts[0], box.width);
+    const height = extent(parts[1] ?? parts[0], box.height);
+    if (width === null || height === null
+      || Number.isNaN(width) || Number.isNaN(height)) return null;
+    const pos = splitParts(per(positions, i) ?? '0% 0%');
+    const offset = (value, total, span) => {
+      if (value?.endsWith('%')) return (parseFloat(value) / 100) * (total - span);
+      if (value?.endsWith('px')) return parseFloat(value);
+      return null;
+    };
+    const offsetX = offset(pos[0], box.width, width);
+    const offsetY = offset(pos[1] ?? '50%', box.height, height);
+    // NaN, not just null: `calc(100% - 1px)` is a real position a design
+    // system writes, and a NaN that escapes as a rect is worse than an
+    // unresolved one — it compares false against everything, so a genuine
+    // image backdrop would be silently ruled clear of the text.
+    if (offsetX === null || offsetY === null
+      || Number.isNaN(offsetX) || Number.isNaN(offsetY)) return null;
+    const left = box.left + offsetX;
+    const top = box.top + offsetY;
+    return { left, top, right: left + width, bottom: top + height };
+  });
+}
+
+/** Split a space-separated CSS value, keeping function calls whole. Splitting
+ *  `calc(100% - 1px)` on whitespace yields `calc(100%`, which parseFloat reads
+ *  as 100 and every guard downstream then trusts. */
+function splitParts(value) {
+  const out = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of value) {
+    if (ch === '(') depth += 1;
+    if (ch === ')') depth -= 1;
+    if (/\s/.test(ch) && depth === 0) { if (current) out.push(current); current = ''; continue; }
+    current += ch;
+  }
+  if (current) out.push(current);
+  return out;
+}
+
+/** Split a comma-separated CSS list, ignoring commas inside parentheses. */
+function splitLayers(value) {
+  if (!value || value === 'none') return value === 'none' ? ['none'] : [];
+  const out = [];
+  let depth = 0;
+  let current = '';
+  for (const ch of value) {
+    if (ch === '(') depth += 1;
+    if (ch === ')') depth -= 1;
+    if (ch === ',' && depth === 0) { out.push(current.trim()); current = ''; continue; }
+    current += ch;
+  }
+  if (current.trim()) out.push(current.trim());
+  return out;
+}
+
 export function backgroundImagePaintRect(element, intrinsic) {
   const style = getComputedStyle(element);
   if ((style.backgroundImage.match(/url\(|gradient\(/g) ?? []).length !== 1) return null;

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

@@ -4,13 +4,25 @@ import {
   backgroundImageSource, backgroundImagePaintRect, imageLuminanceRange, gradientLuminanceRange,
   rangeVerdict, isLargeText, cumulativeOpacity, opacityAnimating, restingOpacity, mediaRects,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
-  pseudoBackdropForText, backgroundColorSource,
+  pseudoBackdropForText, backgroundColorSource, scrimPaint, applyOverlays,
 } from '../../lib/contrast.js';
 
 /** Display a ratio truncated (never rounded up): 4.495 must read "4.49",
  *  because "4.50:1 — below the 4.5:1 minimum" reads as a contradiction. */
 const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
 
+/** The one case a full-page veil still can't be judged for the author: the
+ *  resting page and the dimmed one land on opposite sides of the threshold,
+ *  so the verdict depends on whether the veil is transient or permanent. */
+const veiledIncomplete = (resting, veiled) => ({
+  status: 'incomplete',
+  message: 'This text sits behind a translucent full-page overlay (a modal or loading veil), which changes its presented contrast'
+    + (resting && veiled
+      ? `: ${showRatio(resting)}:1 at rest, ${showRatio(veiled)}:1 as presented through the overlay, which straddles the threshold`
+      : '')
+    + ' — judge the page with the overlay dismissed, or the dimmed state by eye if the overlay is permanent.',
+});
+
 /**
  * Is a duplicate copy of the same text painted exactly on top of this
  * element? The gradient-text pattern ships two copies — a plain-colour
@@ -388,28 +400,30 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // of merely flagging them for a human.
     const painted = paintedBackdrop(element);
     // A translucent viewport-scale veil is painted ON TOP of this text
-    // (modal scrim, loading overlay, consent dimmer): the user sees the
-    // text through it, so the resting colours are not the presented ones —
-    // and if the veil is transient, the resting state is what should be
-    // judged. Either way this is a human call, in both verdict directions.
-    if (painted?.scrim) {
-      return {
-        status: 'incomplete',
-        message: 'This text sits behind a translucent full-page overlay (a modal or loading veil), which changes its presented contrast — judge the page with the overlay dismissed, or the dimmed state by eye if the overlay is permanent.',
-      };
-    }
+    // (modal scrim, loading overlay, consent dimmer): the user sees the text
+    // through it, so the resting colours are not the presented ones — and if
+    // the veil is transient, the resting state is what should be judged.
+    // TWO states, then, and the honest question is whether they disagree.
+    // A consent dimmer over failing body text fails dimmed AND at rest; the
+    // veil changes nothing a human could rule differently, so a verdict is
+    // owed. Abstaining on sight instead silenced contrast across every page
+    // that greets a visitor with a cookie modal — which is most of the web.
+    // Only genuine disagreement between the two states is a human call.
+    let veilPaint = null;
+    let scrimLayers = painted?.scrim ?? null;
     // Offscreen text can't be hit-tested against the veil — but a FIXED
     // translucent overlay follows the viewport, so it dims scrolled-away
     // content just the same. (The veil's own contents are fixed too, hence
     // in-viewport, hence never routed through this branch.)
-    if (painted === 'offscreen') {
+    if (!scrimLayers && painted === 'offscreen') {
       const veil = viewportVeil(doc);
-      if (veil && !veil.contains(element)) {
-        return {
-          status: 'incomplete',
-          message: 'This text sits behind a translucent full-page overlay (a modal or loading veil), which changes its presented contrast — judge the page with the overlay dismissed, or the dimmed state by eye if the overlay is permanent.',
-        };
-      }
+      if (veil && !veil.contains(element)) scrimLayers = [veil];
+    }
+    if (scrimLayers) {
+      veilPaint = scrimPaint(scrimLayers);
+      // A veil whose paint can't be reduced to flat colour (backdrop-filter,
+      // blend mode) leaves the dimmed state uncomputable: still a human call.
+      if (!veilPaint) return veiledIncomplete();
     }
     // Pseudo-element paint sits above everything the hit-test and the walk
     // can report, and neither can see it — so it is resolved before them and
@@ -423,6 +437,11 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
         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.',
       };
     }
+    // An image backdrop under a veil would have to be sampled a second time,
+    // dimmed, to answer whether the two states agree. Not worth a second pass
+    // over the pixels of every hero photo behind a cookie modal: these keep
+    // the human call they have always had.
+    if (veilPaint && (pseudoBack?.image || painted?.image)) return veiledIncomplete();
     // Gradient/image paint from a pseudo-element: bracket it by sampling,
     // exactly as an element's own background-image is bracketed.
     if (pseudoBack?.image) {
@@ -526,6 +545,17 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     };
 
     const ratio = contrastRatio(foreground, background);
+    // The dimmed state, when a veil is up: it paints over the glyphs and
+    // their background alike, so both composite through the same layers.
+    // Dimming is not monotonic on ratio (it can rescue or ruin a pairing),
+    // which is exactly why both states are measured rather than assumed.
+    const veiled = (fg, bg) => contrastRatio(applyOverlays(fg, veilPaint), applyOverlays(bg, veilPaint));
+    if (veilPaint) {
+      const veiledRatio = veiled(foreground, background);
+      if ((veiledRatio >= required) !== (ratio >= required)) {
+        return veiledIncomplete(ratio, veiledRatio);
+      }
+    }
     if (ratio >= required) {
       return backdropHazard('pass', backgroundVerified) ?? { status: 'pass' };
     }
@@ -545,6 +575,14 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
       const halo = textShadowHalo(style.textShadow, fontSize);
       if (halo) {
         const haloRatio = contrastRatio(foreground, halo);
+        // A veil dims the glyphs and their own outline together: the halo
+        // verdict has to survive both states, exactly as the background one does.
+        if (veilPaint) {
+          const veiledHalo = veiled(foreground, halo);
+          if ((veiledHalo >= required) !== (haloRatio >= required)) {
+            return veiledIncomplete(haloRatio, veiledHalo);
+          }
+        }
         if (haloRatio >= required) return { status: 'pass' };
         return {
           status: 'fail',

package/package.json

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