pour-engine 1.40.0 → 1.42.0

package/engine/rules/wcag/1.3.4-orientation.js

@@ -3,58 +3,108 @@
 // orientation, such as portrait or landscape, unless a specific display
 // orientation is essential."
 //
-// What a stylesheet can PROVE: a rule inside an @media (orientation: …)
-// block that hides or counter-rotates the page root is restricting the
-// whole page to the other orientation — the "please rotate your device"
-// wall (body { display: none }) and the forced-landscape hack
-// (body { transform: rotate(90deg) }). The rotate hack even disproves the
-// "essential" escape by itself: content that renders rotated demonstrably
-// works in both orientations.
+// What a stylesheet can show: a rule inside an @media (orientation: …)
+// block that hides or counter-rotates the page root restricts the whole
+// page to the other orientation, the "please rotate your device" wall
+// (body { display: none }) and the forced-landscape hack
+// (body { transform: rotate(90deg) }). Asserted the way ACT rule b33eff
+// asserts a quarter turn between orientations, under its stated assumption
+// that no orientation is essential; the message names that exception. Both
+// orientations count: a rule for the orientation the device is not in right
+// now is still a restriction, and ACT evaluates both.
 //
-// Deliberately NOT flagged: orientation media queries that restyle or hide
-// individual regions — that is ordinary responsive design, not a lock.
-// Script-driven locks (screen.orientation.lock()) and cross-origin
-// stylesheets (unreadable under CORS) are invisible to a static pass; the
-// rule asserts only what it can see and stays silent otherwise.
-// The root ELEMENT only, optionally qualified by pseudo-classes. A pseudo-
-// element (body::before, html::backdrop) is one generated box, and hiding
-// it in portrait is the region restyling this rule deliberately leaves
-// alone; matching it asserted "hides the page" over a decorative band
-// (2026-08-25 overnight audit). Pseudo-classes are kept, but only assert
-// when the live root actually matches them (see rootSelector).
+// What the live page adds (2026-09-12): when the block IS active, computed
+// style shows whether the declaration is in force, so an overridden or
+// cancelled declaration is not a failure. When the block is dormant, a
+// later declaration for the same root in the same orientation undoes an
+// earlier one, in cascade order (display: block after display: none,
+// transform: none after a rotation). Unsupported @supports branches and
+// disabled sheets are skipped. Script locks (screen.orientation.lock()) and
+// cross-origin sheets stay invisible to a static pass.
+//
+// Deliberately NOT flagged: orientation queries that restyle or hide
+// individual regions (ordinary responsive design), and a root pseudo-element
+// (body::before is one generated box). Root pseudo-class selectors only
+// count when the live root matches them (body:not(.ready) once .ready is on
+// locks nothing).
+// https://www.w3.org/WAI/WCAG22/Understanding/orientation.html
+// https://www.w3.org/WAI/standards-guidelines/act/rules/b33eff/
 const ROOT_PART = /^(html|body|:root)((?::[a-z-]+(?:\([^()]*\))?)*)$/i;
 const LOCK_ROTATE = /rotate(?:3d\([^)]*,\s*)?\(?\s*(?:-?(?:90|270)deg|0\.25turn|-0\.25turn|100grad|-100grad)/i;
 
-function rootSelector(selectorText, doc) {
-  return (selectorText ?? '').split(',').some((part) => {
+function matchingRoots(selectorText, doc) {
+  const roots = new Set();
+  for (const part of (selectorText ?? '').split(',')) {
     const match = ROOT_PART.exec(part.trim());
-    if (!match) return false;
-    if (!match[2]) return true; // bare root: always in force
-    // body:not(.ready) { visibility: hidden } locks nothing once the class
-    // is on; the selector must match the root as it stands to be a lock.
+    if (!match) continue;
     const root = /^body$/i.test(match[1]) ? doc.body : doc.documentElement;
-    try { return !!root && root.matches(part.trim()); } catch { return false; }
-  });
+    try { if (root?.matches(part.trim())) roots.add(root); } catch { /* invalid selector */ }
+  }
+  return [...roots];
+}
+
+// CSS transforms and the independent rotate property compose. A 90-degree
+// declaration can be overridden, or cancelled by an opposite rotation.
+function quarterTurn(style, win) {
+  let angle = 0;
+  if (style.transform && style.transform !== 'none') {
+    try {
+      const matrix = new win.DOMMatrixReadOnly(style.transform);
+      if (!matrix.is2D) return null;
+      angle += Math.atan2(matrix.b, matrix.a) * 180 / Math.PI;
+    } catch { return null; }
+  }
+  if (style.rotate && style.rotate !== 'none') {
+    const rotation = /^(?:(?:z|0\s+0\s+1)\s+)?(-?[\d.]+)(deg|rad|grad|turn)$/.exec(style.rotate);
+    if (!rotation) return null;
+    const scale = { deg: 1, rad: 180 / Math.PI, grad: 0.9, turn: 360 }[rotation[2]];
+    angle += Number(rotation[1]) * scale;
+  }
+  return Math.abs(((angle % 180) + 180) % 180 - 90) < 0.01;
 }
 
-function scanRules(rules, insideOrientation, findings, doc) {
+/** Walk the sheet in cascade order, keeping the LAST relevant declaration
+ *  per root, orientation and property, so a later declaration in the same
+ *  orientation block undoes an earlier lock. */
+function scanRules(rules, orientationContext, active, state, doc) {
+  const win = doc.defaultView;
   for (const rule of rules ?? []) {
-    const condition = rule.conditionText ?? rule.media?.mediaText;
-    if (condition !== undefined && rule.cssRules) {
+    if (rule.type === win.CSSRule.SUPPORTS_RULE) {
+      // An unsupported branch cannot apply in either orientation.
+      if (win.CSS.supports(rule.conditionText)) scanRules(rule.cssRules, orientationContext, active, state, doc);
+      continue;
+    }
+    if (rule.type === win.CSSRule.MEDIA_RULE) {
+      const condition = rule.conditionText ?? rule.media.mediaText;
       const orientation = /orientation\s*:\s*(portrait|landscape)/i.exec(condition)?.[1];
-      scanRules(rule.cssRules, orientation ? { condition, orientation } : insideOrientation, findings, doc);
+      const context = orientation ? { condition, orientation } : orientationContext;
+      scanRules(rule.cssRules, context, active && win.matchMedia(condition).matches, state, doc);
       continue;
     }
-    if (insideOrientation && rule.style && rootSelector(rule.selectorText, doc)) {
+    if (orientationContext && rule.style) {
       const { display, visibility, transform, rotate } = rule.style;
-      if (display === 'none' || visibility === 'hidden') {
-        findings.push({ kind: 'hidden', selector: rule.selectorText, ...insideOrientation });
-      } else if (LOCK_ROTATE.test(transform ?? '') || LOCK_ROTATE.test(rotate ?? '')) {
-        findings.push({ kind: 'rotated', selector: rule.selectorText, ...insideOrientation });
+      const declared = {
+        display: display ? (display === 'none' ? 'hidden' : null) : undefined,
+        visibility: visibility ? (visibility === 'hidden' ? 'hidden' : null) : undefined,
+        transform: transform ? (LOCK_ROTATE.test(transform) ? 'rotated' : null) : undefined,
+        rotate: rotate ? (LOCK_ROTATE.test(`rotate(${rotate})`) ? 'rotated' : null) : undefined,
+      };
+      if (Object.values(declared).some((value) => value !== undefined)) {
+        for (const root of matchingRoots(rule.selectorText, doc)) {
+          const key = `${orientationContext.orientation.toLowerCase()}|${root === doc.body ? 'body' : 'html'}`;
+          if (!state.has(key)) state.set(key, {});
+          const entry = state.get(key);
+          for (const [property, kind] of Object.entries(declared)) {
+            if (kind === undefined) continue;
+            entry[property] = kind ? { kind, active, selector: rule.selectorText, ...orientationContext } : null;
+          }
+        }
       }
-    } else if (rule.cssRules) {
-      scanRules(rule.cssRules, insideOrientation, findings);
     }
+    // Layers and other grouping rules retain the surrounding media state.
+    // Unknown conditional groups cannot establish an active restriction.
+    if (rule.cssRules) scanRules(rule.cssRules, orientationContext,
+      active && rule.conditionText === undefined, state, doc);
   }
 }
 
@@ -66,24 +116,43 @@ export default {
   help: 'Content must work in both portrait and landscape',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/orientation.html',
   selector: 'html',
-  // The evidence is in the stylesheet, not in the root's own rendering — and
-  // the lock hides the root exactly when it is in force, so a visibility
-  // filter here would silence the rule in the only state that matters.
-  visibleOnly: false,
+  visibleOnly: false, // a restriction can hide the root itself
   evaluate(element) {
-    const findings = [];
-    for (const sheet of element.ownerDocument.styleSheets) {
+    const doc = element.ownerDocument;
+    const win = doc.defaultView;
+    const state = new Map();
+    for (const sheet of doc.styleSheets) {
+      if (sheet.disabled) continue;
+      const media = sheet.media?.mediaText;
+      if (media && !win.matchMedia(media).matches) continue;
       let rules;
       try { rules = sheet.cssRules; } catch { continue; } // cross-origin: unreadable, skip
-      scanRules(rules, null, findings, element.ownerDocument);
+      scanRules(rules, null, true, state, doc);
+    }
+    const findings = [];
+    for (const [key, entry] of state) {
+      const root = key.endsWith('|body') ? doc.body : doc.documentElement;
+      for (const finding of Object.values(entry)) {
+        if (!finding) continue;
+        if (finding.active) {
+          // The block applies right now, so the computed style is the truth:
+          // an overridden or cancelled declaration locks nothing.
+          const computed = win.getComputedStyle(root);
+          const effective = finding.kind === 'hidden'
+            ? computed.display === 'none' || computed.visibility === 'hidden'
+            : quarterTurn(computed, win);
+          if (effective === false) continue;
+        }
+        findings.push(finding);
+      }
     }
     if (!findings.length) return { status: 'pass' };
-    const f = findings[0];
-    const verb = f.kind === 'hidden' ? 'hides the page' : 'rotates the page to force the other orientation';
+    const finding = findings.find((candidate) => candidate.active) ?? findings[0];
+    const verb = finding.kind === 'hidden' ? 'hides the page' : 'rotates the page to force the other orientation';
     return {
       status: 'fail',
-      message: `A stylesheet rule (${f.selector} under @media ${f.condition}) ${verb} when the device is in ${f.orientation} — the content is locked to a single display orientation.`,
-      fix: 'Let the layout adapt to both orientations instead of hiding or rotating the page. If a single orientation is genuinely essential (rare), document why.',
+      message: `A stylesheet rule (${finding.selector} under @media ${finding.condition}) ${verb} when the device is in ${finding.orientation}${finding.active ? ', and it is in effect now' : ''}: the content is locked to a single display orientation. 1.3.4 allows that only where one orientation is essential, which a stylesheet cannot show; this finding assumes it is not.`,
+      fix: 'Let the layout adapt to both orientations instead of hiding or rotating the page. If a single orientation is genuinely essential (rare), document why and dismiss this finding.',
     };
   },
 };

package/engine/rules/wcag/1.3.5-autocomplete-valid.js

@@ -97,19 +97,32 @@ export default {
       .split(/\s+/)
       .filter(Boolean);
     const invalid = tokens.filter((token) => !isKnown(token));
-    if (invalid.length) {
+    const fault = invalid.length ? null : (tokens.length ? grammarFault(tokens) : null);
+    if (!invalid.length && !fault) return { status: 'pass' };
+    // Asserted the way ACT rule 73f2c2 asserts it, under its assumption that
+    // an autocomplete attribute sits on a field collecting information about
+    // the user, which is what the attribute is for. A search box is the one
+    // common field that carries the attribute and collects nothing about the
+    // user, so it is asked about rather than failed. The message names the
+    // assumption so a reviewer can dismiss the finding on a field 1.3.5 does
+    // not cover. https://www.w3.org/WAI/standards-guidelines/act/rules/73f2c2/
+    const problem = invalid.length
+      ? `autocomplete contains unknown token(s): ${invalid.join(', ')}, so browsers and assistive tools cannot identify this field's purpose from it`
+      : `autocomplete="${element.getAttribute('autocomplete').trim()}" is not a valid autofill value: ${fault}. Browsers discard the whole value, so no purpose is exposed`;
+    const fix = invalid.length
+      ? 'Use tokens from the HTML input-purposes list, e.g. autocomplete="email" or autocomplete="given-name".'
+      : 'Use one field name from the HTML autofill list, optionally preceded by section-*, then shipping or billing, and (for tel, email and impp only) a contact type, e.g. autocomplete="shipping tel" or autocomplete="home email".';
+    if (element.type === 'search') {
       return {
-        status: 'fail',
-        message: `autocomplete contains unknown token(s): ${invalid.join(', ')} — browsers and assistive tools can't identify this field's purpose.`,
-        fix: 'Use tokens from the HTML input-purposes list, e.g. autocomplete="email" or autocomplete="given-name".',
+        status: 'incomplete',
+        message: `${problem}. 1.3.5 covers fields that collect information about the user, which a search box usually does not; if this one does, correct the value.`,
+        fix,
       };
     }
-    const fault = tokens.length ? grammarFault(tokens) : null;
-    if (!fault) return { status: 'pass' };
     return {
       status: 'fail',
-      message: `autocomplete="${element.getAttribute('autocomplete').trim()}" is not a valid autofill value: ${fault}. Browsers discard the whole value, so no purpose is exposed.`,
-      fix: 'Use one field name from the HTML autofill list, optionally preceded by section-*, then shipping or billing, and (for tel, email and impp only) a contact type, e.g. autocomplete="shipping tel" or autocomplete="home email".',
+      message: `${problem}. 1.3.5 covers fields that collect information about the user, which is what an autocomplete attribute is for; if this field collects nothing about the user, the criterion does not apply and this finding can be dismissed.`,
+      fix,
     };
   },
 };

package/engine/rules/wcag/1.3.6-region-purpose.js

@@ -0,0 +1,35 @@
+// WCAG SC 1.3.6 Identify Purpose (Level AAA)
+// "The purpose of user interface components, icons, and regions can be
+// programmatically determined." Its sufficient technique for regions is
+// ARIA11, landmarks; the purpose of components and icons has no DOM-visible
+// technique at all (personalization semantics never shipped), so that half
+// of the criterion stays with a person. What a page can show is the
+// regions half: a document with no landmark whatsoever has identified the
+// purpose of none of its regions. That is one question per page, asked
+// once, and it never asserts, because the criterion lists other routes
+// (microdata, other programmatic means) the DOM does not reveal.
+//
+// Pages that HAVE landmarks pass here; stray content outside them is the
+// best-practice region rule's finding, which stays opt-in because A and AA
+// never require landmarks. This rule is the AAA criterion's own question.
+import { LANDMARK } from '../best-practice/region.js';
+
+export default {
+  id: 'region-purpose',
+  name: 'Regions with a purpose',
+  impact: 'moderate',
+  tags: ['wcag21aaa', 'wcag136'],
+  help: 'The purpose of page regions should be programmatically determinable (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/identify-purpose.html',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    const doc = element.ownerDocument;
+    if (doc.querySelector(LANDMARK)) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: 'This page declares no landmark regions (no main, nav, header, footer, aside, search or labelled region), so the purpose of its regions is not exposed to assistive technology or personalisation tools. 1.3.6 (AAA) lists landmarks as the way to identify regions; the purpose of components and icons still needs a person to check.',
+      fix: 'Wrap the page\'s regions in <main>, <nav>, <header>, <footer>, <aside> and labelled <section> elements (or the matching ARIA roles).',
+    };
+  },
+};

package/engine/rules/wcag/1.4.1-link-in-text-block.js

@@ -176,7 +176,14 @@ export default {
       if (sidePaints(s, 'Bottom')) return { status: 'pass' };
       if (boxShadowPaints(s.boxShadow)) return { status: 'pass' };
       const ownBackground = parseColor(s.backgroundColor);
-      if (ownBackground && ownBackground.a > 0) return { status: 'pass' };
+      if (ownBackground && ownBackground.a > 0) {
+        const surroundings = effectiveBackground(parent);
+        if (!surroundings) unclear = true;
+        else {
+          const shown = composite(ownBackground, surroundings);
+          if (['r', 'g', 'b'].some((channel) => Math.round(shown[channel]) !== Math.round(surroundings[channel]))) return { status: 'pass' };
+        }
+      }
       const painted = backgroundImagePaints(s, el.getBoundingClientRect()); // gradient/image underline technique
       if (painted === 'yes') return { status: 'pass' };
       if (painted === 'unclear') unclear = true;
@@ -205,8 +212,17 @@ export default {
     const sizeStep = Math.max(...textBearers.map((s) => Math.abs((parseFloat(s.fontSize) || parentSize) - parentSize)));
     const sizeCue = sizeStep >= 2 && sizeStep / parentSize >= 0.1;
 
-    let linkColor = parseColor(style.color);
-    let textColor = parseColor(parentStyle.color);
+    // A wrapper's colour need not paint any glyphs: inline spans commonly
+    // override it. Compare actual own-text bearers, and review multicolour
+    // text rather than attributing an unpainted wrapper colour to it.
+    const glyphColours = cueBearers.filter(({ el }) => ownText(el))
+      .map(({ s }) => s.webkitTextFillColor || s.color);
+    const distinctColours = [...new Set(glyphColours)];
+    if (distinctColours.length > 1) {
+      return { status: 'incomplete', message: 'This link presents text in several colours without a detected non-colour cue. Check that each part is distinguishable from the surrounding text.' };
+    }
+    let linkColor = parseColor(distinctColours[0] || style.webkitTextFillColor || style.color);
+    let textColor = parseColor(parentStyle.webkitTextFillColor || parentStyle.color);
     if (!linkColor || !textColor) return { status: 'pass' };
     // 2026-08-25 overnight audit: a translucent colour is presented
     // composited over its backdrop (rgba(0,0,0,.3) in black prose on white

package/engine/rules/wcag/1.4.10-reflow.js

@@ -1,8 +1,8 @@
 // WCAG SC 1.4.10 Reflow (Level AA)
 // The full test renders at 320 CSS px; an audit runs at whatever viewport
 // the page is in. What IS knowable here: content that already forces
-// two-dimensional scrolling at the current width will only be worse at
-// 320px. Abstain-over-assert: this flags, it never fails — tables, maps,
+// horizontal scrolling at the current width is a candidate to check at
+// 320px; responsive breakpoints can change the layout. Abstain-over-assert: this flags, it never fails — tables, maps,
 // and images are exempt content the geometry can't distinguish.
 export default {
   id: 'reflow',
@@ -20,7 +20,7 @@ export default {
     if (overflow <= 1) return { status: 'pass' };
     return {
       status: 'incomplete',
-      message: `The page already scrolls horizontally by ${Math.round(overflow)}px at the current viewport — at the 320px reflow breakpoint it will be worse. Verify content reflows at 320 CSS px width (data tables, maps and images are exempt).`,
+      message: `The page already scrolls horizontally by ${Math.round(overflow)}px at the current viewport. Verify content reflows at 320 CSS px width (data tables, maps and images are exempt).`,
     };
   },
 };

package/engine/rules/wcag/1.4.11-non-text-contrast.js

@@ -114,7 +114,15 @@ export default {
       const wrapperHasBorder = ['Top', 'Right', 'Bottom', 'Left'].some((side) =>
         parseFloat(wrapperStyle[`border${side}Width`]) > 0 && wrapperStyle[`border${side}Style`] !== 'none'
         && (parseColor(wrapperStyle[`border${side}Color`])?.a ?? 0) > 0);
-      if (wrapperHasBorder) return { status: 'pass' };
+      if (wrapperHasBorder) {
+        const around = effectiveBackground(wrapper.parentElement ?? wrapper);
+        const contrastingBorder = around && ['Top', 'Right', 'Bottom', 'Left'].some((side) => {
+          if (!(parseFloat(wrapperStyle[`border${side}Width`]) > 0) || wrapperStyle[`border${side}Style`] === 'none') return false;
+          const colour = parseColor(wrapperStyle[`border${side}Color`]);
+          return colour && contrastRatio(composite(colour, around), around) >= 3;
+        });
+        if (contrastingBorder) return { status: 'pass' };
+      }
       const wrapperFill = parseColor(wrapperStyle.backgroundColor);
       if (wrapperFill && wrapperFill.a >= 1) {
         const around = effectiveBackground(wrapper.parentElement ?? wrapper);

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

@@ -44,7 +44,11 @@ export default {
     // ruinous on 200k-node single-page specs, whose plain flowing text is
     // also the least likely content on the web to clip. Past a scale where
     // the probe's cost dwarfs its yield, abstain wholesale.
-    if (elements.length > 20_000) return elements.map(() => ({ status: 'pass' }));
+    if (elements.length > 20_000) {
+      return elements.map((_, index) => index === 0
+        ? { status: 'incomplete', message: `The text-spacing probe was not run because this page has ${elements.length} candidate elements, exceeding its 20,000-element budget. Check the page with the WCAG spacing overrides applied.` }
+        : { status: 'skipped' });
+    }
     // Only containers that hide overflow and hold text can lose content.
     // Collapsed containers (accordion panels at height 0) show nothing —
     // there is no visible text for the override to clip.
@@ -64,13 +68,22 @@ export default {
     probe.dataset.pourAudit = 'probe';
     probe.textContent = override(doc.documentElement.scrollHeight);
     doc.documentElement.append(probe);
+    // Document selectors cannot cross a shadow boundary. Each candidate
+    // root receives the same override so the measured text is really probed.
+    const probes = [probe];
+    for (const root of new Set(candidates.filter(Boolean).map((element) => element.getRootNode()))) {
+      if (root === doc || !root.host) continue;
+      const scoped = probe.cloneNode(true);
+      root.append(scoped);
+      probes.push(scoped);
+    }
     let after;
     try {
       // Force the reflow the measurements depend on.
       void doc.documentElement.offsetHeight;
       after = candidates.map((element) => element && clipped(element));
     } finally {
-      probe.remove();
+      for (const applied of probes) applied.remove();
       // The audit must never move the page: put the scroll back exactly
       // where the user had it, after the removal's own reflow settles.
       void doc.documentElement.offsetHeight;

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

@@ -6,7 +6,7 @@ import {
   opacityAnimating, restingOpacity, mediaRects, inZeroClipSubtree,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
-  showRatio, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors, BOLD_WEIGHT } from '../../lib/contrast.js';
+  showRatio, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors, BOLD_WEIGHT, hasPaintEffects, isolatedBlendBackdrop } from '../../lib/contrast.js';
 
 /** The first url() among a background-image list's layers, or null. */
 const firstLayerUrl = (css) => splitBackgroundLayers(css ?? '').map(backgroundLayerUrl).find(Boolean) ?? null;
@@ -297,7 +297,7 @@ async function sampledVerdict(source, foreground, required, doc, overlays = [],
   let what = 'image';
   const grid = sampleGridFor(extent);
   if (source.tagName === 'IMG') {
-    range = await imageLuminanceRange(source.currentSrc || source.src, overlays, grid);
+    range = await imageLuminanceRange(source.currentSrc || source.src, overlays, grid, under);
   } else {
     const css = source.css ?? getComputedStyle(source).backgroundImage;
     if (!css || css === 'none') return null;
@@ -314,7 +314,7 @@ async function sampledVerdict(source, foreground, required, doc, overlays = [],
     if (url) {
       let absolute;
       try { absolute = new URL(url, doc.baseURI).href; } catch { return null; }
-      range = await imageLuminanceRange(absolute, overlays, grid);
+      range = await imageLuminanceRange(absolute, overlays, grid, under);
     } else if (layer.includes('gradient(')) {
       what = 'gradient';
       const stops = gradientStops(layer);
@@ -539,6 +539,10 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     const fill = parseColor(style.webkitTextFillColor);
     const clipsText = /\btext\b/.test(style.webkitBackgroundClip ?? '') || /\btext\b/.test(style.backgroundClip ?? '');
     if (clipsText) {
+    if (hasPaintEffects(styleSource)) {
+      return { status: 'incomplete', message: 'A filter or blend mode changes the colours presented by this text and its background. Check the resulting contrast by eye.' };
+    }
+
       const behind = effectiveBackground(element.parentElement ?? element);
       const fgRange = style.backgroundImage !== 'none'
         ? sampledGradientRange(splitBackgroundLayers(style.backgroundImage)[0] ?? '') : null;
@@ -559,6 +563,38 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // Visually hidden text (sr-only, image replacement) has no visual
     // presentation for contrast to apply to — screen readers still read it.
     if (textVisuallyHidden(element, style, foreground)) return { status: 'pass' };
+    // A leaf's own multiply blend over flat paint is exact per Compositing
+    // Level 1: B(Cb, Cs) = Cb * Cs. Keep groups, filters and generated paint
+    // outside this narrow path; its backdrop is resolved below as usual.
+    const ownMultiply = style.mixBlendMode === 'multiply'
+      && styleSource === element && !element.children.length && !element.shadowRoot
+      && parseColor(style.backgroundColor)?.a === 0 && style.backgroundImage === 'none'
+      && style.filter === 'none' && (!style.backdropFilter || style.backdropFilter === 'none')
+      && (!style.textShadow || style.textShadow === 'none')
+      && !hasPaintEffects(element.assignedSlot ?? element.parentElement ?? element.getRootNode()?.host)
+      && !isolatedBlendBackdrop(element.assignedSlot ?? element.parentElement ?? element.getRootNode()?.host)
+      && !['::before', '::after'].some((pseudo) => {
+        const pseudoStyle = getComputedStyle(element, pseudo);
+        const content = pseudoStyle.content;
+        // U+2060 only controls line breaking and has no glyph. A plain
+        // inline joiner with no independent box paint does not add a
+        // painted source to this leaf's multiply group.
+        const bareJoiner = (content === '"\u2060"' || content === "'\u2060'")
+          && pseudoStyle.display === 'inline' && pseudoStyle.position === 'static'
+          && pseudoStyle.cssFloat === 'none'
+          && parseColor(pseudoStyle.backgroundColor)?.a === 0
+          && ['backgroundImage', 'boxShadow', 'textShadow', 'transform', 'filter', 'backdropFilter', 'maskImage', 'webkitMaskImage']
+            .every((key) => !pseudoStyle[key] || pseudoStyle[key] === 'none')
+          && ['Top', 'Right', 'Bottom', 'Left'].every((side) =>
+            parseFloat(pseudoStyle[`padding${side}`]) === 0 && parseFloat(pseudoStyle[`border${side}Width`]) === 0)
+          && pseudoStyle.outlineStyle === 'none'
+          && (!pseudoStyle.mixBlendMode || pseudoStyle.mixBlendMode === 'normal');
+        if (bareJoiner) return false;
+        return content && content !== 'none' && content !== 'normal' && content !== '""';
+      });
+    if (hasPaintEffects(styleSource) && !ownMultiply) {
+      return { status: 'incomplete', message: 'A filter or blend mode changes the colours presented by this text and its background. Check the resulting contrast by eye.' };
+    }
     if (!foreground) {
       return { status: 'incomplete', message: 'The text colour could not be parsed — check contrast by eye.' };
     }
@@ -582,6 +618,26 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
       .map(({ pseudo, color, style: pseudoStyle }) => ({
         origin: pseudo, color, required: isLargeText(pseudoStyle) ? thresholds.large : thresholds.normal,
       }));
+    // A first-line override can paint every glyph. With no element
+    // descendants and one actual line, the base colour paints nothing and
+    // must not manufacture a failure. Wrapped text retains its base colour.
+    let basePaints = true;
+    if (!element.childElementCount && alternates.some((a) => a.origin === '::first-line')) {
+      const range = doc.createRange();
+      range.selectNodeContents(element);
+      const lines = [...range.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+      if (lines.length && lines.every((r) => Math.abs(r.top - lines[0].top) < 1)) {
+        const generated = ['::before', '::after'].some((pseudo) => {
+          const generatedStyle = getComputedStyle(element, pseudo);
+          return generatedStyle.display !== 'none'
+            && !['none', 'normal'].includes(generatedStyle.content);
+        });
+        // Range does not include generated content. A generated block can
+        // occupy the first formatted line while the own text sits below it.
+        if (generated) return { status: 'incomplete', message: 'Generated content may occupy this element’s first line, so the colours that actually paint its text cannot be identified from text ranges alone. Check contrast by eye.' };
+        basePaints = false;
+      }
+    }
     const worstCandidate = (candidates, backdrop) => candidates.reduce((worst, candidate) => {
       const shown = candidate.color.a < 1 ? composite(candidate.color, backdrop) : candidate.color;
       const margin = contrastRatio(shown, backdrop) / candidate.required;
@@ -589,7 +645,7 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     }, null);
     if (alternates.length) {
       const estimate = effectiveBackground(styleSource) ?? { r: 255, g: 255, b: 255, a: 1 };
-      const pick = worstCandidate([{ origin: null, color: foreground, required }, ...alternates], estimate);
+      const pick = worstCandidate([...(basePaints ? [{ origin: null, color: foreground, required }] : []), ...alternates], estimate);
       foreground = pick.color;
       required = pick.required;
       foregroundOrigin = pick.origin;
@@ -604,6 +660,9 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // Near-zero resting opacity means the text isn't visually presented.
     const opacity = opacityAnimating(element) ? restingOpacity(element) : cumulativeOpacity(element);
     if (opacity < 0.05) return { status: 'pass' };
+    if (ownMultiply && (opacity < 1 || alternates.length)) {
+      return { status: 'incomplete', message: 'This text blends as a group or uses additional text paint. Check its presented contrast by eye.' };
+    }
     if (opacity < 1) {
       // Group opacity with a background INSIDE the group: the browser blends
       // text and background together over what lies behind the carrier, so
@@ -696,6 +755,7 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // images (external-link arrows etc.) don't affect the text's contrast.
     const imageSource = backgroundImageSource(element);
     if (imageSource) {
+      if (ownMultiply) return { status: 'incomplete', message: 'This text multiplies against an image or gradient. Its contrast depends on the pixels behind each glyph; check it by eye.' };
       const { relation, intrinsic, dimensionless, isGradient, sizedSmall, paint } = await imageVsText(imageSource, element, doc);
       if (relation !== 'clear') {
         // imageSource.overlays are the translucent layers painted between the
@@ -761,6 +821,9 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // hero panels, overlay scrims) that the ancestor walk cannot — instead
     // of merely flagging them for a human.
     const painted = paintedBackdrop(element);
+    if (ownMultiply && painted?.image) {
+      return { status: 'incomplete', message: 'This text multiplies against image paint. Check its presented contrast by eye.' };
+    }
     // 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
@@ -801,6 +864,9 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // 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);
+    if (ownMultiply && pseudoResolved) {
+      return { status: 'incomplete', message: 'Pseudo-element paint affects the backdrop of this blended text. Check its presented contrast by eye.' };
+    }
     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
@@ -959,12 +1025,18 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     if (alternates.length) {
       const dim = (color) => (opacity < 1 ? { ...color, a: color.a * opacity } : color);
       const base = { origin: null, color: dim(baseForeground), required: baseRequired };
-      const pick = worstCandidate([base, ...alternates.map((a) => ({ ...a, color: dim(a.color) }))], background);
+      const pick = worstCandidate([...(basePaints ? [base] : []), ...alternates.map((a) => ({ ...a, color: dim(a.color) }))], background);
       foreground = pick.color;
       required = pick.required;
       foregroundOrigin = pick.origin;
     }
     // Semi-transparent text is really text-colour blended into the background.
+    if (ownMultiply) {
+      foreground = { ...foreground,
+        r: foreground.r * background.r / 255,
+        g: foreground.g * background.g / 255,
+        b: foreground.b * background.b / 255 };
+    }
     if (foreground.a < 1) foreground = composite(foreground, background);
 
     // The scroll-independent hazard bracket for UNVERIFIED backgrounds:
@@ -1008,7 +1080,7 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
         (!blindOnly || hitTestBlind) && near(rect)
         && !panel.contains(element) && !element.contains(panel)
         && textIntersects(element, rect)
-        && (contrastRatio(foreground, color) >= required) !== (direction === 'pass'));
+        && (ownMultiply || (contrastRatio(foreground, color) >= required) !== (direction === 'pass')));
       if (flipping) {
         return {
           status: 'incomplete',
@@ -1046,7 +1118,7 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
               if (!paint || paint.a < 1) continue;
               const siblingRect = sibling.getBoundingClientRect();
               if (siblingRect.width < 24 || siblingRect.height < 12 || !near(siblingRect) || !textIntersects(element, siblingRect)) continue;
-              if ((contrastRatio(foreground, paint) >= required) !== (direction === 'pass')) {
+              if (ownMultiply || (contrastRatio(foreground, paint) >= required) !== (direction === 'pass')) {
                 return {
                   status: 'incomplete',
                   message: 'This text is positioned over a coloured box that isn’t its DOM ancestor, so its real background is ambiguous — check contrast by eye.',