pour-engine 1.1.0

package/engine/lib/dom.js

@@ -0,0 +1,116 @@
+// DOM helpers shared by all rules.
+
+/**
+ * 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
+ * root without re-walking the page. Closed shadow roots are unreachable by
+ * design — like every DOM tool, we can only see what the page exposes.
+ */
+export function collectRoots(context) {
+  const roots = [context];
+  for (let i = 0; i < roots.length; i++) {
+    if (!roots[i].querySelectorAll) continue;
+    for (const el of roots[i].querySelectorAll('*')) {
+      if (el.shadowRoot) roots.push(el.shadowRoot);
+    }
+  }
+  return roots;
+}
+
+/** 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;
+}
+
+/**
+ * Rendered on screen — ignores aria-hidden. For purely visual rules
+ * (contrast, target size): sighted users see aria-hidden content too.
+ */
+export function isRendered(element) {
+  if (typeof element.checkVisibility === 'function') {
+    return element.checkVisibility({ visibilityProperty: true });
+  }
+  const style = getComputedStyle(element);
+  return style.display !== 'none' && style.visibility !== 'hidden';
+}
+
+/** Rendered AND exposed to assistive technology (default rule filter).
+ *  aria-hidden is checked up the flat tree, so aria-hidden on a shadow host
+ *  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;
+  }
+  return isRendered(element);
+}
+
+/** Selector for an element within its own root (document or shadow root). */
+function cssPathInRoot(element) {
+  if (element.id) 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})`;
+    }
+    parts.unshift(part);
+    if (current.parentElement?.id) {
+      parts.unshift(`#${CSS.escape(current.parentElement.id)}`);
+      break;
+    }
+    current = current.parentElement;
+  }
+  return parts.join(' > ') || element.tagName.toLowerCase();
+}
+
+/**
+ * A short, stable-ish CSS selector for an element. Elements inside shadow
+ * roots get a `host-path >>> inner-path` chain (one `>>>` per boundary);
+ * resolve by querying each segment and descending into `.shadowRoot`.
+ */
+export function cssPath(element) {
+  let path = cssPathInRoot(element);
+  let root = element.getRootNode();
+  while (root && root.host) {
+    path = `${cssPathInRoot(root.host)} >>> ${path}`;
+    root = root.host.getRootNode();
+  }
+  return path;
+}
+
+/** Element's opening markup (attributes) plus a snippet of its own text —
+ *  enough to recognise it in a table. Built WITHOUT element.outerHTML, which
+ *  serializes the whole subtree and turns audits quadratic on huge pages
+ *  (container divs would each stringify most of the document). */
+export function htmlSnippet(element, maxLength = 300) {
+  let html = `<${element.tagName.toLowerCase()}`;
+  for (const { name, value } of element.attributes) {
+    if (html.length >= maxLength) break;
+    html += ` ${name}="${value}"`;
+  }
+  html += '>';
+  const text = ownText(element);
+  if (text && html.length < maxLength) html += text.slice(0, maxLength - html.length);
+  return html.length > maxLength ? `${html.slice(0, maxLength)}…` : html;
+}
+
+/** The element's own (not descendant-element) text, trimmed. */
+export function ownText(element) {
+  return [...element.childNodes]
+    .filter((node) => node.nodeType === Node.TEXT_NODE)
+    .map((node) => node.textContent)
+    .join('')
+    .trim();
+}

package/engine/lib/roles.js

