pour-engine 1.15.0 → 1.16.0

package/config/project.config.js

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

package/engine/lib/contrast.js

@@ -525,8 +525,14 @@ function pseudoLayers(host) {
     // 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.
+    // Repeat/size/position ride along too: a no-repeat url() paints its
+    // intrinsic rect inside this box, not the whole of it, and only the
+    // caller (which knows where the text is) can rule on that geometry.
     const imageCss = style.backgroundImage !== 'none' ? style.backgroundImage : null;
-    layers.push({ rect, color: layerColor, imageCss });
+    const imageMeta = imageCss
+      ? { repeat: style.backgroundRepeat, size: style.backgroundSize, position: style.backgroundPosition }
+      : null;
+    layers.push({ rect, color: layerColor, imageCss, imageMeta });
   }
   pseudoCache.set(host, layers);
   return layers;
@@ -574,8 +580,11 @@ export function pseudoBackdropForText(element) {
       const { rect, color, imageCss } = layer;
       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) { image = { css: imageCss, element: node }; settled = true; continue; }
+      // caller rather than giving up on the whole element. The pseudo's box
+      // and image geometry travel with it: covering the sample point is a
+      // fact about the BOX, and a no-repeat icon may still paint nowhere
+      // near the text.
+      if (imageCss) { image = { css: imageCss, element: node, box: rect, meta: layer.imageMeta }; settled = true; continue; }
       if (!color || color.a === 0) continue;
       acc = acc ? composite(acc, color) : color;
       if (acc.a >= 1) settled = true;
