pour-engine 1.1.4 → 1.1.6

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -72,7 +72,7 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 | 2.4.13 | [Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) | AAA | Manual review | — |
 | 2.5.1 | [Pointer Gestures](https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html) | A | Manual review | — |
 | 2.5.2 | [Pointer Cancellation](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html) | A | Manual review | — |
-| 2.5.3 | [Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) | A | Partially automated | label-in-name |
+| 2.5.3 | [Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) | A | Manual review | — |
 | 2.5.4 | [Motion Actuation](https://www.w3.org/WAI/WCAG22/Understanding/motion-actuation.html) | A | Manual review | — |
 | 2.5.5 | [Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) | AAA | Partially automated | target-size-enhanced |
 | 2.5.6 | [Concurrent Input Mechanisms](https://www.w3.org/WAI/WCAG22/Understanding/concurrent-input-mechanisms.html) | AAA | Manual review | — |
@@ -112,4 +112,4 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 | 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-valid-refs, button-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
-**Totals:** 2 automated · 28 partially automated · 56 manual — with 73 rules.
+**Totals:** 2 automated · 27 partially automated · 57 manual — with 72 rules.

package/engine/lib/contrast.js

@@ -52,6 +52,7 @@ let opacityCache = new WeakMap();
 let opacityAnimatorsCache = null;
 let mediaRectsCache = null;
 let panelRectsCache = null;
+let pseudoCache = new WeakMap();
 const HAS_IMAGE = Symbol('background-image in chain');
 
 export function resetAuditCaches() {
@@ -60,6 +61,7 @@ export function resetAuditCaches() {
   opacityAnimatorsCache = null;
   mediaRectsCache = null;
   panelRectsCache = null;
+  pseudoCache = new WeakMap();
 }
 
 function canvasColor(doc) {
@@ -278,6 +280,186 @@ function textSamplePoint(element) {
  * missed. The ancestor walk (which callers still run) covers the common
  * cases of that shape.
  */
+const px = (value) => (typeof value === 'string' && value.endsWith('px') ? parseFloat(value) : NaN);
+
+/**
+ * The viewport rect a positioned pseudo-element paints into, or null when
+ * its geometry isn't statically resolvable.
+ *
+ * An absolutely positioned box resolves against its containing block's
+ * PADDING box, which is the nearest ancestor that establishes one — usually
+ * the host itself (authors nearly always set position: relative for exactly
+ * this), but not always, so the chain is walked rather than assumed.
+ * Non-px insets, rotations and scales return null, which makes callers
+ * abstain rather than guess a rect.
+ */
+function containingBlockFor(host) {
+  for (let node = host; node && node.nodeType === 1; node = node.parentElement) {
+    const style = getComputedStyle(node);
+    // Transforms, filters and containment make an element a containing block
+    // for its absolutely positioned descendants just as positioning does.
+    if (style.position !== 'static' || style.transform !== 'none'
+      || style.filter !== 'none' || /paint|layout|strict|content/.test(style.contain ?? '')) return node;
+  }
+  return null; // the initial containing block — viewport-relative, not resolved here
+}
+
+function pseudoRect(host, style) {
+  const block = containingBlockFor(host);
+  if (!block) return null;
+  const hostStyle = getComputedStyle(block);
+  // A zero-extent containing block is still a valid ORIGIN — a collapsed
+  // positioned wrapper whose pseudo paints outside it is ordinary CSS. Only
+  // the opposing-inset derivation needs a real extent, and the degenerate
+  // boxes that produces are caught by the sanity check at the end.
+  const hostRect = block.getBoundingClientRect();
+
+  // Absolute positioning resolves against the containing block's PADDING box.
+  const borderLeft = px(hostStyle.borderLeftWidth) || 0;
+  const borderTop = px(hostStyle.borderTopWidth) || 0;
+  const cbLeft = hostRect.left + borderLeft;
+  const cbTop = hostRect.top + borderTop;
+  const cbWidth = hostRect.width - borderLeft - (px(hostStyle.borderRightWidth) || 0);
+  const cbHeight = hostRect.height - borderTop - (px(hostStyle.borderBottomWidth) || 0);
+
+  // getComputedStyle reports the CONTENT box, so padding and border have to
+  // be added back to get the extent that actually paints.
+  const extraX = (px(style.paddingLeft) || 0) + (px(style.paddingRight) || 0)
+    + (px(style.borderLeftWidth) || 0) + (px(style.borderRightWidth) || 0);
+  const extraY = (px(style.paddingTop) || 0) + (px(style.paddingBottom) || 0)
+    + (px(style.borderTopWidth) || 0) + (px(style.borderBottomWidth) || 0);
+
+  // An opposing inset pair pins both edges directly; otherwise one inset plus
+  // the used size does. `auto` on both sides leaves the box where static flow
+  // would have put it — not resolvable here.
+  const span = (startValue, endValue, sizeValue, origin, extent, extra) => {
+    const start = px(startValue);
+    const end = px(endValue);
+    const size = px(sizeValue);
+    if (Number.isFinite(start) && Number.isFinite(end)) return [origin + start, origin + extent - end];
+    if (Number.isFinite(start) && Number.isFinite(size)) return [origin + start, origin + start + size + extra];
+    if (Number.isFinite(end) && Number.isFinite(size)) {
+      const far = origin + extent - end;
+      return [far - size - extra, far];
+    }
+    return null;
+  };
+  const x = span(style.left, style.right, style.width, cbLeft, cbWidth, extraX);
+  const y = span(style.top, style.bottom, style.height, cbTop, cbHeight, extraY);
+  if (!x || !y) return null;
+
+  let [left, right] = x;
+  let [top, bottom] = y;
+  if (style.transform && style.transform !== 'none') {
+    // Only a pure translation keeps the box axis-aligned and the same size;
+    // rotation/scale/skew would need real geometry, so they stay unresolved.
+    const matrix = /^matrix\(([^)]+)\)$/.exec(style.transform);
+    if (!matrix) return null;
+    const [a, b, c, d, e, f] = matrix[1].split(',').map(Number);
+    if (a !== 1 || b !== 0 || c !== 0 || d !== 1) return null;
+    left += e; right += e; top += f; bottom += f;
+  }
+  // A degenerate box is not unknowable — it is a box that paints nothing
+  // (collapsed separator rules are usually exactly this: 1px wide, 0 tall).
+  // Callers skip it rather than abstaining on the whole element.
+  return { left, top, right, bottom, empty: !(right > left) || !(bottom > top) };
+}
+
+/**
+ * The backdrop a host's own ::before/::after paints over `point`.
+ *
+ * This is the one resolution path that can see pseudo-element paint at all:
+ * they carry no DOM node, so the ancestor walk (which reads element computed
+ * styles) and elementsFromPoint (which retargets them to their host) are both
+ * structurally blind to them. The sliding indicator pill behind a selected
+ * segmented-control option is the canonical case — the text really does sit
+ * 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.
+ */
+/** The paint a host's pseudo-elements contribute, resolved once per audit.
+ *  Two extra getComputedStyle calls per host would otherwise land on every
+ *  text element on the page; cached, the per-point test below is rect math. */
+function pseudoLayers(host) {
+  let layers = pseudoCache.get(host);
+  if (layers !== undefined) return layers;
+  layers = [];
+  // Paint order within a host: background, ::before, content, ::after — so a
+  // later entry covers an earlier one, and both sit above the host's own
+  // background but below its text.
+  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;
+    if (!paints) continue;
+    // In-flow pseudos (the overwhelming majority: bullets, icons, rules,
+    // badges) occupy their own box in the content flow beside the text
+    // rather than painting behind it. Only out-of-flow ones can be the
+    // 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 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.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 };
+    // 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.
+    const imageCss = style.backgroundImage !== 'none' ? style.backgroundImage : null;
+    layers.push({ rect, color, imageCss });
+  }
+  pseudoCache.set(host, layers);
+  return layers;
+}
+
+/**
+ * The nearest pseudo-element paint covering this element's text, walking the
+ * flat tree upward: an out-of-flow ::before/::after paints above its host's
+ * background but below its host's descendants, so the first one that covers
+ * the text is the real backdrop.
+ *
+ * This is the only path that can see pseudo-element paint at all — they carry
+ * no DOM node, so the ancestor walk (element computed styles) and
+ * elementsFromPoint (which retargets them to their host) are both
+ * structurally blind. The sliding indicator behind a selected
+ * segmented-control option is the canonical case: the text really does sit on
+ * the pill, not on the track colour both other paths report.
+ *
+ * Pure geometry, deliberately: unlike the hit-test it needs no viewport, so
+ * it answers for text scrolled far off screen too.
+ *
+ * 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.
+ */
+export function pseudoBackdropForText(element) {
+  const point = textSamplePoint(element);
+  if (!point) return null;
+  let acc = null;
+  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) {
+      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 } };
+      if (!color || color.a === 0) continue;
+      acc = acc ? composite(acc, color) : color;
+      if (acc.a >= 1) return { color: acc };
+    }
+  }
+  return acc ? { color: acc } : null;
+}
+
 /** A layer qualifies as a scrim over `element` when it is translucent paint
  *  (or a backdrop-filter) covering most of the viewport and the whole
  *  element — the shape of a modal/loading veil, not a badge or header. */

