pour-engine 1.36.0 → 1.37.1

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -111,7 +111,7 @@ meaning that only a person can settle, even where a rule decides most real pages
 
 | SC | Name | Level | Coverage | Rules |
 |---|---|---|---|---|
-| 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-label-misuse, aria-valid-refs, button-name, composite-widget-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, summary-name, valid-role, invoker-target |
+| 4.1.2 | [Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) | A | Partially automated | input-image-alt, form-label, link-name, aria-allowed-attr, aria-attr-valid, aria-field-name, aria-hidden-focus, aria-label-misuse, aria-valid-refs, button-name, composite-widget-name, dialog-name, frame-title, invoker-target, label-for-valid, nested-interactive, role-required-aria, summary-name, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
 **Totals:** 39 partially automated · 47 manual — with 88 rules.

package/engine/README.md

@@ -112,7 +112,7 @@ Nothing in the spec is silently skipped — that claim is the product.
 
 ## Honest current state
 
-74 rules, hardened on real sites and the `testbeds/` pages. Audits walk into
+88 rules, hardened on real sites and the `testbeds/` pages. Audits walk into
 open shadow roots (targets come back as `host >>> inner` selector chains);
 iframe traversal is the host's job, and the extension does it. Known gaps:
 the full accname spec (ours is a close approximation) and the language

package/engine/lib/contrast.js