@@ -0,0 +1,125 @@
+// 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.
+
+/** Every attribute name in the ARIA 1.2 vocabulary (without the prefix).
+ *  aria-attr-valid judges membership; aria-allowed-attr judges role fit —
+ *  each unknown attribute is reported once, by aria-attr-valid alone. */
+export const KNOWN_ARIA = new Set([
+  'activedescendant', 'atomic', 'autocomplete', 'braillelabel', 'brailleroledescription',
+  'busy', 'checked', 'colcount', 'colindex', 'colindextext', 'colspan', 'controls',
+  'current', 'describedby', 'description', 'details', 'disabled', 'dropeffect',
+  'errormessage', 'expanded', 'flowto', 'grabbed', 'haspopup', 'hidden', 'invalid',
+  'keyshortcuts', 'label', 'labelledby', 'level', 'live', 'modal', 'multiline',
+  'multiselectable', 'orientation', 'owns', 'placeholder', 'posinset', 'pressed',
+  'readonly', 'relevant', 'required', 'roledescription', 'rowcount', 'rowindex',
+  'rowindextext', 'rowspan', 'selected', 'setsize', 'sort', 'valuemax', 'valuemin',
+  'valuenow', 'valuetext',
+]);
+
+/** Global attributes, usable with any role (ARIA 1.2 §6.4). */
+export const GLOBAL_ARIA = new Set([
+  'atomic', 'busy', 'controls', 'current', 'describedby', 'description', 'details',
+  'dropeffect', 'flowto', 'grabbed', 'hidden', 'keyshortcuts', 'label', 'labelledby',
+  'live', 'owns', 'relevant', 'roledescription', 'braillelabel', 'brailleroledescription',
+]);
+
+/** Attributes each role supports IN ADDITION to the globals. */
+export const ROLE_ARIA = {
+  link: ['disabled', 'expanded', 'haspopup'],
+  button: ['disabled', 'expanded', 'haspopup', 'pressed'],
+  checkbox: ['checked', 'disabled', 'errormessage', 'invalid', 'readonly', 'required'],
+  switch: ['checked', 'disabled', 'errormessage', 'invalid', 'readonly', 'required'],
+  radio: ['checked', 'disabled', 'posinset', 'setsize'],
+  option: ['selected', 'checked', 'disabled', 'posinset', 'setsize'],
+  tab: ['selected', 'disabled', 'expanded', 'haspopup', 'posinset', 'setsize'],
+  menuitem: ['disabled', 'expanded', 'haspopup', 'posinset', 'setsize'],
+  menuitemcheckbox: ['checked', 'disabled', 'expanded', 'haspopup', 'posinset', 'setsize'],
+  menuitemradio: ['checked', 'disabled', 'expanded', 'haspopup', 'posinset', 'setsize'],
+  textbox: ['activedescendant', 'autocomplete', 'disabled', 'errormessage', 'haspopup', 'invalid', 'multiline', 'placeholder', 'readonly', 'required'],
+  searchbox: ['activedescendant', 'autocomplete', 'disabled', 'errormessage', 'haspopup', 'invalid', 'multiline', 'placeholder', 'readonly', 'required'],
+  combobox: ['activedescendant', 'autocomplete', 'disabled', 'errormessage', 'expanded', 'haspopup', 'invalid', 'readonly', 'required'],
+  listbox: ['activedescendant', 'disabled', 'errormessage', 'expanded', 'invalid', 'multiselectable', 'orientation', 'readonly', 'required'],
+  slider: ['disabled', 'errormessage', 'haspopup', 'invalid', 'orientation', 'readonly', 'valuemax', 'valuemin', 'valuenow', 'valuetext'],
+  spinbutton: ['activedescendant', 'disabled', 'errormessage', 'invalid', 'readonly', 'required', 'valuemax', 'valuemin', 'valuenow', 'valuetext'],
+  progressbar: ['valuemax', 'valuemin', 'valuenow', 'valuetext'],
+  meter: ['valuemax', 'valuemin', 'valuenow', 'valuetext'],
+  scrollbar: ['disabled', 'orientation', 'valuemax', 'valuemin', 'valuenow', 'valuetext'],
+  heading: ['level'],
+  list: [],
+  listitem: ['level', 'posinset', 'setsize'],
+  row: ['colindex', 'disabled', 'expanded', 'level', 'posinset', 'rowindex', 'selected', 'setsize'],
+  rowgroup: [],
+  cell: ['colindex', 'colspan', 'rowindex', 'rowspan'],
+  gridcell: ['colindex', 'colspan', 'rowindex', 'rowspan', 'disabled', 'errormessage', 'expanded', 'haspopup', 'invalid', 'readonly', 'required', 'selected'],
+  columnheader: ['colindex', 'colspan', 'rowindex', 'rowspan', 'disabled', 'errormessage', 'expanded', 'haspopup', 'invalid', 'readonly', 'required', 'selected', 'sort'],
+  rowheader: ['colindex', 'colspan', 'rowindex', 'rowspan', 'disabled', 'errormessage', 'expanded', 'haspopup', 'invalid', 'readonly', 'required', 'selected', 'sort'],
+  table: ['colcount', 'rowcount'],
+  grid: ['activedescendant', 'colcount', 'disabled', 'multiselectable', 'readonly', 'rowcount'],
+  treegrid: ['activedescendant', 'colcount', 'disabled', 'errormessage', 'invalid', 'multiselectable', 'orientation', 'readonly', 'required', 'rowcount'],
+  tablist: ['activedescendant', 'disabled', 'multiselectable', 'orientation'],
+  menu: ['activedescendant', 'disabled', 'orientation'],
+  menubar: ['activedescendant', 'disabled', 'orientation'],
+  tree: ['activedescendant', 'disabled', 'errormessage', 'invalid', 'multiselectable', 'orientation', 'required'],
+  treeitem: ['checked', 'disabled', 'expanded', 'haspopup', 'level', 'posinset', 'selected', 'setsize'],
+  radiogroup: ['activedescendant', 'disabled', 'errormessage', 'invalid', 'orientation', 'readonly', 'required'],
+  group: ['activedescendant', 'disabled'],
+  separator: ['disabled', 'orientation', 'valuemax', 'valuemin', 'valuenow', 'valuetext'],
+  toolbar: ['activedescendant', 'disabled', 'orientation'],
+  dialog: ['modal'],
+  alertdialog: ['modal'],
+  application: ['activedescendant', 'disabled', 'expanded', 'haspopup'],
+  article: ['posinset', 'setsize'],
+  img: [], figure: [], document: [], feed: [], math: [], note: [], presentation: [], none: [],
+  banner: [], complementary: [], contentinfo: [], form: [], main: [], navigation: [], region: [], search: [],
+  alert: [], log: [], marquee: [], status: [], timer: [], tabpanel: [], tooltip: [],
+  definition: [], term: [], paragraph: [], generic: [], blockquote: [], caption: [], code: [],
+  emphasis: [], strong: [], time: [], deletion: [], insertion: [], subscript: [], superscript: [],
+};
+
+const INPUT_ROLES = {
+  checkbox: 'checkbox', radio: 'radio', range: 'slider', number: 'spinbutton',
+  search: 'searchbox', email: 'textbox', tel: 'textbox', text: 'textbox', url: 'textbox',
+  button: 'button', submit: 'button', reset: 'button', image: 'button',
+};
+
+const TAG_ROLES = {
+  button: 'button', textarea: 'textbox', img: 'img', article: 'article',
+  aside: 'complementary', nav: 'navigation', main: 'main',
+  h1: 'heading', h2: 'heading', h3: 'heading', h4: 'heading', h5: 'heading', h6: 'heading',
+  ul: 'list', ol: 'list', menu: 'list', li: 'listitem',
+  table: 'table', thead: 'rowgroup', tbody: 'rowgroup', tfoot: 'rowgroup',
+  tr: 'row', td: 'cell', th: 'columnheader',
+  form: 'form', fieldset: 'group', details: 'group', dialog: 'dialog', hr: 'separator',
+  progress: 'progressbar', meter: 'meter', output: 'status', option: 'option',
+  datalist: 'listbox', dt: 'term', dd: 'definition', p: 'paragraph',
+  div: 'generic', span: 'generic', blockquote: 'blockquote', figure: 'figure',
+  time: 'time', code: 'code', em: 'emphasis', strong: 'strong',
+};
+
+/**
+ * The element's implicit ARIA role, or null when it has none / we don't
+ * model it (callers should treat null as "don't judge").
+ */
+export function implicitRole(element) {
+  const tag = element.tagName.toLowerCase();
+  if (tag === 'a' || tag === 'area') return element.hasAttribute('href') ? 'link' : 'generic';
+  if (tag === 'input') return INPUT_ROLES[element.type] ?? null;
+  if (tag === 'select') return element.multiple || element.size > 1 ? 'listbox' : 'combobox';
+  if (tag === 'img') return element.getAttribute('alt') === '' ? 'presentation' : 'img';
+  if (tag === 'header') return element.closest('article, aside, main, nav, section') ? 'generic' : 'banner';
+  if (tag === 'footer') return element.closest('article, aside, main, nav, section') ? 'generic' : 'contentinfo';
+  if (tag === 'section') {
+    return element.hasAttribute('aria-label') || element.hasAttribute('aria-labelledby') ? 'region' : 'generic';
+  }
+  return TAG_ROLES[tag] ?? null;
+}
+
+/** The element's effective role: explicit (first modelled token) or implicit. */
+export function effectiveRole(element) {
+  const explicit = element.getAttribute('role')?.trim().split(/\s+/) ?? [];
+  for (const token of explicit) {
+    if (ROLE_ARIA[token.toLowerCase()]) return token.toLowerCase();
+  }
+  return explicit.length ? null : implicitRole(element); // unknown explicit role: don't judge
+}

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

