pour-engine 1.1.0

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

@@ -0,0 +1,25 @@
+// WCAG SC 2.2.2 Pause, Stop, Hide (Level A)
+export default {
+  id: 'pause-stop-hide',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag222'],
+  help: 'Moving content must be pausable',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide.html',
+  selector: 'marquee, blink',
+  // The criterion is about VISIBLE movement — a display:none marquee moves
+  // nothing. aria-hidden content still moves on screen, so the rendered
+  // check (not the AT-exposure check) is the right filter.
+  visibility: 'visual',
+  evaluate(element) {
+    // scrollamount="0" is the documented way to ship a <marquee> that
+    // doesn't actually move.
+    if (element.tagName === 'MARQUEE' && element.getAttribute('scrollamount') === '0') {
+      return { status: 'pass' };
+    }
+    return {
+      status: 'fail',
+      message: `<${element.tagName.toLowerCase()}> scrolls or blinks with no way to pause it, which is unusable for people with attention or vestibular conditions.`,
+      fix: 'Replace it with static content, or a CSS animation with a pause control that honours prefers-reduced-motion.',
+    };
+  },
+};

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

@@ -0,0 +1,36 @@
+// WCAG SC 2.4.1 Bypass Blocks (Level A)
+import { collectRoots } from '../../lib/dom.js';
+
+export default {
+  id: 'bypass-blocks',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag241'],
+  help: 'The page must offer a way to skip repeated blocks',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/bypass-blocks.html',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    // 2.4.1's sufficient techniques: a skip link, landmarks (ARIA11), or
+    // headings (H69) — any one mechanism satisfies the criterion. Modern
+    // component pages keep ALL of these inside open shadow roots (the
+    // whole app under one custom element), so every root is searched —
+    // judging only the light DOM invents failures on web-component sites.
+    const doc = element.ownerDocument;
+    const roots = collectRoots(doc);
+    const inAnyRoot = (selector) => roots.some((root) => root.querySelector?.(selector));
+    if (inAnyRoot('main, [role="main"]')) return { status: 'pass' };
+    if (inAnyRoot('h1, h2, h3, h4, h5, h6, [role="heading"]')) return { status: 'pass' };
+    for (const root of roots) {
+      const firstLink = root.querySelector?.('a[href^="#"]');
+      const id = firstLink?.getAttribute('href').slice(1);
+      if (id && roots.some((r) => r.getElementById?.(id) || r.querySelector?.(`[id="${CSS.escape(id)}"]`))) {
+        return { status: 'pass' };
+      }
+    }
+    return {
+      status: 'fail',
+      message: 'No skip link, main landmark, or headings — keyboard users must Tab through the whole header/nav to reach anything.',
+      fix: 'Add a skip link like <a href="#content">Skip to content</a>, wrap primary content in <main>, or structure the page with headings.',
+    };
+  },
+};

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