package/engine/rules/index.js

@@ -15,11 +15,14 @@ import imageAlt from './wcag/1.1.1-image-alt.js';
 import svgImgAlt from './wcag/1.1.1-svg-img-alt.js';
 import buttonName from './wcag/4.1.2-button-name.js';
 import linkName from './wcag/2.4.4-link-name.js';
-// Un-parked 2026-08-01 (was parked 2026-07-29): benchmarking against other
-// engines showed real 2.5.3 misses on mainstream sites, and the rule now
-// also covers labelable fields whose associated <label> text is missing
-// from an overriding aria-name.
-import labelInName from './wcag/2.5.3-label-in-name.js';
+// Re-parked by product decision (2026-08-01, David, after a one-day
+// un-parking): 2.5.3 is normative Level A but chiefly serves speech-input
+// users, and the findings volume isn't wanted in results for now. The SC is
+// classed 'manual' in wcag22.js so it lands in the human checklist instead
+// of being silently skipped. The rule itself (incl. the labelled-field
+// widening) stays maintained here — restore the import + registry entry to
+// bring it back.
+// import labelInName from './wcag/2.5.3-label-in-name.js';
 import formLabel from './wcag/1.3.1-form-label.js';
 import autocompleteValid from './wcag/1.3.5-autocomplete-valid.js';
 import orientationLock from './wcag/1.3.4-orientation.js';