@@ -0,0 +1,29 @@
+export default {
+  id: 'accesskeys',
+  impact: 'serious',
+  tags: ['best-practice'],
+  help: 'The same accesskey must not be assigned twice',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/character-key-shortcuts.html',
+  selector: '[accesskey]',
+  visibleOnly: false,
+  // Judged as a set: duplicates are the problem.
+  evaluateAll(elements) {
+    const byKey = {};
+    elements.forEach((element, index) => {
+      const key = element.getAttribute('accesskey').trim().toLowerCase();
+      (byKey[key] ??= []).push(index);
+    });
+    const outcomes = elements.map(() => ({ status: 'pass' }));
+    for (const [key, indexes] of Object.entries(byKey)) {
+      if (indexes.length < 2) continue;
+      for (const index of indexes) {
+        outcomes[index] = {
+          status: 'fail',
+          message: `accesskey="${key}" is used ${indexes.length} times — the browser can only honour one, so the others silently do nothing.`,
+          fix: 'Give each accesskey a unique value, or remove them (they conflict with AT shortcuts anyway).',
+        };
+      }
+    }
+    return outcomes;
+  },
+};

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

@@ -0,0 +1,22 @@
+// aria-label on a generic element (plain div/span/p) is PROHIBITED by ARIA
+// 1.2 — the role doesn't support naming, so conforming assistive technology
+// ignores the label. That makes it an authoring defect worth surfacing, but
+// NOT a WCAG failure: a static text container is not a "user interface
+// component", so no success criterion (4.1.2 included) actually fails.
+// Best-practice scope is the honest home; demoted from WCAG scope after an
+// independent audit found it dominating WCAG results on news/commerce pages.
+export default {
+  id: 'aria-label-misuse',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'aria-label on generic elements is ignored by assistive technology',
+  helpUrl: 'https://www.w3.org/TR/using-aria/#practical-support-aria-label-aria-labelledby-and-aria-describedby',
+  selector: 'div[aria-label]:not([role]):not([tabindex]), span[aria-label]:not([role]):not([tabindex]), p[aria-label]:not([role]):not([tabindex])',
+  evaluate(element) {
+    return {
+      status: 'fail',
+      message: `aria-label="${element.getAttribute('aria-label')}" on a plain <${element.tagName.toLowerCase()}> does nothing — screen readers only announce labels on interactive elements or landmarks.`,
+      fix: 'Give the element a suitable role (or use a landmark/heading), or remove the aria-label.',
+    };
+  },
+};

