pour-engine 1.14.1 → 1.16.0

package/config/project.config.js

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

package/engine/lib/contrast.js

@@ -479,8 +479,9 @@ function pseudoRect(host, style) {
  * on the pill, not on the track colour both other paths report.
  *
  * Returns { color } (opaque or translucent paint over the point),
- * 'unresolved' when something paints there that flat colour math can't
- * follow, or null when no pseudo of this host paints over the point.
+ * or null when no pseudo of this host paints over the point. Paint that
+ * can't be placed becomes a { film } entry — an upper bound on its alpha —
+ * so callers can bracket its effect instead of giving up on the element.
  */
 /** The paint a host's pseudo-elements contribute, resolved once per audit.
  *  Two extra getComputedStyle calls per host would otherwise land on every
@@ -495,7 +496,8 @@ function pseudoLayers(host) {
   for (const which of ['::before', '::after']) {
     const style = getComputedStyle(host, which);
     if (style.content === 'none' || style.display === 'none' || style.visibility === 'hidden') continue;
-    const paints = style.backgroundImage !== 'none' || (parseColor(style.backgroundColor)?.a ?? 0) > 0;
+    const color = parseColor(style.backgroundColor);
+    const paints = style.backgroundImage !== 'none' || (color?.a ?? 0) > 0;
     if (!paints) continue;
     // In-flow pseudos (the overwhelming majority: bullets, icons, rules,
     // badges) occupy their own box in the content flow beside the text
@@ -503,19 +505,34 @@ function pseudoLayers(host) {
     // backdrop, so everything else is simply not a layer here — treating
     // them as unknowable would abstain on half the web.
     if (style.position !== 'absolute' && style.position !== 'fixed') continue;
+    const opacity = parseFloat(style.opacity);
+    const opacityFactor = Number.isFinite(opacity) ? opacity : 1;
     const rect = style.position === 'absolute' ? pseudoRect(host, style) : null;
-    // Paint we can't place can't be ruled in or out — say so rather than
-    // silently leaving it out of the stack.
-    if (!rect) { layers = 'unresolved'; break; }
+    if (!rect) {
+      // Paint we can't place still can't paint MORE than its alpha allows:
+      // whatever colour it is and wherever it sits, it moves any channel
+      // beneath it by at most alpha × 255. Record that bound as a "film"
+      // so callers can bracket the verdict — a 3.5%-opacity grain overlay
+      // (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 });
+      continue;
+    }
     if (rect.empty) continue; // placed, and covers nothing
-    let color = parseColor(style.backgroundColor);
-    const opacity = parseFloat(style.opacity);
-    if (color && Number.isFinite(opacity) && opacity < 1) color = { ...color, a: color.a * opacity };
+    let layerColor = color;
+    if (layerColor && opacityFactor < 1) layerColor = { ...layerColor, a: layerColor.a * opacityFactor };
     // Gradient and image paint rides along as CSS so callers can sample it,
     // the same way they sample an element's background-image — a gradient
     // scrim over a card headline is a bracketable backdrop, not a mystery.
+    // Repeat/size/position ride along too: a no-repeat url() paints its
+    // intrinsic rect inside this box, not the whole of it, and only the
+    // caller (which knows where the text is) can rule on that geometry.
     const imageCss = style.backgroundImage !== 'none' ? style.backgroundImage : null;
-    layers.push({ rect, color, imageCss });
+    const imageMeta = imageCss
+      ? { repeat: style.backgroundRepeat, size: style.backgroundSize, position: style.backgroundPosition }
+      : null;
+    layers.push({ rect, color: layerColor, imageCss, imageMeta });
   }
   pseudoCache.set(host, layers);
   return layers;
@@ -539,28 +556,78 @@ function pseudoLayers(host) {
  *
  * Returns { color } (opaque, or translucent paint to composite over the
  * walked background), { image } for gradient/image paint the caller should
- * sample, 'unresolved' when paint in the chain can't be placed, or null when
- * no pseudo covers the text.
+ * sample, or null when no pseudo covers the text. Whenever the chain also
+ * holds paint that CAN'T be placed, the result carries `film`: an upper
+ * bound on that paint's alpha, accumulated across every unplaceable layer.
+ * The caller brackets the verdict against it — a film of alpha a moves any
+ * channel by at most a × 255 whether it sits behind the text or over it,
+ * and paint hidden beneath an opaque layer moves nothing, so the bound
+ * holds regardless of paint order.
  */
 export function pseudoBackdropForText(element) {
   const point = textSamplePoint(element);
   if (!point) return null;
   let acc = null;
+  let image = null;
+  let settled = false; // an opaque colour or an image hit: deeper layers are covered
+  let film = 0;
   for (let node = element; node && node.nodeType === 1; node = node.parentElement ?? node.getRootNode()?.host) {
-    const layers = pseudoLayers(node);
-    // Paint we can't place can't be ruled in or out, in either direction.
-    if (layers === 'unresolved') return 'unresolved';
-    for (const { rect, color, imageCss } of layers) {
+    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; }
+      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;
       // Gradient/image paint is bracketable by sampling, so hand it to the
-      // caller rather than giving up on the whole element.
-      if (imageCss) return { image: { css: imageCss, element: node } };
+      // caller rather than giving up on the whole element. The pseudo's box
+      // 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 (!color || color.a === 0) continue;
       acc = acc ? composite(acc, color) : color;
-      if (acc.a >= 1) return { color: acc };
+      if (acc.a >= 1) settled = true;
     }
   }
-  return acc ? { color: acc } : null;
+  if (image) return film > 0 ? { image, film } : { image };
+  if (acc) return film > 0 ? { color: acc, film } : { color: acc };
+  return film > 0 ? { film } : null;
+}
+
+/**
+ * The range the contrast ratio can occupy once an unplaceable translucent
+ * layer (a "film" of alpha ≤ film) may be painting somewhere in the stack.
+ *
+ * Two physical scenarios bound everything: the film behind the glyphs
+ * (shifting only the background) or over the whole element (shifting text
+ * and background alike, as t3-style full-page grain overlays do). Within
+ * each, luminance is monotone per colour channel and the ratio's derivative
+ * carries one sign across channels, so the extremes sit at an all-black or
+ * all-white film — five evaluations bound the true range.
+ *
+ * `crossed` flags the one case the endpoints can't bound from below: a film
+ * behind the text whose extremes land the background's luminance on OPPOSITE
+ * sides of the text's, where an intermediate colour collapses the ratio
+ * toward 1:1. Callers must not assert a pass when it is set; a fail needs
+ * only `max`, which the endpoints do bound.
+ */
+export function filmedContrastBounds(foreground, background, film) {
+  const ratios = [contrastRatio(foreground, background)];
+  const textLum = luminance(foreground);
+  const sides = [];
+  for (const channel of [0, 255]) {
+    const paint = { r: channel, g: channel, b: channel, a: film };
+    const shiftedBackground = composite(paint, background);
+    ratios.push(contrastRatio(foreground, shiftedBackground)); // film behind the text
+    ratios.push(contrastRatio(composite(paint, foreground), shiftedBackground)); // film over text and backdrop alike
+    sides.push(Math.sign(textLum - luminance(shiftedBackground)));
+  }
+  return {
+    min: Math.min(...ratios),
+    max: Math.max(...ratios),
+    crossed: sides[0] !== sides[1],
+  };
 }
 
 /** A layer qualifies as a scrim over `element` when it is translucent paint
@@ -887,7 +954,13 @@ export function imageLuminanceRange(url, overlays = []) {
         let minColor = null;
         let maxColor = null;
         let opaquePixels = 0;
+        let alphaSeen = false;
         for (let i = 0; i < data.length; i += 4) {
+          // Any see-through pixel means part of this layer shows whatever is
+          // painted beneath it — the sampled range alone then describes only
+          // the ink, not the backdrop the eye meets. Callers widen the range
+          // with the underlying paint (rangeWithBackdrop) or abstain.
+          if (data[i + 3] < 255) alphaSeen = true;
           if (data[i + 3] < 128) continue; // mostly-transparent pixels reveal what's beneath — unknowable
           opaquePixels += 1;
           // Composite each pixel through anything painted between the image
@@ -915,7 +988,7 @@ export function imageLuminanceRange(url, overlays = []) {
           return;
         }
         resolve(min <= max
-          ? { min, max, minColor, maxColor, width: img.naturalWidth, height: img.naturalHeight }
+          ? { min, max, minColor, maxColor, hasAlpha: alphaSeen, width: img.naturalWidth, height: img.naturalHeight }
           : null);
       } catch {
         resolve(null); // tainted canvas: cross-origin image without CORS headers
@@ -1032,17 +1105,34 @@ function splitLayers(value) {
 export function backgroundImagePaintRect(element, intrinsic) {
   const style = getComputedStyle(element);
   if ((style.backgroundImage.match(/url\(|gradient\(/g) ?? []).length !== 1) return null;
-  if (style.backgroundRepeat !== 'no-repeat') return null; // may tile under the text
-  if (style.backgroundSize === 'cover' || style.backgroundSize === 'contain') return null;
   const box = element.getBoundingClientRect();
+  return imagePaintRectInBox(
+    { left: box.left, top: box.top, right: box.right, bottom: box.bottom },
+    { repeat: style.backgroundRepeat, size: style.backgroundSize, position: style.backgroundPosition },
+    intrinsic,
+  );
+}
+
+/**
+ * The same paint-rect math for any painting box a caller already has —
+ * above all a pseudo-element's resolved box, which no element rect can
+ * describe. Returns null when the geometry is not statically knowable
+ * (tiling, cover/contain, keyword positions).
+ */
+export function imagePaintRectInBox(box, meta, intrinsic) {
+  if (!box || !meta) return null;
+  if (meta.repeat !== 'no-repeat') return null; // may tile under the text
+  if (meta.size === 'cover' || meta.size === 'contain') return null;
+  const boxWidth = box.right - box.left;
+  const boxHeight = box.bottom - box.top;
   const dimension = (value, total, auto) => {
     if (value?.endsWith('px')) return parseFloat(value);
     if (value?.endsWith('%')) return (parseFloat(value) / 100) * total;
     return auto;
   };
-  const size = style.backgroundSize.split(' ');
-  const width = dimension(size[0], box.width, intrinsic?.width);
-  const height = dimension(size[1] ?? size[0], box.height, intrinsic?.height);
+  const size = meta.size.split(' ');
+  const width = dimension(size[0], boxWidth, intrinsic?.width);
+  const height = dimension(size[1] ?? size[0], boxHeight, intrinsic?.height);
   if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
   // position N% aligns the image's N% point with the container's N% point.
   // Anything else (calc() from three-value syntax, keywords) is not
@@ -1053,15 +1143,41 @@ export function backgroundImagePaintRect(element, intrinsic) {
     if (value?.endsWith('px')) return parseFloat(value);
     return null;
   };
-  const pos = style.backgroundPosition.split(' ');
-  const offsetX = offset(pos[0], box.width, width);
-  const offsetY = offset(pos[1] ?? '50%', box.height, height);
+  const pos = meta.position.split(' ');
+  const offsetX = offset(pos[0], boxWidth, width);
+  const offsetY = offset(pos[1] ?? '50%', boxHeight, height);
   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 };
 }
 
