npm - @a11y-skills/audit - Versions diffs - 0.1.0 → 0.3.0 - Mend

@a11y-skills/audit 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (59) hide show

package/CHANGELOG.md +65 -0
package/README.ja.md +76 -6
package/README.md +78 -6
package/dist/constants.d.ts +84 -0
package/dist/constants.js +228 -0
package/dist/detectors/index.d.ts +1 -0
package/dist/detectors/index.js +1 -0
package/dist/detectors/pause-control.d.ts +18 -0
package/dist/detectors/pause-control.js +206 -0
package/dist/index.d.ts +3 -1
package/dist/index.js +3 -1
package/dist/playwright/index.d.ts +7 -1
package/dist/playwright/index.js +7 -1
package/dist/playwright/runAutoPlayDetection.d.ts +36 -0
package/dist/playwright/runAutoPlayDetection.js +143 -0
package/dist/playwright/runAutocompleteAudit.d.ts +27 -0
package/dist/playwright/runAutocompleteAudit.js +227 -0
package/dist/playwright/runAxeAudit.d.ts +4 -0
package/dist/playwright/runAxeAudit.js +26 -30
package/dist/playwright/runFocusIndicatorCheck.js +55 -12
package/dist/playwright/runOrientationCheck.d.ts +40 -0
package/dist/playwright/runOrientationCheck.js +170 -0
package/dist/playwright/runReflowCheck.js +18 -11
package/dist/playwright/runTargetSizeCheck.js +42 -10
package/dist/playwright/runTextSpacingCheck.d.ts +25 -0
package/dist/playwright/runTextSpacingCheck.js +285 -0
package/dist/playwright/runTimeLimitDetector.d.ts +31 -0
package/dist/playwright/runTimeLimitDetector.js +219 -0
package/dist/playwright/runZoomCheck.d.ts +42 -0
package/dist/playwright/runZoomCheck.js +174 -0
package/dist/schemas/index.d.ts +20 -1
package/dist/schemas/index.js +404 -186
package/dist/test-entries/auto-play-detection.d.ts +7 -0
package/dist/test-entries/auto-play-detection.js +13 -0
package/dist/test-entries/autocomplete-audit.d.ts +5 -0
package/dist/test-entries/autocomplete-audit.js +11 -0
package/dist/test-entries/orientation-check.d.ts +8 -0
package/dist/test-entries/orientation-check.js +12 -0
package/dist/test-entries/text-spacing-check.d.ts +5 -0
package/dist/test-entries/text-spacing-check.js +11 -0
package/dist/test-entries/time-limit-detector.d.ts +8 -0
package/dist/test-entries/time-limit-detector.js +12 -0
package/dist/test-entries/zoom-200-check.d.ts +5 -0
package/dist/test-entries/zoom-200-check.js +11 -0
package/dist/types.d.ts +275 -40
package/dist/types.js +9 -0
package/dist/utils/axe-format.d.ts +88 -0
package/dist/utils/axe-format.js +361 -0
package/dist/utils/image-compare.d.ts +24 -0
package/dist/utils/image-compare.js +49 -0
package/dist/utils/layout.d.ts +2 -0
package/dist/utils/layout.js +20 -1
package/dist/utils/recommendations.d.ts +18 -0
package/dist/utils/recommendations.js +88 -0
package/dist/utils/rule-registry.d.ts +216 -0
package/dist/utils/rule-registry.js +220 -0
package/dist/utils/test-harness.d.ts +8 -2
package/dist/utils/test-harness.js +13 -6
package/package.json +32 -2

package/dist/utils/axe-format.js ADDED Viewed