@@ -0,0 +1,80 @@
+// WCAG SC 2.4.11 Focus Not Obscured (Minimum) (Level AA)
+// When a focusable element's box lies ENTIRELY under an opaque fixed or
+// sticky overlay at its resting position, focusing it shows the user
+// nothing — the criterion's core case (bottom cookie bars covering footer
+// links). Partial overlap passes 2.4.11 by definition ("not entirely
+// hidden"), so only full containment is judged, and only for elements
+// currently inside the viewport where the geometry is real.
+const FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea, summary, [tabindex]:not([tabindex="-1"])';
+
+export default {
+  id: 'focus-not-obscured',
+  impact: 'serious',
+  tags: ['wcag22aa', 'wcag2411'],
+  help: 'Focused elements must not be fully hidden behind overlays',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html',
+  selector: FOCUSABLE,
+  visibility: 'visual',
+  evaluateAll(elements) {
+    const doc = elements[0]?.ownerDocument ?? document;
+    const win = doc.defaultView;
+    // While a modal (cookie-consent dialog etc.) is open, the page behind
+    // it is INTENTIONALLY covered and focus is supposed to be trapped in
+    // the modal — a snapshot in that state proves nothing about 2.4.11.
+    // The backdrop is often a separate sibling of the dialog, so the modal
+    // state is checked document-wide, not per overlay.
+    const modal = [...doc.querySelectorAll('dialog[open], [role="dialog"], [role="alertdialog"], [aria-modal="true"]')]
+      .some((el) => {
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0 && getComputedStyle(el).visibility !== 'hidden';
+      });
+    if (modal) return elements.map(() => ({ status: 'pass' }));
+
+    // Hit-test per IN-VIEWPORT focusable instead of style-scanning the
+    // whole document for overlays: elementsFromPoint at the target's
+    // centre surfaces whatever paints above it, and only the handful of
+    // on-screen targets pay any cost — a 200k-node spec page costs the
+    // same as a landing page. Per-overlay verdicts are memoized.
+    const overlayVerdict = new Map();
+    const isObscuringOverlay = (layer) => {
+      if (overlayVerdict.has(layer)) return overlayVerdict.get(layer);
+      let verdict = false;
+      const style = getComputedStyle(layer);
+      if (style.position === 'fixed' || style.position === 'sticky') {
+        const bg = style.backgroundColor.match(/rgba?\(([^)]+)\)/)?.[1]?.split(',');
+        const alpha = bg?.[3] === undefined ? 1 : parseFloat(bg[3]);
+        const rect = layer.getBoundingClientRect();
+        verdict = alpha >= 0.9 && rect.width >= 40 && rect.height >= 24;
+      }
+      overlayVerdict.set(layer, verdict);
+      return verdict;
+    };
+    const covered = (rect, overlay) =>
+      rect.left >= overlay.left && rect.right <= overlay.right
+      && rect.top >= overlay.top && rect.bottom <= overlay.bottom;
+
+    return elements.map((element) => {
+      if (element.disabled) return { status: 'pass' };
+      const rect = element.getBoundingClientRect();
+      if (!rect.width || !rect.height) return { status: 'pass' };
+      // Only in-viewport geometry is trustworthy (or cheap).
+      if (rect.bottom < 0 || rect.right < 0 || rect.top > win.innerHeight || rect.left > win.innerWidth) {
+        return { status: 'pass' };
+      }
+      const x = Math.min(Math.max(rect.left + rect.width / 2, 0), win.innerWidth - 1);
+      const y = Math.min(Math.max(rect.top + rect.height / 2, 0), win.innerHeight - 1);
+      const stack = doc.elementsFromPoint(x, y);
+      const index = stack.indexOf(element);
+      if (index <= 0) return { status: 'pass' }; // topmost, or not hit-testable
+      const blocker = stack.slice(0, index).find((layer) =>
+        !layer.contains(element) && !element.contains(layer)
+        && isObscuringOverlay(layer) && covered(rect, layer.getBoundingClientRect()));
+      if (!blocker) return { status: 'pass' };
+      return {
+        status: 'fail',
+        message: 'This focusable element sits entirely behind an opaque fixed/sticky overlay — when keyboard focus lands on it, nothing visible changes and the user is lost.',
+        fix: 'Add scroll-padding for the overlay height, or make the overlay dismissible/non-overlapping so focused elements stay at least partly visible.',
+      };
+    });
+  },
+};

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

@@ -0,0 +1,18 @@
+// WCAG SC 2.4.2 Page Titled (Level A)
+export default {
+  id: 'document-title',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag242'],
+  help: 'The page must have a title that describes its topic or purpose',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/page-titled.html',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    if (element.ownerDocument.title.trim()) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'The page has no title, so users of screen readers and browser tabs cannot tell what it is.',
+      fix: 'Add <title>Page name — Site name</title> inside <head>.',
+    };
+  },
+};

package/engine/rules/wcag/2.4.4-link-name.js

@@ -0,0 +1,19 @@
+// WCAG SC 2.4.4 Link Purpose (In Context) (Level A) · SC 4.1.2 Name, Role, Value (Level A)
+export default {
+  id: 'link-name',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag244', 'wcag412'],
+  help: 'Links must have an accessible name',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html',
+  // a[href] has the link role implicitly; role="link" claims it explicitly.
+  // (Links without href have no link role and are correctly excluded.)
+  selector: 'a[href], [role="link"]',
+  evaluate(element, { accessibleName }) {
+    if (accessibleName(element)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'This link has no accessible name — screen readers can only announce its URL.',
+      fix: 'Add text content to the link, alt text to the image inside it, or an aria-label.',
+    };
+  },
+};

