@a11y-skills/audit 0.1.0 → 0.2.0

package/dist/playwright/runOrientationCheck.js

@@ -0,0 +1,164 @@
+/**
+ * Orientation Check — WCAG 1.3.4 (Orientation)
+ *
+ * Renders the page in portrait (375x667) and landscape (667x375), detecting
+ * "rotate device" messages/overlays and whether the main content is hidden in
+ * either orientation. Reports if the page restricts content to a specific
+ * orientation.
+ *
+ * This function OWNS navigation: it sets each viewport then navigates to the
+ * target URL for that orientation (two full navigations, not a reload), so the
+ * page lays out fresh for each orientation.
+ *
+ * Limitations:
+ * - Heuristics may miss CSS-only orientation restrictions
+ * - Cannot detect JavaScript-based orientation detection without visual indicators
+ * - Manual verification needed for exceptions (e.g., camera apps)
+ */
+import { 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 { saveAuditResult, resolveOutputPath, takeAuditScreenshot, resolveScreenshotPath, requireTargetUrl, logAuditHeader, logOutputPaths, } from '../utils/test-harness.js';
+/** Capture orientation state in browser context. */
+function captureOrientationState(args) {
+    const { lockKeywords, mainContentSelectors } = args;
+    const bodyWidth = document.body.scrollWidth;
+    const bodyHeight = document.body.scrollHeight;
+    const visibleText = document.body.innerText || '';
+    const visibleTextLength = visibleText.length;
+    const lowerText = visibleText.toLowerCase();
+    // Search for lock message keywords
+    let lockMessageFound = false;
+    let lockMessageText = null;
+    for (const keyword of lockKeywords) {
+        if (lowerText.includes(keyword.toLowerCase())) {
+            lockMessageFound = true;
+            const allElements = document.querySelectorAll('*');
+            for (const el of allElements) {
+                const text = el.textContent?.toLowerCase() || '';
+                if (text.includes(keyword.toLowerCase()) && text.length < 200) {
+                    lockMessageText = el.textContent?.trim().slice(0, 100) || null;
+                    break;
+                }
+            }
+            break;
+        }
+    }
+    // Check if main content is hidden
+    let mainContentHidden = false;
+    for (const selector of mainContentSelectors) {
+        const mainEl = document.querySelector(selector);
+        if (mainEl) {
+            const style = window.getComputedStyle(mainEl);
+            const isHidden = style.display === 'none' ||
+                style.visibility === 'hidden' ||
+                parseFloat(style.opacity) === 0;
+            if (isHidden) {
+                mainContentHidden = true;
+                break;
+            }
+            const rect = mainEl.getBoundingClientRect();
+            if (rect.width < 50 || rect.height < 50) {
+                mainContentHidden = true;
+                break;
+            }
+        }
+    }
+    return {
+        lockMessageFound,
+        lockMessageText,
+        mainContentHidden,
+        bodyWidth,
+        bodyHeight,
+        visibleTextLength,
+    };
+}
+/** Determine where orientation lock was detected. */
+function determineLockLocation(portraitHasLock, landscapeHasLock) {
+    if (portraitHasLock && landscapeHasLock) {
+        return 'both';
+    }
+    if (portraitHasLock) {
+        return 'portrait';
+    }
+    if (landscapeHasLock) {
+        return 'landscape';
+    }
+    return 'none';
+}
+/** Log orientation state for a specific orientation. */
+function logOrientationState(label, viewport, state) {
+    console.log(`\n${label} (${viewport.width}x${viewport.height}):`);
+    console.log(`  Lock message found: ${state.lockMessageFound ? 'YES' : 'No'}`);
+    if (state.lockMessageText) {
+        console.log(`  Message: "${state.lockMessageText}"`);
+    }
+    console.log(`  Main content hidden: ${state.mainContentHidden ? 'YES' : 'No'}`);
+    console.log(`  Body size: ${state.bodyWidth}x${state.bodyHeight}`);
+}
+/**
+ * Run the orientation check, navigating the page in both portrait and landscape,
+ * write the result JSON (and optionally screenshots), and return the parsed
+ * result.
+ */
+export async function runOrientationCheck(options) {
+    const { page, targetUrl, screenshot = false, ...location } = options;
+    const url = requireTargetUrl(targetUrl);
+    const checkArgs = {
+        lockKeywords: [...ORIENTATION_LOCK_KEYWORDS],
+        mainContentSelectors: [...MAIN_CONTENT_SELECTORS],
+    };
+    // Resolve where the result will be written up front so screenshots can be
+    // placed next to it (mirrors saveAuditResult's resolution).
+    const resolvedPath = resolveOutputPath({
+        ...location,
+        defaultFile: DEFAULT_ORIENTATION_RESULT_FILE,
+    });
+    // Test portrait orientation
+    await page.setViewportSize(ORIENTATION_VIEWPORTS.portrait);
+    await page.goto(url, { waitUntil: 'networkidle' });
+    const portraitState = await page.evaluate(captureOrientationState, checkArgs);
+    let portraitScreenshotPath;
+    if (screenshot) {
+        portraitScreenshotPath = await takeAuditScreenshot(page, {
+            path: resolveScreenshotPath(resolvedPath, DEFAULT_ORIENTATION_PORTRAIT_SCREENSHOT_FILE),
+        });
+    }
+    // Test landscape orientation
+    await page.setViewportSize(ORIENTATION_VIEWPORTS.landscape);
+    await page.goto(url, { waitUntil: 'networkidle' });
+    const landscapeState = await page.evaluate(captureOrientationState, checkArgs);
+    let landscapeScreenshotPath;
+    if (screenshot) {
+        landscapeScreenshotPath = await takeAuditScreenshot(page, {
+            path: resolveScreenshotPath(resolvedPath, DEFAULT_ORIENTATION_LANDSCAPE_SCREENSHOT_FILE),
+        });
+    }
+    // Determine lock status
+    const portraitHasLock = portraitState.lockMessageFound || portraitState.mainContentHidden;
+    const landscapeHasLock = landscapeState.lockMessageFound || landscapeState.mainContentHidden;
+    const hasOrientationLock = portraitHasLock || landscapeHasLock;
+    const lockDetectedIn = determineLockLocation(portraitHasLock, landscapeHasLock);
+    const result = {
+        url: page.url(),
+        portrait: portraitState,
+        landscape: landscapeState,
+        hasOrientationLock,
+        lockDetectedIn,
+    };
+    // 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}`);
+    }
+    const writtenPath = saveAuditResult(result, {
+        ...location,
+        defaultFile: DEFAULT_ORIENTATION_RESULT_FILE,
+    });
+    const screenshotPaths = [portraitScreenshotPath, landscapeScreenshotPath]
+        .filter((p) => p !== undefined)
+        .join(', ');
+    logOutputPaths(writtenPath, screenshotPaths || undefined);
+    return result;
+}

