@a11y-skills/audit 0.1.0 → 0.3.0

package/dist/playwright/runAutoPlayDetection.js

@@ -0,0 +1,143 @@
+/**
+ * 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 { buildAuditResult, normalizeAutoPlayDetection, } from '../utils/axe-format.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 details = {
+        screenshotRecords: screenshots,
+        comparisons,
+        hasAutoPlayContent: hasAnyChange,
+        stopsWithin5Seconds,
+        pauseControls,
+        pauseVerification,
+        recommendation: generateRecommendation({
+            hasAutoPlayContent: hasAnyChange,
+            stopsWithin5Seconds,
+            pauseControls,
+            pauseVerification,
+        }),
+    };
+    const result = buildAuditResult({
+        source: 'auto-play-detection',
+        url: page.url(),
+        details,
+        buckets: normalizeAutoPlayDetection(details),
+    });
+    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,227 @@
+/**
+ * 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, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeAutocompleteAudit, } from '../utils/axe-format.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(args) {
+    const { htmlSnippetMaxLength } = args;
+    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 };
+    }
+    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(),
+            ...getHtmlSnippet(element),
+            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,
+                html: field.html,
+                htmlTruncated: field.htmlTruncated,
+                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,
+                html: field.html,
+                htmlTruncated: field.htmlTruncated,
+                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, {
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
+    });
+    // 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 details = {
+        totalFieldsChecked: fields.length,
+        missingAutocomplete: missing,
+        invalidAutocomplete: invalid,
+    };
+    const result = buildAuditResult({
+        source: 'autocomplete-audit',
+        url: page.url(),
+        details,
+        buckets: normalizeAutocompleteAudit(details),
+    });
+    // Output results
+    logAuditHeader('Autocomplete Audit Results', 'WCAG 1.3.5', result.url);
+    logSummary({
+        'Total form fields': details.totalFieldsChecked,
+        'Fields missing autocomplete': details.missingAutocomplete.length,
+        'Fields with invalid autocomplete': details.invalidAutocomplete.length,
+    });
+    logIssueList('Missing Autocomplete', details.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', details.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/runAxeAudit.d.ts

@@ -5,6 +5,10 @@
  * caller is responsible for navigating the page (e.g. `await page.goto(url)`)
  * before calling this function.
  *
+ * The normalized buckets are built from the RAW axe results (violations and
+ * incomplete keep their nodes; passes/inapplicable keep rule metadata only),
+ * and `details` records the execution configuration.
+ *
  * Axe-core cannot detect all accessibility issues — manual testing and the
  * other checks in this package are still needed for complete coverage.
  */

package/dist/playwright/runAxeAudit.js

@@ -5,11 +5,16 @@
  * caller is responsible for navigating the page (e.g. `await page.goto(url)`)
  * before calling this function.
  *
+ * The normalized buckets are built from the RAW axe results (violations and
+ * incomplete keep their nodes; passes/inapplicable keep rule metadata only),
+ * and `details` records the execution configuration.
+ *
  * Axe-core cannot detect all accessibility issues — manual testing and the
  * other checks in this package are still needed for complete coverage.
  */
 import { AxeBuilder } from '@axe-core/playwright';
-import { AUDIT_DISCLAIMER, DEFAULT_AXE_TAGS, DEFAULT_AXE_RESULT_FILE, } from '../constants.js';
+import { DEFAULT_AXE_TAGS, DEFAULT_AXE_RESULT_FILE } from '../constants.js';
+import { buildAuditResult, normalizeAxeResults } from '../utils/axe-format.js';
 import { saveAuditResult, logAuditHeader, logSummary, logOutputPaths, } from '../utils/test-harness.js';
 /**
  * Run an axe-core audit against the current page, write the result JSON, and
@@ -22,36 +27,29 @@ export async function runAxeAudit(options) {
         builder = builder.options({ rules });
     }
     const axeResults = await builder.analyze();
-    const result = {
-        url: page.url(),
-        timestamp: new Date().toISOString(),
-        violations: axeResults.violations.map((v) => ({
-            id: v.id,
-            impact: v.impact ?? null,
-            description: v.description,
-            help: v.help,
-            helpUrl: v.helpUrl,
-            tags: v.tags,
-            nodes: v.nodes.map((n) => ({
-                html: n.html,
-                target: n.target,
-                failureSummary: n.failureSummary,
-            })),
-        })),
-        passes: axeResults.passes.length,
-        incomplete: axeResults.incomplete.length,
-        inapplicable: axeResults.inapplicable.length,
-        violationCount: axeResults.violations.length,
-        disclaimer: AUDIT_DISCLAIMER,
+    const buckets = normalizeAxeResults(axeResults);
+    const details = {
+        tagsRun: [...tags],
+        rulesOverride: rules ?? null,
+        violationRuleCount: axeResults.violations.length,
+        passRuleCount: axeResults.passes.length,
+        incompleteRuleCount: axeResults.incomplete.length,
+        inapplicableRuleCount: axeResults.inapplicable.length,
     };
+    const result = buildAuditResult({
+        source: 'axe-audit',
+        url: page.url(),
+        details,
+        buckets,
+    });
     // Output results
     logAuditHeader('Axe-core Accessibility Audit Results', 'axe-core', result.url);
     logSummary({
         Timestamp: result.timestamp,
-        Violations: result.violationCount,
-        Passes: result.passes,
-        'Incomplete (needs review)': result.incomplete,
-        Inapplicable: result.inapplicable,
+        Violations: result.summary.violationCount,
+        Passes: result.summary.passCount,
+        'Incomplete (needs review)': result.summary.incompleteCount,
+        Inapplicable: result.inapplicable.length,
     });
     if (result.violations.length > 0) {
         console.log('\n--- Violations ---');
@@ -71,18 +69,16 @@ export async function runAxeAudit(options) {
         });
     }
     console.log(`\n--- Summary ---`);
-    if (result.violationCount === 0) {
+    if (result.summary.violationCount === 0) {
         console.log('No violations detected by axe-core');
     }
     else {
         const totalElements = result.violations.reduce((sum, v) => sum + v.nodes.length, 0);
-        console.log(`Found ${result.violationCount} violation type(s) affecting ${totalElements} element(s)`);
+        console.log(`Found ${result.summary.violationCount} violation type(s) affecting ${totalElements} element(s)`);
     }
-    // axe results already carry the disclaimer field; don't append it again.
     const resolvedPath = saveAuditResult(result, {
         ...location,
         defaultFile: DEFAULT_AXE_RESULT_FILE,
-        includeDisclaimer: false,
     });
     logOutputPaths(resolvedPath);
     return result;

package/dist/playwright/runFocusIndicatorCheck.js

@@ -10,7 +10,8 @@
  *
  * The context this function creates is closed before it returns.
  */