+/**
+ * Widen a sampled luminance range with the layer painted beneath the image,
+ * for images that do not cover their box with opaque pixels (hasAlpha).
+ * A semi-transparent pixel blends per channel between its own colour and
+ * the underlying paint, and luminance is monotone in each channel, so a
+ * range extended with the underlying colour bounds every blend the eye can
+ * meet. Returns null when the underlying paint is unknown or itself
+ * see-through: no bound exists then, and the caller must not assert either
+ * verdict from the ink pixels alone — a mostly-transparent illustration
+ * sampled dark was asserting failures for text that really sat on the white
+ * showing through it.
+ */
+export function rangeWithBackdrop(range, under, overlays = []) {
+  if (!range || !range.hasAlpha) return range;
+  if (!under || under.a < 1) return null;
+  const shown = overlays.length ? applyOverlays(under, overlays) : under;
+  const underLum = luminance(shown);
+  return {
+    ...range,
+    min: Math.min(range.min, underLum),
+    max: Math.max(range.max, underLum),
+    minColor: underLum < range.min ? shown : range.minColor,
+    maxColor: underLum > range.max ? shown : range.maxColor,
+  };
+}
+
 /**
  * Luminance range of a CSS gradient, from its colour stops. Interpolated
  * colours stay close enough to their stops' luminances to bracket.

package/engine/lib/dom.js

@@ -106,6 +106,17 @@ export function htmlSnippet(element, maxLength = 300) {
   return html.length > maxLength ? `${html.slice(0, maxLength)}…` : html;
 }
 
+/** True when the document renders embedded inside another page (iframe or
+ *  frame). WCAG defines a "Web page" as a NON-embedded resource, so the
+ *  page-level criteria (2.4.2 Page Titled, 2.4.1 Bypass Blocks) judge only
+ *  the document the user actually opened: an embedded frame owes an
+ *  accessible name under 4.1.2, not its own <title> or skip link. The
+ *  reference comparison is safe cross-origin; frameElement is not. */
+export function isEmbeddedDocument(doc) {
+  const win = doc?.defaultView;
+  return !!(win && win.top && win !== win.top);
+}
+
 /** The element's own (not descendant-element) text, trimmed. */
 export function ownText(element) {
   return [...element.childNodes]

package/engine/rules/wcag/1.4.12-text-spacing.js

@@ -61,10 +61,20 @@ export default {
       // Only NEW clipping counts: content already truncated by design
       // (ellipsis patterns) is judged as-authored, not under the probe.
       if (before[i] || !after[i]) return { status: 'pass' };
+      // Review, not fail: the probe proves the box OVERFLOWS under the
+      // override, not that glyphs are lost. The genuine violation is a
+      // fixed-height overflow-hidden container that doesn't grow with its
+      // text, hiding whole lines (measured live: a 2-line card clamped at
+      // 37px whose text needs 61px spaced — the last line vanishes). But
+      // the same scroll-size delta also fires on benign overflow: the
+      // 0.12em letter-spacing lands AFTER the final glyph, so a snug box
+      // can overflow by trailing empty spacing that hides no ink, and a
+      // clamp pattern that swaps hidden words for an ellipsis is arguably
+      // truncation-by-design. Proving ink loss would need per-glyph rects
+      // against the clip box under the probe; until then, a human call.
       return {
-        status: 'fail',
-        message: 'With the WCAG text-spacing overrides applied (line height 1.5, letter/word spacing bumps), text in this element gets cut off — users who need wider spacing lose content.',
-        fix: 'Let the container grow (min-height instead of height, avoid overflow:hidden on text), so spacing changes reflow instead of clip.',
+        status: 'incomplete',
+        message: 'With the WCAG text-spacing overrides applied (line height 1.5, letter/word spacing bumps), this container overflows instead of growing — if that hides text rather than empty trailing spacing, users who need wider spacing lose content. Check with the overrides applied; to be safe, let the container grow (min-height instead of height, avoid overflow:hidden on text).',
       };
     });
   },

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