package/engine/rules/best-practice/button-type.js

@@ -0,0 +1,15 @@
+export default {
+  id: 'button-type',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'Buttons inside forms should declare their type',
+  helpUrl: 'https://html.spec.whatwg.org/multipage/form-elements.html#attr-button-type',
+  selector: 'form button:not([type]), form button[type=""]',
+  evaluate() {
+    return {
+      status: 'fail',
+      message: 'A <button> without type inside a form defaults to type="submit" — pressing Enter (or activating it with AT) can submit the form by accident.',
+      fix: 'Add type="button" (or type="submit" if submission is intended).',
+    };
+  },
+};

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

@@ -0,0 +1,19 @@
+export default {
+  id: 'empty-heading',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'Headings must contain text',
+  helpUrl: 'https://www.w3.org/WAI/tutorials/page-structure/headings/',
+  selector: 'h1, h2, h3, h4, h5, h6, [role="heading"]',
+  evaluate(element, { accessibleName }) {
+    // A role override demotes the element — it isn't a heading any more.
+    const role = element.getAttribute('role');
+    if (role && role !== 'heading') return { status: 'pass' };
+    if (accessibleName(element)) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'This heading is empty — screen-reader users navigating by headings land on nothing.',
+      fix: 'Add text to the heading, or remove the element if it is only used for spacing.',
+    };
+  },
+};

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