@@ -110,7 +113,7 @@ export default [
   svgImgAlt,
   buttonName,
   linkName,
-  labelInName,
+  // labelInName, — re-parked 2026-08-01, see note at the import
   formLabel,
   autocompleteValid,
   orientationLock,

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

@@ -4,6 +4,7 @@ import {
   backgroundImageSource, backgroundImagePaintRect, imageLuminanceRange, gradientLuminanceRange,
   rangeVerdict, isLargeText, cumulativeOpacity, opacityAnimating, restingOpacity, mediaRects,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
+  pseudoBackdropForText,
 } from '../../lib/contrast.js';
 
 /** Display a ratio truncated (never rounded up): 4.495 must read "4.49",
@@ -302,7 +303,28 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
         };
       }
     }
-    if (painted?.image) {
+    // Pseudo-element paint sits above everything the hit-test and the walk
+    // can report, and neither can see it — so it is resolved before them and
+    // 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.',
+      };
+    }
+    // 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);
+      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.',
+      };
+    }
+    if (painted?.image && !pseudoBack) {
       const sampled = await sampledVerdict(painted.image, foreground, required, doc);
       return sampled ?? {
         status: 'incomplete',
@@ -330,6 +352,15 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
         };
       }
     }
+    if (pseudoBack?.color) {
+      // Opaque pill: it IS the backdrop. Translucent paint composites over
+      // whatever the walk resolved beneath it. Either way the geometry is
+      // computed, not guessed, so this counts as verified paint truth.
+      background = pseudoBack.color.a >= 1 || !background
+        ? pseudoBack.color
+        : composite(pseudoBack.color, background);
+      backgroundVerified = true;
+    }
     if (!background) {
       return { status: 'incomplete', message: 'The background could not be determined — check contrast by eye.' };
     }

package/engine/rules/wcag/4.1.2-valid-role.js

@@ -1,5 +1,5 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
-// ARIA 1.2 roles (concrete, usable roles — abstract roles are invalid in markup).
+// Concrete, usable roles — abstract roles are invalid in markup.
 const VALID_ROLES = new Set([
   'alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote', 'button',
   'caption', 'cell', 'checkbox', 'code', 'columnheader', 'combobox', 'complementary',
@@ -12,6 +12,14 @@ const VALID_ROLES = new Set([
   'slider', 'spinbutton', 'status', 'strong', 'subscript', 'superscript', 'switch', 'tab',
   'table', 'tablist', 'tabpanel', 'term', 'textbox', 'time', 'timer', 'toolbar', 'tooltip',
   'tree', 'treegrid', 'treeitem',
+  // ARIA 1.3 additions. `image` is the spec's own primary spelling with
+  // `img` kept as the synonym — img is the one ARIA role that isn't a whole
+  // word, which is why authors reach for `image`, and Safari (2021),
+  // Firefox (116) and Chromium all map it. Flagging it was a false positive
+  // on real sites; verified against Chromium's accessibility tree, where
+  // role="image" resolves to image and only a genuinely bogus role falls
+  // back to generic.
+  'image', 'comment', 'mark', 'suggestion',
 ]);
 
 export default {

package/engine/wcag22.js

@@ -82,7 +82,7 @@ export default [
   sc('2.4.13', 'Focus Appearance', 'AAA', 'manual', '2.2'),
   sc('2.5.1', 'Pointer Gestures', 'A', 'manual', '2.1'),
   sc('2.5.2', 'Pointer Cancellation', 'A', 'manual', '2.1'),
-  sc('2.5.3', 'Label in Name', 'A', 'partial', '2.1'), // label-in-name un-parked 2026-08-01: catches aria-name/visible-label mismatches on controls and labelled fields; can't prove every naming path, so partial
+  sc('2.5.3', 'Label in Name', 'A', 'manual', '2.1'), // manual WHILE label-in-name is parked (re-parked 2026-08-01, see rules/index.js) — 'auto' with no active rule would make this SC vanish from results AND the manual checklist
   sc('2.5.4', 'Motion Actuation', 'A', 'manual', '2.1'),
   sc('2.5.5', 'Target Size (Enhanced)', 'AAA', 'partial', '2.1'),
   sc('2.5.6', 'Concurrent Input Mechanisms', 'AAA', 'manual', '2.1'),

package/package.json

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