@a11y-skills/audit 0.1.0 → 0.2.0

package/dist/detectors/pause-control.js

@@ -0,0 +1,206 @@
+/**
+ * Pause/Stop control detection for auto-playing content.
+ * WCAG 1.4.2 (Audio Control) / 2.2.2 (Pause, Stop, Hide)
+ */
+import * as path from 'node:path';
+import { compareImages, formatDiffPercent, hasSignificantChange, } from '../utils/image-compare.js';
+import { PAUSE_KEYWORDS, CONTROL_CLASS_PATTERNS, CAROUSEL_PATTERNS, NAV_KEYWORDS, SVG_METADATA_PATTERNS, MAX_PARENT_LEVELS, PAUSE_CLICK_WAIT, SCREENSHOT_COMPARISON_WAIT, } from '../constants.js';
+/**
+ * Detect pause/stop controls in the page.
+ */
+export async function detectPauseControls(page) {
+    const config = {
+        pauseKeywords: [...PAUSE_KEYWORDS],
+        controlClassPatterns: [...CONTROL_CLASS_PATTERNS],
+        carouselPatterns: [...CAROUSEL_PATTERNS],
+        navKeywords: [...NAV_KEYWORDS],
+        svgMetadataPatterns: [...SVG_METADATA_PATTERNS],
+        maxParentLevels: MAX_PARENT_LEVELS,
+    };
+    return await page.evaluate((cfg) => {
+        const controls = [];
+        const carouselIndicators = [];
+        let hasAccessibleName = false;
+        const getSelector = (el) => {
+            if (el.id)
+                return `#${el.id}`;
+            if (el.className) {
+                const classes = el.className
+                    .toString()
+                    .split(' ')
+                    .filter((c) => c)
+                    .join('.');
+                if (classes)
+                    return `${el.tagName.toLowerCase()}.${classes}`;
+            }
+            return el.tagName.toLowerCase();
+        };
+        const interactiveElements = document.querySelectorAll('button, [role="button"], input[type="button"], [tabindex="0"]');
+        interactiveElements.forEach((el) => {
+            const element = el;
+            const tagName = element.tagName.toLowerCase();
+            const ariaLabel = element.getAttribute('aria-label') || '';
+            const textContent = element.textContent?.trim() || '';
+            const className = element.className?.toString() || '';
+            let accessibleName = ariaLabel || textContent;
+            const isSvgMetadata = cfg.svgMetadataPatterns.some((pattern) => accessibleName.toLowerCase().includes(pattern));
+            if (isSvgMetadata) {
+                accessibleName = '';
+            }
+            const lowerName = accessibleName.toLowerCase();
+            const lowerClass = className.toLowerCase();
+            const nameMatch = cfg.pauseKeywords.some((kw) => lowerName.includes(kw.toLowerCase()));
+            const classMatch = cfg.controlClassPatterns.some((pattern) => lowerClass.includes(pattern));
+            const isNearCarousel = cfg.carouselPatterns.some((pattern) => {
+                if (lowerClass.includes(pattern))
+                    return true;
+                let parent = element.parentElement;
+                for (let i = 0; i < cfg.maxParentLevels && parent; i++) {
+                    if (parent.className?.toString().toLowerCase().includes(pattern)) {
+                        return true;
+                    }
+                    parent = parent.parentElement;
+                }
+                return false;
+            });
+            const hasSvg = element.querySelector('svg');
+            let hasPauseIconPattern = false;
+            if (hasSvg) {
+                const rects = hasSvg.querySelectorAll('rect, path');
+                if (rects.length === 2) {
+                    hasPauseIconPattern = true;
+                }
+            }
+            if (nameMatch) {
+                controls.push({
+                    element: tagName,
+                    name: accessibleName || `[class: ${className.slice(0, 50)}]`,
+                    matchedBy: 'accessible-name',
+                    selector: getSelector(element),
+                });
+                hasAccessibleName = true;
+            }
+            else if (classMatch && isNearCarousel) {
+                controls.push({
+                    element: tagName,
+                    name: accessibleName || `[class: ${className.slice(0, 50)}]`,
+                    matchedBy: 'class-name-near-carousel',
+                    selector: getSelector(element),
+                });
+                if (accessibleName)
+                    hasAccessibleName = true;
+            }
+            else if (hasPauseIconPattern && isNearCarousel) {
+                controls.push({
+                    element: tagName,
+                    name: accessibleName || `[class: ${className.slice(0, 50)}]`,
+                    matchedBy: 'svg-icon-pattern',
+                    selector: getSelector(element),
+                });
+                if (accessibleName)
+                    hasAccessibleName = true;
+            }
+            const isNavControl = cfg.navKeywords.some((kw) => lowerName.includes(kw) || lowerClass.includes(kw));
+            if (isNavControl && isNearCarousel) {
+                carouselIndicators.push({
+                    element: tagName,
+                    name: accessibleName || `[class: ${className.slice(0, 50)}]`,
+                });
+            }
+        });
+        return {
+            found: controls.length > 0,
+            controls,
+            carouselIndicators,
+            hasAccessibleName,
+        };
+    }, config);
+}
+/**
+ * Verify if clicking the pause control actually stops the auto-play.
+ */
+export async function verifyPauseControl(page, pauseControls, outputDir, changeThreshold) {
+    const control = pauseControls.controls[0];
+    if (!pauseControls.found || !control) {
+        return {
+            attempted: false,
+            controlClicked: null,
+            beforeClickDiffPercent: null,
+            afterClickDiffPercent: null,
+            pauseWorked: null,
+            error: 'No pause controls found to verify',
+        };
+    }
+    const selector = control.selector;
+    if (!selector) {
+        return {
+            attempted: false,
+            controlClicked: null,
+            beforeClickDiffPercent: null,
+            afterClickDiffPercent: null,
+            pauseWorked: null,
+            error: 'No selector available for pause control',
+        };
+    }
+    try {
+        const beforePath1 = path.join(outputDir, 'verify-before-1.png');
+        const beforePath2 = path.join(outputDir, 'verify-before-2.png');
+        await page.screenshot({ path: beforePath1, fullPage: false });
+        await page.waitForTimeout(SCREENSHOT_COMPARISON_WAIT);
+        await page.screenshot({ path: beforePath2, fullPage: false });
+        const beforeDiff = compareImages(beforePath1, beforePath2, path.join(outputDir, 'verify-before-diff.png'));
+        const element = await page.$(selector);
+        if (!element) {
+            return {
+                attempted: true,
+                controlClicked: selector,
+                beforeClickDiffPercent: formatDiffPercent(beforeDiff.diffPercent),
+                afterClickDiffPercent: null,
+                pauseWorked: null,
+                error: `Could not find element with selector: ${selector}`,
+            };
+        }
+        await element.click();
+        await page.waitForTimeout(PAUSE_CLICK_WAIT);
+        const afterPath1 = path.join(outputDir, 'verify-after-1.png');
+        const afterPath2 = path.join(outputDir, 'verify-after-2.png');
+        await page.screenshot({ path: afterPath1, fullPage: false });
+        await page.waitForTimeout(SCREENSHOT_COMPARISON_WAIT);
+        await page.screenshot({ path: afterPath2, fullPage: false });
+        const afterDiff = compareImages(afterPath1, afterPath2, path.join(outputDir, 'verify-after-diff.png'));
+        const hadChangeBefore = hasSignificantChange(beforeDiff.diffPercent, changeThreshold);
+        const hasChangeAfter = hasSignificantChange(afterDiff.diffPercent, changeThreshold);
+        const pauseWorked = hadChangeBefore && !hasChangeAfter;
+        return {
+            attempted: true,
+            controlClicked: selector,
+            beforeClickDiffPercent: formatDiffPercent(beforeDiff.diffPercent),
+            afterClickDiffPercent: formatDiffPercent(afterDiff.diffPercent),
+            pauseWorked,
+            error: null,
+        };
+    }
+    catch (err) {
+        return {
+            attempted: true,
+            controlClicked: selector,
+            beforeClickDiffPercent: null,
+            afterClickDiffPercent: null,
+            pauseWorked: null,
+            error: `Error during verification: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * Create a skipped verification result.
+ */
+export function createSkippedVerification(reason) {
+    return {
+        attempted: false,
+        controlClicked: null,
+        beforeClickDiffPercent: null,
+        afterClickDiffPercent: null,
+        pauseWorked: null,
+        error: reason,
+    };
+}

package/dist/playwright/index.d.ts

@@ -16,4 +16,10 @@ export { runAxeAudit, type RunAxeAuditOptions } from './runAxeAudit.js';
 export { runFocusIndicatorCheck, type RunFocusIndicatorCheckOptions, } from './runFocusIndicatorCheck.js';
 export { runReflowCheck, type RunReflowCheckOptions } from './runReflowCheck.js';
 export { runTargetSizeCheck, type RunTargetSizeCheckOptions, } from './runTargetSizeCheck.js';
-export { resolveOutputPath, type OutputLocationOptions, } from '../utils/test-harness.js';
+export { runTextSpacingCheck, type RunTextSpacingCheckOptions, } from './runTextSpacingCheck.js';
+export { runZoomCheck, type RunZoomCheckOptions } from './runZoomCheck.js';
+export { runOrientationCheck, type RunOrientationCheckOptions, } from './runOrientationCheck.js';
+export { runAutocompleteAudit, type RunAutocompleteAuditOptions, } from './runAutocompleteAudit.js';
+export { runTimeLimitDetector, type RunTimeLimitDetectorOptions, } from './runTimeLimitDetector.js';
+export { runAutoPlayDetection, type RunAutoPlayDetectionOptions, } from './runAutoPlayDetection.js';
+export { resolveOutputPath, getTargetUrl, requireTargetUrl, type OutputLocationOptions, } from '../utils/test-harness.js';

package/dist/playwright/index.js

@@ -16,4 +16,10 @@ export { runAxeAudit } from './runAxeAudit.js';
 export { runFocusIndicatorCheck, } from './runFocusIndicatorCheck.js';
 export { runReflowCheck } from './runReflowCheck.js';
 export { runTargetSizeCheck, } from './runTargetSizeCheck.js';
-export { resolveOutputPath, } from '../utils/test-harness.js';
+export { runTextSpacingCheck, } from './runTextSpacingCheck.js';
+export { runZoomCheck } from './runZoomCheck.js';
+export { runOrientationCheck, } from './runOrientationCheck.js';
+export { runAutocompleteAudit, } from './runAutocompleteAudit.js';
+export { runTimeLimitDetector, } from './runTimeLimitDetector.js';
+export { runAutoPlayDetection, } from './runAutoPlayDetection.js';
+export { resolveOutputPath, getTargetUrl, requireTargetUrl, } from '../utils/test-harness.js';

package/dist/playwright/runAutoPlayDetection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Auto-play Content Detection — WCAG 1.4.2 (Audio Control) / 2.2.2 (Pause, Stop, Hide)
+ *
+ * Takes screenshots at 2s intervals (0/2/4/6s), pixel-diffs consecutive frames,
+ * detects whether visual content continues past 5s, finds pause/stop controls,
+ * and verifies whether they work.
+ *
+ * The caller is responsible for navigating the page before calling this.
+ *
+ * IMPORTANT: this is the only check that needs `pixelmatch` + `pngjs` (declared
+ * as optionalDependencies). To keep them out of the package barrel, the modules
+ * that pull them (`utils/image-compare`, `detectors`) are imported LAZILY here,
+ * so importing `@a11y-skills/audit/playwright` never requires the optional deps
+ * unless `runAutoPlayDetection` is actually called.
+ */
+import type { Page } from '@playwright/test';
+import type { AutoPlayDetectionResult } from '../types.js';
+export interface RunAutoPlayDetectionOptions {
+    /** A page already navigated to the target URL. */
+    page: Page;
+    /**
+     * Directory for screenshots, diffs, and the result JSON. Defaults to
+     * `<A11Y_OUTPUT_DIR | cwd>/auto-play-screenshots`.
+     */
+    outputDir?: string;
+    /** Significant-change threshold in percent (default: 0.1). */
+    changeThreshold?: number;
+}
+/**
+ * Run auto-play detection against the current page. Writes screenshots, diff
+ * images, and `detection-result.json` into the output directory; returns the
+ * result.
+ *
+ * @throws if the optional `pixelmatch` / `pngjs` deps are not installed.
+ */
+export declare function runAutoPlayDetection(options: RunAutoPlayDetectionOptions): Promise<AutoPlayDetectionResult>;

package/dist/playwright/runAutoPlayDetection.js

@@ -0,0 +1,137 @@
+/**
+ * Auto-play Content Detection — WCAG 1.4.2 (Audio Control) / 2.2.2 (Pause, Stop, Hide)
+ *
+ * Takes screenshots at 2s intervals (0/2/4/6s), pixel-diffs consecutive frames,
+ * detects whether visual content continues past 5s, finds pause/stop controls,
+ * and verifies whether they work.
+ *
+ * The caller is responsible for navigating the page before calling this.
+ *
+ * IMPORTANT: this is the only check that needs `pixelmatch` + `pngjs` (declared
+ * as optionalDependencies). To keep them out of the package barrel, the modules
+ * that pull them (`utils/image-compare`, `detectors`) are imported LAZILY here,
+ * so importing `@a11y-skills/audit/playwright` never requires the optional deps
+ * unless `runAutoPlayDetection` is actually called.
+ */
+import * as path from 'node:path';
+import { SCREENSHOT_INTERVALS, CHANGE_THRESHOLD, DEFAULT_AUTO_PLAY_OUTPUT_DIR, DETECTION_RESULT_FILENAME, } from '../constants.js';
+import { generateRecommendation, printSummary } from '../utils/recommendations.js';
+/** Capture screenshots at configured intervals. */
+async function captureScreenshots(page, outputDir) {
+    const screenshots = [];
+    for (let i = 0; i < SCREENSHOT_INTERVALS.length; i++) {
+        const current = SCREENSHOT_INTERVALS[i] ?? 0;
+        if (i > 0) {
+            const previous = SCREENSHOT_INTERVALS[i - 1] ?? 0;
+            await page.waitForTimeout(current - previous);
+        }
+        const timeLabel = `${current / 1000}s`;
+        const filename = `screenshot-${timeLabel}.png`;
+        const filepath = path.join(outputDir, filename);
+        await page.screenshot({ path: filepath, fullPage: false });
+        screenshots.push({ time: timeLabel, path: filepath });
+    }
+    return screenshots;
+}
+/**
+ * Run auto-play detection against the current page. Writes screenshots, diff
+ * images, and `detection-result.json` into the output directory; returns the
+ * result.
+ *
+ * @throws if the optional `pixelmatch` / `pngjs` deps are not installed.
+ */
+export async function runAutoPlayDetection(options) {
+    const { page, changeThreshold = CHANGE_THRESHOLD } = options;
+    const outputDir = options.outputDir ??
+        path.join(process.env.A11Y_OUTPUT_DIR ?? process.cwd(), DEFAULT_AUTO_PLAY_OUTPUT_DIR);
+    // Lazy-load the modules that depend on the optional pixelmatch/pngjs deps.
+    let imageCompare;
+    let detectors;
+    try {
+        imageCompare = await import('../utils/image-compare.js');
+        detectors = await import('../detectors/index.js');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const code = err.code;
+        // Only translate a genuine missing-optional-dep error; re-throw anything
+        // else (e.g. a real bug inside image-compare/detectors) unchanged.
+        if (code === 'ERR_MODULE_NOT_FOUND' || /pixelmatch|pngjs/.test(msg)) {
+            throw new Error('runAutoPlayDetection requires the optional dependencies `pixelmatch` and `pngjs`. ' +
+                'Install them: `npm install pixelmatch pngjs`.\n' +
+                `Original error: ${msg}`);
+        }
+        throw err;
+    }
+    const { compareImages, formatDiffPercent, hasSignificantChange, ensureOutputDir, saveJsonResult, } = imageCompare;
+    const { detectPauseControls, verifyPauseControl, createSkippedVerification } = detectors;
+    ensureOutputDir(outputDir);
+    // Take screenshots at intervals.
+    const screenshots = await captureScreenshots(page, outputDir);
+    // Compare consecutive screenshots.
+    const comparisons = [];
+    let hasAnyChange = false;
+    let hasChangeAfter5s = false;
+    for (let i = 1; i < screenshots.length; i++) {
+        const prev = screenshots[i - 1];
+        const curr = screenshots[i];
+        if (!prev || !curr)
+            continue;
+        const diffPath = path.join(outputDir, `diff-${prev.time}-vs-${curr.time}.png`);
+        const { diffPixels, totalPixels, diffPercent } = compareImages(prev.path, curr.path, diffPath);
+        const hasChange = hasSignificantChange(diffPercent, changeThreshold);
+        if (hasChange) {
+            hasAnyChange = true;
+            if ((SCREENSHOT_INTERVALS[i] ?? 0) > 5000) {
+                hasChangeAfter5s = true;
+            }
+        }
+        comparisons.push({
+            compare: `${prev.time} vs ${curr.time}`,
+            diffPixels,
+            totalPixels,
+            diffPercent: formatDiffPercent(diffPercent),
+            hasChange,
+        });
+    }
+    const stopsWithin5Seconds = hasAnyChange && !hasChangeAfter5s;
+    // Detect and verify pause controls.
+    const pauseControls = await detectPauseControls(page);
+    let pauseVerification;
+    if (hasAnyChange && !stopsWithin5Seconds && pauseControls.found) {
+        pauseVerification = await verifyPauseControl(page, pauseControls, outputDir, changeThreshold);
+    }
+    else {
+        let reason;
+        if (!hasAnyChange) {
+            reason = 'No auto-play detected';
+        }
+        else if (stopsWithin5Seconds) {
+            reason = 'Content stops within 5 seconds';
+        }
+        else {
+            reason = 'No pause controls found';
+        }
+        pauseVerification = createSkippedVerification(reason);
+    }
+    const result = {
+        url: page.url(),
+        screenshotRecords: screenshots,
+        comparisons,
+        hasAutoPlayContent: hasAnyChange,
+        stopsWithin5Seconds,
+        pauseControls,
+        pauseVerification,
+        recommendation: generateRecommendation({
+            hasAutoPlayContent: hasAnyChange,
+            stopsWithin5Seconds,
+            pauseControls,
+            pauseVerification,
+        }),
+    };
+    console.log('\n=== Auto-play Detection Results ===\n');
+    console.log(JSON.stringify(result, null, 2));
+    saveJsonResult(path.join(outputDir, DETECTION_RESULT_FILENAME), result);
+    printSummary({ hasAutoPlayContent: hasAnyChange, stopsWithin5Seconds, pauseControls, pauseVerification }, outputDir);
+    return result;
+}

package/dist/playwright/runAutocompleteAudit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Autocomplete Audit — WCAG 1.3.5 (Identify Input Purpose)
+ *
+ * Finds all form fields (input/select/textarea), uses Playwright's
+ * `ariaSnapshot()` to compute accessible names (following the ARIA naming
+ * algorithm), matches field names/ids/labels/placeholders to expected
+ * autocomplete tokens, and reports fields that are missing or have invalid
+ * autocomplete values.
+ *
+ * The caller is responsible for navigating the page before calling this.
+ *
+ * Limitations:
+ * - Cannot confirm actual field purpose; pattern matching is heuristic
+ * - Manual verification needed for edge cases
+ */
+import type { Page } from '@playwright/test';
+import type { AutocompleteAuditResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunAutocompleteAuditOptions extends OutputLocationOptions {
+    /** A page already navigated to the target URL. */
+    page: Page;
+}
+/**
+ * Run the autocomplete audit against the current page, write the result JSON,
+ * and return the parsed result.
+ */
+export declare function runAutocompleteAudit(options: RunAutocompleteAuditOptions): Promise<AutocompleteAuditResult>;

package/dist/playwright/runAutocompleteAudit.js

@@ -0,0 +1,197 @@
+/**
+ * Autocomplete Audit — WCAG 1.3.5 (Identify Input Purpose)
+ *
+ * Finds all form fields (input/select/textarea), uses Playwright's
+ * `ariaSnapshot()` to compute accessible names (following the ARIA naming
+ * algorithm), matches field names/ids/labels/placeholders to expected
+ * autocomplete tokens, and reports fields that are missing or have invalid
+ * autocomplete values.
+ *
+ * The caller is responsible for navigating the page before calling this.
+ *
+ * Limitations:
+ * - Cannot confirm actual field purpose; pattern matching is heuristic
+ * - Manual verification needed for edge cases
+ */
+import { AUTOCOMPLETE_FIELD_PATTERNS, VALID_AUTOCOMPLETE_TOKENS, DEFAULT_AUTOCOMPLETE_RESULT_FILE, } from '../constants.js';
+import { saveAuditResult, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
+/**
+ * Collect basic form field information in browser context.
+ * Accessible names are retrieved separately via ariaSnapshot().
+ */
+function collectBasicFieldInfo() {
+    function getUniqueSelector(element, elementIndex) {
+        if (element.id) {
+            return `#${element.id}`;
+        }
+        const path = [];
+        let current = element;
+        while (current && current !== document.body) {
+            let selector = current.tagName.toLowerCase();
+            const parent = current.parentElement;
+            if (parent) {
+                const childIndex = Array.from(parent.children).indexOf(current) + 1;
+                selector += `:nth-child(${childIndex})`;
+            }
+            path.unshift(selector);
+            current = parent;
+        }
+        return path.length > 0 ? path.join(' > ') : `[data-index="${elementIndex}"]`;
+    }
+    const skipTypes = ['hidden', 'submit', 'reset', 'button', 'image', 'file'];
+    const fields = [];
+    const elements = document.querySelectorAll('input, select, textarea');
+    elements.forEach((element, index) => {
+        const el = element;
+        if (el instanceof HTMLInputElement && skipTypes.includes(el.type)) {
+            return;
+        }
+        const inputType = el instanceof HTMLInputElement ? el.type : el.tagName.toLowerCase();
+        const autocompleteAttr = el.getAttribute('autocomplete');
+        fields.push({
+            selector: getUniqueSelector(element, index),
+            tagName: el.tagName.toLowerCase(),
+            inputType,
+            name: el.name || null,
+            id: el.id || null,
+            placeholder: el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement
+                ? el.placeholder || null
+                : null,
+            autocomplete: autocompleteAttr,
+        });
+    });
+    return fields;
+}
+/**
+ * Extract accessible name from ariaSnapshot output.
+ * ariaSnapshot returns YAML-like format: "- role \"accessible name\"".
+ */
+function parseAccessibleName(snapshot) {
+    // ariaSnapshot format: "- textbox \"Email address\"" or "- textbox \"Email address\" [focused]"
+    const match = snapshot.match(/^- \w+(?:\s+"([^"]*)")?/);
+    if (match && match[1]) {
+        return match[1];
+    }
+    return null;
+}
+/** Find pattern match for a field across name, id, label, and placeholder. */
+function findPatternMatch(field, patterns) {
+    for (const [token, pattern] of patterns) {
+        if (field.name && pattern.test(field.name)) {
+            return { token, matchedBy: 'name' };
+        }
+        if (field.id && pattern.test(field.id)) {
+            return { token, matchedBy: 'id' };
+        }
+        if (field.labelText && pattern.test(field.labelText)) {
+            return { token, matchedBy: 'label' };
+        }
+        if (field.placeholder && pattern.test(field.placeholder)) {
+            return { token, matchedBy: 'placeholder' };
+        }
+    }
+    return null;
+}
+/** Analyze fields for autocomplete issues. */
+function analyzeFields(fields, patterns, validTokens) {
+    const missing = [];
+    const invalid = [];
+    for (const field of fields) {
+        const match = findPatternMatch(field, patterns);
+        if (!match) {
+            continue;
+        }
+        const { token: expectedToken, matchedBy } = match;
+        if (!field.autocomplete || field.autocomplete === 'off') {
+            missing.push({
+                selector: field.selector,
+                tagName: field.tagName,
+                inputType: field.inputType,
+                name: field.name,
+                id: field.id,
+                labelText: field.labelText,
+                currentAutocomplete: field.autocomplete,
+                expectedToken,
+                matchedBy,
+                issueType: 'missing',
+            });
+            continue;
+        }
+        const autocompleteTokens = field.autocomplete.toLowerCase().split(/\s+/);
+        const mainToken = autocompleteTokens[autocompleteTokens.length - 1];
+        if (mainToken === undefined ||
+            !validTokens.includes(mainToken)) {
+            invalid.push({
+                selector: field.selector,
+                tagName: field.tagName,
+                inputType: field.inputType,
+                name: field.name,
+                id: field.id,
+                labelText: field.labelText,
+                currentAutocomplete: field.autocomplete,
+                expectedToken,
+                matchedBy,
+                issueType: 'invalid',
+            });
+        }
+    }
+    return { missing, invalid };
+}
+/**
+ * Run the autocomplete audit against the current page, write the result JSON,
+ * and return the parsed result.
+ */
+export async function runAutocompleteAudit(options) {
+    const { page, ...location } = options;
+    // Collect basic field info from DOM
+    const basicFields = await page.evaluate(collectBasicFieldInfo);
+    // Enhance with accessible names via ariaSnapshot()
+    const fields = [];
+    for (const basicField of basicFields) {
+        const locator = page.locator(basicField.selector);
+        let labelText = null;
+        try {
+            const snapshot = await locator.ariaSnapshot();
+            labelText = parseAccessibleName(snapshot);
+        }
+        catch {
+            // If ariaSnapshot fails, labelText remains null
+        }
+        fields.push({
+            ...basicField,
+            labelText,
+        });
+    }
+    const patterns = Object.entries(AUTOCOMPLETE_FIELD_PATTERNS);
+    const { missing, invalid } = analyzeFields(fields, patterns, VALID_AUTOCOMPLETE_TOKENS);
+    const result = {
+        url: page.url(),
+        totalFieldsChecked: fields.length,
+        missingAutocomplete: missing,
+        invalidAutocomplete: invalid,
+    };
+    // Output results
+    logAuditHeader('Autocomplete Audit Results', 'WCAG 1.3.5', result.url);
+    logSummary({
+        'Total form fields': result.totalFieldsChecked,
+        'Fields missing autocomplete': result.missingAutocomplete.length,
+        'Fields with invalid autocomplete': result.invalidAutocomplete.length,
+    });
+    logIssueList('Missing Autocomplete', result.missingAutocomplete, (el, i) => [
+        `${i + 1}. <${el.tagName}> "${el.selector}"`,
+        `   name: ${el.name || 'none'}, id: ${el.id || 'none'}`,
+        `   label: "${el.labelText || 'none'}"`,
+        `   Expected: autocomplete="${el.expectedToken}" (matched by ${el.matchedBy})`,
+    ]);
+    logIssueList('Invalid Autocomplete', result.invalidAutocomplete, (el, i) => [
+        `${i + 1}. <${el.tagName}> "${el.selector}"`,
+        `   Current: autocomplete="${el.currentAutocomplete}"`,
+        `   Expected: autocomplete="${el.expectedToken}"`,
+    ]);
+    const resolvedPath = saveAuditResult(result, {
+        ...location,
+        defaultFile: DEFAULT_AUTOCOMPLETE_RESULT_FILE,
+    });
+    logOutputPaths(resolvedPath);
+    return result;
+}

