pour-engine 1.34.1 → 1.35.0

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -58,7 +58,7 @@ meaning that only a person can settle, even where a rule decides most real pages
 | 2.2.6 | [Timeouts](https://www.w3.org/WAI/WCAG22/Understanding/timeouts.html) | AAA | Manual review | — |
 | 2.3.1 | [Three Flashes or Below Threshold](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html) | A | Manual review | — |
 | 2.3.2 | [Three Flashes](https://www.w3.org/WAI/WCAG22/Understanding/three-flashes.html) | AAA | Manual review | — |
-| 2.3.3 | [Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) | AAA | Manual review | — |
+| 2.3.3 | [Animation from Interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html) | AAA | Partially automated | reduced-motion |
 | 2.4.1 | [Bypass Blocks](https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html) | A | Partially automated | bypass-blocks |
 | 2.4.2 | [Page Titled](https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html) | A | Partially automated | document-title |
 | 2.4.3 | [Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) | A | Partially automated | visual-order-divergence |
@@ -111,7 +111,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, dialog-name, frame-title, 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-valid-refs, button-name, composite-widget-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, summary-name, valid-role, invoker-target |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
-**Totals:** 38 partially automated · 48 manual — with 86 rules.
+**Totals:** 39 partially automated · 47 manual — with 88 rules.

package/engine/lib/dom.js

@@ -124,6 +124,22 @@ export function isEmbeddedDocument(doc) {
 }
 
 /** The element's own (not descendant-element) text, trimmed. */
+/**
+ * Is this element inside an `inert` subtree? The attribute makes a whole
+ * subtree unreachable: nothing in it takes focus, nothing in it accepts a
+ * click, and assistive technology skips it (HTML §6.6.7). A rule that
+ * reasons about focus order, reachability or pointer targets must treat
+ * such elements as absent. Walks up through shadow hosts, because inert on
+ * a host inerts its shadow tree too. `inert` is a boolean attribute:
+ * presence is what counts, whatever the value.
+ */
+export function isInert(element) {
+  for (let node = element; node; node = node.parentElement ?? node.getRootNode?.()?.host ?? null) {
+    if (node.nodeType === 1 && node.hasAttribute('inert')) return true;
+  }
+  return false;
+}
+
 export function ownText(element) {
   return [...element.childNodes]
     .filter((node) => node.nodeType === Node.TEXT_NODE)

package/engine/lib/roles.js

@@ -133,7 +133,7 @@ const DATALIST_TYPES = new Set(['text', 'search', 'tel', 'url', 'email']);
 
 const TAG_ROLES = {
   button: 'button', textarea: 'textbox', img: 'img', article: 'article',
-  aside: 'complementary', nav: 'navigation', main: 'main',
+  aside: 'complementary', nav: 'navigation', main: 'main', search: 'search',
   h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading',
   ul: 'list', ol: 'list', menu: 'list', li: 'listitem',
   table: 'table', thead: 'rowgroup', tbody: 'rowgroup', tfoot: 'rowgroup',

package/engine/rules/best-practice/landmark-unique.js

@@ -38,7 +38,7 @@ export default {
   // Implicit landmarks (header, footer, labelled section/form) join the
   // grouping — a page's <header> and a div[role="banner"] ARE duplicates.
   selector:
-    'nav, aside, header, footer, section[aria-label], section[aria-labelledby], ' +
+    'nav, search, aside, header, footer, section[aria-label], section[aria-labelledby], ' +
     'form[aria-label], form[aria-labelledby], [role="navigation"], [role="complementary"], ' +
     '[role="banner"], [role="contentinfo"], [role="region"], [role="search"], [role="form"], [role="main"], main',
   // Judged as a set: two unlabelled navs are the problem, not either alone.

package/engine/rules/best-practice/region.js

@@ -10,7 +10,7 @@
 // so a closed dialog cannot make a landmark-less page look landmarked
 // (2026-08-25 overnight audit).
 const LANDMARK =
-  'main, nav, aside, form[aria-label], form[aria-labelledby], ' +
+  'main, nav, aside, search, form[aria-label], form[aria-labelledby], ' +
   'header:not(:is(article, aside, main, nav, section) header), ' +
   'footer:not(:is(article, aside, main, nav, section) footer), ' +
   'section[aria-label], section[aria-labelledby], [role="main"], [role="navigation"], ' +

package/engine/rules/index.js

@@ -99,6 +99,12 @@ import audioTranscript from './wcag/1.2.1-audio-transcript.js';
 import readingOrderDivergence from './wcag/1.3.2-reading-order-divergence.js';
 import dragAlternative from './wcag/2.5.7-drag-alternative.js';
 import redundantEntry from './wcag/3.3.7-redundant-entry.js';
+// 2026-08-27 platform batch: the HTML invoker attributes (popovertarget,
+// commandfor) get the dangling-reference assert aria-controls already has,
+// and 2.3.3 gains its review question about interaction-driven motion that
+// no stylesheet lets the reader turn off.
+import invokerTarget from './wcag/4.1.2-invoker-target.js';
+import reducedMotion from './wcag/2.3.3-reduced-motion.js';
 import onInputNavigation from './wcag/3.2.2-on-input-navigation.js';
 import errorMessageLinkage from './wcag/3.3.1-error-message-linkage.js';
 import compositeWidgetName from './wcag/4.1.2-composite-widget-name.js';
@@ -198,6 +204,8 @@ export default [
   readingOrderDivergence,
   dragAlternative,
   redundantEntry,
+  invokerTarget,
+  reducedMotion,
   onInputNavigation,
   errorMessageLinkage,
   compositeWidgetName,

package/engine/rules/wcag/2.1.1-scrollable-region-focusable.js

@@ -6,6 +6,8 @@
 // (found on carbondesignsystem.com: a scrollable <nav> the rule never saw).
 // The cost stays flat because the overwhelming majority of elements exit on
 // two integer reads before any style or visibility work happens.
+import { isInert } from '../../lib/dom.js';
+
 const FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea, summary, [tabindex]';
 
 /** Reachable with the Tab key — what actually lets a keyboard user move
@@ -15,6 +17,8 @@ const FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea
  *  nothing reachable (it auto-focuses the scroller, same as when empty). */
 function isTabbable(element) {
   if (element.tabIndex < 0 || element.disabled) return false;
+  // Inert content never takes focus, so it cannot make a region reachable.
+  if (isInert(element)) return false;
   if (typeof element.checkVisibility === 'function') {
     return element.checkVisibility({ visibilityProperty: true });
   }

package/engine/rules/wcag/2.2.2-pause-stop-hide.js

@@ -28,7 +28,7 @@ const MOTION_PROPERTIES = new Set([
 
 /** Does this keyframe set move the element around, rather than merely
  *  restyle it? A hue cycle is not movement; a translate is. */
-function keyframesMove(keyframes) {
+export function keyframesMove(keyframes) {
   return keyframes.some((frame) => Object.keys(frame).some((property) => MOTION_PROPERTIES.has(property)));
 }
 

package/engine/rules/wcag/2.3.3-reduced-motion.js

@@ -0,0 +1,170 @@
+// WCAG SC 2.3.3 Animation from Interactions (Level AAA)
+// "Motion animation triggered by interaction can be disabled, unless the
+// animation is essential to the functionality or the information being
+// conveyed."
+//
+// The criterion is about movement a person's own action sets off: the page
+// scrolls and things glide, a pointer arrives and a card lifts, a link is
+// followed and the viewport slides. The web's one standard way to let a
+// reader turn such motion off is the prefers-reduced-motion media feature
+// (technique C39): a page that honours it anywhere has a mechanism; one
+// that animates on interaction and never mentions it has none.
+//
+// Three kinds of evidence are readable from the loaded page:
+//   - scroll- and view-driven animations (animation-timeline: scroll() /
+//     view()), read from the Web Animations API as animations on a timeline
+//     other than the document's, whose keyframes move the element;
+//   - smooth scrolling (scroll-behavior: smooth) on the root or the body,
+//     which turns every in-page link and anchor jump into a glide;
+//   - style rules keyed to :hover, :focus, :focus-visible, :focus-within or
+//     :active that set a motion property (transform, translate, offset
+//     path, position) on a subject that transitions or animates it: an
+//     instant snap on hover is a change of place, not motion.
+// Whether any of it is essential is the criterion's own test and a human
+// call, so the rule reviews, never asserts. One question per page, on the
+// root: the finding is about the page's motion policy, not about each
+// element that moves. A stylesheet this audit cannot read (cross-origin
+// without CORS) might be the one carrying the media rule, so the question
+// says so when that is the case, and a page whose only motion sits in
+// unreadable sheets is not asked at all.
+import { keyframesMove } from './2.2.2-pause-stop-hide.js';
+
+// Properties whose change on hover or focus is movement. Deliberately
+// narrower than 2.2.2's list: `background` and `margin` shorthands expand
+// to background-position and margin-* in the CSSOM, so a plain hover
+// colour change would read as motion if those were counted.
+const MOTION_CSS = [
+  'transform', 'translate', 'rotate', 'scale', 'offset-path', 'offset-distance', 'offset-rotate',
+  'left', 'right', 'top', 'bottom',
+];
+const INTERACTION = /:(?:hover|focus-visible|focus-within|focus|active)\b/;
+const INTERACTION_ALL = /:(?:hover|focus-visible|focus-within|focus|active)\b/g;
+const ANIMATES = /\b(?:all|transform|translate|rotate|scale|offset-path|offset-distance|offset-rotate|left|right|top|bottom|inset)\b/;
+
+/** Does a hover/focus rule that sets a motion property actually ANIMATE
+ *  its subject? 2.3.3 is about animation: a transform that snaps into
+ *  place on hover is an instant change, not motion. The rule itself may
+ *  declare the transition or animation; more often the resting rule does,
+ *  so the elements the selector addresses at rest are sampled for a
+ *  transition that covers a motion property (or `all`) with a duration.
+ *  An interaction selector that matches nothing on this page moves
+ *  nothing. Measured on the benchmark corpus: counting every hover
+ *  transform asked the question of two pages in five, mostly 1px button
+ *  nudges with no transition; this keeps it to pages that glide. */
+/** Is the movement this rule declares more than a nudge? A transform that
+ *  shifts its subject under 8px, or scales it within 15%, gives no sense of
+ *  travel across the page (the criterion's own examples are parallax and
+ *  elements flying in); counting those asked the question of a page in
+ *  four for a hover lift on a button. Percentage translates, rotations,
+ *  offset paths and inset changes always count: their size is unbounded
+ *  or unknowable from the rule alone. */
+function movesFar(rule) {
+  const style = rule.style;
+  if (['offset-path', 'offset-distance', 'offset-rotate', 'rotate', 'left', 'right', 'top', 'bottom']
+    .some((property) => style.getPropertyValue(property))) return true;
+  const values = ['transform', 'translate', 'scale'].map((property) => style.getPropertyValue(property)).join(' ');
+  if (/rotate|skew|matrix|%|em|rem|vw|vh/.test(values)) return true;
+  const px = [...values.matchAll(/(-?\d*\.?\d+)px/g)].map((m) => Math.abs(parseFloat(m[1])));
+  if (px.some((n) => n >= 8)) return true;
+  const scales = [...values.matchAll(/scale[XYZ3d]*\(([^)]*)\)/gi)].flatMap((m) => m[1].split(',').map((v) => parseFloat(v)));
+  const bareScale = style.getPropertyValue('scale').split(/\s+/).map((v) => parseFloat(v)).filter((v) => !Number.isNaN(v));
+  return [...scales, ...bareScale].some((v) => !Number.isNaN(v) && (v < 0.85 || v > 1.15));
+}
+
+function rulesAnimate(doc, rule) {
+  const own = rule.style.getPropertyValue('transition-duration') || rule.style.getPropertyValue('animation-name');
+  if (own && own !== 'none' && own !== '0s') return true;
+  const resting = rule.selectorText.replace(INTERACTION_ALL, '').trim();
+  if (!resting || /^[,\s]*$/.test(resting)) return false;
+  let subjects;
+  try { subjects = doc.querySelectorAll(resting); } catch { return false; }
+  let seen = 0;
+  for (const subject of subjects) {
+    if (seen++ >= 5) break;
+    const style = doc.defaultView.getComputedStyle(subject);
+    const durations = style.transitionDuration.split(',').map((d) => parseFloat(d) || 0);
+    if (!durations.some((d) => d > 0)) continue;
+    if (ANIMATES.test(style.transitionProperty)) return true;
+  }
+  return false;
+}
+
+/** Walk every rule of every readable stylesheet (nested rules and imports
+ *  included), collecting the two facts this rule needs. */
+function readStyles(doc) {
+  const facts = { honours: false, hoverMotion: 0, hoverSelectors: [], unreadable: 0 };
+  const scan = (rules) => {
+    for (const rule of rules) {
+      const media = rule.media?.mediaText;
+      if (media && /prefers-reduced-motion/i.test(media)) facts.honours = true;
+      if (rule.selectorText && INTERACTION.test(rule.selectorText) && rule.style
+        && MOTION_CSS.some((property) => rule.style.getPropertyValue(property))
+        && movesFar(rule) && rulesAnimate(doc, rule)) {
+        facts.hoverMotion += 1;
+        if (facts.hoverSelectors.length < 3) facts.hoverSelectors.push(rule.selectorText.slice(0, 80));
+      }
+      const inner = rule.cssRules ?? rule.styleSheet?.cssRules;
+      if (inner) {
+        try { scan(inner); } catch { facts.unreadable += 1; }
+      }
+    }
+  };
+  const sheets = [...(doc.styleSheets ?? []), ...(doc.adoptedStyleSheets ?? [])];
+  for (const sheet of sheets) {
+    try { scan(sheet.cssRules); } catch { facts.unreadable += 1; }
+  }
+  return facts;
+}
+
+/** Animations that advance with scrolling rather than with time, and move. */
+function scrollDrivenMotion(doc) {
+  if (typeof doc.getAnimations !== 'function') return 0;
+  let animations;
+  try { animations = doc.getAnimations(); } catch { return 0; }
+  let count = 0;
+  for (const animation of animations) {
+    if (!animation.timeline || animation.timeline === doc.timeline) continue;
+    let keyframes;
+    try { keyframes = animation.effect?.getKeyframes?.() ?? []; } catch { continue; }
+    if (keyframesMove(keyframes)) count += 1;
+  }
+  return count;
+}
+
+export default {
+  id: 'reduced-motion',
+  name: 'Motion honours reduced-motion',
+  impact: 'moderate',
+  tags: ['wcag21aaa', 'wcag233'],
+  help: 'Motion set off by scrolling, hovering or focusing should be switchable off',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    const doc = element.ownerDocument;
+    const win = doc.defaultView;
+    const styles = readStyles(doc);
+    if (styles.honours) return { status: 'pass' };
+
+    const evidence = [];
+    const scrolling = scrollDrivenMotion(doc);
+    if (scrolling) evidence.push(`${scrolling} scroll-driven animation${scrolling === 1 ? '' : 's'} that move${scrolling === 1 ? 's' : ''} content`);
+    const smooth = [doc.documentElement, doc.body].some((node) =>
+      node && win.getComputedStyle(node).scrollBehavior === 'smooth');
+    if (smooth) evidence.push('smooth scrolling on in-page navigation (scroll-behavior: smooth)');
+    if (styles.hoverMotion) {
+      const more = styles.hoverMotion > styles.hoverSelectors.length ? ', …' : '';
+      evidence.push(`${styles.hoverMotion} style rule${styles.hoverMotion === 1 ? '' : 's'} animating movement on hover or focus (${styles.hoverSelectors.join(', ')}${more})`);
+    }
+    if (!evidence.length) return { status: 'pass' };
+
+    const unread = styles.unreadable
+      ? ` (${styles.unreadable} stylesheet${styles.unreadable === 1 ? '' : 's'} could not be read and might carry one)`
+      : '';
+    return {
+      status: 'incomplete',
+      message: `This page moves content when people interact with it (${evidence.join('; ')}), and none of the stylesheets this audit could read honours prefers-reduced-motion${unread}. 2.3.3 asks that such motion can be turned off unless it is essential.`,
+      fix: 'Put the motion inside @media (prefers-reduced-motion: no-preference), or remove it under @media (prefers-reduced-motion: reduce), keeping only motion that is essential to the function or the information.',
+    };
+  },
+};

package/engine/rules/wcag/2.4.11-focus-not-obscured.js

@@ -16,6 +16,8 @@
 //
 // Sites that apply the spec's own sufficient technique — scroll-padding for
 // the overlay's edge — are not flagged at all.
+import { isInert } from '../../lib/dom.js';
+
 const FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea, summary, [tabindex]:not([tabindex="-1"])';
 
 /** Does the scroll container reserve room for an overlay on this edge?
@@ -80,6 +82,8 @@ export default {
       // `:disabled` catches controls disabled by an ancestor fieldset, which
       // the `disabled` property does not reflect — those never take focus.
       if (element.matches(':disabled')) return { status: 'pass' };
+      // Inert content cannot be focused, so nothing can obscure its focus.
+      if (isInert(element)) return { status: 'pass' };
       const rect = element.getBoundingClientRect();
       if (!rect.width || !rect.height) return { status: 'pass' };
       // Only in-viewport geometry is trustworthy (or cheap).

package/engine/rules/wcag/2.4.3-visual-order-divergence.js

@@ -25,8 +25,12 @@
 export const FLEXGRID = /^(inline-)?(flex|grid)$/;
 
 /** DOM-order focusable children grouped per flex/grid parent. */
+import { isInert } from '../../lib/dom.js';
+
 export function tabbable(element) {
   if (element.disabled || element.tabIndex < 0) return false;
+  // An inert subtree is skipped by Tab entirely: no sequence to compare.
+  if (isInert(element)) return false;
   return true;
 }
 

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

@@ -29,6 +29,8 @@ const TARGETS = 'a[href], button, input, select, [role="button"], [role="link"]'
  * These are keyboard affordances, not pointer targets — and their phantom
  * rects must not count as "crowding" for the real targets around them.
  */
+import { isInert } from '../../lib/dom.js';
+
 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
@@ -321,8 +323,13 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
           && !element.checkVisibility({ contentVisibilityAuto: true, visibilityProperty: true });
       } catch { return false; }
     };
+    // Inert targets accept no pointer action at all, so they are neither
+    // 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 && !isHiddenFromPointer(elements[i], r) && !layoutSkipped(elements[i]));
+      r.width > 0 && r.height > 0 && !isInert(elements[i])
+      && !isHiddenFromPointer(elements[i], r) && !layoutSkipped(elements[i]));
     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.
@@ -570,6 +577,15 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
           // fragment IS its box, so genuine overlays are dismissed exactly
           // as before.
           if (paintedEncloses(other, rects[j], rects[i]) || paintedEncloses(element, rects[i], rects[j])) return false;
+          // Crowding across fixed/sticky contexts is scroll state, not
+          // layout, exactly as the obscured-target test reads overlap: a
+          // consent banner pinned to the bottom of the viewport lays its
+          // "Privacy Policy" link on whichever headline happens to sit
+          // under it right now, and that headline has clear space the
+          // moment the page scrolls. Asserting it as crowded invents a
+          // defect the layout does not have (measured live on two news
+          // homes carrying the same consent banner, 2026-08-27).
+          if (fixedContextOf(other) !== fixedContextOf(element)) return false;
           const within = (box) => {
             if (undersized[j]) {
               const c = { x: box.left + box.width / 2, y: box.top + box.height / 2 };

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

@@ -0,0 +1,71 @@
+// WCAG SC 4.1.2 Name, Role, Value (Level A) — the HTML invoker slice
+//
+// HTML's invoker attributes wire a button to the element it acts on:
+// `popovertarget` opens, closes or toggles a popover, and `commandfor` with
+// a `command` drives a popover or a <dialog> (or a custom `--` command the
+// page handles itself). The browser builds the accessibility relationship
+// from that wiring on its own: the button exposes its expanded state and a
+// relation to what it controls, with no ARIA written by the author.
+//
+// That relationship exists only when the reference resolves. An id that
+// names nothing, a popovertarget aimed at an element with no popover
+// attribute, or show-modal aimed at a <div>, leaves a button that does
+// nothing when activated and exposes no state: the same defect as a
+// dangling aria-controls, which aria-valid-refs asserts, except that here
+// it is the browser's own semantics that go missing. Decidable from the
+// DOM, so asserted.
+//
+// Unknown command keywords are NOT judged: the command vocabulary is still
+// growing (new built-ins ship every few releases), and a keyword this
+// engine has not heard of is not evidence of a fault.
+const POPOVER_COMMANDS = new Set(['toggle-popover', 'show-popover', 'hide-popover']);
+const DIALOG_COMMANDS = new Set(['show-modal', 'close', 'request-close']);
+
+export default {
+  id: 'invoker-target',
+  name: 'Popover and command targets',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag412'],
+  help: 'popovertarget and commandfor must point at an element they can act on',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+  selector: '[popovertarget], [commandfor]',
+  evaluate(element) {
+    // 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();
+    const lookup = (id) => (id && root.getElementById?.(id)) || null;
+    const problems = [];
+
+    if (element.hasAttribute('popovertarget')) {
+      const id = element.getAttribute('popovertarget').trim();
+      const target = lookup(id);
+      if (!target) {
+        problems.push(`popovertarget="${id}" names no element in this document`);
+      } else if (!target.hasAttribute('popover')) {
+        problems.push(`popovertarget="${id}" points at a <${target.tagName.toLowerCase()}> with no popover attribute, which the button cannot open`);
+      }
+    }
+
+    if (element.hasAttribute('commandfor')) {
+      const id = element.getAttribute('commandfor').trim();
+      const command = (element.getAttribute('command') ?? '').trim().toLowerCase();
+      const target = lookup(id);
+      if (!target) {
+        problems.push(`commandfor="${id}" names no element in this document`);
+      } else if (!command) {
+        problems.push('commandfor has no command attribute, so activating the button does nothing');
+      } else if (POPOVER_COMMANDS.has(command) && !target.hasAttribute('popover')) {
+        problems.push(`command="${command}" needs a popover, and "${id}" has no popover attribute`);
+      } else if (DIALOG_COMMANDS.has(command) && target.tagName !== 'DIALOG') {
+        problems.push(`command="${command}" needs a <dialog>, and "${id}" is a <${target.tagName.toLowerCase()}>`);
+      }
+    }
+
+    if (!problems.length) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `${problems.join('; ')}. Activating this button does nothing, and the expanded state and control relationship the browser would expose for it are missing.`,
+      fix: 'Point the attribute at the id of the popover or dialog it drives (give that element the popover attribute, or make it a <dialog>), and keep the id unique in this tree.',
+    };
+  },
+};

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

@@ -22,6 +22,38 @@ const VALID_ROLES = new Set([
   'image', 'comment', 'mark', 'suggestion',
 ]);
 
+/** Edit distance between two short tokens (Levenshtein). */
+function editDistance(a, b) {
+  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i]);
+  for (let j = 1; j <= b.length; j++) rows[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      rows[i][j] = Math.min(
+        rows[i - 1][j] + 1,
+        rows[i][j - 1] + 1,
+        rows[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+  }
+  return rows[a.length][b.length];
+}
+
+/** The valid role closest to any of the written tokens, when one sits
+ *  within two edits of it; null when nothing is that close. */
+function nearestRole(tokens) {
+  let best = null;
+  let bestDistance = 3;
+  for (const token of tokens) {
+    const t = token.toLowerCase();
+    for (const role of VALID_ROLES) {
+      if (Math.abs(role.length - t.length) > 2) continue;
+      const distance = editDistance(t, role);
+      if (distance > 0 && distance < bestDistance) { best = role; bestDistance = distance; }
+    }
+  }
+  return best;
+}
+
 export default {
   id: 'valid-role',
   name: 'Valid roles',
@@ -46,6 +78,15 @@ export default {
     // canonical harmless case. The failure worth reporting is an invalid
     // role MASKING real semantics or decorating an interactive element.
     const tag = element.tagName.toLowerCase();
+    // A near-miss is almost always a typo: name the role that is one or two
+    // edits away, so "buton" reads as the misspelling it is rather than as
+    // a mystery ("role="buton" isn't really… what?" was the first reaction
+    // to the bare message on a seeded fault, 2026-08-27).
+    const nearest = nearestRole(tokens);
+    const hint = nearest ? ` (did you mean role="${nearest}"?)` : '';
+    const fix = nearest
+      ? `Correct the spelling to role="${nearest}", or remove the attribute to keep the element’s native role.`
+      : 'Use a valid role from the ARIA specification, or remove the attribute to keep the element’s native role.';
     // What the element falls back to when the bogus role is ignored. div/span
     // expose generic; <svg> exposes image (or graphics-document) in every
     // current engine, which is what an author writing role="img"/"image" on it
@@ -69,14 +110,14 @@ export default {
     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.',
+        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.`,
+        fix,
       };
     }
     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`}.`,
-      fix: 'Use a valid role from the ARIA specification, or remove the attribute to keep the element’s native role.',
+      message: `role="${element.getAttribute('role')}" is not a valid ARIA role${hint}, so assistive technology ignores it${genericFallback ? '' : ` and falls back to the element’s native <${tag}> semantics`}.`,
+      fix,
     };
   },
 };

package/engine/wcag22.js

@@ -66,7 +66,7 @@ export default [
   sc('2.2.6', 'Timeouts', 'AAA', 'manual', '2.1'),
   sc('2.3.1', 'Three Flashes or Below Threshold', 'A', 'manual'),
   sc('2.3.2', 'Three Flashes', 'AAA', 'manual'),
-  sc('2.3.3', 'Animation from Interactions', 'AAA', 'manual', '2.1'),
+  sc('2.3.3', 'Animation from Interactions', 'AAA', 'partial', '2.1'), // partial: reduced-motion reads scroll-driven, smooth-scroll and animated hover/focus motion against the page's prefers-reduced-motion rules; whether the motion is essential stays human
   sc('2.4.1', 'Bypass Blocks', 'A', 'partial'), // partial: "repeated across pages" can't be established from one page
   sc('2.4.2', 'Page Titled', 'A', 'partial'), // partial: document-title proves a title exists and catches known placeholders; whether a real one DESCRIBES the page needs a reader
   sc('2.4.3', 'Focus Order', 'A', 'partial'), // visual-order-divergence flags CSS order/*-reverse against DOM order; whether an order preserves MEANING stays human

package/package.json

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