-import { FOCUSABLE_SELECTOR, FOCUS_STYLE_PROPERTIES, EXTRA_TAB_ITERATIONS, DEFAULT_FOCUS_RESULT_FILE, DEFAULT_FOCUS_SCREENSHOT_FILE, FOCUS_OBSCURED_MIN_OVERLAP_RATIO, FOCUS_OBSCURED_MIN_OVERLAP_PX, FOCUS_OBSCURED_EXCLUDE_SELECTORS, } from '../constants.js';
+import { FOCUSABLE_SELECTOR, FOCUS_STYLE_PROPERTIES, EXTRA_TAB_ITERATIONS, DEFAULT_FOCUS_RESULT_FILE, DEFAULT_FOCUS_SCREENSHOT_FILE, FOCUS_OBSCURED_MIN_OVERLAP_RATIO, FOCUS_OBSCURED_MIN_OVERLAP_PX, FOCUS_OBSCURED_EXCLUDE_SELECTORS, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeFocusCheck } from '../utils/axe-format.js';
 import { resolveOutputPath, resolveScreenshotPath, saveAuditResult, takeAuditScreenshot, requireTargetUrl, logAuditHeader, logOutputPaths, } from '../utils/test-harness.js';
 // =============================================================================
 // Browser-injected styles for marking elements
@@ -106,6 +107,8 @@ export async function runFocusIndicatorCheck(options) {
                     name: data.name,
                     selector: data.selector ||
                         `${data.tag.toLowerCase()}:nth-of-type(${data.id + 1})`,
+                    html: data.html,
+                    htmlTruncated: data.htmlTruncated,
                 };
             });
             // Expose function to receive focus obscured reports (WCAG 2.4.12)
