@a11y-skills/audit 0.1.0 → 0.2.0

package/dist/utils/image-compare.js

@@ -0,0 +1,49 @@
+/**
+ * Image comparison utilities using pixelmatch.
+ *
+ * NOTE: `pixelmatch` and `pngjs` are optional peer/runtime deps (only the
+ * auto-play check needs them). This module top-level imports them, so it must
+ * only be loaded via a dynamic `import()` from `runAutoPlayDetection` — never
+ * statically from the package barrel. That keeps the other checks usable when
+ * the optional deps are absent.
+ */
+import * as fs from 'node:fs';
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+import { PIXELMATCH_THRESHOLD } from '../constants.js';
+/**
+ * Compare two PNG images using pixel-level diff.
+ *
+ * @returns Diff statistics
+ */
+export function compareImages(img1Path, img2Path, diffOutputPath) {
+    const img1 = PNG.sync.read(fs.readFileSync(img1Path));
+    const img2 = PNG.sync.read(fs.readFileSync(img2Path));
+    const { width, height } = img1;
+    const totalPixels = width * height;
+    const diff = new PNG({ width, height });
+    const diffPixels = pixelmatch(img1.data, img2.data, diff.data, width, height, {
+        threshold: PIXELMATCH_THRESHOLD,
+    });
+    fs.writeFileSync(diffOutputPath, PNG.sync.write(diff));
+    const diffPercent = (diffPixels / totalPixels) * 100;
+    return { diffPixels, totalPixels, diffPercent };
+}
+/** Format diff percentage as string with 3 decimal places */
+export function formatDiffPercent(diffPercent) {
+    return diffPercent.toFixed(3) + '%';
+}
+/** Check if change is significant based on threshold */
+export function hasSignificantChange(diffPercent, threshold) {
+    return diffPercent > threshold;
+}
+/** Ensure output directory exists */
+export function ensureOutputDir(outputDir) {
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+}
+/** Save JSON result to file */
+export function saveJsonResult(filePath, data) {
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}

package/dist/utils/recommendations.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Recommendation generation for auto-play detection.
+ */
+import type { PauseControlInfo, PauseVerificationResult } from '../types.js';
+export interface RecommendationContext {
+    hasAutoPlayContent: boolean;
+    stopsWithin5Seconds: boolean;
+    pauseControls: PauseControlInfo;
+    pauseVerification: PauseVerificationResult;
+}
+/**
+ * Generate a recommendation based on detection results.
+ */
+export declare function generateRecommendation(ctx: RecommendationContext): string;
+/**
+ * Print summary to console.
+ */
+export declare function printSummary(ctx: RecommendationContext, outputDir: string): void;

package/dist/utils/recommendations.js

@@ -0,0 +1,88 @@
+/**
+ * Recommendation generation for auto-play detection.
+ */
+/**
+ * Generate a recommendation based on detection results.
+ */
+export function generateRecommendation(ctx) {
+    const { hasAutoPlayContent, stopsWithin5Seconds, pauseControls, pauseVerification } = ctx;
+    if (!hasAutoPlayContent) {
+        return 'No auto-playing content detected in viewport.';
+    }
+    if (stopsWithin5Seconds) {
+        return 'Auto-playing content detected but stops within 5 seconds. WCAG 2.2.2 may be satisfied, but verify no user impact.';
+    }
+    if (pauseControls.found) {
+        if (pauseVerification.pauseWorked === true) {
+            return pauseControls.hasAccessibleName
+                ? 'Auto-playing content detected with working pause control. Verify keyboard accessibility.'
+                : 'Auto-playing content detected. Pause control works but lacks accessible name (aria-label). Add accessible labels (WCAG 4.1.2).';
+        }
+        if (pauseVerification.pauseWorked === false) {
+            return 'Auto-playing content detected. Pause control found but does NOT stop the animation. Fix the control or add a working one (WCAG 1.4.2, 2.2.2).';
+        }
+        // Verification not conclusive
+        return pauseControls.hasAccessibleName
+            ? 'Auto-playing content detected with pause controls. Manually verify controls work and are keyboard accessible.'
+            : 'Auto-playing content detected. Pause control found but lacks accessible name (aria-label). Add accessible labels (WCAG 1.4.2, 2.2.2, 4.1.2).';
+    }
+    return 'Auto-playing content detected and continues beyond 5 seconds. No pause/stop controls found. Add controls (WCAG 1.4.2, 2.2.2).';
+}
+/**
+ * Print summary to console.
+ */
+export function printSummary(ctx, outputDir) {
+    const { hasAutoPlayContent, stopsWithin5Seconds, pauseControls, pauseVerification } = ctx;
+    console.log('\n--- Summary ---');
+    if (!hasAutoPlayContent) {
+        console.log('✓ No auto-playing content detected in viewport');
+        return;
+    }
+    console.log('⚠ Auto-playing content detected!');
+    console.log(`  Stops within 5 seconds: ${stopsWithin5Seconds ? 'Yes' : 'No'}`);
+    console.log(`  Screenshots saved to: ${outputDir}`);
+    console.log('  Diff images generated for visual verification');
+    // Pause control detection
+    console.log('\n--- Pause Control Detection ---');
+    if (pauseControls.found) {
+        console.log(`✓ Pause controls found: ${pauseControls.controls.length}`);
+        pauseControls.controls.forEach((ctrl, i) => {
+            console.log(`  ${i + 1}. <${ctrl.element}> "${ctrl.name}" (matched by: ${ctrl.matchedBy})`);
+        });
+        if (!pauseControls.hasAccessibleName) {
+            console.log('⚠ Warning: Pause control lacks accessible name (aria-label)');
+        }
+    }
+    else {
+        console.log('✗ No pause controls detected');
+    }
+    // Pause verification results
+    if (pauseVerification.attempted) {
+        console.log('\n--- Pause Control Verification ---');
+        console.log(`  Control clicked: ${pauseVerification.controlClicked}`);
+        console.log(`  Change before click: ${pauseVerification.beforeClickDiffPercent}`);
+        console.log(`  Change after click: ${pauseVerification.afterClickDiffPercent}`);
+        if (pauseVerification.pauseWorked === true) {
+            console.log('✓ Pause control WORKS - animation stopped after clicking');
+        }
+        else if (pauseVerification.pauseWorked === false) {
+            console.log('✗ Pause control DOES NOT WORK - animation continues after clicking');
+        }
+        else if (pauseVerification.error) {
+            console.log(`⚠ Verification error: ${pauseVerification.error}`);
+        }
+    }
+    if (pauseControls.carouselIndicators.length > 0) {
+        console.log(`\nCarousel navigation controls found: ${pauseControls.carouselIndicators.length}`);
+    }
+    // Manual verification checklist
+    console.log('\nManual verification required:');
+    console.log('  - Verify pause/stop controls are keyboard accessible');
+    console.log('  - Check for audio auto-play (requires manual listening)');
+    if (!pauseControls.hasAccessibleName && pauseControls.found) {
+        console.log('  - Add aria-label to pause control buttons');
+    }
+    if (pauseVerification.pauseWorked === false) {
+        console.log('  - Fix the pause control to actually stop the animation');
+    }
+}

