pour-engine 1.40.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 —
@@ -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/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-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).',