@@ -1,10 +1,11 @@
 // WCAG SC 1.4.3 Contrast (Minimum) (Level AA)
 import {
   parseColor, contrastRatio, composite, effectiveBackground, backgroundObscured,
-  backgroundImageSource, backgroundImagePaintRect, imageLuminanceRange, gradientLuminanceRange,
-  rangeVerdict, isLargeText, cumulativeOpacity, opacityAnimating, restingOpacity, mediaRects,
+  backgroundImageSource, backgroundImagePaintRect, imagePaintRectInBox, imageLuminanceRange,
+  gradientLuminanceRange, rangeVerdict, rangeWithBackdrop, isLargeText, cumulativeOpacity,
+  opacityAnimating, restingOpacity, mediaRects,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
-  pseudoBackdropForText, backgroundColorSource, scrimPaint, applyOverlays,
+  pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
 } from '../../lib/contrast.js';
 
 /** Display a ratio truncated (never rounded up): 4.495 must read "4.49",
@@ -165,7 +166,7 @@ function verdictFromRange(range, foreground, required, what) {
  */
 function unaccountedScrim(element, imageCarrier) {
   const pseudo = pseudoBackdropForText(element);
-  if (pseudo && pseudo !== 'unresolved' && pseudo.color?.a > 0) return true;
+  if (pseudo?.color?.a > 0) return true;
   const doc = element.ownerDocument;
   if (typeof doc.elementsFromPoint !== 'function') return false;
   const rect = element.getBoundingClientRect();
@@ -187,11 +188,29 @@ function unaccountedScrim(element, imageCarrier) {
  *  changing it, so the callers step over it rather than reporting on it. */
 const PAINTS_NOTHING = Symbol('fully transparent image layer');
 
+/** The flat paint directly beneath a carrier's background-image: the
+ *  carrier's own background-color composited over whatever resolves behind
+ *  the carrier. This is what shows through the image's transparent pixels.
+ *  Null when it is itself unknowable (another image or an unresolvable
+ *  chain behind) — the sampling then has no floor to extend its range with. */
+function paintUnderImage(carrier) {
+  const color = parseColor(getComputedStyle(carrier).backgroundColor);
+  if (color && color.a >= 1) return color;
+  const parent = carrier.parentElement ?? carrier.getRootNode()?.host ?? null;
+  const behind = parent ? effectiveBackground(parent) : null;
+  if (!behind) return null;
+  return color && color.a > 0 ? composite(color, behind) : behind;
+}
+
 // Bracket the verdict by sampling what's actually painted: image pixels
 // (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 = []) {
+// `under` is the colour painted beneath the sampled layer, when the caller
+// knows it: an image with see-through pixels shows that colour wherever the
+// ink is absent, so the judged range must include it — and without it no
+// verdict can be asserted from such an image at all.
+async function sampledVerdict(source, foreground, required, doc, overlays = [], under = null) {
   if (!source) return null;
   let range = null;
   let what = 'image';
@@ -216,6 +235,19 @@ async function sampledVerdict(source, foreground, required, doc, overlays = [])
   // 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;
+  // See-through pixels reveal the layer beneath: widen the range with it
+  // when it is known; when it isn't, the ink pixels alone prove nothing —
+  // a mostly-transparent illustration sampled dark was failing text that
+  // really sat on the white showing through it.
+  if (range?.hasAlpha) {
+    range = rangeWithBackdrop(range, under, overlays);
+    if (!range) {
+      return {
+        status: 'incomplete',
+        message: `The ${what} behind this text has transparent regions, so parts of the text sit on whatever is painted beneath it, and that layer could not be resolved — check the contrast by eye.`,
+      };
+    }
+  }
   // Translucent text takes its presented colour from the very pixels
   // beneath it, so a luminance range of the backdrop cannot be read straight
   // off: dimmed white over a dark photo reads mid-grey, not white.
@@ -270,11 +302,16 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
   tags,
   help,
   helpUrl,
-  // div included deliberately: real-world layouts put lots of text in bare
-  // divs; the own-text check below keeps wrapper divs out of the results.
+  // Every element except the ones whose text is judged elsewhere or isn't
+  // CSS-colour text at all: a tag allow-list silently skipped visible text
+  // in anything it forgot (form, center, font, custom elements — Hacker
+  // News writes "Search:" directly inside <form>), and the own-text check
+  // below keeps the empty wrappers out of the results either way. Form
+  // controls stay out because control-contrast judges their text; SVG/MathML
+  // stay out because their glyphs are painted by fill, not color.
   selector:
-    'p, span, a, li, td, th, dt, dd, h1, h2, h3, h4, h5, h6, label, button, legend, caption, ' +
-    'figcaption, div, blockquote, small, strong, em, b, i, code, pre, time, cite, q, summary',
+    '*:not(script):not(style):not(noscript):not(title):not(option):not(optgroup)' +
+    ':not(input):not(textarea):not(select):not(svg):not(svg *):not(math):not(math *)',
   visibility: 'visual', // contrast is seen by sighted users even in aria-hidden content
   async evaluate(element, { ownText }) {
     if (!ownText(element)) return { status: 'pass' }; // no text of its own to judge
@@ -352,7 +389,8 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
         // 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);
+        let sampled = await sampledVerdict(imageSource, foreground, required, doc, imageSource.overlays,
+          paintUnderImage(imageSource.element));
         // 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.
@@ -430,12 +468,52 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // wins. Geometry-only, so it settles offscreen text too, where the
     // hit-test is blind and the walk would otherwise assert the track colour
     // of a control the text visibly is not sitting on.
-    const pseudoBack = pseudoBackdropForText(element);
-    if (pseudoBack === 'unresolved') {
-      return {
-        status: 'incomplete',
-        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.',
-      };
+    //
+    // Unplaceable pseudo paint no longer abstains on sight: it arrives as
+    // `film`, an upper bound on its alpha, and the flat-colour verdict below
+    // is bracketed against it — asserted only when black and white films,
+    // behind the text or over it, all land the same side of the threshold.
+    // A 3.5%-opacity fixed grain overlay (the full-page texture pattern)
+    // otherwise sent every element on the page to the review lane, and a
+    // genuine 4.1:1 failure drowned among 163 siblings that were fine.
+    const pseudoResolved = pseudoBackdropForText(element);
+    const film = pseudoResolved?.film ?? 0;
+    let pseudoBack = pseudoResolved?.color || pseudoResolved?.image ? pseudoResolved : null;
+    // The pseudo's BOX covering the text says nothing about its IMAGE doing
+    // so: a no-repeat url() paints its intrinsic rect inside that box (a
+    // menu item's ::before arrow icon in a box that spans the whole item).
+    // When that rect is computable and provably misses every text box, the
+    // icon sits beside the text, not behind it — the layer is not a
+    // backdrop at all. And an icon-sized image that IS under a text corner
+    // may flag for eyes, never assert: the same discipline the element
+    // background-image path has always applied.
+    let pseudoIconScale = false;
+    if (pseudoBack?.image?.meta && pseudoBack.image.box) {
+      const pseudoUrl = pseudoBack.image.css.match(/url\(["']?(.*?)["']?\)/)?.[1];
+      if (pseudoUrl && pseudoBack.image.meta.repeat === 'no-repeat') {
+        let pseudoIntrinsic = null;
+        try { pseudoIntrinsic = await imageLuminanceRange(new URL(pseudoUrl, doc.baseURI).href); } catch { /* unknowable */ }
+        const dimensionless = !pseudoIntrinsic || !pseudoIntrinsic.width
+          || (pseudoIntrinsic.width === 300 && pseudoIntrinsic.height === 150);
+        const paint = imagePaintRectInBox(pseudoBack.image.box, pseudoBack.image.meta, dimensionless ? null : pseudoIntrinsic);
+        if (paint && !paint.empty && !textIntersects(element, paint)) {
+          pseudoBack = null; // paints clear of the glyphs — judge what's beneath
+        } else {
+          pseudoIconScale = dimensionless
+            || (pseudoIntrinsic.width <= 32 && pseudoIntrinsic.height <= 32);
+        }
+      }
+    }
+    const filmIncomplete = {
+      status: 'incomplete',
+      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.',
+    };
+    // Sampled pixels, veils and text-shadow halos can't be film-bracketed
+    // (the film may sit between the sample and the glyphs): those verdicts
+    // keep the human call they had when any unplaceable paint abstained.
+    if (film > 0 && (pseudoBack?.image || painted?.image || painted === 'unresolved'
+      || veilPaint || (style.textShadow && style.textShadow !== 'none'))) {
+      return filmIncomplete;
     }
     // 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
@@ -445,10 +523,21 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // Gradient/image paint from a pseudo-element: bracket it by sampling,
     // exactly as an element's own background-image is bracketed.
     if (pseudoBack?.image) {
-      const sampled = await sampledVerdict(pseudoBack.image, foreground, required, doc);
+      // Beneath the pseudo's paint sits its own host's background — a
+      // ::before draws above the host's background and below everything
+      // else, so the host's resolved colour is what shows through any
+      // transparent pixels the image has.
+      const sampled = await sampledVerdict(pseudoBack.image, foreground, required, doc, [],
+        effectiveBackground(pseudoBack.image.element));
       // PAINTS_NOTHING: the pseudo-element's image is fully transparent, so
       // it never displaced the background the walk resolved.
       if (sampled !== PAINTS_NOTHING) {
+        if (sampled?.status === 'fail' && pseudoIconScale) {
+          return {
+            status: 'incomplete',
+            message: 'A small icon is painted by a pseudo-element 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 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.',
@@ -515,6 +604,16 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // gradient canvas under its hero heading is exactly this shape), so
     // even verified verdicts must be bracketed against them.
     const backdropHazard = (direction, blindOnly) => {
+      // An element's OWN opaque background sits directly beneath its own
+      // text: no non-descendant layer can paint between the two, and
+      // descendant media is already excluded below — so however the page
+      // stacks around it, the resolved colour is the presented one. Without
+      // this, every below-the-fold category chip painted over a card
+      // thumbnail (white-on-red at a flat 3.99:1) sat in the review lane
+      // because the offscreen hit-test could not verify what geometry
+      // already proves.
+      const ownPaint = parseColor(style.backgroundColor);
+      if (ownPaint && ownPaint.a >= 1) return null;
       // One box read for the element, then pure rect math per candidate —
       // this runs for every unverified element on the page.
       const box = element.getBoundingClientRect();
@@ -545,6 +644,17 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     };
 
     const ratio = contrastRatio(foreground, background);
+    // Bracket the verdict against any unplaceable pseudo paint: only when
+    // every colour and placement the film could take leaves the ratio on one
+    // side of the threshold is the verdict provable. A 3.5% grain film can
+    // never rescue 4.1:1, so that fails outright; a 50% veil could rescue or
+    // ruin anything, so it stays the human call it always was.
+    if (film > 0) {
+      const bounds = filmedContrastBounds(foreground, background, film);
+      const decided = (bounds.min >= required) === (bounds.max >= required)
+        && !(bounds.crossed && bounds.min >= required);
+      if (!decided) return filmIncomplete;
+    }
     // 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),

package/engine/rules/wcag/1.4.4-meta-viewport.js

@@ -1,4 +1,6 @@
 // WCAG SC 1.4.4 Resize Text (Level AA)
+import { isEmbeddedDocument } from '../../lib/dom.js';
+
 export default {
   id: 'meta-viewport',
   impact: 'critical',
@@ -8,6 +10,10 @@ export default {
   selector: 'meta[name="viewport"]',
   visibleOnly: false,
   evaluate(element) {
+    // Browsers read the viewport meta of the TOP document only; one inside
+    // an embedded frame is ignored wholesale, so it cannot stop anyone
+    // zooming and must not be reported as if it did.
+    if (isEmbeddedDocument(element.ownerDocument)) return { status: 'pass' };
     const content = element.getAttribute('content') ?? '';
     const disablesZoom = /user-scalable\s*=\s*(no|0)/i.test(content);
     const maxScale = content.match(/maximum-scale\s*=\s*([\d.]+)/i);

package/engine/rules/wcag/2.4.1-bypass-blocks.js

@@ -1,5 +1,5 @@
 // WCAG SC 2.4.1 Bypass Blocks (Level A)
-import { collectRoots } from '../../lib/dom.js';
+import { collectRoots, isEmbeddedDocument } from '../../lib/dom.js';
 
 export default {
   id: 'bypass-blocks',
@@ -10,6 +10,11 @@ export default {
   selector: 'html',
   visibleOnly: false,
   evaluate(element) {
+    // 2.4.1 governs blocks "repeated on multiple Web pages", and a WCAG
+    // Web page is a non-embedded resource: an embedded frame's document
+    // owes no skip link of its own (the frame's title is itself the bypass
+    // the spec names in H64).
+    if (isEmbeddedDocument(element.ownerDocument)) return { status: 'pass' };
     // 2.4.1's sufficient techniques: a skip link, landmarks (ARIA11), or
     // headings (H69) — any one mechanism satisfies the criterion. Modern
     // component pages keep ALL of these inside open shadow roots (the

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

@@ -14,6 +14,8 @@
 // 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.
+import { isEmbeddedDocument } from '../../lib/dom.js';
+
 const PLACEHOLDER = new Set([
   'untitled document', 'untitled page', 'untitled-1', 'untitled 1',
   'new document', 'new page', 'new tab', 'no title',
@@ -37,6 +39,11 @@ export default {
   selector: 'html',
   visibleOnly: false,
   evaluate(element) {
+    // 2.4.2 applies to "Web pages", which the spec defines as non-embedded
+    // resources. A widget or ad iframe is part of the page, not a page:
+    // demanding a <title> of it invents failures on every embedded frame
+    // (its name comes from the iframe's title attribute, judged by 4.1.2).
+    if (isEmbeddedDocument(element.ownerDocument)) return { status: 'pass' };
     const title = element.ownerDocument.title.trim();
     if (!title) {
       return {

package/engine/rules/wcag/2.5.8-target-size.js

@@ -32,6 +32,20 @@ const TARGETS = 'a[href], button, input, select, [role="button"], [role="link"]'
 function isHiddenFromPointer(element, rect) {
   if (rect.width <= 1 || rect.height <= 1) return true;
   if (rect.right <= 0 || rect.bottom <= 0) return true; // parked above/left of the canvas
+  // Parked BEYOND the document's scrollable extent on the other two sides:
+  // the slide-in drawer pattern (basket/menu panels held at
+  // translateX(100%) until opened). A fixed drawer does not extend the
+  // document's scroll range, so no scroll position ever brings the pointer
+  // to it — its dozen stacked links are not pointer targets in this state,
+  // and they must not crowd the page's real targets either. In-flow content
+  // that genuinely overflows DOES extend scrollWidth/scrollHeight and keeps
+  // being judged.
+  const win = element.ownerDocument.defaultView;
+  const scroller = element.ownerDocument.scrollingElement ?? element.ownerDocument.documentElement;
+  if (win && scroller) {
+    if (rect.left + win.scrollX >= scroller.scrollWidth - 1) return true;
+    if (rect.top + win.scrollY >= scroller.scrollHeight - 1) return true;
+  }
   const style = getComputedStyle(element);
   if ((parseFloat(style.opacity) || 0) === 0) return true;
   if (style.clipPath !== 'none' || (style.clip !== 'auto' && style.position === 'absolute')) return true;

package/engine/rules/wcag/4.1.2-aria-label-misuse.js

@@ -2,19 +2,27 @@
 // element does not support name from author. Authors MUST NOT use the
 // aria-label or aria-labelledby attributes to name the element." A label on
 // a plain div/span/p breaks that MUST, so it is a real, provable authoring
-// error — and browsers respond by dropping the prohibited name, which is
-// exactly what makes the WCAG verdict undecidable from the DOM.
+// error.
 //
-// It is not, on its own, a 4.1.2 failure. A static text container is not a
-// "user interface component", and the dropped name leaves whatever name,
-// role and value the element legitimately has untouched. Nothing is
-// announced wrongly; nothing the criterion requires is provably absent.
+// What browsers DO with the prohibited name was measured, not assumed
+// (2026-08-09, Chromium accessibility tree + VoiceOver on a live product
+// page): both expose aria-label on paragraph/generic/strong as the
+// element's accessible name, and VoiceOver announces it. So the label is
+// NOT reliably dropped — the earlier wording here claimed it was, and a
+// user who tested with a screen reader rightly called it misleading. But
+// prohibited means unguaranteed: exposure of a name the spec forbids is
+// browser goodwill, varies across AT pairings, and may change without
+// notice. A page can neither rely on the label being announced nor on it
+// being ignored — which cuts in both directions and is exactly what makes
+// the WCAG verdict undecidable from the DOM.
 //
-// What CAN fail is the thing underneath: if the author reached for a label
-// because assistive technology genuinely should announce this element — a
-// hand-rolled widget missing its role, a region missing its landmark — then
-// the name they wrote is invisible and the missing role is the defect.
-// Whether that is so is exactly what the DOM cannot establish.
+// It is not, on its own, a 4.1.2 failure. A static text container is not a
+// "user interface component", and whatever name, role and value the element
+// legitimately has stays untouched. Where the label IS announced, it
+// replaces the element's visible text for AT users (sometimes deliberately:
+// a price written for the ear over a struck-through visual price); where it
+// is ignored, users get the visible text alone. The human question is
+// whether either presentation is wrong for this element.
 //
 // This rule has lived on both sides of the line. It asserted under WCAG
 // scope originally, was demoted to best-practice when an independent audit
@@ -36,7 +44,7 @@ export default {
   id: 'aria-label-misuse',
   impact: 'moderate',
   tags: ['wcag2a', 'wcag412'],
-  help: 'aria-label on a generic element is dropped by the browser',
+  help: 'aria-label on a plain container is prohibited by ARIA, so its announcement is not guaranteed',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: 'div[aria-label]:not([role]):not([tabindex]), span[aria-label]:not([role]):not([tabindex]), p[aria-label]:not([role]):not([tabindex])',
   evaluate(element) {
@@ -48,8 +56,8 @@ export default {
     if (element.closest(NAME_FROM_CONTENT)) return { status: 'pass' };
     return {
       status: 'incomplete',
-      message: `aria-label="${element.getAttribute('aria-label')}" on a plain <${element.tagName.toLowerCase()}> is prohibited by ARIA and dropped by the browser, so assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. Should this element be announced? If it plays a role worth naming — a widget, a region, a group — the missing role is the defect and this is a 4.1.2 failure. If it is just a styled container, the attribute is stray and no one is affected.`,
-      fix: 'If the element should be announced, give it the role it is playing (a landmark, group, or widget role) so the name is legal and exposed. If it should not, remove the aria-label. Do not add a role solely to legalise the label.',
+      message: `aria-label="${element.getAttribute('aria-label')}" on a plain <${element.tagName.toLowerCase()}> is prohibited by ARIA: this element's role does not support naming, so although many browser and screen reader pairings announce the label today, that support is not guaranteed anywhere and can differ between assistive technologies. Where it is announced it replaces the element's visible text; where it is not, users get the visible text alone. Check both presentations read correctly, and that nothing here relies on the label being heard.`,
+      fix: 'If this element must reliably announce something of its own, give it the role it is playing (a landmark, group, or widget role) so the name is legal and exposure is guaranteed — or move the spoken text into visible or visually-hidden real text. If the label is stray, remove it. Do not add a role solely to legalise the label.',
     };
   },
 };

package/package.json

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