pour-engine 1.40.0 → 1.42.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 —
@@ -222,7 +223,7 @@ 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.matches(':disabled') || isInert(element)) return false;
   if (element.tabIndex >= 0) return true;
   return element.matches('a[href], button, input, select, textarea, summary, [contenteditable="true"]');
 }
@@ -231,11 +232,13 @@ 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/region.js

@@ -9,7 +9,7 @@
 // showing one (the open attribute is set by show() and showModal()) counts,
 // so a closed dialog cannot make a landmark-less page look landmarked
 // (2026-08-25 overnight audit).
-const LANDMARK =
+export const LANDMARK =
   'main, nav, aside, search, form[aria-label], form[aria-labelledby], ' +
   'header:not(:is(article, aside, main, nav, section) header), ' +
   'footer:not(:is(article, aside, main, nav, section) footer), ' +

package/engine/rules/index.js

@@ -109,6 +109,25 @@ import onInputNavigation from './wcag/3.2.2-on-input-navigation.js';
 import errorMessageLinkage from './wcag/3.3.1-error-message-linkage.js';
 import compositeWidgetName from './wcag/4.1.2-composite-widget-name.js';
 import summaryName from './wcag/4.1.2-summary-name.js';
+// 2026-09-12 manual-to-partial batch (reports/coverage-gaps/2026-09-12): the
+// slices of twelve criteria that had no rule where the DOM shows a real
+// candidate. Two AAA siblings built from existing factories (a timed refresh
+// with no 20-hour allowance, any overlap of a focused element); eight
+// review questions on declared facts (a video without a descriptions
+// track, a declared <section> with no heading, a touch-action surface, a
+// payment form, a CAPTCHA beside a credential, a page with no landmarks,
+// justified running text) and one assert on template text left in a
+// heading or label. Two assert, the rest ask.
+import metaRefreshNoExceptions from './wcag/2.2.4-meta-refresh-no-exceptions.js';
+import focusNotObscuredEnhanced from './wcag/2.4.12-focus-not-obscured-enhanced.js';
+import videoAudioDescription from './wcag/1.2.3-video-audio-description.js';
+import headingLabelPlaceholder from './wcag/2.4.6-heading-label-placeholder.js';
+import textJustified from './wcag/1.4.8-text-justified.js';
+import sectionHeading from './wcag/2.4.10-section-heading.js';
+import captchaAlternative from './wcag/3.3.9-captcha-alternative.js';
+import regionPurpose from './wcag/1.3.6-region-purpose.js';
+import financialFormConfirmation from './wcag/3.3.4-financial-form-confirmation.js';
+import pointerGestureAlternative from './wcag/2.5.1-pointer-gesture-alternative.js';
 
 // --- Best practice ---
 import headingOrder from './best-practice/heading-order.js';