package/dist/playwright/runOrientationCheck.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Orientation Check — WCAG 1.3.4 (Orientation)
+ *
+ * Renders the page in portrait (375x667) and landscape (667x375), detecting
+ * "rotate device" messages/overlays and whether the main content is hidden in
+ * either orientation. Reports if the page restricts content to a specific
+ * orientation.
+ *
+ * This function OWNS navigation: it sets each viewport then navigates to the
+ * target URL for that orientation (two full navigations, not a reload), so the
+ * page lays out fresh for each orientation.
+ *
+ * Limitations:
+ * - Heuristics may miss CSS-only orientation restrictions
+ * - Cannot detect JavaScript-based orientation detection without visual indicators
+ * - Manual verification needed for exceptions (e.g., camera apps)
+ */
+import type { Page } from '@playwright/test';
+import type { OrientationCheckResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunOrientationCheckOptions extends OutputLocationOptions {
+    /**
+     * A page to drive. This check navigates the page itself (once per
+     * orientation), so the page does not need to be pre-navigated.
+     */
+    page: Page;
+    /** Target URL to audit. Falls back to the `TEST_PAGE` env var. */
+    targetUrl?: string;
+    /**
+     * Whether to capture portrait/landscape screenshots next to the result file
+     * (default: false).
+     */
+    screenshot?: boolean;
+}
+/**
+ * Run the orientation check, navigating the page in both portrait and landscape,
+ * write the result JSON (and optionally screenshots), and return the parsed
+ * result.
+ */
+export declare function runOrientationCheck(options: RunOrientationCheckOptions): Promise<OrientationCheckResult>;