@@ -0,0 +1,361 @@
+/**
+ * Pure mappers from check-specific `details` to the axe-style buckets
+ * (`violations` / `incomplete` / `passes` / `inapplicable`), plus the envelope
+ * assembler and the opt-in cross-check merge.
+ *
+ * Everything here is browser-independent: the runners gather evidence into a
+ * details object, and these functions derive the normalized view from it.
+ * Because the details objects are part of the saved JSON, the buckets can be
+ * re-derived from a result file at any time.
+ */
+import { AUDIT_DISCLAIMER, HTML_SNIPPET_MAX_LENGTH } from '../constants.js';
+import { getRule } from './rule-registry.js';
+function emptyBuckets() {
+    return { violations: [], incomplete: [], passes: [], inapplicable: [] };
+}
+function ruleResult(key, nodes) {
+    const meta = getRule(key);
+    return {
+        id: meta.id,
+        impact: meta.impact,
+        description: meta.description,
+        help: meta.help,
+        helpUrl: meta.helpUrl,
+        tags: [...meta.tags],
+        nodes,
+    };
+}
+/**
+ * Route a rule's findings into the right bucket:
+ * not applicable → `inapplicable`, no findings → `passes`, findings →
+ * the registry's classification (or an explicit override).
+ */
+function bucketize(buckets, key, nodes, applicable, override) {
+    if (!applicable) {
+        buckets.inapplicable.push(ruleResult(key, []));
+        return;
+    }
+    if (nodes.length === 0) {
+        buckets.passes.push(ruleResult(key, []));
+        return;
+    }
+    const classification = override ?? getRule(key).classification;
+    (classification === 'violation' ? buckets.violations : buckets.incomplete).push(ruleResult(key, nodes));
+}
+/** Build a node from element evidence, synthesizing `html` when missing. */
+function toNode(el, failureSummary) {
+    const tag = (el.tagName ?? el.tag ?? 'element').toLowerCase();
+    const html = el.html && el.html.length > 0 ? el.html : `<${tag}>`;
+    return {
+        target: [el.selector],
+        html,
+        htmlTruncated: el.htmlTruncated ?? false,
+        failureSummary,
+    };
+}
+/** Build a page-level node (`target: ['html']`). */
+function pageNode(failureSummary) {
+    return { target: ['html'], html: '<html>', htmlTruncated: false, failureSummary };
+}
+function describeElement(ref) {
+    return `<${ref.tag.toLowerCase()}> "${ref.name}"`;
+}
+// =============================================================================
+// Envelope assembly
+// =============================================================================
+/** Assemble the common envelope from a check's details and buckets. */
+export function buildAuditResult(args) {
+    const { source, url, details, buckets, timestamp } = args;
+    const summary = {
+        violationCount: buckets.violations.length,
+        incompleteCount: buckets.incomplete.length,
+        passCount: buckets.passes.length,
+    };
+    if (buckets.checkedNodes !== undefined) {
+        summary.checkedNodes = buckets.checkedNodes;
+    }
+    return {
+        source,
+        url,
+        timestamp: timestamp ?? new Date().toISOString(),
+        violations: buckets.violations,
+        incomplete: buckets.incomplete,
+        passes: buckets.passes,
+        inapplicable: buckets.inapplicable,
+        summary,
+        details,
+        disclaimer: AUDIT_DISCLAIMER,
+    };
+}
+// =============================================================================
+// Per-check normalizers
+// =============================================================================
+export function normalizeFocusCheck(details) {
+    const buckets = emptyBuckets();
+    const applicable = details.totalFocusableElements > 0;
+    buckets.checkedNodes = details.totalFocusableElements;
+    bucketize(buckets, 'focus-visible', details.issues.map((el) => toNode(el, `${describeElement(el)} shows no computed-style change on focus ` +
+        '(outline, box-shadow, background-color). Verify manually whether a ' +
+        'visual focus indicator exists (pseudo-elements, canvas, or parent ' +
+        'changes are not detected).')), applicable);
+    bucketize(buckets, 'no-context-change-on-focus', details.onFocusViolations.map((v) => toNode(v.element, `Focusing ${describeElement(v.element)} triggered a ${v.changeType} ` +
+        `from ${v.fromUrl} to ${v.toUrl}.`)), applicable);
+    bucketize(buckets, 'focus-not-obscured', details.focusObscuredIssues.map((issue) => toNode(issue.element, `${describeElement(issue.element)} is ${(issue.obscuredRatio * 100).toFixed(0)}% ` +
+        `obscured when focused (by ${issue.overlaps
+            .map((o) => `<${o.obscuredBy.tag.toLowerCase()}>`)
+            .join(', ')}). Verify whether the focused element is hidden.`)), applicable);
+    return buckets;
+}
+export function normalizeReflowCheck(details) {
+    const buckets = emptyBuckets();
+    const overflowNodes = details.overflowingElements.map((el) => toNode(el, `<${el.tagName}> extends to ${el.rect.right}px in a ${el.viewportWidth}px ` +
+        `viewport (${el.reason}). Verify whether a two-dimensional layout ` +
+        'exception (table, map, diagram, ...) applies.'));
+    if (details.hasHorizontalScroll && overflowNodes.length === 0) {
+        overflowNodes.push(pageNode(`Document scrolls horizontally at ${details.viewport.width}px ` +
+            `(scrollWidth ${details.documentScrollWidth}px > clientWidth ` +
+            `${details.documentClientWidth}px). Verify whether an exception applies.`));
+    }
+    bucketize(buckets, 'reflow-overflow', overflowNodes, true);
+    bucketize(buckets, 'reflow-clipped-text', details.clippedTextElements.map((el) => toNode(el, `<${el.tagName}> clips its text at ${details.viewport.width}px ` +
+        `(scrollWidth ${el.scrollWidth}px > clientWidth ${el.clientWidth}px, ` +
+        `overflow: ${el.overflow}). Verify whether content is lost.`)), true);
+    return buckets;
+}
+export function normalizeTargetSizeCheck(details) {
+    const buckets = emptyBuckets();
+    const applicable = details.totalTargetsChecked > 0;
+    buckets.checkedNodes = details.totalTargetsChecked;
+    const minimumFailureSummary = (issue) => {
+        const base = `Target is ${issue.width}x${issue.height}px ` +
+            `(min dimension ${issue.minDimension}px, requirement 24px).`;
+        if (issue.exception) {
+            return (`${base} Possible '${issue.exception}' exception: ` +
+                `${issue.exceptionDetails ?? 'see manual review notes'}. Confirm manually.`);
+        }
+        return `${base} No exception detected, but the essential exception cannot be ruled out automatically.`;
+    };
+    // Minimum (2.5.8 AA): findings are fail-aa targets, with and without
+    // detected exceptions. Only 'ruled-out' assessments are confirmed violations.
+    const minimumIssues = [...details.failAA, ...details.exceptedTargets].filter((issue) => issue.level === 'fail-aa');
+    const confirmed = minimumIssues.filter((i) => i.exceptionAssessment === 'ruled-out');
+    const needsReview = minimumIssues.filter((i) => i.exceptionAssessment !== 'ruled-out');
+    if (!applicable) {
+        buckets.inapplicable.push(ruleResult('target-size-minimum', []));
+    }
+    else if (minimumIssues.length === 0) {
+        buckets.passes.push(ruleResult('target-size-minimum', []));
+    }
+    else {
+        if (confirmed.length > 0) {
+            buckets.violations.push(ruleResult('target-size-minimum', confirmed.map((i) => toNode(i, minimumFailureSummary(i)))));
+        }
+        if (needsReview.length > 0) {
+            buckets.incomplete.push(ruleResult('target-size-minimum', needsReview.map((i) => toNode(i, minimumFailureSummary(i)))));
+        }
+    }
+    // Enhanced (2.5.5 AAA): targets that pass AA but miss the 44px requirement.
+    // Targets already failing AA are reported under target-size-minimum only.
+    bucketize(buckets, 'target-size-enhanced', details.failAAAOnly.map((issue) => toNode(issue, `Target is ${issue.width}x${issue.height}px ` +
+        `(min dimension ${issue.minDimension}px, AAA requirement 44px). ` +
+        'Verify whether an SC 2.5.5 exception applies.')), applicable);
+    return buckets;
+}
+export function normalizeTextSpacingCheck(details) {
+    const buckets = emptyBuckets();
+    buckets.checkedNodes = details.totalElementsChecked;
+    bucketize(buckets, 'text-spacing', details.clippedElements.map((el) => toNode(el, `<${el.tagName}> clips its content (${el.issueType}) when WCAG 1.4.12 ` +
+        `text spacing is applied: ${el.afterMetrics.scrollWidth}x${el.afterMetrics.scrollHeight}px ` +
+        `content in a ${el.afterMetrics.clientWidth}x${el.afterMetrics.clientHeight}px box.`)), details.totalElementsChecked > 0);
+    return buckets;
+}
+export function normalizeZoomCheck(details) {
+    const buckets = emptyBuckets();
+    const nodes = details.clippedElements.map((el) => toNode(el, `<${el.tagName}> ${el.issueType === 'horizontal-scroll' ? 'overflows horizontally' : 'clips its content'} ` +
+        `at ${details.zoomFactor * 100}% zoom (scrollWidth ${el.scrollWidth}px > ` +
+        `clientWidth ${el.clientWidth}px). Verify whether content or ` +
+        'functionality is lost.'));
+    if (details.hasHorizontalScroll && nodes.length === 0) {
+        nodes.push(pageNode(`Document scrolls horizontally at ${details.zoomFactor * 100}% zoom ` +
+            `(scrollWidth ${details.documentScrollWidth}px > clientWidth ` +
+            `${details.documentClientWidth}px). Horizontal scrolling alone does ` +
+            'not fail SC 1.4.4 — verify whether text becomes unusable.'));
+    }
+    bucketize(buckets, 'resize-text', nodes, true);
+    return buckets;
+}
+export function normalizeOrientationCheck(details) {
+    const buckets = emptyBuckets();
+    const nodes = [];
+    if (details.hasOrientationLock) {
+        const state = details.lockDetectedIn === 'landscape' ? details.landscape : details.portrait;
+        const messagePart = state.lockMessageText
+            ? ` Lock message found: "${state.lockMessageText}".`
+            : '';
+        nodes.push(pageNode(`Content appears restricted to a single orientation ` +
+            `(detected in: ${details.lockDetectedIn}).${messagePart} Verify ` +
+            'whether the essential exception (SC 1.3.4) applies.'));
+    }
+    bucketize(buckets, 'orientation-lock', nodes, true);
+    return buckets;
+}
+export function normalizeAutocompleteAudit(details) {
+    const buckets = emptyBuckets();
+    const applicable = details.totalFieldsChecked > 0;
+    buckets.checkedNodes = details.totalFieldsChecked;
+    bucketize(buckets, 'autocomplete-invalid', details.invalidAutocomplete.map((field) => toNode(field, `autocomplete="${field.currentAutocomplete}" is not a valid token. ` +
+        `Expected "${field.expectedToken}" (purpose matched by ${field.matchedBy}).`)), applicable);
+    bucketize(buckets, 'autocomplete-missing', details.missingAutocomplete.map((field) => toNode(field, `Field appears to collect "${field.expectedToken}" (matched by ` +
+        `${field.matchedBy}) but has ${field.currentAutocomplete === null
+            ? 'no autocomplete attribute'
+            : `autocomplete="${field.currentAutocomplete}"`}. Confirm the field purpose manually.`)), applicable);
+    return buckets;
+}
+export function normalizeTimeLimitDetector(details) {
+    const buckets = emptyBuckets();
+    bucketize(buckets, 'meta-refresh', details.metaRefresh.map((meta) => ({
+        target: ['meta[http-equiv="refresh"]'],
+        html: meta.html || `<meta http-equiv="refresh" content="${meta.content}">`,
+        htmlTruncated: meta.htmlTruncated ?? false,
+        failureSummary: `Page refreshes${meta.url ? ` to ${meta.url}` : ''} after ${meta.seconds}s. ` +
+            'Verify whether the time limit can be turned off, adjusted, or extended, ' +
+            'or whether an SC 2.2.1 exception (e.g. over 20 hours) applies.',
+    })), true);
+    bucketize(buckets, 'time-limit-timer', details.timers.map((timer) => pageNode(`${timer.type} with a ${timer.delayMs}ms delay detected` +
+        `${timer.callStack ? ` (${timer.callStack.split('\n')[0]?.trim()})` : ''}. ` +
+        'Verify whether it implements a time limit and is adjustable.')), true);
+    bucketize(buckets, 'time-limit-countdown', details.countdownIndicators.map((indicator) => toNode(indicator, `Countdown/timeout wording found: "${indicator.text.slice(0, 80)}". ` +
+        'Verify whether it indicates an adjustable time limit.')), true);
+    return buckets;
+}
+export function normalizeAutoPlayDetection(details) {
+    const buckets = emptyBuckets();
+    const nodes = [];
+    if (details.hasAutoPlayContent && !details.stopsWithin5Seconds) {
+        const controlsPart = details.pauseControls.found
+            ? `Pause controls found (${details.pauseControls.controls.length}); ` +
+                `pause verified working: ${details.pauseVerification.pauseWorked ?? 'unknown'}.`
+            : 'No pause controls found.';
+        nodes.push(pageNode(`Moving content continues past 5 seconds (pixel-diff detection). ` +
+            `${controlsPart} ${details.recommendation} Verify the content type ` +
+            'and audio manually.'));
+    }
+    bucketize(buckets, 'auto-play', nodes, true);
+    return buckets;
+}
+function normalizeAxeRule(rule, includeNodes) {
+    return {
+        id: rule.id,
+        impact: (rule.impact ?? null),
+        description: rule.description,
+        help: rule.help,
+        helpUrl: rule.helpUrl,
+        tags: [...rule.tags],
+        nodes: includeNodes
+            ? rule.nodes.map((n) => {
+                const truncated = n.html.length > HTML_SNIPPET_MAX_LENGTH;
+                return {
+                    target: n.target.map((t) => String(t)),
+                    html: truncated ? n.html.slice(0, HTML_SNIPPET_MAX_LENGTH) : n.html,
+                    htmlTruncated: truncated,
+                    failureSummary: n.failureSummary ?? '',
+                };
+            })
+            : [],
+    };
+}
+/**
+ * Normalize raw axe-core results into the common buckets. Must be fed the RAW
+ * `AxeResults` (before any reduction) — pass/incomplete details are not
+ * recoverable afterwards. Node lists are kept for violations and incomplete;
+ * passes/inapplicable carry rule metadata only.
+ */
+export function normalizeAxeResults(raw) {
+    return {
+        violations: raw.violations.map((r) => normalizeAxeRule(r, true)),
+        incomplete: raw.incomplete.map((r) => normalizeAxeRule(r, true)),
+        passes: raw.passes.map((r) => normalizeAxeRule(r, false)),
+        inapplicable: raw.inapplicable.map((r) => normalizeAxeRule(r, false)),
+    };
+}
+const BUCKETS = ['violations', 'incomplete', 'passes', 'inapplicable'];
+/**
+ * Merge several check results for the same URL into one normalized view.
+ *
+ * - Results with differing URLs are rejected (throws).
+ * - The same rule id is merged into one entry; nodes are deduplicated by
+ *   `target` + `failureSummary`. Identical selectors inside different frames
+ *   or shadow roots are NOT distinguished.
+ * - A rule appearing in several buckets is placed in the highest-priority one:
+ *   violations > incomplete > passes > inapplicable.
+ */
+export function mergeNormalizedResults(results) {
+    if (results.length === 0) {
+        throw new Error('mergeNormalizedResults requires at least one result.');
+    }
+    const first = results[0];
+    const mismatch = results.find((r) => r.url !== first.url);
+    if (mismatch) {
+        throw new Error(`mergeNormalizedResults: URL mismatch — "${first.url}" vs "${mismatch.url}". ` +
+            'Merge only results for the same page.');
+    }
+    const byId = new Map();
+    const nodeKey = (n) => `${JSON.stringify(n.target)}|${n.failureSummary}`;
+    for (const result of results) {
+        BUCKETS.forEach((bucket, bucketIndex) => {
+            for (const rule of result[bucket]) {
+                let entry = byId.get(rule.id);
+                if (!entry) {
+                    entry = {
+                        bucketIndex,
+                        rule: { ...rule, nodes: [] },
+                        nodeKeys: new Set(),
+                    };
+                    byId.set(rule.id, entry);
+                }
+                entry.bucketIndex = Math.min(entry.bucketIndex, bucketIndex);
+                for (const node of rule.nodes) {
+                    const key = nodeKey(node);
+                    if (!entry.nodeKeys.has(key)) {
+                        entry.nodeKeys.add(key);
+                        entry.rule.nodes.push(node);
+                    }
+                }
+            }
+        });
+    }
+    const merged = {
+        violations: [],
+        incomplete: [],
+        passes: [],
+        inapplicable: [],
+    };
+    for (const entry of byId.values()) {
+        merged[BUCKETS[entry.bucketIndex]].push(entry.rule);
+    }
+    const latestTimestamp = results
+        .map((r) => r.timestamp)
+        .sort()
+        .at(-1);
+    const checkedNodes = results.reduce((sum, r) => {
+        if (r.summary.checkedNodes === undefined)
+            return sum;
+        return (sum ?? 0) + r.summary.checkedNodes;
+    }, undefined);
+    const summary = {
+        violationCount: merged.violations.length,
+        incompleteCount: merged.incomplete.length,
+        passCount: merged.passes.length,
+    };
+    if (checkedNodes !== undefined) {
+        summary.checkedNodes = checkedNodes;
+    }
+    return {
+        url: first.url,
+        timestamp: latestTimestamp,
+        sources: [...new Set(results.map((r) => r.source))],
+        ...merged,
+        summary,
+        disclaimer: AUDIT_DISCLAIMER,
+    };
+}

