pour-engine 1.33.0 → 1.34.0

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

@@ -6,39 +6,16 @@ const REF_ATTRIBUTES = [
   'aria-activedescendant', 'aria-owns', 'aria-errormessage', 'aria-details',
 ];
 
-// Deferred-tooltip pattern: libraries (Deque's own docs component included)
-// write aria-describedby="tooltip7" at rest and only CREATE #tooltip7 when
-// the trigger is hovered or focused — which is exactly when a screen reader
-// announces the description, so the pattern works. Only DESCRIPTIVE refs
-// get this benefit of the doubt: a NAME that exists only on hover is broken
-// for rotor navigation even when the deferral works, so aria-labelledby
-// (and the rest) keep failing at rest.
-const PROBEABLE = new Set(['aria-describedby', 'aria-details']);
-// A handful of probes covers any real page; a template bug that dangles
-// fifty refs is broken enough that the un-probed remainder failing as
-// before is the right answer.
-const PROBE_BUDGET = 8;
-const PROBE_WAIT_MS = 250;
-
-/** Fire the events a tooltip library listens for, wait for it to react,
- *  check whether the ids materialised, then put the page back. */
-async function probeDeferred(element, ids) {
-  const over = ['pointerover', 'mouseover', 'mouseenter'];
-  const out = ['pointerout', 'mouseout', 'mouseleave'];
-  for (const type of over) element.dispatchEvent(new MouseEvent(type, { bubbles: type !== 'mouseenter' }));
-  element.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
-  try { element.focus?.({ preventScroll: true }); } catch { /* non-focusable */ }
-  await new Promise((resolve) => setTimeout(resolve, PROBE_WAIT_MS));
-  const root = element.getRootNode();
-  const appeared = ids.every((id) => root.getElementById?.(id));
-  // Restore: the audit must leave the page as it found it, and later rules
-  // must not meet a tooltip that only exists because we hovered.
-  for (const type of out) element.dispatchEvent(new MouseEvent(type, { bubbles: type !== 'mouseleave' }));
-  element.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
-  try { element.blur?.(); } catch { /* ignore */ }
-  await new Promise((resolve) => setTimeout(resolve, 50));
-  return appeared;
-}
+// No hover/focus probe (removed 2026-08-26, David). From 1.2.81 to this
+// change the rule dispatched hover and focus events at elements whose
+// aria-describedby pointed nowhere, to catch tooltip libraries that create
+// the target on demand. That mutated the page under audit: focus was taken
+// and not given back, hover-driven menus opened, page scripts ran, mobile
+// keyboards popped, and 300 ms went by per element. Once a dead describedby
+// became a review rather than a fail (same morning) the probe only bought
+// fewer review rows, which is not worth an audit that is no longer
+// read-only. The deferred-tooltip pattern is now named in the review
+// message instead, for the human to confirm.
 
 function inspect(element) {
   // ARIA id references cannot cross shadow boundaries: they resolve only
@@ -67,29 +44,42 @@ function inspect(element) {
   return { missing, ambiguous };
 }
 
-function outcome({ missing, ambiguous }, probed, element, accessibleName) {
+function outcome({ missing, ambiguous }, element, accessibleName) {
   if (missing.length) {
     // A dangling ref is skipped by the accname computation, so the HARM
-    // depends on what remains. A labelledby that dangles while the element
-    // still names itself (contents, aria-label) is inert clutter — real,
-    // fragile, validator-flagged, but announced correctly today. The same
-    // dangle on an otherwise nameless element is the 4.1.2 failure proper:
-    // names are consumed at REST (element lists, rotor), so the finding
-    // says which of the two this is instead of one blanket accusation.
+    // depends on what remains, and 4.1.2 only cares about name, role and
+    // user-settable value (re-decided by David 2026-08-26 with axe-core's
+    // measured verdicts as the second opinion; the old "fragile,
+    // validator-flagged" argument was 4.1.1's, and 2.2 retired it):
+    //   - aria-labelledby that dangles while the element still names
+    //     itself from elsewhere: the name is fully determinable (accname
+    //     step 2B processes the valid IDREFs), so it is not a finding here;
+    //   - aria-labelledby that leaves the element nameless, and
+    //     aria-activedescendant (a focused composite reports the wrong
+    //     active item): the 4.1.2 failure proper, asserted;
+    //   - aria-describedby that points nowhere at rest: a description is
+    //     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).
     const restingName = (accessibleName?.(element) ?? '').trim();
-    const detail = missing
-      .map(({ attr, id }) => {
-        if (attr === 'aria-labelledby') {
-          return restingName
-            ? `aria-labelledby="${id}" points to nothing — the reference is ignored and this element's name ("${restingName.slice(0, 40)}") currently comes from elsewhere; announced correctly today, but the dead reference is fragile`
-            : `aria-labelledby="${id}" points to nothing and leaves this element without an accessible name`;
-        }
-        return `${attr}="${id}" points to nothing — assistive technology silently ignores it`;
-      })
-      .join('; ');
+    const relevant = missing.filter(({ attr }) => !(attr === 'aria-labelledby' && restingName));
+    if (!relevant.length) return { status: 'pass' };
+    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');
+    if (asserted.length) {
+      return {
+        status: 'fail',
+        message: `Broken ARIA references: ${relevant.map(line).join('; ')}.`,
+        fix: 'Correct or remove the reference, or give the target element that id.',
+      };
+    }
     return {
-      status: 'fail',
-      message: `Broken ARIA references: ${detail}.${probed ? ' Probed with focus and hover in case the target is created on demand — it never appeared.' : ''}`,
+      status: 'incomplete',
+      message: `${relevant.map(line).join('; ')} at rest. The element keeps its name and role, so this is not a proven 4.1.2 failure: if the description is created when the element is hovered or focused (a tooltip library), this works; otherwise correct the reference.`,
       fix: 'Correct or remove the reference, or give the target element that id.',
     };
   }
@@ -116,26 +106,7 @@ export default {
   help: 'ARIA id references must point to elements that exist',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
   selector: REF_ATTRIBUTES.map((attr) => `[${attr}]`).join(', '),
-  async evaluateAll(elements, { accessibleName } = {}) {
-    let budget = PROBE_BUDGET;
-    const outcomes = new Array(elements.length);
-    for (let i = 0; i < elements.length; i++) {
-      const element = elements[i];
-      const found = inspect(element);
-      const deferredOnly = found.missing.length > 0
-        && found.missing.every(({ attr }) => PROBEABLE.has(attr));
-      if (deferredOnly && budget > 0) {
-        budget--;
-        if (await probeDeferred(element, found.missing.map(({ id }) => id))) {
-          // The description materialises exactly when it would be announced.
-          outcomes[i] = { status: 'pass' };
-          continue;
-        }
-        outcomes[i] = outcome(found, true, element, accessibleName);
-        continue;
-      }
-      outcomes[i] = outcome(found, false, element, accessibleName);
-    }
-    return outcomes;
+  evaluate(element, { accessibleName } = {}) {
+    return outcome(inspect(element), element, accessibleName);
   },
 };

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

@@ -1,4 +1,6 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
+import { effectiveRole, implicitRole } from '../../lib/roles.js';
+
 export default {
   id: 'button-name',
   name: 'Button names',
@@ -8,6 +10,15 @@ export default {
   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"]',
   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
+    // missing name belongs to the rule that speaks for that role
+    // (composite-widget-name, link-name). This rule owns every element whose
+    // effective role is button, whatever its tag: <a href role="button">
+    // included, which used to draw a finding here AND in link-name. An
+    // unknown explicit role falls back to the native role.
+    const role = effectiveRole(element) ?? implicitRole(element);
+    if (role !== 'button') return { status: 'pass' };
     if (accessibleName(element)) return { status: 'pass' };
     return {
       status: 'fail',

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

@@ -8,6 +8,10 @@
 // The container roles (tablist, menu, listbox, tree) are name-recommended
 // rather than required and are deliberately not judged here; the items are
 // where the binary, assertable failure lives.
+import { effectiveRole } from '../../lib/roles.js';
+
+const ITEM_ROLES = new Set(['tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'treeitem']);
+
 export default {
   id: 'composite-widget-name',
   name: 'Widget item names',
@@ -17,13 +21,15 @@ export default {
   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"]',
   evaluate(element, { accessibleName }) {
-    // <button role="tab"> and <a href role="tab"> are already selected by
-    // button-name/link-name (their selectors match the tag regardless of
-    // the role override) — one nameless control must not become two
-    // findings, so this rule owns only the div/span/li-style hosts.
-    if (element.matches('button, a[href], input, select, textarea, summary')) return { status: 'pass' };
+    // 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
+    // link-name defer to the effective role since 2026-08-25 (overnight
+    // audit), so the tab wording now reaches the tab, and one nameless
+    // control still yields one finding. A host whose role resolves elsewhere
+    // (presentation discarded back to a native role, say) is not ours.
+    const role = effectiveRole(element);
+    if (!ITEM_ROLES.has(role)) return { status: 'pass' };
     if (accessibleName(element)) return { status: 'pass' };
-    const role = element.getAttribute('role');
     return {
       status: 'fail',
       message: `This ${role} has no accessible name — a screen reader announces an unnamed ${role}, and users cannot tell what choosing it does.`,

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

@@ -1,5 +1,25 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
-const LABELABLE = 'input, select, textarea, button, meter, output, progress';
+//
+// Rewritten 2026-08-25 overnight audit, two decisions:
+//
+// 1. The browser decides what is labelable, not a tag list. HTML defines
+//    the labeled control as "the first element in tree order whose ID is
+//    equal to the value of the for attribute, if it is a labelable element",
+//    and exposes exactly that resolution as label.control. The list this
+//    rule used to keep missed form-associated custom elements (HTML lists
+//    them as labelable) and admitted input type=hidden (HTML does not).
+//
+// 2. A label is not a user interface component. 4.1.2 asks that every
+//    component's name and role be determinable; a caption whose for points
+//    at nothing, or at a paragraph, harms no component by itself. Where a
+//    real control was left nameless, form-label asserts on that control, so
+//    asserting here too was one fault reported twice, and where no control
+//    was ever meant, it was a fault reported that does not exist. The rule
+//    now asks. It still asserts the one shape the DOM proves: a label that
+//    WRAPS a labelable control while its for points elsewhere, because
+//    HTML's for rule overrides the wrapping and the wrapped control provably
+//    loses its label.
+const WRAPPABLE = 'input:not([type="hidden"]), select, textarea, button, meter, output, progress';
 
 export default {
   id: 'label-for-valid',
@@ -11,16 +31,29 @@ export default {
   selector: 'label[for]',
   evaluate(element) {
     const id = element.getAttribute('for');
-    // id references resolve within the element's own root — a label in a
-    // shadow tree can only point at controls in that same tree.
+    // `control` is the browser's own for-resolution: null when the id is
+    // missing or names something that is not labelable. It resolves within
+    // the label's own root, so a label in a shadow tree can only point at
+    // controls in that same tree.
+    if (element.control) return { status: 'pass' };
     const target = element.getRootNode().getElementById?.(id);
-    if (target?.matches(LABELABLE)) return { status: 'pass' };
+    // A hidden input is not labelable, but nothing perceivable is harmed by
+    // 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) {
+      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.`,
+        fix: `Point the for attribute at the wrapped control's id, or remove the for attribute so the wrapping labels it.`,
+      };
+    }
     return {
-      status: 'fail',
+      status: 'incomplete',
       message: target
-        ? `for="${id}" points at a <${target.tagName.toLowerCase()}>, which cannot be labelled — the association is ignored.`
-        : `for="${id}" points at nothing — the label is not associated with any field.`,
-      fix: 'Point the for attribute at the id of the input/select/textarea it labels.',
+        ? `for="${id}" points at a <${target.tagName.toLowerCase()}>, which is not a labelable element, so the browser ignores the association. Was a form control meant to be here? If so it has no label from this text (form-label reports the control itself); if this text captions something that is not a control, nothing is affected.`
+        : `for="${id}" points at nothing, so this label is not associated with any control. Was a form control meant to be here? If so it has lost its label (form-label reports the control itself); if this is leftover markup, no one is affected.`,
+      fix: 'Point the for attribute at the id of the control it labels, or remove the attribute.',
     };
   },
 };

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

@@ -26,12 +26,29 @@ export default {
     // role="button" with no tabindex is not in the tab order — keyboard
     // users cannot reach it, so it cannot be a competing stop).
     const NATIVE = 'a[href], button, input, select, textarea, summary, audio[controls], video[controls]';
+    // Any negative tabindex is unreachable by Tab (HTML: "a negative
+    // integer"), not only the literal "-1"; hasAttribute guards the default
+    // -1 Chromium reports for attribute-less contenteditable elements.
+    // 2026-08-25 overnight audit.
     const nested = [...element.querySelectorAll(INTERACTIVE)].find((el) =>
-      !el.matches(':disabled') && el.getAttribute('tabindex') !== '-1'
+      !el.matches(':disabled') && !(el.hasAttribute('tabindex') && el.tabIndex < 0)
       && !(el.tagName === 'INPUT' && el.type === 'hidden') && isRendered(el)
       && !el.closest('[aria-hidden="true"]')
       && (el.matches(NATIVE) || el.hasAttribute('tabindex')));
     if (!nested) return { status: 'pass' };
+    // <summary> is the one outer control HTML does not forbid this on: its
+    // content model is phrasing content with no "no interactive content
+    // descendant" clause (a and button both carry one), it maps to no ARIA
+    // role that is Children Presentational, and browsers keep a link inside
+    // it as a link. Both controls have their name and role, so nothing is
+    // announced wrongly; whether Enter on the link versus the disclosure
+    // confuses is a question for a person. 2026-08-25 overnight audit.
+    if (element.tagName === 'SUMMARY') {
+      return {
+        status: 'incomplete',
+        message: `This summary contains another interactive element (<${nested.tagName.toLowerCase()}>). HTML allows it and both controls keep their name and role, but the disclosure and the control inside it are separate keyboard stops in one label. Check that activating each does what a user expects.`,
+      };
+    }
     return {
       status: 'fail',
       message: `This ${element.tagName.toLowerCase()} contains another interactive element (<${nested.tagName.toLowerCase()}>) — focus order and announcements become unpredictable.`,

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

@@ -57,6 +57,22 @@ export default {
     const hasAriaProps = [...element.attributes].some(
       (attr) => attr.name.startsWith('aria-') && attr.name !== 'aria-hidden');
     if (genericFallback && !focusable && !hasAriaProps) return { status: 'pass' };
+    // The same two triggers decide for EVERY tag (2026-08-25 overnight
+    // audit). ARIA 1.2 section 9.1: an unrecognised role token is treated as
+    // if no role had been provided, so <h2 role="text"> is exposed exactly
+    // as <h2>. Name, role and value are all intact and determinable; what
+    // the DOM cannot tell is what the author meant, so when the element is
+    // not focusable and carries no ARIA state on the back of the bogus role
+    // 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) {
+      return {
+        status: 'incomplete',
+        message: `role="${element.getAttribute('role')}" is not a valid ARIA role, 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.`,
+        fix: 'Use a valid role from the ARIA specification, or remove the attribute to keep the element’s native role.',
+      };
+    }
     return {
       status: 'fail',
       message: `role="${element.getAttribute('role')}" is not a valid ARIA role, so assistive technology ignores it${genericFallback ? '' : ` and falls back to the element’s native <${tag}> semantics`}.`,

package/engine/wcag22.js

@@ -25,7 +25,7 @@ const sc = (num, name, level, automation, since = '2.0') => ({
 export default [
   // 1. Perceivable
   sc('1.1.1', 'Non-text Content', 'A', 'partial'),
-  sc('1.2.1', 'Audio-only and Video-only (Prerecorded)', 'A', 'manual'),
+  sc('1.2.1', 'Audio-only and Video-only (Prerecorded)', 'A', 'partial'), // partial: the audio-only transcript question is askable; silent-video detection is not
   sc('1.2.2', 'Captions (Prerecorded)', 'A', 'partial'),
   sc('1.2.3', 'Audio Description or Media Alternative (Prerecorded)', 'A', 'manual'),
   sc('1.2.4', 'Captions (Live)', 'AA', 'manual'),
@@ -35,7 +35,7 @@ export default [
   sc('1.2.8', 'Media Alternative (Prerecorded)', 'AAA', 'manual'),
   sc('1.2.9', 'Audio-only (Live)', 'AAA', 'manual'),
   sc('1.3.1', 'Info and Relationships', 'A', 'partial'),
-  sc('1.3.2', 'Meaningful Sequence', 'A', 'manual'),
+  sc('1.3.2', 'Meaningful Sequence', 'A', 'partial'), // partial: CSS-reorder divergence is measurable; whether meaning survives is the reader's call
   sc('1.3.3', 'Sensory Characteristics', 'A', 'manual'),
   sc('1.3.4', 'Orientation', 'AA', 'partial', '2.1'), // orientation-lock (2026-08-01) proves CSS root hides/rotations; script locks stay a human check
   sc('1.3.5', 'Identify Input Purpose', 'AA', 'partial', '2.1'), // partial: wrong tokens are provable; MISSING autocomplete on identity fields needs judgment
@@ -86,7 +86,7 @@ export default [
   sc('2.5.4', 'Motion Actuation', 'A', 'manual', '2.1'),
   sc('2.5.5', 'Target Size (Enhanced)', 'AAA', 'partial', '2.1'),
   sc('2.5.6', 'Concurrent Input Mechanisms', 'AAA', 'manual', '2.1'),
-  sc('2.5.7', 'Dragging Movements', 'AA', 'manual', '2.2'),
+  sc('2.5.7', 'Dragging Movements', 'AA', 'partial', '2.2'), // partial: declared draggable UI is visible; pointer-event drag logic is not
   sc('2.5.8', 'Target Size (Minimum)', 'AA', 'partial', '2.2'), // partial: size/spacing are computable; the equivalent-control and essential exceptions need judgment
   // 3. Understandable
   sc('3.1.1', 'Language of Page', 'A', 'partial'), // partial: html-lang proves the tag is present and well-formed; whether it names the language actually written needs a reader
@@ -107,7 +107,7 @@ export default [
   sc('3.3.4', 'Error Prevention (Legal, Financial, Data)', 'AA', 'manual'),
   sc('3.3.5', 'Help', 'AAA', 'manual'),
   sc('3.3.6', 'Error Prevention (All)', 'AAA', 'manual'),
-  sc('3.3.7', 'Redundant Entry', 'A', 'manual', '2.2'),
+  sc('3.3.7', 'Redundant Entry', 'A', 'partial', '2.2'), // partial: duplicate autocomplete purposes in one form are visible; cross-page processes are not
   sc('3.3.8', 'Accessible Authentication (Minimum)', 'AA', 'partial', '2.2'), // partial: auth-field-obstruction catches paste blocking; alternatives need judgment
   sc('3.3.9', 'Accessible Authentication (Enhanced)', 'AAA', 'manual', '2.2'),
   // 4. Robust (4.1.1 Parsing was removed in WCAG 2.2)

package/package.json

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