package/dist/playwright/runTextSpacingCheck.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Text Spacing Check — WCAG 1.4.12 (Text Spacing)
+ *
+ * Captures baseline metrics, injects the WCAG 1.4.12 spacing overrides, and
+ * reports elements whose text becomes clipped (overflow:hidden) under the
+ * increased spacing.
+ *
+ * The caller is responsible for navigating the page before calling this.
+ */
+import type { Page } from '@playwright/test';
+import type { TextSpacingCheckResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunTextSpacingCheckOptions extends OutputLocationOptions {
+    /** A page already navigated to the target URL. */
+    page: Page;
+    /** Tolerance in pixels for clip detection (default: 2). */
+    tolerance?: number;
+    /** Whether to capture a screenshot next to the result file (default: false). */
+    screenshot?: boolean;
+}
+/**
+ * Run the text spacing check against the current page, write the result JSON
+ * (and optionally a screenshot), and return the parsed result.
+ */
+export declare function runTextSpacingCheck(options: RunTextSpacingCheckOptions): Promise<TextSpacingCheckResult>;

package/dist/playwright/runTextSpacingCheck.js

@@ -0,0 +1,241 @@
+/**
+ * Text Spacing Check — WCAG 1.4.12 (Text Spacing)
+ *
+ * Captures baseline metrics, injects the WCAG 1.4.12 spacing overrides, and
+ * reports elements whose text becomes clipped (overflow:hidden) under the
+ * increased spacing.
+ *
+ * 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 { 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;
+    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}"]`;
+    }
+    function isVisible(element) {
+        const style = window.getComputedStyle(element);
+        return (style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            parseFloat(style.opacity) > 0);
+    }
+    function hasHiddenOverflow(style) {
+        return (style.overflow === 'hidden' ||
+            style.overflow === 'clip' ||
+            style.overflowX === 'hidden' ||
+            style.overflowX === 'clip' ||
+            style.overflowY === 'hidden' ||
+            style.overflowY === 'clip');
+    }
+    const elements = document.querySelectorAll(checkSelector);
+    const metrics = [];
+    elements.forEach((element, index) => {
+        if (!isVisible(element)) {
+            return;
+        }
+        const style = window.getComputedStyle(element);
+        const hasText = element.textContent && element.textContent.trim().length > 0;
+        if (hasText && hasHiddenOverflow(style)) {
+            metrics.push({
+                selector: getUniqueSelector(element, index),
+                tagName: element.tagName.toLowerCase(),
+                scrollWidth: element.scrollWidth,
+                scrollHeight: element.scrollHeight,
+                clientWidth: element.clientWidth,
+                clientHeight: element.clientHeight,
+                overflow: style.overflow,
+                overflowX: style.overflowX,
+                overflowY: style.overflowY,
+            });
+        }
+    });
+    return metrics;
+}
+/** Inject text spacing CSS and re-collect metrics (browser context). */
+function injectSpacingAndCollect(args) {
+    const { css, checkSelector } = 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 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}"]`;
+    }
+    function isVisible(element) {
+        const style = window.getComputedStyle(element);
+        return (style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            parseFloat(style.opacity) > 0);
+    }
+    function hasHiddenOverflow(style) {
+        return (style.overflow === 'hidden' ||
+            style.overflow === 'clip' ||
+            style.overflowX === 'hidden' ||
+            style.overflowX === 'clip' ||
+            style.overflowY === 'hidden' ||
+            style.overflowY === 'clip');
+    }
+    const elements = document.querySelectorAll(checkSelector);
+    const metrics = [];
+    elements.forEach((element, index) => {
+        if (!isVisible(element)) {
+            return;
+        }
+        const style = window.getComputedStyle(element);
+        const hasText = element.textContent && element.textContent.trim().length > 0;
+        if (hasText && hasHiddenOverflow(style)) {
+            metrics.push({
+                selector: getUniqueSelector(element, index),
+                tagName: element.tagName.toLowerCase(),
+                scrollWidth: element.scrollWidth,
+                scrollHeight: element.scrollHeight,
+                clientWidth: element.clientWidth,
+                clientHeight: element.clientHeight,
+                overflow: style.overflow,
+                overflowX: style.overflowX,
+                overflowY: style.overflowY,
+            });
+        }
+    });
+    return metrics;
+}
+function determineIssueType(hasHorizontalIssue, hasVerticalIssue) {
+    if (hasHorizontalIssue && hasVerticalIssue) {
+        return 'both';
+    }
+    if (hasVerticalIssue) {
+        return 'vertical-clip';
+    }
+    return 'horizontal-clip';
+}
+function detectClippingIssues(beforeMetrics, afterMetrics, tolerance) {
+    const beforeMap = new Map();
+    beforeMetrics.forEach((m) => beforeMap.set(m.selector, m));
+    const issues = [];
+    afterMetrics.forEach((after) => {
+        const before = beforeMap.get(after.selector);
+        const defaultBefore = {
+            scrollWidth: after.clientWidth,
+            scrollHeight: after.clientHeight,
+            clientWidth: after.clientWidth,
+            clientHeight: after.clientHeight,
+        };
+        const beforeData = before || defaultBefore;
+        const horizontalClipBefore = beforeData.scrollWidth > beforeData.clientWidth + tolerance;
+        const horizontalClipAfter = after.scrollWidth > after.clientWidth + tolerance;
+        const verticalClipBefore = beforeData.scrollHeight > beforeData.clientHeight + tolerance;
+        const verticalClipAfter = after.scrollHeight > after.clientHeight + tolerance;
+        const newHorizontalClip = !horizontalClipBefore && horizontalClipAfter;
+        const newVerticalClip = !verticalClipBefore && verticalClipAfter;
+        const worsenedHorizontalClip = horizontalClipBefore &&
+            horizontalClipAfter &&
+            after.scrollWidth - after.clientWidth >
+                beforeData.scrollWidth - beforeData.clientWidth + tolerance;
+        const worsenedVerticalClip = verticalClipBefore &&
+            verticalClipAfter &&
+            after.scrollHeight - after.clientHeight >
+                beforeData.scrollHeight - beforeData.clientHeight + tolerance;
+        const hasHorizontalIssue = newHorizontalClip || worsenedHorizontalClip;
+        const hasVerticalIssue = newVerticalClip || worsenedVerticalClip;
+        if (hasHorizontalIssue || hasVerticalIssue) {
+            issues.push({
+                selector: after.selector,
+                tagName: after.tagName,
+                beforeMetrics: {
+                    scrollWidth: beforeData.scrollWidth,
+                    scrollHeight: beforeData.scrollHeight,
+                    clientWidth: beforeData.clientWidth,
+                    clientHeight: beforeData.clientHeight,
+                },
+                afterMetrics: {
+                    scrollWidth: after.scrollWidth,
+                    scrollHeight: after.scrollHeight,
+                    clientWidth: after.clientWidth,
+                    clientHeight: after.clientHeight,
+                },
+                overflow: after.overflow,
+                overflowX: after.overflowX,
+                overflowY: after.overflowY,
+                issueType: determineIssueType(hasHorizontalIssue, hasVerticalIssue),
+            });
+        }
+    });
+    return issues;
+}
+/**
+ * Run the text spacing check against the current page, write the result JSON
+ * (and optionally a screenshot), and return the parsed result.
+ */
+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,
+    });
+    const afterMetrics = await page.evaluate(injectSpacingAndCollect, {
+        css: TEXT_SPACING_CSS,
+        checkSelector: TEXT_SPACING_CHECK_SELECTOR,
+    });
+    const clippedElements = detectClippingIssues(beforeMetrics, afterMetrics, tolerance);
+    const result = {
+        url: page.url(),
+        clippedElements,
+        totalElementsChecked: afterMetrics.length,
+    };
+    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,
+    });
+    logIssueList('Clipped Elements', result.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}`,
+        `   After:  ${el.afterMetrics.scrollWidth}x${el.afterMetrics.scrollHeight} in ${el.afterMetrics.clientWidth}x${el.afterMetrics.clientHeight}`,
+    ]);
+    const resolvedPath = saveAuditResult(result, {
+        ...location,
+        defaultFile: DEFAULT_TEXT_SPACING_RESULT_FILE,
+    });
+    let screenshotPath;
+    if (screenshot) {
+        screenshotPath = await takeAuditScreenshot(page, {
+            path: resolveScreenshotPath(resolvedPath, DEFAULT_TEXT_SPACING_SCREENSHOT_FILE),
+        });
+    }
+    logOutputPaths(resolvedPath, screenshotPath);
+    return result;
+}

package/dist/playwright/runTimeLimitDetector.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Time Limit Detector — WCAG 2.2.1 (Timing Adjustable)
+ *
+ * Hooks setTimeout/setInterval (via an init script injected BEFORE navigation),
+ * checks meta refresh tags, and scans visible text for countdown/timeout
+ * keywords.
+ *
+ * Because the timer hook must be installed before page scripts run, this
+ * function OWNS navigation: pass an un-navigated `page` and a `targetUrl`
+ * (option → `TEST_PAGE` env → required). Unlike the focus check it does not
+ * need a fresh context per attempt, so it stays page-based.
+ */
+import type { Page } from '@playwright/test';
+import type { TimeLimitDetectorResult } from '../types.js';
+import { type OutputLocationOptions } from '../utils/test-harness.js';
+export interface RunTimeLimitDetectorOptions extends OutputLocationOptions {
+    /** An un-navigated page (this function navigates after installing the timer hook). */
+    page: Page;
+    /** Target URL. Falls back to the `TEST_PAGE` env var; required. */
+    targetUrl?: string;
+    /** Minimum timer delay to capture, ms (default: 10000). */
+    minMs?: number;
+    /** Maximum timer delay to capture, ms (default: 600000). */
+    maxMs?: number;
+    /** How long to wait after load for timers to register, ms (default: 2000). */
+    settleMs?: number;
+}
+/**
+ * Run the time limit detector, write the result JSON, and return the result.
+ */
+export declare function runTimeLimitDetector(options: RunTimeLimitDetectorOptions): Promise<TimeLimitDetectorResult>;

package/dist/playwright/runTimeLimitDetector.js

@@ -0,0 +1,194 @@
+/**
+ * Time Limit Detector — WCAG 2.2.1 (Timing Adjustable)
+ *
+ * Hooks setTimeout/setInterval (via an init script injected BEFORE navigation),
+ * checks meta refresh tags, and scans visible text for countdown/timeout
+ * keywords.
+ *
+ * Because the timer hook must be installed before page scripts run, this
+ * function OWNS navigation: pass an un-navigated `page` and a `targetUrl`
+ * (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 { saveAuditResult, requireTargetUrl, logAuditHeader, logSummary, logIssueList, logOutputPaths, } from '../utils/test-harness.js';
+/** Timer hook injected before page load (browser context). */
+function createTimerHookScript(args) {
+    const { minMs, maxMs } = args;
+    const capturedTimers = [];
+    const originalSetTimeout = window.setTimeout;
+    const originalSetInterval = window.setInterval;
+    window.setTimeout = function (callback, delay, ...rest) {
+        const actualDelay = delay || 0;
+        if (actualDelay >= minMs && actualDelay <= maxMs) {
+            let callStack = null;
+            try {
+                throw new Error();
+            }
+            catch (e) {
+                callStack =
+                    e.stack?.split('\n').slice(2, 5).join('\n') || null;
+            }
+            capturedTimers.push({ type: 'setTimeout', delayMs: actualDelay, callStack });
+        }
+        return originalSetTimeout.apply(window, [
+            callback,
+            delay,
+            ...rest,
+        ]);
+    };
+    window.setInterval = function (callback, delay, ...rest) {
+        const actualDelay = delay || 0;
+        if (actualDelay >= minMs && actualDelay <= maxMs) {
+            let callStack = null;
+            try {
+                throw new Error();
+            }
+            catch (e) {
+                callStack =
+                    e.stack?.split('\n').slice(2, 5).join('\n') || null;
+            }
+            capturedTimers.push({ type: 'setInterval', delayMs: actualDelay, callStack });
+        }
+        return originalSetInterval.apply(window, [
+            callback,
+            delay,
+            ...rest,
+        ]);
+    };
+    window.__capturedTimers = capturedTimers;
+}
+/** Detect meta refresh + countdown indicators (browser context). */
+function detectTimeLimitIndicators(args) {
+    const { keywords } = args;
+    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 metaRefresh = [];
+    const metaTags = document.querySelectorAll('meta[http-equiv="refresh"]');
+    metaTags.forEach((meta) => {
+        const content = meta.getAttribute('content');
+        if (content) {
+            const trimmed = content.trim();
+            const match = trimmed.match(/^(\d+)\s*(?:;\s*url\s*=\s*(.+))?$/i);
+            if (match) {
+                metaRefresh.push({
+                    content,
+                    seconds: parseInt(match[1] ?? '0', 10),
+                    url: match[2]?.trim() || null,
+                });
+            }
+        }
+    });
+    const countdownIndicators = [];
+    const visibleText = document.body.innerText || '';
+    const lowerText = visibleText.toLowerCase();
+    for (const keyword of keywords) {
+        if (!lowerText.includes(keyword.toLowerCase())) {
+            continue;
+        }
+        const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
+        let node;
+        let elementIndex = 0;
+        while ((node = walker.nextNode())) {
+            if (node.textContent?.toLowerCase().includes(keyword.toLowerCase())) {
+                const parent = node.parentElement;
+                if (parent) {
+                    const fullText = parent.textContent?.trim().slice(0, 150) || '';
+                    const alreadyAdded = countdownIndicators.some((c) => c.text === fullText);
+                    if (!alreadyAdded && fullText.length > 0) {
+                        countdownIndicators.push({
+                            selector: getUniqueSelector(parent, elementIndex),
+                            text: fullText,
+                            tagName: parent.tagName.toLowerCase(),
+                        });
+                    }
+                }
+            }
+            elementIndex++;
+        }
+    }
+    return { metaRefresh, countdownIndicators };
+}
+/**
+ * Run the time limit detector, write the result JSON, and return the result.
+ */
+export async function runTimeLimitDetector(options) {
+    const { page, targetUrl: targetUrlOption, minMs = TIME_LIMIT_MIN_MS, maxMs = TIME_LIMIT_THRESHOLD_MS, settleMs = 2000, ...location } = options;
+    const targetUrl = requireTargetUrl(targetUrlOption);
+    await page.addInitScript(createTimerHookScript, { minMs, maxMs });
+    await page.goto(targetUrl, { waitUntil: 'networkidle' });
+    await page.waitForTimeout(settleMs);
+    const timers = await page.evaluate(() => {
+        return (window.__capturedTimers || []);
+    });
+    const indicators = await page.evaluate(detectTimeLimitIndicators, {
+        keywords: [...TIME_LIMIT_KEYWORDS],
+    });
+    const hasTimeLimits = indicators.metaRefresh.length > 0 ||
+        timers.length > 0 ||
+        indicators.countdownIndicators.length > 0;
+    const result = {
+        url: page.url(),
+        metaRefresh: indicators.metaRefresh,
+        timers,
+        countdownIndicators: indicators.countdownIndicators,
+        hasTimeLimits,
+    };
+    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,
+    });
+    logIssueList('Meta Refresh', result.metaRefresh, (meta, i) => {
+        const lines = [
+            `${i + 1}. content="${meta.content}"`,
+            `   Refresh in ${meta.seconds} seconds`,
+        ];
+        if (meta.url) {
+            lines.push(`   Redirects to: ${meta.url}`);
+        }
+        return lines;
+    });
+    logIssueList('Detected Timers', result.timers, (timer, i) => {
+        const lines = [
+            `${i + 1}. ${timer.type} - ${timer.delayMs}ms (${(timer.delayMs / 1000).toFixed(1)}s)`,
+        ];
+        if (timer.callStack) {
+            lines.push(`   Stack: ${timer.callStack.split('\n')[0]}`);
+        }
+        return lines;
+    });
+    logIssueList('Countdown Indicators', result.countdownIndicators, (indicator, i) => {
+        const truncatedText = indicator.text.length > 80
+            ? indicator.text.slice(0, 80) + '...'
+            : indicator.text;
+        return [
+            `${i + 1}. <${indicator.tagName}> "${indicator.selector}"`,
+            `   Text: "${truncatedText}"`,
+        ];
+    }, 5);
+    const resolvedPath = saveAuditResult(result, {
+        ...location,
+        defaultFile: DEFAULT_TIME_LIMIT_RESULT_FILE,
+    });
+    logOutputPaths(resolvedPath);
+    return result;
+}