pour-engine 1.37.0 → 1.38.0

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -111,7 +111,7 @@ meaning that only a person can settle, even where a rule decides most real pages
 
 | SC | Name | Level | Coverage | Rules |
 |---|---|---|---|---|
-| 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-label-misuse, aria-valid-refs, button-name, composite-widget-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, summary-name, valid-role, invoker-target |
+| 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-label-misuse, aria-valid-refs, button-name, composite-widget-name, dialog-name, frame-title, invoker-target, label-for-valid, nested-interactive, role-required-aria, summary-name, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
 **Totals:** 39 partially automated · 47 manual — with 88 rules.

package/engine/README.md

@@ -112,7 +112,7 @@ Nothing in the spec is silently skipped — that claim is the product.
 
 ## Honest current state
 
-74 rules, hardened on real sites and the `testbeds/` pages. Audits walk into
+88 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

package/engine/lib/contrast.js

@@ -1040,7 +1040,7 @@ export function viewportVeil(doc) {
 /** Parse a computed text-shadow list into layers. Computed style serializes
  *  the colour first ("rgb(0, 0, 0) 1px 0px 2px") with px lengths; author-ish
  *  orderings are tolerated. */
-export function parseTextShadows(cssText) {
+function parseTextShadows(cssText) {
   if (!cssText || cssText === 'none') return [];
   const layers = [];
   for (const part of cssText.split(/,(?![^(]*\))/)) {
@@ -1116,7 +1116,7 @@ export function textShadowNegligible(cssText, fontSize) {
  * uncertain path keeps the FULL box, erring toward review, never past a
  * real overlap. Returns null when the clip leaves nothing paintable.
  */
-export function paintableRect(element, rect) {
+function paintableRect(element, rect) {
   let { left, top, right, bottom } = rect;
   let mode = getComputedStyle(element).position;
   for (let a = element.parentElement; a; a = a.parentElement) {
@@ -1333,7 +1333,7 @@ export function imageLuminanceRange(url, overlays = [], grid = null) {
  * cover/contain hands sizing to an intrinsic this function does not have, or
  * when its position is not a plain length or percentage.
  */
-export function backgroundImagePaintRects(element) {
+function backgroundImagePaintRects(element) {
   const style = getComputedStyle(element);
   const images = splitLayers(style.backgroundImage);
   if (!images.length) return [];
@@ -1492,29 +1492,6 @@ export function rangeWithBackdrop(range, under, overlays = []) {
   };
 }
 
-/**
- * Luminance range of a CSS gradient, from its colour stops. Interpolated
- * colours stay close enough to their stops' luminances to bracket.
- */
-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 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)],
-  };
-}
-
 /** The layers of a computed background-image list, split on top-level
  *  commas only: commas inside url() and gradient() belong to the layer. */
 export function splitBackgroundLayers(backgroundImageCss) {
@@ -1713,10 +1690,16 @@ export function pseudoTextColors(element, style) {
   return found;
 }
 
+/** The font weight from which text counts as bold for the large-scale
+ *  test. WCAG's glossary says "bold" and no number; CSS's bold keyword is
+ *  700, and the semibold 600 that most modern faces ship reads as bold at
+ *  14pt on screen, so it counts here too (David, 2026-09-02; was 700). */
+export const BOLD_WEIGHT = 600;
+
 /** WCAG "large text": ≥24px, or ≥18.66px (14pt) bold. */
 export function isLargeText(style) {
   const size = parseFloat(style.fontSize);
   const weight = parseInt(style.fontWeight, 10) || 400;
   // 18pt and 14pt at CSS's 96dpi: 24px, and 56/3 = 18.666…px exactly.
-  return size >= 24 || (size >= 56 / 3 && weight >= 700);
+  return size >= 24 || (size >= 56 / 3 && weight >= BOLD_WEIGHT);
 }

package/engine/lib/dom.js

@@ -1,5 +1,11 @@
 // DOM helpers shared by all rules.
 
+/** Elements that never reach the accessibility tree, so they cannot break
+ *  the structure of a list or a description list. STYLE belongs with them:
+ *  CSS-in-JS libraries inject <style> right beside the markup, and it was
+ *  being counted as a stray child that broke the list. */
+export const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+
 /**
  * The audit context plus every OPEN shadow root beneath it, hosts before
  * their shadow trees. Collected once per audit so each rule can query every

package/engine/lib/roles.js

@@ -24,6 +24,12 @@ export const GLOBAL_ARIA = new Set([
   'live', 'owns', 'relevant', 'roledescription', 'braillelabel', 'brailleroledescription',
 ]);
 
+/** The eight landmark roles (ARIA 1.2, Landmark Roles). Shared by the
+ *  landmark rules, the landmark lens and the screen reader's rotor. */
+export const LANDMARK_ROLES = new Set([
+  'banner', 'complementary', 'contentinfo', 'form', 'main', 'navigation', 'region', 'search',
+]);
+
 /** Attributes each role supports IN ADDITION to the globals.
  *
  *  Includes the four attributes ARIA 1.2 removed from the GLOBAL set

package/engine/rules/best-practice/landmark-top-level.js

@@ -3,11 +3,7 @@
 // page outline. Complementary joins via the aside demotion semantics in
 // lib/roles.js: only an aside that actually reaches the accessibility tree
 // as complementary owes top-levelness.
-import { implicitRole } from '../../lib/roles.js';
-
-const LANDMARK_ROLES = new Set([
-  'main', 'navigation', 'banner', 'contentinfo', 'complementary', 'region', 'search', 'form',
-]);
+import { implicitRole, LANDMARK_ROLES } from '../../lib/roles.js';
 
 /** HTML-AAM (form, section): "If a form has no accessible name, do not
  *  expose the element as a landmark", and a section is a region only with

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

@@ -1,18 +1,15 @@
 // ARIA APG landmark pattern: same-type landmarks need distinguishing
 // labels, and banner / contentinfo / main must be unique per page outright
 // (two "banners" are ambiguous however well they're labelled).
-import { implicitRole } from '../../lib/roles.js';
+import { implicitRole, LANDMARK_ROLES } from '../../lib/roles.js';
 import { labelledByName } from '../../lib/accessible-name.js';
 
 const SINGLETON = new Set(['banner', 'contentinfo', 'main']);
 
-// ARIA 1.2, Landmark Roles: the eight roles that are landmarks. An explicit
+// Only the eight ARIA landmark roles (lib/roles.js) count. An explicit
 // non-landmark role on a landmark element (<nav role="menubar">) makes it a
 // widget, not a landmark, so it has nothing to be distinguished from
 // (2026-08-25 overnight audit).
-const LANDMARK_ROLES = new Set([
-  'banner', 'complementary', 'contentinfo', 'form', 'main', 'navigation', 'region', 'search',
-]);
 
 /** Landmark role of the element in the accessibility tree — explicit role
  *  first, else the implicit role (which handles header/footer demotion

package/engine/rules/wcag/1.3.1-definition-list.js

@@ -1,13 +1,12 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
+import { NEVER_RENDERED } from '../../lib/dom.js';
+
 const ALLOWED = new Set(['DT', 'DD', 'DIV']);
-// Nothing here reaches the accessibility tree, so none of it can corrupt
-// the term/description pairing: the same set list-structure keeps, for the
-// same reason (CSS-in-JS injects <style> right beside the markup). HTML's
-// content model does exclude style from dl, but validity is not the
-// criterion; 1.3.1 is about relationships assistive technology can
-// determine, and every dt/dd pair stays intact around an element that has
-// no tree presence (2026-08-25 overnight audit).
-const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+// NEVER_RENDERED cannot corrupt the term/description pairing: HTML's content
+// model does exclude style from dl, but validity is not the criterion;
+// 1.3.1 is about relationships assistive technology can determine, and
+// every dt/dd pair stays intact around an element that has no tree
+// presence (2026-08-25 overnight audit).
 
 export default {
   id: 'definition-list',

package/engine/rules/wcag/1.3.1-list-structure.js

@@ -1,9 +1,6 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
-// Nothing here reaches the accessibility tree, so none of it can corrupt a
-// list's structure. STYLE belongs with them: CSS-in-JS libraries inject
-// <style> right where the markup sits, and it was being counted as a stray
-// child that broke the list.
-const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+import { NEVER_RENDERED } from '../../lib/dom.js';
+
 const ITEM_ROLES = ['listitem', 'presentation', 'none'];
 
 export default {

package/engine/rules/wcag/1.4.12-text-spacing.js

@@ -4,13 +4,19 @@
 // The override is injected and removed inside one synchronous pass — the
 // engine only yields to the renderer between rules, so the page never
 // paints the probed state.
-// The probe reflows the whole page for a moment. Two guards keep that
+// The probe reflows the whole page for a moment. Three guards keep that
 // invisible to the user: scroll anchoring is disabled while the override
 // is in (or Chrome re-anchors during the inflated layout and leaves the
 // page scrolled somewhere else when the probe lifts — measured at 884px
-// of drift on a long report page), and the window scroll is restored
-// after removal in case the browser clamped it anyway.
-const OVERRIDE = `html { overflow-anchor: none !important; }
+// of drift on a long report page); the document keeps at least its own
+// height, because a page set with a line height above 1.5 gets SHORTER
+// under the override, the browser clamps the scroll position to the new
+// end, and that clamp paints (measured on rocketvalidator.com: 2500px to
+// 1966px in one frame, David, 2026-09-02); and the window scroll is put
+// back instantly after removal, instantly whatever the page's own
+// scroll-behavior says, since a smooth restore is the visible half of the
+// jump.
+const override = (minHeight) => `html { overflow-anchor: none !important; min-height: ${minHeight}px !important; }
 * {
   line-height: 1.5 !important;
   letter-spacing: 0.12em !important;
@@ -56,7 +62,7 @@ export default {
     const scrollY = win?.scrollY ?? 0;
     const probe = doc.createElement('style');
     probe.dataset.pourAudit = 'probe';
-    probe.textContent = OVERRIDE;
+    probe.textContent = override(doc.documentElement.scrollHeight);
     doc.documentElement.append(probe);
     let after;
     try {
@@ -68,7 +74,7 @@ export default {
       // The audit must never move the page: put the scroll back exactly
       // where the user had it, after the removal's own reflow settles.
       void doc.documentElement.offsetHeight;
-      if (win && (win.scrollX !== scrollX || win.scrollY !== scrollY)) win.scrollTo(scrollX, scrollY);
+      if (win && (win.scrollX !== scrollX || win.scrollY !== scrollY)) win.scrollTo({ left: scrollX, top: scrollY, behavior: 'instant' });
     }
 
     return elements.map((element, i) => {

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

@@ -6,8 +6,7 @@ import {
   opacityAnimating, restingOpacity, mediaRects, inZeroClipSubtree,
   paintedBackdrop, opaquePanelRects, viewportVeil, textShadowHalo, textShadowNegligible,
   pseudoBackdropForText, filmedContrastBounds, backgroundColorSource, scrimPaint, applyOverlays,
-  showRatio, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors,
-} from '../../lib/contrast.js';
+  showRatio, splitBackgroundLayers, backgroundLayerUrl, sampleGridFor, opacityGroupPaint, pseudoTextColors, BOLD_WEIGHT } from '../../lib/contrast.js';
 
 /** The first url() among a background-image list's layers, or null. */
 const firstLayerUrl = (css) => splitBackgroundLayers(css ?? '').map(backgroundLayerUrl).find(Boolean) ?? null;
@@ -407,7 +406,8 @@ async function sampledVerdict(source, foreground, required, doc, overlays = [],
  */
 export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
   // When the colour pair already clears the LARGE-scale minimum, the miss
-  // is about scale, not colour: name the boundary (14pt bold / 18pt), or
+  // is about scale, not colour: name the boundary (14pt bold / 18pt, bold
+  // meaning BOLD_WEIGHT and up), or
   // a bold-but-just-under button reads as the checker ignoring its weight.
   const largeScaleNoteFor = (style, required, ratio) => {
     if (required !== thresholds.normal || ratio < thresholds.large) return '';
@@ -418,15 +418,16 @@ export function createContrastRule({ id, tags, help, helpUrl, thresholds }) {
     // twentieth of a pixel of a cutoff the size is shown to two decimals,
     // and when even that rounds onto the cutoff it is named as just under
     // it. (2026-08-25 overnight audit, defect 9.)
-    const cutoff = weightNum >= 700 ? 56 / 3 : 24;
-    const cutoffText = weightNum >= 700 ? '18.67px' : '24px';
+    const bold = weightNum >= BOLD_WEIGHT;
+    const cutoff = bold ? 56 / 3 : 24;
+    const cutoffText = bold ? '18.67px' : '24px';
     const nearCutoff = Math.abs(sizePx - cutoff) < 0.05;
     let shown = nearCutoff ? `${sizePx.toFixed(2)}px` : `${Math.round(sizePx * 10) / 10}px`;
     if (nearCutoff && parseFloat(shown) >= parseFloat(cutoffText)) shown = `just under ${cutoffText}`;
-    if (weightNum >= 700 && sizePx < 56 / 3) {
+    if (bold && sizePx < 56 / 3) {
       return ` This text is bold at ${shown}; bold text counts as large scale from 18.67px (14pt), where the ${thresholds.large}:1 minimum would apply and these colours would pass.`;
     }
-    if (weightNum < 700 && sizePx >= 56 / 3 && sizePx < 24) {
+    if (!bold && sizePx >= 56 / 3 && sizePx < 24) {
       return ` At ${shown} regular weight this is not large scale; from 24px (18pt), or bold at this size, the ${thresholds.large}:1 minimum would apply and these colours would pass.`;
     }
     return '';

package/engine/rules/wcag/2.2.2-video-loop-motion.js

@@ -8,11 +8,35 @@
 // finding goes to a human with the evidence attached, never asserted: the
 // same verdict discipline as pause-stop-hide's ticker branch.
 //
+// One shape of that mechanism is stated in the markup and needs no human:
+// a visible button whose aria-controls names the video, or a container
+// holding it. That is what aria-controls is for, the element whose
+// presence or contents the control changes, and a page that wires its
+// pause button that way has answered the question the review would ask
+// (pour.dev's own hero and sense videos, David, 2026-09-02). A button that
+// merely sits near the video, or one that is hidden, settles nothing.
+//
 // A <video controls> ships its own pause button and is out of the selector.
 // Icon-scale playback (tiny inline previews) is left alone for the same
 // reason pause-stop-hide skips spinners: flagging every small moving
 // thumbnail would bury the full-bleed hero that matters. Silence there is
 // abstaining, not clearing.
+/** A visible, enabled button whose aria-controls names the video or an
+ *  ancestor of it, looked up in the video's own document or shadow tree. */
+function pauseControlFor(video, isVisible) {
+  const root = video.getRootNode();
+  if (!root.querySelectorAll) return null;
+  const byId = (id) => (root.getElementById ? root.getElementById(id) : root.querySelector(`#${CSS.escape(id)}`));
+  for (const control of root.querySelectorAll('button[aria-controls], [role="button"][aria-controls], input[type="button"][aria-controls]')) {
+    if (control.disabled || !isVisible(control)) continue;
+    for (const id of control.getAttribute('aria-controls').split(/\s+/)) {
+      const target = id && byId(id);
+      if (target && (target === video || target.contains(video))) return control;
+    }
+  }
+  return null;
+}
+
 export default {
   id: 'video-loop-motion',
   name: 'Looping video control',
@@ -23,7 +47,7 @@ export default {
   selector: 'video[autoplay][loop]:not([controls])',
   // Movement is a visual matter: an aria-hidden hero still moves on screen.
   visibility: 'visual',
-  evaluate(element) {
+  evaluate(element, { isVisible }) {
     // Icon scale means SMALL, not thin: a 1200×60 animated banner strip is
     // a ticker, and only a video small on both axes is spinner-class.
     const rect = element.getBoundingClientRect();
@@ -32,6 +56,7 @@ export default {
     // something on the page already paused it — in both cases nothing is
     // moving, and a paused-by-a-control video is the mechanism working.
     if (element.paused && element.readyState >= 2) return { status: 'pass' };
+    if (pauseControlFor(element, isVisible)) return { status: 'pass' };
     return {
       status: 'incomplete',
       message: 'This video auto-plays on a loop with no built-in controls: it starts by itself and never ends, so it runs well past the five seconds at which WCAG 2.2.2 requires a way to pause, stop or hide it. Check the page offers a pause control that reaches this video, or that the video is the only content presented.',

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

@@ -1,6 +1,6 @@
 // WCAG SC 2.4.1 Bypass Blocks (Level A)
 import { collectRoots, isEmbeddedDocument } from '../../lib/dom.js';
-import { effectiveRole } from '../../lib/roles.js';
+import { effectiveRole, LANDMARK_ROLES } from '../../lib/roles.js';
 
 // ARIA11 lists the landmark roles: banner, complementary, contentinfo,
 // form, main, navigation, region, search. Judged by EFFECTIVE role, not tag
@@ -10,7 +10,6 @@ import { effectiveRole } from '../../lib/roles.js';
 // and missed the second. region and form are landmarks only when named
 // (ARIA 1.2 requires an accessible name for region; HTML-AAM maps form to
 // the form landmark only with one), so the name is checked here.
-const LANDMARK_ROLES = new Set(['banner', 'complementary', 'contentinfo', 'form', 'main', 'navigation', 'region', 'search']);
 const NAMED_ONLY = new Set(['form', 'region']);
 const LANDMARK_CANDIDATES = 'main, header, footer, nav, aside, section, form, [role]';
 const hasName = (el) => Boolean(

package/package.json

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