pour-engine 1.1.5 → 1.1.7

package/config/project.config.js

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

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/lib/roles.js

@@ -116,10 +116,34 @@ export function implicitRole(element) {
 }
 
 /** The element's effective role: explicit (first modelled token) or implicit. */
+/**
+ * Presentational Roles Conflict Resolution: a `presentation`/`none` role is
+ * DISCARDED when the element is focusable or carries a global ARIA property,
+ * and the implicit role is exposed instead. Reporting against the written role
+ * in those cases names a role the browser already threw away, and sends the
+ * author to fix the wrong thing.
+ *
+ * The two triggers below are what browsers actually implement, verified in
+ * Chromium's accessibility tree: `<h2 role="presentation">` exposes StaticText,
+ * but adding tabindex or aria-describedby exposes `heading`. Note a non-global
+ * property applicable to the implicit role (aria-level on a heading) does NOT
+ * trigger it, even though a strict reading of the spec suggests it should.
+ */
+function presentationDiscarded(element) {
+  if (element.tabIndex >= 0) return true;
+  if (element.matches('a[href], button, input, select, textarea, summary, [contenteditable="true"]')) return true;
+  return [...GLOBAL_ARIA].some((name) => element.hasAttribute(`aria-${name}`));
+}
+
 export function effectiveRole(element) {
   const explicit = element.getAttribute('role')?.trim().split(/\s+/) ?? [];
   for (const token of explicit) {
-    if (ROLE_ARIA[token.toLowerCase()]) return token.toLowerCase();
+    const role = token.toLowerCase();
+    if (!ROLE_ARIA[role]) continue;
+    if ((role === 'presentation' || role === 'none') && presentationDiscarded(element)) {
+      return implicitRole(element);
+    }
+    return role;
   }
   return explicit.length ? null : implicitRole(element); // unknown explicit role: don't judge
 }

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/2.4.11-focus-not-obscured.js

@@ -1,12 +1,34 @@
 // WCAG SC 2.4.11 Focus Not Obscured (Minimum) (Level AA)
-// When a focusable element's box lies ENTIRELY under an opaque fixed or
-// sticky overlay at its resting position, focusing it shows the user
-// nothing — the criterion's core case (bottom cookie bars covering footer
-// links). Partial overlap passes 2.4.11 by definition ("not entirely
-// hidden"), so only full containment is judged, and only for elements
-// currently inside the viewport where the geometry is real.
+// An opaque fixed/sticky overlay covering a focusable element is the
+// criterion's core case (bottom cookie bars over footer links). Partial
+// overlap passes by definition ("not entirely hidden"), so only full
+// containment counts.
+//
+// This REVIEWS rather than fails, deliberately. What a snapshot can see is
+// "element X is under the panel right now", and that is a fact about the
+// current scroll position, not about the page: scrolling the same page a few
+// hundred pixels names entirely different elements, or none at all. The
+// criterion asks about the state focus ARRIVES in, which depends on tab order,
+// on whether the browser scrolls (it won't, for an element already inside the
+// viewport — merely covered), and on any author focus handler that moves the
+// page. None of that is knowable from geometry alone, so the honest output is
+// a pointer to the overlay and a request for a keyboard pass.
+//
+// Sites that apply the spec's own sufficient technique — scroll-padding for
+// the overlay's edge — are not flagged at all.
 const FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea, summary, [tabindex]:not([tabindex="-1"])';
 
+/** Does the scroll container reserve room for an overlay on this edge?
+ *  scroll-padding is what the Understanding doc cites as sufficient: it keeps
+ *  the browser's own scroll-into-view clear of a sticky panel. */
+function edgeReserved(doc, edge, needed) {
+  const scroller = doc.scrollingElement ?? doc.documentElement;
+  const style = getComputedStyle(scroller);
+  const value = edge === 'top' ? style.scrollPaddingTop : style.scrollPaddingBottom;
+  const px = value && value.endsWith('px') ? parseFloat(value) : 0;
+  return px >= needed - 1;
+}
+
 export default {
   id: 'focus-not-obscured',
   impact: 'serious',
@@ -70,10 +92,16 @@ export default {
         !layer.contains(element) && !element.contains(layer)
         && isObscuringOverlay(layer) && covered(rect, layer.getBoundingClientRect()));
       if (!blocker) return { status: 'pass' };
+      // Which viewport edge is the panel pinned to? That is the edge the
+      // browser's scroll-into-view has to clear.
+      const panel = blocker.getBoundingClientRect();
+      const edge = panel.top <= 1 && panel.bottom < win.innerHeight ? 'top'
+        : panel.bottom >= win.innerHeight - 1 ? 'bottom' : null;
+      if (edge && edgeReserved(doc, edge, panel.height)) return { status: 'pass' };
       return {
-        status: 'fail',
-        message: 'This focusable element sits entirely behind an opaque fixed/sticky overlay — when keyboard focus lands on it, nothing visible changes and the user is lost.',
-        fix: 'Add scroll-padding for the overlay height, or make the overlay dismissible/non-overlapping so focused elements stay at least partly visible.',
+        status: 'incomplete',
+        message: 'This element is currently underneath an opaque fixed panel. Whether that breaks 2.4.11 depends on where the page sits when focus reaches it — the browser does not scroll an element that is already in the viewport, merely covered, so focus can land invisibly. Tab through the page and check the focus indicator is never entirely hidden.',
+        fix: `Reserve room for the panel with scroll-padding-${edge ?? 'bottom'} on the scrolling container, or move focus clear of it when the panel is up.`,
       };
     });
   },

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 {
@@ -37,7 +45,12 @@ export default {
     // canonical harmless case. The failure worth reporting is an invalid
     // role MASKING real semantics or decorating an interactive element.
     const tag = element.tagName.toLowerCase();
-    const genericFallback = tag === 'div' || tag === 'span';
+    // What the element falls back to when the bogus role is ignored. div/span
+    // expose generic; <svg> exposes image (or graphics-document) in every
+    // current engine, which is what an author writing role="img"/"image" on it
+    // wanted anyway — so a typo there costs an AT user nothing. Elements with
+    // real semantics to mask (headings, lists, controls) stay out of the hatch.
+    const genericFallback = tag === 'div' || tag === 'span' || tag === 'svg';
     const focusable = element.tabIndex >= 0
       || element.matches('a[href], button, input, select, textarea, summary');
     const hasAriaProps = [...element.attributes].some(

package/package.json

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