@a11y-skills/audit 0.2.0 → 0.3.0

package/dist/playwright/runOrientationCheck.js

@@ -16,6 +16,7 @@
  * - Manual verification needed for exceptions (e.g., camera apps)
  */
 import { ORIENTATION_VIEWPORTS, ORIENTATION_LOCK_KEYWORDS, MAIN_CONTENT_SELECTORS, DEFAULT_ORIENTATION_RESULT_FILE, DEFAULT_ORIENTATION_PORTRAIT_SCREENSHOT_FILE, DEFAULT_ORIENTATION_LANDSCAPE_SCREENSHOT_FILE, } from '../constants.js';
+import { buildAuditResult, normalizeOrientationCheck, } from '../utils/axe-format.js';
 import { saveAuditResult, resolveOutputPath, takeAuditScreenshot, resolveScreenshotPath, requireTargetUrl, logAuditHeader, logOutputPaths, } from '../utils/test-harness.js';
 /** Capture orientation state in browser context. */
 function captureOrientationState(args) {
@@ -137,20 +138,25 @@ export async function runOrientationCheck(options) {
     const landscapeHasLock = landscapeState.lockMessageFound || landscapeState.mainContentHidden;
     const hasOrientationLock = portraitHasLock || landscapeHasLock;
     const lockDetectedIn = determineLockLocation(portraitHasLock, landscapeHasLock);
-    const result = {
-        url: page.url(),
+    const details = {
         portrait: portraitState,
         landscape: landscapeState,
         hasOrientationLock,
         lockDetectedIn,
     };
+    const result = buildAuditResult({
+        source: 'orientation-check',
+        url: page.url(),
+        details,
+        buckets: normalizeOrientationCheck(details),
+    });
     // Output results
     logAuditHeader('Orientation Check Results', 'WCAG 1.3.4', result.url);
-    logOrientationState('Portrait', ORIENTATION_VIEWPORTS.portrait, result.portrait);
-    logOrientationState('Landscape', ORIENTATION_VIEWPORTS.landscape, result.landscape);
-    console.log(`\nOrientation lock detected: ${result.hasOrientationLock ? 'YES' : 'No'}`);
-    if (result.hasOrientationLock) {
-        console.log(`Lock detected in: ${result.lockDetectedIn}`);
+    logOrientationState('Portrait', ORIENTATION_VIEWPORTS.portrait, details.portrait);
+    logOrientationState('Landscape', ORIENTATION_VIEWPORTS.landscape, details.landscape);
+    console.log(`\nOrientation lock detected: ${details.hasOrientationLock ? 'YES' : 'No'}`);
+    if (details.hasOrientationLock) {
+        console.log(`Lock detected in: ${details.lockDetectedIn}`);
     }
     const writtenPath = saveAuditResult(result, {
         ...location,

package/dist/playwright/runReflowCheck.js

@@ -13,8 +13,9 @@
  * - Cannot distinguish acceptable horizontal scroll (e.g., data tables)
  * - Does not verify functional reflow for complex widgets
  */
-import { REFLOW_VIEWPORT, REFLOW_OVERFLOW_TOLERANCE, REFLOW_CHECK_SELECTOR, REFLOW_ALLOWED_OVERFLOW_SELECTORS, DEFAULT_REFLOW_RESULT_FILE, DEFAULT_REFLOW_SCREENSHOT_FILE, } from '../constants.js';
+import { REFLOW_VIEWPORT, REFLOW_OVERFLOW_TOLERANCE, REFLOW_CHECK_SELECTOR, REFLOW_ALLOWED_OVERFLOW_SELECTORS, DEFAULT_REFLOW_RESULT_FILE, DEFAULT_REFLOW_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
 import { createLayoutChecker } from '../utils/layout.js';
+import { buildAuditResult, normalizeReflowCheck } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /**
  * Run the reflow check against the current page, write the result JSON
@@ -28,27 +29,33 @@ export async function runReflowCheck(options) {
         overflowTolerance,
         checkSelector: REFLOW_CHECK_SELECTOR,
         allowedOverflowSelectors: [...REFLOW_ALLOWED_OVERFLOW_SELECTORS],
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
-    const result = {
-        url: page.url(),
+    const details = {
         viewport: { width: viewport.width, height: viewport.height },
         ...layoutResult,
     };
+    const result = buildAuditResult({
+        source: 'reflow-check',
+        url: page.url(),
+        details,
+        buckets: normalizeReflowCheck(details),
+    });
     // Output results
     logAuditHeader('Reflow Check Results', 'WCAG 1.4.10', result.url);
     logSummary({
-        Viewport: `${result.viewport.width}x${result.viewport.height}`,
-        'Document scroll width': `${result.documentScrollWidth}px`,
-        'Document client width': `${result.documentClientWidth}px`,
-        'Horizontal scroll': result.hasHorizontalScroll,
-        'Overflowing elements': result.overflowingElements.length,
-        'Clipped text elements': result.clippedTextElements.length,
+        Viewport: `${details.viewport.width}x${details.viewport.height}`,
+        'Document scroll width': `${details.documentScrollWidth}px`,
+        'Document client width': `${details.documentClientWidth}px`,
+        'Horizontal scroll': details.hasHorizontalScroll,
+        'Overflowing elements': details.overflowingElements.length,
+        'Clipped text elements': details.clippedTextElements.length,
     });
-    logIssueList('Overflowing Elements', result.overflowingElements, (el, i) => [
+    logIssueList('Overflowing Elements', details.overflowingElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   rect.right: ${el.rect.right}px (viewport: ${el.viewportWidth}px)`,
     ]);
-    logIssueList('Clipped Text Elements', result.clippedTextElements, (el, i) => [
+    logIssueList('Clipped Text Elements', details.clippedTextElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   scrollWidth: ${el.scrollWidth}px, clientWidth: ${el.clientWidth}px`,
         `   overflow: ${el.overflow}, overflowX: ${el.overflowX}`,

package/dist/playwright/runTargetSizeCheck.js

@@ -15,13 +15,31 @@
  * - Cannot detect all redundant target cases
  * - CSS transform may affect measurements
  */
-import { INTERACTIVE_SELECTOR, TARGET_SIZE_AA, TARGET_SIZE_AAA, INLINE_CONTEXT_TAGS, UA_CONTROLLED_INPUT_TYPES, INLINE_CONTEXT_MIN_TEXT, DEFAULT_TARGET_SIZE_RESULT_FILE, DEFAULT_TARGET_SIZE_SCREENSHOT_FILE, } from '../constants.js';
+import { INTERACTIVE_SELECTOR, TARGET_SIZE_AA, TARGET_SIZE_AAA, INLINE_CONTEXT_TAGS, UA_CONTROLLED_INPUT_TYPES, INLINE_CONTEXT_MIN_TEXT, DEFAULT_TARGET_SIZE_RESULT_FILE, DEFAULT_TARGET_SIZE_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTargetSizeCheck, } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 import { addPageAnnotations } from '../utils/annotations.js';
 /**
  * Collect basic target information from DOM (runs in browser context).
  */
-function collectBasicTargetInfo(interactiveSelector) {
+function collectBasicTargetInfo(args) {
+    const { interactiveSelector, 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 `#${CSS.escape(element.id)}`;
@@ -72,6 +90,7 @@ function collectBasicTargetInfo(interactiveSelector) {
         targets.push({
             selector: getUniqueSelector(element, index),
             tagName,
+            ...getHtmlSnippet(element),
             role,
             width: Math.round(rect.width * 100) / 100,
             height: Math.round(rect.height * 100) / 100,
@@ -247,6 +266,8 @@ function analyzeTargets(targets, aaThreshold, aaaThreshold) {
         const issue = {
             selector: target.selector,
             tagName: target.tagName,
+            html: target.html,
+            htmlTruncated: target.htmlTruncated,
             role: target.role,
             accessibleName: target.accessibleName,
             width: target.width,
@@ -255,6 +276,9 @@ function analyzeTargets(targets, aaThreshold, aaaThreshold) {
             level,
             exception,
             exceptionDetails,
+            // the heuristics can detect exceptions but can never rule out the
+            // essential exception, so findings are at best 'possible'/'not-assessed'.
+            exceptionAssessment: exception ? 'possible' : 'not-assessed',
             href: target.href,
         };
         if (exception) {
@@ -276,7 +300,10 @@ function analyzeTargets(targets, aaThreshold, aaaThreshold) {
 export async function runTargetSizeCheck(options) {
     const { page, aaThreshold = TARGET_SIZE_AA, aaaThreshold = TARGET_SIZE_AAA, screenshot = false, ...location } = options;
     // Collect basic target info from DOM
-    const basicTargets = await page.evaluate(collectBasicTargetInfo, INTERACTIVE_SELECTOR);
+    const basicTargets = await page.evaluate(collectBasicTargetInfo, {
+        interactiveSelector: INTERACTIVE_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
+    });
     // Enhance with accessible names via ariaSnapshot()
     const targets = [];
     for (const basicTarget of basicTargets) {
@@ -296,8 +323,7 @@ export async function runTargetSizeCheck(options) {
     }
     // Analyze targets
     const { failAA, failAAAOnly, passCount, excepted } = analyzeTargets(targets, aaThreshold, aaaThreshold);
-    const result = {
-        url: page.url(),
+    const details = {
         totalTargetsChecked: targets.length,
         failAA,
         failAAAOnly,
@@ -310,16 +336,22 @@ export async function runTargetSizeCheck(options) {
             exceptedCount: excepted.length,
         },
     };
+    const result = buildAuditResult({
+        source: 'target-size-check',
+        url: page.url(),
+        details,
+        buckets: normalizeTargetSizeCheck(details),
+    });
     // Output results
     logAuditHeader('Target Size Check Results', 'WCAG 2.5.5 / 2.5.8', result.url);
     logSummary({
-        'Total targets checked': result.totalTargetsChecked,
+        'Total targets checked': details.totalTargetsChecked,
     });
     console.log('\nSummary:');
-    console.log(`  Pass (>= ${aaaThreshold}px): ${result.summary.passCount}`);
-    console.log(`  Fail AAA only (${aaThreshold}-${aaaThreshold - 1}px): ${result.summary.failAAAOnlyCount}`);
-    console.log(`  Fail AA (< ${aaThreshold}px): ${result.summary.failAACount}`);
-    console.log(`  Possible exceptions: ${result.summary.exceptedCount}`);
+    console.log(`  Pass (>= ${aaaThreshold}px): ${details.summary.passCount}`);
+    console.log(`  Fail AAA only (${aaThreshold}-${aaaThreshold - 1}px): ${details.summary.failAAAOnlyCount}`);
+    console.log(`  Fail AA (< ${aaThreshold}px): ${details.summary.failAACount}`);
+    console.log(`  Possible exceptions: ${details.summary.exceptedCount}`);
     logIssueList(`Fail AA (< ${aaThreshold}px) - Requires Fix`, failAA, (el, i) => {
         const lines = [
             `${i + 1}. <${el.tagName}> "${el.selector}"`,

package/dist/playwright/runTextSpacingCheck.js

@@ -7,11 +7,28 @@
  *
  * The caller is responsible for navigating the page before calling this.
  */
-import { TEXT_SPACING_CSS, TEXT_SPACING_CLIP_TOLERANCE, TEXT_SPACING_CHECK_SELECTOR, DEFAULT_TEXT_SPACING_RESULT_FILE, DEFAULT_TEXT_SPACING_SCREENSHOT_FILE, } from '../constants.js';
+import { TEXT_SPACING_CSS, TEXT_SPACING_CLIP_TOLERANCE, TEXT_SPACING_CHECK_SELECTOR, DEFAULT_TEXT_SPACING_RESULT_FILE, DEFAULT_TEXT_SPACING_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTextSpacingCheck, } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /** Collect metrics for elements with hidden overflow (browser context). */
 function collectElementMetrics(args) {
-    const { checkSelector } = args;
+    const { checkSelector, 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}`;
@@ -56,6 +73,7 @@ function collectElementMetrics(args) {
             metrics.push({
                 selector: getUniqueSelector(element, index),
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 scrollWidth: element.scrollWidth,
                 scrollHeight: element.scrollHeight,
                 clientWidth: element.clientWidth,
@@ -70,13 +88,29 @@ function collectElementMetrics(args) {
 }
 /** Inject text spacing CSS and re-collect metrics (browser context). */
 function injectSpacingAndCollect(args) {
-    const { css, checkSelector } = args;
+    const { css, checkSelector, htmlSnippetMaxLength } = args;
     const styleEl = document.createElement('style');
     styleEl.id = 'wcag-text-spacing-override';
     styleEl.textContent = css;
     document.head.appendChild(styleEl);
     // Force reflow
     void document.body.offsetHeight;
+    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}`;
@@ -121,6 +155,7 @@ function injectSpacingAndCollect(args) {
             metrics.push({
                 selector: getUniqueSelector(element, index),
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 scrollWidth: element.scrollWidth,
                 scrollHeight: element.scrollHeight,
                 clientWidth: element.clientWidth,
@@ -175,6 +210,8 @@ function detectClippingIssues(beforeMetrics, afterMetrics, tolerance) {
             issues.push({
                 selector: after.selector,
                 tagName: after.tagName,
+                html: after.html,
+                htmlTruncated: after.htmlTruncated,
                 beforeMetrics: {
                     scrollWidth: beforeData.scrollWidth,
                     scrollHeight: beforeData.scrollHeight,
@@ -204,23 +241,30 @@ export async function runTextSpacingCheck(options) {
     const { page, tolerance = TEXT_SPACING_CLIP_TOLERANCE, screenshot = false, ...location } = options;
     const beforeMetrics = await page.evaluate(collectElementMetrics, {
         checkSelector: TEXT_SPACING_CHECK_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
     const afterMetrics = await page.evaluate(injectSpacingAndCollect, {
         css: TEXT_SPACING_CSS,
         checkSelector: TEXT_SPACING_CHECK_SELECTOR,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
     const clippedElements = detectClippingIssues(beforeMetrics, afterMetrics, tolerance);
-    const result = {
-        url: page.url(),
+    const details = {
         clippedElements,
         totalElementsChecked: afterMetrics.length,
     };
+    const result = buildAuditResult({
+        source: 'text-spacing-check',
+        url: page.url(),
+        details,
+        buckets: normalizeTextSpacingCheck(details),
+    });
     logAuditHeader('Text Spacing Check Results', 'WCAG 1.4.12', result.url);
     logSummary({
-        'Elements with overflow:hidden checked': result.totalElementsChecked,
-        'Elements with clipping issues': result.clippedElements.length,
+        'Elements with overflow:hidden checked': details.totalElementsChecked,
+        'Elements with clipping issues': details.clippedElements.length,
     });
-    logIssueList('Clipped Elements', result.clippedElements, (el, i) => [
+    logIssueList('Clipped Elements', details.clippedElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   Issue: ${el.issueType}`,
         `   Before: ${el.beforeMetrics.scrollWidth}x${el.beforeMetrics.scrollHeight} in ${el.beforeMetrics.clientWidth}x${el.beforeMetrics.clientHeight}`,

package/dist/playwright/runTimeLimitDetector.js

@@ -10,7 +10,8 @@
  * (option → `TEST_PAGE` env → required). Unlike the focus check it does not
  * need a fresh context per attempt, so it stays page-based.
  */
-import { TIME_LIMIT_KEYWORDS, TIME_LIMIT_THRESHOLD_MS, TIME_LIMIT_MIN_MS, DEFAULT_TIME_LIMIT_RESULT_FILE, } from '../constants.js';
+import { TIME_LIMIT_KEYWORDS, TIME_LIMIT_THRESHOLD_MS, TIME_LIMIT_MIN_MS, DEFAULT_TIME_LIMIT_RESULT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeTimeLimitDetector, } from '../utils/axe-format.js';
 import { saveAuditResult, requireTargetUrl, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /** Timer hook injected before page load (browser context). */
 function createTimerHookScript(args) {
@@ -60,7 +61,23 @@ function createTimerHookScript(args) {
 }
 /** Detect meta refresh + countdown indicators (browser context). */
 function detectTimeLimitIndicators(args) {
-    const { keywords } = args;
+    const { keywords, 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}`;
@@ -91,6 +108,7 @@ function detectTimeLimitIndicators(args) {
                     content,
                     seconds: parseInt(match[1] ?? '0', 10),
                     url: match[2]?.trim() || null,
+                    ...getHtmlSnippet(meta),
                 });
             }
         }
@@ -116,6 +134,7 @@ function detectTimeLimitIndicators(args) {
                             selector: getUniqueSelector(parent, elementIndex),
                             text: fullText,
                             tagName: parent.tagName.toLowerCase(),
+                            ...getHtmlSnippet(parent),
                         });
                     }
                 }
@@ -139,25 +158,31 @@ export async function runTimeLimitDetector(options) {
     });
     const indicators = await page.evaluate(detectTimeLimitIndicators, {
         keywords: [...TIME_LIMIT_KEYWORDS],
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
     const hasTimeLimits = indicators.metaRefresh.length > 0 ||
         timers.length > 0 ||
         indicators.countdownIndicators.length > 0;
-    const result = {
-        url: page.url(),
+    const details = {
         metaRefresh: indicators.metaRefresh,
         timers,
         countdownIndicators: indicators.countdownIndicators,
         hasTimeLimits,
     };
+    const result = buildAuditResult({
+        source: 'time-limit-detector',
+        url: page.url(),
+        details,
+        buckets: normalizeTimeLimitDetector(details),
+    });
     logAuditHeader('Time Limit Detection Results', 'WCAG 2.2.1', result.url);
     logSummary({
-        'Meta refresh tags': result.metaRefresh.length,
-        [`Timers detected (${minMs / 1000}s - ${maxMs / 1000}s)`]: result.timers.length,
-        'Countdown text indicators': result.countdownIndicators.length,
-        'Time limits detected': result.hasTimeLimits,
+        'Meta refresh tags': details.metaRefresh.length,
+        [`Timers detected (${minMs / 1000}s - ${maxMs / 1000}s)`]: details.timers.length,
+        'Countdown text indicators': details.countdownIndicators.length,
+        'Time limits detected': details.hasTimeLimits,
     });
-    logIssueList('Meta Refresh', result.metaRefresh, (meta, i) => {
+    logIssueList('Meta Refresh', details.metaRefresh, (meta, i) => {
         const lines = [
             `${i + 1}. content="${meta.content}"`,
             `   Refresh in ${meta.seconds} seconds`,
@@ -167,7 +192,7 @@ export async function runTimeLimitDetector(options) {
         }
         return lines;
     });
-    logIssueList('Detected Timers', result.timers, (timer, i) => {
+    logIssueList('Detected Timers', details.timers, (timer, i) => {
         const lines = [
             `${i + 1}. ${timer.type} - ${timer.delayMs}ms (${(timer.delayMs / 1000).toFixed(1)}s)`,
         ];
@@ -176,7 +201,7 @@ export async function runTimeLimitDetector(options) {
         }
         return lines;
     });
-    logIssueList('Countdown Indicators', result.countdownIndicators, (indicator, i) => {
+    logIssueList('Countdown Indicators', details.countdownIndicators, (indicator, i) => {
         const truncatedText = indicator.text.length > 80
             ? indicator.text.slice(0, 80) + '...'
             : indicator.text;

package/dist/playwright/runZoomCheck.js

@@ -15,11 +15,28 @@
  * - Does not verify responsive breakpoint behavior
  * - Manual verification needed for complex interactions at zoom
  */
-import { ZOOM_FACTOR, ZOOM_BASE_VIEWPORT, ZOOM_CLIP_TOLERANCE, REFLOW_CHECK_SELECTOR, DEFAULT_ZOOM_RESULT_FILE, DEFAULT_ZOOM_SCREENSHOT_FILE, } from '../constants.js';
+import { ZOOM_FACTOR, ZOOM_BASE_VIEWPORT, ZOOM_CLIP_TOLERANCE, REFLOW_CHECK_SELECTOR, DEFAULT_ZOOM_RESULT_FILE, DEFAULT_ZOOM_SCREENSHOT_FILE, HTML_SNIPPET_MAX_LENGTH, } from '../constants.js';
+import { buildAuditResult, normalizeZoomCheck } from '../utils/axe-format.js';
 import { saveAuditResult, takeAuditScreenshot, resolveScreenshotPath, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
 /** Apply zoom and detect issues in browser context. */
 function applyZoomAndCheck(args) {
-    const { checkSelector, tolerance } = args;
+    const { checkSelector, tolerance, 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 };
+    }
     // Apply CSS zoom
     document.documentElement.style.zoom =
         '200%';
@@ -83,6 +100,7 @@ function applyZoomAndCheck(args) {
             clippedElements.push({
                 selector: getUniqueSelector(element, index),
                 tagName: element.tagName.toLowerCase(),
+                ...getHtmlSnippet(element),
                 scrollWidth,
                 clientWidth,
                 scrollHeight,
@@ -113,24 +131,30 @@ export async function runZoomCheck(options) {
     const zoomResult = await page.evaluate(applyZoomAndCheck, {
         checkSelector: REFLOW_CHECK_SELECTOR,
         tolerance: ZOOM_CLIP_TOLERANCE,
+        htmlSnippetMaxLength: HTML_SNIPPET_MAX_LENGTH,
     });
-    const result = {
-        url: page.url(),
+    const details = {
         zoomFactor: ZOOM_FACTOR,
         viewport: { width: viewport.width, height: viewport.height },
         ...zoomResult,
     };
+    const result = buildAuditResult({
+        source: 'zoom-200-check',
+        url: page.url(),
+        details,
+        buckets: normalizeZoomCheck(details),
+    });
     // Output results
     logAuditHeader('Zoom 200% Check Results', 'WCAG 1.4.4', result.url);
     logSummary({
-        'Zoom factor': `${result.zoomFactor}x`,
-        'Base viewport': `${result.viewport.width}x${result.viewport.height}`,
-        'Document scroll width': `${result.documentScrollWidth}px`,
-        'Document client width': `${result.documentClientWidth}px`,
-        'Horizontal scroll': result.hasHorizontalScroll,
-        'Clipped elements': result.clippedElements.length,
+        'Zoom factor': `${details.zoomFactor}x`,
+        'Base viewport': `${details.viewport.width}x${details.viewport.height}`,
+        'Document scroll width': `${details.documentScrollWidth}px`,
+        'Document client width': `${details.documentClientWidth}px`,
+        'Horizontal scroll': details.hasHorizontalScroll,
+        'Clipped elements': details.clippedElements.length,
     });
-    logIssueList('Clipped Elements', result.clippedElements, (el, i) => [
+    logIssueList('Clipped Elements', details.clippedElements, (el, i) => [
         `${i + 1}. <${el.tagName}> "${el.selector}"`,
         `   scrollWidth: ${el.scrollWidth}px, clientWidth: ${el.clientWidth}px`,
         `   Issue: ${el.issueType}`,

package/dist/schemas/index.d.ts

@@ -6,18 +6,25 @@
  * (e.g. an issue creator that reads `*-result.json`). They are intentionally
  * permissive (no `additionalProperties: false`) so that additive changes to a
  * result shape do not break downstream validation.
+ *
+ * Every check shares the same envelope (`source` / `url` / `timestamp` / the
+ * four normalized buckets / `summary` / `details` / `disclaimer`); the common
+ * pieces live in `$defs` and each check schema defines its own `details`.
  */
-export type { AxeViolationNode, AxeViolation, AxeAuditResult, FocusRecord, OnFocusViolation, FocusCheckResult, BoundingRect, FocusObscuredOverlap, FocusObscuredIssue, ReflowIssue, ClippedTextElement, ReflowCheckResult, TargetSizeException, TargetSizeIssue, TargetSizeSummary, TargetSizeCheckResult, TextSpacingIssue, TextSpacingCheckResult, ZoomIssue, ZoomCheckResult, OrientationState, OrientationCheckResult, AutocompleteIssue, AutocompleteAuditResult, MetaRefreshInfo, TimerInfo, CountdownIndicator, TimeLimitDetectorResult, ScreenshotRecord, ComparisonResult, ImageDiffResult, PauseControl, CarouselIndicator, PauseControlInfo, PauseVerificationResult, AutoPlayDetectionResult, } from '../types.js';
+export type { AuditCheckResult, AuditResultSummary, CheckSource, NormalizedImpact, NormalizedNode, NormalizedRuleResult, AxeAuditDetails, AxeAuditResult, FocusRecord, FocusElementRef, OnFocusViolation, FocusCheckDetails, FocusCheckResult, BoundingRect, FocusObscuredOverlap, FocusObscuredIssue, ReflowIssue, ClippedTextElement, ReflowCheckDetails, ReflowCheckResult, TargetSizeException, TargetSizeExceptionAssessment, TargetSizeIssue, TargetSizeSummary, TargetSizeCheckDetails, TargetSizeCheckResult, TextSpacingIssue, TextSpacingCheckDetails, TextSpacingCheckResult, ZoomIssue, ZoomCheckDetails, ZoomCheckResult, OrientationState, OrientationCheckDetails, OrientationCheckResult, AutocompleteIssue, AutocompleteAuditDetails, AutocompleteAuditResult, MetaRefreshInfo, TimerInfo, CountdownIndicator, TimeLimitDetectorDetails, TimeLimitDetectorResult, ScreenshotRecord, ComparisonResult, ImageDiffResult, PauseControl, CarouselIndicator, PauseControlInfo, PauseVerificationResult, AutoPlayDetectionDetails, AutoPlayDetectionResult, } from '../types.js';
 /** Minimal JSON Schema object shape (Draft 2020-12 compatible subset). */
 export interface JsonSchema {
     $schema?: string;
     $id?: string;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
     title?: string;
     type?: string | string[];
     properties?: Record<string, JsonSchema>;
     items?: JsonSchema;
     required?: string[];
     enum?: unknown[];
+    const?: unknown;
     description?: string;
     [key: string]: unknown;
 }