package/dist/utils/test-harness.d.ts

@@ -66,6 +66,12 @@ export declare function resolveScreenshotPath(resolvedResultPath: string, defaul
  * @throws if neither is provided.
  */
 export declare function requireTargetUrl(explicit?: string): string;
+/**
+ * Resolve the target URL from the `TEST_PAGE` env var, falling back to the
+ * given default. Useful for callers that want a sensible default (e.g. a test
+ * fixture URL or preset) instead of throwing when `TEST_PAGE` is unset.
+ */
+export declare function getTargetUrl(defaultPath: string): string;
 /** Log the header for audit results to console. */
 export declare function logAuditHeader(title: string, wcagRef: string, url: string): void;
 /** Log a summary section with key-value pairs. */

package/dist/utils/test-harness.js

@@ -80,6 +80,14 @@ export function requireTargetUrl(explicit) {
     }
     return url;
 }
+/**
+ * Resolve the target URL from the `TEST_PAGE` env var, falling back to the
+ * given default. Useful for callers that want a sensible default (e.g. a test
+ * fixture URL or preset) instead of throwing when `TEST_PAGE` is unset.
+ */
+export function getTargetUrl(defaultPath) {
+    return process.env.TEST_PAGE || defaultPath;
+}
 // =============================================================================
 // Console Logging
 // =============================================================================

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@a11y-skills/audit",
-  "version": "0.1.0",
-  "description": "Playwright + axe-core based WCAG 2.2 accessibility audit functions (axe, focus indicator, reflow, target size).",
+  "version": "0.2.0",
+  "description": "Playwright + axe-core based WCAG 2.2 accessibility audit functions (axe, focus indicator, reflow, target size, text spacing, zoom, orientation, autocomplete, time limit, auto-play).",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -57,6 +57,30 @@
     "./test-entries/target-size-check": {
       "types": "./dist/test-entries/target-size-check.d.ts",
       "import": "./dist/test-entries/target-size-check.js"
+    },
+    "./test-entries/text-spacing-check": {
+      "types": "./dist/test-entries/text-spacing-check.d.ts",
+      "import": "./dist/test-entries/text-spacing-check.js"
+    },
+    "./test-entries/zoom-200-check": {
+      "types": "./dist/test-entries/zoom-200-check.d.ts",
+      "import": "./dist/test-entries/zoom-200-check.js"
+    },
+    "./test-entries/orientation-check": {
+      "types": "./dist/test-entries/orientation-check.d.ts",
+      "import": "./dist/test-entries/orientation-check.js"
+    },
+    "./test-entries/autocomplete-audit": {
+      "types": "./dist/test-entries/autocomplete-audit.d.ts",
+      "import": "./dist/test-entries/autocomplete-audit.js"
+    },
+    "./test-entries/time-limit-detector": {
+      "types": "./dist/test-entries/time-limit-detector.d.ts",
+      "import": "./dist/test-entries/time-limit-detector.js"
+    },
+    "./test-entries/auto-play-detection": {
+      "types": "./dist/test-entries/auto-play-detection.d.ts",
+      "import": "./dist/test-entries/auto-play-detection.js"
     }
   },
   "files": [
@@ -80,10 +104,15 @@
     "@axe-core/playwright": "^4.10.0",
     "@playwright/test": "^1.50.0"
   },
+  "optionalDependencies": {
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0"
+  },
   "devDependencies": {
     "@axe-core/playwright": "^4.10.0",
     "@playwright/test": "^1.50.0",
     "@types/node": "^22.10.0",
+    "@types/pngjs": "^6.0.5",
     "typescript": "^5.6.0"
   },
   "engines": {