pour-engine 1.3.1 → 1.4.0

package/config/project.config.js

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

package/engine/README.md

@@ -102,14 +102,15 @@ pour engine therefore reports on **every** in-scope criterion, one of two ways:
 1. **Automated/partial** — the rules in `rules/`.
 2. **Manual review** — every audit's results include `manualReview`: the
    in-scope criteria (filtered by the requested WCAG version and level)
-   that automation can't judge, rendered as a checklist in the extension.
+   that automation can't judge, for a host to render however it wants.
 
 Nothing in the spec is silently skipped — that claim is the product.
 
 ## Honest current state
 
-72 rules, hardened on real sites and the `testbeds/` pages. Known gaps:
-shadow DOM and iframe traversal, the full accname spec (ours is a close
-approximation), and the language subtag registry (BCP 47 shape check only).
-Grow it rule by rule; the test beds' `expect:` annotations are the
-regression suite.
+72 rules, hardened on real sites and the `testbeds/` pages. Audits walk into
+open shadow roots (targets come back as `host >>> inner` selector chains);
+iframe traversal is the host's job, and the extension does it. Known gaps:
+the full accname spec (ours is a close approximation) and the language
+subtag registry (BCP 47 shape check only). Grow it rule by rule; the test
+beds' `expect:` annotations and the spec cases are the regression suite.

package/engine/index.js

@@ -1,4 +1,4 @@
-// DY Engine runner: evaluates every applicable rule against the page and
+// Engine runner: evaluates every applicable rule against the page and
 // returns structured results (violations / passes / incomplete /
 // inapplicable, plus the manual-review criteria and per-rule timings).
 import config from '../config/project.config.js';

package/engine/lib/contrast.js

@@ -835,6 +835,11 @@ export function imageLuminanceRange(url, overlays = []) {
         const data = ctx.getImageData(0, 0, size, size).data;
         let min = 1;
         let max = 0;
+        // The colours at those extremes, kept for the same reason the
+        // gradient range keeps them: translucent text blends with the actual
+        // pixels, and a luminance cannot be un-gamma'd back into an rgb.
+        let minColor = null;
+        let maxColor = null;
         let opaquePixels = 0;
         for (let i = 0; i < data.length; i += 4) {
           if (data[i + 3] < 128) continue; // mostly-transparent pixels reveal what's beneath — unknowable
@@ -843,9 +848,10 @@ export function imageLuminanceRange(url, overlays = []) {
           // and the text before measuring: a photo under a 75% black scrim is
           // seen as the blend, never as the photo.
           const pixel = { r: data[i], g: data[i + 1], b: data[i + 2], a: 1 };
-          const l = luminance(overlays.length ? applyOverlays(pixel, overlays) : pixel);
-          if (l < min) min = l;
-          if (l > max) max = l;
+          const shown = overlays.length ? applyOverlays(pixel, overlays) : pixel;
+          const l = luminance(shown);
+          if (l < min) { min = l; minColor = shown; }
+          if (l > max) { max = l; maxColor = shown; }
         }
         // Not one opaque pixel: a spacer, a cleared sprite, or a decorative
         // layer left in place with nothing in it. It covers the background
@@ -862,7 +868,9 @@ export function imageLuminanceRange(url, overlays = []) {
           resolve({ transparent: true, width: img.naturalWidth, height: img.naturalHeight });
           return;
         }
-        resolve(min <= max ? { min, max, width: img.naturalWidth, height: img.naturalHeight } : null);
+        resolve(min <= max
+          ? { min, max, minColor, maxColor, width: img.naturalWidth, height: img.naturalHeight }
+          : null);
       } catch {
         resolve(null); // tainted canvas: cross-origin image without CORS headers
       }
@@ -921,8 +929,20 @@ export function backgroundImagePaintRect(element, intrinsic) {
 export function gradientLuminanceRange(backgroundImageCss, overlays = []) {
   const stops = (backgroundImageCss.match(/rgba?\([^)]+\)/g) ?? []).map(parseColor).filter(Boolean);
   if (!stops.length || stops.some((c) => c.a < 1)) return null; // translucent stops reveal what's beneath
-  const lums = stops.map((stop) => luminance(overlays.length ? applyOverlays(stop, overlays) : stop));
-  return { min: Math.min(...lums), max: Math.max(...lums) };
+  const composited = stops.map((stop) => (overlays.length ? applyOverlays(stop, overlays) : stop));
+  const lums = composited.map(luminance);
+  const min = Math.min(...lums);
+  const max = Math.max(...lums);
+  // The COLOURS at the extremes, not just their luminances: translucent text
+  // takes its presented colour from the pixels beneath, so bracketing that
+  // blend needs the actual rgb to composite against, and luminance alone
+  // cannot be un-gamma'd back into one.
+  return {
+    min,
+    max,
+    minColor: composited[lums.indexOf(min)],
+    maxColor: composited[lums.indexOf(max)],
+  };
 }
 
 /** Contrast ratio from two luminances. */

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

@@ -79,9 +79,14 @@ export default {
     }
     return {
       status: 'fail',
+      // The measured fact is the ratio against G183's threshold, and that is
+      // all this says. Naming a group who "can't see it" overclaims: a
+      // saturated red against near-white misses 3:1 on luminance while
+      // staying perfectly distinct to most people, including most red-green
+      // colour blindness, where the red darkens and the gap widens.
       message: ratio < 1.01
-        ? 'This link has no underline and the same colour as the surrounding text — sighted users can’t tell it’s a link.'
-        : `This link has no underline and only ${ratio.toFixed(2)}:1 colour difference from the surrounding text — colour-blind users can’t spot it.`,
+        ? 'This link has no underline and the same colour as the surrounding text, so there is nothing at all to mark it as a link.'
+        : `This link has no underline and only ${ratio.toFixed(2)}:1 colour difference from the surrounding text, below the 3:1 WCAG technique G183 asks for when colour is the only thing marking a link.`,
       fix: 'Underline links inside text (text-decoration: underline), or add a non-colour indicator.',
     };
   },

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

