pour-engine 1.1.1 → 1.1.4

package/README.md

@@ -51,6 +51,18 @@ invoked before and after each rule — useful for live progress UI. Results
 include `violations`, `passes`, `incomplete`, `inapplicable`,
 `manualReview`, and per-rule timings.
 
+## Examples
+
+Minimal, console-only examples live in [`examples/`](examples/):
+
+- [`examples/browser.html`](examples/browser.html) — a page that audits
+  itself; the dependency-free ES modules load straight from a CDN, no
+  bundler.
+- [`examples/puppeteer.mjs`](examples/puppeteer.mjs) — audit any URL:
+  `node examples/puppeteer.mjs https://example.com`
+- [`examples/playwright.mjs`](examples/playwright.mjs) — the same with
+  Playwright.
+
 ## Philosophy
 
 - **Spec-first.** Every rule and helper was written from the W3C

package/config/project.config.js

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

package/engine/COVERAGE.md

@@ -23,7 +23,7 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 | 1.3.1 | [Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) | A | Partially automated | aria-required-children, aria-required-parent, definition-list, dlitem-parent, form-label, list-structure, listitem-parent, p-as-heading, table-headers |
 | 1.3.2 | [Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) | A | Manual review | — |
 | 1.3.3 | [Sensory Characteristics](https://www.w3.org/WAI/WCAG22/Understanding/sensory-characteristics.html) | A | Manual review | — |
-| 1.3.4 | [Orientation](https://www.w3.org/WAI/WCAG22/Understanding/orientation.html) | AA | Manual review | — |
+| 1.3.4 | [Orientation](https://www.w3.org/WAI/WCAG22/Understanding/orientation.html) | AA | Partially automated | orientation-lock |
 | 1.3.5 | [Identify Input Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html) | AA | Partially automated | autocomplete-valid |
 | 1.3.6 | [Identify Purpose](https://www.w3.org/WAI/WCAG22/Understanding/identify-purpose.html) | AAA | Manual review | — |
 | 1.4.1 | [Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) | A | Partially automated | link-in-text-block |
@@ -72,7 +72,7 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 | 2.4.13 | [Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) | AAA | Manual review | — |
 | 2.5.1 | [Pointer Gestures](https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html) | A | Manual review | — |
 | 2.5.2 | [Pointer Cancellation](https://www.w3.org/WAI/WCAG22/Understanding/pointer-cancellation.html) | A | Manual review | — |
-| 2.5.3 | [Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) | A | Manual review | — |
+| 2.5.3 | [Label in Name](https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html) | A | Partially automated | label-in-name |
 | 2.5.4 | [Motion Actuation](https://www.w3.org/WAI/WCAG22/Understanding/motion-actuation.html) | A | Manual review | — |
 | 2.5.5 | [Target Size (Enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) | AAA | Partially automated | target-size-enhanced |
 | 2.5.6 | [Concurrent Input Mechanisms](https://www.w3.org/WAI/WCAG22/Understanding/concurrent-input-mechanisms.html) | AAA | Manual review | — |
@@ -112,4 +112,4 @@ All 86 success criteria of WCAG 2.2, and how the native engine covers them.
 | 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-valid-refs, button-name, dialog-name, frame-title, label-for-valid, nested-interactive, role-required-aria, valid-role |
 | 4.1.3 | [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | AA | Manual review | — |
 
-**Totals:** 2 automated · 26 partially automated · 58 manual — with 71 rules.
+**Totals:** 2 automated · 28 partially automated · 56 manual — with 73 rules.

package/engine/lib/roles.js

@@ -28,8 +28,8 @@ export const GLOBAL_ARIA = new Set([
 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'],
+  checkbox: ['checked', 'disabled', 'errormessage', 'expanded', 'invalid', 'readonly', 'required'],
+  switch: ['checked', 'disabled', 'errormessage', 'expanded', 'invalid', 'readonly', 'required'],
   radio: ['checked', 'disabled', 'posinset', 'setsize'],
   option: ['selected', 'checked', 'disabled', 'posinset', 'setsize'],
   tab: ['selected', 'disabled', 'expanded', 'haspopup', 'posinset', 'setsize'],

package/engine/rules/index.js

@@ -15,11 +15,14 @@ import imageAlt from './wcag/1.1.1-image-alt.js';
 import svgImgAlt from './wcag/1.1.1-svg-img-alt.js';
 import buttonName from './wcag/4.1.2-button-name.js';
 import linkName from './wcag/2.4.4-link-name.js';
-// Parked by product decision (2026-07-29): label-in-name excluded from runs
-// for now — restore the import and registry entry below to bring it back.
-// import labelInName from './wcag/2.5.3-label-in-name.js';
+// Un-parked 2026-08-01 (was parked 2026-07-29): benchmarking against other
+// engines showed real 2.5.3 misses on mainstream sites, and the rule now
+// also covers labelable fields whose associated <label> text is missing
+// from an overriding aria-name.
+import labelInName from './wcag/2.5.3-label-in-name.js';
 import formLabel from './wcag/1.3.1-form-label.js';
 import autocompleteValid from './wcag/1.3.5-autocomplete-valid.js';
+import orientationLock from './wcag/1.3.4-orientation.js';
 import metaViewport from './wcag/1.4.4-meta-viewport.js';
 import colorContrast from './wcag/1.4.3-color-contrast.js';
 import frameTitle from './wcag/4.1.2-frame-title.js';
@@ -107,9 +110,10 @@ export default [
   svgImgAlt,
   buttonName,
   linkName,
-  // labelInName, — parked 2026-07-29, see note at the import
+  labelInName,
   formLabel,
   autocompleteValid,
+  orientationLock,
   metaViewport,
   colorContrast,
   frameTitle,

package/engine/rules/wcag/1.3.4-orientation.js

@@ -0,0 +1,70 @@
+// WCAG SC 1.3.4 Orientation (Level AA, added in WCAG 2.1)
+// "Content does not restrict its view and operation to a single display
+// orientation, such as portrait or landscape, unless a specific display
+// orientation is essential."
+//
+// What a stylesheet can PROVE: a rule inside an @media (orientation: …)
+// block that hides or counter-rotates the page root is restricting the
+// whole page to the other orientation — the "please rotate your device"
+// wall (body { display: none }) and the forced-landscape hack
+// (body { transform: rotate(90deg) }). The rotate hack even disproves the
+// "essential" escape by itself: content that renders rotated demonstrably
+// works in both orientations.
+//
+// Deliberately NOT flagged: orientation media queries that restyle or hide
+// individual regions — that is ordinary responsive design, not a lock.
+// Script-driven locks (screen.orientation.lock()) and cross-origin
+// stylesheets (unreadable under CORS) are invisible to a static pass; the
+// rule asserts only what it can see and stays silent otherwise.
+const ROOT_PART = /^(html|body|:root)(::?[a-z-]+(\(.*\))?)?$/i;
+const LOCK_ROTATE = /rotate(?:3d\([^)]*,\s*)?\(?\s*(?:-?(?:90|270)deg|0\.25turn|-0\.25turn|100grad|-100grad)/i;
+
+function rootSelector(selectorText) {
+  return (selectorText ?? '').split(',').some((part) => ROOT_PART.test(part.trim()));
+}
+
+function scanRules(rules, insideOrientation, findings) {
+  for (const rule of rules ?? []) {
+    const condition = rule.conditionText ?? rule.media?.mediaText;
+    if (condition !== undefined && rule.cssRules) {
+      const orientation = /orientation\s*:\s*(portrait|landscape)/i.exec(condition)?.[1];
+      scanRules(rule.cssRules, orientation ? { condition, orientation } : insideOrientation, findings);
+      continue;
+    }
+    if (insideOrientation && rule.style && rootSelector(rule.selectorText)) {
+      const { display, visibility, transform, rotate } = rule.style;
+      if (display === 'none' || visibility === 'hidden') {
+        findings.push({ kind: 'hidden', selector: rule.selectorText, ...insideOrientation });
+      } else if (LOCK_ROTATE.test(transform ?? '') || LOCK_ROTATE.test(rotate ?? '')) {
+        findings.push({ kind: 'rotated', selector: rule.selectorText, ...insideOrientation });
+      }
+    } else if (rule.cssRules) {
+      scanRules(rule.cssRules, insideOrientation, findings);
+    }
+  }
+}
+
+export default {
+  id: 'orientation-lock',
+  impact: 'serious',
+  tags: ['wcag21aa', 'wcag134'],
+  help: 'Content must work in both portrait and landscape',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/orientation.html',
+  selector: 'html',
+  evaluate(element) {
+    const findings = [];
+    for (const sheet of element.ownerDocument.styleSheets) {
+      let rules;
+      try { rules = sheet.cssRules; } catch { continue; } // cross-origin: unreadable, skip
+      scanRules(rules, null, findings);
+    }
+    if (!findings.length) return { status: 'pass' };
+    const f = findings[0];
+    const verb = f.kind === 'hidden' ? 'hides the page' : 'rotates the page to force the other orientation';
+    return {
+      status: 'fail',
+      message: `A stylesheet rule (${f.selector} under @media ${f.condition}) ${verb} when the device is in ${f.orientation} — the content is locked to a single display orientation.`,
+      fix: 'Let the layout adapt to both orientations instead of hiding or rotating the page. If a single orientation is genuinely essential (rare), document why.',
+    };
+  },
+};

package/engine/rules/wcag/2.5.3-label-in-name.js

@@ -17,6 +17,12 @@ const BASES = [
   'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]',
   '[role="button"]', '[role="link"]', '[role="menuitem"]', '[role="tab"]',
   '[role="checkbox"]', '[role="radio"]', '[role="switch"]',
+  // Labelable form fields: their visible label is the associated <label>
+  // element, and an aria-name that omits its text breaks voice control just
+  // as surely as it does on a button (SC text scopes to any UI component
+  // whose label includes text, not only content-named controls).
+  'input:not([type="hidden"]):not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="image"])',
+  'select', 'textarea',
 ];
 const COMPONENTS = BASES.flatMap((base) => [`${base}[aria-label]`, `${base}[aria-labelledby]`]).join(', ');
 
@@ -71,9 +77,23 @@ export default {
   helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html',
   selector: COMPONENTS,
   evaluate(element, { accessibleName }) {
-    const rawVisible = element.tagName === 'INPUT'
-      ? (element.getAttribute('value') ?? '')
-      : visibleText(element.childNodes);
+    const tag = element.tagName.toLowerCase();
+    const buttonLike = tag === 'input' && ['button', 'submit', 'reset'].includes(element.type);
+    let rawVisible;
+    if (buttonLike) {
+      rawVisible = element.getAttribute('value') ?? '';
+    } else if (tag === 'input' || tag === 'select' || tag === 'textarea') {
+      // A field's visible label is its associated <label> (for= or wrapping,
+      // via the DOM `labels` list) — the part a voice-control user reads out.
+      // No visible label, nothing to match: label-less fields are
+      // form-label's finding, not a 2.5.3 mismatch.
+      rawVisible = [...(element.labels ?? [])]
+        .filter((label) => !visuallyErased(label))
+        .map((label) => visibleText(label.childNodes))
+        .join(' ');
+    } else {
+      rawVisible = visibleText(element.childNodes);
+    }
     const visible = rawVisible.replace(/\s+/g, ' ').trim();
     // Icon/symbol-only or nothing visible: there is no text label to match.
     if (!visible || !HAS_LETTERS.test(visible)) return { status: 'pass' };

package/engine/wcag22.js

@@ -37,7 +37,7 @@ export default [
   sc('1.3.1', 'Info and Relationships', 'A', 'partial'),
   sc('1.3.2', 'Meaningful Sequence', 'A', 'manual'),
   sc('1.3.3', 'Sensory Characteristics', 'A', 'manual'),
-  sc('1.3.4', 'Orientation', 'AA', 'manual', '2.1'),
+  sc('1.3.4', 'Orientation', 'AA', 'partial', '2.1'), // orientation-lock (2026-08-01) proves CSS root hides/rotations; script locks stay a human check
   sc('1.3.5', 'Identify Input Purpose', 'AA', 'partial', '2.1'), // partial: wrong tokens are provable; MISSING autocomplete on identity fields needs judgment
   sc('1.3.6', 'Identify Purpose', 'AAA', 'manual', '2.1'),
   sc('1.4.1', 'Use of Color', 'A', 'partial'), // link-in-text-block automates the link case
@@ -82,7 +82,7 @@ export default [
   sc('2.4.13', 'Focus Appearance', 'AAA', 'manual', '2.2'),
   sc('2.5.1', 'Pointer Gestures', 'A', 'manual', '2.1'),
   sc('2.5.2', 'Pointer Cancellation', 'A', 'manual', '2.1'),
-  sc('2.5.3', 'Label in Name', 'A', 'manual', '2.1'), // manual WHILE the label-in-name rule is parked (see rules/index.js) — 'auto' with no active rule made this SC vanish from both the results AND the manual checklist
+  sc('2.5.3', 'Label in Name', 'A', 'partial', '2.1'), // label-in-name un-parked 2026-08-01: catches aria-name/visible-label mismatches on controls and labelled fields; can't prove every naming path, so partial
   sc('2.5.4', 'Motion Actuation', 'A', 'manual', '2.1'),
   sc('2.5.5', 'Target Size (Enhanced)', 'AAA', 'partial', '2.1'),
   sc('2.5.6', 'Concurrent Input Mechanisms', 'AAA', 'manual', '2.1'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pour-engine",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "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",