@@ -945,7 +954,13 @@ export function imageLuminanceRange(url, overlays = []) {
         let minColor = null;
         let maxColor = null;
         let opaquePixels = 0;
+        let alphaSeen = false;
         for (let i = 0; i < data.length; i += 4) {
+          // Any see-through pixel means part of this layer shows whatever is
+          // painted beneath it — the sampled range alone then describes only
+          // the ink, not the backdrop the eye meets. Callers widen the range
+          // with the underlying paint (rangeWithBackdrop) or abstain.
+          if (data[i + 3] < 255) alphaSeen = true;
           if (data[i + 3] < 128) continue; // mostly-transparent pixels reveal what's beneath — unknowable
           opaquePixels += 1;
           // Composite each pixel through anything painted between the image
@@ -973,7 +988,7 @@ export function imageLuminanceRange(url, overlays = []) {
           return;
         }
         resolve(min <= max
-          ? { min, max, minColor, maxColor, width: img.naturalWidth, height: img.naturalHeight }
+          ? { min, max, minColor, maxColor, hasAlpha: alphaSeen, width: img.naturalWidth, height: img.naturalHeight }
           : null);
       } catch {
         resolve(null); // tainted canvas: cross-origin image without CORS headers
@@ -1090,17 +1105,34 @@ function splitLayers(value) {
 export function backgroundImagePaintRect(element, intrinsic) {
   const style = getComputedStyle(element);
   if ((style.backgroundImage.match(/url\(|gradient\(/g) ?? []).length !== 1) return null;
-  if (style.backgroundRepeat !== 'no-repeat') return null; // may tile under the text
-  if (style.backgroundSize === 'cover' || style.backgroundSize === 'contain') return null;
   const box = element.getBoundingClientRect();
+  return imagePaintRectInBox(
+    { left: box.left, top: box.top, right: box.right, bottom: box.bottom },
+    { repeat: style.backgroundRepeat, size: style.backgroundSize, position: style.backgroundPosition },
+    intrinsic,
+  );
+}
+
+/**
+ * The same paint-rect math for any painting box a caller already has —
+ * above all a pseudo-element's resolved box, which no element rect can
+ * describe. Returns null when the geometry is not statically knowable
+ * (tiling, cover/contain, keyword positions).
+ */
+export function imagePaintRectInBox(box, meta, intrinsic) {
+  if (!box || !meta) return null;
+  if (meta.repeat !== 'no-repeat') return null; // may tile under the text
+  if (meta.size === 'cover' || meta.size === 'contain') return null;
+  const boxWidth = box.right - box.left;
+  const boxHeight = box.bottom - box.top;
   const dimension = (value, total, auto) => {
     if (value?.endsWith('px')) return parseFloat(value);
     if (value?.endsWith('%')) return (parseFloat(value) / 100) * total;
     return auto;
   };
-  const size = style.backgroundSize.split(' ');
-  const width = dimension(size[0], box.width, intrinsic?.width);
-  const height = dimension(size[1] ?? size[0], box.height, intrinsic?.height);
+  const size = meta.size.split(' ');
+  const width = dimension(size[0], boxWidth, intrinsic?.width);
+  const height = dimension(size[1] ?? size[0], boxHeight, intrinsic?.height);
   if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
   // position N% aligns the image's N% point with the container's N% point.
   // Anything else (calc() from three-value syntax, keywords) is not
@@ -1111,15 +1143,41 @@ export function backgroundImagePaintRect(element, intrinsic) {
     if (value?.endsWith('px')) return parseFloat(value);
     return null;
   };
-  const pos = style.backgroundPosition.split(' ');
-  const offsetX = offset(pos[0], box.width, width);
-  const offsetY = offset(pos[1] ?? '50%', box.height, height);
+  const pos = meta.position.split(' ');
+  const offsetX = offset(pos[0], boxWidth, width);
+  const offsetY = offset(pos[1] ?? '50%', boxHeight, height);
   if (offsetX === null || offsetY === null || Number.isNaN(offsetX) || Number.isNaN(offsetY)) return null;
   const left = box.left + offsetX;
   const top = box.top + offsetY;
   return { left, top, right: left + width, bottom: top + height };
 }
 
+/**
+ * Widen a sampled luminance range with the layer painted beneath the image,
+ * for images that do not cover their box with opaque pixels (hasAlpha).
+ * A semi-transparent pixel blends per channel between its own colour and
+ * the underlying paint, and luminance is monotone in each channel, so a
+ * range extended with the underlying colour bounds every blend the eye can
+ * meet. Returns null when the underlying paint is unknown or itself
+ * see-through: no bound exists then, and the caller must not assert either
+ * verdict from the ink pixels alone — a mostly-transparent illustration
+ * sampled dark was asserting failures for text that really sat on the white
+ * showing through it.
+ */
+export function rangeWithBackdrop(range, under, overlays = []) {
+  if (!range || !range.hasAlpha) return range;
+  if (!under || under.a < 1) return null;
+  const shown = overlays.length ? applyOverlays(under, overlays) : under;
+  const underLum = luminance(shown);
+  return {
+    ...range,
+    min: Math.min(range.min, underLum),
+    max: Math.max(range.max, underLum),
+    minColor: underLum < range.min ? shown : range.minColor,
+    maxColor: underLum > range.max ? shown : range.maxColor,
+  };
+}
+
 /**
  * Luminance range of a CSS gradient, from its colour stops. Interpolated
  * colours stay close enough to their stops' luminances to bracket.

package/engine/lib/dom.js

@@ -106,6 +106,17 @@ export function htmlSnippet(element, maxLength = 300) {
   return html.length > maxLength ? `${html.slice(0, maxLength)}…` : html;
 }
 
+/** True when the document renders embedded inside another page (iframe or
+ *  frame). WCAG defines a "Web page" as a NON-embedded resource, so the
+ *  page-level criteria (2.4.2 Page Titled, 2.4.1 Bypass Blocks) judge only
+ *  the document the user actually opened: an embedded frame owes an
+ *  accessible name under 4.1.2, not its own <title> or skip link. The
+ *  reference comparison is safe cross-origin; frameElement is not. */
+export function isEmbeddedDocument(doc) {
+  const win = doc?.defaultView;
+  return !!(win && win.top && win !== win.top);
+}
+
 /** The element's own (not descendant-element) text, trimmed. */
 export function ownText(element) {
   return [...element.childNodes]

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

@@ -1,8 +1,9 @@
 // WCAG SC 1.4.3 Contrast (Minimum) (Level AA)
 import {
   parseColor, contrastRatio, composite, effectiveBackground, backgroundObscured,
-  backgroundImageSource, backgroundImagePaintRect, imageLuminanceRange, gradientLuminanceRange,
-  rangeVerdict, isLargeText, cumulativeOpacity, opacityAnimating, restingOpacity, mediaRects,
+  backgroundImageSource, backgroundImagePaintRect, imagePaintRectInBox, imageLuminanceRange,
+  gradientLuminanceRange, rangeVerdict, rangeWithBackdrop, isLargeText, cumulativeOpacity,
+  opacityAnimating, restingOpacity, mediaRects,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
 } from '../../lib/contrast.js';
@@ -187,11 +188,29 @@ function unaccountedScrim(element, imageCarrier) {
  *  changing it, so the callers step over it rather than reporting on it. */
 const PAINTS_NOTHING = Symbol('fully transparent image layer');
 
+/** The flat paint directly beneath a carrier's background-image: the
+ *  carrier's own background-color composited over whatever resolves behind
+ *  the carrier. This is what shows through the image's transparent pixels.
+ *  Null when it is itself unknowable (another image or an unresolvable
+ *  chain behind) — the sampling then has no floor to extend its range with. */
+function paintUnderImage(carrier) {
+  const color = parseColor(getComputedStyle(carrier).backgroundColor);
+  if (color && color.a >= 1) return color;
+  const parent = carrier.parentElement ?? carrier.getRootNode()?.host ?? null;
+  const behind = parent ? effectiveBackground(parent) : null;
+  if (!behind) return null;
+  return color && color.a > 0 ? composite(color, behind) : behind;
+}
+
 // Bracket the verdict by sampling what's actually painted: image pixels
 // (same-origin/CORS only) or gradient colour stops. Returns an outcome,
 // PAINTS_NOTHING, or null when nothing here can be sampled at all (stacked
 // layers, translucent gradient stops) and the caller must say so itself.
-async function sampledVerdict(source, foreground, required, doc, overlays = []) {
+// `under` is the colour painted beneath the sampled layer, when the caller
+// knows it: an image with see-through pixels shows that colour wherever the
+// ink is absent, so the judged range must include it — and without it no
+// verdict can be asserted from such an image at all.
+async function sampledVerdict(source, foreground, required, doc, overlays = [], under = null) {
   if (!source) return null;
   let range = null;
   let what = 'image';
@@ -216,6 +235,19 @@ async function sampledVerdict(source, foreground, required, doc, overlays = [])
   // Checked before the text's own alpha: there is no blend to reason about
   // when the layer paints nothing.
   if (range?.transparent) return PAINTS_NOTHING;
+  // See-through pixels reveal the layer beneath: widen the range with it
+  // when it is known; when it isn't, the ink pixels alone prove nothing —
+  // a mostly-transparent illustration sampled dark was failing text that
+  // really sat on the white showing through it.
+  if (range?.hasAlpha) {
+    range = rangeWithBackdrop(range, under, overlays);
+    if (!range) {
+      return {
+        status: 'incomplete',
+        message: `The ${what} behind this text has transparent regions, so parts of the text sit on whatever is painted beneath it, and that layer could not be resolved — check the contrast by eye.`,
+      };
+    }
+  }
   // Translucent text takes its presented colour from the very pixels
   // 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.
@@ -270,11 +302,16 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
   tags,
   help,
   helpUrl,
-  // div included deliberately: real-world layouts put lots of text in bare
-  // divs; the own-text check below keeps wrapper divs out of the results.
+  // Every element except the ones whose text is judged elsewhere or isn't
+  // CSS-colour text at all: a tag allow-list silently skipped visible text
+  // in anything it forgot (form, center, font, custom elements — Hacker
+  // News writes "Search:" directly inside <form>), and the own-text check
+  // below keeps the empty wrappers out of the results either way. Form
+  // controls stay out because control-contrast judges their text; SVG/MathML
+  // stay out because their glyphs are painted by fill, not color.
   selector:
-    'p, span, a, li, td, th, dt, dd, h1, h2, h3, h4, h5, h6, label, button, legend, caption, ' +
-    'figcaption, div, blockquote, small, strong, em, b, i, code, pre, time, cite, q, summary',
+    '*:not(script):not(style):not(noscript):not(title):not(option):not(optgroup)' +
+    ':not(input):not(textarea):not(select):not(svg):not(svg *):not(math):not(math *)',
   visibility: 'visual', // contrast is seen by sighted users even in aria-hidden content
   async evaluate(element, { ownText }) {
     if (!ownText(element)) return { status: 'pass' }; // no text of its own to judge
@@ -352,7 +389,8 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
         // imageSource.overlays are the translucent layers painted between the
         // image and this text (hero scrims, tint panels). Judging the raw
         // image pixels would describe a page the user never sees.
-        let sampled = await sampledVerdict(imageSource, foreground, required, doc, imageSource.overlays);
+        let sampled = await sampledVerdict(imageSource, foreground, required, doc, imageSource.overlays,
+          paintUnderImage(imageSource.element));
         // A layer with no opaque pixels changes nothing about what is behind
         // the glyphs, so it must not block the verdict: fall through and
         // judge the background that actually paints.
@@ -440,7 +478,32 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // genuine 4.1:1 failure drowned among 163 siblings that were fine.
     const pseudoResolved = pseudoBackdropForText(element);
     const film = pseudoResolved?.film ?? 0;
-    const pseudoBack = pseudoResolved?.color || pseudoResolved?.image ? pseudoResolved : null;
+    let pseudoBack = pseudoResolved?.color || pseudoResolved?.image ? pseudoResolved : null;
+    // The pseudo's BOX covering the text says nothing about its IMAGE doing
+    // so: a no-repeat url() paints its intrinsic rect inside that box (a
+    // menu item's ::before arrow icon in a box that spans the whole item).
+    // When that rect is computable and provably misses every text box, the
+    // icon sits beside the text, not behind it — the layer is not a
+    // backdrop at all. And an icon-sized image that IS under a text corner
+    // may flag for eyes, never assert: the same discipline the element
+    // background-image path has always applied.
+    let pseudoIconScale = false;
+    if (pseudoBack?.image?.meta && pseudoBack.image.box) {
+      const pseudoUrl = pseudoBack.image.css.match(/url\(["']?(.*?)["']?\)/)?.[1];
+      if (pseudoUrl && pseudoBack.image.meta.repeat === 'no-repeat') {
+        let pseudoIntrinsic = null;
+        try { pseudoIntrinsic = await imageLuminanceRange(new URL(pseudoUrl, doc.baseURI).href); } catch { /* unknowable */ }
+        const dimensionless = !pseudoIntrinsic || !pseudoIntrinsic.width
+          || (pseudoIntrinsic.width === 300 && pseudoIntrinsic.height === 150);
+        const paint = imagePaintRectInBox(pseudoBack.image.box, pseudoBack.image.meta, dimensionless ? null : pseudoIntrinsic);
+        if (paint && !paint.empty && !textIntersects(element, paint)) {
+          pseudoBack = null; // paints clear of the glyphs — judge what's beneath
+        } else {
+          pseudoIconScale = dimensionless
+            || (pseudoIntrinsic.width <= 32 && pseudoIntrinsic.height <= 32);
+        }
+      }
+    }
     const filmIncomplete = {
       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.',
@@ -460,10 +523,21 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // 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);
+      // Beneath the pseudo's paint sits its own host's background — a
+      // ::before draws above the host's background and below everything
+      // else, so the host's resolved colour is what shows through any
+      // transparent pixels the image has.
+      const sampled = await sampledVerdict(pseudoBack.image, foreground, required, doc, [],
+        effectiveBackground(pseudoBack.image.element));
       // PAINTS_NOTHING: the pseudo-element's image is fully transparent, so
       // it never displaced the background the walk resolved.
       if (sampled !== PAINTS_NOTHING) {
+        if (sampled?.status === 'fail' && pseudoIconScale) {
+          return {
+            status: 'incomplete',
+            message: 'A small icon is painted by a pseudo-element on this element — if it sits beside the text rather than under it, judge the contrast against the plain background by eye.',
+          };
+        }
         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.',
@@ -530,6 +604,16 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // gradient canvas under its hero heading is exactly this shape), so
     // even verified verdicts must be bracketed against them.
     const backdropHazard = (direction, blindOnly) => {
+      // An element's OWN opaque background sits directly beneath its own
+      // text: no non-descendant layer can paint between the two, and
+      // descendant media is already excluded below — so however the page
+      // stacks around it, the resolved colour is the presented one. Without
+      // this, every below-the-fold category chip painted over a card
+      // thumbnail (white-on-red at a flat 3.99:1) sat in the review lane
+      // because the offscreen hit-test could not verify what geometry
+      // already proves.
+      const ownPaint = parseColor(style.backgroundColor);
+      if (ownPaint && ownPaint.a >= 1) return null;
       // One box read for the element, then pure rect math per candidate —
       // this runs for every unverified element on the page.
       const box = element.getBoundingClientRect();

package/engine/rules/wcag/1.4.4-meta-viewport.js

@@ -1,4 +1,6 @@
 // WCAG SC 1.4.4 Resize Text (Level AA)
+import { isEmbeddedDocument } from '../../lib/dom.js';
+
 export default {
   id: 'meta-viewport',
   impact: 'critical',
@@ -8,6 +10,10 @@ export default {
   selector: 'meta[name="viewport"]',
   visibleOnly: false,
   evaluate(element) {
+    // Browsers read the viewport meta of the TOP document only; one inside
+    // an embedded frame is ignored wholesale, so it cannot stop anyone
+    // zooming and must not be reported as if it did.
+    if (isEmbeddedDocument(element.ownerDocument)) return { status: 'pass' };
     const content = element.getAttribute('content') ?? '';
     const disablesZoom = /user-scalable\s*=\s*(no|0)/i.test(content);
     const maxScale = content.match(/maximum-scale\s*=\s*([\d.]+)/i);

package/engine/rules/wcag/2.4.1-bypass-blocks.js

@@ -1,5 +1,5 @@
 // WCAG SC 2.4.1 Bypass Blocks (Level A)
-import { collectRoots } from '../../lib/dom.js';
+import { collectRoots, isEmbeddedDocument } from '../../lib/dom.js';
 
 export default {
   id: 'bypass-blocks',
@@ -10,6 +10,11 @@ export default {
   selector: 'html',
   visibleOnly: false,
   evaluate(element) {
+    // 2.4.1 governs blocks "repeated on multiple Web pages", and a WCAG
+    // Web page is a non-embedded resource: an embedded frame's document
+    // owes no skip link of its own (the frame's title is itself the bypass
+    // the spec names in H64).
+    if (isEmbeddedDocument(element.ownerDocument)) return { status: 'pass' };
     // 2.4.1's sufficient techniques: a skip link, landmarks (ARIA11), or
     // headings (H69) — any one mechanism satisfies the criterion. Modern
     // component pages keep ALL of these inside open shadow roots (the

package/engine/rules/wcag/2.4.2-document-title.js

@@ -14,6 +14,8 @@
 // Deliberately NOT judged: whether a real-looking title matches the page it
 // sits on. That needs someone who can read the page, and guessing at it
 // would produce exactly the confident-but-wrong findings this engine avoids.
+import { isEmbeddedDocument } from '../../lib/dom.js';
+
 const PLACEHOLDER = new Set([
   'untitled document', 'untitled page', 'untitled-1', 'untitled 1',
   'new document', 'new page', 'new tab', 'no title',
@@ -37,6 +39,11 @@ export default {
   selector: 'html',
   visibleOnly: false,
   evaluate(element) {
+    // 2.4.2 applies to "Web pages", which the spec defines as non-embedded
+    // resources. A widget or ad iframe is part of the page, not a page:
+    // demanding a <title> of it invents failures on every embedded frame
+    // (its name comes from the iframe's title attribute, judged by 4.1.2).
+    if (isEmbeddedDocument(element.ownerDocument)) return { status: 'pass' };
     const title = element.ownerDocument.title.trim();
     if (!title) {
       return {

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

@@ -32,6 +32,20 @@ const TARGETS = 'a[href], button, input, select, [role="button"], [role="link"]'
 function isHiddenFromPointer(element, rect) {
   if (rect.width <= 1 || rect.height <= 1) return true;
   if (rect.right <= 0 || rect.bottom <= 0) return true; // parked above/left of the canvas
+  // Parked BEYOND the document's scrollable extent on the other two sides:
+  // the slide-in drawer pattern (basket/menu panels held at
+  // translateX(100%) until opened). A fixed drawer does not extend the
+  // document's scroll range, so no scroll position ever brings the pointer
+  // to it — its dozen stacked links are not pointer targets in this state,
+  // and they must not crowd the page's real targets either. In-flow content
+  // that genuinely overflows DOES extend scrollWidth/scrollHeight and keeps
+  // being judged.
+  const win = element.ownerDocument.defaultView;
+  const scroller = element.ownerDocument.scrollingElement ?? element.ownerDocument.documentElement;
+  if (win && scroller) {
+    if (rect.left + win.scrollX >= scroller.scrollWidth - 1) return true;
+    if (rect.top + win.scrollY >= scroller.scrollHeight - 1) return true;
+  }
   const style = getComputedStyle(element);
   if ((parseFloat(style.opacity) || 0) === 0) return true;
   if (style.clipPath !== 'none' || (style.clip !== 'auto' && style.position === 'absolute')) return true;

package/engine/rules/wcag/4.1.2-aria-label-misuse.js

@@ -2,19 +2,27 @@
 // element does not support name from author. Authors MUST NOT use the
 // aria-label or aria-labelledby attributes to name the element." A label on
 // a plain div/span/p breaks that MUST, so it is a real, provable authoring
-// error — and browsers respond by dropping the prohibited name, which is
-// exactly what makes the WCAG verdict undecidable from the DOM.
+// error.
 //
-// It is not, on its own, a 4.1.2 failure. A static text container is not a
-// "user interface component", and the dropped name leaves whatever name,
-// role and value the element legitimately has untouched. Nothing is
-// announced wrongly; nothing the criterion requires is provably absent.
+// What browsers DO with the prohibited name was measured, not assumed
+// (2026-08-09, Chromium accessibility tree + VoiceOver on a live product
+// page): both expose aria-label on paragraph/generic/strong as the
+// element's accessible name, and VoiceOver announces it. So the label is
+// NOT reliably dropped — the earlier wording here claimed it was, and a
+// user who tested with a screen reader rightly called it misleading. But
+// prohibited means unguaranteed: exposure of a name the spec forbids is
+// browser goodwill, varies across AT pairings, and may change without
+// notice. A page can neither rely on the label being announced nor on it
+// being ignored — which cuts in both directions and is exactly what makes
+// the WCAG verdict undecidable from the DOM.
 //
-// What CAN fail is the thing underneath: if the author reached for a label
-// because assistive technology genuinely should announce this element — a
-// hand-rolled widget missing its role, a region missing its landmark — then
-// the name they wrote is invisible and the missing role is the defect.
-// Whether that is so is exactly what the DOM cannot establish.
+// It is not, on its own, a 4.1.2 failure. A static text container is not a
+// "user interface component", and whatever name, role and value the element
+// legitimately has stays untouched. Where the label IS announced, it
+// replaces the element's visible text for AT users (sometimes deliberately:
+// a price written for the ear over a struck-through visual price); where it
+// is ignored, users get the visible text alone. The human question is
+// whether either presentation is wrong for this element.
 //
 // This rule has lived on both sides of the line. It asserted under WCAG
 // scope originally, was demoted to best-practice when an independent audit
@@ -36,7 +44,7 @@ export default {
   id: 'aria-label-misuse',
   impact: 'moderate',
   tags: ['wcag2a', 'wcag412'],
-  help: 'aria-label on a generic element is dropped by the browser',
+  help: 'aria-label on a plain container is prohibited by ARIA, so its announcement is not guaranteed',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: 'div[aria-label]:not([role]):not([tabindex]), span[aria-label]:not([role]):not([tabindex]), p[aria-label]:not([role]):not([tabindex])',
   evaluate(element) {
@@ -48,8 +56,8 @@ export default {
     if (element.closest(NAME_FROM_CONTENT)) return { status: 'pass' };
     return {
       status: 'incomplete',
-      message: `aria-label="${element.getAttribute('aria-label')}" on a plain <${element.tagName.toLowerCase()}> is prohibited by ARIA and dropped by the browser, so assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. Should this element be announced? If it plays a role worth naming — a widget, a region, a group — the missing role is the defect and this is a 4.1.2 failure. If it is just a styled container, the attribute is stray and no one is affected.`,
-      fix: 'If the element should be announced, give it the role it is playing (a landmark, group, or widget role) so the name is legal and exposed. If it should not, remove the aria-label. Do not add a role solely to legalise the label.',
+      message: `aria-label="${element.getAttribute('aria-label')}" on a plain <${element.tagName.toLowerCase()}> is prohibited by ARIA: this element's role does not support naming, so although many browser and screen reader pairings announce the label today, that support is not guaranteed anywhere and can differ between assistive technologies. Where it is announced it replaces the element's visible text; where it is not, users get the visible text alone. Check both presentations read correctly, and that nothing here relies on the label being heard.`,
+      fix: 'If this element must reliably announce something of its own, give it the role it is playing (a landmark, group, or widget role) so the name is legal and exposure is guaranteed — or move the spoken text into visible or visually-hidden real text. If the label is stray, remove it. Do not add a role solely to legalise the label.',
     };
   },
 };

package/package.json

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