pour-engine 1.1.1 → 1.1.5

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.5',
   },
 };

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 |
@@ -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 · 27 partially automated · 57 manual — with 72 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,17 @@ 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.
+// Re-parked by product decision (2026-08-01, David, after a one-day
+// un-parking): 2.5.3 is normative Level A but chiefly serves speech-input
+// users, and the findings volume isn't wanted in results for now. The SC is
+// classed 'manual' in wcag22.js so it lands in the human checklist instead
+// of being silently skipped. The rule itself (incl. the labelled-field
+// widening) stays maintained here — restore the import + registry entry to
+// bring it back.
 // 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 +113,10 @@ export default [
   svgImgAlt,
   buttonName,
   linkName,
-  // labelInName, — parked 2026-07-29, see note at the import
+  // labelInName, — re-parked 2026-08-01, see note at the import
   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', 'manual', '2.1'), // manual WHILE label-in-name is parked (re-parked 2026-08-01, see rules/index.js) — 'auto' with no active rule would make this SC vanish from results AND the manual checklist
   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.5",
   "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",