pour-engine 1.3.1 → 1.5.0

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -62,12 +62,12 @@ meaning that only a person can settle, even where a rule decides most real pages
 | 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 | Manual review | — |
-| 2.4.4 | [Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) | A | Partially automated | area-alt, link-name |
+| 2.4.4 | [Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html) | A | Partially automated | area-alt, link-name, link-text-generic |
 | 2.4.5 | [Multiple Ways](https://www.w3.org/WAI/WCAG22/Understanding/multiple-ways.html) | AA | Manual review | — |
 | 2.4.6 | [Headings and Labels](https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html) | AA | Manual review | — |
 | 2.4.7 | [Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) | AA | Partially automated | focus-visible |
 | 2.4.8 | [Location](https://www.w3.org/WAI/WCAG22/Understanding/location.html) | AAA | Manual review | — |
-| 2.4.9 | [Link Purpose (Link Only)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html) | AAA | Manual review | — |
+| 2.4.9 | [Link Purpose (Link Only)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html) | AAA | Partially automated | link-text-generic-only |
 | 2.4.10 | [Section Headings](https://www.w3.org/WAI/WCAG22/Understanding/section-headings.html) | AAA | Manual review | — |
 | 2.4.11 | [Focus Not Obscured (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html) | AA | Partially automated | focus-not-obscured |
 | 2.4.12 | [Focus Not Obscured (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html) | AAA | Manual review | — |
@@ -114,4 +114,4 @@ meaning that only a person can settle, even where a rule decides most real pages
 | 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-valid-refs, button-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
-**Totals:** 29 partially automated · 57 manual — with 72 rules.
+**Totals:** 30 partially automated · 56 manual — with 74 rules.

package/engine/README.md

@@ -102,14 +102,15 @@ pour engine therefore reports on **every** in-scope criterion, one of two ways:
 1. **Automated/partial** — the rules in `rules/`.
 2. **Manual review** — every audit's results include `manualReview`: the
    in-scope criteria (filtered by the requested WCAG version and level)
-   that automation can't judge, rendered as a checklist in the extension.
+   that automation can't judge, for a host to render however it wants.
 
 Nothing in the spec is silently skipped — that claim is the product.
 
 ## Honest current state
 
-72 rules, hardened on real sites and the `testbeds/` pages. Known gaps:
-shadow DOM and iframe traversal, the full accname spec (ours is a close
-approximation), and the language subtag registry (BCP 47 shape check only).
-Grow it rule by rule; the test beds' `expect:` annotations are the
-regression suite.
+72 rules, hardened on real sites and the `testbeds/` pages. Audits walk into
+open shadow roots (targets come back as `host >>> inner` selector chains);
+iframe traversal is the host's job, and the extension does it. Known gaps:
+the full accname spec (ours is a close approximation) and the language
+subtag registry (BCP 47 shape check only). Grow it rule by rule; the test
+beds' `expect:` annotations and the spec cases are the regression suite.

package/engine/index.js

@@ -1,4 +1,4 @@
-// DY Engine runner: evaluates every applicable rule against the page and
+// Engine runner: evaluates every applicable rule against the page and
 // returns structured results (violations / passes / incomplete /
 // inapplicable, plus the manual-review criteria and per-rule timings).
 import config from '../config/project.config.js';

package/engine/lib/contrast.js

@@ -835,6 +835,11 @@ export function imageLuminanceRange(url, overlays = []) {
         const data = ctx.getImageData(0, 0, size, size).data;
         let min = 1;
         let max = 0;
+        // The colours at those extremes, kept for the same reason the
+        // gradient range keeps them: translucent text blends with the actual
+        // pixels, and a luminance cannot be un-gamma'd back into an rgb.
+        let minColor = null;
+        let maxColor = null;
         let opaquePixels = 0;
         for (let i = 0; i < data.length; i += 4) {
           if (data[i + 3] < 128) continue; // mostly-transparent pixels reveal what's beneath — unknowable
@@ -843,9 +848,10 @@ export function imageLuminanceRange(url, overlays = []) {
           // and the text before measuring: a photo under a 75% black scrim is
           // seen as the blend, never as the photo.
           const pixel = { r: data[i], g: data[i + 1], b: data[i + 2], a: 1 };
-          const l = luminance(overlays.length ? applyOverlays(pixel, overlays) : pixel);
-          if (l < min) min = l;
-          if (l > max) max = l;
+          const shown = overlays.length ? applyOverlays(pixel, overlays) : pixel;
+          const l = luminance(shown);
+          if (l < min) { min = l; minColor = shown; }
+          if (l > max) { max = l; maxColor = shown; }
         }
         // Not one opaque pixel: a spacer, a cleared sprite, or a decorative
         // layer left in place with nothing in it. It covers the background
@@ -862,7 +868,9 @@ export function imageLuminanceRange(url, overlays = []) {
           resolve({ transparent: true, width: img.naturalWidth, height: img.naturalHeight });
           return;
         }
-        resolve(min <= max ? { min, max, width: img.naturalWidth, height: img.naturalHeight } : null);
+        resolve(min <= max
+          ? { min, max, minColor, maxColor, width: img.naturalWidth, height: img.naturalHeight }
+          : null);
       } catch {
         resolve(null); // tainted canvas: cross-origin image without CORS headers
       }
@@ -921,8 +929,20 @@ export function backgroundImagePaintRect(element, intrinsic) {
 export function gradientLuminanceRange(backgroundImageCss, overlays = []) {
   const stops = (backgroundImageCss.match(/rgba?\([^)]+\)/g) ?? []).map(parseColor).filter(Boolean);
   if (!stops.length || stops.some((c) => c.a < 1)) return null; // translucent stops reveal what's beneath
-  const lums = stops.map((stop) => luminance(overlays.length ? applyOverlays(stop, overlays) : stop));
-  return { min: Math.min(...lums), max: Math.max(...lums) };
+  const composited = stops.map((stop) => (overlays.length ? applyOverlays(stop, overlays) : stop));
+  const lums = composited.map(luminance);
+  const min = Math.min(...lums);
+  const max = Math.max(...lums);
+  // The COLOURS at the extremes, not just their luminances: translucent text
+  // takes its presented colour from the pixels beneath, so bracketing that
+  // blend needs the actual rgb to composite against, and luminance alone
+  // cannot be un-gamma'd back into one.
+  return {
+    min,
+    max,
+    minColor: composited[lums.indexOf(min)],
+    maxColor: composited[lums.indexOf(max)],
+  };
 }
 
 /** Contrast ratio from two luminances. */

package/engine/rules/index.js

@@ -15,6 +15,8 @@ import imageAlt from './wcag/1.1.1-image-alt.js';
 import svgImgAlt from './wcag/1.1.1-svg-img-alt.js';
 import buttonName from './wcag/4.1.2-button-name.js';
 import linkName from './wcag/2.4.4-link-name.js';
+import linkTextGeneric from './wcag/2.4.4-link-text-generic.js';
+import linkTextGenericOnly from './wcag/2.4.9-link-text-generic-only.js';
 // Re-parked by product decision (2026-08-01, David, after a one-day
 // un-parking): 2.5.3 is normative Level A but chiefly serves speech-input
 // users, and the findings volume isn't wanted in results for now. The SC is
@@ -113,6 +115,8 @@ export default [
   svgImgAlt,
   buttonName,
   linkName,
+  linkTextGeneric,
+  linkTextGenericOnly,
   // labelInName, — re-parked 2026-08-01, see note at the import
   formLabel,
   autocompleteValid,

package/engine/rules/wcag/1.4.1-link-in-text-block.js

@@ -79,9 +79,14 @@ export default {
     }
     return {
       status: 'fail',
+      // The measured fact is the ratio against G183's threshold, and that is
+      // all this says. Naming a group who "can't see it" overclaims: a
+      // saturated red against near-white misses 3:1 on luminance while
+      // staying perfectly distinct to most people, including most red-green
+      // colour blindness, where the red darkens and the gap widens.
       message: ratio < 1.01
-        ? 'This link has no underline and the same colour as the surrounding text — sighted users can’t tell it’s a link.'
-        : `This link has no underline and only ${ratio.toFixed(2)}:1 colour difference from the surrounding text — colour-blind users can’t spot it.`,
+        ? 'This link has no underline and the same colour as the surrounding text, so there is nothing at all to mark it as a link.'
+        : `This link has no underline and only ${ratio.toFixed(2)}:1 colour difference from the surrounding text, below the 3:1 WCAG technique G183 asks for when colour is the only thing marking a link.`,
       fix: 'Underline links inside text (text-decoration: underline), or add a non-colour indicator.',
     };
   },

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

@@ -78,9 +78,26 @@ async function imageVsText(imageSource, element, doc) {
   // paint rect must not use it (icon SVGs would "cover" all the text).
   const dimensionless = !intrinsic || !intrinsic.width
     || (intrinsic.width === 300 && intrinsic.height === 150);
+  // A gradient has no intrinsic size and never will, but that is not the
+  // same as an unknown paint area: with the default background-size it fills
+  // its carrier's painting box exactly. Lumping it in with "we cannot tell
+  // how big this is" meant a gradient could never earn a definite verdict,
+  // however large the panel it covers. Its scale is the carrier's, unless
+  // background-size names something small, which is the one way a gradient
+  // really is icon-scale (a tiny repeated swatch).
+  const isGradient = !url && imageSource.css.includes('gradient(');
+  let sizedSmall = false;
+  if (isGradient) {
+    const size = getComputedStyle(imageSource.element).backgroundSize ?? '';
+    const px = [...size.matchAll(/(\d+(?:\.\d+)?)px/g)].map((m) => parseFloat(m[1]));
+    sizedSmall = px.length > 0 && px.every((value) => value <= 40);
+  }
   const paint = backgroundImagePaintRect(imageSource.element, dimensionless ? null : intrinsic);
-  if (!paint) return { relation: 'unknown', intrinsic, dimensionless };
-  return { relation: textIntersects(element, paint) ? 'under' : 'clear', intrinsic, dimensionless };
+  if (!paint) return { relation: 'unknown', intrinsic, dimensionless, isGradient, sizedSmall };
+  return {
+    relation: textIntersects(element, paint) ? 'under' : 'clear',
+    intrinsic, dimensionless, isGradient, sizedSmall,
+  };
 }
 
 /**
@@ -188,10 +205,31 @@ async function sampledVerdict(source, foreground, required, doc, overlays = [])
   // when the layer paints nothing.
   if (range?.transparent) return PAINTS_NOTHING;
   // Translucent text takes its presented colour from the very pixels
-  // beneath it — a luminance range of the backdrop cannot bracket the
-  // blend (dimmed white over a dark photo reads mid-grey, not white).
-  // Asserting either way from sampling would be a coin toss.
+  // beneath it, so a luminance range of the backdrop cannot be read straight
+  // off: dimmed white over a dark photo reads mid-grey, not white.
+  //
+  // It CAN still be bracketed, by compositing the text over each end of the
+  // backdrop's range and judging each blend against the backdrop it was
+  // blended with. That bracket is sound in one direction only. Ratio is not
+  // monotonic in backdrop luminance — as the composited text passes through
+  // the backdrop's own luminance the ratio collapses toward 1:1 — so an
+  // interior point can be WORSE than both ends but never better. Both ends
+  // failing therefore proves the whole range fails; both ends passing proves
+  // nothing about the middle, and stays a human call.
   if (foreground.a < 1) {
+    const ends = [range?.minColor, range?.maxColor].filter(Boolean);
+    if (ends.length === 2) {
+      const ratios = ends.map((backdrop) => contrastRatio(composite(foreground, backdrop), backdrop));
+      if (ratios.every((ratio) => ratio < required)) {
+        const best = Math.max(...ratios);
+        return {
+          status: 'fail',
+          message: `This text is translucent, so it blends with what is behind it: against every part of that backdrop the blend reaches at best ${showRatio(best)}:1, below the ${required}:1 minimum.`,
+          fix: 'Raise the text opacity, change its colour, or put a solid layer between the text and the backdrop.',
+          data: { ratio: Number(showRatio(best)), required },
+        };
+      }
+    }
     return {
       status: 'incomplete',
       message: 'This text is translucent over an image or gradient, so its presented colour depends on the pixels beneath — contrast must be checked by eye.',
@@ -297,7 +335,7 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // images (external-link arrows etc.) don't affect the text's contrast.
     const imageSource = backgroundImageSource(element);
     if (imageSource) {
-      const { relation, intrinsic, dimensionless } = await imageVsText(imageSource, element, doc);
+      const { relation, intrinsic, dimensionless, isGradient, sizedSmall } = await imageVsText(imageSource, element, doc);
       if (relation !== 'clear') {
         // imageSource.overlays are the translucent layers painted between the
         // image and this text (hero scrims, tint panels). Judging the raw
@@ -325,8 +363,10 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
           // inline link is still an icon). Only backdrop-scale images earn a
           // definite fail from sampling.
           const carrierBox = imageSource.element.getBoundingClientRect();
-          if (sampled?.status === 'fail'
-            && (dimensionless || (intrinsic.width <= 32 && intrinsic.height <= 32) || carrierBox.height <= 40)) {
+          const iconScale = isGradient
+            ? (sizedSmall || carrierBox.height <= 40)
+            : (dimensionless || (intrinsic.width <= 32 && intrinsic.height <= 32) || carrierBox.height <= 40);
+          if (sampled?.status === 'fail' && iconScale) {
             return {
               status: 'incomplete',
               message: 'A small background icon is painted on this element — if it sits beside the text rather than under it, judge the contrast against the plain background by eye.',

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

@@ -39,10 +39,26 @@ export default {
     // including content slotted in from the light DOM and content inside
     // open shadow roots (carousels built as web components).
     if (hasFocusableContent(element)) return { status: 'pass' };
+    // NOT a failure, because the browser may already have solved it.
+    //
+    // Chromium puts a scroll container in the tab order by itself when the
+    // container holds nothing focusable — and that condition is exactly the
+    // one this rule fires on, so in Chrome every element reaching this line
+    // IS keyboard reachable. Measured, not assumed: Chrome 151 tabs
+    // before → the scroller → after, while `element.tabIndex` still reports
+    // -1, which is why the check above cannot see it.
+    //
+    // It is not settled across engines though. MDN still advises the
+    // tabindex ("in some browsers, scrolling content areas are not
+    // keyboard-focusable"), and WebKit did not take focus here. So the
+    // honest report is the fact plus the split, not a verdict: asserting a
+    // Level A failure would be wrong for anyone on Chrome, and asserting a
+    // pass would be wrong for anyone who has to support the browsers that
+    // don't.
     return {
-      status: 'fail',
-      message: 'This region scrolls, but contains nothing focusable and isn’t focusable itself — keyboard users can never see the overflowed content.',
-      fix: 'Add tabindex="0" to the scrollable element (plus role="region" and an aria-label describing it).',
+      status: 'incomplete',
+      message: 'This region scrolls and holds nothing focusable, so reaching its overflowed content depends on the browser. Chromium gives such containers keyboard focus automatically; not every engine does. Tab to it in the browsers you support, and add tabindex="0" if it cannot be reached.',
+      fix: 'If you support browsers that do not focus scroll containers, add tabindex="0" (plus role="region" and an aria-label describing it).',
     };
   },
 };

package/engine/rules/wcag/2.4.4-link-text-generic.js

@@ -0,0 +1,80 @@
+// WCAG SC 2.4.4 Link Purpose (In Context) (Level A)
+//     · SC 2.4.9 Link Purpose (Link Only) (Level AAA)
+//
+// A link named "Read more" carries no purpose in its name. Screen reader
+// users routinely pull up a list of every link on a page and navigate from
+// it, and nine identical "Read more" entries in that list are worthless —
+// the technique WCAG names for this is F63, and G91 is the fix.
+//
+// The two criteria differ in exactly one way, and it decides the verdict:
+//
+//   2.4.4 (A)   purpose may come from CONTEXT — the sentence around the
+//               link, its list item, its table cell, the heading of the card
+//               it sits in. A "Read more" under a headline naming the
+//               article is a judgment call about whether that context really
+//               reaches the user, so this REVIEWS. It never asserts.
+//   2.4.9 (AAA) purpose must come from the link text ALONE, with the only
+//               exception being links whose purpose "would be ambiguous to
+//               users in general". A link named nothing but "Read more" is
+//               ambiguous to everyone, which is the exception failing to
+//               apply rather than saving it, so this FAILS.
+//
+// Judged on the ACCESSIBLE NAME, not the text content: a link written as
+// <a href="…" aria-label="Read more about the budget">Read more</a> is
+// already fixed, and must not be flagged. That also means an aria-label
+// which is itself generic is caught, which is the more common mistake.
+//
+// English only, deliberately. A phrase list cannot be quietly extended to
+// other languages without a speaker of each checking it, and a wrong entry
+// would fail correct links. Non-English pages get no findings here rather
+// than bad ones.
+
+const GENERIC = new Set([
+  'read more', 'read more about this', 'more', 'much more', 'learn more',
+  'click here', 'click', 'click this', 'tap here', 'press here',
+  'here', 'this', 'this link', 'link', 'this page', 'go', 'go here',
+  'more info', 'more information', 'further information',
+  'see more', 'view more', 'show more', 'find out more', 'discover more',
+  'continue', 'continue reading', 'keep reading', 'full story', 'full article',
+  'details', 'see details', 'view details', 'more details',
+]);
+
+/** Lowercased, punctuation and arrows dropped, spaces collapsed, so
+ *  "Read more →", "Click here!" and "READ  MORE" all compare equal. */
+export function normalizeName(name) {
+  return name.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').replace(/\s+/g, ' ').trim();
+}
+
+export function createLinkPurposeRule({ id, impact, tags, help, helpUrl, verdict }) {
+  return {
+    id,
+    impact,
+    tags,
+    help,
+    helpUrl,
+    // role="link" claims the link role explicitly; an <a> without href has no
+    // link role at all and is correctly out of scope. Links with NO name are
+    // link-name's finding, not this one.
+    selector: 'a[href], [role="link"]',
+    evaluate(element, { accessibleName }) {
+      const name = accessibleName(element);
+      if (!name) return { status: 'pass' }; // nameless: link-name reports it
+      const normalized = normalizeName(name);
+      if (!GENERIC.has(normalized)) return { status: 'pass' };
+      return verdict(name);
+    },
+  };
+}
+
+export default createLinkPurposeRule({
+  id: 'link-text-generic',
+  impact: 'moderate',
+  tags: ['wcag2a', 'wcag244'],
+  help: 'Link text should describe where the link goes',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html',
+  verdict: (name) => ({
+    status: 'incomplete',
+    message: `“${name}” does not say where this link goes. 2.4.4 lets the surrounding text supply that, so this passes only if the context a screen reader reaches — the same sentence, list item, table cell, or the heading of the card it sits in — makes the destination obvious. Check it does, and remember that anyone navigating by a list of the page's links sees this name on its own.`,
+    fix: 'Put the destination in the link text itself, e.g. "Read more about the 2026 budget", or extend the name with aria-label while keeping the visible words at the start of it.',
+  }),
+});

package/engine/rules/wcag/2.4.9-link-text-generic-only.js

@@ -0,0 +1,26 @@
+// WCAG SC 2.4.9 Link Purpose (Link Only) (Level AAA)
+//
+// Same phrase list and same name computation as 2.4.4's rule, at the AAA
+// threshold: the link text ALONE has to identify the purpose, and context
+// is not allowed to make up the difference.
+//
+// This one asserts where the AA rule reviews. The criterion's only escape is
+// links "where the purpose of the link would be ambiguous to users in
+// general", and a link named nothing but "Read more" is ambiguous to
+// everyone — which is the exception failing to apply rather than rescuing
+// it. Nothing about the surrounding page can change that reading, so there
+// is nothing here for a human to settle.
+import { createLinkPurposeRule } from './2.4.4-link-text-generic.js';
+
+export default createLinkPurposeRule({
+  id: 'link-text-generic-only',
+  impact: 'moderate',
+  tags: ['wcag2aaa', 'wcag249'],
+  help: 'Link text alone must identify where the link goes (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-link-only.html',
+  verdict: (name) => ({
+    status: 'fail',
+    message: `“${name}” gives no purpose on its own. 2.4.9 asks that the link text alone identify where a link goes, without relying on the sentence or heading around it, so anyone reading the page's links as a list can tell them apart.`,
+    fix: 'Name the destination in the link text, e.g. "Read more about the 2026 budget".',
+  }),
+});

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

@@ -38,6 +38,68 @@ function isHiddenFromPointer(element, rect) {
   return false;
 }
 
+/**
+ * Is this element the thing a click at that point would actually reach, or
+ * is something painted over it there?
+ *
+ * The spacing exception is about targets COMPETING for pointer space, and
+ * two targets that can never be hit at the same place do not compete. On any
+ * page with a fixed header, scrolling slides ordinary content underneath it:
+ * a footer link can end up geometrically 3px from a header button while
+ * being completely unclickable there, and counting it as a crowder invents a
+ * failure out of the scroll position. That was reported on pour's own site.
+ *
+ * Only asked about targets that are ALREADY crowding an undersized one, so
+ * the hit-test cost is paid on the handful of candidate failures rather than
+ * on every target of the page.
+ *
+ * Out-of-viewport points can't be hit-tested at all: elementsFromPoint is
+ * viewport-relative and returns nothing outside it. There the honest answer
+ * is "don't know", and don't-know must not silence a finding, so it counts
+ * as reachable.
+ */
+function reachableRects(element, rect) {
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  if (!win || typeof doc.elementsFromPoint !== 'function') return [rect];
+  // Per LINE FRAGMENT, never the bounding box. An inline link that wraps has
+  // one fragment per line, and the box enclosing them is mostly space the
+  // element never paints: its middle falls in the leading BETWEEN the lines,
+  // where elementsFromPoint does not contain the element at all. A
+  // box-centre probe therefore reads "not hit-testable" for every wrapped
+  // link. (Same geometry trap as link-in-text-block's own-line test.)
+  //
+  // Fragments also make the answer usefully partial. A footer link scrolled
+  // half under a fixed header has its first line buried and its second line
+  // perfectly clickable, so the honest result is not "reachable" or
+  // "covered" but WHICH PART is reachable — and only that part can compete
+  // for pointer space with anything nearby.
+  const fragments = [...element.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+  const probes = fragments.length ? fragments : [rect];
+  const reachable = [];
+  let testable = false;
+  for (const fragment of probes) {
+    const x = fragment.left + fragment.width / 2;
+    const y = fragment.top + fragment.height / 2;
+    if (x < 0 || y < 0 || x >= win.innerWidth || y >= win.innerHeight) continue;
+    const stack = doc.elementsFromPoint(x, y);
+    const index = stack.indexOf(element);
+    if (index < 0) continue; // this fragment isn't hit-testable; try the next
+    testable = true;
+    // Anything above it that is part of the same control is not an
+    // obstruction: a button's own icon paints over the button, an overlay
+    // label over its input. Only a genuinely separate element blocks it.
+    if (stack.slice(0, index).every((layer) => layer.contains(element) || element.contains(layer))) {
+      reachable.push(fragment);
+    }
+  }
+  // Nothing could be probed at all (entirely out of viewport,
+  // pointer-events: none, nothing laid out): don't know, and don't-know must
+  // not silence a finding, so the whole rect stands.
+  if (!testable) return [rect];
+  return reachable;
+}
+
 /** Text this element contributes that is NOT inside a target — i.e. does it
  *  read as prose beside the link, or is it just another control in a list? */
 function textOutsideTargets(element) {
@@ -146,14 +208,37 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
         // 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) => {
+        const crowds = (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;
-        });
+          const within = (box) => {
+            if (undersized[j]) {
+              const c = { x: box.left + box.width / 2, y: box.top + box.height / 2 };
+              if (Math.hypot(c.x - centers[i].x, c.y - centers[i].y) < min) return true;
+            }
+            return pointToRectDistance(centers[i], box) < min / 2;
+          };
+          // Whole-rect test first, as a cheap superset: no part of a target
+          // can be closer than the box enclosing it, so a box that doesn't
+          // reach rules the target out without any hit-testing. Only the
+          // survivors pay for the paint-order queries, which on a page of
+          // hundreds of targets is a handful.
+          if (!within(rects[j])) return false;
+          // Then the honest test: only the parts a pointer can actually
+          // reach compete for pointer space. A link whose first line is
+          // buried under a fixed header and whose second line is clear is
+          // crowding from its second line or not at all.
+          return reachableRects(other, rects[j]).some(within);
+        };
+        const crowded = elements.some(crowds);
         if (!crowded) return { status: 'pass' };
+        // Deliberately NOT applied to the target itself. A crowder that
+        // can't be clicked breaks the premise of the exception, because it
+        // isn't competing for anything. A target that happens to be under a
+        // cookie banner right now is still 20×20 the moment that banner is
+        // dismissed, and suppressing it would hide a real defect behind a
+        // transient overlay, which is the wrong way round.
       }
       const rect = rects[i];
       return {

package/engine/wcag22.js

@@ -75,7 +75,7 @@ export default [
   sc('2.4.6', 'Headings and Labels', 'AA', 'manual'),
   sc('2.4.7', 'Focus Visible', 'AA', 'partial'), // partial: focus-visible flags outline suppression; the indicator itself needs eyes
   sc('2.4.8', 'Location', 'AAA', 'manual'),
-  sc('2.4.9', 'Link Purpose (Link Only)', 'AAA', 'manual'),
+  sc('2.4.9', 'Link Purpose (Link Only)', 'AAA', 'partial'), // partial: contentless link names are provable; whether a real name describes its destination needs a reader
   sc('2.4.10', 'Section Headings', 'AAA', 'manual'),
   sc('2.4.11', 'Focus Not Obscured (Minimum)', 'AA', 'partial', '2.2'), // partial: focus-not-obscured catches fully-covered targets at rest
   sc('2.4.12', 'Focus Not Obscured (Enhanced)', 'AAA', 'manual', '2.2'),

package/package.json

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