package/engine/rules/wcag/2.4.7-focus-visible.js

@@ -0,0 +1,46 @@
+// WCAG SC 2.4.7 Focus Visible (Level AA)
+// A stylesheet that strips focus outlines without providing a replacement
+// indicator is the classic 2.4.7 failure (F78). Cross-origin sheets are
+// unreadable and skipped; a replacement indicator can live in a different
+// rule entirely — so this flags for review, it never asserts a fail.
+function focusSuppressors(doc) {
+  const suspects = [];
+  const scan = (rules) => {
+    for (const rule of rules) {
+      if (rule.cssRules) { scan(rule.cssRules); continue; } // @media/@supports
+      if (!rule.selectorText || !/:focus/.test(rule.selectorText)) continue;
+      const style = rule.style;
+      if (!style) continue;
+      const outline = `${style.getPropertyValue('outline')} ${style.getPropertyValue('outline-style')} ${style.getPropertyValue('outline-width')}`;
+      const removesOutline = /\bnone\b/.test(outline) || /(^|\s)0(px)?(\s|$)/.test(outline);
+      if (!removesOutline) continue;
+      const replaced = style.getPropertyValue('box-shadow') || style.getPropertyValue('border')
+        || style.getPropertyValue('border-color') || style.getPropertyValue('background')
+        || style.getPropertyValue('background-color') || style.getPropertyValue('text-decoration');
+      if (!replaced) suspects.push(rule.selectorText);
+    }
+  };
+  for (const sheet of doc.styleSheets) {
+    try { scan(sheet.cssRules); } catch { /* cross-origin sheet */ }
+  }
+  return suspects;
+}
+
+export default {
+  id: 'focus-visible',
+  impact: 'serious',
+  tags: ['wcag2aa', 'wcag247'],
+  help: 'Keyboard focus must remain visible',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    const suspects = focusSuppressors(element.ownerDocument);
+    if (!suspects.length) return { status: 'pass' };
+    const shown = suspects.slice(0, 3).join(', ');
+    return {
+      status: 'incomplete',
+      message: `${suspects.length} CSS rule(s) remove the focus outline without setting a replacement in the same rule (e.g. ${shown}) — if no other rule provides a visible indicator, keyboard users lose their place. Tab through the page to check.`,
+    };
+  },
+};

package/engine/rules/wcag/2.5.3-label-in-name.js