@@ -0,0 +1,35 @@
+// WAI forms tutorial: radio/checkbox groups need a group label — each
+// input's own label isn't enough to convey what the group asks.
+export default {
+  id: 'fieldset-legend',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'Radio and checkbox groups should be grouped with a label',
+  helpUrl: 'https://www.w3.org/WAI/tutorials/forms/grouping/',
+  selector: 'input[type="radio"][name], input[type="checkbox"][name]',
+  // Judged as a set: only same-name groups of 2+ need grouping, and one
+  // finding per group is enough.
+  evaluateAll(elements) {
+    const groups = {};
+    elements.forEach((element, index) => {
+      const key = `${element.type}::${element.form?.id ?? ''}::${element.name}`;
+      (groups[key] ??= []).push(index);
+    });
+    const outcomes = elements.map(() => ({ status: 'pass' }));
+    for (const indexes of Object.values(groups)) {
+      if (indexes.length < 2) continue;
+      const first = elements[indexes[0]];
+      const fieldset = first.closest('fieldset');
+      const grouped =
+        (fieldset && fieldset.querySelector('legend')?.textContent.trim()) ||
+        first.closest('[role="group"][aria-label], [role="group"][aria-labelledby], [role="radiogroup"][aria-label], [role="radiogroup"][aria-labelledby]');
+      if (grouped) continue;
+      outcomes[indexes[0]] = {
+        status: 'fail',
+        message: `This group of ${indexes.length} ${first.type} inputs (name="${first.name}") has no group label — screen-reader users hear each option without knowing what question it answers.`,
+        fix: 'Wrap the group in <fieldset> with a <legend>, or role="radiogroup"/"group" with an aria-label.',
+      };
+    }
+    return outcomes;
+  },
+};

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

@@ -0,0 +1,30 @@
+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
+
+export default {
+  id: 'heading-order',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'Headings should step down one level at a time',
+  helpUrl: 'https://www.w3.org/WAI/tutorials/page-structure/headings/',
+  selector: 'h1, h2, h3, h4, h5, h6, [role="heading"]',
+  // Needs the whole page: each heading is judged against the previous one.
+  evaluateAll(elements) {
+    let previous = 0;
+    return elements.map((element) => {
+      const current = level(element);
+      const skipped = previous > 0 && current > previous + 1;
+      const outcome = skipped
+        ? {
+            status: 'fail',
+            message: `Heading level jumps from h${previous} to h${current}, which breaks the page outline for screen-reader navigation.`,
+            fix: `Use <h${previous + 1}> here, or restructure so levels increase one at a time.`,
+          }
+        : { status: 'pass' };
+      previous = current;
+      return outcome;
+    });
+  },
+};

package/engine/rules/best-practice/landmark-one-main.js

@@ -0,0 +1,22 @@
+export default {
+  id: 'landmark-one-main',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'The page should have exactly one main landmark',
+  helpUrl: 'https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element, { isVisible }) {
+    // Hidden mains (responsive/SPA double-renders kept display:none) are
+    // not exposed and must not count as duplicates.
+    const count = [...element.ownerDocument.querySelectorAll('main, [role="main"]')].filter(isVisible).length;
+    if (count === 1) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: count === 0
+        ? 'No <main> landmark — screen-reader users have no shortcut to the primary content.'
+        : `${count} main landmarks — "skip to main" becomes ambiguous.`,
+      fix: count === 0 ? 'Wrap the primary content in a single <main> element.' : 'Keep one <main>; demote the others to <section> or <div>.',
+    };
+  },
+};

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