@@ -210,6 +229,16 @@ export default [
   errorMessageLinkage,
   compositeWidgetName,
   summaryName,
+  metaRefreshNoExceptions,
+  focusNotObscuredEnhanced,
+  videoAudioDescription,
+  headingLabelPlaceholder,
+  textJustified,
+  sectionHeading,
+  captchaAlternative,
+  regionPurpose,
+  financialFormConfirmation,
+  pointerGestureAlternative,
   contrastEnhanced,
   targetSizeEnhanced,
   headingOrder,

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.2.3-video-audio-description.js

@@ -0,0 +1,42 @@
+// WCAG SC 1.2.3 Audio Description or Media Alternative (Prerecorded)
+// (Level A) and SC 1.2.5 Audio Description (Prerecorded) (Level AA)
+//
+// Prerecorded video in synchronized media needs audio description of the
+// visual track (1.2.5), or at Level A alternatively a full text alternative
+// for the media (1.2.3). Whether either exists is not decidable from the
+// DOM: description can be a second audio track chosen in the player, a
+// separately produced version, narration mixed into the soundtrack, or a
+// transcript beside the player. And the Understanding of 1.2.5 says no
+// description is needed when the soundtrack already carries every
+// important thing the picture shows (a talking head). So this rule never
+// asserts. It asks, once per video that can actually present sound to
+// someone, and stays silent where the page shows the one thing the DOM can
+// show: a <track kind="descriptions"> (technique H96).
+//
+// Same media gating as media-captions, for the same reasons: no resource
+// means nothing is presented, and muted-with-no-controls is the decorative
+// loop nobody can hear, which is not synchronized media for a viewer.
+// Video-only files (no audio stream at all) are 1.2.1 territory and not
+// visible from the DOM either; the message says so.
+export default {
+  id: 'video-audio-description',
+  name: 'Video audio description',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag123', 'wcag125'],
+  help: 'Video content needs audio description or a text alternative',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/audio-description-prerecorded.html',
+  selector: 'video',
+  visibleOnly: false,
+  evaluate(element) {
+    if (element.querySelector('track[kind="descriptions" i]')) return { status: 'pass' };
+    if (!element.currentSrc && !element.getAttribute('src') && !element.querySelector('source')) {
+      return { status: 'pass' };
+    }
+    if (element.muted && !element.controls) return { status: 'pass' };
+    return {
+      status: 'incomplete',
+      message: 'This video has no audio-description track. If it shows something its soundtrack does not say (text on screen, actions, charts, who is speaking), blind and low-vision users miss it. 1.2.5 asks for audio description; at Level A, 1.2.3 is also met by a full text alternative describing the visuals, linked near the player. A talking-head video whose soundtrack already carries everything needs neither, and a video with no soundtrack at all is 1.2.1\'s question instead: check which this is, and where the description or alternative lives.',
+      fix: 'Provide a described audio track or a described version of the video (a <track kind="descriptions"> file works for text-based description), or publish a full transcript that describes the visuals next to the player.',
+    };
+  },
+};

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-form-label.js

@@ -2,7 +2,7 @@
 // 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 {
@@ -29,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',

package/engine/rules/wcag/1.3.1-table-headers.js

@@ -65,7 +65,7 @@ export default {
       const headers = cell.getAttribute('headers');
       return headers && headers.trim().split(/\s+/).filter(Boolean).some((id) => {
         const target = element.getRootNode().getElementById?.(id);
-        return !target || !cells.includes(target) || !(/^T[HD]$/.test(target.tagName) || isHeaderCell(target));
+        return !target || !cells.includes(target) || !isHeaderCell(target);
       });
     });
     if (badRefs.length) {
@@ -84,13 +84,34 @@ export default {
           message: 'This table has no header cells and its cells hold block content (headings, paragraphs, lists or forms), which is a layout-table signature. If it really presents data, mark its header cells with <th>; if it is layout scaffolding, add role="presentation".',
         };
       }
+      // A grid whose every filled cell is nothing but a link or a button is a
+      // navigation block laid out as a table, not data with labels: asked,
+      // not asserted (2026-09-12).
+      const filled = cells.filter((cell) => cell.textContent.trim());
+      const navigational = filled.every((cell) => {
+        const controls = [...cell.querySelectorAll('a, button')];
+        return controls.length
+          && controls.map((control) => control.textContent.trim()).join(' ').replace(/\s+/g, ' ')
+            === cell.textContent.trim().replace(/\s+/g, ' ');
+      });
+      if (navigational) {
+        return {
+          status: 'incomplete',
+          message: 'This table has no header cells and every cell holds only a link or a button, which is the shape of a navigation block laid out as a table. If it presents data, mark its header cells with <th>; if it is layout, add role="presentation".',
+        };
+      }
+      // Everything that remains is a grid of at least four short text cells
+      // with no nested table, no block content and no layout role: a data
+      // table by every signal the markup gives, which is the determination
+      // F91 asks for before it applies. Asserted, as the shipped engine
+      // asserted it; the message says what to do if it is layout after all.
       // A two-column table is a list of label-and-value pairs; its first
       // column is the row headers, and that is the whole fix (gov.uk
       // inheritance tax guidance, 2026-09-01: five such tables, all td).
       const twoColumns = Math.max(0, ...rows.map((row) => row.cells.length)) === 2;
       return {
         status: 'fail',
-        message: 'This looks like a data table but has no header cells — screen reader users get the data with no way to tell what each row/column means.',
+        message: 'This looks like a data table but has no header cells, so screen reader users get the data with no way to tell what each row or column means. If it only arranges content, mark it role="presentation" and dismiss this finding.',
         fix: twoColumns
           ? 'Mark the first cell of each row as <th scope="row">: in a two-column table the first column names what the second holds.'
           : 'Mark header cells with <th> (add scope="col" or scope="row" when the table has both).',