@@ -0,0 +1,88 @@
+// WCAG SC 2.5.3 Label in Name (Level A)
+// When a UI COMPONENT has a visible text label AND an aria-provided name,
+// the visible text must appear in the accessible name — otherwise
+// voice-control users saying the visible label cannot activate it.
+//
+// Scope per spec: interactive components only (things a user operates), and
+// only their VISIBLE text. Screen-reader-only text (sr-only clips, offscreen
+// text-indent) is not a visible label; aria-hidden text IS visible to
+// sighted users and counts; symbolic content ("×", "→", emoji) is not a
+// text label at all.
+//
+// Re-enabled 2026-07-27 (was parked 2026-07-25 for marginal hits): rewritten
+// to compute genuinely visible text — sr-only exclusion, input values,
+// aria-labelledby, slotted content — so it can run by default.
+const BASES = [
+  'button', 'a[href]', 'summary',
+  'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]',
+  '[role="button"]', '[role="link"]', '[role="menuitem"]', '[role="tab"]',
+  '[role="checkbox"]', '[role="radio"]', '[role="switch"]',
+];
+const COMPONENTS = BASES.flatMap((base) => [`${base}[aria-label]`, `${base}[aria-labelledby]`]).join(', ');
+
+const HAS_LETTERS = /\p{L}/u;
+
+/** Lowercase, letters/digits only between single spaces — so "Search…" and
+ *  "search" compare equal. */
+function normalize(text) {
+  return text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/** Is this element's own box visually erased (sr-only, offscreen, invisible)?
+ *  aria-hidden is deliberately NOT checked: it hides content from assistive
+ *  technology, not from sighted users. */
+function visuallyErased(element) {
+  const style = getComputedStyle(element);
+  if (style.display === 'none' || style.visibility === 'hidden') return true;
+  if (parseFloat(style.opacity) === 0 || parseFloat(style.fontSize) === 0) return true;
+  const rect = element.getBoundingClientRect();
+  const clipped = /hidden|clip/.test(`${style.overflow} ${style.overflowX} ${style.overflowY}`)
+    || style.clipPath !== 'none' || (style.clip !== 'auto' && style.position === 'absolute');
+  if ((rect.width <= 1 || rect.height <= 1) && clipped) return true;
+  const indent = parseFloat(style.textIndent) || 0;
+  if (Math.abs(indent) > rect.width && (clipped || Math.abs(indent) > 1000)) return true;
+  return false;
+}
+
+/** The text a sighted user actually sees inside the component (slot-aware). */
+function visibleText(nodes) {
+  let text = '';
+  for (const node of nodes) {
+    if (node.nodeType === 3 /* TEXT_NODE */) { text += node.textContent; continue; }
+    if (node.nodeType !== 1 /* ELEMENT_NODE */) continue;
+    const tag = node.tagName.toLowerCase();
+    if (tag === 'script' || tag === 'style' || tag === 'noscript' || tag === 'template') continue;
+    if (node.hasAttribute('hidden') || visuallyErased(node)) continue;
+    if (tag === 'slot') {
+      const assigned = node.assignedNodes?.() ?? [];
+      text += visibleText(assigned.length ? assigned : node.childNodes);
+      continue;
+    }
+    text += visibleText(node.childNodes);
+  }
+  return text;
+}
+
+export default {
+  id: 'label-in-name',
+  impact: 'serious',
+  tags: ['wcag21a', 'wcag253'],
+  help: 'The visible label must be part of the accessible name',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html',
+  selector: COMPONENTS,
+  evaluate(element, { accessibleName }) {
+    const rawVisible = element.tagName === 'INPUT'
+      ? (element.getAttribute('value') ?? '')
+      : visibleText(element.childNodes);
+    const visible = rawVisible.replace(/\s+/g, ' ').trim();
+    // Icon/symbol-only or nothing visible: there is no text label to match.
+    if (!visible || !HAS_LETTERS.test(visible)) return { status: 'pass' };
+    const name = accessibleName(element);
+    if (normalize(name).includes(normalize(visible))) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `The visible text "${visible}" is not contained in the accessible name "${name}" — saying the visible label out loud won't activate this control.`,
+      fix: 'Make the aria-label start with the visible text, or remove the aria-label so the visible text names the control.',
+    };
+  },
+};

package/engine/rules/wcag/2.5.5-target-size-enhanced.js

@@ -0,0 +1,14 @@
+// WCAG SC 2.5.5 Target Size (Enhanced) (Level AAA)
+// Same geometry as 2.5.8, at 44×44px — and WITHOUT the spacing exception,
+// which 2.5.5 does not offer (its exceptions: equivalent, inline,
+// user-agent, essential).
+import { createTargetSizeRule } from './2.5.8-target-size.js';
+
+export default createTargetSizeRule({
+  id: 'target-size-enhanced',
+  tags: ['wcag2aaa', 'wcag255'],
+  help: 'Interactive targets must be at least 44×44 pixels (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html',
+  min: 44,
+  spacingException: false,
+});

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

