pour-engine 1.32.0 → 1.34.0

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

@@ -1,6 +1,6 @@
 // WAI forms tutorial: radio/checkbox groups need a group label — each
 // input's own label isn't enough to convey what the group asks.
-import { labelledByName } from '../../lib/accessible-name.js';
+import { accessibleName, labelledByName } from '../../lib/accessible-name.js';
 export default {
   id: 'fieldset-legend',
   name: 'Grouped field labels',
@@ -29,9 +29,14 @@ export default {
       // a reference, or a label. Not a general accessible-name call, which
       // would fall through to name-from-contents and read the options inside
       // the fieldset as if they were its name.
+      // The legend itself IS named by the accessible-name computation: a
+      // legend holding an <img alt="Choose a colour"> names the group (the
+      // browser exposes group "Choose a colour"), and raw textContent called
+      // 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 && (
-        group.querySelector(':scope > legend')?.textContent.trim()
+        (legend && accessibleName(legend))
         || labelledByName(group)
         || group.getAttribute('aria-label')?.trim()
       );

package/engine/rules/best-practice/heading-order.js

@@ -1,6 +1,7 @@
 import { effectiveRole } from '../../lib/roles.js';
 
-const level = (el) =>
+// Shared with page-heading-one so both rules agree on what level 1 is.
+export const level = (el) =>
   el.hasAttribute('aria-level')
     ? parseInt(el.getAttribute('aria-level'), 10)
     : parseInt(el.tagName[1], 10) || 2; // role="heading" without aria-level defaults to 2

package/engine/rules/best-practice/landmark-top-level.js

@@ -9,6 +9,15 @@ const LANDMARK_ROLES = new Set([
   'main', 'navigation', 'banner', 'contentinfo', 'complementary', 'region', 'search', 'form',
 ]);
 
+/** HTML-AAM (form, section): "If a form has no accessible name, do not
+ *  expose the element as a landmark", and a section is a region only with
+ *  an accessible name. An unnamed page-wrapping <form> (the WebForms
+ *  form runat="server" shape) is therefore no landmark container at all,
+ *  and the banner, main and contentinfo inside it are top level. Mirrors
+ *  region.js, decided locally here (2026-08-25 overnight audit). */
+const named = (element) =>
+  element.hasAttribute('aria-label') || element.hasAttribute('aria-labelledby') || element.hasAttribute('title');
+
 /** The nearest ancestor that is a landmark in the accessibility tree —
  *  explicit role OR implicit (nav, labelled section/form, top-level
  *  header/footer). A selector can't express the implicit cases; a
@@ -18,6 +27,7 @@ function landmarkAncestor(element) {
   for (let parent = element.parentElement; parent; parent = parent.parentElement) {
     const explicit = parent.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase();
     const role = explicit ?? implicitRole(parent);
+    if (!explicit && (role === 'form' || role === 'region') && !named(parent)) continue;
     if (role && LANDMARK_ROLES.has(role)) return { element: parent, role };
   }
   return null;

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

@@ -6,6 +6,14 @@ import { labelledByName } from '../../lib/accessible-name.js';
 
 const SINGLETON = new Set(['banner', 'contentinfo', 'main']);
 
+// ARIA 1.2, Landmark Roles: the eight roles that are landmarks. An explicit
+// non-landmark role on a landmark element (<nav role="menubar">) makes it a
+// widget, not a landmark, so it has nothing to be distinguished from
+// (2026-08-25 overnight audit).
+const LANDMARK_ROLES = new Set([
+  'banner', 'complementary', 'contentinfo', 'form', 'main', 'navigation', 'region', 'search',
+]);
+
 /** Landmark role of the element in the accessibility tree — explicit role
  *  first, else the implicit role (which handles header/footer demotion
  *  inside sectioning content and unlabelled sections being generic). */
@@ -39,7 +47,7 @@ export default {
     const outcomes = elements.map(() => ({ status: 'pass' }));
     const landmarkIndexes = elements
       .map((element, index) => ({ element, index, role: roles[index] }))
-      .filter(({ role }) => role && role !== 'generic' && role !== 'presentation' && role !== 'none');
+      .filter(({ role }) => LANDMARK_ROLES.has(role));
 
     // Singleton roles: more than one banner/contentinfo/main is a failure
     // regardless of labels.

package/engine/rules/best-practice/new-window-link.js

@@ -2,6 +2,27 @@
 // users who can't see the window change. Heuristic is English-only for now.
 const MENTIONS_NEW_WINDOW = /new (window|tab)|opens? in/i;
 
+/** The nearest declared language. An undeclared language is judged as
+ *  English (html-lang reports the missing declaration itself). */
+function effectiveLang(element) {
+  return element.closest('[lang]')?.getAttribute('lang')?.trim()
+    || element.ownerDocument.documentElement.getAttribute('lang')?.trim()
+    || '';
+}
+
+/** G201 asks only that a warning is "spoken in assistive technology"; its
+ *  own second example delivers it through aria-describedby, so the
+ *  description joins the text tested. Targets are read hidden or not, the
+ *  way the description computation reads them (2026-08-25 overnight audit). */
+function describedByText(element) {
+  const refs = element.getAttribute('aria-describedby');
+  if (!refs) return '';
+  const root = element.getRootNode();
+  return refs.split(/\s+/).filter(Boolean)
+    .map((id) => root.getElementById?.(id)?.textContent ?? '')
+    .join(' ');
+}
+
 export default {
   id: 'new-window-link',
   name: 'New-window warnings',
@@ -11,8 +32,20 @@ export default {
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Techniques/general/G201',
   selector: 'a[target="_blank"], a[target="blank"]',
   evaluate(element, { accessibleName }) {
-    const name = `${accessibleName(element)} ${element.getAttribute('title') ?? ''}`;
+    const name = `${accessibleName(element)} ${element.getAttribute('title') ?? ''} ${describedByText(element)}`;
     if (MENTIONS_NEW_WINDOW.test(name)) return { status: 'pass' };
+    // The wording test reads English only. In another language the DOM
+    // cannot prove the warning is missing ("nouvelle fenêtre" satisfies
+    // G201 just as well), so the verdict is a question, not a failure
+    // (2026-08-25 overnight audit).
+    const lang = effectiveLang(element);
+    if (lang && !/^en(?:[-_]|$)/i.test(lang)) {
+      return {
+        status: 'incomplete',
+        message: `This link opens a new window or tab. Does its name, title or description say so in the page's language ("${lang}")? The automated wording check reads English only.`,
+        fix: 'Say so in the link text or a visually hidden span (for example the local-language equivalent of "opens in new window"), or drop target="_blank".',
+      };
+    }
     return {
       status: 'fail',
       message: 'This link opens a new window/tab without saying so — the back button stops working and screen-reader users get no warning about the context change.',

package/engine/rules/best-practice/no-autofocus.js

@@ -1,3 +1,13 @@
+// Inside a dialog or popover the attribute never acts on page load: the HTML
+// dialog focusing steps pick the autofocus descendant as the control to
+// focus when the dialog is SHOWN, and the spec's own note tells authors to
+// put autofocus on exactly that element (or on the dialog itself when there
+// is none). Outside those containers the spec's caution ("use careful
+// consideration") is real, but its own example of a page whose main purpose
+// IS the control is legitimate use, so the DOM cannot prove a failure: the
+// verdict is a review question (2026-08-25 overnight audit).
+const FOCUS_CONTAINER = 'dialog, [role="dialog"], [role="alertdialog"], [popover]';
+
 export default {
   id: 'no-autofocus',
   name: 'Autofocus on load',
@@ -8,10 +18,12 @@ export default {
   selector: '[autofocus]',
   visibleOnly: false,
   evaluate(element) {
+    if (element.closest(FOCUS_CONTAINER)) return { status: 'pass' };
+    const tag = element.tagName.toLowerCase();
     return {
-      status: 'fail',
-      message: 'autofocus jumps focus past the page start — screen-reader and magnifier users lose all the context before this element.',
-      fix: `Remove autofocus from the <${element.tagName.toLowerCase()}>; let users reach it in document order.`,
+      status: 'incomplete',
+      message: `autofocus moves focus to this <${tag}> as soon as the page loads, so screen-reader and magnifier users skip everything before it. Review: the HTML spec allows this only when the control is the page's main purpose (a search box on a search page, say); otherwise it disorients.`,
+      fix: `Remove autofocus from the <${tag}> unless this control is the page's whole purpose; let users reach it in document order.`,
     };
   },
 };

package/engine/rules/best-practice/page-heading-one.js

@@ -1,3 +1,15 @@
+import { collectRoots } from '../../lib/dom.js';
+import { level } from './heading-order.js';
+
+// The outline is what the accessibility tree builds: it spans every open
+// shadow root (a web-component shell whose only h1 renders in its shadow
+// tree HAS an h1, exactly as landmark-one-main counts mains), and a
+// heading's level is aria-level when set, else the tag's own digit, on any
+// h1-h6 or role="heading". heading-order's level helper decides both rules,
+// so <h2 aria-level="1"> starts the outline and <h1 aria-level="2"> does
+// not (2026-08-25 overnight audit).
+const HEADING = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
+
 export default {
   id: 'page-heading-one',
   name: 'Leading page heading',
@@ -8,7 +20,9 @@ export default {
   selector: 'html',
   visibleOnly: false,
   evaluate(element) {
-    if (element.ownerDocument.querySelector('h1, [role="heading"][aria-level="1"]')) return { status: 'pass' };
+    const hasLevelOne = collectRoots(element.ownerDocument)
+      .some((root) => [...root.querySelectorAll(HEADING)].some((heading) => level(heading) === 1));
+    if (hasLevelOne) return { status: 'pass' };
     return {
       status: 'fail',
       message: 'No <h1> — the page outline has no starting point for screen-reader navigation.',

package/engine/rules/best-practice/redundant-alt-phrase.js

@@ -1,7 +1,15 @@
 // "photo of"/"photograph of" is deliberately NOT flagged: for portraits it
 // conveys the medium (a photo of a person vs. a logo or illustration),
 // which is widely accepted alt style — flagging it is noise.
-const REDUNDANT_PHRASE = /^(image|picture|graphic|icon)\b( of\b)?/i;
+//
+// The tip this rule cites (WAI images tutorial) is about announcing the
+// MEDIUM, so only the prefix shape counts: the word followed by "of", a
+// colon, a hyphen, "showing"/"depicting", or the word alone as the whole
+// alt. "Graphic design services" and "Picture frame, oak" are content, and
+// stripping their first word destroys the meaning; "graphic" and "picture"
+// are common nouns, so they count only with "of" (2026-08-25 overnight audit).
+const REDUNDANT_PHRASE =
+  /^(?:(?:image|icon)s?(?:\s*[:-]\s*|\s+(?:of|showing|depicting)\b\s*|\s*$)|(?:picture|graphic)s?\s+of\b\s*)/i;
 
 export default {
   id: 'redundant-alt-phrase',

package/engine/rules/best-practice/redundant-aria-label.js

@@ -9,6 +9,29 @@ const NAME_FROM_CONTENT = new Set(['button', 'link', 'menuitem', 'menuitemcheckb
   'menuitemradio', 'option', 'tab', 'treeitem', 'checkbox', 'radio', 'switch', 'heading',
   'cell', 'gridcell', 'columnheader', 'rowheader', 'tooltip']);
 
+const EMPTY_CONTENT = new Set(['none', 'normal', '""', "''"]);
+
+/** Name-from-content is not textContent. accname 2F adds ::before/::after
+ *  text, image alternatives and svg titles, and drops hidden subtrees; when
+ *  any of those sit inside the element, the aria-label is what keeps the
+ *  announced name clean (an icon-font glyph before "Menu" would otherwise
+ *  be spoken as part of the name), so it is not redundant. Only computed
+ *  for elements whose label already matched their text, so the per-element
+ *  style reads stay bounded to real candidates (2026-08-25 overnight audit). */
+function contentBeyondText(element) {
+  const nodes = [element, ...element.querySelectorAll('*')];
+  for (const node of nodes) {
+    const tag = node.tagName.toLowerCase();
+    if (tag === 'img' || tag === 'area' || tag === 'svg') return true;
+    if (node !== element && (node.getAttribute('aria-hidden') === 'true' || node.hasAttribute('hidden'))) return true;
+    const style = getComputedStyle(node);
+    if (node !== element && (style.display === 'none' || style.visibility === 'hidden')) return true;
+    if (!EMPTY_CONTENT.has(getComputedStyle(node, '::before').content)) return true;
+    if (!EMPTY_CONTENT.has(getComputedStyle(node, '::after').content)) return true;
+  }
+  return false;
+}
+
 export default {
   id: 'redundant-aria-label',
   name: 'Redundant aria-label',
@@ -22,6 +45,7 @@ export default {
     const label = element.getAttribute('aria-label').replace(/\s+/g, ' ').trim().toLowerCase();
     const visible = element.textContent.replace(/\s+/g, ' ').trim().toLowerCase();
     if (!visible || label !== visible) return { status: 'pass' };
+    if (contentBeyondText(element)) return { status: 'pass' };
     return {
       status: 'fail',
       message: `aria-label="${element.getAttribute('aria-label')}" is identical to the element's visible text — it adds nothing and will drift out of sync when the text changes.`,

package/engine/rules/best-practice/redundant-role.js

@@ -1,29 +1,76 @@
 // "Overdoing it" family: explicit role attributes that duplicate the
 // element's built-in (implicit) ARIA role are noise — they add maintenance
 // risk without helping assistive technology.
-const IMPLICIT_ROLES = {
-  ul: 'list', ol: 'list', li: 'listitem',
-  button: 'button', nav: 'navigation', main: 'main', aside: 'complementary',
-  form: 'form', table: 'table', article: 'article', img: 'img', hr: 'separator',
-  progress: 'progressbar', textarea: 'textbox', dialog: 'dialog', option: 'option',
-  h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading',
+//
+// The implicit role comes from lib/roles.js, not a private table: the
+// contextual cases (an unnamed aside inside sectioning content is generic,
+// so role="complementary" on it is the ONLY thing making it a landmark) are
+// modelled there and verified against Chromium. The set of elements judged
+// stays as it was, so nothing new is asserted (2026-08-25 overnight audit).
+import { implicitRole as modelledRole } from '../../lib/roles.js';
+
+const JUDGED_TAGS = new Set([
+  'ul', 'ol', 'li', 'button', 'nav', 'main', 'aside', 'form', 'table', 'article', 'img', 'hr',
+  'progress', 'textarea', 'dialog', 'option', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
   // Table structure (th is skipped: its implicit role is contextual —
   // columnheader or rowheader). header/footer/section are contextual too.
-  tr: 'row', thead: 'rowgroup', tbody: 'rowgroup', tfoot: 'rowgroup', td: 'cell',
-  fieldset: 'group',
-};
+  'tr', 'thead', 'tbody', 'tfoot', 'td', 'fieldset', 'a', 'input',
+]);
 
-const INPUT_ROLES = {
-  checkbox: 'checkbox', radio: 'radio', button: 'button', submit: 'button', reset: 'button',
-  text: 'textbox', email: 'textbox', tel: 'textbox', url: 'textbox',
-  range: 'slider', number: 'spinbutton', search: 'searchbox',
-};
+const JUDGED_INPUT_TYPES = new Set([
+  'checkbox', 'radio', 'button', 'submit', 'reset', 'text', 'email', 'tel', 'url',
+  'range', 'number', 'search',
+]);
 
 function implicitRole(element) {
   const tag = element.tagName.toLowerCase();
-  if (tag === 'a') return element.hasAttribute('href') ? 'link' : null;
-  if (tag === 'input') return INPUT_ROLES[element.type] ?? null;
-  return IMPLICIT_ROLES[tag] ?? null;
+  if (!JUDGED_TAGS.has(tag)) return null;
+  if (tag === 'input' && !JUDGED_INPUT_TYPES.has(element.type)) return null;
+  const role = modelledRole(element);
+  // generic / presentation are "no role to duplicate" here, never a match.
+  return role && role !== 'generic' && role !== 'presentation' ? role : null;
+}
+
+// Native display value of each table-structure element. When CSS has
+// replaced it (display:flex / grid / block responsive tables), browsers
+// stop exposing a data table and the explicit role is what restores the
+// semantics (MDN, table role: "when CSS's display property overrides the
+// native semantics of a table ... you can use the ARIA table roles to
+// re-add the semantics"). Same shape as the list-style exception
+// (2026-08-25 overnight audit).
+const TABLE_DISPLAY = {
+  table: ['table', 'inline-table'],
+  thead: ['table-header-group'], tbody: ['table-row-group'], tfoot: ['table-footer-group'],
+  tr: ['table-row'], td: ['table-cell'],
+};
+const TABLE_ROLES = new Set(['table', 'rowgroup', 'row', 'cell']);
+
+function tableSemanticsStripped(element, tag) {
+  const table = tag === 'table' ? element : element.closest('table');
+  if (table && !TABLE_DISPLAY.table.includes(getComputedStyle(table).display)) return true;
+  const native = TABLE_DISPLAY[tag];
+  return !!native && !native.includes(getComputedStyle(element).display);
+}
+
+/** An item with no marker: list-style-type none on the item itself, or a
+ *  ::marker emptied by CSS. Safari/VoiceOver drops list semantics whenever
+ *  the bullets go, however the CSS spells it (the write-up the exception
+ *  is based on: "any CSS that would remove the bullet or number indicators
+ *  of a list's items will also remove the semantics"). The ul's own
+ *  list-style-type stays "disc" when the property sits on the li, which is
+ *  the more common spelling (2026-08-25 overnight audit). */
+function markerRemoved(item) {
+  if (getComputedStyle(item).listStyleType === 'none') return true;
+  const marker = getComputedStyle(item, '::marker').content;
+  return marker === 'none' || marker === '""' || marker === "''";
+}
+
+function listMarkersRemoved(list) {
+  if (getComputedStyle(list).listStyleType === 'none') return true;
+  for (const child of list.children) {
+    if (child.tagName === 'LI' && markerRemoved(child)) return true;
+  }
+  return false;
 }
 
 export default {
@@ -38,19 +85,23 @@ export default {
     const explicit = element.getAttribute('role').trim().split(/\s+/)[0]?.toLowerCase();
     const implicit = implicitRole(element);
     if (!implicit || explicit !== implicit) return { status: 'pass' };
+    const tag = element.tagName.toLowerCase();
     // The exceptions this rule's own advice describes are honoured, not
     // just documented:
-    //  - role="list"/"listitem" on list-style:none lists is the standard
+    //  - role="list"/"listitem" on marker-less lists is the standard
     //    fix for Safari/VoiceOver dropping list semantics — keep it.
     //  - role="img" on an SVG-source <img> is the standard fix for
     //    VoiceOver skipping the alt text of SVG images — keep it.
-    if (explicit === 'list' && getComputedStyle(element).listStyleType === 'none') return { status: 'pass' };
+    //  - table roles on a table whose CSS display is no longer table-* are
+    //    what keeps it a data table: keep them.
+    if (explicit === 'list' && listMarkersRemoved(element)) return { status: 'pass' };
     if (explicit === 'listitem') {
+      if (markerRemoved(element)) return { status: 'pass' };
       const list = element.closest('ul, ol');
       if (list && getComputedStyle(list).listStyleType === 'none') return { status: 'pass' };
     }
+    if (TABLE_ROLES.has(explicit) && tableSemanticsStripped(element, tag)) return { status: 'pass' };
     if (explicit === 'img' && /\.svg([?#]|$)/i.test(element.currentSrc || element.src || '')) return { status: 'pass' };
-    const tag = element.tagName.toLowerCase();
     const caveat = implicit === 'list'
       ? ' (Exception: keep it if you set list-style: none — Safari/VoiceOver drops list semantics without it.)'
       : '';

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

@@ -4,14 +4,18 @@
 // Divs do NOT demote — a header wrapped in plain divs is still a banner.
 // role="alertdialog" joins dialog: both are modal containers whose content
 // region navigation reaches through the dialog itself, and consent banners
-// (measured on a live news home) are exactly this shape.
+// (measured on a live news home) are exactly this shape. The native
+// <dialog> element has the same implicit role and the same policy; only a
+// 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 =
   'main, nav, aside, form[aria-label], form[aria-labelledby], ' +
   '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"]';
+  '[role="search"], [role="form"], [role="dialog"], [role="alertdialog"], dialog[open]';
 
 export default {
   id: 'region',

package/engine/rules/index.js

@@ -90,6 +90,15 @@ import embedAlt from './wcag/1.1.1-embed-alt.js';
 import canvasAlt from './wcag/1.1.1-canvas-alt.js';
 import videoLoopMotion from './wcag/2.2.2-video-loop-motion.js';
 import visualOrderDivergence from './wcag/2.4.3-visual-order-divergence.js';
+// 2026-08-25 gap batch (reports/coverage-gaps/2026-08-25-1915.html): the four
+// A/AA criteria neither engine covered where an honest review question
+// exists. All four ask, none asserts — each SC's failure hinges on a fact
+// (a transcript nearby, an essential confirmation, a no-drag path, meaning
+// in a sequence) the DOM cannot prove.
+import audioTranscript from './wcag/1.2.1-audio-transcript.js';
+import readingOrderDivergence from './wcag/1.3.2-reading-order-divergence.js';
+import dragAlternative from './wcag/2.5.7-drag-alternative.js';
+import redundantEntry from './wcag/3.3.7-redundant-entry.js';
 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';
@@ -185,6 +194,10 @@ export default [
   canvasAlt,
   videoLoopMotion,
   visualOrderDivergence,
+  audioTranscript,
+  readingOrderDivergence,
+  dragAlternative,
+  redundantEntry,
   onInputNavigation,
   errorMessageLinkage,
   compositeWidgetName,

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

@@ -11,7 +11,10 @@ export default {
     if (accessibleName(element)) return { status: 'pass' };
     return {
       status: 'fail',
-      message: 'This image button has no alt text — screen readers announce just "button".',
+      // HTML-AAM: a nameless image input takes an implementation-defined
+      // name such as "Submit", which says nothing about what THIS button
+      // does (2026-08-25 overnight audit).
+      message: 'This image button has no alt text, so browsers fall back to a generic "Submit" name that does not describe what the button does.',
       fix: 'Add alt="What the button does", e.g. alt="Search".',
     };
   },

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

@@ -1,4 +1,9 @@
 // WCAG SC 1.1.1 Non-text Content (Level A)
+// An <object> that declares a TEXT document (type="text/…", PDF, XHTML, or
+// a typeless data URL whose extension says document) embeds text, not
+// non-text content, so 1.1.1's applicability is itself in question there.
+// That case asks instead of asserting, the same gate embed-alt applies to
+// its sibling element (2026-08-25 overnight audit closed the asymmetry).
 export default {
   id: 'object-alt',
   name: 'Object alt text',
@@ -9,6 +14,18 @@ export default {
   selector: 'object',
   evaluate(element, { accessibleName }) {
     if (accessibleName(element) || element.textContent.trim()) return { status: 'pass' };
+    const type = (element.getAttribute('type') ?? '').trim().toLowerCase();
+    const data = (element.getAttribute('data') ?? '').split(/[?#]/)[0].toLowerCase();
+    const isDocument = type.startsWith('text/')
+      || type === 'application/pdf' || type === 'application/xhtml+xml'
+      || (!type && /\.(html?|xhtml|pdf|txt)$/.test(data));
+    if (isDocument) {
+      return {
+        status: 'incomplete',
+        message: 'This embedded object renders a text document but has no accessible name, so assistive technology users get no indication of what the embedded document is. Check it is identified in the surrounding context.',
+        fix: 'Add aria-label="…" naming the embedded document, or fallback content inside the <object> element.',
+      };
+    }
     return {
       status: 'fail',
       message: 'This embedded object has no text alternative — users who can’t see it get nothing.',

package/engine/rules/wcag/1.2.1-audio-transcript.js

@@ -0,0 +1,47 @@
+// WCAG SC 1.2.1 Audio-only and Video-only (Prerecorded) (Level A) — the
+// audio-only slice
+//
+// Prerecorded audio-only content needs a text alternative that presents
+// equivalent information: a transcript. Whether a transcript exists — a
+// link beside the player, a paragraph below it, a page it points to — is
+// not decidable from the DOM, so this rule never asserts. It asks, once
+// per audio element that can actually present sound to someone.
+//
+// The video-only half of the criterion (silent video needing a transcript
+// or audio track) is a DISCLOSED gap: whether a video file carries an
+// audio stream is not visible from the DOM, so flagging every <video>
+// would drown real findings in noise.
+//
+// The "cannot present sound" logic mirrors media-captions: muteness and
+// controls decide whether audio can reach anyone (properties first —
+// frameworks set them without reflecting attributes), and an element with
+// no media resource presents nothing. The live exemption (1.2.1 covers
+// prerecorded only) is undecidable from the DOM and stays with the human:
+// the message names it rather than the rule guessing.
+export default {
+  id: 'audio-transcript',
+  name: 'Audio transcript',
+  impact: 'serious',
+  tags: ['wcag2a', 'wcag121'],
+  help: 'Prerecorded audio-only content needs a transcript',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/audio-only-and-video-only-prerecorded.html',
+  selector: 'audio',
+  visibleOnly: false,
+  evaluate(element) {
+    // No media resource: nothing is presented, nothing to transcribe
+    // (lazy players before a script sets their src).
+    if (!element.currentSrc && !element.getAttribute('src') && !element.querySelector('source')) {
+      return { status: 'pass' };
+    }
+    // Muted with no controls: no user path to any sound, so whatever the
+    // file carries is never presented to anyone.
+    if ((element.muted || element.volume === 0) && !element.hasAttribute('controls')) {
+      return { status: 'pass' };
+    }
+    return {
+      status: 'incomplete',
+      message: 'This audio content needs a transcript nearby — deaf and hard-of-hearing users get nothing from the recording itself. Check that an equivalent text version exists and is easy to find from the player (1.2.1 covers prerecorded audio; a live stream is 1.2.9 instead).',
+      fix: 'Provide a transcript of the recording as text on the page or behind a clearly labelled link next to the player.',
+    };
+  },
+};

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

@@ -14,9 +14,24 @@ export default {
     // state — so a bare <track> is a subtitle track and counts. (An invalid
     // value defaults to metadata, which does not, so `kind=""` and
     // `kind="banana"` are deliberately left out.)
-    if (element.querySelector('track[kind="captions" i], track[kind="subtitles" i], track:not([kind])')) {
+    if (element.querySelector('track[kind="captions" i]')) {
       return { status: 'pass' };
     }
+    // A subtitles track (explicit, or the kind-less default) is not proof
+    // of captions: HTML defines subtitles as dialogue for hearers who do
+    // not understand the language, captions as dialogue PLUS sound effects
+    // and other audio information for people who cannot hear it. H95 says
+    // a subtitles track "will not be sufficient" where other audio
+    // information matters, while a mislabelled one may be. The DOM cannot
+    // tell which, so this is a review, not a pass (David, 2026-08-26; it
+    // had passed since the rule was written).
+    if (element.querySelector('track[kind="subtitles" i], track:not([kind])')) {
+      return {
+        status: 'incomplete',
+        message: 'This video has a subtitles track but no captions track. Subtitles carry dialogue for people who can hear the audio; captions also carry sound effects and other audio information deaf and hard-of-hearing users need. Check the track covers those, or mark it kind="captions" if it does.',
+        fix: 'Use <track kind="captions" src="…" srclang="…" label="…"> for a track that includes non-speech audio information.',
+      };
+    }
     // A video with no media resource at all presents nothing — there is no
     // audio content to caption (lazy players before their source is set).
     if (!element.currentSrc && !element.getAttribute('src') && !element.querySelector('source')) {

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

@@ -20,6 +20,32 @@ const roleOf = (element) =>
   element.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ??
   implicitRole(element);
 
+/**
+ * Every element in the COMPOSED subtree of `element`: its light-DOM
+ * descendants plus, for each element carrying an open shadow root
+ * (`element` itself included), everything inside that shadow tree, again
+ * recursively. Assistive technology reads the flat tree, so a role="list"
+ * whose items are custom elements rendering role="listitem" inside their
+ * own shadow roots is a list of listitems (Chromium exposes list > listitem,
+ * listitem); querySelectorAll stops at the shadow boundary and reported it
+ * as empty (2026-08-25 overnight audit; same reasoning as
+ * aria-required-parent's flat-tree walk). Closed roots stay invisible, as
+ * everywhere else in the engine.
+ */
+function composedDescendants(element) {
+  const found = [];
+  const pending = [element];
+  for (let i = 0; i < pending.length; i++) {
+    const scope = pending[i];
+    if (scope.shadowRoot) pending.push(scope.shadowRoot);
+    for (const el of scope.querySelectorAll('*')) {
+      found.push(el);
+      if (el.shadowRoot) pending.push(el.shadowRoot);
+    }
+  }
+  return found;
+}
+
 /**
  * Everything the container could plausibly own: its whole subtree, plus any
  * element it claims by aria-owns.
@@ -33,13 +59,13 @@ const roleOf = (element) =>
  * container is not empty, and that is the only claim this rule should make.
  */
 function candidateDescendants(element) {
-  const found = [...element.querySelectorAll('*')].filter((el) => !el.matches('script, style, template'));
+  const found = composedDescendants(element).filter((el) => !el.matches('script, style, template'));
   const owns = element.getAttribute('aria-owns');
   if (owns) {
     const root = element.getRootNode();
     for (const id of owns.split(/\s+/).filter(Boolean)) {
       const target = root.getElementById?.(id);
-      if (target) found.push(target, ...target.querySelectorAll('*'));
+      if (target) found.push(target, ...composedDescendants(target));
     }
   }
   return found;
@@ -57,7 +83,8 @@ export default {
     if (element.getAttribute('aria-busy') === 'true') return { status: 'pass' }; // still loading
     const role = element.getAttribute('role').trim().split(/\s+/)[0].toLowerCase();
     const required = REQUIRED_CHILDREN[role];
-    const children = [...element.children].filter((c) => !c.matches('script, style, template'));
+    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' };