pour-engine 1.20.0 → 1.21.0

package/config/project.config.js

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

package/engine/lib/contrast.js

@@ -153,7 +153,7 @@ export function resetAuditCaches() {
  */
 export function backgroundColorSource(element) {
   for (let node = element; node && node.nodeType === 1;
-    node = node.parentElement ?? node.getRootNode()?.host) {
+    node = node.assignedSlot ?? node.parentElement ?? node.getRootNode()?.host) {
     const style = getComputedStyle(node);
     if (style.backgroundImage !== 'none' && !paintsNothing(style.backgroundImage)) return null;
     const color = parseColor(style.backgroundColor);
@@ -209,7 +209,13 @@ function resolveBackground(element, doc) {
     if (color && color.a >= 1) {
       result = color;
     } else {
-      const behind = resolveBackground(element.parentElement ?? element.getRootNode()?.host, doc);
+      // The FLAT-tree parent: a slotted element's backdrop chain runs
+      // through its slot into the shadow tree it renders in — walking the
+      // light parent instead skipped every background painted inside the
+      // outer component's shadow (a consent banner's blue container lived
+      // there, and its slotted copy was judged against the page white).
+      const behind = resolveBackground(
+        element.assignedSlot ?? element.parentElement ?? element.getRootNode()?.host, doc);
       result = behind === null ? null : (color && color.a > 0 ? composite(color, behind) : behind);
     }
   }
@@ -531,7 +537,12 @@ function pseudoLayers(host) {
       // (position: fixed, the common full-page-texture pattern) must not
       // send every element on the page to a human.
       const alphaBound = Math.min(1, opacityFactor * (style.backgroundImage !== 'none' ? 1 : color.a));
-      if (alphaBound > 0) layers.push({ film: alphaBound });
+      // Position rides along: a FIXED unplaceable pseudo is the full-page
+      // overlay pattern and dims everything below the walk; an ABSOLUTE one
+      // that defeated the geometry solver (rotation, percentage insets) is
+      // a decorative shape that nearer opaque paint covers in normal
+      // stacking — the walk needs to know which it is.
+      if (alphaBound > 0) layers.push({ film: alphaBound, fixed: style.position === 'fixed' });
       continue;
     }
     if (rect.empty) continue; // placed, and covers nothing
@@ -586,11 +597,33 @@ export function pseudoBackdropForText(element) {
   let image = null;
   let settled = false; // an opaque colour or an image hit: deeper layers are covered
   let film = 0;
+  // Paint (an opaque background-color or a background-image) on an element
+  // BETWEEN the text and a pseudo's host makes the pseudo's place in the
+  // stack unprovable from here: CSS paint order can put an out-of-flow
+  // ancestor pseudo above OR below that intermediate paint depending on
+  // positioning, z-index and tree order — the full stacking model this walk
+  // deliberately does not reimplement. Such layers are surfaced with
+  // `beyondPaint` so the caller brackets the verdict instead of asserting
+  // against paint that may never show behind the glyphs (a full-page
+  // decorative body::before wash under sections with their own solid
+  // backgrounds produced 90 false contrast failures on one university home).
+  let crossed = false;
+  let beyondPaint = false;
   for (let node = element; node && node.nodeType === 1; node = node.parentElement ?? node.getRootNode()?.host) {
     for (const layer of pseudoLayers(node)) {
-      // Films accumulate over the WHOLE chain — even past an opaque hit,
-      // because an ancestor's ::after can paint above a descendant's pill.
-      if (layer.film) { film = 1 - (1 - film) * (1 - layer.film); continue; }
+      // Films accumulate over the whole chain — an ancestor's fixed ::after
+      // (grain overlays, veils) paints above everything below it. But an
+      // ABSOLUTE pseudo whose geometry could not be solved (a rotated or
+      // percent-positioned decorative shape) sits in normal flow stacking:
+      // once opaque paint lies between the text and its host, that paint
+      // covers it, and filming the verdict anyway sent every element under
+      // a decorative page shape to the review lane (127 reviews on one
+      // charity home whose buttons carry their own solid backgrounds).
+      if (layer.film) {
+        if (!layer.fixed && crossed) continue;
+        film = 1 - (1 - film) * (1 - layer.film);
+        continue;
+      }
       if (settled) continue;
       const { rect, color, imageCss } = layer;
       if (point.x < rect.left || point.x > rect.right || point.y < rect.top || point.y > rect.bottom) continue;
@@ -599,14 +632,28 @@ export function pseudoBackdropForText(element) {
       // and image geometry travel with it: covering the sample point is a
       // fact about the BOX, and a no-repeat icon may still paint nowhere
       // near the text.
-      if (imageCss) { image = { css: imageCss, element: node, box: rect, meta: layer.imageMeta }; settled = true; continue; }
+      if (imageCss) {
+        image = { css: imageCss, element: node, box: rect, meta: layer.imageMeta };
+        settled = true;
+        beyondPaint = beyondPaint || crossed;
+        continue;
+      }
       if (!color || color.a === 0) continue;
       acc = acc ? composite(acc, color) : color;
+      beyondPaint = beyondPaint || crossed;
       if (acc.a >= 1) settled = true;
     }
+    // Crossing updates AFTER the node's own pseudos: a host's ::before
+    // paints above its own background, so its own paint never makes its own
+    // pseudo ambiguous — only paint on elements nearer the text does.
+    if (!crossed) {
+      const style = getComputedStyle(node);
+      if ((style.backgroundImage !== 'none' && !paintsNothing(style.backgroundImage))
+        || (parseColor(style.backgroundColor)?.a ?? 0) >= 1) crossed = true;
+    }
   }
-  if (image) return film > 0 ? { image, film } : { image };
-  if (acc) return film > 0 ? { color: acc, film } : { color: acc };
+  if (image) return { image, ...(film > 0 && { film }), ...(beyondPaint && { beyondPaint }) };
+  if (acc) return { color: acc, ...(film > 0 && { film }), ...(beyondPaint && { beyondPaint }) };
   return film > 0 ? { film } : null;
 }
 
@@ -727,6 +774,13 @@ export function paintedBackdrop(element) {
       return { image: layer, scrim };
     }
     const style = getComputedStyle(layer);
+    // A shadow HOST in the stack hides its shadow tree from the hit-test
+    // (elementsFromPoint retargets internal elements to the host), so paint
+    // inside it is invisible here: compositing the host as "transparent"
+    // and reading layers behind it judged slotted banner text against the
+    // page white while the component's shadow painted a blue container
+    // between them. Whatever renders inside is unknowable to this walk.
+    if (layer.shadowRoot) return 'unresolved';
     // Blend modes and filters change the paint in ways flat colour math
     // can't follow — that's a human check, not a resolution.
     if ((style.mixBlendMode && style.mixBlendMode !== 'normal')

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

@@ -9,6 +9,12 @@ import {
   showRatio,
 } from '../../lib/contrast.js';
 
+/** The strict separator set for the pure-decoration exemption: pipes,
+ *  interpuncts, slashes, dashes and guillemets — one glyph, optionally
+ *  repeated ("···"). Deliberately excludes brackets, colons, stars and
+ *  every character that carries grouping, rating or code meaning. */
+const SEPARATOR_GLYPHS = /^([|¦·•∙‧/⁄\\‐‑‒–—―⁃«»‹›-])\1*$/;
+
 /** Serialise a judged colour for the report and the checker link. Composited
  *  channels keep up to two decimals: rounding them to integers changes the
  *  pair enough that the checker scores a different ratio than the audit
@@ -323,7 +329,49 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // The criterion exempts "inactive user interface components".
     if (element.closest(':disabled, [aria-disabled="true"]')) return { status: 'pass' };
 
-    const style = getComputedStyle(element);
+    // A shadow HOST's own text renders through its shadow tree: when a
+    // <slot> projects it, the text inherits styles from the slot's
+    // shadow-side parent, NOT from the host — a consent banner's shadow
+    // <p> painted the slotted copy near-white while the host computed
+    // black, and the host-styled pair was one no user ever sees. With no
+    // slot to project it, the host's own text does not render at all.
+    // (Closed shadow roots are undetectable; those hosts keep the old
+    // behaviour.)
+    let styleSource = element;
+    if (element.shadowRoot) {
+      const ownTextNode = [...element.childNodes]
+        .find((node) => node.nodeType === 3 && node.textContent.trim());
+      const slot = ownTextNode?.assignedSlot ?? null;
+      if (!slot) return { status: 'pass' }; // unprojected: not rendered
+      styleSource = slot;
+    }
+    const style = getComputedStyle(styleSource);
+
+    // A lone separator glyph between inline items is 1.4.3 "pure
+    // decoration": it does the job a border does (and borders carry no
+    // text-contrast requirement), and the ARIA Authoring Practices tell
+    // authors to draw exactly these separators in CSS or aria-hidden them.
+    // Strictly bounded — one repeated glyph from a fixed separator set,
+    // inline, outside code and interactive content, with rendered content
+    // on BOTH sides — so Python's `>>>` prompt, code operators, maths in
+    // prose and meaning-bearing brackets all keep their verdicts.
+    if (SEPARATOR_GLYPHS.test(ownText(element))
+      && style.display.startsWith('inline')
+      && !element.closest('code, pre, samp, kbd, var, a[href], button, [role="button"], [role="link"], [role="menuitem"], [role="tab"], [role="option"]')) {
+      const hasContent = (start, dir) => {
+        for (let node = start; node; node = node[dir]) {
+          if (node.nodeType === 3 && node.textContent.trim()) return true;
+          if (node.nodeType === 1 && (node.textContent.trim()
+            || node.matches('img, svg, video, canvas, input, select, button'))) return true;
+        }
+        return false;
+      };
+      if (hasContent(element.previousSibling, 'previousSibling')
+        && hasContent(element.nextSibling, 'nextSibling')) {
+        return { status: 'pass' };
+      }
+    }
+
     // Controls conveying "disabled" without the attribute: pointer-events:
     // none on an interactive element is functional inertness — the low
     // contrast IS the disabled styling (carousel arrows at the end of
@@ -434,7 +482,11 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
       }
     }
 
-    let background = effectiveBackground(element);
+    // For slotted host text, the walk starts at the slot: its flat-tree
+    // chain (slot → shadow parents → host → light ancestors) is the one the
+    // text actually paints in; effectiveBackground crosses the shadow
+    // boundary via getRootNode().host on its own.
+    let background = effectiveBackground(styleSource);
 
     // Browser-truth paint order at the text's own sample point: sees and
     // RESOLVES backdrops painted by non-ancestors (positioned siblings,
@@ -524,6 +576,18 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // 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();
+    // A pseudo layer that sits BEYOND intermediate paint (an element between
+    // the text and the pseudo's host carries its own opaque background or
+    // image): whether the pseudo paints behind these glyphs or is covered by
+    // that nearer paint is a stacking-order question this engine deliberately
+    // does not model. Image paint can't be bracketed against the walked
+    // colour, so it stays a human call.
+    if (pseudoBack?.image && pseudoBack.beyondPaint) {
+      return {
+        status: 'incomplete',
+        message: 'An ancestor\'s pseudo-element paints an image or gradient where this text is, but other backgrounds sit between them — which one is behind the glyphs depends on paint order, so check the contrast by eye.',
+      };
+    }
     // Gradient/image paint from a pseudo-element: bracket it by sampling,
     // exactly as an element's own background-image is bracketed.
     if (pseudoBack?.image) {
@@ -580,7 +644,31 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
         }
       }
     }
-    if (pseudoBack?.color) {
+    if (pseudoBack?.color && pseudoBack.beyondPaint) {
+      // Paint sits between this text and the pseudo's host, so the pseudo
+      // may equally be covered by it (the common case: a decorative
+      // full-bleed wash on body under sections with their own backgrounds).
+      // Bracket instead of choosing: a verdict is only provable when the
+      // walked background and the pseudo-as-backdrop land the same side of
+      // the threshold; disagreement is a genuine human call.
+      const candidate = pseudoBack.color.a >= 1 || !background
+        ? pseudoBack.color
+        : composite(pseudoBack.color, background);
+      if (!background) {
+        return { status: 'incomplete', message: 'The background could not be determined — check contrast by eye.' };
+      }
+      const overWalked = foreground.a < 1 ? composite(foreground, background) : foreground;
+      const overPseudo = foreground.a < 1 ? composite(foreground, candidate) : foreground;
+      if ((contrastRatio(overWalked, background) >= required)
+        !== (contrastRatio(overPseudo, candidate) >= required)) {
+        return {
+          status: 'incomplete',
+          message: 'An ancestor\'s pseudo-element paints where this text is, but other backgrounds sit between them — which colour is behind the glyphs depends on paint order, and the two candidates disagree on the verdict. Check the contrast by eye.',
+        };
+      }
+      // Both candidates agree: judge against the walked background below.
+      // The backdrop stays UNVERIFIED — the hazard bracket still applies.
+    } else if (pseudoBack?.color) {
       // Opaque pill: it IS the backdrop. Translucent paint composites over
       // whatever the walk resolved beneath it. Either way the geometry is
       // computed, not guessed, so this counts as verified paint truth.
@@ -679,6 +767,19 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     const rect = element.getBoundingClientRect();
     // Zero-area text paints nothing (collapsed badges, empty counters).
     if (!rect.width || !rect.height) return { status: 'pass' };
+    // Text parked wholly left of or above the document is unreachable by any
+    // scroll position (skip links pre-focus, sr-only labels at left:-10000px,
+    // panels slid out at negative offsets): it is not visually presented, so
+    // 1.4.3 has nothing to judge. Scrolling can only reach coordinates >= 0
+    // in LTR documents; RTL pages legitimately extend leftward, so they keep
+    // the old behavior.
+    {
+      const win = doc.defaultView;
+      if (win && getComputedStyle(doc.documentElement).direction !== 'rtl'
+        && (rect.right + win.scrollX <= 0 || rect.bottom + win.scrollY <= 0)) {
+        return { status: 'pass' };
+      }
+    }
     // A text-shadow can supply the contrast (technique G18 measures the
     // letters against their halo): white text with a solid dark outline
     // passes however the fill compares to the backdrop. A parseable solid

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

@@ -27,6 +27,19 @@ export default {
     const rect = element.getBoundingClientRect();
     if (rect.width <= 1 || rect.height <= 1) return { status: 'pass' };
     const style = getComputedStyle(element);
+    // Text rendered at font-size 0 (icon buttons whose value is a
+    // screen-reader label) is not visually presented — nothing to judge.
+    if (parseFloat(style.fontSize) === 0) return { status: 'pass' };
+    // Controls parked wholly left of or above the document are unreachable
+    // by scrolling (sr-only duplicates): same exemption as the main rule.
+    {
+      const doc = element.ownerDocument;
+      const win = doc.defaultView;
+      if (win && getComputedStyle(doc.documentElement).direction !== 'rtl'
+        && (rect.right + win.scrollX <= 0 || rect.bottom + win.scrollY <= 0)) {
+        return { status: 'pass' };
+      }
+    }
     // Judge the opacity the text RESTS at, matching the main contrast rule:
     // a control faded out by an ancestor (fade-in-on-scroll, a collapsed
     // panel) presents no text at all, and one held at a low opacity presents

package/package.json

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