@@ -0,0 +1,159 @@
+// WCAG SC 2.5.8 Target Size (Minimum) (Level AA)
+// WCAG 2.2's new Target Size (Minimum): interactive targets ≥ 24×24 CSS px.
+// Exceptions we honour, per the spec:
+//   - inline: the target is in a sentence — an inline element with actual
+//     text alongside it on the line. Being display:inline alone is NOT
+//     enough: nav/footer link lists are inline by default but are standalone
+//     targets, not text, and the spec does not exempt them.
+//   - spacing: an undersized target is exempt when a 24px-diameter circle
+//     centred on it intersects no other target's rectangle and no other
+//     undersized target's circle (the spec's circle test, not a
+//     centre-to-centre distance).
+//   - zero-size rects (element not laid out — nothing to measure)
+// Not detectable ("essential", "equivalent control elsewhere") — those need
+// the human reviewing the finding.
+
+const TARGETS = 'a[href], button, input, select, [role="button"], [role="link"]';
+
+/** Is this target genuinely sitting in a line of text (the spec's "in a
+ *  sentence / size constrained by line-height of non-target text" exception)?
+ *  True for inline elements that share a line with non-target text — either a
+ *  text node or an inline non-target element carrying text — checked up the
+ *  inline-ancestor chain, so a link wrapped in a <sup>/<span> inside a
+ *  sentence (Wikipedia-style citations) still counts as in-text. A link in a
+ *  nav list (block/list-item parent, only other links beside it) does not. */
+/**
+ * A target the pointer can never meaningfully hit is exempt from a POINTER
+ * target-size rule: the sr-only clip pattern (≤1px boxes), skip links
+ * parked off-canvas until focused, clip-path'd controls, opacity: 0.
+ * These are keyboard affordances, not pointer targets — and their phantom
+ * rects must not count as "crowding" for the real targets around them.
+ */
+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
+  const style = getComputedStyle(element);
+  if ((parseFloat(style.opacity) || 0) === 0) return true;
+  if (style.clipPath !== 'none' || (style.clip !== 'auto' && style.position === 'absolute')) return true;
+  return false;
+}
+
+function isInTextLine(element) {
+  let node = element;
+  // inline-block/inline-flex links inside a sentence are still "in a line
+  // of text" for the spec's exception — the line-height constrains them
+  // exactly the same; the text-sibling requirement below is what keeps
+  // nav/footer link lists (no non-target text) out of the exemption.
+  while (node && getComputedStyle(node).display.startsWith('inline')) {
+    for (const sibling of node.parentNode?.childNodes ?? []) {
+      if (sibling === node) continue;
+      if (sibling.nodeType === Node.TEXT_NODE && sibling.textContent.trim()) return true;
+      if (sibling.nodeType === Node.ELEMENT_NODE
+        && !sibling.matches(TARGETS)
+        && sibling.textContent.trim()
+        && getComputedStyle(sibling).display.startsWith('inline')) return true;
+    }
+    node = node.parentElement;
+  }
+  return false;
+}
+
+/** Nearest distance from a point to a rectangle (0 when inside it). */
+function pointToRectDistance(point, rect) {
+  const dx = Math.max(rect.left - point.x, 0, point.x - rect.right);
+  const dy = Math.max(rect.top - point.y, 0, point.y - rect.bottom);
+  return Math.hypot(dx, dy);
+}
+
+/**
+ * Both target-size criteria share the geometry; they differ in minimum and
+ * exceptions:
+ * 2.5.8 Target Size (Minimum), AA — 24px, WITH the spacing exception
+ * 2.5.5 Target Size (Enhanced), AAA — 44px, NO spacing exception (the spec
+ * lists only equivalent/inline/user-agent/essential there)
+ */
+export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingException }) {
+  return {
+  id,
+  impact: 'serious',
+  tags,
+  help,
+  helpUrl,
+  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) {
+    // 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
+    // 13px input alone.
+    const targetRect = (element) => {
+      const rect = element.getBoundingClientRect();
+      const label = element.labels?.[0];
+      if (!label) return rect;
+      const labelRect = label.getBoundingClientRect();
+      if (!labelRect.width || !labelRect.height) return rect;
+      const left = Math.min(rect.left, labelRect.left);
+      const top = Math.min(rect.top, labelRect.top);
+      const right = Math.max(rect.right, labelRect.right);
+      const bottom = Math.max(rect.bottom, labelRect.bottom);
+      return { left, top, right, bottom, width: right - left, height: bottom - top };
+    };
+    // The spec's User Agent Control exception: a default-styled native
+    // checkbox/radio is sized by the browser, not the author.
+    const uaControlled = (element) => element.tagName === 'INPUT'
+      && (element.type === 'checkbox' || element.type === 'radio')
+      && getComputedStyle(element).appearance !== 'none';
+    const rects = elements.map(targetRect);
+    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,
+    // usually) belongs to the name rules, not to size judgment. Pointer-
+    // invisible targets (clipped skip links etc.) are excluded the same
+    // way, on both sides of the crowding test.
+    const laidOut = rects.map((r, i) => r.width > 0 && r.height > 0 && !isHiddenFromPointer(elements[i], r));
+    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.
+    const encloses = (a, b) =>
+      a.left <= b.left && a.right >= b.right && a.top <= b.top && a.bottom >= b.bottom;
+
+    return elements.map((element, i) => {
+      if (!laidOut[i]) return { status: 'pass' }; // not laid out / not a pointer target
+      if (!undersized[i]) return { status: 'pass' };
+      if (uaControlled(element)) return { status: 'pass' }; // UA Control exception
+      if (isInTextLine(element)) return { status: 'pass' };
+      if (spacingException) {
+        // Spacing exception: the min-sized circle around this target must
+        // clear every other target's rect and every other undersized
+        // target's circle.
+        const crowded = elements.some((other, j) => {
+          if (j === i || !laidOut[j]) return false;
+          if (other.contains(element) || element.contains(other)) return false; // same control, nested markup
+          if (encloses(rects[j], rects[i]) || encloses(rects[i], rects[j])) return false;
+          if (undersized[j] && Math.hypot(centers[j].x - centers[i].x, centers[j].y - centers[i].y) < min) return true;
+          return pointToRectDistance(centers[i], rects[j]) < min / 2;
+        });
+        if (!crowded) return { status: 'pass' };
+      }
+      const rect = rects[i];
+      return {
+        status: 'fail',
+        message: spacingException
+          ? `This target is ${Math.round(rect.width)}×${Math.round(rect.height)}px AND another target crowds it (within ${min}px) — small targets are only acceptable with clear space around them; crowded ones are hard to hit for users with motor impairments.`
+          : `This target is ${Math.round(rect.width)}×${Math.round(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' : ''}.`,
+      };
+    });
+  },
+  };
+}
+
+export default createTargetSizeRule({
+  id: 'target-size',
+  tags: ['wcag22aa', 'wcag258'],
+  help: 'Interactive targets must be at least 24×24 pixels',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html',
+  min: 24,
+  spacingException: true,
+});

