pour-engine 1.23.0 → 1.25.0

package/config/project.config.js

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

package/engine/lib/accessible-name.js

@@ -143,7 +143,18 @@ function textFromNodes(nodes, includeHidden) {
       continue;
     }
     if (tag === 'img' || tag === 'area') {
-      text += ` ${node.getAttribute('alt') ?? ''} `;
+      // HTML-AAM order for an image's own name: aria-label → alt → title.
+      // A PRESENT-but-empty alt marks the image decorative and contributes
+      // nothing — title must not resurrect it. Only when alt is ABSENT do
+      // the fallbacks apply (a title-only <img> inside a link names the
+      // link; Chromium exposes exactly this, measured on a live site where
+      // the walk's old alt-or-nothing shortcut called a named link nameless).
+      const imgAria = node.getAttribute('aria-label')?.trim();
+      if (imgAria) { text += ` ${imgAria} `; continue; }
+      const alt = node.getAttribute('alt');
+      if (alt !== null) { text += ` ${alt} `; continue; }
+      const imgTitle = node.getAttribute('title')?.trim();
+      if (imgTitle) text += ` ${imgTitle} `;
       continue;
     }
     const ariaLabel = node.getAttribute('aria-label')?.trim();

package/engine/lib/dom.js

@@ -47,7 +47,13 @@ export function isVisible(element) {
 
 /** Selector for an element within its own root (document or shadow root). */
 function cssPathInRoot(element) {
-  if (element.id) return `#${CSS.escape(element.id)}`;
+  // An id anchors the selector only when it is UNIQUE in this root: real
+  // pages duplicate ids (three carousel pagers all id="default"), and a
+  // bare #id selector would round-trip every one of them to the first,
+  // collapsing distinct findings onto a single element.
+  const root = element.getRootNode();
+  const uniqueId = (el) => el.id && root.querySelectorAll(`#${CSS.escape(el.id)}`).length === 1;
+  if (uniqueId(element)) return `#${CSS.escape(element.id)}`;
   const parts = [];
   let current = element;
   while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.documentElement) {
@@ -66,7 +72,7 @@ function cssPathInRoot(element) {
       if (repeated) part += `:nth-of-type(${index})`;
     }
     parts.unshift(part);
-    if (current.parentElement?.id) {
+    if (current.parentElement && uniqueId(current.parentElement)) {
       parts.unshift(`#${CSS.escape(current.parentElement.id)}`);
       break;
     }

package/engine/rules/wcag/1.2.2-media-captions.js

@@ -16,6 +16,24 @@ export default {
     if (element.querySelector('track[kind="captions" i], track[kind="subtitles" i], track:not([kind])')) {
       return { status: 'pass' };
     }
+    // A video with no media resource at all presents nothing — there is no
+    // audio content to caption (lazy players before their source is set).
+    if (!element.currentSrc && !element.getAttribute('src') && !element.querySelector('source')) {
+      return { status: 'pass' };
+    }
+    // The decorative no-audio-path signature — the same boundary
+    // video-loop-motion draws for 2.2.2: muted, autoplaying, no controls.
+    // With no controls there is no user path to unmute, so whatever audio
+    // the file may carry is never presented to anyone; audio that cannot be
+    // presented is not audio content under 1.2.2, and asking a human to
+    // verify captions for it is noise (measured on the benchmark corpus:
+    // our own site's aria-hidden hero loops, ffprobe-confirmed to carry no
+    // audio stream, plus the same family on four news/university homes).
+    // Properties, not attributes: script-muted heroes count too. A muted
+    // video WITH controls keeps its review — one click unmutes it.
+    if (element.muted && element.autoplay && !element.controls) {
+      return { status: 'pass' };
+    }
     // Captions may be burned in or provided by the player — a human must check.
     return {
       status: 'incomplete',

package/engine/rules/wcag/1.3.1-form-label.js

@@ -21,16 +21,23 @@ export default {
       const style = getComputedStyle(label);
       return style.display !== 'none' && style.visibility !== 'hidden';
     });
-    // Label content includes aria-labels on things inside it (icon-only
-    // labels like <label><svg aria-label="Dark mode"/></label> still name)
-    // and image alts (<label><img alt="…"></label> is a visible, named
-    // label — alt text feeds name-from-contents per accname).
-    const labelsText = visibleLabels
-      .map((l) =>
-        `${l.textContent} ${[...l.querySelectorAll('[aria-label], img[alt], area[alt]')]
-          .map((e) => e.getAttribute('aria-label') ?? e.getAttribute('alt')).join(' ')}`)
-      .join(' ')
-      .trim();
+    // A label's contribution is its ACCESSIBLE text, not its raw textContent:
+    // aria-hidden subtrees inside the label are excluded from the name
+    // computation (a custom radio whose only visible text sits in an
+    // aria-hidden styled twin names NOTHING — the browser's tree computes an
+    // empty name), while aria-label on the label itself or on things inside
+    // it (icon-only labels) and image alts DO feed the name per accname.
+    const accessibleText = (node) => {
+      if (node.nodeType === Node.TEXT_NODE) return node.textContent;
+      if (node.nodeType !== Node.ELEMENT_NODE) return '';
+      if (node.getAttribute('aria-hidden') === 'true') return '';
+      const aria = node.getAttribute('aria-label');
+      if (aria?.trim()) return aria;
+      const alt = (node.tagName === 'IMG' || node.tagName === 'AREA') ? node.getAttribute('alt') : null;
+      if (alt?.trim()) return alt;
+      return [...node.childNodes].map(accessibleText).join(' ');
+    };
+    const labelsText = visibleLabels.map(accessibleText).join(' ').trim();
     const ariaLabel = element.getAttribute('aria-label')?.trim();
     const labelledby = labelledByName(element);
     if (labelsText || ariaLabel || labelledby) return { status: 'pass' };
@@ -65,10 +72,18 @@ export default {
       };
     }
     if (element.labels?.length) {
+      // The label may LOOK fine while announcing nothing: all its text
+      // sitting inside an aria-hidden subtree (the styled-twin custom
+      // control pattern) is excluded from the name computation.
+      const looksLabelled = visibleLabels.some((l) => l.textContent.trim());
       return {
         status: 'fail',
-        message: 'This field has a <label>, but the label is empty — it announces nothing.',
-        fix: 'Put visible text inside the label.',
+        message: looksLabelled
+          ? 'This field\'s <label> shows text, but all of it is inside aria-hidden content — the accessible name computes to nothing.'
+          : 'This field has a <label>, but the label is empty — it announces nothing.',
+        fix: looksLabelled
+          ? 'Move the visible text out of the aria-hidden wrapper, or add aria-label to the field.'
+          : 'Put visible text inside the label.',
       };
     }
     return {

package/engine/rules/wcag/1.4.11-non-text-contrast.js

@@ -77,7 +77,12 @@ export default {
     // the visible boundary (border, or a fill contrasting with the page
     // around it). The FIELD the user perceives is the wrapper — but only a
     // SNUG wrapper counts: a page section's border is not a field boundary.
-    for (let wrapper = element.parentElement, depth = 0; wrapper && depth < 2; wrapper = wrapper.parentElement, depth++) {
+    // Snugness is the guard, so the walk continues through transparent
+    // intermediate wrappers (autocomplete shells, JS mount points) as long
+    // as each stays field-sized — a search plate three levels up is still
+    // the field the user sees, while a page section fails the size check
+    // long before any depth cap would matter.
+    for (let wrapper = element.parentElement, depth = 0; wrapper && depth < 4; wrapper = wrapper.parentElement, depth++) {
       const wrapperRect = wrapper.getBoundingClientRect();
       if (wrapperRect.height > ownRect.height + 24 || wrapperRect.width > ownRect.width + 160) break;
       const wrapperStyle = getComputedStyle(wrapper);

package/engine/rules/wcag/4.1.2-nested-interactive.js

@@ -17,9 +17,19 @@ export default {
     // Only descendants a user can actually reach count: hidden inputs,
     // disabled controls, display:none templates, and tabindex="-1" nodes
     // inside a control are inert markup, not competing tab stops.
+    // Two more shapes are unreachable by the same principle: aria-hidden
+    // content (AT ignores it wholesale — a decorative svg role="button"
+    // aria-hidden="true" inside a play button competes with nothing; if it
+    // is natively focusable that is aria-hidden-focus's finding, not a
+    // second one here), and role-only widgets never given a tabindex (a
+    // role="button" with no tabindex is not in the tab order — keyboard
+    // users cannot reach it, so it cannot be a competing stop).
+    const NATIVE = 'a[href], button, input, select, textarea, summary, audio[controls], video[controls]';
     const nested = [...element.querySelectorAll(INTERACTIVE)].find((el) =>
       !el.matches(':disabled') && el.getAttribute('tabindex') !== '-1'
-      && !(el.tagName === 'INPUT' && el.type === 'hidden') && isRendered(el));
+      && !(el.tagName === 'INPUT' && el.type === 'hidden') && isRendered(el)
+      && !el.closest('[aria-hidden="true"]')
+      && (el.matches(NATIVE) || el.hasAttribute('tabindex')));
     if (!nested) return { status: 'pass' };
     return {
       status: 'fail',

package/engine/rules/wcag/4.1.2-role-required-aria.js

@@ -20,12 +20,16 @@ export default {
     const role = element.getAttribute('role');
     const required = REQUIRED[role];
     if (element.hasAttribute(required)) return { status: 'pass' };
-    // A redundant explicit role on the native element (input type=checkbox
-    // role=checkbox — common framework output) needs no ARIA state: the
-    // host language supplies checkedness/value natively.
+    // Native semantics supply the state regardless of WHICH state-bearing
+    // role is claimed: HTML-AAM maps an input's checkedness to aria-checked
+    // (input type=checkbox role="switch" — the standard toggle pattern —
+    // exposes checked=false/true in the browser's tree with no ARIA at all),
+    // and a range input's value to aria-valuenow likewise.
     const type = element.tagName === 'INPUT' ? element.type : null;
-    const NATIVE_STATE = { checkbox: 'checkbox', radio: 'radio', range: 'slider' };
-    if (type && NATIVE_STATE[type] === role) return { status: 'pass' };
+    if (type === 'checkbox' || type === 'radio') {
+      if (required === 'aria-checked') return { status: 'pass' };
+    }
+    if (type === 'range' && required === 'aria-valuenow') return { status: 'pass' };
     if (element.tagName === 'SELECT' && role === 'combobox') return { status: 'pass' };
     return {
       status: 'fail',

package/package.json

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