pour-engine 1.40.0 → 1.41.0

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

@@ -5,6 +5,7 @@
 import {
   parseColor, contrastRatio, composite, effectiveBackground, isLargeText,
   backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity, showRatio,
+  hasPaintEffects, opacityGroupPaint, splitBackgroundLayers, sampledGradientRange,
 } from '../../lib/contrast.js';
 
 export default {
@@ -56,10 +57,26 @@ export default {
     // far less contrast than its declared colours suggest.
     const opacity = opacityAnimating(element) ? restingOpacity(element) : cumulativeOpacity(element);
     if (opacity < 0.05) return { status: 'pass' };
+    if (hasPaintEffects(element)) {
+      return { status: 'incomplete', message: 'A filter or blend mode changes the colours presented inside this field. Check the resulting text contrast by eye.' };
+    }
     // The control's own background wins; else whatever shows through it.
     const own = parseColor(style.backgroundColor);
     let background;
-    if (own && own.a >= 1) {
+    if (style.backgroundImage !== 'none') {
+      const layers = splitBackgroundLayers(style.backgroundImage);
+      const range = layers.length === 1 && layers[0].includes('gradient(')
+        ? sampledGradientRange(layers[0]) : null;
+      // A constant opaque gradient has exactly one painted background.
+      // Other image paint needs spatial sampling, not its fallback colour.
+      const fullBox = /^(auto|auto auto)$/.test(style.backgroundSize)
+        && style.backgroundPosition === '0% 0%'
+        && ['repeat', 'no-repeat'].includes(style.backgroundRepeat);
+      if (!range || range.min !== range.max || opacity < 1 || !fullBox) {
+        return { status: 'incomplete', message: 'An image or gradient paints this field background. Check its text against the pixels behind it.' };
+      }
+      background = range.minColor;
+    } else if (own && own.a >= 1) {
       background = own;
     } else {
       // An image or gradient painted under a see-through control is a
@@ -73,18 +90,27 @@ export default {
         };
       }
       const behind = effectiveBackground(element);
-      background = behind && own && own.a > 0 ? composite(own, behind) : behind;
+      background = behind; // effectiveBackground already composites the field fill
     }
     if (!background) {
       return { status: 'incomplete', message: 'The control’s background could not be determined — check its text contrast by eye.' };
     }
     const required = isLargeText(style) ? 3 : 4.5;
 
+    let unresolvedGroup = false;
     const judge = (color, what, ownOpacity = 1) => {
       const parsed = parseColor(color);
       if (!parsed || parsed.a === 0) return null;
       // Same treatment the main rule gives faded text: what reaches the eye
       // is the declared colour thinned by the opacity it is painted at.
+      if (opacity < 1) {
+        const group = opacityGroupPaint(element, { ...parsed, a: parsed.a * ownOpacity });
+        if (group?.unresolved) { unresolvedGroup = true; return null; }
+        if (group) {
+          const ratio = contrastRatio(group.foreground, group.background);
+          return ratio >= required ? null : { what, ratio };
+        }
+      }
       const painted = opacity * ownOpacity;
       const faded = painted < 1 ? { ...parsed, a: parsed.a * painted } : parsed;
       const fg = faded.a < 1 ? composite(faded, background) : faded;
@@ -94,16 +120,18 @@ export default {
     };
 
     const failures = [];
-    const valueVerdict = judge(style.color, 'value text');
+    const valueVerdict = judge(style.webkitTextFillColor || style.color, 'value text');
     if (valueVerdict) failures.push(valueVerdict);
     // Placeholder text is real text users must read; browsers expose its
-    // computed colour via the ::placeholder pseudo-element.
-    if (element.getAttribute('placeholder')?.trim()) {
+    // computed colour via the ::placeholder pseudo-element. Selectors 4
+    // defines :placeholder-shown for controls actually showing that text;
+    // a populated field's unpainted hint must not create a violation.
+    if (element.getAttribute('placeholder')?.trim() && element.matches(':placeholder-shown')) {
       let placeholderColor = null;
       let placeholderOpacity = 1;
       try {
         const placeholderStyle = getComputedStyle(element, '::placeholder');
-        placeholderColor = placeholderStyle.color;
+        placeholderColor = placeholderStyle.webkitTextFillColor || placeholderStyle.color;
         // ::placeholder { opacity: .3 } is a widespread idiom (framework
         // resets, Firefox's own UA default of 0.54), and the criterion is on
         // the visual presentation of the text, which is the faded colour.
@@ -117,6 +145,7 @@ export default {
         if (verdict) failures.push(verdict);
       }
     }
+    if (unresolvedGroup) return { status: 'incomplete', message: 'The field and its text fade together over an unresolved background. Check the presented text contrast by eye.' };
     if (!failures.length) return { status: 'pass' };
     const worst = failures.sort((a, b) => a.ratio - b.ratio)[0];
     return {

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

@@ -20,10 +20,15 @@ export default {
     const maxScale = content.match(/maximum-scale\s*=\s*([\d.]+)/i);
     const cappedZoom = maxScale && parseFloat(maxScale[1]) < 2;
     if (!disablesZoom && !cappedZoom) return { status: 'pass' };
+    // Asserted the way ACT rule b4f0c3 asserts it, under its assumption that
+    // the page provides no other way to enlarge the text (technique G178).
+    // The message names that assumption so a reviewer who knows the page
+    // has its own text-size control can dismiss the finding.
+    // https://www.w3.org/WAI/standards-guidelines/act/rules/b4f0c3/
     return {
       status: 'fail',
-      message: 'This viewport meta tag stops low-vision users from zooming the page.',
-      fix: 'Remove user-scalable=no and any maximum-scale below 2 from the viewport meta tag.',
+      message: 'This viewport meta tag stops users zooming the page, so text cannot be enlarged with the browser. 1.4.4 is met only if the page provides its own control that enlarges all text to 200% (technique G178); this finding assumes it does not, since the tag cannot show it.',
+      fix: 'Remove user-scalable=no and any maximum-scale below 2 from the viewport meta tag. If the page has its own text-size control that reaches 200%, record that and dismiss this finding.',
     };
   },
 };

package/engine/rules/wcag/2.1.1-scrollable-region-focusable.js

@@ -92,13 +92,13 @@ export default {
     // An explicit negative tabindex is the author OPTING OUT of the tab
     // order, and the browser honours it: measured in Chrome 151, a scroller
     // with tabindex="-1" is skipped by Tab even though the same scroller
-    // without the attribute would be auto-focused. Nothing inside is
-    // tabbable either, so the overflowed content is unreachable by keyboard
-    // in every engine — assertable, not browser-dependent.
+    // without the attribute would be auto-focused. That does not prove
+    // keyboard inoperability: external controls may scroll the region or
+    // move focus into it programmatically.
     if (element.hasAttribute('tabindex')) {
       return {
-        status: 'fail',
-        message: 'This region scrolls, holds nothing tabbable, and its tabindex="-1" removes the region itself from the tab order — keyboard users cannot reach the overflowed content in any browser.',
+        status: 'incomplete',
+        message: 'This region scrolls, has no detected tabbable content and is removed from sequential focus by a negative tabindex. Check whether keyboard-operable controls elsewhere scroll it or move focus into it; without such a mechanism, the overflowed content may be unreachable.',
         fix: 'Change tabindex="-1" to tabindex="0" (plus role="region" and an aria-label describing it), or make something inside it tabbable.',
       };
     }

package/engine/rules/wcag/2.2.1-meta-refresh.js

@@ -80,10 +80,16 @@ export default {
     // 2.2.1 exempts a time limit "longer than 20 hours" — 20 hours exactly
     // is still inside the criterion.
     if (delay > 72000) return { status: 'pass' };
+    // Asserted the way ACT rule bc659a asserts it: a meta refresh gives the
+    // user no way to turn the limit off, adjust it or extend it, so the only
+    // escapes are the real-time and essential exceptions, which the tag
+    // cannot show either way. The message names that assumption so a
+    // reviewer who knows the page offers a control can dismiss the finding.
+    // https://www.w3.org/WAI/standards-guidelines/act/rules/bc659a/
     return {
       status: 'fail',
-      message: `The page refreshes/redirects after ${delay}s — slow readers lose their place (or the whole page) with no control.`,
-      fix: 'Remove the timed refresh; let users act in their own time.',
+      message: `The page refreshes or redirects itself after ${delay}s. Slow readers lose their place, or the whole page, and a meta refresh offers no way to turn that off, adjust it or extend it. 2.2.1 excuses a time limit only where it is part of a real-time event or essential; this finding assumes neither applies, since the tag cannot show it.`,
+      fix: 'Remove the timed refresh; let users act in their own time. If the page offers a control that turns the refresh off, or the refresh is essential, record that and dismiss this finding.',
     };
   },
 };

package/engine/rules/wcag/2.2.2-pause-stop-hide.js

@@ -6,8 +6,8 @@
 //
 // Two shapes are checkable, and they need different verdicts.
 //
-// <marquee> and <blink> exist only to move, ship no control of their own,
-// and are obsolete: a definite failure.
+// Legacy markup is not proof of motion: blink has no native animation in
+// modern browsers, and a marquee may be stopped or controlled by script.
 //
 // A CSS animation set to repeat for ever is the modern ticker. Clauses 1
 // and 2 are settled by the CSS itself — it starts with the page and never
@@ -117,15 +117,15 @@ export default {
     if (!elements.length) return [];
     const moving = endlesslyMoving(elements[0].ownerDocument);
     return elements.map((element) => {
-      if (element.tagName === 'MARQUEE' || element.tagName === 'BLINK') {
+      if (element.tagName === 'MARQUEE') {
         // scrollamount="0" is the documented way to ship a <marquee> that
         // doesn't actually move.
         if (element.tagName === 'MARQUEE' && element.getAttribute('scrollamount') === '0') {
           return { status: 'pass' };
         }
         return {
-          status: 'fail',
-          message: `<${element.tagName.toLowerCase()}> scrolls or blinks with no way to pause it, which is unusable for people with attention or vestibular conditions.`,
+          status: 'incomplete',
+          message: 'This marquee can scroll content. Check whether it actually starts automatically, continues for more than five seconds alongside other content, and has a working pause, stop or hide mechanism. The element alone does not establish those conditions.',
           fix: 'Replace it with static content, or a CSS animation with a pause control that honours prefers-reduced-motion.',
         };
       }

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

@@ -80,8 +80,8 @@ export default {
     const linkCount = roots.reduce((n, root) => n + (root.querySelectorAll?.('a[href], button').length ?? 0), 0);
     if (linkCount < 4) return { status: 'pass' };
     return {
-      status: 'fail',
-      message: `This page has ${linkCount} links and buttons but no landmark, heading, skip link, or titled frame — keyboard and screen-reader users must go through the whole header and nav to reach anything.`,
+      status: 'incomplete',
+      message: `This page has ${linkCount} links and buttons but no detected landmark, heading, skip link or titled frame. Check whether it contains blocks repeated on other pages and, if so, whether a mechanism lets users bypass them. A single page cannot establish repetition.`,
       fix: 'Add a skip link like <a href="#content">Skip to content</a>, wrap primary content in <main>, or structure the page with headings.',
     };
   },

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

@@ -3,18 +3,17 @@
 // merely PRESENT satisfies the markup, not the criterion, so the two
 // well-known undescriptive shapes are checked as well.
 //
-// Tier one, failed: strings that are a stand-in under every reading.
-// "Untitled Document" is what an editor writes when the author wrote
-// nothing, and no page is ever about that.
+// Familiar template strings are review candidates, not proof of a missing
+// topic: a document can genuinely describe the HTML document title or an
+// artwork named Untitled 1.
 // Tier two, sent to a human: single generic words and framework scaffold
 // defaults. Almost always a leftover, but a gallery page really can be about
 // an artwork called "Untitled", and "Example Domain" really is the subject
 // of example.com. Those are somebody's call to make, not the engine's.
 // "New document", "New page" and "New tab" sit in tier two as well: a
 // document editor's creation screen, a wiki's new-page form or a
-// browser-style app's new-tab page is about exactly that, so only the
-// numbered editor default ("New Page 1", F25's example) is a certain
-// placeholder (2026-08-25 overnight audit).
+// browser-style app's new-tab page is about exactly that. Even numbered
+// editor-style titles remain a question about the actual subject.
 //
 // 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
@@ -63,8 +62,8 @@ export default {
     const normalized = title.replace(/\s+/g, ' ').toLowerCase();
     if (PLACEHOLDER.has(normalized) || /^(?:untitled|new (?:document|page|tab))[\s-]*\d+$/.test(normalized)) {
       return {
-        status: 'fail',
-        message: `“${title}” is a placeholder left by an editor or template. It gives no topic and no purpose, so a screen reader announces nothing useful when the page loads, and a row of open tabs, bookmarks or history entries becomes impossible to tell apart.`,
+        status: 'incomplete',
+        message: `“${title}” resembles a template title. Check whether it describes this page's actual topic or purpose; the same words can also be a legitimate subject or name.`,
         fix: 'Put this page\'s own subject in the title first, then the site name.',
       };
     }

package/engine/rules/wcag/2.4.4-link-text-generic.js

@@ -13,11 +13,9 @@
 //               it sits in. A "Read more" under a headline naming the
 //               article is a judgment call about whether that context really
 //               reaches the user, so this REVIEWS. It never asserts.
-//   2.4.9 (AAA) purpose must come from the link text ALONE, with the only
-//               exception being links whose purpose "would be ambiguous to
-//               users in general". A link named nothing but "Read more" is
-//               ambiguous to everyone, which is the exception failing to
-//               apply rather than saving it, so this FAILS.
+//   2.4.9 (AAA) requires a mechanism for purpose to be available from link
+//               text alone. A page may let users expand its link names,
+//               so a generic name in this snapshot still needs review.
 //
 // Judged on the ACCESSIBLE NAME, not the text content: a link written as
 // <a href="…" aria-label="Read more about the budget">Read more</a> is
@@ -31,6 +29,8 @@
 // normalizeName below): apostrophes become spaces, so "plus d informations"
 // is how "plus d'informations" — straight or typographic — must be listed.
 
+import { effectiveRole, implicitRole } from '../../lib/roles.js';
+
 const GENERIC = new Set([
   // English
   'read more', 'read more about this', 'more', 'much more', 'learn more',
@@ -83,6 +83,7 @@ export function createLinkPurposeRule({ id, impact, tags, help, helpUrl, verdict
     // link-name's finding, not this one.
     selector: 'a[href], [role="link"]',
     evaluate(element, { accessibleName }) {
+      if ((effectiveRole(element) ?? implicitRole(element)) !== 'link') return { status: 'pass' };
       const name = accessibleName(element);
       if (!name) return { status: 'pass' }; // nameless: link-name reports it
       const normalized = normalizeName(name);

package/engine/rules/wcag/2.4.9-link-text-generic-only.js

@@ -4,28 +4,13 @@
 // threshold: the link text ALONE has to identify the purpose, and context
 // is not allowed to make up the difference.
 //
-// This one asserts where the AA rule reviews. The criterion's only escape is
-// links "where the purpose of the link would be ambiguous to users in
-// general", and a link named nothing but "Read more" is ambiguous to
-// everyone — which is the exception failing to apply rather than rescuing
-// it. Nothing about the surrounding page can change that reading, so there
-// is nothing here for a human to settle.
+// The criterion allows a mechanism that expands link names. F84 requires
+// checking that no such mechanism exists, which a name-only snapshot cannot
+// prove. Semantic ambiguity and alternative presentation remain review.
 //
-// Two matches stay in the review lane because the failure is not provable
-// (2026-08-25 corpus adjudication):
-//   · a name wrapped in a paired bracket or quote — "<details>" is a code
-//     term that names its destination exactly (one-sided decoration like
-//     python.org's CSS-generated ">>>More" prompt still asserts);
-//   · a name that is exactly "go" — every corpus hit was a brand logo
-//     ("Go" is the language's name), and a brand name identifies the link.
-//
-// A third, beside "go" (2026-08-25 overnight audit): the French entries
-// "plus" and "suite" are ordinary English words and, more to the point,
-// common English plan and product names (a "Plus" tier, a "Suite"). A
-// pricing link named "Plus" identifies its destination the way the Go logo
-// does, so outside a page declared French they review rather than assert.
-// On a link whose closest lang is French the generic reading ("more",
-// "continued") is the only one and the assertion stands.
+// The review wording distinguishes recognizable proper-name ambiguities
+// (Go, Plus, Suite and quoted code terms) from ordinary generic phrases.
+// Neither branch treats a phrase-list match as semantic proof.
 import { createLinkPurposeRule } from './2.4.4-link-text-generic.js';
 
 const FRENCH_ONLY_ENGLISH_NAMES = new Set(['plus', 'suite']);
@@ -50,8 +35,8 @@ export default createLinkPurposeRule({
       fix: 'If the name really is generic here, put the destination in the link text, e.g. "Read more about the 2026 budget".',
     };
     return {
-      status: 'fail',
-      message: `“${name}” gives no purpose on its own. 2.4.9 asks that the link text alone identify where a link goes, without relying on the sentence or heading around it, so anyone reading the page's links as a list can tell them apart.`,
+      status: 'incomplete',
+      message: `“${name}” appears generic when read alone. Check whether it identifies the destination in this context or whether a mechanism makes the link text descriptive. 2.4.9 permits such a mechanism; the initial link name alone cannot establish a failure.`,
       fix: 'Name the destination in the link text, e.g. "Read more about the 2026 budget".',
     };
   },