@@ -78,9 +78,26 @@ async function imageVsText(imageSource, element, doc) {
   // paint rect must not use it (icon SVGs would "cover" all the text).
   const dimensionless = !intrinsic || !intrinsic.width
     || (intrinsic.width === 300 && intrinsic.height === 150);
+  // A gradient has no intrinsic size and never will, but that is not the
+  // same as an unknown paint area: with the default background-size it fills
+  // its carrier's painting box exactly. Lumping it in with "we cannot tell
+  // how big this is" meant a gradient could never earn a definite verdict,
+  // however large the panel it covers. Its scale is the carrier's, unless
+  // background-size names something small, which is the one way a gradient
+  // really is icon-scale (a tiny repeated swatch).
+  const isGradient = !url && imageSource.css.includes('gradient(');
+  let sizedSmall = false;
+  if (isGradient) {
+    const size = getComputedStyle(imageSource.element).backgroundSize ?? '';
+    const px = [...size.matchAll(/(\d+(?:\.\d+)?)px/g)].map((m) => parseFloat(m[1]));
+    sizedSmall = px.length > 0 && px.every((value) => value <= 40);
+  }
   const paint = backgroundImagePaintRect(imageSource.element, dimensionless ? null : intrinsic);
-  if (!paint) return { relation: 'unknown', intrinsic, dimensionless };
-  return { relation: textIntersects(element, paint) ? 'under' : 'clear', intrinsic, dimensionless };
+  if (!paint) return { relation: 'unknown', intrinsic, dimensionless, isGradient, sizedSmall };
+  return {
+    relation: textIntersects(element, paint) ? 'under' : 'clear',
+    intrinsic, dimensionless, isGradient, sizedSmall,
+  };
 }
 
 /**
@@ -188,10 +205,31 @@ async function sampledVerdict(source, foreground, required, doc, overlays = [])
   // when the layer paints nothing.
   if (range?.transparent) return PAINTS_NOTHING;
   // Translucent text takes its presented colour from the very pixels
-  // beneath it — a luminance range of the backdrop cannot bracket the
-  // blend (dimmed white over a dark photo reads mid-grey, not white).
-  // Asserting either way from sampling would be a coin toss.
+  // 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.
+  //
+  // It CAN still be bracketed, by compositing the text over each end of the
+  // backdrop's range and judging each blend against the backdrop it was
+  // blended with. That bracket is sound in one direction only. Ratio is not
+  // monotonic in backdrop luminance — as the composited text passes through
+  // the backdrop's own luminance the ratio collapses toward 1:1 — so an
+  // interior point can be WORSE than both ends but never better. Both ends
+  // failing therefore proves the whole range fails; both ends passing proves
+  // nothing about the middle, and stays a human call.
   if (foreground.a < 1) {
+    const ends = [range?.minColor, range?.maxColor].filter(Boolean);
+    if (ends.length === 2) {
+      const ratios = ends.map((backdrop) => contrastRatio(composite(foreground, backdrop), backdrop));
+      if (ratios.every((ratio) => ratio < required)) {
+        const best = Math.max(...ratios);
+        return {
+          status: 'fail',
+          message: `This text is translucent, so it blends with what is behind it: against every part of that backdrop the blend reaches at best ${showRatio(best)}:1, below the ${required}:1 minimum.`,
+          fix: 'Raise the text opacity, change its colour, or put a solid layer between the text and the backdrop.',
+          data: { ratio: Number(showRatio(best)), required },
+        };
+      }
+    }
     return {
       status: 'incomplete',
       message: 'This text is translucent over an image or gradient, so its presented colour depends on the pixels beneath — contrast must be checked by eye.',
@@ -297,7 +335,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) {
-      const { relation, intrinsic, dimensionless } = await imageVsText(imageSource, element, doc);
+      const { relation, intrinsic, dimensionless, isGradient, sizedSmall } = await imageVsText(imageSource, element, doc);
       if (relation !== 'clear') {
         // imageSource.overlays are the translucent layers painted between the
         // image and this text (hero scrims, tint panels). Judging the raw
@@ -325,8 +363,10 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
           // inline link is still an icon). Only backdrop-scale images earn a
           // definite fail from sampling.
           const carrierBox = imageSource.element.getBoundingClientRect();
-          if (sampled?.status === 'fail'
-            && (dimensionless || (intrinsic.width <= 32 && intrinsic.height <= 32) || carrierBox.height <= 40)) {
+          const iconScale = isGradient
+            ? (sizedSmall || carrierBox.height <= 40)
+            : (dimensionless || (intrinsic.width <= 32 && intrinsic.height <= 32) || carrierBox.height <= 40);
+          if (sampled?.status === 'fail' && iconScale) {
             return {
               status: 'incomplete',
               message: 'A small background icon is painted on this element — if it sits beside the text rather than under it, judge the contrast against the plain background by eye.',

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

@@ -39,10 +39,26 @@ export default {
     // including content slotted in from the light DOM and content inside
     // open shadow roots (carousels built as web components).
     if (hasFocusableContent(element)) return { status: 'pass' };
+    // NOT a failure, because the browser may already have solved it.
+    //
+    // Chromium puts a scroll container in the tab order by itself when the
+    // container holds nothing focusable — and that condition is exactly the
+    // one this rule fires on, so in Chrome every element reaching this line
+    // IS keyboard reachable. Measured, not assumed: Chrome 151 tabs
+    // before → the scroller → after, while `element.tabIndex` still reports
+    // -1, which is why the check above cannot see it.
+    //
+    // It is not settled across engines though. MDN still advises the
+    // tabindex ("in some browsers, scrolling content areas are not
+    // keyboard-focusable"), and WebKit did not take focus here. So the
+    // honest report is the fact plus the split, not a verdict: asserting a
+    // Level A failure would be wrong for anyone on Chrome, and asserting a
+    // pass would be wrong for anyone who has to support the browsers that
+    // don't.
     return {
-      status: 'fail',
-      message: 'This region scrolls, but contains nothing focusable and isn’t focusable itself — keyboard users can never see the overflowed content.',
-      fix: 'Add tabindex="0" to the scrollable element (plus role="region" and an aria-label describing it).',
+      status: 'incomplete',
+      message: 'This region scrolls and holds nothing focusable, so reaching its overflowed content depends on the browser. Chromium gives such containers keyboard focus automatically; not every engine does. Tab to it in the browsers you support, and add tabindex="0" if it cannot be reached.',
+      fix: 'If you support browsers that do not focus scroll containers, add tabindex="0" (plus role="region" and an aria-label describing it).',
     };
   },
 };

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

@@ -38,6 +38,68 @@ function isHiddenFromPointer(element, rect) {
   return false;
 }
 
+/**
+ * Is this element the thing a click at that point would actually reach, or
+ * is something painted over it there?
+ *
+ * The spacing exception is about targets COMPETING for pointer space, and
+ * two targets that can never be hit at the same place do not compete. On any
+ * page with a fixed header, scrolling slides ordinary content underneath it:
+ * a footer link can end up geometrically 3px from a header button while
+ * being completely unclickable there, and counting it as a crowder invents a
+ * failure out of the scroll position. That was reported on pour's own site.
+ *
+ * Only asked about targets that are ALREADY crowding an undersized one, so
+ * the hit-test cost is paid on the handful of candidate failures rather than
+ * on every target of the page.
+ *
+ * Out-of-viewport points can't be hit-tested at all: elementsFromPoint is
+ * viewport-relative and returns nothing outside it. There the honest answer
+ * is "don't know", and don't-know must not silence a finding, so it counts
+ * as reachable.
+ */
+function reachableRects(element, rect) {
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  if (!win || typeof doc.elementsFromPoint !== 'function') return [rect];
+  // Per LINE FRAGMENT, never the bounding box. An inline link that wraps has
+  // one fragment per line, and the box enclosing them is mostly space the
+  // element never paints: its middle falls in the leading BETWEEN the lines,
+  // where elementsFromPoint does not contain the element at all. A
+  // box-centre probe therefore reads "not hit-testable" for every wrapped
+  // link. (Same geometry trap as link-in-text-block's own-line test.)
+  //
+  // Fragments also make the answer usefully partial. A footer link scrolled
+  // half under a fixed header has its first line buried and its second line
+  // perfectly clickable, so the honest result is not "reachable" or
+  // "covered" but WHICH PART is reachable — and only that part can compete
+  // for pointer space with anything nearby.
+  const fragments = [...element.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+  const probes = fragments.length ? fragments : [rect];
+  const reachable = [];
+  let testable = false;
+  for (const fragment of probes) {
+    const x = fragment.left + fragment.width / 2;
+    const y = fragment.top + fragment.height / 2;
+    if (x < 0 || y < 0 || x >= win.innerWidth || y >= win.innerHeight) continue;
+    const stack = doc.elementsFromPoint(x, y);
+    const index = stack.indexOf(element);
+    if (index < 0) continue; // this fragment isn't hit-testable; try the next
+    testable = true;
+    // Anything above it that is part of the same control is not an
+    // obstruction: a button's own icon paints over the button, an overlay
+    // label over its input. Only a genuinely separate element blocks it.
+    if (stack.slice(0, index).every((layer) => layer.contains(element) || element.contains(layer))) {
+      reachable.push(fragment);
+    }
+  }
+  // Nothing could be probed at all (entirely out of viewport,
+  // pointer-events: none, nothing laid out): don't know, and don't-know must
+  // not silence a finding, so the whole rect stands.
+  if (!testable) return [rect];
+  return reachable;
+}
+
 /** Text this element contributes that is NOT inside a target — i.e. does it
  *  read as prose beside the link, or is it just another control in a list? */
 function textOutsideTargets(element) {
@@ -146,14 +208,37 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
         // Spacing exception: the min-sized circle around this target must
         // clear every other target's rect and every other undersized
         // target's circle.
-        const crowded = elements.some((other, j) => {
+        const crowds = (other, j) => {
           if (j === i || !laidOut[j]) return false;
           if (other.contains(element) || element.contains(other)) return false; // same control, nested markup
           if (encloses(rects[j], rects[i]) || encloses(rects[i], rects[j])) return false;
-          if (undersized[j] && Math.hypot(centers[j].x - centers[i].x, centers[j].y - centers[i].y) < min) return true;
-          return pointToRectDistance(centers[i], rects[j]) < min / 2;
-        });
+          const within = (box) => {
+            if (undersized[j]) {
+              const c = { x: box.left + box.width / 2, y: box.top + box.height / 2 };
+              if (Math.hypot(c.x - centers[i].x, c.y - centers[i].y) < min) return true;
+            }
+            return pointToRectDistance(centers[i], box) < min / 2;
+          };
+          // Whole-rect test first, as a cheap superset: no part of a target
+          // can be closer than the box enclosing it, so a box that doesn't
+          // reach rules the target out without any hit-testing. Only the
+          // survivors pay for the paint-order queries, which on a page of
+          // hundreds of targets is a handful.
+          if (!within(rects[j])) return false;
+          // Then the honest test: only the parts a pointer can actually
+          // reach compete for pointer space. A link whose first line is
+          // buried under a fixed header and whose second line is clear is
+          // crowding from its second line or not at all.
+          return reachableRects(other, rects[j]).some(within);
+        };
+        const crowded = elements.some(crowds);
         if (!crowded) return { status: 'pass' };
+        // Deliberately NOT applied to the target itself. A crowder that
+        // can't be clicked breaks the premise of the exception, because it
+        // isn't competing for anything. A target that happens to be under a
+        // cookie banner right now is still 20×20 the moment that banner is
+        // dismissed, and suppressing it would hide a real defect behind a
+        // transient overlay, which is the wrong way round.
       }
       const rect = rects[i];
       return {

package/package.json

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