@@ -118,6 +121,7 @@ export async function runFocusIndicatorCheck(options) {
                 styleProperties: [...FOCUS_STYLE_PROPERTIES],
                 warningStyles: WARNING_STYLES,
                 skipSelectors: [...skipSelectors],
+                htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
                 obscuredConfig: {
                     minOverlapRatio: FOCUS_OBSCURED_MIN_OVERLAP_RATIO,
                     minOverlapPx: FOCUS_OBSCURED_MIN_OVERLAP_PX,
@@ -163,7 +167,7 @@ export async function runFocusIndicatorCheck(options) {
                 // Get currently focused element IMMEDIATELY after Tab
                 let currentFocusedElement = null;
                 try {
-                    currentFocusedElement = await page.evaluate(() => {
+                    currentFocusedElement = await page.evaluate((htmlSnippetMaxLength) => {
                         const el = document.activeElement;
                         if (!el || el === document.body)
                             return null;
@@ -180,6 +184,17 @@ export async function runFocusIndicatorCheck(options) {
                             const index = siblings.indexOf(element) + 1;
                             return `${getSelector(parent)} > ${tag}:nth-of-type(${index})`;
                         };
+                        let html = '';
+                        try {
+                            html = el.outerHTML || '';
+                        }
+                        catch {
+                            html = '';
+                        }
+                        if (!html) {
+                            html = `<${el.tagName.toLowerCase()}>`;
+                        }
+                        const htmlTruncated = html.length > htmlSnippetMaxLength;
                         return {
                             tag: el.tagName,
                             role: el.getAttribute('role'),
@@ -187,8 +202,10 @@ export async function runFocusIndicatorCheck(options) {
                                 el.textContent?.slice(0, 30) ||
                                 '',
                             selector: getSelector(el),
+                            html: htmlTruncated ? html.slice(0, htmlSnippetMaxLength) : html,
+                            htmlTruncated,
                         };
-                    });
+                    }, HTML_SNIPPET_MAX_LENGTH);
                 }
                 catch {
                     // Page might have navigated, use lastFocusedElement as fallback
@@ -248,8 +265,7 @@ export async function runFocusIndicatorCheck(options) {
             console.warn('Elements without visible focus indicator:', elementsWithoutFocusStyle);
         }
         // Build result
-        const result = {
-            url: finalPage.url(),
+        const details = {
             totalFocusableElements: finalFocusHistory.length,
             elementsWithFocusStyle: finalFocusHistory.length - elementsWithoutFocusStyle.length,
             elementsWithoutFocusStyle: elementsWithoutFocusStyle.length,
@@ -257,6 +273,9 @@ export async function runFocusIndicatorCheck(options) {
                 tag: el.tag,
                 role: el.role,
                 name: el.name,
+                selector: el.selector,
+                html: el.html,
+                htmlTruncated: el.htmlTruncated,
             })),
             onFocusViolations,
             focusObscuredIssues,
@@ -265,12 +284,18 @@ export async function runFocusIndicatorCheck(options) {
             interrupted: false,
             screenshotPath: screenshot ? resolvedScreenshotPath : '',
         };
+        const result = buildAuditResult({
+            source: 'focus-indicator-check',
+            url: finalPage.url(),
+            details,
+            buckets: normalizeFocusCheck(details),
+        });
         // Output results
-        logAuditHeader('Focus Indicator Check Results', 'WCAG 2.4.7 / 2.4.12 / 3.2.1', result.url);
-        console.log(`Total focusable elements: ${result.totalFocusableElements}`);
-        console.log(`Elements with focus style: ${result.elementsWithFocusStyle}`);
-        console.log(`Elements WITHOUT focus style: ${result.elementsWithoutFocusStyle}`);
-        console.log(`Elements with OBSCURED focus: ${result.elementsWithObscuredFocus}`);
+        logAuditHeader('Focus Indicator Check Results', 'WCAG 2.4.7 / 2.4.11 / 3.2.1', result.url);
+        console.log(`Total focusable elements: ${details.totalFocusableElements}`);
+        console.log(`Elements with focus style: ${details.elementsWithFocusStyle}`);
+        console.log(`Elements WITHOUT focus style: ${details.elementsWithoutFocusStyle}`);
+        console.log(`Elements with OBSCURED focus: ${details.elementsWithObscuredFocus}`);
         if (retryCount > 0) {
             console.log(`\nTest restarted ${retryCount} time(s) due to navigation violations`);
         }
@@ -328,7 +353,23 @@ export async function runFocusIndicatorCheck(options) {
 // Browser-injected script factory
 // =============================================================================
 function createFocusTrackerScript(args) {
-    const { focusableSelector, styleProperties, warningStyles, skipSelectors, obscuredConfig } = args;
+    const { focusableSelector, styleProperties, warningStyles, skipSelectors, htmlSnippetMaxLength, obscuredConfig, } = args;
+    const getHtmlSnippet = (el) => {
+        let html = '';
+        try {
+            html = el.outerHTML || '';
+        }
+        catch {
+            html = '';
+        }
+        if (!html) {
+            return { html: `<${el.tagName.toLowerCase()}>`, htmlTruncated: false };
+        }
+        if (html.length > htmlSnippetMaxLength) {
+            return { html: html.slice(0, htmlSnippetMaxLength), htmlTruncated: true };
+        }
+        return { html, htmlTruncated: false };
+    };
     // Add warning styles
     const styleSheet = new CSSStyleSheet();
     document.adoptedStyleSheets = [...document.adoptedStyleSheets, styleSheet];
@@ -658,6 +699,7 @@ function createFocusTrackerScript(args) {
                         focusedEl.textContent?.slice(0, 30) ||
                         '',
                     selector: getSelector(focusedEl),
+                    ...getHtmlSnippet(focusedEl),
                 },
                 elementRect: {
                     left: focusedRect.left,
@@ -729,10 +771,11 @@ function createFocusTrackerScript(args) {
             id,
             tag: el.tagName,
             role: el.getAttribute('role'),
-            name: el.getAttribute('aria-label') || el.textContent?.slice(0, 30),
+            name: el.getAttribute('aria-label') || el.textContent?.slice(0, 30) || '',
             hasFocusStyle,
             diff,
             selector: elementSelectors.get(el) || getSelector(el),
+            ...getHtmlSnippet(el),
         });
         // Check for WCAG 2.4.12 - focus obscured by fixed/sticky elements
         checkFocusObscured(el);