pour-engine 1.38.0 → 1.41.0

package/engine/lib/dom.js

@@ -13,7 +13,9 @@ export const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'M
  * design — like every DOM tool, we can only see what the page exposes.
  */
 export function collectRoots(context) {
-  const roots = [context];
+  // querySelectorAll excludes the context itself, including its own open
+  // shadow root when a host element is the requested audit scope.
+  const roots = context.shadowRoot ? [context, context.shadowRoot] : [context];
   for (let i = 0; i < roots.length; i++) {
     if (!roots[i].querySelectorAll) continue;
     for (const el of roots[i].querySelectorAll('*')) {
@@ -25,8 +27,8 @@ export function collectRoots(context) {
 
 /** Nearest ancestor in the FLAT tree: parent element, or the shadow host
  *  when the walk reaches the top of a shadow tree. */
-function flatTreeParent(node) {
-  return node.parentElement ?? node.getRootNode()?.host ?? null;
+export function flatTreeParent(node) {
+  return node.assignedSlot ?? node.parentElement ?? node.getRootNode()?.host ?? null;
 }
 
 /**
@@ -46,9 +48,75 @@ export function isRendered(element) {
  *  hides its shadow content too. */
 export function isVisible(element) {
   for (let node = element; node; node = flatTreeParent(node)) {
-    if (node.getAttribute?.('aria-hidden') === 'true') return false;
+    if (node.getAttribute?.('aria-hidden') === 'true' || node.hasAttribute?.('inert')) return false;
   }
-  return isRendered(element);
+  if (isRendered(element)) return true;
+  // Boxless semantic containers can still be exposed to AT. Keep the
+  // visual helper box-based, but do not skip their names/relationships.
+  const style = getComputedStyle(element);
+  if (style.display !== 'contents' || style.visibility === 'hidden' || style.visibility === 'collapse') return false;
+  for (let node = flatTreeParent(element); node; node = flatTreeParent(node)) {
+    if (getComputedStyle(node).display === 'none') return false;
+  }
+  return true;
+}
+
+let pathRoots = new WeakMap();
+const pathObservers = new Set();
+
+/** Release observers after an audit, including an aborted audit. */
+export function releaseDOMCaches() {
+  for (const observer of pathObservers) observer.disconnect();
+  pathObservers.clear();
+  pathRoots = new WeakMap();
+}
+
+export const resetDOMCaches = releaseDOMCaches;
+
+function pathIndex(root) {
+  let index = pathRoots.get(root);
+  if (!index) {
+    const observer = typeof MutationObserver === 'function' ? new MutationObserver(() => {
+      index.ids = null;
+      index.parents = new WeakMap();
+    }) : null;
+    index = { ids: null, parents: new WeakMap(), observer };
+    if (observer) {
+      observer.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['id'] });
+      pathObservers.add(observer);
+    }
+    pathRoots.set(root, index);
+  }
+  // Synchronous mutations may precede the observer callback. A selector
+  // must describe the current tree even in the same JavaScript task.
+  if (index.observer?.takeRecords().length) {
+    index.ids = null;
+    index.parents = new WeakMap();
+  }
+  if (!index.ids) {
+    index.ids = new Map();
+    for (const el of root.querySelectorAll('[id]')) {
+      index.ids.set(el.id, (index.ids.get(el.id) ?? 0) + 1);
+    }
+  }
+  return index;
+}
+
+function siblingPosition(element, index) {
+  const parent = element.parentElement;
+  let positions = index.parents.get(parent);
+  if (!positions) {
+    const counts = new Map();
+    positions = new WeakMap();
+    for (const child of parent.children) {
+      const position = (counts.get(child.tagName) ?? 0) + 1;
+      counts.set(child.tagName, position);
+      positions.set(child, { position, repeated: false });
+    }
+    for (const child of parent.children) positions.get(child).repeated = counts.get(child.tagName) > 1;
+    index.parents.set(parent, positions);
+  }
+  return positions.get(element);
 }
 
 /** Selector for an element within its own root (document or shadow root). */
@@ -58,24 +126,16 @@ function cssPathInRoot(element) {
   // 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;
+  const index = pathIndex(root);
+  const uniqueId = (el) => el.id && index.ids.get(el.id) === 1;
   if (uniqueId(element)) return `#${CSS.escape(element.id)}`;
   const parts = [];
   let current = element;
   while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.documentElement) {
     let part = current.tagName.toLowerCase();
     if (current.parentElement) {
-      // Sibling walk without materializing children arrays — this runs for
-      // every reported element at every ancestor level.
-      let index = 1;
-      for (let sib = current.previousElementSibling; sib; sib = sib.previousElementSibling) {
-        if (sib.tagName === current.tagName) index += 1;
-      }
-      let repeated = index > 1;
-      for (let sib = current.nextElementSibling; !repeated && sib; sib = sib.nextElementSibling) {
-        if (sib.tagName === current.tagName) repeated = true;
-      }
-      if (repeated) part += `:nth-of-type(${index})`;
+      const { position, repeated } = siblingPosition(current, index);
+      if (repeated) part += `:nth-of-type(${position})`;
     }
     parts.unshift(part);
     if (current.parentElement && uniqueId(current.parentElement)) {
@@ -152,7 +212,7 @@ export function isEmbeddedDocument(doc) {
  * presence is what counts, whatever the value.
  */
 export function isInert(element) {
-  for (let node = element; node; node = node.parentElement ?? node.getRootNode?.()?.host ?? null) {
+  for (let node = element; node; node = flatTreeParent(node)) {
     if (node.nodeType === 1 && node.hasAttribute('inert')) return true;
   }
   return false;

package/engine/lib/roles.js

@@ -1,6 +1,7 @@
 // ARIA 1.2 role model: implicit roles for HTML elements, and which aria-*
 // attributes each role supports (flattened with inheritance). Attribute
 // names are stored without the "aria-" prefix.
+import { isInert } from './dom.js';
 
 /** Every attribute name in the ARIA 1.2 vocabulary (without the prefix).
  *  aria-attr-valid judges membership; aria-allowed-attr judges role fit —
@@ -208,22 +209,36 @@ 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') || isInert(element)) 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) {
   const explicit = element.getAttribute('role')?.trim().split(/\s+/) ?? [];
   for (const token of explicit) {
     const role = token.toLowerCase();
+    if (role === 'image') return 'img'; // supported synonym for the image role
     if (!ROLE_ARIA[role]) continue;
     if ((role === 'presentation' || role === 'none') && presentationDiscarded(element)) {
       return implicitRole(element);
     }
     return role;
   }
-  return explicit.length ? null : implicitRole(element); // unknown explicit role: don't judge
+  // ARIA 9.1: unrecognized tokens leave native semantics intact.
+  return implicitRole(element);
 }

package/engine/rules/best-practice/fieldset-legend.js

@@ -12,13 +12,19 @@ export default {
   // Judged as a set: only same-name groups of 2+ need grouping, and one
   // finding per group is enough.
   evaluateAll(elements) {
-    const groups = {};
+    const groups = new Map();
     elements.forEach((element, index) => {
-      const key = `${element.type}::${element.form?.id ?? ''}::${element.name}`;
-      (groups[key] ??= []).push(index);
+      // Form identity matters: two idless forms can use the same field name
+      // without making one group. Group controls within their own tree too.
+      const owner = element.form ?? element.getRootNode();
+      if (!groups.has(owner)) groups.set(owner, new Map());
+      const byName = groups.get(owner);
+      const key = `${element.type}::${element.name}`;
+      if (!byName.has(key)) byName.set(key, []);
+      byName.get(key).push(index);
     });
     const outcomes = elements.map(() => ({ status: 'pass' }));
-    for (const indexes of Object.values(groups)) {
+    for (const indexes of [...groups.values()].flatMap((byName) => [...byName.values()])) {
       if (indexes.length < 2) continue;
       const first = elements[indexes[0]];
       // A <fieldset> IS a group; it does not need role="group" written on it
@@ -35,7 +41,7 @@ export default {
       // it empty (2026-08-25 overnight audit).
       const group = first.closest('fieldset, [role="group"], [role="radiogroup"]');
       const legend = group?.querySelector(':scope > legend');
-      const grouped = group && (
+      const grouped = group && indexes.every((index) => group.contains(elements[index])) && (
         (legend && accessibleName(legend))
         || labelledByName(group)
         || group.getAttribute('aria-label')?.trim()

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.1.1-area-alt.js

@@ -8,7 +8,12 @@ export default {
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
   selector: 'map area[href]',
   visibleOnly: false,
-  evaluate(element, { accessibleName }) {
+  evaluate(element, { accessibleName, isVisible }) {
+    const map = element.closest('map');
+    const images = [...element.getRootNode().querySelectorAll('img[usemap], object[usemap]')];
+    const active = map?.name && images.some((image) =>
+      image.getAttribute('usemap') === `#${map.name}` && isVisible(image));
+    if (!active) return { status: 'pass' };
     if (accessibleName(element)) return { status: 'pass' };
     return {
       status: 'fail',

package/engine/rules/wcag/1.1.1-image-alt.js

@@ -11,6 +11,7 @@
 // nothing (F30/F39) — flagged for eyes.
 const FILENAME_ALT = /\.(png|jpe?g|gif|webp|svg|avif|bmp|ico)([?#].*)?$/i;
 const GENERIC_ALT = /^(image|img|photo|photograph|picture|graphic|icon|untitled|placeholder|spacer|\d+)$/i;
+import { effectiveRole } from '../../lib/roles.js';
 
 export default {
   id: 'image-alt',
@@ -21,7 +22,7 @@ export default {
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html',
   selector: 'img',
   evaluate(element, { accessibleName }) {
-    const role = element.getAttribute('role');
+    const role = effectiveRole(element);
     if (role === 'presentation' || role === 'none') return { status: 'pass' };
     if (element.hasAttribute('alt')) {
       const alt = element.getAttribute('alt');

package/engine/rules/wcag/1.1.1-svg-img-alt.js

@@ -1,5 +1,6 @@
 // WCAG SC 1.1.1 Non-text Content (Level A)
 import { labelledByName } from '../../lib/accessible-name.js';
+import { effectiveRole } from '../../lib/roles.js';
 
 export default {
   id: 'svg-img-alt',
@@ -11,24 +12,20 @@ export default {
   // <img> itself is handled by image-alt; this covers SVG (with or without a
   // role) and role="img" divs/spans. Top-level plain <svg> is included
   // because browsers expose it to AT as a graphic even without a role.
-  selector: 'svg[role="img"], svg[role="graphics-document"], svg[role="graphics-symbol"], [role="img"]:not(img):not(svg), svg:not([role])',
+  selector: 'svg, [role]',
   evaluate(element, { accessibleName }) {
-    // A non-svg role="img" host names from author only, and the role makes
-    // its subtree presentational (ARIA: children presentational) — so a
-    // descendant <svg><title> or text content never reaches AT as a name,
-    // even though a generic contents walk would find it.
-    if (element.tagName.toLowerCase() !== 'svg' && element.getAttribute('role') === 'img') {
-      const authorName = labelledByName(element)
-        || element.getAttribute('aria-label')?.trim()
-        || element.getAttribute('title')?.trim();
-      if (authorName) return { status: 'pass' };
-      return {
-        status: 'fail',
-        message: 'This element is marked as an image but has no accessible name — for role="img", content inside it (including an inner SVG’s <title>) does not count as a name.',
-        fix: 'Add aria-label="…" or aria-labelledby pointing at visible text.',
-      };
-    }
-    if (accessibleName(element)) return { status: 'pass' };
+    if (element.tagName === 'IMG') return { status: 'pass' }; // image-alt owns native images
+    const svg = element.tagName.toLowerCase() === 'svg';
+    const explicitGraphic = effectiveRole(element) === 'img'
+      || ['graphics-document', 'graphics-symbol'].includes(element.getAttribute('role')?.trim());
+    if (!svg && !explicitGraphic) return { status: 'pass' };
+    if (svg && element.hasAttribute('role') && !explicitGraphic) return { status: 'pass' };
+    // Graphic roles name from author, not arbitrary descendant text.
+    // SVG adds its own direct title as a native naming source.
+    const nativeTitle = svg && [...element.children].find((child) => child.tagName.toLowerCase() === 'title');
+    const name = labelledByName(element) || element.getAttribute('aria-label')?.trim()
+      || (nativeTitle && accessibleName(nativeTitle)) || element.getAttribute('title')?.trim();
+    if (name) return { status: 'pass' };
     if (!element.getAttribute('role') && element.tagName.toLowerCase() === 'svg') {
       if (element.parentNode instanceof SVGElement) return { status: 'pass' }; // nested svg: part of the outer graphic
       // Inside a control that already has a name, the svg is effectively

package/engine/rules/wcag/1.3.1-aria-required-children.js

@@ -1,7 +1,7 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
 // Composite roles are meaningless without their required child roles —
 // role="list" with no listitems announces as an empty list.
-import { implicitRole } from '../../lib/roles.js';
+import { effectiveRole } from '../../lib/roles.js';
 // Every row of ARIA 1.2's Required Owned Elements table; verify:aria-tables
 // diffs this map against the spec (2026-09-01, after feed and row were
 // found missing).
@@ -21,9 +21,7 @@ export const REQUIRED_CHILDREN = {
   rowgroup: ['row'],
 };
 
-const roleOf = (element) =>
-  element.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ??
-  implicitRole(element);
+const roleOf = effectiveRole;
 
 /**
  * Every element in the COMPOSED subtree of `element`: its light-DOM
@@ -88,6 +86,19 @@ function candidateDescendants(element) {
   return found;
 }
 
+function exposedChild(element, isVisible) {
+  if (isVisible(element)) return true;
+  // A collapsed native select still exposes its options through the
+  // platform accessibility API, although those options have no CSS boxes.
+  // Chromium also retains individually hidden options in that native popup
+  // tree. Only the select's exposure gates this narrow native exception;
+  // applying CSS-box visibility to its options would assert an empty widget
+  // even while the browser exposes its choices.
+  if (element.tagName !== 'OPTION') return false;
+  const select = element.closest('select');
+  return !!select && isVisible(select);
+}
+
 export default {
   id: 'aria-required-children',
   name: 'Required ARIA children',
@@ -95,17 +106,18 @@ export default {
   tags: ['wcag2a', 'wcag131'],
   help: 'Composite ARIA roles must contain their required children',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
-  selector: Object.keys(REQUIRED_CHILDREN).map((role) => `[role="${role}"]`).join(', '),
-  evaluate(element) {
+  selector: '[role]',
+  evaluate(element, { isVisible }) {
     if (element.getAttribute('aria-busy') === 'true') return { status: 'pass' }; // still loading
-    const role = element.getAttribute('role').trim().split(/\s+/)[0].toLowerCase();
+    const role = effectiveRole(element);
     const required = REQUIRED_CHILDREN[role];
+    if (!required) return { status: 'pass' };
     const children = [...element.children, ...(element.shadowRoot?.children ?? [])]
       .filter((c) => !c.matches('script, style, template'));
     // A completely empty container is a lazy-load placeholder more often
     // than a defect — it announces as an empty list, which is accurate.
     if (!children.length && !element.hasAttribute('aria-owns')) return { status: 'pass' };
-    if (candidateDescendants(element).some((child) => required.includes(roleOf(child)))) {
+    if (candidateDescendants(element).some((child) => required.includes(roleOf(child)) && exposedChild(child, isVisible))) {
       return { status: 'pass' };
     }
     return {

package/engine/rules/wcag/1.3.1-aria-required-parent.js

@@ -1,5 +1,6 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
 // Child roles that only make sense inside a specific container role.
+import { effectiveRole } from '../../lib/roles.js';
 // Explicit roles only — native elements (li outside ul) are covered by
 // listitem-parent/dlitem-parent.
 //
@@ -33,7 +34,6 @@ export const REQUIRED_PARENT = {
   gridcell: ['row'],
 };
 
-const IMPLICIT_CONTAINER = { ul: 'list', ol: 'list', menu: 'list', table: 'table', tbody: 'rowgroup', thead: 'rowgroup', tfoot: 'rowgroup', tr: 'row', figure: 'figure' };
 
 export default {
   id: 'aria-required-parent',
@@ -42,10 +42,11 @@ export default {
   tags: ['wcag2a', 'wcag131'],
   help: 'ARIA child roles must be inside their required container role',
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html',
-  selector: Object.keys(REQUIRED_PARENT).map((role) => `[role="${role}"]`).join(', '),
+  selector: '[role]',
   evaluate(element) {
-    const role = element.getAttribute('role').trim().split(/\s+/)[0].toLowerCase();
+    const role = effectiveRole(element);
     const containers = REQUIRED_PARENT[role];
+    if (!containers) return { status: 'pass' };
     // The container named in the message and fix: the structure's root, not
     // the group that may sit between it and the item.
     const named = containers.filter((container) => container !== 'group');
@@ -54,9 +55,7 @@ export default {
     // Judging by DOM ancestry alone failed every remotely-owned child.
     if (element.id) {
       const owner = element.getRootNode().querySelector?.(`[aria-owns~="${CSS.escape(element.id)}"]`);
-      const ownerRole = owner && (
-        owner.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase()
-        ?? IMPLICIT_CONTAINER[owner.tagName.toLowerCase()]);
+      const ownerRole = owner && effectiveRole(owner);
       if (ownerRole && containers.includes(ownerRole)) return { status: 'pass' };
     }
     // FLAT-TREE ancestry, not light-DOM ancestry: assistive technology sees
@@ -72,9 +71,7 @@ export default {
     for (let parent = flatParent(element); parent; parent = flatParent(parent)) {
       // A <slot> is rendering plumbing with no tree presence of its own.
       if (parent.tagName === 'SLOT' && !parent.hasAttribute('role')) continue;
-      const parentRole =
-        parent.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ??
-        IMPLICIT_CONTAINER[parent.tagName.toLowerCase()];
+      const parentRole = effectiveRole(parent);
       // A permitted context (the structure's root, or a group for the roles
       // whose ARIA context lists it) satisfies the requirement outright.
       if (containers.includes(parentRole)) return { status: 'pass' };
@@ -83,7 +80,7 @@ export default {
       // children owned by the next real ancestor — li[role=presentation]
       // between a tablist and its tabs is the canonical pattern.
       if (parentRole === 'presentation' || parentRole === 'none') continue;
-      if (parentRole) break; // a different role interrupts the required structure
+      if (parentRole && parentRole !== 'generic') break; // a different role interrupts the required structure
     }
     return {
       status: 'fail',

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

@@ -2,7 +2,8 @@
 // Instructions (Level A) · SC 4.1.2 Name, Role, Value (Level A)
 // 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 { labelledByName, nativeLabelName } 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.
@@ -22,34 +29,10 @@ export default {
       const style = getComputedStyle(label);
       return style.display !== 'none' && style.visibility !== 'hidden';
     });
-    // 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.
-    //
-    // An UNRENDERED descendant is excluded the same way: accname step 2A
-    // returns the empty string for a hidden node that is not the root of
-    // the label traversal, and hidden covers display:none and
-    // visibility:hidden (the hidden attribute is display:none). A label
-    // whose only text sits in a display:none span names nothing (Chromium
-    // computes ""), the mirror of the aria-hidden twin above (2026-08-25
-    // overnight audit). Computed style rather than checkVisibility: an SVG
-    // <title> has no box yet still names its graphic.
-    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 nodeStyle = getComputedStyle(node);
-      if (nodeStyle.display === 'none' || nodeStyle.visibility === 'hidden') 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();
+    // Share the recursive native-label computation with other name rules,
+    // including generated text and image alternatives. Exclude this field
+    // from its wrapping label's traversal to avoid self-naming cycles.
+    const labelsText = visibleLabels.map((label) => nativeLabelName(element, label)).join(' ').trim();
     const ariaLabel = element.getAttribute('aria-label')?.trim();
     const labelledby = labelledByName(element);
     if (labelsText || ariaLabel || labelledby) return { status: 'pass' };

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

@@ -1,5 +1,6 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
 import { NEVER_RENDERED } from '../../lib/dom.js';
+import { effectiveRole } from '../../lib/roles.js';
 
 const ITEM_ROLES = ['listitem', 'presentation', 'none'];
 
@@ -14,7 +15,7 @@ export default {
   evaluate(element, { isRendered }) {
     // A role attribute replaces the HTML list semantics — a <ul role="tablist">
     // is judged by ARIA structure rules, not HTML list rules.
-    if (element.hasAttribute('role') && element.getAttribute('role') !== 'list') return { status: 'pass' };
+    if (effectiveRole(element) !== 'list') return { status: 'pass' };
     // Flat-tree children: a <slot> renders as its assigned elements (or its
     // fallback content), so a shadow <ul><slot></slot></ul> receiving <li>s
     // is a perfectly valid list.
@@ -39,7 +40,7 @@ export default {
       // listitems, so the list announces broken/empty. Only a role-less
       // <li> (or an explicit listitem/presentation/none anywhere) keeps
       // the structure intact.
-      const role = child.getAttribute('role') ?? '';
+      const role = effectiveRole(child);
       if (child.tagName === 'LI') return !role || ITEM_ROLES.includes(role);
       if (ITEM_ROLES.includes(role)) return true;
       const genericWrapper = !child.hasAttribute('role')
@@ -62,7 +63,7 @@ export default {
       const renderedItems = effectiveChildren(element).filter((child) =>
         child.tagName === 'LI' && (!isRendered || isRendered(child)));
       const neutralised = renderedItems.filter((child) =>
-        ['presentation', 'none'].includes(child.getAttribute('role') ?? ''));
+        ['presentation', 'none'].includes(effectiveRole(child)));
       if (renderedItems.length && neutralised.length === renderedItems.length) {
         return {
           status: 'fail',