package/engine/rules/wcag/3.1.1-html-lang.js

@@ -0,0 +1,31 @@
+// WCAG SC 3.1.1 Language of Page (Level A)
+// Rough BCP 47 shape: primary subtag + optional extras ("en", "en-GB", "zh-Hans").
+const LANG_PATTERN = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+
+export default {
+  id: 'html-lang',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag311'],
+  help: 'The <html> element must declare a valid language',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/language-of-page.html',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    const lang = element.getAttribute('lang')?.trim();
+    if (!lang) {
+      return {
+        status: 'fail',
+        message: 'No lang attribute: screen readers will guess the language and may mispronounce everything.',
+        fix: 'Add lang to the html element, e.g. <html lang="en">.',
+      };
+    }
+    if (!LANG_PATTERN.test(lang)) {
+      return {
+        status: 'fail',
+        message: `lang="${lang}" is not a valid language tag.`,
+        fix: 'Use a BCP 47 tag such as lang="en" or lang="en-GB".',
+      };
+    }
+    return { status: 'pass' };
+  },
+};

package/engine/rules/wcag/3.1.2-valid-lang-parts.js

@@ -0,0 +1,20 @@
+// WCAG SC 3.1.2 Language of Parts (Level AA)
+const LANG_PATTERN = /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/;
+
+export default {
+  id: 'valid-lang-parts',
+  impact: 'serious',
+  tags: ['wcag2aa', 'wcag312'],
+  help: 'lang attributes on page parts must be valid',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/language-of-parts.html',
+  selector: '[lang]:not(html)',
+  evaluate(element) {
+    const lang = element.getAttribute('lang').trim();
+    if (lang === '' || LANG_PATTERN.test(lang)) return { status: 'pass' }; // empty resets to page language
+    return {
+      status: 'fail',
+      message: `lang="${lang}" is not a valid language tag, so screen readers may switch to the wrong pronunciation.`,
+      fix: 'Use a BCP 47 tag such as lang="fr" or lang="de-AT".',
+    };
+  },
+};

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

