pour-engine 1.38.0 → 1.40.0

package/config/project.config.js

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

package/engine/lib/accessible-name.js

@@ -115,10 +115,21 @@ function visibleContentText(element, includeHidden) {
 
 /** CSS generated content contributes to name-from-contents per the accname
  *  spec — icon-font prefixes and content:"…" labels are real names. Only
- *  plain strings count: counters, url(), attr() are not resolvable here. */
+ *  plain strings count: counters, url(), attr() are not resolvable here.
+ *
+ *  The exception is the CSS alternative text syntax, content: <image or
+ *  string> / "alt", which exists precisely to give assistive technology the
+ *  text for generated content and which browsers expose: an icon-only button
+ *  drawn with content: url(menu.svg) / "Menu" IS named "Menu" (Chromium's
+ *  accessibility tree agrees), and calling it nameless asserted a critical
+ *  4.1.2 failure against the recommended pattern. An EMPTY alternative marks
+ *  the generated content decorative and contributes nothing, which is how
+ *  the same syntax silences icon glyphs. */
 function generatedContent(element, pseudo) {
   const content = getComputedStyle(element, pseudo).content;
   if (!content || content === 'none' || content === 'normal') return '';
+  const alt = content.match(/\/\s*"((?:[^"\\]|\\.)*)"\s*$/);
+  if (alt) return alt[1].replace(/\\(.)/g, '$1');
   const match = content.match(/^"((?:[^"\\]|\\.)*)"$/);
   return match ? match[1].replace(/\\(.)/g, '$1') : '';
 }

package/engine/lib/roles.js

