pour-engine 1.40.0 → 1.42.0

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

@@ -5,6 +5,7 @@
 import {
   parseColor, contrastRatio, composite, effectiveBackground, isLargeText,
   backgroundImageSource, cumulativeOpacity, opacityAnimating, restingOpacity, showRatio,
+  hasPaintEffects, opacityGroupPaint, splitBackgroundLayers, sampledGradientRange,
 } from '../../lib/contrast.js';
 
 export default {
@@ -56,10 +57,26 @@ export default {
     // far less contrast than its declared colours suggest.
     const opacity = opacityAnimating(element) ? restingOpacity(element) : cumulativeOpacity(element);
     if (opacity < 0.05) return { status: 'pass' };
+    if (hasPaintEffects(element)) {
+      return { status: 'incomplete', message: 'A filter or blend mode changes the colours presented inside this field. Check the resulting text contrast by eye.' };
+    }
     // The control's own background wins; else whatever shows through it.
     const own = parseColor(style.backgroundColor);
     let background;
-    if (own && own.a >= 1) {
+    if (style.backgroundImage !== 'none') {
+      const layers = splitBackgroundLayers(style.backgroundImage);
+      const range = layers.length === 1 && layers[0].includes('gradient(')
+        ? sampledGradientRange(layers[0]) : null;
+      // A constant opaque gradient has exactly one painted background.
+      // Other image paint needs spatial sampling, not its fallback colour.
+      const fullBox = /^(auto|auto auto)$/.test(style.backgroundSize)
+        && style.backgroundPosition === '0% 0%'
+        && ['repeat', 'no-repeat'].includes(style.backgroundRepeat);
+      if (!range || range.min !== range.max || opacity < 1 || !fullBox) {
+        return { status: 'incomplete', message: 'An image or gradient paints this field background. Check its text against the pixels behind it.' };
+      }
+      background = range.minColor;
+    } else if (own && own.a >= 1) {
       background = own;
     } else {
       // An image or gradient painted under a see-through control is a
@@ -73,18 +90,27 @@ export default {
         };
       }
       const behind = effectiveBackground(element);
-      background = behind && own && own.a > 0 ? composite(own, behind) : behind;
+      background = behind; // effectiveBackground already composites the field fill
     }
     if (!background) {
       return { status: 'incomplete', message: 'The control’s background could not be determined — check its text contrast by eye.' };
     }
     const required = isLargeText(style) ? 3 : 4.5;
 
+    let unresolvedGroup = false;
     const judge = (color, what, ownOpacity = 1) => {
       const parsed = parseColor(color);
       if (!parsed || parsed.a === 0) return null;
       // Same treatment the main rule gives faded text: what reaches the eye
       // is the declared colour thinned by the opacity it is painted at.
+      if (opacity < 1) {
+        const group = opacityGroupPaint(element, { ...parsed, a: parsed.a * ownOpacity });
+        if (group?.unresolved) { unresolvedGroup = true; return null; }
+        if (group) {
+          const ratio = contrastRatio(group.foreground, group.background);
+          return ratio >= required ? null : { what, ratio };
+        }
+      }
       const painted = opacity * ownOpacity;
       const faded = painted < 1 ? { ...parsed, a: parsed.a * painted } : parsed;
       const fg = faded.a < 1 ? composite(faded, background) : faded;
@@ -94,16 +120,18 @@ export default {
     };
 
     const failures = [];
-    const valueVerdict = judge(style.color, 'value text');
+    const valueVerdict = judge(style.webkitTextFillColor || style.color, 'value text');
     if (valueVerdict) failures.push(valueVerdict);
     // Placeholder text is real text users must read; browsers expose its
-    // computed colour via the ::placeholder pseudo-element.
-    if (element.getAttribute('placeholder')?.trim()) {
+    // computed colour via the ::placeholder pseudo-element. Selectors 4
+    // defines :placeholder-shown for controls actually showing that text;
+    // a populated field's unpainted hint must not create a violation.
+    if (element.getAttribute('placeholder')?.trim() && element.matches(':placeholder-shown')) {
       let placeholderColor = null;
       let placeholderOpacity = 1;
       try {
         const placeholderStyle = getComputedStyle(element, '::placeholder');
-        placeholderColor = placeholderStyle.color;
+        placeholderColor = placeholderStyle.webkitTextFillColor || placeholderStyle.color;
         // ::placeholder { opacity: .3 } is a widespread idiom (framework
         // resets, Firefox's own UA default of 0.54), and the criterion is on
         // the visual presentation of the text, which is the faded colour.
@@ -117,6 +145,7 @@ export default {
         if (verdict) failures.push(verdict);
       }
     }
+    if (unresolvedGroup) return { status: 'incomplete', message: 'The field and its text fade together over an unresolved background. Check the presented text contrast by eye.' };
     if (!failures.length) return { status: 'pass' };
     const worst = failures.sort((a, b) => a.ratio - b.ratio)[0];
     return {

package/engine/rules/wcag/1.4.4-meta-viewport.js

@@ -20,10 +20,15 @@ export default {
     const maxScale = content.match(/maximum-scale\s*=\s*([\d.]+)/i);
     const cappedZoom = maxScale && parseFloat(maxScale[1]) < 2;
     if (!disablesZoom && !cappedZoom) return { status: 'pass' };
+    // Asserted the way ACT rule b4f0c3 asserts it, under its assumption that
+    // the page provides no other way to enlarge the text (technique G178).
+    // The message names that assumption so a reviewer who knows the page
+    // has its own text-size control can dismiss the finding.
+    // https://www.w3.org/WAI/standards-guidelines/act/rules/b4f0c3/
     return {
       status: 'fail',
-      message: 'This viewport meta tag stops low-vision users from zooming the page.',
-      fix: 'Remove user-scalable=no and any maximum-scale below 2 from the viewport meta tag.',
+      message: 'This viewport meta tag stops users zooming the page, so text cannot be enlarged with the browser. 1.4.4 is met only if the page provides its own control that enlarges all text to 200% (technique G178); this finding assumes it does not, since the tag cannot show it.',
+      fix: 'Remove user-scalable=no and any maximum-scale below 2 from the viewport meta tag. If the page has its own text-size control that reaches 200%, record that and dismiss this finding.',
     };
   },
 };

package/engine/rules/wcag/1.4.8-text-justified.js

@@ -0,0 +1,49 @@
+// WCAG SC 1.4.8 Visual Presentation (Level AAA) — the justified-text slice
+//
+// 1.4.8 lists five things a reader must be able to achieve for blocks of
+// text; the third is "text is not justified (aligned to both the left and
+// the right margins)". Justified text is the one of the five that the page
+// itself imposes and that shows in a computed style; F88 ("using text that
+// is justified") is its failure technique. The criterion is met when a
+// mechanism lets the reader undo it, and the Understanding says the
+// browser may provide that mechanism, so a justified block is asked about,
+// not failed: the DOM cannot show whether a style switcher or a reader
+// mode is on offer. The other four requirements (colour selection, 80
+// character measure, line spacing, 200% resize) are met by browser
+// mechanisms on ordinary pages and are not judged here.
+//
+// Only blocks with real running text count: the block's own text and the
+// text of its inline children, at least 120 characters, so a justified
+// wrapper is reported once at the paragraph that carries the words, not at
+// every ancestor that inherits the alignment.
+const BLOCK = /^(?:block|list-item|table-cell|flow-root)$/;
+
+function inlineText(element) {
+  let text = '';
+  for (const node of element.childNodes) {
+    if (node.nodeType === 3) text += node.textContent;
+    else if (node.nodeType === 1 && getComputedStyle(node).display.startsWith('inline')) text += node.textContent;
+  }
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+export default {
+  id: 'text-justified',
+  name: 'Justified text',
+  impact: 'moderate',
+  tags: ['wcag2aaa', 'wcag148'],
+  help: 'Blocks of text should not be justified to both margins (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/visual-presentation.html',
+  selector: 'p, li, dd, dt, td, th, blockquote, figcaption, summary, address, div, section, article, main, aside, header, footer',
+  evaluate(element) {
+    const style = getComputedStyle(element);
+    if (style.textAlign !== 'justify' && style.textAlign !== 'justify-all') return { status: 'pass' };
+    if (!BLOCK.test(style.display)) return { status: 'pass' };
+    if (inlineText(element).length < 120) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: 'This block of text is justified to both margins. The uneven spaces between words form "rivers of white" down the page that some readers with dyslexia or low vision cannot read across (failure F88). 1.4.8 allows justified text only where a mechanism lets the reader switch it off; check that one exists, in the page or the browser.',
+      fix: 'Set text-align: start (or left) on running text, or offer a control that turns justification off.',
+    };
+  },
+};

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

@@ -92,13 +92,13 @@ export default {
     // An explicit negative tabindex is the author OPTING OUT of the tab
     // order, and the browser honours it: measured in Chrome 151, a scroller
     // with tabindex="-1" is skipped by Tab even though the same scroller
-    // without the attribute would be auto-focused. Nothing inside is
-    // tabbable either, so the overflowed content is unreachable by keyboard
-    // in every engine — assertable, not browser-dependent.
+    // without the attribute would be auto-focused. That does not prove
+    // keyboard inoperability: external controls may scroll the region or
+    // move focus into it programmatically.
     if (element.hasAttribute('tabindex')) {
       return {
-        status: 'fail',
-        message: 'This region scrolls, holds nothing tabbable, and its tabindex="-1" removes the region itself from the tab order — keyboard users cannot reach the overflowed content in any browser.',
+        status: 'incomplete',
+        message: 'This region scrolls, has no detected tabbable content and is removed from sequential focus by a negative tabindex. Check whether keyboard-operable controls elsewhere scroll it or move focus into it; without such a mechanism, the overflowed content may be unreachable.',
         fix: 'Change tabindex="-1" to tabindex="0" (plus role="region" and an aria-label describing it), or make something inside it tabbable.',
       };
     }

package/engine/rules/wcag/2.2.1-meta-refresh.js

@@ -10,7 +10,7 @@
  * the old test demanded the literal "url=", so content="0;https://…" was
  * asserted as a reload loop while the browser redirected from it.)
  */
-function refreshDestination(content) {
+export function refreshDestination(content) {
   let rest = content.replace(/^\s*[\d.]*\s*(?:[;,]\s*)?/, '');
   // "url" is consumed letter by letter, then optional whitespace and "=".
   rest = rest.replace(/^url\s*(?:=\s*)?/i, '');
@@ -33,7 +33,7 @@ function refreshDestination(content) {
  * rule asserted a time limit on pages the browser never moves. Verified in
  * Chromium: both of those pages stay put while content="1; url=…" navigates.
  */
-function refreshDelay(content) {
+export function refreshDelay(content) {
   const isAsciiSpace = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\f' || c === '\r';
   const isDigit = (c) => c >= '0' && c <= '9';
   let i = 0;
@@ -80,10 +80,16 @@ export default {
     // 2.2.1 exempts a time limit "longer than 20 hours" — 20 hours exactly
     // is still inside the criterion.
     if (delay > 72000) return { status: 'pass' };
+    // Asserted the way ACT rule bc659a asserts it: a meta refresh gives the
+    // user no way to turn the limit off, adjust it or extend it, so the only
+    // escapes are the real-time and essential exceptions, which the tag
+    // cannot show either way. The message names that assumption so a
+    // reviewer who knows the page offers a control can dismiss the finding.
+    // https://www.w3.org/WAI/standards-guidelines/act/rules/bc659a/
     return {
       status: 'fail',
-      message: `The page refreshes/redirects after ${delay}s — slow readers lose their place (or the whole page) with no control.`,
-      fix: 'Remove the timed refresh; let users act in their own time.',
+      message: `The page refreshes or redirects itself after ${delay}s. Slow readers lose their place, or the whole page, and a meta refresh offers no way to turn that off, adjust it or extend it. 2.2.1 excuses a time limit only where it is part of a real-time event or essential; this finding assumes neither applies, since the tag cannot show it.`,
+      fix: 'Remove the timed refresh; let users act in their own time. If the page offers a control that turns the refresh off, or the refresh is essential, record that and dismiss this finding.',
     };
   },
 };

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

@@ -6,8 +6,8 @@
 //
 // Two shapes are checkable, and they need different verdicts.
 //
-// <marquee> and <blink> exist only to move, ship no control of their own,
-// and are obsolete: a definite failure.
+// Legacy markup is not proof of motion: blink has no native animation in
+// modern browsers, and a marquee may be stopped or controlled by script.
 //
 // A CSS animation set to repeat for ever is the modern ticker. Clauses 1
 // and 2 are settled by the CSS itself — it starts with the page and never
@@ -117,15 +117,15 @@ export default {
     if (!elements.length) return [];
     const moving = endlesslyMoving(elements[0].ownerDocument);
     return elements.map((element) => {
-      if (element.tagName === 'MARQUEE' || element.tagName === 'BLINK') {
+      if (element.tagName === 'MARQUEE') {
         // 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.`,
+          status: 'incomplete',
+          message: 'This marquee can scroll content. Check whether it actually starts automatically, continues for more than five seconds alongside other content, and has a working pause, stop or hide mechanism. The element alone does not establish those 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.2.4-meta-refresh-no-exceptions.js

@@ -0,0 +1,50 @@
+// WCAG SC 2.2.4 Interruptions (Level AAA) and SC 3.2.5 Change on Request
+// (Level AAA) — the timed meta refresh, with none of 2.2.1's escapes.
+//
+// Both criteria list the same two failure techniques: F40 (a meta redirect
+// with a time limit) and F41 (a meta refresh that reloads the page). 2.2.1
+// excuses a limit longer than 20 hours; neither AAA criterion does. An
+// interruption the reader cannot postpone or suppress breaks 2.2.4, and a
+// change of context the reader did not ask for breaks 3.2.5, however long
+// the timer. The instant redirect (zero seconds with a destination) stays
+// allowed: G110 and H76 are sufficient techniques of 3.2.5 itself.
+//
+// One rule, two tags, on the twin-tag precedent (2.1.1/2.1.3): the same
+// fact fails both. It runs beside 2.2.1's rule at AAA scope, so a refresh
+// inside 20 hours is reported by both; each names its own criterion.
+// 2.2.4 exempts emergencies, which a meta tag cannot show, so the message
+// names that assumption the way the 2.2.1 rule names its own.
+import { refreshDelay, refreshDestination } from './2.2.1-meta-refresh.js';
+
+export default {
+  id: 'meta-refresh-no-exceptions',
+  name: 'Timed refresh (AAA)',
+  impact: 'serious',
+  tags: ['wcag2aaa', 'wcag224', 'wcag325'],
+  help: 'The page must not refresh or redirect itself on any timer (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/interruptions.html',
+  selector: 'meta[http-equiv="refresh" i]',
+  visibleOnly: false,
+  evaluate(element) {
+    const content = element.getAttribute('content') ?? '';
+    const delay = refreshDelay(content);
+    // The browser discards the directive: nothing is scheduled.
+    if (delay === null) return { status: 'pass' };
+    const hasDestination = refreshDestination(content) !== '';
+    // Zero seconds with a destination is the instant client-side redirect
+    // that G110 and H76 permit.
+    if (delay === 0 && hasDestination) return { status: 'pass' };
+    if (!hasDestination) {
+      return {
+        status: 'fail',
+        message: `The page reloads itself${delay > 0 ? ` every ${delay}s` : ' immediately, over and over'} (failure F41). The reader cannot postpone or suppress the reload, which 2.2.4 requires, and it changes the page without being asked, which 3.2.5 forbids. Neither AAA criterion has 2.2.1's 20-hour allowance.`,
+        fix: 'Remove the timed refresh and update the content in place, or let the reader request an update with a control.',
+      };
+    }
+    return {
+      status: 'fail',
+      message: `The page redirects itself after ${delay}s (failure F40). The reader cannot postpone or suppress the move, which 2.2.4 requires, and the change of context is not requested, which 3.2.5 forbids; the AAA criteria allow no 20-hour exemption. 2.2.4 excuses only an emergency, which the tag cannot show, so this finding assumes there is none.`,
+      fix: 'Redirect instantly (content="0; url=…") or on the server, or give the reader a link and let them choose when to move.',
+    };
+  },
+};

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

@@ -80,8 +80,8 @@ export default {
     const linkCount = roots.reduce((n, root) => n + (root.querySelectorAll?.('a[href], button').length ?? 0), 0);
     if (linkCount < 4) return { status: 'pass' };
     return {
-      status: 'fail',
-      message: `This page has ${linkCount} links and buttons but no landmark, heading, skip link, or titled frame — keyboard and screen-reader users must go through the whole header and nav to reach anything.`,
+      status: 'incomplete',
+      message: `This page has ${linkCount} links and buttons but no detected landmark, heading, skip link or titled frame. Check whether it contains blocks repeated on other pages and, if so, whether a mechanism lets users bypass them. A single page cannot establish repetition.`,
       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.10-section-heading.js

@@ -0,0 +1,86 @@
+// WCAG SC 2.4.10 Section Headings (Level AAA)
+// "Section headings are used to organize the content." The Understanding
+// defines a section as a self-contained portion of written content, says
+// the criterion covers sections within writing rather than UI components,
+// and gives H69 (a heading element at the beginning of each section) as
+// the technique. Where a page's sections begin is a judgement about the
+// writing, except in one case the author has made for us: an HTML
+// <section> element is a declared section. A declared section that holds
+// running text and starts with no heading is the honest candidate; whether
+// it is really a section of writing or a layout wrapper stays the
+// reader's call, so this asks and never asserts.
+//
+// A section has its heading when one of its own sits anywhere inside it
+// (a nested section's or article's heading is that element's), when it
+// BEGINS with one however the markup nests it (inside a header, a div or a
+// nested article), or when the element immediately before it is that
+// heading or ends with it: the blog pattern of an article's title followed by a
+// section holding the post body (measured on the corpus: 292 such bodies
+// on one feed page, none of them a missing heading). A section named by
+// aria-labelledby or aria-label has a title by another route and is left
+// alone. Sections with little text, or none, are the UI-component case the
+// criterion excludes.
+const HEADING = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
+const SUBSTANTIVE = 'img, svg, video, audio, canvas, iframe, input, select, textarea, button';
+const SKIP = 'script, style, template, noscript';
+
+/** The first (or, reversed, the last) substantive thing inside an element,
+ *  in document order: a heading, or text or media that is not one. */
+function edgeIsHeading(element, fromEnd) {
+  const children = (node) => (fromEnd ? [...node.childNodes].reverse() : [...node.childNodes]);
+  const stack = children(element).reverse();
+  while (stack.length) {
+    const node = stack.pop();
+    if (node.nodeType === 3) { if (node.textContent.trim()) return false; continue; }
+    if (node.nodeType !== 1) continue;
+    if (node.matches(HEADING)) return true;
+    if (node.matches(SKIP)) continue;
+    if (node.matches(SUBSTANTIVE)) return false;
+    for (const child of children(node).reverse()) stack.push(child);
+  }
+  return false;
+}
+
+export default {
+  id: 'section-heading',
+  name: 'Section headings',
+  impact: 'moderate',
+  tags: ['wcag2aaa', 'wcag2410'],
+  help: 'Sections of written content should begin with a heading (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/section-headings.html',
+  selector: 'section',
+  evaluate(element) {
+    if (element.hasAttribute('aria-label') || element.hasAttribute('aria-labelledby')) return { status: 'pass' };
+    const role = element.getAttribute('role');
+    if (role && role !== 'region') return { status: 'pass' };
+    // Any heading of the section's own (not a nested section's or article's)
+    // organises it, wherever it sits; a section that BEGINS with a heading,
+    // however nested, is headed too.
+    const ownHeading = [...element.querySelectorAll(HEADING)]
+      .some((heading) => heading.closest('section, article') === element);
+    if (ownHeading || edgeIsHeading(element, false)) return { status: 'pass' };
+    const before = element.previousElementSibling;
+    if (before && (before.matches(HEADING) || (before.matches('header, hgroup') && before.querySelector(HEADING)) || edgeIsHeading(before, true))) {
+      return { status: 'pass' };
+    }
+    // A feed of untitled notes: the section is the body of an article with
+    // no heading of its own, in a run of at least three such items. Whether
+    // the notes of a feed need headings is one question about the feed, for
+    // the reviewer to ask once; asking it per item put 292 findings on one
+    // corpus page and helped nobody.
+    const item = element.closest('article');
+    if (item && item.parentElement && !item.querySelector(HEADING)) {
+      const items = (node) => [...node.children].filter((child) => child.matches('article') || child.querySelector(':scope > article')).length;
+      const container = item.parentElement;
+      if (items(container) >= 3 || (container.parentElement && items(container.parentElement) >= 3)) return { status: 'pass' };
+    }
+    const text = (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+    const paragraphs = element.querySelectorAll('p').length;
+    if (text.length < 200 && paragraphs < 2) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: 'This section holds written content but begins with no heading of its own, so readers scanning by headings cannot find or skip it. 2.4.10 asks for a heading at the start of each section of writing; check whether this is a section of content that needs one, or a purely structural wrapper.',
+      fix: 'Start the section with a heading that names its topic, at the level below its parent heading, or name it with aria-labelledby pointing at its visible title.',
+    };
+  },
+};

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

@@ -2,7 +2,8 @@
 // An opaque fixed/sticky overlay covering a focusable element is the
 // criterion's core case (bottom cookie bars over footer links). Partial
 // overlap passes by definition ("not entirely hidden"), so only full
-// containment counts.
+// containment counts. The AAA sibling built from the same factory (2.4.12,
+// "no part of the component is hidden") counts any overlap at all.
 //
 // This REVIEWS rather than fails, deliberately. What a snapshot can see is
 // "element X is under the panel right now", and that is a fact about the
@@ -31,85 +32,140 @@ function edgeReserved(doc, edge, needed) {
   return px >= needed - 1;
 }
 
-export default {
+/**
+ * Build the minimum (full containment) or enhanced (any overlap) rule.
+ * `partial: false` is 2.4.11 exactly as it has always run: one hit-test at
+ * the element's centre, and a blocker only counts when its box contains the
+ * whole element. `partial: true` is 2.4.12: the centre plus the four corners
+ * and four edge midpoints are hit-tested, and a blocker counts when it paints
+ * above the element at any of them and overlaps its box at all.
+ */
+export function createFocusObscuredRule({ id, name, tags, help, helpUrl, partial }) {
+  return {
+    id,
+    name,
+    impact: 'serious',
+    tags,
+    help,
+    helpUrl,
+    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 the
+      // criterion. 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 contained = (rect, overlay) =>
+        rect.left >= overlay.left && rect.right <= overlay.right
+        && rect.top >= overlay.top && rect.bottom <= overlay.bottom;
+      const overlaps = (rect, overlay) =>
+        Math.min(rect.right, overlay.right) - Math.max(rect.left, overlay.left) > 0
+        && Math.min(rect.bottom, overlay.bottom) - Math.max(rect.top, overlay.top) > 0;
+      const clampX = (x) => Math.min(Math.max(x, 0), win.innerWidth - 1);
+      const clampY = (y) => Math.min(Math.max(y, 0), win.innerHeight - 1);
+      // The layer painting above the element at one point, if it is an
+      // obscuring overlay whose box relates to the element's as the mode
+      // demands. elementsFromPoint lists the whole stack, covered elements
+      // included, so an element ABSENT from it does not paint at that point
+      // at all (a rounded corner, a clip-path): nothing is hidden there.
+      // Measured on the corpus: consent-dialog buttons with rounded corners
+      // over their own opaque backdrop were flagged from exactly that.
+      const blockerAt = (element, rect, x, y) => {
+        const stack = doc.elementsFromPoint(clampX(x), clampY(y));
+        const index = stack.indexOf(element);
+        if (index <= 0) return null;
+        const above = stack.slice(0, index);
+        return above.find((layer) =>
+          !layer.contains(element) && !element.contains(layer)
+          && isObscuringOverlay(layer)
+          && (partial ? overlaps : contained)(rect, layer.getBoundingClientRect())) ?? null;
+      };
+
+      return elements.map((element) => {
+        // `: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).
+        if (rect.bottom < 0 || rect.right < 0 || rect.top > win.innerHeight || rect.left > win.innerWidth) {
+          return { status: 'pass' };
+        }
+        const cx = rect.left + rect.width / 2;
+        const cy = rect.top + rect.height / 2;
+        let blocker = blockerAt(element, rect, cx, cy);
+        if (!blocker && partial) {
+          // A strip of cookie bar over the bottom of a link leaves its
+          // centre clear; the corners and edge midpoints see it.
+          const inset = 1;
+          const xs = [rect.left + inset, cx, rect.right - inset];
+          const ys = [rect.top + inset, cy, rect.bottom - inset];
+          for (const x of xs) {
+            for (const y of ys) {
+              if (x === cx && y === cy) continue;
+              blocker = blockerAt(element, rect, x, y);
+              if (blocker) break;
+            }
+            if (blocker) break;
+          }
+        }
+        if (!blocker) return { status: 'pass' };
+        // Which viewport edge is the panel pinned to? That is the edge the
+        // browser's scroll-into-view has to clear.
+        const panel = blocker.getBoundingClientRect();
+        const edge = panel.top <= 1 && panel.bottom < win.innerHeight ? 'top'
+          : panel.bottom >= win.innerHeight - 1 ? 'bottom' : null;
+        if (edge && edgeReserved(doc, edge, panel.height)) return { status: 'pass' };
+        return partial ? {
+          status: 'incomplete',
+          message: 'Part of this element is currently underneath an opaque fixed panel. 2.4.12 (AAA) allows no part of a focused component to be hidden by author content, and whether that happens depends on where the page sits when focus reaches it — the browser does not scroll an element that is already in the viewport, merely overlapped, so focus can land half-hidden. Tab through the page and check the whole element, indicator included, stays clear of the panel.',
+          fix: `Reserve room for the panel with scroll-padding-${edge ?? 'bottom'} on the scrolling container, or move focus clear of it when the panel is up.`,
+        } : {
+          status: 'incomplete',
+          message: 'This element is currently underneath an opaque fixed panel. Whether that breaks 2.4.11 depends on where the page sits when focus reaches it — the browser does not scroll an element that is already in the viewport, merely covered, so focus can land invisibly. Tab through the page and check the focus indicator is never entirely hidden.',
+          fix: `Reserve room for the panel with scroll-padding-${edge ?? 'bottom'} on the scrolling container, or move focus clear of it when the panel is up.`,
+        };
+      });
+    },
+  };
+}
+
+export default createFocusObscuredRule({
   id: 'focus-not-obscured',
   name: 'Unobscured focus',
-  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) => {
-      // `: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).
-      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' };
-      // Which viewport edge is the panel pinned to? That is the edge the
-      // browser's scroll-into-view has to clear.
-      const panel = blocker.getBoundingClientRect();
-      const edge = panel.top <= 1 && panel.bottom < win.innerHeight ? 'top'
-        : panel.bottom >= win.innerHeight - 1 ? 'bottom' : null;
-      if (edge && edgeReserved(doc, edge, panel.height)) return { status: 'pass' };
-      return {
-        status: 'incomplete',
-        message: 'This element is currently underneath an opaque fixed panel. Whether that breaks 2.4.11 depends on where the page sits when focus reaches it — the browser does not scroll an element that is already in the viewport, merely covered, so focus can land invisibly. Tab through the page and check the focus indicator is never entirely hidden.',
-        fix: `Reserve room for the panel with scroll-padding-${edge ?? 'bottom'} on the scrolling container, or move focus clear of it when the panel is up.`,
-      };
-    });
-  },
-};
+  partial: false,
+});