pour-engine 1.8.0 → 1.10.0

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -111,7 +111,7 @@ meaning that only a person can settle, even where a rule decides most real pages
 
 | SC | Name | Level | Coverage | Rules |
 |---|---|---|---|---|
-| 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.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-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:** 30 partially automated · 56 manual — with 74 rules.

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) {

package/engine/rules/{wcag/4.1.2-aria-allowed-attr.js → best-practice/aria-allowed-attr.js}

@@ -1,26 +1,30 @@
-// WCAG SC 4.1.2 Name, Role, Value (Level A)
-// An ARIA attribute the role does not support is INERT. Measured in Chromium:
-// aria-expanded on a button exposes expanded=false, and the same attribute on
-// a complementary landmark exposes no state at all. It is dropped, not
-// misreported, so the old "announces the wrong state" wording was wrong.
+// ARIA 1.2 §8.6, repeated verbatim in the 1.3 draft: "authors MUST only use
+// non-global states and properties on elements with a role supporting the
+// state or property". An unsupported attribute breaks that MUST, so this is a
+// real, provable authoring error and the rule asserts it.
 //
-// Which is why this REVIEWS rather than fails. ARIA 1.2 §5.2.3 says authors
-// MAY provide supported states and user agents MUST map them; "prohibited"
-// (§5.2.5) is a separate category this rule does not cover. An unsupported
-// attribute is therefore not a spec violation, and name, role and value are
-// all still conveyed correctly, so no success criterion provably fails.
+// It is NOT a WCAG failure, which is why it lives here rather than under
+// 4.1.2. An unsupported attribute is INERT, measured in Chromium:
+// aria-expanded on a button exposes expanded=false, while the same attribute
+// on a complementary landmark exposes no state at all. It is dropped, not
+// misreported. So the role is still exposed, the name is still computed, and
+// nothing is announced incorrectly. Name, role and value all survive, which
+// is all 4.1.2 asks for.
 //
-// The 4.1.2 tag stays because there IS a real failure hiding here: if the
-// element genuinely has the state the author was reaching for, that state is
-// now invisible to assistive technology. Whether it does is exactly what the
-// DOM cannot establish, so it is a question for a person. Same reasoning that
-// put aria-label-misuse in best-practice.
+// What CAN fail 4.1.2 is the thing underneath: if the element genuinely has
+// the state the author reached for, that state is now invisible. Whether it
+// does is exactly what the DOM cannot establish, so the message asks rather
+// than asserts. Reporting the ARIA error as a WCAG violation would have been
+// asserting a criterion failure off the back of a question.
+//
+// Note "unsupported" is distinct from "prohibited" (§5.2.5), a separate
+// category about naming that this rule does not cover.
 //
 // Worth knowing when comparing against other tools: aria-expanded WAS
 // inherited into complementary, banner, heading, img and list under ARIA 1.1,
 // and was narrowed in 1.2 (narrowed again in the 1.3 draft). Markup written
 // against 1.1 is not conforming under 1.2, and a tool on the older baseline
-// stays silent on it.
+// stays silent on it. Neither reading is a bug; they are different editions.
 import { GLOBAL_ARIA, ROLE_ARIA, KNOWN_ARIA, effectiveRole } from '../../lib/roles.js';
 
 // aria-label/labelledby misuse on generic elements has its own rule
@@ -30,9 +34,9 @@ const HANDLED_ELSEWHERE = new Set(['label', 'labelledby']);
 export default {
   id: 'aria-allowed-attr',
   impact: 'moderate',
-  tags: ['wcag2a', 'wcag412'],
-  help: 'ARIA attributes must be allowed for the element’s role',
-  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+  tags: ['best-practice'],
+  help: 'ARIA attributes must be supported by the element’s role',
+  helpUrl: 'https://www.w3.org/TR/wai-aria-1.2/#state_property_processing',
   selector: '*',
   visibleOnly: false,
   evaluate(element) {
@@ -56,9 +60,9 @@ export default {
     if (!disallowed.length) return { status: 'pass' };
     const names = disallowed.map((n) => `aria-${n}`);
     return {
-      status: 'incomplete',
-      message: `${names.join(', ')} is not supported on role "${role}", so the browser drops it and assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. If this element really does have that state, it is currently invisible: check whether it needs conveying another way.`,
-      fix: `Move ${names.join('/')} to the element whose role supports it, usually the control that toggles this one, or remove it if the element has no such state.`,
+      status: 'fail',
+      message: `${names.join(', ')} is not supported on role "${role}", so the browser drops it and assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. If this element really does have that state, it is currently invisible to anyone using a screen reader.`,
+      fix: `Move ${names.join('/')} to the element whose role supports it, usually the control that toggles this one, or remove it if the element has no such state. Adding a role to this element to make the attribute legal is rarely right: the host language restricts which roles each element may take.`,
     };
   },
 };

package/engine/rules/index.js

@@ -42,7 +42,10 @@ import audioControl from './wcag/1.4.2-audio-control.js';
 import pauseStopHide from './wcag/2.2.2-pause-stop-hide.js';
 import mediaCaptions from './wcag/1.2.2-media-captions.js';
 import ariaAttrValid from './wcag/4.1.2-aria-attr-valid.js';
-import ariaAllowedAttr from './wcag/4.1.2-aria-allowed-attr.js';
+// Demoted to best-practice: an unsupported ARIA attribute breaks an ARIA
+// author MUST (1.2 §8.6) but is INERT, so name, role and value all survive
+// and no success criterion fails (see the note in the rule file).
+import ariaAllowedAttr from './best-practice/aria-allowed-attr.js';
 import ariaFieldName from './wcag/4.1.2-aria-field-name.js';
 // Demoted to best-practice: prohibited-but-inert ARIA on a generic element
 // fails no success criterion (see the note in the rule file).

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.8.0",
+  "version": "1.10.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",