@@ -208,11 +208,23 @@ export function implicitRole(element) {
  * but adding tabindex or aria-describedby exposes `heading`. Note a non-global
  * property applicable to the implicit role (aria-level on a heading) does NOT
  * trigger it, even though a strict reading of the spec suggests it should.
+ *
+ * "Focusable" means focusable in fact, not focusable by tag. A disabled
+ * control and anything inside an inert subtree are not focusable areas, so
+ * their presentational role STANDS and the browser keeps them out of the
+ * accessibility tree: Chromium exposes `<button role="none" disabled>` as
+ * role none, with no name to owe. Reading focusability from the tag alone
+ * (or from tabIndex, which Chromium still reports as 0 on a disabled
+ * button) resurrected those elements and asserted a missing name on a
+ * control the user is never offered.
  */
 function presentationDiscarded(element) {
+  // A global property is exposed whatever the element's state, so it
+  // discards the role on its own, disabled or not.
+  if ([...GLOBAL_ARIA].some((name) => element.hasAttribute(`aria-${name}`))) return true;
+  if (element.matches(':disabled') || element.closest('[inert]')) return false;
   if (element.tabIndex >= 0) return true;
-  if (element.matches('a[href], button, input, select, textarea, summary, [contenteditable="true"]')) return true;
-  return [...GLOBAL_ARIA].some((name) => element.hasAttribute(`aria-${name}`));
+  return element.matches('a[href], button, input, select, textarea, summary, [contenteditable="true"]');
 }
 
 export function effectiveRole(element) {

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

@@ -34,10 +34,18 @@ export default {
   helpUrl: 'https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/',
   // Implicit landmarks (header, footer, labelled section/form) join the
   // grouping — a page's <header> and a div[role="banner"] ARE duplicates.
+  // region and form need a name to BE landmarks (ARIA 1.2 gives both "Name
+  // From: author", and Chromium exposes an unnamed one as generic), which is
+  // why the native <section> and <form> above are already spelled with the
+  // name requirement. Without it, two unnamed div[role="region"] were
+  // reported as indistinguishable landmarks when neither is a landmark at
+  // all, sending the author to label something no screen reader announces.
   selector:
     'nav, search, aside, header, footer, section[aria-label], section[aria-labelledby], ' +
     'form[aria-label], form[aria-labelledby], [role="navigation"], [role="complementary"], ' +
-    '[role="banner"], [role="contentinfo"], [role="region"], [role="search"], [role="form"], [role="main"], main',
+    '[role="banner"], [role="contentinfo"], [role="region"][aria-label], ' +
+    '[role="region"][aria-labelledby], [role="form"][aria-label], [role="form"][aria-labelledby], ' +
+    '[role="search"], [role="main"], main',
   // Judged as a set: two unlabelled navs are the problem, not either alone.
   evaluateAll(elements) {
     const roles = elements.map(landmarkRole);

package/engine/rules/best-practice/region.js

@@ -14,8 +14,16 @@ const LANDMARK =
   'header:not(:is(article, aside, main, nav, section) header), ' +
   'footer:not(:is(article, aside, main, nav, section) footer), ' +
   'section[aria-label], section[aria-labelledby], [role="main"], [role="navigation"], ' +
-  '[role="banner"], [role="contentinfo"], [role="complementary"], [role="region"], ' +
-  '[role="search"], [role="form"], [role="dialog"], [role="alertdialog"], dialog[open]';
+  '[role="banner"], [role="contentinfo"], [role="complementary"], ' +
+  // region and form are exposed as landmarks only once they are named (ARIA
+  // 1.2 gives both "Name From: author"), which is why the native <section>
+  // and <form> above already carry that requirement. Accepting the ARIA
+  // spelling bare let a nameless div[role="region"] stand in for a landmark
+  // and hid every stray element inside it; Chromium exposes that div as
+  // generic, so screen-reader users reach none of it by region navigation.
+  '[role="region"][aria-label], [role="region"][aria-labelledby], ' +
+  '[role="form"][aria-label], [role="form"][aria-labelledby], ' +
+  '[role="search"], [role="dialog"], [role="alertdialog"], dialog[open]';
 
 export default {
   id: 'region',

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

@@ -1,5 +1,5 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
-import { NEVER_RENDERED } from '../../lib/dom.js';
+import { NEVER_RENDERED, isInert } from '../../lib/dom.js';
 
 const ALLOWED = new Set(['DT', 'DD', 'DIV']);
 // NEVER_RENDERED cannot corrupt the term/description pairing: HTML's content
@@ -17,11 +17,14 @@ export default {
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
   selector: 'dl:not([role])', // a role attribute replaces the dl semantics
   evaluate(element, { isRendered }) {
+    const exposed = (child) => !NEVER_RENDERED.has(child.tagName)
+      && !child.closest('[aria-hidden="true"]') && !isInert(child)
+      && (!isRendered || isRendered(child) || getComputedStyle(child).display === 'contents');
     // A child the browser never renders (display:none, hidden) is not in
     // the accessibility tree either, so it cannot break the pairing a
     // reader hears; list-structure applies the same gate.
     const invalid = [...element.children].filter((child) =>
-      !ALLOWED.has(child.tagName) && !NEVER_RENDERED.has(child.tagName) && (!isRendered || isRendered(child)));
+      !ALLOWED.has(child.tagName) && exposed(child));
     if (invalid.length) {
       const tags = [...new Set(invalid.map((child) => `<${child.tagName.toLowerCase()}>`))].join(', ');
       return {
@@ -36,7 +39,7 @@ export default {
     // out of the dl's content model, so the term/description association is
     // no longer guaranteed to assistive technology.
     const emptyWrappers = [...element.children].filter((child) =>
-      child.tagName === 'DIV' && ![...child.children].some((inner) => inner.tagName === 'DT' || inner.tagName === 'DD'));
+      child.tagName === 'DIV' && exposed(child) && ![...child.children].some((inner) => inner.tagName === 'DT' || inner.tagName === 'DD'));
     if (emptyWrappers.length) {
       return {
         status: 'fail',
@@ -44,6 +47,42 @@ export default {
         fix: 'Make each <div> child of the <dl> contain its <dt>/<dd> pair directly, or flatten the pairs into the <dl> itself.',
       };
     }
+    // HTML defines a group as one or more terms followed by one or more
+    // descriptions. Check each wrapper independently, so a term in one
+    // group cannot supply the missing term of another.
+    // https://html.spec.whatwg.org/multipage/grouping-content.html#the-dl-element
+    const children = [...element.children].filter(exposed);
+    const groups = [[...element.children].filter((child) => child.tagName !== 'DIV'),
+      ...children.filter((child) => child.tagName === 'DIV').map((child) => [...child.children])];
+    for (const members of groups) {
+      const group = members.filter(exposed);
+      const concealedPairMember = members.some((child) => (child.tagName === 'DT' || child.tagName === 'DD') && !exposed(child));
+      const concealedResult = {
+        status: 'incomplete',
+        message: 'A term or description in this group is hidden from assistive technology. Check that any disclosure control exposes the associated content when opened, and that the term and description relationship remains available.',
+      };
+      let last = null;
+      for (const child of group) {
+        if (child.tagName !== 'DT' && child.tagName !== 'DD') continue;
+        if (child.tagName === 'DD' && last === null) {
+          if (concealedPairMember) return concealedResult;
+          return {
+            status: 'fail',
+            message: 'This description list has a description without a preceding term in its group.',
+            fix: 'Add a <dt> before the <dd>, or use a paragraph when the content is not a term and description.',
+          };
+        }
+        last = child.tagName;
+      }
+      if (last === 'DT') {
+        if (concealedPairMember) return concealedResult;
+        return {
+          status: 'fail',
+          message: 'This description list ends a group with a term that has no description.',
+          fix: 'Follow the <dt> element or elements with at least one <dd> in the same group.',
+        };
+      }
+    }
     return { status: 'pass' };
   },
 };

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

@@ -3,6 +3,7 @@
 // 3.3.2 mapping: a field with no label at all, or only a vanishing
 // placeholder, is failure F82 — the classic 3.3.2 pattern.
 import { labelledByName } from '../../lib/accessible-name.js';
+import { effectiveRole } from '../../lib/roles.js';
 
 export default {
   id: 'form-label',
@@ -14,6 +15,12 @@ export default {
   selector:
     'input:not([type="hidden"]):not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="image"]), select, textarea',
   evaluate(element) {
+    // A field whose presentational role survives the conflict resolution is
+    // not in the accessibility tree at all: <select role="none" disabled> is
+    // exposed as role none, so there is no field to name under 4.1.2 and
+    // nothing to fill in under 3.3.2. The role library owns that judgment.
+    const role = effectiveRole(element);
+    if (role === 'presentation' || role === 'none') return { status: 'pass' };
     // Only perceivable labels count: a display:none / aria-hidden label
     // technically feeds the accessible name, but nobody can see it and
     // that defeats the point of a label.

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

@@ -121,16 +121,23 @@ export default {
   // embedded in prose exactly as 1.4.1 means it. Pure link lists (navs,
   // blogrolls) are still excluded, but by the ownText guard below rather than
   // by tag: in <li><a>Home</a></li> the item has no text of its own.
-  // <div> was measured too and added nothing on any test site, so it stays
-  // out rather than widening the blast radius for no gain.
-  selector: 'p a[href], dd a[href], blockquote a[href], td a[href], li a[href]',
+  // Prose in a generic container has the same requirement. F73 does not
+  // limit colour-only links to paragraph markup. The text and shared-line
+  // checks below keep navigation and separate blocks out of this lane.
+  // https://www.w3.org/WAI/WCAG22/Techniques/failures/F73
+  selector: 'p a[href], dd a[href], blockquote a[href], td a[href], li a[href], div a[href]',
   visibility: 'visual', // colour distinction is a purely visual concern
   evaluate(element, { ownText }) {
-    const parent = element.closest('p, dd, blockquote, td, li');
+    const parent = element.closest('p, dd, blockquote, td, li, div');
     if (!element.textContent.trim() || !parent) return { status: 'pass' };
     // Needs real surrounding text to blend into (1.4.1 is about links
     // embedded in prose, not a link that IS the content).
-    if (ownText(parent).replace(/\s+/g, '').length < 10) return { status: 'pass' };
+    const surroundingText = ownText(parent).trim();
+    if (!/[\p{L}\p{N}]/u.test(surroundingText)) return { status: 'pass' };
+    // A short fragment may be prose ("See ..."), an equation or a label.
+    // F73 has no minimum character count. Keep evaluating the visual cues
+    // and ask about ambiguous context instead of silently passing it.
+    const shortContext = surroundingText.replace(/\s+/g, '').length < 10;
 
     const style = getComputedStyle(element);
     const parentStyle = getComputedStyle(parent);
@@ -330,6 +337,13 @@ export default {
         fix: reviewFix,
       };
     }
+    if (shortContext) {
+      return {
+        status: 'incomplete',
+        message: `This link has no detected non-colour cue and only ${shown}:1 colour difference from nearby text. The surrounding text is a short fragment. Check whether it forms a sentence or other prose with the link; if it does, colour alone does not distinguish the link sufficiently.`,
+        fix: reviewFix,
+      };
+    }
     return {
       status: 'fail',
       // The measured fact is the ratio against G183's threshold, and that is

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

@@ -23,6 +23,33 @@ function refreshDestination(content) {
   return rest.trim();
 }
 
+/**
+ * The delay the browser would actually use, and null when the HTML "shared
+ * declarative refresh steps" bail out and schedule nothing at all. Those
+ * steps collect ASCII digits and stop: a leading "+" ends the parse before a
+ * single digit is read (content="+5; url=…" refreshes nothing), and anything
+ * other than ";", "," or whitespace directly after the digits does the same
+ * (content="1x; url=…"). parseInt accepts both and returned 5 and 1, so the
+ * 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) {
+  const isAsciiSpace = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\f' || c === '\r';
+  const isDigit = (c) => c >= '0' && c <= '9';
+  let i = 0;
+  while (i < content.length && isAsciiSpace(content[i])) i++;
+  let digits = '';
+  while (i < content.length && isDigit(content[i])) digits += content[i++];
+  // No digits is only allowed when a decimal point follows, which the steps
+  // read as a fractional delay of zero seconds.
+  if (!digits && content[i] !== '.') return null;
+  const delay = digits ? Number(digits) : 0;
+  // Trailing digits and full stops are collected and thrown away.
+  while (i < content.length && (isDigit(content[i]) || content[i] === '.')) i++;
+  if (i < content.length && content[i] !== ';' && content[i] !== ',' && !isAsciiSpace(content[i])) return null;
+  return delay;
+}
+
 export default {
   id: 'meta-refresh',
   name: 'Timed page refresh',
@@ -34,7 +61,10 @@ export default {
   visibleOnly: false,
   evaluate(element) {
     const content = element.getAttribute('content') ?? '';
-    const delay = parseInt(content, 10);
+    const delay = refreshDelay(content);
+    // The browser discards this directive, so no time limit is set by the
+    // content and 2.2.1 has nothing to judge.
+    if (delay === null) return { status: 'pass' };
     // A refresh with no destination reloads THIS page. At zero seconds that
     // is not the allowed instant redirect — it is a loop that throws the
     // user back to the top of the page over and over (failure F41).

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

@@ -31,6 +31,31 @@ const TARGETS = 'a[href], button, input, select, [role="button"], [role="link"]'
  */
 import { isInert } from '../../lib/dom.js';
 
+// A web component's internal link and its enclosing light-DOM link are
+// not independent pointer targets. DOM contains() stops at shadow roots.
+function containsComposed(ancestor, element) {
+  if (ancestor.contains(element)) return true;
+  if (ancestor.getRootNode() === element.getRootNode() && !element.assignedSlot) return false;
+  for (let node = element; node; node = node.assignedSlot ?? node.parentElement ?? node.getRootNode()?.host) {
+    if (node === ancestor) return true;
+  }
+  return false;
+}
+
+function outsideHiddenOverflow(element, rect) {
+  for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+    const style = getComputedStyle(parent);
+    if (style.display === 'contents') continue; // no principal box to clip its children
+    const x = /^(hidden|clip)$/.test(style.overflowX);
+    const y = /^(hidden|clip)$/.test(style.overflowY);
+    if (!x && !y) continue;
+    const clip = parent.getBoundingClientRect();
+    if ((x && (clip.width === 0 || rect.right <= clip.left || rect.left >= clip.right))
+      || (y && (clip.height === 0 || rect.bottom <= clip.top || rect.top >= clip.bottom))) return true;
+  }
+  return false;
+}
+
 function isHiddenFromPointer(element, rect) {
   if (rect.width <= 1 || rect.height <= 1) return true;
   if (rect.right <= 0 || rect.bottom <= 0) return true; // parked above/left of the canvas
@@ -567,7 +592,7 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
         // target's circle.
         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 (containsComposed(other, element) || containsComposed(element, other)) return false; // same control, including shadow content
           // "One control drawn twice" (stretched-link overlays) is a claim
           // about PAINT, so it must be proved on a painted fragment, not on
           // the bounding box: a two-line wrapped link's box swallows a small
@@ -576,7 +601,20 @@ export function createTargetSizeRule({ id, tags, help, helpUrl, min, spacingExce
           // the honest fragment test below. A single-fragment element's one
           // fragment IS its box, so genuine overlays are dismissed exactly
           // as before.
-          if (paintedEncloses(other, rects[j], rects[i]) || paintedEncloses(element, rects[i], rects[j])) return false;
+          // Containment of one painted box inside another does not prove
+          // that they perform the same action. A small preview button over
+          // an image link is explicitly a spacing failure in SC 2.5.8.
+          // Only two links with the same real destination can use the
+          // equivalent-control exemption here.
+          // https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
+          if (paintedEncloses(other, rects[j], rects[i]) || paintedEncloses(element, rects[i], rects[j])) {
+            const destination = destinationOf(element);
+            if (destination && destination === destinationOf(other)) return false;
+            // Collapsed disclosures can leave their descendants' boxes
+            // overlapping nearby controls even though the overflow clips
+            // them completely. Such boxes accept no pointer input.
+            if (outsideHiddenOverflow(element, rects[i]) || outsideHiddenOverflow(other, rects[j])) return false;
+          }
           // Crowding across fixed/sticky contexts is scroll state, not
           // layout, exactly as the obscured-target test reads overlap: a
           // consent banner pinned to the bottom of the viewport lays its

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

@@ -1,4 +1,5 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
+import { isInert } from '../../lib/dom.js';
 // Deliberately excludes bare [tabindex]: a focusable container (e.g. a
 // scrollable region with tabindex="0") holding links is correct markup.
 const INTERACTIVE =
@@ -16,8 +17,7 @@ export default {
   selector: INTERACTIVE,
   evaluate(element, { isRendered }) {
     // 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.
+    // disabled controls and display:none templates are excluded.
     // 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
@@ -26,16 +26,28 @@ export default {
     // 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]';
-    // Any negative tabindex is unreachable by Tab (HTML: "a negative
-    // integer"), not only the literal "-1"; hasAttribute guards the default
-    // -1 Chromium reports for attribute-less contenteditable elements.
-    // 2026-08-25 overnight audit.
-    const nested = [...element.querySelectorAll(INTERACTIVE)].find((el) =>
-      !el.matches(':disabled') && !(el.hasAttribute('tabindex') && el.tabIndex < 0)
+    // Negative tabindex removes sequential focus navigation, not focusability.
+    // https://html.spec.whatwg.org/multipage/interaction.html#attr-tabindex
+    const candidates = [...element.querySelectorAll(INTERACTIVE)].filter((el) =>
+      !el.matches(':disabled') && !isInert(el)
       && !(el.tagName === 'INPUT' && el.type === 'hidden') && isRendered(el)
       && !el.closest('[aria-hidden="true"]')
       && (el.matches(NATIVE) || el.hasAttribute('tabindex')));
+    // A child requiring review must not conceal a later definite finding.
+    const nested = candidates.find((el) => !(el.hasAttribute('tabindex') && el.tabIndex < 0)) ?? candidates[0];
     if (!nested) return { status: 'pass' };
+    // A programmatically focusable child must not silently pass. In an
+    // ARIA widget its name and role can survive presentational-descendant
+    // processing, so nesting alone does not prove a 4.1.2 failure.
+    // Native links/buttons separately forbid interactive descendants.
+    // https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion
+    if (nested.hasAttribute('tabindex') && nested.tabIndex < 0
+      && !element.matches('a[href], button')) {
+      return {
+        status: 'incomplete',
+        message: `This control contains an element (<${nested.tagName.toLowerCase()}>) with a negative tabindex. It can still receive focus. Check that both controls expose the intended name and role, and that focusing and activating the child works correctly.`,
+      };
+    }
     // <summary> is the one outer control HTML does not forbid this on: its
     // content model is phrasing content with no "no interactive content
     // descendant" clause (a and button both carry one), it maps to no ARIA

package/package.json

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