@@ -0,0 +1,46 @@
+// ARIA APG landmark pattern: banner, main, and contentinfo are page-level
+// regions — nesting them inside other landmarks breaks the page outline.
+import { implicitRole } from '../../lib/roles.js';
+
+const LANDMARK_ROLES = new Set([
+  'main', 'navigation', 'banner', 'contentinfo', 'complementary', 'region', 'search', 'form',
+]);
+
+/** 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
+ *  usa.gov-style div[role=banner] inside section[aria-label] was invisible
+ *  to the old explicit-only check. */
+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 (role && LANDMARK_ROLES.has(role)) return { element: parent, role };
+  }
+  return null;
+}
+
+export default {
+  id: 'landmark-top-level',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'banner, main and contentinfo landmarks must be top level',
+  helpUrl: 'https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/',
+  selector: 'header, footer, main, [role="banner"], [role="contentinfo"], [role="main"]',
+  evaluate(element) {
+    const tag = element.tagName.toLowerCase();
+    // <header>/<footer> inside sectioning content are not landmarks at all.
+    if ((tag === 'header' || tag === 'footer') && !element.hasAttribute('role') &&
+        element.closest('article, aside, main, nav, section')) {
+      return { status: 'pass' };
+    }
+    const container = landmarkAncestor(element);
+    if (!container) return { status: 'pass' };
+    const role = element.getAttribute('role') ?? { header: 'banner', footer: 'contentinfo', main: 'main' }[tag];
+    return {
+      status: 'fail',
+      message: `This ${role} landmark is nested inside a ${container.role} landmark (<${container.element.tagName.toLowerCase()}>) — page-level regions lose their meaning when nested.`,
+      fix: 'Move it to be a direct child of <body>, or remove the landmark role.',
+    };
+  },
+};

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

@@ -0,0 +1,84 @@
+// 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';
+
+const SINGLETON = new Set(['banner', 'contentinfo', 'main']);
+
+/** 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). */
+const landmarkRole = (element) =>
+  element.getAttribute('role')?.trim().split(/\s+/)[0]?.toLowerCase() ?? implicitRole(element);
+
+// Landmarks are not name-from-content roles: only author-provided labels
+// distinguish them (the text inside a nav is its content, not its name).
+const landmarkName = (element) => {
+  const labelledby = element.getAttribute('aria-labelledby');
+  if (labelledby) {
+    const text = labelledby
+      .split(/\s+/)
+      .map((id) => element.ownerDocument.getElementById(id)?.textContent ?? '')
+      .join(' ')
+      .trim();
+    if (text) return text;
+  }
+  return element.getAttribute('aria-label')?.trim() || element.getAttribute('title')?.trim() || '';
+};
+
+export default {
+  id: 'landmark-unique',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'Landmarks of the same type need distinguishing labels',
+  helpUrl: 'https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/',
+  // Implicit landmarks (header, footer, labelled section/form) join the
+  // grouping — a page's <header> and a div[role="banner"] ARE duplicates.
+  selector:
+    'nav, aside, header, footer, section[aria-label], section[aria-labelledby], ' +
+    'form[aria-label], form[aria-labelledby], [role="navigation"], [role="complementary"], ' +
+    '[role="banner"], [role="contentinfo"], [role="region"], [role="search"], [role="form"], [role="main"], main',
+  // Judged as a set: two unlabelled navs are the problem, not either alone.
+  evaluateAll(elements) {
+    const roles = elements.map(landmarkRole);
+    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');
+
+    // Singleton roles: more than one banner/contentinfo/main is a failure
+    // regardless of labels.
+    for (const singleton of SINGLETON) {
+      const dupes = landmarkIndexes.filter(({ role }) => role === singleton);
+      if (dupes.length < 2) continue;
+      for (const { index } of dupes) {
+        outcomes[index] = {
+          status: 'fail',
+          message: `${dupes.length} ${singleton} landmarks on one page — ${singleton} must be unique; screen-reader region navigation becomes ambiguous.`,
+          fix: `Keep one ${singleton}; demote the others (remove the role, or use a non-landmark element).`,
+        };
+      }
+    }
+
+    const groups = {};
+    for (const { element, index, role } of landmarkIndexes) {
+      if (SINGLETON.has(role)) continue; // already judged above
+      const key = `${role}::${landmarkName(element).toLowerCase()}`;
+      (groups[key] ??= []).push(index);
+    }
+    for (const [key, indexes] of Object.entries(groups)) {
+      if (indexes.length < 2) continue;
+      const [role, name] = key.split('::');
+      for (const index of indexes) {
+        outcomes[index] = {
+          status: 'fail',
+          message: name
+            ? `${indexes.length} ${role} landmarks share the label "${name}" — screen-reader users can't tell them apart.`
+            : `${indexes.length} unlabelled ${role} landmarks — screen-reader users hear "${role}" twice with no way to tell them apart.`,
+          fix: 'Give each one a distinct aria-label, e.g. aria-label="Primary" / aria-label="Footer".',
+        };
+      }
+    }
+    return outcomes;
+  },
+};