package/dist/utils/image-compare.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/**
+ * 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 type { ImageDiffResult } from '../types.js';
+/**
+ * Compare two PNG images using pixel-level diff.
+ *
+ * @returns Diff statistics
+ */
+export declare function compareImages(img1Path: string, img2Path: string, diffOutputPath: string): ImageDiffResult;
+/** Format diff percentage as string with 3 decimal places */
+export declare function formatDiffPercent(diffPercent: number): string;
+/** Check if change is significant based on threshold */
+export declare function hasSignificantChange(diffPercent: number, threshold: number): boolean;
+/** Ensure output directory exists */
+export declare function ensureOutputDir(outputDir: string): void;
+/** Save JSON result to file */
+export declare function saveJsonResult(filePath: string, data: unknown): void;

package/dist/utils/image-compare.js ADDED Viewed

@@ -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/layout.d.ts CHANGED Viewed

@@ -8,6 +8,8 @@ export interface LayoutCheckOptions {
     overflowTolerance: number;
     checkSelector: string;
     allowedOverflowSelectors: readonly string[];
+    /** Maximum length of captured outerHTML snippets. */
+    htmlSnippetMaxLength: number;
 }
 export interface LayoutCheckResult {
     hasHorizontalScroll: boolean;

package/dist/utils/layout.js CHANGED Viewed

@@ -7,7 +7,23 @@
  * This is serialized and executed in the browser context.
  */
 export function createLayoutChecker(options) {
-    const { viewportWidth, overflowTolerance, checkSelector, allowedOverflowSelectors, } = options;
+    const { viewportWidth, overflowTolerance, checkSelector, allowedOverflowSelectors, htmlSnippetMaxLength, } = options;
+    function getHtmlSnippet(element) {
+        let html = '';
+        try {
+            html = element.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return { html: `<${element.tagName.toLowerCase()}>`, htmlTruncated: false };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    }
     // Helper functions (must be defined inside for browser context)
     /**
      * Generate a unique CSS selector for an element using index-based approach
@@ -76,6 +92,7 @@ export function createLayoutChecker(options) {
             overflowingElements.push({
                 selector,
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 rect: {
                     left: Math.round(rect.left),
                     right: Math.round(rect.right),
@@ -91,6 +108,7 @@ export function createLayoutChecker(options) {
             overflowingElements.push({
                 selector,
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 rect: {
                     left: Math.round(rect.left),
                     right: Math.round(rect.right),
@@ -123,6 +141,7 @@ export function createLayoutChecker(options) {
                     clippedTextElements.push({
                         selector,
                         tagName: element.tagName.toLowerCase(),
+                        ...getHtmlSnippet(element),
                         scrollWidth,
                         clientWidth,
                         scrollHeight,

package/dist/utils/recommendations.d.ts ADDED Viewed

@@ -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 ADDED Viewed

@@ -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');
+    }
+}