pour-engine 1.17.0 → 1.19.0

package/config/project.config.js

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

package/engine/lib/contrast.js

@@ -93,6 +93,21 @@ export function contrastRatio(foreground, background) {
   return (lighter + 0.05) / (darker + 0.05);
 }
 
+/**
+ * Display a ratio truncated, never rounded up: 4.495 must read "4.49",
+ * because "4.50:1 — below the 4.5:1 minimum" reads as a contradiction.
+ * Shared by the rules and the /contrast/ checker so the two surfaces can
+ * never show the same ratio differently. Above 10 one decimal is plenty
+ * (no text threshold lives up there), and "21:1" reads better than
+ * "21.0:1" — a trailing zero implies precision the eye can use.
+ */
+export function showRatio(ratio) {
+  const text = ratio >= 10
+    ? (Math.floor(ratio * 10) / 10).toFixed(1)
+    : (Math.floor(ratio * 100) / 100).toFixed(2);
+  return text.replace(/\.0+$/, '');
+}
+
 /** Alpha-composite `top` over `bottom` (both {r,g,b,a}) → opaque colour. */
 export function composite(top, bottom) {
   const a = top.a + bottom.a * (1 - top.a);

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

@@ -6,9 +6,7 @@
 // with placeholder text can conform with a faint border (#ccc borders are
 // endemic, WebAIM's own search field included), and that judgment needs
 // eyes. Focus-indicator contrast is not statically computable — manual.
-import { parseColor, contrastRatio, composite, effectiveBackground } from '../../lib/contrast.js';
-
-const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
+import { parseColor, contrastRatio, composite, effectiveBackground, showRatio } from '../../lib/contrast.js';
 
 export default {
   id: 'non-text-contrast',

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

@@ -6,11 +6,15 @@ import {
   opacityAnimating, restingOpacity, mediaRects,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
+  showRatio,
 } from '../../lib/contrast.js';
 
-/** Display a ratio truncated (never rounded up): 4.495 must read "4.49",
- *  because "4.50:1 — below the 4.5:1 minimum" reads as a contradiction. */
-const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
+/** Serialise a judged colour for the report and the checker link. Composited
+ *  channels keep up to two decimals: rounding them to integers changes the
+ *  pair enough that the checker scores a different ratio than the audit
+ *  reported (4.21 vs 4.19 on a 70%-opacity footer). */
+const channelText = (value) => String(Math.round(value * 100) / 100);
+const asRgb = (color) => `rgb(${channelText(color.r)}, ${channelText(color.g)}, ${channelText(color.b)})`;
 
 /** The one case a full-page veil still can't be judged for the author: the
  *  resting page and the dimmed one land on opposite sides of the threshold,
@@ -699,8 +703,10 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
           message: `Contrast is ${showRatio(haloRatio)}:1 against this text's own outline and ${showRatio(ratio)}:1 against the background — below the ${required}:1 WCAG minimum for this text size.`,
           fix: `Increase the difference between the text colour and its text-shadow outline (or the background) until the ratio reaches ${required}:1.`,
           data: {
-            foreground: style.color,
-            background: `rgb(${Math.round(halo.r)}, ${Math.round(halo.g)}, ${Math.round(halo.b)})`,
+            // The judged (composited) colour, not style.color: the checker
+            // link must score the pair the viewer actually sees.
+            foreground: asRgb(foreground),
+            background: asRgb(halo),
             ratio: Number(showRatio(haloRatio)),
             required,
           },
@@ -737,22 +743,44 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // carried alongside, never instead: a page written in oklch() or
     // color(srgb …) would otherwise be handed an rgb() value that appears
     // nowhere in its stylesheet.
-    const asRgb = (color) => `rgb(${Math.round(color.r)}, ${Math.round(color.g)}, ${Math.round(color.b)})`;
     const foregroundRgb = asRgb(foreground);
     const backgroundRgb = asRgb(background);
-    const foregroundCss = style.color !== foregroundRgb ? style.color : null;
+    // …but only when the authored string is the judged colour in another
+    // spelling. An authored colour that differs in VALUE (translucent text,
+    // an ancestor's opacity dimming the glyphs) still names what to search
+    // the stylesheet for, yet must never reach the checker link: the checker
+    // would score a pair the page never renders, showing a passing ratio for
+    // this very failure.
+    const sameValue = (css, judged) => {
+      const parsed = parseColor(css);
+      return parsed != null && parsed.a >= 1 && asRgb(parsed) === judged;
+    };
+    const authoredFg = style.color !== foregroundRgb ? style.color : null;
     const backgroundSource = backgroundColorSource(element);
-    const backgroundCss = backgroundSource && backgroundSource !== backgroundRgb ? backgroundSource : null;
+    const authoredBg = backgroundSource && backgroundSource !== backgroundRgb ? backgroundSource : null;
+    const foregroundCss = authoredFg && sameValue(authoredFg, foregroundRgb) ? authoredFg : null;
+    const backgroundCss = authoredBg && sameValue(authoredBg, backgroundRgb) ? authoredBg : null;
     const authored = [
-      foregroundCss && `the text as ${foregroundCss}`,
-      backgroundCss && `the background as ${backgroundCss}`,
+      authoredFg && `the text as ${authoredFg}`,
+      authoredBg && `the background as ${authoredBg}`,
     ].filter(Boolean).join(' and ');
+    // Say WHY the rendered colour differs when the mechanism is provable, so
+    // the author learns the cause along with the finding.
+    const parsedAuthoredFg = authoredFg && !foregroundCss ? parseColor(authoredFg) : null;
+    const dimmedNote = parsedAuthoredFg
+      ? (opacity < 1
+        ? ` The gap is opacity: this element or an ancestor renders at ${Math.round(opacity * 100)}% opacity, dimming the text to the sRGB value above.`
+        : (parsedAuthoredFg.a < 1
+          ? ' The text colour is translucent, so it composites with the background into the sRGB value above.'
+          : ''))
+      : '';
 
     return {
       status: 'fail',
       message: `Contrast is ${showRatio(ratio)}:1 — below the ${required}:1 WCAG minimum for this text size.`,
       fix: `Darken the text or lighten the background until the ratio reaches ${required}:1 (currently ${foregroundRgb} on ${backgroundRgb}).`
-        + (authored ? ` Your CSS writes ${authored}, so searching it for the sRGB values above won't find them.` : ''),
+        + (authored ? ` Your CSS writes ${authored}, so searching it for the sRGB values above won't find them.` : '')
+        + dimmedNote,
       // The exact pair, for the UIs to link out to an interactive checker.
       data: {
         foreground: foregroundRgb,

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

@@ -4,11 +4,9 @@
 // endemic ~2.8:1 gray-on-white) was previously never measured by any rule.
 import {
   parseColor, contrastRatio, composite, effectiveBackground, isLargeText,
-  backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity,
+  backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity, showRatio,
 } from '../../lib/contrast.js';
 
-const showRatio = (ratio) => (Math.floor(ratio * 100) / 100).toFixed(2);
-
 export default {
   id: 'control-contrast',
   impact: 'serious',

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

@@ -108,9 +108,14 @@ function reachableRects(element, rect) {
     }
   }
   // 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];
+  // pointer-events: none, nothing laid out): the OCCLUSION question is
+  // unanswerable, and don't-know must not silence a finding — but the
+  // fragment GEOMETRY is measurable regardless, so the fragments stand,
+  // never the bounding box. A wrapped link's box is mostly leading and
+  // line-gap no pointer can activate; counting that empty space as
+  // reachable made an offscreen two-line neighbour crowd a small target
+  // its painted lines never came near (ja.wikipedia's word list).
+  if (!testable) return probes;
   return reachable;
 }
 
@@ -212,6 +217,17 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
     // link cards, overlay + inner button) — not two targets crowding.
     const encloses = (a, b) =>
       a.left <= b.left && a.right >= b.right && a.top <= b.top && a.bottom >= b.bottom;
+    // Enclosure proved on the element's PAINT: true only when a single
+    // painted fragment contains the other rect. For unwrapped elements the
+    // one fragment is the box, so this is `encloses` exactly; a wrapped
+    // element's fragments are each line it actually paints, and a box that
+    // merely spans them encloses nothing. The box test runs first as a
+    // cheap superset — no fragment can enclose what the box doesn't.
+    const paintedEncloses = (target, targetBox, innerBox) => {
+      if (!encloses(targetBox, innerBox)) return false;
+      const fragments = [...target.getClientRects()].filter((f) => f.width > 0 && f.height > 0);
+      return fragments.length <= 1 || fragments.some((f) => encloses(f, innerBox));
+    };
 
     // ── Obscured targets ──────────────────────────────────────────────
     // The criterion measures the region that ACCEPTS the pointer action.
@@ -399,7 +415,15 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
         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;
+          // "One control drawn twice" (stretched-link overlays) is a claim
+          // about PAINT, so it must be proved on a painted fragment, not on
+          // the bounding box: a two-line wrapped link's box swallows a small
+          // same-line neighbour while its painted lines sit nowhere near it
+          // — a different control entirely, and dismissing it here silenced
+          // the honest fragment test below. A single-fragment element's one
+          // fragment IS its box, so genuine overlays are dismissed exactly
+          // as before.
+          if (paintedEncloses(other, rects[j], rects[i]) || paintedEncloses(element, rects[i], rects[j])) return false;
           const within = (box) => {
             if (undersized[j]) {
               const c = { x: box.left + box.width / 2, y: box.top + box.height / 2 };

package/package.json

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