package/engine/rules/best-practice/multiple-labels.js

@@ -0,0 +1,23 @@
+// Multiple <label>s per field are VALID HTML and accname concatenates them,
+// so nothing in WCAG 3.3.2 prohibits the pattern — demoted from WCAG scope
+// after a spec sweep. It stays worth surfacing: screen readers differ in
+// which label they announce, and the visible-label + sr-only-supplement
+// pair usually reads better as label + aria-describedby.
+export default {
+  id: 'multiple-labels',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'Form fields should not have multiple labels',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/labels-or-instructions.html',
+  selector: 'input, select, textarea',
+  evaluate(element, { isVisible }) {
+    // Hidden labels don't compete for announcement.
+    const visibleLabels = [...(element.labels ?? [])].filter(isVisible);
+    if (visibleLabels.length <= 1) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: `${visibleLabels.length} visible labels point at this field — screen readers differ in which they announce.`,
+      fix: 'Keep one label; move extra guidance into aria-describedby text.',
+    };
+  },
+};

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

@@ -0,0 +1,21 @@
+// WCAG technique G200/G201: opening a new window without warning disorients
+// users who can't see the window change. Heuristic is English-only for now.
+const MENTIONS_NEW_WINDOW = /new (window|tab)|opens? in/i;
+
+export default {
+  id: 'new-window-link',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'Links opening a new window should say so',
+  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') ?? ''}`;
+    if (MENTIONS_NEW_WINDOW.test(name)) return { status: 'pass' };
+    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.',
+      fix: 'Append visually-hidden text like <span class="sr-only">(opens in new window)</span>, or drop target="_blank".',
+    };
+  },
+};

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

@@ -0,0 +1,16 @@
+export default {
+  id: 'no-autofocus',
+  impact: 'minor',
+  tags: ['best-practice'],
+  help: 'autofocus disorients assistive-technology users',
+  helpUrl: 'https://html.spec.whatwg.org/multipage/interaction.html#the-autofocus-attribute',
+  selector: '[autofocus]',
+  visibleOnly: false,
+  evaluate(element) {
+    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.`,
+    };
+  },
+};

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

@@ -0,0 +1,17 @@
+export default {
+  id: 'page-heading-one',
+  impact: 'moderate',
+  tags: ['best-practice'],
+  help: 'Every page should start its outline with an <h1>',
+  helpUrl: 'https://www.w3.org/WAI/tutorials/page-structure/headings/',
+  selector: 'html',
+  visibleOnly: false,
+  evaluate(element) {
+    if (element.ownerDocument.querySelector('h1, [role="heading"][aria-level="1"]')) return { status: 'pass' };
+    return {
+      status: 'fail',
+      message: 'No <h1> — the page outline has no starting point for screen-reader navigation.',
+      fix: 'Add one <h1> naming what the page is about.',
+    };
+  },
+};