@@ -1040,7 +1040,7 @@ export function viewportVeil(doc) {
 /** Parse a computed text-shadow list into layers. Computed style serializes
  *  the colour first ("rgb(0, 0, 0) 1px 0px 2px") with px lengths; author-ish
  *  orderings are tolerated. */
-export function parseTextShadows(cssText) {
+function parseTextShadows(cssText) {
   if (!cssText || cssText === 'none') return [];
   const layers = [];
   for (const part of cssText.split(/,(?![^(]*\))/)) {
@@ -1116,7 +1116,7 @@ export function textShadowNegligible(cssText, fontSize) {
  * uncertain path keeps the FULL box, erring toward review, never past a
  * real overlap. Returns null when the clip leaves nothing paintable.
  */
-export function paintableRect(element, rect) {
+function paintableRect(element, rect) {
   let { left, top, right, bottom } = rect;
   let mode = getComputedStyle(element).position;
   for (let a = element.parentElement; a; a = a.parentElement) {
@@ -1333,7 +1333,7 @@ export function imageLuminanceRange(url, overlays = [], grid = null) {
  * cover/contain hands sizing to an intrinsic this function does not have, or
  * when its position is not a plain length or percentage.
  */
-export function backgroundImagePaintRects(element) {
+function backgroundImagePaintRects(element) {
   const style = getComputedStyle(element);
   const images = splitLayers(style.backgroundImage);
   if (!images.length) return [];
@@ -1492,29 +1492,6 @@ export function rangeWithBackdrop(range, under, overlays = []) {
   };
 }
 
-/**
- * Luminance range of a CSS gradient, from its colour stops. Interpolated
- * colours stay close enough to their stops' luminances to bracket.
- */
-export function gradientLuminanceRange(backgroundImageCss, overlays = []) {
-  const stops = (backgroundImageCss.match(/rgba?\([^)]+\)/g) ?? []).map(parseColor).filter(Boolean);
-  if (!stops.length || stops.some((c) => c.a < 1)) return null; // translucent stops reveal what's beneath
-  const composited = stops.map((stop) => (overlays.length ? applyOverlays(stop, overlays) : stop));
-  const lums = composited.map(luminance);
-  const min = Math.min(...lums);
-  const max = Math.max(...lums);
-  // The COLOURS at the extremes, not just their luminances: translucent text
-  // takes its presented colour from the pixels beneath, so bracketing that
-  // blend needs the actual rgb to composite against, and luminance alone
-  // cannot be un-gamma'd back into one.
-  return {
-    min,
-    max,
-    minColor: composited[lums.indexOf(min)],
-    maxColor: composited[lums.indexOf(max)],
-  };
-}
-
 /** The layers of a computed background-image list, split on top-level
  *  commas only: commas inside url() and gradient() belong to the layer. */
 export function splitBackgroundLayers(backgroundImageCss) {

package/engine/lib/dom.js

@@ -1,5 +1,11 @@
 // DOM helpers shared by all rules.
 
+/** Elements that never reach the accessibility tree, so they cannot break
+ *  the structure of a list or a description list. STYLE belongs with them:
+ *  CSS-in-JS libraries inject <style> right beside the markup, and it was
+ *  being counted as a stray child that broke the list. */
+export const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+
 /**
  * The audit context plus every OPEN shadow root beneath it, hosts before
  * their shadow trees. Collected once per audit so each rule can query every

package/engine/lib/roles.js

@@ -24,6 +24,12 @@ export const GLOBAL_ARIA = new Set([
   'live', 'owns', 'relevant', 'roledescription', 'braillelabel', 'brailleroledescription',
 ]);
 
+/** The eight landmark roles (ARIA 1.2, Landmark Roles). Shared by the
+ *  landmark rules, the landmark lens and the screen reader's rotor. */
+export const LANDMARK_ROLES = new Set([
+  'banner', 'complementary', 'contentinfo', 'form', 'main', 'navigation', 'region', 'search',
+]);
+
 /** Attributes each role supports IN ADDITION to the globals.
  *
  *  Includes the four attributes ARIA 1.2 removed from the GLOBAL set

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

@@ -3,11 +3,7 @@
 // page outline. Complementary joins via the aside demotion semantics in
 // lib/roles.js: only an aside that actually reaches the accessibility tree
 // as complementary owes top-levelness.
-import { implicitRole } from '../../lib/roles.js';
-
-const LANDMARK_ROLES = new Set([
-  'main', 'navigation', 'banner', 'contentinfo', 'complementary', 'region', 'search', 'form',
-]);
+import { implicitRole, LANDMARK_ROLES } from '../../lib/roles.js';
 
 /** 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

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

@@ -1,18 +1,15 @@
 // ARIA APG landmark pattern: same-type landmarks need distinguishing
 // labels, and banner / contentinfo / main must be unique per page outright
 // (two "banners" are ambiguous however well they're labelled).
-import { implicitRole } from '../../lib/roles.js';
+import { implicitRole, LANDMARK_ROLES } from '../../lib/roles.js';
 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
+// Only the eight ARIA landmark roles (lib/roles.js) count. 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

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

@@ -2,7 +2,12 @@
 // 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';
-const REQUIRED_CHILDREN = {
+// 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).
+export const REQUIRED_CHILDREN = {
+  feed: ['article'],
+  row: ['cell', 'columnheader', 'gridcell', 'rowheader'],
   list: ['listitem'],
   listbox: ['option', 'group'],
   menu: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'group'],

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

@@ -13,7 +13,13 @@
 // > group > treeitem exactly as authored). For the roles whose context does
 // not list group (listitem, tab, row, cell), group stays transparent as
 // before.
-const REQUIRED_PARENT = {
+// Every row of ARIA 1.2's Required Context Role table; verify:aria-tables
+// diffs this map against the spec (2026-09-01, after caption, columnheader
+// and rowheader were found missing).
+export const REQUIRED_PARENT = {
+  caption: ['figure', 'grid', 'table', 'treegrid'],
+  columnheader: ['row'],
+  rowheader: ['row'],
   listitem: ['list'],
   option: ['listbox', 'group'],
   menuitem: ['menu', 'menubar', 'group'],
@@ -27,7 +33,7 @@ const REQUIRED_PARENT = {
   gridcell: ['row'],
 };
 
-const IMPLICIT_CONTAINER = { ul: 'list', ol: 'list', menu: 'list', table: 'table', tbody: 'rowgroup', thead: 'rowgroup', tfoot: 'rowgroup', tr: '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',

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

@@ -1,13 +1,12 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
+import { NEVER_RENDERED } from '../../lib/dom.js';
+
 const ALLOWED = new Set(['DT', 'DD', 'DIV']);
-// Nothing here reaches the accessibility tree, so none of it can corrupt
-// the term/description pairing: the same set list-structure keeps, for the
-// same reason (CSS-in-JS injects <style> right beside the markup). HTML's
-// content model does exclude style from dl, but validity is not the
-// criterion; 1.3.1 is about relationships assistive technology can
-// determine, and every dt/dd pair stays intact around an element that has
-// no tree presence (2026-08-25 overnight audit).
-const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+// NEVER_RENDERED cannot corrupt the term/description pairing: HTML's content
+// model does exclude style from dl, but validity is not the criterion;
+// 1.3.1 is about relationships assistive technology can determine, and
+// every dt/dd pair stays intact around an element that has no tree
+// presence (2026-08-25 overnight audit).
 
 export default {
   id: 'definition-list',

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

@@ -125,6 +125,23 @@ export default {
           : 'Put visible text inside the label.',
       };
     }
+    // A label points at this id, but the id is shared: for binds to the
+    // FIRST element with it, so this later twin has no label and no name
+    // even though a label sits beside it (hsbc.com download basket, two
+    // rows reusing one document id, 2026-09-01). The fix is a unique id,
+    // not another label.
+    if (element.id) {
+      const root = element.getRootNode();
+      const pointed = root.querySelector?.(`label[for="${CSS.escape(element.id)}"]`);
+      const first = root.getElementById?.(element.id);
+      if (pointed && first && first !== element) {
+        return {
+          status: 'fail',
+          message: `A <label for="${element.id}"> exists, but an earlier element on the page has the same id, so the label belongs to that one and this field has no label at all.`,
+          fix: `Give this field a unique id and point its label at that; ids must not repeat on a page.`,
+        };
+      }
+    }
     return {
       status: 'fail',
       message: 'This form field has no label — users cannot tell what to enter.',

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

@@ -1,9 +1,6 @@
 // WCAG SC 1.3.1 Info and Relationships (Level A)
-// Nothing here reaches the accessibility tree, so none of it can corrupt a
-// list's structure. STYLE belongs with them: CSS-in-JS libraries inject
-// <style> right where the markup sits, and it was being counted as a stray
-// child that broke the list.
-const NEVER_RENDERED = new Set(['SCRIPT', 'TEMPLATE', 'STYLE', 'LINK', 'META']);
+import { NEVER_RENDERED } from '../../lib/dom.js';
+
 const ITEM_ROLES = ['listitem', 'presentation', 'none'];
 
 export default {

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

@@ -84,10 +84,16 @@ 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 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.',
-        fix: 'Mark header cells with <th> (add scope="col" or scope="row" when the table has both).',
+        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).',
       };
     }
     return { status: 'pass' };

package/engine/rules/wcag/2.4.1-bypass-blocks.js

@@ -1,6 +1,6 @@
 // WCAG SC 2.4.1 Bypass Blocks (Level A)
 import { collectRoots, isEmbeddedDocument } from '../../lib/dom.js';
-import { effectiveRole } from '../../lib/roles.js';
+import { effectiveRole, LANDMARK_ROLES } from '../../lib/roles.js';
 
 // ARIA11 lists the landmark roles: banner, complementary, contentinfo,
 // form, main, navigation, region, search. Judged by EFFECTIVE role, not tag
@@ -10,7 +10,6 @@ import { effectiveRole } from '../../lib/roles.js';
 // and missed the second. region and form are landmarks only when named
 // (ARIA 1.2 requires an accessible name for region; HTML-AAM maps form to
 // the form landmark only with one), so the name is checked here.
-const LANDMARK_ROLES = new Set(['banner', 'complementary', 'contentinfo', 'form', 'main', 'navigation', 'region', 'search']);
 const NAMED_ONLY = new Set(['form', 'region']);
 const LANDMARK_CANDIDATES = 'main, header, footer, nav, aside, section, form, [role]';
 const hasName = (el) => Boolean(

package/engine/rules/wcag/4.1.2-aria-label-misuse.js

@@ -40,6 +40,18 @@ const NAME_FROM_CONTENT = 'a[href], button, summary, h1, h2, h3, h4, h5, h6, th,
   + ' [role="checkbox"], [role="radio"], [role="switch"], [role="heading"],'
   + ' [role="cell"], [role="gridcell"], [role="columnheader"], [role="rowheader"], [role="tooltip"]';
 
+// ARIA 1.2's ten roles that prohibit naming, and the HTML elements that
+// carry them implicitly (HTML-AAM); verify:aria-tables diffs the set
+// against the spec. The rule started with div, span and p alone
+// (generic and paragraph); the other eight, explicit or as strong, em,
+// code, del, s, ins, sub and sup, joined 2026-09-01.
+export const NAME_PROHIBITED_ROLES = ['caption', 'code', 'deletion', 'emphasis', 'generic', 'insertion', 'paragraph', 'strong', 'subscript', 'superscript'];
+const IMPLICITLY_PROHIBITED = ['div', 'span', 'p', 'strong', 'em', 'code', 'del', 's', 'ins', 'sub', 'sup'];
+const SELECTOR = ['aria-label', 'aria-labelledby'].flatMap((attr) => [
+  ...IMPLICITLY_PROHIBITED.map((tag) => `${tag}[${attr}]:not([role]):not([tabindex])`),
+  ...NAME_PROHIBITED_ROLES.map((role) => `[role="${role}"][${attr}]:not([tabindex])`),
+]).join(', ');
+
 export default {
   id: 'aria-label-misuse',
   name: 'aria-label placement',
@@ -50,8 +62,7 @@ export default {
   // §5.2.8.6 prohibits BOTH naming attributes on generic — aria-labelledby
   // pointing at perfectly real text is the same authoring error as an inline
   // aria-label, and the more tempting one (a card labelled by its own title).
-  selector: 'div[aria-label]:not([role]):not([tabindex]), span[aria-label]:not([role]):not([tabindex]), p[aria-label]:not([role]):not([tabindex]),'
-    + ' div[aria-labelledby]:not([role]):not([tabindex]), span[aria-labelledby]:not([role]):not([tabindex]), p[aria-labelledby]:not([role]):not([tabindex])',
+  selector: SELECTOR,
   evaluate(element) {
     // Inside a name-from-content ancestor the label is NOT ignored: accname
     // applies the whole algorithm to each descendant while building the
@@ -72,7 +83,7 @@ export default {
         })();
     return {
       status: 'incomplete',
-      message: `${attempt} on a plain <${element.tagName.toLowerCase()}> is prohibited by ARIA: this element's role does not support naming, so although many browser and screen reader pairings announce the label today, that support is not guaranteed anywhere and can differ between assistive technologies. Where it is announced it replaces the element's visible text; where it is not, users get the visible text alone. Check both presentations read correctly, and that nothing here relies on the label being heard. Prohibited markup is not by itself a WCAG failure: the criterion that policed validity, 4.1.1 Parsing, was removed in WCAG 2.2 (w3.org/WAI/WCAG22/Understanding/parsing.html), so what decides this is what users actually hear.`,
+      message: `${attempt} on ${element.hasAttribute('role') ? `role="${element.getAttribute('role').trim()}"` : `a plain <${element.tagName.toLowerCase()}>`} is prohibited by ARIA: this element's role does not support naming, so although many browser and screen reader pairings announce the label today, that support is not guaranteed anywhere and can differ between assistive technologies. Where it is announced it replaces the element's visible text; where it is not, users get the visible text alone. Check both presentations read correctly, and that nothing here relies on the label being heard. Prohibited markup is not by itself a WCAG failure: the criterion that policed validity, 4.1.1 Parsing, was removed in WCAG 2.2 (w3.org/WAI/WCAG22/Understanding/parsing.html), so what decides this is what users actually hear.`,
       fix: 'If this element must reliably announce something of its own, give it the role it is playing (a landmark, group, or widget role) so the name is legal and exposure is guaranteed — or move the spoken text into visible or visually-hidden real text. If the label is stray, remove it. Do not add a role solely to legalise the label.',
     };
   },

package/engine/rules/wcag/4.1.2-role-required-aria.js

@@ -15,7 +15,7 @@
 // control yet), and without aria-selected on an option (selection is
 // often conveyed by focus alone); the spec lists both, the DOM cannot
 // show a user is blocked, so the finding asks rather than asserts.
-const REQUIRED = {
+export const REQUIRED = {
   checkbox: ['aria-checked'],
   switch: ['aria-checked'],
   radio: ['aria-checked'],
@@ -29,7 +29,7 @@ const REQUIRED = {
   combobox: ['aria-expanded', 'aria-controls'],
   option: ['aria-selected'],
 };
-const HELD_AT_REVIEW = new Set(['aria-controls', 'aria-selected']);
+export const HELD_AT_REVIEW = new Set(['aria-controls', 'aria-selected']);
 
 // What each missing property costs the user, in the message.
 const COST = {

package/engine/rules/wcag/4.1.2-valid-role.js

@@ -1,7 +1,7 @@
 // WCAG SC 4.1.2 Name, Role, Value (Level A)
 import { attributesOf } from '../../lib/dom.js';
 // Concrete, usable roles — abstract roles are invalid in markup.
-const VALID_ROLES = new Set([
+export const VALID_ROLES = new Set([
   'alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote', 'button',
   'caption', 'cell', 'checkbox', 'code', 'columnheader', 'combobox', 'complementary',
   'contentinfo', 'definition', 'deletion', 'dialog', 'directory', 'document', 'emphasis',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pour-engine",
-  "version": "1.36.0",
+  "version": "1.37.1",
   "description": "Accessibility (WCAG 2.2) audit engine written from the W3C specifications — runs entirely in the browser, no dependencies.",
   "type": "module",
   "main": "engine/index.js",