@@ -0,0 +1,37 @@
+// WCAG SC 3.3.8 Accessible Authentication (Minimum) (Level AA)
+// The SC requires a cognitive-function-test-free way to authenticate, and
+// names copy-paste and password managers as the mechanisms that provide
+// it. Blocking paste on a password/OTP field removes exactly that
+// mechanism — a provable failure. autocomplete="off" merely ASKS the
+// browser not to help; password managers often fill anyway, so that's a
+// review flag, not an assertion.
+export default {
+  id: 'auth-field-obstruction',
+  impact: 'serious',
+  tags: ['wcag22aa', 'wcag338'],
+  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"], input[autocomplete~="current-password"], input[autocomplete~="one-time-code"], input[autocomplete~="new-password"]',
+  evaluate(element) {
+    // Inline handlers are the only statically-visible blockers; framework
+    // listeners are invisible to a DOM audit.
+    const blocking = ['onpaste', 'ondrop'].find((attr) => {
+      const handler = element.getAttribute(attr) ?? '';
+      return /return\s+false|preventDefault/.test(handler);
+    });
+    if (blocking) {
+      return {
+        status: 'fail',
+        message: `This authentication field blocks ${blocking === 'onpaste' ? 'pasting' : 'dropping'} — users of password managers must retype credentials from memory, a cognitive function test 3.3.8 forbids.`,
+        fix: 'Remove the paste/drop blocking; let password managers and copy-paste work.',
+      };
+    }
+    if ((element.getAttribute('autocomplete') ?? '').trim().toLowerCase() === 'off') {
+      return {
+        status: 'incomplete',
+        message: 'This authentication field sets autocomplete="off", discouraging password managers. Browsers often fill anyway — verify a password manager can complete this login without retyping.',
+      };
+    }
+    return { status: 'pass' };
+  },
+};

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

@@ -0,0 +1,44 @@
+// WCAG SC 4.1.2 Name, Role, Value (Level A)
+// ARIA attributes must be supported by the element's role — aria-selected
+// on a plain link, aria-checked on a heading, etc. are ignored (or worse,
+// misreported) by assistive technology.
+import { GLOBAL_ARIA, ROLE_ARIA, KNOWN_ARIA, effectiveRole } from '../../lib/roles.js';
+
+// aria-label/labelledby misuse on generic elements has its own rule
+// (aria-label-misuse) — excluded here to avoid double-reporting.
+const HANDLED_ELSEWHERE = new Set(['label', 'labelledby']);
+
+export default {
+  id: 'aria-allowed-attr',
+  impact: 'critical',
+  tags: ['wcag2a', 'wcag412'],
+  help: 'ARIA attributes must be allowed for the element’s role',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+  selector: '*',
+  visibleOnly: false,
+  evaluate(element) {
+    // Plain loop, no intermediate arrays: this runs on every element of the
+    // page, and nearly all have no aria-* attributes at all.
+    const ariaAttrs = [];
+    for (const { name } of element.attributes) {
+      if (!name.startsWith('aria-')) continue;
+      const attr = name.slice(5);
+      // Unknown/misspelled attributes are aria-attr-valid's finding — judging
+      // them against a role too would report the same typo twice.
+      if (!HANDLED_ELSEWHERE.has(attr) && KNOWN_ARIA.has(attr)) ariaAttrs.push(attr);
+    }
+    if (!ariaAttrs.length) return { status: 'pass' };
+
+    const role = effectiveRole(element);
+    const allowed = role && ROLE_ARIA[role];
+    if (!allowed) return { status: 'pass' }; // role not modelled: don't guess
+
+    const disallowed = ariaAttrs.filter((name) => !GLOBAL_ARIA.has(name) && !allowed.includes(name));
+    if (!disallowed.length) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `${disallowed.map((n) => `aria-${n}`).join(', ')} is not supported on role "${role}" — assistive technology ignores it or announces the wrong state.`,
+      fix: `Use a role that supports ${disallowed.map((n) => `aria-${n}`).join('/')}, or remove the attribute(s).`,
+    };
+  },
+};