pour-engine 1.42.2 → 1.42.3

package/config/project.config.js

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

package/engine/lib/accessible-name.js

@@ -150,6 +150,13 @@ function visibleContentText(element, includeHidden, inLabelledBy, visited) {
  *  the generated content decorative and contributes nothing, which is how
  *  the same syntax silences icon glyphs. */
 function generatedContent(element, pseudo, includeHidden) {
+  // SVG elements generate no ::before/::after box: the computed style still
+  // reports the content, but nothing is painted and Chromium's accessible
+  // name leaves it out (measured 2026-09-13: an icon font's ::before "h" on
+  // the <svg> inside an icon-only button paints 0 pixels and Chromium names
+  // the button ""; the same rule on a <span> paints and names it "h"). Naming
+  // the button "h" from it hid a nameless close button on channel4.com.
+  if (element.namespaceURI === 'http://www.w3.org/2000/svg') return '';
   const style = getComputedStyle(element, pseudo);
   // Generated nodes follow the same hidden-content exclusion as ordinary
   // descendants. A hover label can exist in computed content while its

package/engine/lib/contrast.js

@@ -318,7 +318,7 @@ const transparentImages = new Set();
 /** True when every layer of this computed background-image is a url() known
  *  to paint nothing — so the layer cannot change what is behind it. Any
  *  gradient, or any unsampled image, makes that unknowable. */
-function paintsNothing(backgroundImage) {
+export function paintsNothing(backgroundImage) {
   if (backgroundImage.includes('gradient(')) return false;
   const urls = [...backgroundImage.matchAll(/url\(["']?(.*?)["']?\)/g)].map((m) => m[1]);
   return urls.length > 0 && urls.every((url) => transparentImages.has(url));
@@ -585,7 +585,7 @@ export function backgroundObscured(element) {
  *  hit-testing. A Range around the first non-blank text node beats the
  *  element's own rect centre: wide containers with left-aligned text would
  *  hit-test empty space. Falls back to the element rect. */
-function textSamplePoint(element) {
+export function textSamplePoint(element) {
   for (const node of element.childNodes) {
     if (node.nodeType !== 3 || !node.textContent.trim()) continue;
     const range = element.ownerDocument.createRange();

package/engine/lib/dom.js

@@ -31,6 +31,47 @@ export function flatTreeParent(node) {
   return node.assignedSlot ?? node.parentElement ?? node.getRootNode()?.host ?? null;
 }
 
+/** Every element beneath `element` in the FLAT tree: light descendants,
+ *  open shadow trees, and what slots pull in. Closed shadow roots stay
+ *  unreachable, as everywhere in the engine. */
+export function flatDescendants(element) {
+  const found = [];
+  const seen = new Set();
+  const visit = (scope) => {
+    for (const el of scope.querySelectorAll('*')) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      found.push(el);
+      if (el.shadowRoot) visit(el.shadowRoot);
+      if (el.tagName === 'SLOT') {
+        for (const assigned of el.assignedElements({ flatten: true })) {
+          if (!seen.has(assigned)) { seen.add(assigned); found.push(assigned); }
+          visit(assigned);
+        }
+      }
+    }
+  };
+  if (element.shadowRoot) visit(element.shadowRoot);
+  visit(element);
+  return found;
+}
+
+/** Focusable but left out of sequential (Tab) navigation: a negative
+ *  tabindex on the element itself, or on a shadow host between it and
+ *  `within`. HTML leaves a focus navigation scope owner "whose tabindex value
+ *  is a negative integer" out of the tabindex-ordered focus navigation scope,
+ *  and its scope's contents go with it (measured in Chromium 2026-09-13: Tab
+ *  skips the <button> in an mwc-button host with tabindex="-1", while a click
+ *  or focus() still lands on it). */
+export function outOfSequentialFocus(element, within = null) {
+  const negative = (el) => el.hasAttribute('tabindex') && el.tabIndex < 0;
+  if (negative(element)) return true;
+  for (let node = flatTreeParent(element); node && node !== within; node = flatTreeParent(node)) {
+    if (node.shadowRoot && negative(node)) return true;
+  }
+  return false;
+}
+
 /**
  * Rendered on screen — ignores aria-hidden. For purely visual rules
  * (contrast, target size): sighted users see aria-hidden content too.

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

@@ -1,6 +1,6 @@
 // WCAG SC 1.4.3 Contrast (Minimum) (Level AA)
 import {
-  parseColor, contrastRatio, composite, effectiveBackground, backgroundObscured,
+  parseColor, contrastRatio, composite, effectiveBackground, backgroundObscured, paintsNothing, textSamplePoint,
   backgroundImageSource, backgroundImagePaintRect, imagePaintRectInBox, imageLuminanceRange,
   sampledGradientRange, gradientStops, rangeVerdict, rangeWithBackdrop, isLargeText, cumulativeOpacity,
   opacityAnimating, restingOpacity, mediaRects, inZeroClipSubtree,
@@ -263,6 +263,75 @@ function unaccountedScrim(element, imageCarrier) {
   });
 }
 
+/**
+ * The nearest layer in the browser's hit-test stack that is NOT an ancestor
+ * of the text and paints between the glyphs and the ancestor carrying the
+ * walked background-image. The ancestor walk (backgroundImageSource) is
+ * structurally blind to it: react.dev lays a light card gradient
+ * (position: absolute; inset: 0) inside a section whose own background is a
+ * dark conic gradient, and the walk sampled that dark section behind dark
+ * text (1.18:1) while the pixels under the glyphs read 13.8:1 (2026-09-13
+ * verdict crawl). Returns { image, css, overlays } when such a layer paints
+ * an image or gradient (the real backdrop to sample, with the translucent
+ * ancestor colours passed on the way as overlays), { covered } when it is an
+ * opaque colour or a replaced element (the walked image never shows behind
+ * the glyphs; the colour paths below resolve it), and null when the stack
+ * reaches the carrier first, cannot be read, or the text is off screen.
+ */
+function coveringLayer(element, imageCarrier) {
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  // undefined: the hit-test cannot answer (off screen, retargeted, unread);
+  // null: it answered, and nothing covers the walked image.
+  if (typeof doc.elementsFromPoint !== 'function') return undefined;
+  const point = textSamplePoint(element);
+  if (!point || point.x < 0 || point.y < 0 || point.x >= win.innerWidth || point.y >= win.innerHeight) return undefined;
+  const stack = doc.elementsFromPoint(point.x, point.y);
+  const start = stack.indexOf(element);
+  if (start === -1) return undefined;
+  const overlays = [];
+  for (const layer of stack.slice(start + 1)) {
+    if (layer === imageCarrier) return null;
+    if (layer.contains(element)) {
+      const own = parseColor(getComputedStyle(layer).backgroundColor);
+      if (own && own.a > 0 && own.a < 1) overlays.push(own);
+      continue;
+    }
+    // Paint inside a shadow tree is retargeted to its host: unknowable here.
+    if (layer.shadowRoot) return undefined;
+    if (/^(img|video|canvas|picture)$/i.test(layer.tagName)) return { covered: layer };
+    const style = getComputedStyle(layer);
+    if (style.backgroundImage !== 'none' && !paintsNothing(style.backgroundImage)) return { image: layer, css: style.backgroundImage, overlays };
+    const color = parseColor(style.backgroundColor);
+    if (color && color.a >= 1) return { covered: layer };
+  }
+  return null;
+}
+
+/**
+ * Scroll-independent stand-in for coveringLayer when the hit-test is blind:
+ * is there a positioned element inside the image carrier, not an ancestor of
+ * the text, painting an image or an opaque colour over the text's sample
+ * point? It paints above the carrier's background, and whether it lies
+ * behind the glyphs or over them is paint order this engine does not model,
+ * so the caller asks rather than asserts the walked image.
+ */
+function positionedPaintInside(carrier, element) {
+  const point = textSamplePoint(element);
+  if (!point) return false;
+  for (const node of carrier.querySelectorAll('*')) {
+    if (node.contains(element) || element.contains(node)) continue;
+    const style = getComputedStyle(node);
+    if (style.position !== 'absolute' && style.position !== 'fixed') continue;
+    const paints = (style.backgroundImage !== 'none' && !paintsNothing(style.backgroundImage))
+      || (parseColor(style.backgroundColor)?.a ?? 0) >= 1;
+    if (!paints || node.checkVisibility?.({ checkOpacity: true, checkVisibilityCSS: true }) === false) continue;
+    const box = node.getBoundingClientRect();
+    if (point.x >= box.left && point.x < box.right && point.y >= box.top && point.y < box.bottom) return true;
+  }
+  return false;
+}
+
 /** An image layer with no opaque pixels: it covers the background without
  *  changing it, so the callers step over it rather than reporting on it. */
 const PAINTS_NOTHING = Symbol('fully transparent image layer');
@@ -753,7 +822,22 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // A background image on an ancestor: sample its pixels and bracket —
     // but only when it's actually painted under this text. Icon-in-padding
     // images (external-link arrows etc.) don't affect the text's contrast.
-    const imageSource = backgroundImageSource(element);
+    let imageSource = backgroundImageSource(element);
+    // Where the browser's hit-test can answer, it outranks the ancestor walk:
+    // a non-ancestor layer painted between the text and the walked image is
+    // the backdrop instead (see coveringLayer). The element's own image is
+    // the walk's by construction and is left alone.
+    if (imageSource && imageSource.element !== element) {
+      const cover = coveringLayer(element, imageSource.element);
+      if (cover?.image) imageSource = { css: cover.css, element: cover.image, overlays: cover.overlays };
+      else if (cover) imageSource = null;
+      else if (cover === undefined && positionedPaintInside(imageSource.element, element)) {
+        return {
+          status: 'incomplete',
+          message: 'This text sits in a section with a background image or gradient, and a positioned element inside that section paints its own background where the text is. Which of the two is behind the glyphs depends on paint order, and the text is off screen where the browser cannot be asked, so check the contrast by eye.',
+        };
+      }
+    }
     if (imageSource) {
       if (ownMultiply) return { status: 'incomplete', message: 'This text multiplies against an image or gradient. Its contrast depends on the pixels behind each glyph; check it by eye.' };
       const { relation, intrinsic, dimensionless, isGradient, sizedSmall, paint } = await imageVsText(imageSource, element, doc);

package/engine/rules/wcag/4.1.2-nested-interactive.js

@@ -1,5 +1,5 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
-import { isInert } from '../../lib/dom.js';
+import { isInert, flatDescendants, flatTreeParent, outOfSequentialFocus } from '../../lib/dom.js';
 // Deliberately excludes bare [tabindex]: a focusable container (e.g. a
 // scrollable region with tabindex="0") holding links is correct markup.
 const INTERACTIVE =
@@ -28,8 +28,14 @@ export default {
     const NATIVE = 'a[href], button, input, select, textarea, summary, audio[controls], video[controls]';
     // Negative tabindex removes sequential focus navigation, not focusability.
     // https://html.spec.whatwg.org/multipage/interaction.html#attr-tabindex
-    const candidates = [...element.querySelectorAll(INTERACTIVE)].filter((el) =>
-      !el.matches(':disabled') && !isInert(el)
+    // The FLAT tree: a custom element's shadow tree can hold the real
+    // control (material.io's cookie banner: div role="button" holding an
+    // <mwc-button tabindex="-1"> whose shadow tree renders a <button>).
+    // Sequential focusability follows the host: a negative tabindex on a
+    // shadow host takes its whole scope out of the tab order (HTML focus
+    // navigation scopes), so such a control is the negative-tabindex shape.
+    const candidates = flatDescendants(element).filter((el) =>
+      el.matches?.(INTERACTIVE) && !el.matches(':disabled') && !isInert(el)
       && !(el.tagName === 'INPUT' && el.type === 'hidden') && isRendered(el)
       // aria-hidden content that Tab reaches is aria-hidden-focus's finding.
       // aria-hidden content with a negative tabindex is not, yet a click or a
@@ -38,23 +44,29 @@ export default {
       // interaction with the user or indirectly via programmatic means", so
       // it stays a candidate here.
       // https://www.w3.org/TR/wai-aria-1.2/#aria-hidden
-      && !(el.closest('[aria-hidden="true"]') && !(el.hasAttribute('tabindex') && el.tabIndex < 0))
+      && !(el.closest('[aria-hidden="true"]') && !outOfSequentialFocus(el, element))
       && (el.matches(NATIVE) || el.hasAttribute('tabindex')));
     // A child requiring review must not conceal a later definite finding.
-    const nested = candidates.find((el) => !(el.hasAttribute('tabindex') && el.tabIndex < 0)) ?? candidates[0];
+    const nested = candidates.find((el) => !outOfSequentialFocus(el, element)) ?? candidates[0];
     if (!nested) return { status: 'pass' };
     // A programmatically focusable child must not silently pass. In an
     // ARIA widget its name and role can survive presentational-descendant
     // processing, so nesting alone does not prove a 4.1.2 failure.
     // Native links/buttons separately forbid interactive descendants.
     // https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion
-    if (nested.hasAttribute('tabindex') && nested.tabIndex < 0
-      && !element.matches('a[href], button')) {
+    if (outOfSequentialFocus(nested, element) && !element.matches('a[href], button')) {
+      let host = null;
+      for (let node = flatTreeParent(nested); node && node !== element; node = flatTreeParent(node)) {
+        if (node.shadowRoot && node.hasAttribute('tabindex') && node.tabIndex < 0) { host = node; break; }
+      }
+      const child = `<${nested.tagName.toLowerCase()}>`;
       return {
         status: 'incomplete',
-        message: nested.closest('[aria-hidden="true"]')
-          ? `This control contains an element (<${nested.tagName.toLowerCase()}>) that is hidden from assistive technology but can still receive focus from a click or a script. Focus landing there lands on content a screen reader cannot see. Check whether it can take focus, and if it can, remove it from focus or from aria-hidden.`
-          : `This control contains an element (<${nested.tagName.toLowerCase()}>) with a negative tabindex. It can still receive focus. Check that both controls expose the intended name and role, and that focusing and activating the child works correctly.`,
+        message: host
+          ? `This control contains a custom element (<${host.tagName.toLowerCase()}>) whose shadow tree holds another control (${child}). The host's negative tabindex keeps it out of the tab order, but a click or a script can still focus it. Check that both controls expose the intended name and role, and that focusing and activating the child works correctly.`
+          : nested.closest('[aria-hidden="true"]')
+            ? `This control contains an element (${child}) that is hidden from assistive technology but can still receive focus from a click or a script. Focus landing there lands on content a screen reader cannot see. Check whether it can take focus, and if it can, remove it from focus or from aria-hidden.`
+            : `This control contains an element (${child}) with a negative tabindex. It can still receive focus. Check that both controls expose the intended name and role, and that focusing and activating the child works correctly.`,
       };
     }
     // <summary> is the one outer control HTML does not forbid this on: its

package/package.json

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