pour-engine 1.40.0 → 1.42.0

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

@@ -213,14 +213,13 @@ function isInTextLine(element) {
 // do not apply now are skipped, since they size nothing now.
 const NATIVE_CONTROL = /^(button|input|select|textarea)$/i;
 const SIZING = /^(width|height|(min|max)-(width|height|inline-size|block-size)|inline-size|block-size|padding(-.+)?|border(-.+)?|font(-.+)?|line-height|box-sizing|transform|scale|zoom|appearance|all)$/;
-const sizingRulesByRoot = new WeakMap();
 
 function declaresSizing(style) {
   for (let k = 0; k < style.length; k++) if (SIZING.test(style[k])) return true;
   return false;
 }
 
-function authorSizingRules(root) {
+function authorSizingRules(root, sizingRulesByRoot) {
   const sheets = [...(root.styleSheets ?? []), ...(root.adoptedStyleSheets ?? [])];
   const key = sheets.map((s) => { try { return s.cssRules.length; } catch { return 'x'; } }).join(',');
   const cached = sizingRulesByRoot.get(root);
@@ -254,10 +253,10 @@ function authorSizingRules(root) {
 /** 'yes' when the browser provably sized this native control, 'no' when the
  *  author touched its box (or it is not a native control), 'open' when a
  *  sheet or selector could not be read. */
-function uaSized(element) {
+function uaSized(element, sizingRulesByRoot) {
   if (!NATIVE_CONTROL.test(element.tagName) || element.type === 'image') return 'no';
   if (declaresSizing(element.style)) return 'no';
-  const entry = authorSizingRules(element.getRootNode());
+  const entry = authorSizingRules(element.getRootNode(), sizingRulesByRoot);
   if (entry.combined && element.matches(entry.combined)) return 'no';
   return entry.open ? 'open' : 'yes';
 }
@@ -301,7 +300,11 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
   selector: 'button, a[href], input:not([type="hidden"]), select, [role="button"], [role="link"]',
   visibility: 'visual', // pointer targets are visual regardless of aria-hidden
   // Judged as a set: the spacing exception needs the other targets' positions.
-  evaluateAll(elements) {
+  async evaluateAll(elements, helpers = {}) {
+    // Styles can change between audits without changing a sheet's rule
+    // count. This cache belongs to this evaluation, not the page lifetime.
+    const sizingRulesByRoot = new WeakMap();
+    const yieldToMain = helpers.yieldToMain ?? (() => Promise.resolve());
     // A control's <label> is part of its activation area — clicking the
     // label activates the control, so the TARGET is the union of both
     // boxes. Without this, every label-wrapped checkbox list fails on the
@@ -323,7 +326,11 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
     const uaControlled = (element) => element.tagName === 'INPUT'
       && (element.type === 'checkbox' || element.type === 'radio')
       && getComputedStyle(element).appearance !== 'none';
-    const rects = elements.map(targetRect);
+    const rects = [];
+    for (let i = 0; i < elements.length; i++) {
+      if (i % 64 === 0) await yieldToMain();
+      rects.push(targetRect(elements[i]));
+    }
     const centers = rects.map((r) => ({ x: r.left + r.width / 2, y: r.top + r.height / 2 }));
     // Zero-area rects are degenerate: either not laid out, or an empty
     // control no pointer can hit at all — its real defect (an empty name,
@@ -352,9 +359,13 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
     // judged nor counted as crowders (bbc.com/news keeps 28 controls of a
     // closed menu in an inert subtree; the browser ignores every click on
     // them, and so must the size judgment).
-    const laidOut = rects.map((r, i) =>
-      r.width > 0 && r.height > 0 && !isInert(elements[i])
-      && !isHiddenFromPointer(elements[i], r) && !layoutSkipped(elements[i]));
+    const laidOut = [];
+    for (let i = 0; i < elements.length; i++) {
+      if (i % 64 === 0) await yieldToMain();
+      const r = rects[i], element = elements[i];
+      laidOut.push(r.width > 0 && r.height > 0 && !element.matches(':disabled') && !isInert(element)
+        && !isHiddenFromPointer(element, r) && !layoutSkipped(element));
+    }
     const undersized = rects.map((r, i) => laidOut[i] && (r.width < min || r.height < min));
     // One rect fully inside another is one control drawn twice (stretched-
     // link cards, overlay + inner button) — not two targets crowding.
@@ -434,9 +445,10 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
       }
       return false; // neither reachable there — a third element's problem, not j's
     };
-    /** Largest uncovered sub-rectangle after removing the overlap: the best
-     *  of the four slabs beside/above/below it (exact for one obscurer,
-     *  a safe under-approximation applied sequentially for several). */
+    /** All remaining rectangular areas. The largest area is not necessarily
+     *  the one that contains the required square: 100x23 is larger than
+     *  24x50 but only the latter satisfies the AA size requirement.
+     *  Keep the alternatives until every obscurer has been subtracted. */
     const uncovered = (rect, overlap) => {
       const slabs = [
         { left: rect.left, top: rect.top, right: overlap.left, bottom: rect.bottom },
@@ -445,20 +457,20 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
         { left: rect.left, top: overlap.bottom, right: rect.right, bottom: rect.bottom },
       ].map((s) => ({ ...s, width: s.right - s.left, height: s.bottom - s.top }))
         .filter((s) => s.width >= 1 && s.height >= 1);
-      // Note: rect may be a DOMRect, whose properties do not survive object
-      // spread — the zero-rect is built from explicit reads.
-      if (!slabs.length) {
-        return { left: rect.left, top: rect.top, right: rect.left, bottom: rect.top, width: 0, height: 0 };
-      }
-      return slabs.reduce((best, s) => (s.width * s.height > best.width * best.height ? s : best));
+      return slabs;
     };
     // Spatial hash so finding overlap candidates stays near-linear on pages
     // with tens of thousands of targets: only targets sharing a cell can
     // intersect, so each target is tested against its cell-mates only.
     const CELL = 256;
-    let cellIndex = null;
+    const cellIndex = new Map();
+    const wideTargets = [];
     const cellsOf = (r) => {
       const keys = [];
+      // Huge transformed boxes must not allocate millions of cells. They
+      // remain in a separate candidate list, so the bound drops no target.
+      if ((Math.floor(r.right / CELL) - Math.floor(r.left / CELL) + 1)
+        * (Math.floor(r.bottom / CELL) - Math.floor(r.top / CELL) + 1) > 2048) return null;
       for (let cx = Math.floor(r.left / CELL); cx <= Math.floor(r.right / CELL); cx++) {
         for (let cy = Math.floor(r.top / CELL); cy <= Math.floor(r.bottom / CELL); cy++) {
           keys.push(`${cx}:${cy}`);
@@ -466,19 +478,21 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
       }
       return keys;
     };
-    const overlapCandidates = (i) => {
-      if (!cellIndex) {
-        cellIndex = new Map();
-        rects.forEach((r, j) => {
-          if (!laidOut[j]) return;
-          for (const key of cellsOf(r)) {
-            if (!cellIndex.has(key)) cellIndex.set(key, []);
-            cellIndex.get(key).push(j);
-          }
-        });
+    for (let j = 0; j < rects.length; j++) {
+      if (j % 64 === 0) await yieldToMain();
+      if (!laidOut[j]) continue;
+      const keys = cellsOf(rects[j]);
+      if (!keys) { wideTargets.push(j); continue; }
+      for (const key of keys) {
+        if (!cellIndex.has(key)) cellIndex.set(key, []);
+        cellIndex.get(key).push(j);
       }
-      const seen = new Set();
-      for (const key of cellsOf(rects[i])) {
+    }
+    const nearbyCandidates = (i, box = rects[i]) => {
+      const keys = cellsOf(box);
+      if (!keys) return elements.map((_, j) => j).filter((j) => j !== i && laidOut[j]);
+      const seen = new Set(wideTargets.filter((j) => j !== i));
+      for (const key of keys) {
         for (const j of cellIndex.get(key) ?? []) if (j !== i) seen.add(j);
       }
       return seen;
@@ -486,9 +500,10 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
     /** The pointer-accepting rect of a box-sized-fine target, reduced by
      *  every overlapping target painted above it — or null when nothing
      *  qualifying overlaps. */
-    const obscuredRect = (i) => {
-      let effective = null;
-      for (const j of overlapCandidates(i)) {
+    const obscuredRects = new Map();
+    const calculateObscuredRect = (i) => {
+      let areas = null;
+      for (const j of nearbyCandidates(i)) {
         if (elements[j].contains(elements[i]) || elements[i].contains(elements[j])) continue; // same control, nested markup
         if (encloses(rects[j], rects[i]) || encloses(rects[i], rects[j])) continue; // one control drawn twice
         // Two links to the same place are one control in two boxes (a
@@ -496,13 +511,28 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
         // land on the same destination, which is the criterion's
         // "equivalent" case, provable here because the hrefs match.
         if (typeof elements[i].href === 'string' && elements[i].href === elements[j].href) continue;
-        const overlap = overlapOf(effective ?? rects[i], rects[j]);
+        const overlap = overlapOf(rects[i], rects[j]);
         if (!overlap) continue;
         if (fixedContextOf(elements[j]) !== fixedContextOf(elements[i])) continue; // scroll-state, not layout
         if (!paintsOver(j, i, overlap)) continue;
-        effective = uncovered(effective ?? rects[i], overlap);
+        const next = (areas ?? [rects[i]]).flatMap((area) => {
+          const cut = overlapOf(area, rects[j]);
+          return cut ? uncovered(area, cut) : [area];
+        });
+        // Remove only rectangles wholly covered by another available area.
+        // No useful square is lost by this pruning.
+        areas = next.filter((area, k) => !next.some((other, n) => n !== k
+          && encloses(other, area) && (n < k || !encloses(area, other))));
+        if (areas.length > 128) return { uncertain: true };
       }
-      return effective;
+      if (areas === null) return null;
+      return areas.find((area) => area.width >= min && area.height >= min)
+        ?? areas.reduce((best, area) => area.width * area.height > best.width * best.height ? area : best,
+          { width: 0, height: 0 });
+    };
+    const obscuredRect = (i) => {
+      if (!obscuredRects.has(i)) obscuredRects.set(i, calculateObscuredRect(i));
+      return obscuredRects.get(i);
     };
 
     // ── Equivalent targets ────────────────────────────────────────────
@@ -525,21 +555,86 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
       const destination = destinationOf(elements[i]);
       if (!destination) return false;
       if (!adequateDestinations) {
-        adequateDestinations = new Set();
+        adequateDestinations = new Map();
         elements.forEach((other, j) => {
           if (!laidOut[j] || undersized[j] || other.ownerDocument !== elements[i].ownerDocument) return;
           const d = destinationOf(other);
-          if (d) adequateDestinations.add(d);
+          if (d) {
+            if (!adequateDestinations.has(d)) adequateDestinations.set(d, []);
+            adequateDestinations.get(d).push(j);
+          }
         });
       }
-      return adequateDestinations.has(destination);
+      let uncertain = false;
+      for (const j of adequateDestinations.get(destination) ?? []) {
+        if (j === i) continue;
+        // An original bounding box cannot prove a usable alternative.
+        // Otherwise two separately obscured links rescue one another even
+        // when neither retains the required square for pointer activation.
+        const area = obscuredRect(j);
+        if (area?.uncertain) { uncertain = true; continue; }
+        if (!area || (area.width >= min && area.height >= min)) return 'pass';
+      }
+      return uncertain ? 'incomplete' : null;
     };
 
-    return elements.map((element, i) => {
+    // Scripted functions have no URL identity. Matching names, declared
+    // controls or handler text identify plausible alternatives, not proven
+    // equivalence: a human must verify that both controls do the same thing.
+    // Build these indexes only when a failing scripted control needs them.
+    let alternativeKeys = null;
+    const names = new Map();
+    const nameOf = (element) => {
+      if (!names.has(element)) names.set(element, helpers.accessibleName?.(element)?.trim() ?? '');
+      return names.get(element);
+    };
+    const signatures = (element) => {
+      const keys = [];
+      const name = nameOf(element);
+      if (name) keys.push(`name:${name}`);
+      const handler = element.getAttribute('onclick')?.trim();
+      if (handler) keys.push(`handler:${handler}`);
+      const controls = element.getAttribute('aria-controls')?.trim().split(/\s+/).sort().join(' ');
+      if (controls) keys.push(`controls:${controls}`);
+      return keys;
+    };
+    const plausibleAlternative = (i) => {
+      if (destinationOf(elements[i])) return false; // URL equivalence was judged above
+      const own = signatures(elements[i]);
+      if (!own.length) return false;
+      if (!alternativeKeys) {
+        alternativeKeys = new Map();
+        elements.forEach((other, j) => {
+          if (!laidOut[j] || undersized[j] || destinationOf(other)) return;
+          const area = obscuredRect(j);
+          if (area && !area.uncertain && (area.width < min || area.height < min)) return;
+          for (const key of signatures(other)) {
+            if (!alternativeKeys.has(key)) alternativeKeys.set(key, []);
+            alternativeKeys.get(key).push(j);
+          }
+        });
+      }
+      return own.some((key) => alternativeKeys.get(key)?.some((j) => j !== i));
+    };
+    const alternativeReview = () => ({
+      status: 'incomplete',
+      message: `This control's measured pointer area is below ${min}×${min}px, but a larger control has a matching name, handler or declared target. Check whether it provides the same function and meets the target-size requirement; if so, the Equivalent exception applies.`,
+      fix: 'Verify the larger alternative, or enlarge or separate this target.',
+    });
+    const equivalentReview = () => ({
+      status: 'incomplete',
+      message: `Another link reaches the same destination, but its unobscured pointer area could not be established. Check whether that alternative meets ${min}×${min}px before applying the Equivalent exception.`,
+    });
+
+    const judge = (element, i) => {
       if (!laidOut[i]) return { status: 'pass' }; // not laid out / not a pointer target
       if (!undersized[i]) {
         // Box is big enough — but the pointer only gets the uncovered part.
         const effective = obscuredRect(i);
+        if (effective?.uncertain) return {
+          status: 'incomplete',
+          message: 'Several targets overlap this control. The remaining pointer area could not be resolved within the geometry budget; check whether it contains the required target size.',
+        };
         if (!effective || (effective.width >= min && effective.height >= min)) return { status: 'pass' };
         if (isInTextLine(element)) return { status: 'pass' };
         // A target the pointer never actually hits is a keyboard
@@ -565,6 +660,10 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
           return !tested; // nothing probe-able → don't know → don't silence
         })();
         if (!everHit) return { status: 'pass' };
+        const equivalent = equivalentElsewhere(i);
+        if (equivalent === 'pass') return { status: 'pass' };
+        if (equivalent === 'incomplete') return equivalentReview();
+        if (plausibleAlternative(i)) return alternativeReview();
         // The spacing exception cannot apply: the obscuring target is at
         // distance zero. UA-control cannot either: the browser sized the
         // box, but the author's layout took part of it away.
@@ -583,7 +682,7 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
       // The same exception for every other native control, proved from the
       // sheets; an open proof (unreadable sheet) reviews at the end instead
       // of asserting, and only if nothing else rescues the target first.
-      const uaProof = uaSized(element);
+      const uaProof = uaSized(element, sizingRulesByRoot);
       if (uaProof === 'yes') return { status: 'pass' };
       if (isInTextLine(element)) return { status: 'pass' };
       if (spacingException) {
@@ -643,7 +742,15 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
           // crowding from its second line or not at all.
           return reachableRects(other, rects[j]).some(within);
         };
-        const crowded = elements.some(crowds);
+        // A target can crowd this circle only if its rectangle reaches the
+        // center's min-radius neighborhood. The larger radius also covers
+        // the circle of any undersized neighbor, whose center lies in its
+        // rectangle. This index is a superset, retaining the exact tests.
+        const center = centers[i];
+        const crowded = [...nearbyCandidates(i, {
+          left: center.x - min, right: center.x + min,
+          top: center.y - min, bottom: center.y + min,
+        })].some((j) => crowds(elements[j], j));
         if (!crowded) return { status: 'pass' };
         // Deliberately NOT applied to the target itself. A crowder that
         // can't be clicked breaks the premise of the exception, because it
@@ -652,7 +759,10 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
         // dismissed, and suppressing it would hide a real defect behind a
         // transient overlay, which is the wrong way round.
       }
-      if (equivalentElsewhere(i)) return { status: 'pass' }; // Equivalent exception, proved by href
+      const equivalent = equivalentElsewhere(i);
+      if (equivalent === 'pass') return { status: 'pass' }; // Same destination and adequate usable area
+      if (equivalent === 'incomplete') return equivalentReview();
+      if (plausibleAlternative(i)) return alternativeReview();
       const rect = rects[i];
       if (uaProof === 'open') {
         return {
@@ -667,7 +777,13 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
           : `This target is ${px(rect.width)}×${px(rect.height)}px — below the ${min}×${min}px minimum, hard to hit for users with motor impairments.`,
         fix: `Increase the element’s size or padding to at least ${min}×${min}px${spacingException ? ', or add spacing between the targets' : ''}.`,
       };
-    });
+    };
+    const outcomes = [];
+    for (let i = 0; i < elements.length; i++) {
+      if (i % 64 === 0) await yieldToMain();
+      outcomes.push(judge(elements[i], i));
+    }
+    return outcomes;
   },
   };
 }

package/engine/rules/wcag/3.3.4-financial-form-confirmation.js

@@ -0,0 +1,32 @@
+// WCAG SC 3.3.4 Error Prevention (Legal, Financial, Data) (Level AA)
+// For a page that causes a financial transaction, a legal commitment or a
+// change to stored user data, a submission must be reversible, checked
+// with a chance to correct, or reviewable and confirmable before it is
+// final. Which of those a form offers is process, invisible to a scan; but
+// one class of page names itself: a form that collects card details
+// (autocomplete cc-number, cc-csc, cc-exp and the rest, or a
+// transaction-amount) is a payment form, and a payment is the financial
+// transaction the criterion describes. That form is asked about, once,
+// never failed: a review step may sit on the next page, and a purchase
+// may be refundable within a stated period (G164).
+//
+// Deletion of user data and legal commitments have no markup signature
+// and stay with the reviewer.
+export default {
+  id: 'financial-form-confirmation',
+  name: 'Payment form safeguards',
+  impact: 'serious',
+  tags: ['wcag2aa', 'wcag334'],
+  help: 'A form that takes a payment must be reversible, checked or confirmed before submission',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/error-prevention-legal-financial-data.html',
+  selector: 'form',
+  visibleOnly: false,
+  evaluate(element) {
+    if (!element.querySelector('input[autocomplete*="cc-" i], input[autocomplete~="transaction-amount" i]')) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: 'This form collects card details, so submitting it makes a financial transaction. 3.3.4 requires at least one of: the submission can be reversed, the entries are checked for errors with a chance to correct them, or a review-and-confirm step comes before the final submit. Check which applies to this checkout.',
+      fix: 'Add a review page before the final submit, validate the entries and let the user correct them, or state a period in which the order can be amended or cancelled.',
+    };
+  },
+};

package/engine/rules/wcag/3.3.8-auth-field-obstruction.js

@@ -10,7 +10,8 @@
 // page may also offer an Alternative (a passkey, a federated sign-in, an
 // emailed link) that this rule cannot see. Blocked paste is therefore
 // reported for REVIEW, not failed. Both mechanisms obstructed at once is the
-// case worth asserting.
+// case worth reviewing together. Neither attribute proves that every
+// alternative mechanism is unavailable.
 //
 // Paste only (2026-08-25 overnight audit): an ondrop handler used to count
 // as a paste blocker. It is not. Drag and drop is a different event and a
@@ -26,12 +27,15 @@
 // the form has the classic sign-in shape: exactly one password field beside
 // a username or email field. Two password fields in one form is the shape
 // of sign-up or a password change, and that field is asked about, never
-// failed. The fail branch fires only on a provable login credential.
+// failed. Even a likely login credential still needs its behavior checked.
 export default {
   id: 'auth-field-obstruction',
   name: 'Accessible login fields',
   impact: 'serious',
-  tags: ['wcag22aa', 'wcag338'],
+  // 3.3.9 (AAA) drops 3.3.8's object-recognition and personal-content
+  // exceptions and keeps everything this rule looks at: F109 is listed as a
+  // failure of both. Twin-tagged on the 2.1.1/2.1.3 precedent.
+  tags: ['wcag22aa', 'wcag338', 'wcag339'],
   help: 'Login fields must not block paste or password managers',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html',
   selector: 'input[type="password"]:not([autocomplete~="new-password"]), input[autocomplete~="current-password"], input[autocomplete~="one-time-code"]',
@@ -43,7 +47,7 @@ export default {
     const autocompleteOff = tokens.length === 1 && tokens[0] === 'off';
     if (!blocksPaste && !autocompleteOff) return { status: 'pass' };
 
-    // Is this field provably an existing credential, i.e. inside 3.3.8?
+    // Markup suggests an existing credential; it does not prove the process.
     const form = element.form ?? element.closest('form');
     const passwordFields = form ? form.querySelectorAll('input[type="password"]').length : (element.type === 'password' ? 1 : 0);
     const identityField = form?.querySelector('input[autocomplete~="username"], input[autocomplete~="email"], input[type="email"]');
@@ -55,23 +59,16 @@ export default {
     const step = provenLogin ? 'this login' : 'this step';
 
     if (blocksPaste && autocompleteOff) {
-      if (provenLogin) {
-        return {
-          status: 'fail',
-          message: `This authentication field blocks pasting AND sets autocomplete="off", so both of the mechanisms 3.3.8 names are obstructed at once: copy and paste, and password-manager entry. What is left is typing the credential from memory.`,
-          fix: 'Remove the paste blocking, and drop autocomplete="off" so a password manager can fill the field.',
-        };
-      }
       return {
         status: 'incomplete',
-        message: `This password field blocks pasting AND sets autocomplete="off". If it is part of signing in, both of the mechanisms 3.3.8 names are obstructed at once (copy and paste, and password-manager entry) and it fails. ${scopeQuestion}`,
+        message: `This field has a paste handler containing cancellation code and sets autocomplete="off". Check whether the handler actually blocks pasting, whether a password manager can fill the field, and whether another authentication method is available. Conditional code may leave pasting enabled, and autocomplete="off" does not establish that password-manager entry is blocked.${provenLogin ? '' : ` ${scopeQuestion}`}`,
         fix: 'Remove the paste blocking, and drop autocomplete="off" so a password manager can fill the field.',
       };
     }
     if (blocksPaste) {
       return {
         status: 'incomplete',
-        message: `This field blocks pasting, which removes copy and paste, one of the two mechanisms 3.3.8 names. A password manager fills the field directly and is unaffected, so this is only a failure if nothing else here helps. Check whether a password manager can complete ${step}, or whether the page offers another way in such as a passkey or a federated sign-in.${provenLogin ? '' : ` ${scopeQuestion}`}`,
+        message: `This field has a paste handler containing cancellation code. Check whether pasting is actually blocked; the code may run only conditionally. Also check whether a password manager can complete ${step}, or whether the page offers another way in such as a passkey or a federated sign-in.${provenLogin ? '' : ` ${scopeQuestion}`}`,
         fix: 'Remove the paste blocking, or make sure another way to sign in is available that does not rely on recalling the credential.',
       };
     }

package/engine/rules/wcag/3.3.9-captcha-alternative.js

@@ -0,0 +1,35 @@
+// WCAG SC 3.3.9 Accessible Authentication (Enhanced) (Level AAA)
+// 3.3.8 lets an authentication step use object recognition ("select every
+// bus") and personal content; 3.3.9 removes both exceptions, so a picture
+// puzzle in a login step needs an alternative method or a mechanism that
+// helps the user through it. The one CAPTCHA fact the DOM shows is the
+// widget itself: the reCAPTCHA, hCaptcha and Turnstile embeds and their
+// site-key hosts. Whether that widget will ever show a picture puzzle
+// (risk-based and invisible modes often do not) and whether another way in
+// exists are not visible, so this asks and never asserts.
+//
+// Scope: the criterion covers steps of an AUTHENTICATION process. A
+// CAPTCHA on a contact form or a comment box is outside it, so only a
+// widget inside a form that also takes a credential (a password or a
+// one-time code) is asked about.
+const CREDENTIAL = 'input[type="password"], input[autocomplete~="current-password"], input[autocomplete~="one-time-code"]';
+
+export default {
+  id: 'captcha-alternative',
+  name: 'CAPTCHA in a login step',
+  impact: 'serious',
+  tags: ['wcag22aaa', 'wcag339'],
+  help: 'A picture-puzzle CAPTCHA in an authentication step needs an alternative (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-enhanced.html',
+  selector: 'iframe[src*="recaptcha" i], iframe[src*="hcaptcha" i], iframe[src*="turnstile" i], .g-recaptcha, .h-captcha, .cf-turnstile, [data-sitekey]',
+  visibleOnly: false,
+  evaluate(element) {
+    const form = element.closest('form');
+    if (!form || !form.querySelector(CREDENTIAL)) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: 'This login form carries a CAPTCHA widget. If the challenge can escalate to a picture puzzle, that is object recognition, which 3.3.8 allows but 3.3.9 (AAA) does not: a cognitive function test in an authentication step then needs another way in (a passkey, an emailed link, a federated sign-in) or a mechanism that helps the user through it. Check what the widget can show and what the alternatives are.',
+      fix: 'Use a risk-based or invisible challenge that never shows a puzzle, or offer another authentication method beside it.',
+    };
+  },
+};

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

@@ -68,6 +68,10 @@ export default {
     for (const { name, value } of attributesOf(element)) {
       if (!name.startsWith('aria-')) continue;
       const attr = name.slice(5);
+      // ARIA defines unknown current/invalid tokens as true, not discarded.
+      // Empty/undefined current means false. Syntax alone cannot show a
+      // state mismatch here. https://www.w3.org/TR/wai-aria-1.2/#aria-current
+      if (name === 'aria-current' || name === 'aria-invalid') continue;
       if (!KNOWN.has(attr)) {
         unknown.push(name);
       } else if (ENUMS[name] && value.trim() === '') {

package/engine/rules/wcag/4.1.2-aria-field-name.js

@@ -6,6 +6,7 @@
 // text inside a listbox/textbox does not name it, only author-provided
 // naming counts. Toggle roles (checkbox/radio/switch) DO name from content.
 import { labelledByName } from '../../lib/accessible-name.js';
+import { effectiveRole } from '../../lib/roles.js';
 
 // progressbar and meter belong here too: ARIA 1.2 marks both roles
 // "Accessible Name Required: True", they never name from content, and a
@@ -28,12 +29,12 @@ export default {
   tags: ['wcag2a', 'wcag412'],
   help: 'ARIA fields and value widgets must have an accessible name',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
-  selector: [...AUTHOR_ONLY, ...FROM_CONTENT]
-    .map((role) => `[role="${role}"]:not(input):not(select):not(textarea)`)
-    .join(', '),
+  selector: '[role]:not(input):not(select):not(textarea)',
   evaluate(element, { accessibleName }) {
-    const role = element.getAttribute('role');
-    const name = FROM_CONTENT.includes(role) ? accessibleName(element) : authorName(element);
+    const role = effectiveRole(element);
+    if (![...AUTHOR_ONLY, ...FROM_CONTENT].includes(role)) return { status: 'pass' };
+    const name = FROM_CONTENT.includes(role) || element.labels?.length
+      ? accessibleName(element) : authorName(element);
     if (name) return { status: 'pass' };
     // ARIA 1.1 combobox pattern: a non-focusable wrapper div carries the
     // role while the real, focusable input inside carries the label. The

package/engine/rules/wcag/4.1.2-aria-valid-refs.js

@@ -76,6 +76,10 @@ function inspect(element) {
   const missing = [];
   const ambiguous = [];
   for (const attr of REF_ATTRIBUTES) {
+    // ARIA requires the error relation to remain unexposed while valid.
+    // A lazy error node not yet inserted cannot lose an active message.
+    if (attr === 'aria-errormessage' && (!element.hasAttribute('aria-invalid')
+      || ['false', ''].includes(element.getAttribute('aria-invalid').trim().toLowerCase()))) continue;
     for (const id of (element.getAttribute(attr) ?? '').split(/\s+/).filter(Boolean)) {
       if (!root.getElementById?.(id)) {
         if (attr === 'aria-controls' && collapsed) continue;
@@ -110,8 +114,8 @@ function outcome({ missing, ambiguous }, element, accessibleName) {
     //     not name, role or a user-set value, and tooltip libraries create
     //     the target on hover or focus, so the DOM proves an authoring
     //     error at most. Asked, never asserted;
-    //   - aria-controls, aria-owns, aria-details, aria-errormessage: the
-    //     standing policy (asserted; the comparator asserts these too).
+    //   - other relationships: review unless a missing name or active
+    //     item above independently demonstrates the component's failure.
     const component = isUserInterfaceComponent(element);
     // The resting name for a component is the full computation (a button
     // names itself from its contents). A landmark, list or group is not
@@ -126,7 +130,8 @@ function outcome({ missing, ambiguous }, element, accessibleName) {
     const line = ({ attr, id }) => attr === 'aria-labelledby'
       ? `aria-labelledby="${id}" points to nothing and leaves this element without an accessible name`
       : `${attr}="${id}" points to nothing — assistive technology silently ignores it`;
-    const asserted = relevant.filter(({ attr }) => attr !== 'aria-describedby' && (attr !== 'aria-labelledby' || component));
+    const asserted = relevant.filter(({ attr }) => component
+      && (attr === 'aria-labelledby' || attr === 'aria-activedescendant'));
     if (asserted.length) {
       return {
         status: 'fail',

package/engine/rules/wcag/4.1.2-button-name.js

@@ -8,7 +8,7 @@ export default {
   tags: ['wcag2a', 'wcag412'],
   help: 'Buttons must have an accessible name',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
-  selector: 'button, [role="button"], input[type="button"], input[type="submit"], input[type="reset"]',
+  selector: 'button, [role], input[type="button"], input[type="submit"], input[type="reset"]',
   evaluate(element, { accessibleName }) {
     // Route by EFFECTIVE role (2026-08-25 overnight audit): a <button
     // role="tab"> or <button role="link"> is exposed under that role, so its

package/engine/rules/wcag/4.1.2-composite-widget-name.js

@@ -19,7 +19,7 @@ export default {
   tags: ['wcag2a', 'wcag412'],
   help: 'Tabs, menu items, options and tree items need an accessible name',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
-  selector: '[role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="treeitem"]',
+  selector: '[role]',
   evaluate(element, { accessibleName }) {
     // This rule owns every element whose EFFECTIVE role is one of the six,
     // <button role="tab"> and <a href role="tab"> included: button-name and

package/engine/rules/wcag/4.1.2-invoker-target.js

@@ -30,6 +30,7 @@ export default {
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: '[popovertarget], [commandfor]',
   evaluate(element) {
+    if (element.matches(':disabled') || !element.matches('button, input[type="button"]')) return { status: 'pass' };
     // Ids resolve within the button's own tree scope (a shadow root's ids
     // are its own), exactly as the browser resolves them.
     const root = element.getRootNode();
@@ -46,7 +47,7 @@ export default {
       }
     }
 
-    if (element.hasAttribute('commandfor')) {
+    if (element.tagName === 'BUTTON' && element.hasAttribute('commandfor')) {
       const id = element.getAttribute('commandfor').trim();
       const command = (element.getAttribute('command') ?? '').trim().toLowerCase();
       const target = lookup(id);

package/engine/rules/wcag/4.1.2-label-for-valid.js

@@ -29,7 +29,7 @@ export default {
   help: 'label[for] must reference a form control that exists',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: 'label[for]',
-  evaluate(element) {
+  evaluate(element, { accessibleName }) {
     const id = element.getAttribute('for');
     // `control` is the browser's own for-resolution: null when the id is
     // missing or names something that is not labelable. It resolves within
@@ -41,7 +41,7 @@ export default {
     // a label that points at one (standing policy: this shape passes).
     if (target && target.tagName === 'INPUT' && target.type === 'hidden') return { status: 'pass' };
     const wrapped = element.querySelector(WRAPPABLE);
-    if (wrapped) {
+    if (wrapped && !accessibleName(wrapped)) {
       return {
         status: 'fail',
         message: `This label wraps a <${wrapped.tagName.toLowerCase()}> but its for="${id}" ${target ? `points at a <${target.tagName.toLowerCase()}>, which is not labelable` : 'points at nothing'}. The for attribute overrides the wrapping, so the wrapped control is not labelled by this text.`,

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

@@ -1,5 +1,6 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
 import { attributesOf } from '../../lib/dom.js';
+import { implicitRole } from '../../lib/roles.js';
 // Concrete, usable roles — abstract roles are invalid in markup.
 export const VALID_ROLES = new Set([
   'alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote', 'button',
@@ -108,7 +109,11 @@ export default {
     // this is a question, not an assertion. Focusable or state-bearing
     // elements keep failing: a focusable element left generic, or a state
     // riding on a role the browser threw away, is the real 4.1.2 harm.
-    if (!focusable && !hasAriaProps) {
+    // An invalid role does not erase a native control's semantics. A
+    // misspelling on a button is a review question; its actual missing
+    // name or state, if any, belongs to the corresponding semantic rule.
+    const nativeRole = implicitRole(element);
+    if ((!focusable && !hasAriaProps) || (nativeRole && nativeRole !== 'generic')) {
       return {
         status: 'incomplete',
         message: `role="${element.getAttribute('role')}" is not a valid ARIA role${hint}, so assistive technology ignores it and exposes the element's native <${tag}> semantics. Nothing is announced wrongly, but the author reached for a role that does not exist. Is the native <${tag}> role the right one here? If a different role was intended, that role is missing.`,