pour-engine 1.42.4 → 1.43.0

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -113,7 +113,7 @@ meaning that only a person can settle, even where a rule decides most real pages
 
 | SC | Name | Level | Coverage | Rules |
 |---|---|---|---|---|
-| 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-label-misuse, aria-valid-refs, button-name, composite-widget-name, frame-title, invoker-target, label-for-valid, nested-interactive, role-required-aria, summary-name, valid-role |
+| 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-label-misuse, aria-state-unreachable, aria-valid-refs, button-name, composite-widget-name, frame-title, invoker-target, label-for-valid, nested-interactive, role-required-aria, summary-name, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
-**Totals:** 51 partially automated · 35 manual — with 98 rules.
+**Totals:** 51 partially automated · 35 manual — with 99 rules.

package/engine/README.md

@@ -117,7 +117,7 @@ assessment, including interaction states and any checks reported as skipped.
 
 ## Honest current state
 
-98 rules, hardened on real sites and the `testbeds/` pages. Audits walk into
+99 rules, hardened on real sites and the `testbeds/` pages. Audits walk into
 open shadow roots (targets come back as `host >>> inner` selector chains);
 iframe traversal is the host's job, and the extension does it. Known gaps:
 the full accname spec (ours is a close approximation) and the language

package/engine/lib/contrast.js

@@ -101,6 +101,14 @@ export function contrastRatio(foreground, background) {
  * (no text threshold lives up there), and "21:1" reads better than
  * "21.0:1" — a trailing zero implies precision the eye can use.
  */
+/** 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). Shared by the text and
+ *  the form-control contrast rules (2026-09-17). */
+const channelText = (value) => String(Math.round(value * 100) / 100);
+export const asRgb = (color) => `rgb(${channelText(color.r)}, ${channelText(color.g)}, ${channelText(color.b)})`;
+
 export function showRatio(ratio) {
   const text = ratio >= 10
     ? (Math.floor(ratio * 10) / 10).toFixed(1)

package/engine/rules/index.js

@@ -42,13 +42,13 @@ import audioControl from './wcag/1.4.2-audio-control.js';
 import pauseStopHide from './wcag/2.2.2-pause-stop-hide.js';
 import mediaCaptions from './wcag/1.2.2-media-captions.js';
 import ariaAttrValid from './wcag/4.1.2-aria-attr-valid.js';
-// Reviews rather than asserts: an unsupported ARIA attribute breaks an ARIA
-// author MUST (1.2 §8.6) but is INERT, so name, role and value all survive
-// and no success criterion provably fails. It sits in the WCAG scope anyway,
-// because a real authoring error that a browser silently discards should not
-// be invisible in a default audit, and it asks whether the state is real
-// instead of claiming a failure (see the note in the rule file).
+// An unsupported ARIA attribute breaks an ARIA author MUST (1.2 §8.6) but is
+// INERT, so name, role and value survive: asserted at minor since 2026-09-17
+// (it reviewed before). Where the DOM proves the element really has the
+// state (a native readonly, required, disabled or checked beside the aria-
+// attribute) the finding is aria-state-unreachable's, at moderate.
 import ariaAllowedAttr from './wcag/4.1.2-aria-allowed-attr.js';
+import ariaStateUnreachable from './wcag/4.1.2-aria-state-unreachable.js';
 import ariaFieldName from './wcag/4.1.2-aria-field-name.js';
 // Asks instead of asserting: a prohibited name on a generic element is a
 // real ARIA MUST violation the browser silently drops, so it runs in the
@@ -191,6 +191,7 @@ export default [
   mediaCaptions,
   ariaAttrValid,
   ariaAllowedAttr,
+  ariaStateUnreachable,
   ariaFieldName,
   ariaLabelMisuse,
   roleRequiredAria,

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

@@ -6,7 +6,7 @@ import {
   opacityAnimating, restingOpacity, mediaRects, inZeroClipSubtree,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
-  showRatio, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors, BOLD_WEIGHT, hasPaintEffects, isolatedBlendBackdrop } from '../../lib/contrast.js';
+  showRatio, asRgb, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors, BOLD_WEIGHT, hasPaintEffects, isolatedBlendBackdrop } from '../../lib/contrast.js';
 
 /** The first url() among a background-image list's layers, or null. */
 const firstLayerUrl = (css) => splitBackgroundLayers(css ?? '').map(backgroundLayerUrl).find(Boolean) ?? null;
@@ -20,12 +20,6 @@ const extentOf = (rect) => (rect ? { width: rect.right - rect.left, height: rect
  *  every character that carries grouping, rating or code meaning. */
 const SEPARATOR_GLYPHS = /^([|¦·•∙‧/⁄\\‐‑‒–—―⁃«»‹›-])\1*$/;
 
-/** 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,

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

@@ -5,7 +5,7 @@
 import {
   parseColor, contrastRatio, composite, effectiveBackground, isLargeText,
   backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity, showRatio,
-  hasPaintEffects, opacityGroupPaint, splitBackgroundLayers, sampledGradientRange,
+  hasPaintEffects, opacityGroupPaint, splitBackgroundLayers, sampledGradientRange, asRgb,
 } from '../../lib/contrast.js';
 
 export default {
@@ -108,7 +108,7 @@ export default {
         if (group?.unresolved) { unresolvedGroup = true; return null; }
         if (group) {
           const ratio = contrastRatio(group.foreground, group.background);
-          return ratio >= required ? null : { what, ratio };
+          return ratio >= required ? null : { what, ratio, fg: group.foreground, bg: group.background };
         }
       }
       const painted = opacity * ownOpacity;
@@ -116,7 +116,7 @@ export default {
       const fg = faded.a < 1 ? composite(faded, background) : faded;
       const ratio = contrastRatio(fg, background);
       if (ratio >= required) return null;
-      return { what, ratio };
+      return { what, ratio, fg, bg: background };
     };
 
     const failures = [];
@@ -151,8 +151,11 @@ export default {
     return {
       status: 'fail',
       message: `This field's ${worst.what} has ${showRatio(worst.ratio)}:1 contrast against the field background — below the ${required}:1 minimum.`,
-      fix: `Darken the ${worst.what.includes('placeholder') ? 'placeholder colour (::placeholder)' : 'text colour'} until it reaches ${required}:1 against the field background.`,
-      data: { ratio: Number(showRatio(worst.ratio)), required },
+      fix: `Darken the ${worst.what.includes('placeholder') ? 'placeholder colour (::placeholder)' : 'text colour'} until it reaches ${required}:1 against the field background (currently ${asRgb(worst.fg)} on ${asRgb(worst.bg)}).`,
+      // The judged pair, as the text rule reports it, so the UIs can link
+      // out to the checker with it (the link was missing on this rule's
+      // findings until 2026-09-17: it carried the ratio and nothing else).
+      data: { foreground: asRgb(worst.fg), background: asRgb(worst.bg), ratio: Number(showRatio(worst.ratio)), required },
     };
   },
 };

package/engine/rules/wcag/4.1.2-aria-allowed-attr.js

@@ -1,30 +1,33 @@
 // ARIA 1.2 §8.6, repeated verbatim in the 1.3 draft: "authors MUST only use
 // non-global states and properties on elements with a role supporting the
 // state or property". An unsupported attribute breaks that MUST, so this is a
-// real, provable authoring error and the rule asserts it.
+// real, provable authoring error, and since 2026-09-17 the rule asserts it
+// as a violation at minor impact (David: invalid according to the spec is
+// marked as such, low). It reviewed until then, on the reasoning below,
+// which still decides the impact.
 //
-// It is not, on its own, a WCAG failure. An unsupported attribute is INERT,
-// measured in Chromium: aria-expanded on a button exposes expanded=true,
-// while the same attribute on complementary, heading or list exposes no
-// state at all. It is dropped, not misreported. So the role is still
-// exposed, the name is still computed, and nothing is announced incorrectly.
-// Name, role and value all survive, which is all 4.1.2 asks for.
+// An unsupported attribute is INERT under Core-AAM: user agents expose the
+// states and properties a role supports, so aria-expanded on a button
+// reaches assistive technology as expanded=true while the same attribute on
+// complementary, heading or list reaches nothing (Chromium measured the
+// same, as a starting point, not the arbiter). It is dropped, not
+// misreported. The role is still exposed, the name is still computed, and
+// nothing is announced incorrectly, which is why the impact is minor and
+// not serious.
 //
-// What CAN fail 4.1.2 is the thing underneath: if the element genuinely has
-// the state the author reached for, that state is now invisible to a screen
-// reader. Whether it does is exactly what the DOM cannot establish.
-//
-// So this sits in the WCAG scope and REVIEWS rather than asserts. It lived
-// under best-practice before, which was defensible on the letter of 4.1.2
-// and wrong in practice: teams act on what a tool marks as WCAG, so a real
-// ARIA error that a browser silently discards went unseen in a default
-// audit. Asserting a violation would state a criterion failure the browser
-// does not actually cause; staying silent leaves a genuine authoring error
-// unreported. Asking is the honest third option, and it is the one the
-// engine is built around.
+// What makes it more than a slip is the thing underneath: if the element
+// genuinely has the state the author reached for, that state is now
+// invisible to a screen reader, and that is a 4.1.2 failure in the full
+// sense. The DOM sometimes proves it: a native readonly, required, disabled
+// or checked attribute beside the aria- one (a text input given
+// role="region" with readonly and aria-readonly on privatebanking.hsbc.com,
+// 2026-09-17). Those attributes belong to aria-state-unreachable, which
+// asserts them at moderate; this rule leaves them to it so an element gets
+// one finding per attribute, and keeps the stray ones.
 //
 // Note "unsupported" is distinct from "prohibited" (§5.2.5), a separate
-// category about naming that this rule does not cover.
+// category about naming that this rule does not cover; aria-label and
+// aria-labelledby misuse have their own rule.
 //
 // Worth knowing when comparing against other tools: aria-expanded WAS
 // inherited into complementary, banner, heading, img and list under ARIA 1.1,
@@ -38,38 +41,51 @@ import { GLOBAL_ARIA, ROLE_ARIA, KNOWN_ARIA, effectiveRole } from '../../lib/rol
 // (aria-label-misuse) — excluded here to avoid double-reporting.
 const HANDLED_ELSEWHERE = new Set(['label', 'labelledby']);
 
+// aria- states whose native HTML attribute of the same name proves the
+// element really has the state the unsupported attribute was reaching for.
+// Those are aria-state-unreachable's, which imports this.
+export const NATIVE_STATE = { readonly: 'readonly', required: 'required', disabled: 'disabled', checked: 'checked' };
+
+/** The element's role and the non-global aria- attributes (names without
+ *  the prefix) that role does not support, or null when there are none or
+ *  the role is not modelled. Shared with aria-state-unreachable. */
+export function unsupportedAria(element) {
+  const ariaAttrs = [];
+  for (const { name } of attributesOf(element)) {
+    if (!name.startsWith('aria-')) continue;
+    const attr = name.slice(5);
+    // Unknown/misspelled attributes are aria-attr-valid's finding — judging
+    // them against a role too would report the same typo twice.
+    if (!HANDLED_ELSEWHERE.has(attr) && KNOWN_ARIA.has(attr)) ariaAttrs.push(attr);
+  }
+  if (!ariaAttrs.length) return null;
+  const role = effectiveRole(element);
+  const allowed = role && ROLE_ARIA[role];
+  if (!allowed) return null; // role not modelled: don't guess
+  const names = ariaAttrs.filter((name) => !GLOBAL_ARIA.has(name) && !allowed.includes(name));
+  return names.length ? { role, names } : null;
+}
+
 export default {
   id: 'aria-allowed-attr',
   name: 'Allowed ARIA attributes',
-  impact: 'moderate',
+  impact: 'minor',
   tags: ['wcag2a', 'wcag412'],
   help: 'ARIA attributes must be supported by the element’s role',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: '*',
   visibleOnly: false,
   evaluate(element) {
-    // Plain loop, no intermediate arrays: this runs on every element of the
-    // page, and nearly all have no aria-* attributes at all.
-    const ariaAttrs = [];
-    for (const { name } of attributesOf(element)) {
-      if (!name.startsWith('aria-')) continue;
-      const attr = name.slice(5);
-      // Unknown/misspelled attributes are aria-attr-valid's finding — judging
-      // them against a role too would report the same typo twice.
-      if (!HANDLED_ELSEWHERE.has(attr) && KNOWN_ARIA.has(attr)) ariaAttrs.push(attr);
-    }
-    if (!ariaAttrs.length) return { status: 'pass' };
-
-    const role = effectiveRole(element);
-    const allowed = role && ROLE_ARIA[role];
-    if (!allowed) return { status: 'pass' }; // role not modelled: don't guess
-
-    const disallowed = ariaAttrs.filter((name) => !GLOBAL_ARIA.has(name) && !allowed.includes(name));
+    const found = unsupportedAria(element);
+    if (!found) return { status: 'pass' };
+    // A state the DOM proves the element has is aria-state-unreachable's.
+    const disallowed = found.names.filter((name) => !(NATIVE_STATE[name] && element.hasAttribute(NATIVE_STATE[name])));
     if (!disallowed.length) return { status: 'pass' };
+    const role = found.role;
     const names = disallowed.map((n) => `aria-${n}`);
     return {
-      status: 'incomplete',
-      message: `${names.join(', ')} is not supported on role "${role}", so the browser drops it and assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. Does this element really have that state? If it does, it is invisible to a screen reader and this is a 4.1.2 failure. If it does not, the attribute is simply stray and no one is affected. Invalid markup is not by itself a WCAG failure: the criterion that policed validity, 4.1.1 Parsing, was removed in WCAG 2.2 (w3.org/WAI/WCAG22/Understanding/parsing.html), so what decides this is whether the state reaches users, not the syntax.`,
+      status: 'fail',
+      message: `${names.join(', ')} is not supported on role "${role}" (ARIA 1.2 §8.6), so user agents drop it and assistive technology never sees it. Nothing is announced wrongly, but nothing is announced at all. If the element really has that state, it is invisible to a screen reader; if it does not, the attribute is stray and no one is affected, but ARIA 1.2 still says authors MUST NOT write it.`,
       fix: `Move ${names.join('/')} to the element whose role supports it, usually the control that toggles this one, or remove it if the element has no such state. Adding a role to this element to make the attribute legal is rarely right: the host language restricts which roles each element may take.`,
     };
   },

package/engine/rules/wcag/4.1.2-aria-state-unreachable.js

@@ -0,0 +1,56 @@
+// WCAG SC 4.1.2 Name, Role, Value (Level A)
+// The proven half of aria-allowed-attr, split out on 2026-09-17 so it can
+// carry its own impact. That rule asserts every non-global ARIA attribute
+// an element's role does not support (ARIA 1.2 §8.6, an author MUST) at
+// minor, because such an attribute is inert: user agents expose only the
+// states a role supports, so nothing false is announced and the name and
+// role survive. Most of the time the attribute is stray and nobody is
+// affected.
+//
+// This rule fires when the DOM proves the state is real: a native readonly,
+// required, disabled or checked attribute sits beside the unsupported aria-
+// one. Then the element genuinely has the state, the host language applies
+// it, and no assistive technology can learn it through the role the author
+// chose. That is what 4.1.2 asks for and does not get, so the impact is
+// moderate: a screen reader user meets a readonly field announced as a
+// region and tries to type into it, or a required field they cannot tell is
+// required. Moderate rather than serious because the control still works
+// and its value is still there; the state is what is lost.
+//
+// The shape it was written for: four calculator output fields on
+// privatebanking.hsbc.com, <input type="text" role="region" readonly
+// aria-readonly="true">. ARIA 1.2 does not give region aria-readonly, and
+// Core-AAM maps the author's role, so the field reaches assistive
+// technology as a landmark. (ARIA in HTML also forbids region on a text
+// input, which is a role finding this rule does not make.) Decided from the
+// spec text; Chromium's tree, which exposes the region with no readonly
+// property, was the starting point and not the arbiter.
+//
+// aria-allowed-attr leaves these attributes to this rule, so an element gets
+// one finding per attribute, not two. An element with a proven state and a
+// second, unproven unsupported attribute gets one of each.
+import { unsupportedAria, NATIVE_STATE } from './4.1.2-aria-allowed-attr.js';
+
+export default {
+  id: 'aria-state-unreachable',
+  name: 'ARIA state the element really has cannot be reached',
+  impact: 'moderate',
+  tags: ['wcag2a', 'wcag412'],
+  help: 'A state the element has must be exposed through a role that supports it',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+  selector: '[aria-readonly], [aria-required], [aria-disabled], [aria-checked]',
+  visibleOnly: false,
+  evaluate(element) {
+    const found = unsupportedAria(element);
+    if (!found) return { status: 'pass' };
+    const proven = found.names.filter((name) => NATIVE_STATE[name] && element.hasAttribute(NATIVE_STATE[name]));
+    if (!proven.length) return { status: 'pass' };
+    const states = proven.map((name) => `aria-${name}`);
+    const natives = proven.map((name) => NATIVE_STATE[name]);
+    return {
+      status: 'fail',
+      message: `This element really is ${natives.join(' and ')}: its native ${natives.join(' and ')} attribute says so. But ${states.join(' and ')} is not supported on role "${found.role}" (ARIA 1.2 §8.6), so user agents drop it and assistive technology cannot learn the state. The control works, and nobody using a screen reader is told how.`,
+      fix: `Give the element a role that supports ${states.join(' and ')}, which for a form control is usually its own native role with no role attribute at all, or move the state to the element that carries the control's role. Do not add a role the host language forbids on this element to make the attribute legal.`,
+    };
+  },
+};

package/package.json

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