agentic-qe 3.6.8 → 3.6.9

package/v3/dist/domains/visual-accessibility/services/accessibility-tester.js

@@ -23,7 +23,11 @@ import { v4 as uuidv4 } from 'uuid';
 import { ok, err } from '../../../shared/types/index.js';
 import { EUComplianceService } from './eu-compliance.js';
 import { isBrowserModeEnabled, isAxeCoreEnabled, } from '../../../integrations/vibium/index.js';
+import { toError } from '../../../shared/error-utils.js';
 import { getBrowserClientForUseCase, } from '../../../integrations/browser/index.js';
+// Extracted modules
+import { WCAG_CRITERIA, getErrorMessage, auditWithBrowserClient, auditWithVibium, auditElementWithVibium, checkContrastWithVibium, checkKeyboardWithVibium, } from './accessibility-tester-browser.js';
+import { initializeRules, filterRulesByLevel, runRule, validateCriterion, analyzeContrastForElements, generateKeyboardReportWithHeuristics, hashUrl, } from './accessibility-tester-heuristics.js';
 const DEFAULT_CONFIG = {
     defaultWCAGLevel: 'AA',
     includeWarnings: true,
@@ -39,40 +43,9 @@ const DEFAULT_CONFIG = {
     browserClient: undefined,
     preferAgentBrowser: true,
 };
-/**
- * WCAG 2.2 criteria definitions
- */
-const WCAG_CRITERIA = {
-    '1.1.1': { id: '1.1.1', level: 'A', title: 'Non-text Content' },
-    '1.3.1': { id: '1.3.1', level: 'A', title: 'Info and Relationships' },
-    '1.4.1': { id: '1.4.1', level: 'A', title: 'Use of Color' },
-    '1.4.3': { id: '1.4.3', level: 'AA', title: 'Contrast (Minimum)' },
-    '1.4.6': { id: '1.4.6', level: 'AAA', title: 'Contrast (Enhanced)' },
-    '2.1.1': { id: '2.1.1', level: 'A', title: 'Keyboard' },
-    '2.1.2': { id: '2.1.2', level: 'A', title: 'No Keyboard Trap' },
-    '2.4.1': { id: '2.4.1', level: 'A', title: 'Bypass Blocks' },
-    '2.4.3': { id: '2.4.3', level: 'A', title: 'Focus Order' },
-    '2.4.4': { id: '2.4.4', level: 'A', title: 'Link Purpose (In Context)' },
-    '2.4.7': { id: '2.4.7', level: 'AA', title: 'Focus Visible' },
-    '3.1.1': { id: '3.1.1', level: 'A', title: 'Language of Page' },
-    '4.1.1': { id: '4.1.1', level: 'A', title: 'Parsing' },
-    '4.1.2': { id: '4.1.2', level: 'A', title: 'Name, Role, Value' },
-};
 /**
  * Accessibility Auditing Service Implementation
  * Provides WCAG 2.2 compliance checking with optional browser mode via Vibium
- *
- * @example
- * ```typescript
- * // Heuristic mode (default when Vibium unavailable)
- * const service = new AccessibilityTesterService(memory);
- * const result = await service.audit('https://example.com');
- *
- * // Browser mode with Vibium
- * const vibiumClient = await createVibiumClient({ enabled: true });
- * const browserService = new AccessibilityTesterService(memory, {}, vibiumClient);
- * const browserResult = await browserService.audit('https://example.com');
- * ```
  */
 export class AccessibilityTesterService {
     memory;
@@ -82,80 +55,37 @@ export class AccessibilityTesterService {
     browserClient;
     managedBrowserClient = null;
     euComplianceService;
-    /**
-     * Create an AccessibilityTesterService
-     *
-     * @param memory - Memory backend for storing audit results
-     * @param config - Service configuration options
-     * @param vibiumClient - Optional Vibium client for browser-based testing (legacy)
-     */
     constructor(memory, config = {}, vibiumClient) {
         this.memory = memory;
         this.config = { ...DEFAULT_CONFIG, ...config };
-        this.rules = this.initializeRules();
+        this.rules = initializeRules();
         this.vibiumClient = vibiumClient ?? null;
         this.browserClient = config.browserClient ?? null;
         this.euComplianceService = new EUComplianceService(memory);
     }
-    /**
-     * Check if browser mode is available and enabled
-     *
-     * Browser mode requires:
-     * 1. useBrowserMode config setting enabled
-     * 2. Browser client (IBrowserClient) or VibiumClient instance provided
-     * 3. Feature flags enabled (if using Vibium)
-     *
-     * Priority order:
-     * 1. Provided browserClient (from config)
-     * 2. agent-browser (if preferAgentBrowser is true)
-     * 3. Vibium (if available and feature flags enabled)
-     *
-     * @returns true if browser mode should be used
-     */
+    // ============================================================================
+    // Browser Mode Detection
+    // ============================================================================
     shouldUseBrowserMode() {
-        // Check config setting
-        if (!this.config.useBrowserMode) {
+        if (!this.config.useBrowserMode)
             return false;
-        }
-        // Check if browser client is provided
-        if (this.browserClient) {
+        if (this.browserClient)
             return true;
-        }
-        // Check if we should prefer agent-browser (factory will be used)
-        if (this.config.preferAgentBrowser) {
-            // Will attempt to create agent-browser client on demand
+        if (this.config.preferAgentBrowser)
             return true;
-        }
-        // Legacy Vibium path - check feature flags
-        if (!isBrowserModeEnabled()) {
+        if (!isBrowserModeEnabled())
             return false;
-        }
-        // Check if axe-core is enabled for accessibility testing
-        if (!isAxeCoreEnabled()) {
+        if (!isAxeCoreEnabled())
             return false;
-        }
-        // Check if Vibium client is available
-        if (!this.vibiumClient) {
+        if (!this.vibiumClient)
             return false;
-        }
         return true;
     }
-    /**
-     * Get or create a browser client for accessibility testing
-     * Prefers agent-browser, falls back to Vibium
-     *
-     * @returns Browser client or null if unavailable
-     */
     async getBrowserClient() {
-        // Use provided browser client first
-        if (this.browserClient) {
+        if (this.browserClient)
             return this.browserClient;
-        }
-        // Use already-created managed client
-        if (this.managedBrowserClient) {
+        if (this.managedBrowserClient)
             return this.managedBrowserClient;
-        }
-        // Try to create a browser client via factory
         if (this.config.preferAgentBrowser) {
             try {
                 const client = await getBrowserClientForUseCase('accessibility');
@@ -166,432 +96,73 @@ export class AccessibilityTesterService {
                 }
             }
             catch (error) {
-                // Non-critical: browser client acquisition failed, using Vibium
                 console.debug('[AccessibilityTester] Browser client error:', error instanceof Error ? error.message : error);
             }
         }
-        // Fall back to Vibium (return null, Vibium methods will be used)
         return null;
     }
-    /**
-     * Check if client is an IAgentBrowserClient (has getSnapshot method)
-     */
-    isAgentBrowserClient(client) {
-        return client.tool === 'agent-browser' && 'getSnapshot' in client;
-    }
-    /**
-     * Run full accessibility audit
-     *
-     * Priority order for browser-based testing:
-     * 1. agent-browser (if preferAgentBrowser is true and available)
-     * 2. Vibium (if available and enabled via feature flags)
-     * 3. Heuristic mode (URL pattern analysis)
-     *
-     * @param url - URL to audit
-     * @param options - Audit configuration options
-     * @returns AccessibilityReport with violations, passes, and score
-     */
+    // ============================================================================
+    // Core Audit Methods
+    // ============================================================================
     async audit(url, options) {
         try {
             const wcagLevel = options?.wcagLevel || this.config.defaultWCAGLevel;
-            // Try browser-based audit if available
             if (this.shouldUseBrowserMode()) {
-                // First, try agent-browser if available
                 const browserClient = await this.getBrowserClient();
                 if (browserClient) {
-                    const browserResult = await this.auditWithBrowserClient(browserClient, url, wcagLevel, options);
+                    const browserResult = await auditWithBrowserClient(browserClient, url, wcagLevel, this.config.browserConfig, options);
                     if (browserResult.success) {
                         await this.storeReport(browserResult.value);
                         return browserResult;
                     }
-                    const errorMsg = this.getErrorMessage(browserResult);
+                    const errorMsg = getErrorMessage(browserResult);
                     console.warn(`Browser client audit failed: ${errorMsg}`);
                 }
-                // Fall back to Vibium if available
                 if (this.vibiumClient && isBrowserModeEnabled() && isAxeCoreEnabled()) {
-                    const vibiumResult = await this.auditWithBrowser(url, wcagLevel, options);
+                    const vibiumResult = await auditWithVibium(this.vibiumClient, url, wcagLevel, this.config.browserConfig, options);
                     if (vibiumResult.success) {
                         await this.storeReport(vibiumResult.value);
                         return vibiumResult;
                     }
-                    const errorMsg = this.getErrorMessage(vibiumResult);
+                    const errorMsg = getErrorMessage(vibiumResult);
                     console.warn(`Vibium audit failed, falling back to heuristic mode: ${errorMsg}`);
                 }
             }
-            // Use heuristic-based audit
             return this.auditWithHeuristics(url, wcagLevel, options);
         }
         catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
+            return err(toError(error));
         }
     }
-    /**
-     * Run accessibility audit using unified browser client (agent-browser or other)
-     *
-     * This method uses the IBrowserClient interface for browser automation.
-     * For agent-browser, it uses getSnapshot() for element discovery and
-     * evaluate() to inject and run axe-core for accessibility testing.
-     *
-     * @param client - Browser client instance
-     * @param url - URL to audit
-     * @param wcagLevel - WCAG conformance level
-     * @param options - Audit options
-     * @returns AccessibilityReport from browser-based axe-core audit
-     */
-    async auditWithBrowserClient(client, url, wcagLevel, options) {
-        try {
-            // Launch browser
-            const launchResult = await client.launch({
-                headless: this.config.browserConfig.headless,
-            });
-            if (!launchResult.success) {
-                return err(new Error(`Failed to launch browser: ${launchResult.error?.message ?? 'Unknown error'}`));
-            }
-            try {
-                // Navigate to URL
-                const navResult = await client.navigate(url);
-                if (!navResult.success) {
-                    return err(new Error(`Failed to navigate to ${url}: ${navResult.error?.message ?? 'Unknown error'}`));
-                }
-                // For agent-browser, get snapshot for element context
-                if (this.isAgentBrowserClient(client)) {
-                    const snapshotResult = await client.getSnapshot({ interactive: true });
-                    if (snapshotResult.success) {
-                        // Snapshot provides element refs that can be used for targeted testing
-                        // Log element count for debugging
-                        const elementCount = snapshotResult.value.interactiveElements.length;
-                        console.debug(`[AccessibilityTester] Found ${elementCount} interactive elements`);
-                    }
-                }
-                // Inject and run axe-core
-                const axeResult = await this.runAxeCore(client, wcagLevel, options);
-                if (!axeResult.success) {
-                    return err(axeResult.error);
-                }
-                // Map axe-core result to AccessibilityReport
-                const report = this.mapAxeResultToReport(url, axeResult.value, wcagLevel);
-                return ok(report);
-            }
-            finally {
-                // Always clean up browser
-                await client.quit();
+    async auditElement(url, selector) {
+        if (this.shouldUseBrowserMode() && this.vibiumClient) {
+            const browserResult = await auditElementWithVibium(this.vibiumClient, url, selector, this.config.defaultWCAGLevel, this.config.browserConfig);
+            if (browserResult.success) {
+                await this.storeReport(browserResult.value);
+                return browserResult;
             }
+            const errorMsg = getErrorMessage(browserResult);
+            console.warn(`Browser mode element audit failed, falling back to heuristic mode: ${errorMsg}`);
         }
-        catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
-        }
-    }
-    /**
-     * Inject and run axe-core in the browser context
-     *
-     * @param client - Browser client
-     * @param wcagLevel - WCAG conformance level
-     * @param options - Audit options
-     * @returns Axe-core results
-     */
-    async runAxeCore(client, wcagLevel, options) {
-        // Build axe-core configuration based on WCAG level
-        const tags = this.getAxeTagsForWcagLevel(wcagLevel);
-        const excludeSelectors = options?.excludeSelectors ?? [];
-        // Inject axe-core and run accessibility checks
-        const axeScript = `
-      (async function() {
-        // Check if axe is already loaded
-        if (typeof axe === 'undefined') {
-          // Inject axe-core from CDN
-          const script = document.createElement('script');
-          script.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.8.4/axe.min.js';
-          script.crossOrigin = 'anonymous';
-          document.head.appendChild(script);
-
-          // Wait for script to load
-          await new Promise((resolve, reject) => {
-            script.onload = resolve;
-            script.onerror = () => reject(new Error('Failed to load axe-core'));
-            setTimeout(() => reject(new Error('Timeout loading axe-core')), 10000);
-          });
-        }
-
-        // Configure and run axe
-        const config = {
-          runOnly: {
-            type: 'tag',
-            values: ${JSON.stringify(tags)}
-          },
-          exclude: ${JSON.stringify(excludeSelectors.map(s => [s]))}
-        };
-
-        const results = await axe.run(document, config);
-
-        return JSON.stringify({
-          violations: results.violations.map(v => ({
-            id: v.id,
-            impact: v.impact,
-            description: v.description,
-            help: v.help,
-            helpUrl: v.helpUrl,
-            tags: v.tags,
-            nodes: v.nodes.map(n => ({
-              selector: n.target.join(' > '),
-              html: n.html,
-              target: n.target,
-              failureSummary: n.failureSummary
-            }))
-          })),
-          passes: results.passes.map(p => p.id),
-          incomplete: results.incomplete.map(i => i.id),
-          inapplicable: results.inapplicable.map(i => i.id)
+        return this.audit(url, {
+            excludeSelectors: [],
+            wcagLevel: this.config.defaultWCAGLevel,
         });
-      })();
-    `;
-        const evalResult = await client.evaluate(axeScript);
-        if (!evalResult.success) {
-            return err(new Error(`Failed to run axe-core: ${evalResult.error?.message ?? 'Unknown error'}`));
-        }
-        try {
-            const parsed = JSON.parse(evalResult.value);
-            return ok(parsed);
-        }
-        catch (parseError) {
-            return err(new Error(`Failed to parse axe-core results: ${parseError}`));
-        }
-    }
-    /**
-     * Get axe-core tags for a WCAG conformance level
-     */
-    getAxeTagsForWcagLevel(level) {
-        const baseTags = ['wcag2a', 'wcag21a', 'wcag22a', 'best-practice'];
-        if (level === 'A') {
-            return baseTags;
-        }
-        const aaTags = [...baseTags, 'wcag2aa', 'wcag21aa', 'wcag22aa'];
-        if (level === 'AA') {
-            return aaTags;
-        }
-        // AAA includes everything
-        return [...aaTags, 'wcag2aaa', 'wcag21aaa', 'wcag22aaa'];
-    }
-    /**
-     * Map axe-core result to AccessibilityReport
-     */
-    mapAxeResultToReport(url, axeResult, wcagLevel) {
-        // Map violations
-        const violations = axeResult.violations.map(v => ({
-            id: v.id,
-            impact: this.mapImpactSeverity(v.impact ?? 'moderate'),
-            wcagCriteria: this.extractWcagCriteria(v.tags ?? [], wcagLevel),
-            description: v.description,
-            help: v.help,
-            helpUrl: v.helpUrl ?? `https://dequeuniversity.com/rules/axe/4.8/${v.id}`,
-            nodes: v.nodes.map(n => ({
-                selector: n.selector,
-                html: n.html,
-                target: n.target,
-                failureSummary: n.failureSummary ?? '',
-            })),
-        }));
-        // Map passed rules
-        const passes = axeResult.passes.map(ruleId => ({
-            id: ruleId,
-            description: `Rule ${ruleId} passed`,
-            nodes: 0,
-        }));
-        // Map incomplete checks
-        const incomplete = axeResult.incomplete.map(ruleId => ({
-            id: ruleId,
-            description: `Rule ${ruleId} requires manual review`,
-            reason: 'Could not automatically determine compliance',
-            nodes: [],
-        }));
-        // Calculate score
-        const totalRules = violations.length + passes.length + incomplete.length;
-        const failedWeight = violations.reduce((sum, v) => {
-            const weights = { critical: 4, serious: 3, moderate: 2, minor: 1 };
-            return sum + weights[v.impact];
-        }, 0);
-        const maxWeight = totalRules * 4;
-        const score = totalRules > 0
-            ? Math.round(((maxWeight - failedWeight) / maxWeight) * 100)
-            : 100;
-        return {
-            url,
-            timestamp: new Date(),
-            violations,
-            passes,
-            incomplete,
-            score: Math.max(0, Math.min(100, score)),
-            wcagLevel,
-        };
-    }
-    /**
-     * Extract WCAG criteria from axe-core tags
-     */
-    extractWcagCriteria(tags, defaultLevel) {
-        const criteria = [];
-        for (const tag of tags) {
-            // Match patterns like wcag111, wcag2111
-            const match = tag.match(/^wcag(\d)(\d)(\d)(\d)?$/);
-            if (match) {
-                const id = match[4]
-                    ? `${match[1]}.${match[2]}.${match[3]}${match[4]}`
-                    : `${match[1]}.${match[2]}.${match[3]}`;
-                const existing = WCAG_CRITERIA[id];
-                if (existing) {
-                    criteria.push(existing);
-                }
-                else {
-                    criteria.push({
-                        id,
-                        level: defaultLevel,
-                        title: `WCAG ${id}`,
-                    });
-                }
-            }
-        }
-        return criteria;
     }
-    /**
-     * Run accessibility audit using browser via Vibium (legacy method)
-     *
-     * @param url - URL to audit
-     * @param wcagLevel - WCAG conformance level
-     * @param options - Audit options
-     * @returns AccessibilityReport from browser-based axe-core audit
-     */
-    async auditWithBrowser(url, wcagLevel, options) {
-        if (!this.vibiumClient) {
-            return err(new Error('Vibium client not available'));
-        }
-        try {
-            // Launch browser
-            const launchResult = await this.vibiumClient.launch({
-                headless: this.config.browserConfig.headless,
-            });
-            if (!launchResult.success) {
-                return err(new Error(`Failed to launch browser: ${this.getErrorMessage(launchResult)}`));
-            }
-            try {
-                // Navigate to URL
-                const navResult = await this.vibiumClient.navigate({
-                    url,
-                    waitUntil: 'networkidle',
-                    timeout: this.config.browserConfig.timeout,
-                });
-                if (!navResult.success) {
-                    return err(new Error(`Failed to navigate to ${url}: ${this.getErrorMessage(navResult)}`));
-                }
-                // Run accessibility checks via Vibium
-                const a11yResult = await this.vibiumClient.checkAccessibility({
-                    wcagLevel,
-                    selector: options?.excludeSelectors?.[0], // Use first exclude selector if provided
-                });
-                if (!a11yResult.success) {
-                    return err(new Error(`Accessibility check failed: ${this.getErrorMessage(a11yResult)}`));
-                }
-                // Map Vibium result to AccessibilityReport
-                const report = this.mapVibiumResultToReport(url, a11yResult.value, wcagLevel);
-                return ok(report);
-            }
-            finally {
-                // Always clean up browser
-                await this.vibiumClient.quit();
-            }
-        }
-        catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
-        }
-    }
-    /**
-     * Map Vibium accessibility result to our AccessibilityReport format
-     */
-    mapVibiumResultToReport(url, vibiumResult, wcagLevel) {
-        // Map violations from Vibium format to our format
-        const violations = vibiumResult.violations.map((v) => ({
-            id: v.id,
-            impact: this.mapImpactSeverity(v.impact),
-            wcagCriteria: v.wcagCriterion
-                ? [{ id: v.wcagCriterion, level: wcagLevel, title: v.rule }]
-                : [],
-            description: v.description,
-            help: v.help,
-            helpUrl: v.helpUrl ?? `https://www.w3.org/WAI/WCAG22/Understanding/`,
-            nodes: v.nodes.map((n) => ({
-                selector: n.selector,
-                html: n.html,
-                target: n.target,
-                failureSummary: n.failureSummary,
-            })),
-        }));
-        // Map passed rules
-        const passes = vibiumResult.passedRules.map((ruleId) => ({
-            id: ruleId,
-            description: `Rule ${ruleId} passed`,
-            nodes: 0, // Vibium doesn't provide node count for passed rules
-        }));
-        // Map incomplete checks
-        const incomplete = vibiumResult.incompleteRules.map((ruleId) => ({
-            id: ruleId,
-            description: `Rule ${ruleId} requires manual review`,
-            reason: 'Could not automatically determine compliance',
-            nodes: [],
-        }));
-        // Calculate score from violation severity weights
-        const totalRules = violations.length + passes.length + incomplete.length;
-        const failedWeight = violations.reduce((sum, v) => {
-            const weights = { critical: 4, serious: 3, moderate: 2, minor: 1 };
-            return sum + weights[v.impact];
-        }, 0);
-        const maxWeight = totalRules * 4; // Assume worst case all critical
-        const score = totalRules > 0
-            ? Math.round(((maxWeight - failedWeight) / maxWeight) * 100)
-            : 100;
-        return {
-            url,
-            timestamp: new Date(),
-            violations,
-            passes,
-            incomplete,
-            score: Math.max(0, Math.min(100, score)),
-            wcagLevel,
-        };
-    }
-    /**
-     * Map Vibium Severity type to our impact type
-     */
-    mapImpactSeverity(severity) {
-        const severityMap = {
-            critical: 'critical',
-            high: 'serious',
-            medium: 'moderate',
-            low: 'minor',
-            info: 'minor',
-        };
-        return severityMap[severity] ?? 'moderate';
-    }
-    /**
-     * Run accessibility audit using heuristic-based URL pattern analysis
-     *
-     * This is the fallback mode when browser automation is not available.
-     *
-     * @param url - URL to audit
-     * @param wcagLevel - WCAG conformance level
-     * @param options - Audit options
-     * @returns AccessibilityReport from heuristic analysis
-     */
+    // ============================================================================
+    // Heuristic Audit
+    // ============================================================================
     async auditWithHeuristics(url, wcagLevel, options) {
         try {
             const includeWarnings = options?.includeWarnings ?? this.config.includeWarnings;
-            // Filter rules based on WCAG level and warning preference
             const applicableRules = includeWarnings
-                ? this.filterRulesByLevel(wcagLevel)
-                : this.filterRulesByLevel(wcagLevel).filter(r => r.impact !== 'minor');
-            // Run each rule against the URL context
-            // Note: Without browser automation, rules use heuristic-based checks
+                ? filterRulesByLevel(this.rules, wcagLevel)
+                : filterRulesByLevel(this.rules, wcagLevel).filter(r => r.impact !== 'minor');
             const violations = [];
             const passes = [];
             const incomplete = [];
             for (const rule of applicableRules) {
-                const result = this.runRule(rule, { url });
+                const result = runRule(rule, { url }, this.config.simulationMode, this.config.enableColorContrastCheck);
                 if (result.nodes.length > 0) {
                     violations.push({
                         id: rule.id,
@@ -619,7 +190,6 @@ export class AccessibilityTesterService {
                     });
                 }
             }
-            // Calculate score (0-100)
             const totalChecks = applicableRules.length;
             const failedChecks = violations.length;
             const score = Math.round(((totalChecks - failedChecks) / totalChecks) * 100);
@@ -632,247 +202,58 @@ export class AccessibilityTesterService {
                 score,
                 wcagLevel,
             };
-            // Store report
             await this.storeReport(report);
             return ok(report);
         }
         catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
+            return err(toError(error));
         }
     }
-    /**
-     * Audit specific element
-     *
-     * In browser mode, uses Vibium to audit a specific element.
-     * In heuristic mode, runs a full page audit.
-     *
-     * @param url - URL containing the element
-     * @param selector - CSS selector for the element to audit
-     * @returns AccessibilityReport for the specified element
-     */
-    async auditElement(url, selector) {
-        // Try browser-based element audit if available
-        if (this.shouldUseBrowserMode()) {
-            const browserResult = await this.auditElementWithBrowser(url, selector);
-            if (browserResult.success) {
-                await this.storeReport(browserResult.value);
-                return browserResult;
-            }
-            // Fall back to heuristic mode
-            const errorMsg = this.getErrorMessage(browserResult);
-            console.warn(`Browser mode element audit failed, falling back to heuristic mode: ${errorMsg}`);
-        }
-        // For heuristic mode, we run a full page audit
-        // Selector is reserved for future element-specific heuristic auditing
-        return this.audit(url, {
-            excludeSelectors: [],
-            wcagLevel: this.config.defaultWCAGLevel,
-        });
-    }
-    /**
-     * Audit specific element using browser via Vibium
-     */
-    async auditElementWithBrowser(url, selector) {
-        if (!this.vibiumClient) {
-            return err(new Error('Vibium client not available'));
-        }
-        try {
-            // Launch browser
-            const launchResult = await this.vibiumClient.launch({
-                headless: this.config.browserConfig.headless,
-            });
-            if (!launchResult.success) {
-                return err(new Error(`Failed to launch browser: ${this.getErrorMessage(launchResult)}`));
-            }
-            try {
-                // Navigate to URL
-                const navResult = await this.vibiumClient.navigate({
-                    url,
-                    waitUntil: 'networkidle',
-                    timeout: this.config.browserConfig.timeout,
-                });
-                if (!navResult.success) {
-                    return err(new Error(`Failed to navigate to ${url}: ${this.getErrorMessage(navResult)}`));
-                }
-                // Run accessibility checks on specific element via Vibium
-                const a11yResult = await this.vibiumClient.checkAccessibility({
-                    wcagLevel: this.config.defaultWCAGLevel,
-                    selector, // Target specific element
-                });
-                if (!a11yResult.success) {
-                    return err(new Error(`Element accessibility check failed: ${this.getErrorMessage(a11yResult)}`));
-                }
-                // Map Vibium result to AccessibilityReport
-                const report = this.mapVibiumResultToReport(url, a11yResult.value, this.config.defaultWCAGLevel);
-                return ok(report);
-            }
-            finally {
-                // Always clean up browser
-                await this.vibiumClient.quit();
-            }
-        }
-        catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
-        }
-    }
-    /**
-     * Check color contrast
-     * Analyzes common page elements for WCAG 2.2 contrast compliance
-     *
-     * In browser mode, uses Vibium to run actual axe-core color contrast checks.
-     * In heuristic mode, provides estimated contrast analysis based on URL patterns.
-     *
-     * @param url - URL to check
-     * @returns Array of ContrastAnalysis for page elements
-     */
+    // ============================================================================
+    // Contrast Analysis
+    // ============================================================================
     async checkContrast(url) {
         try {
-            // Check if we have cached results for this URL
-            const cacheKey = `visual-accessibility:contrast:${this.hashUrl(url)}`;
+            const cacheKey = `visual-accessibility:contrast:${hashUrl(url)}`;
             const cached = await this.memory.get(cacheKey);
-            if (cached) {
+            if (cached)
                 return ok(cached);
-            }
             let analyses;
-            // Try browser-based contrast check if available
-            if (this.shouldUseBrowserMode()) {
-                const browserResult = await this.checkContrastWithBrowser(url);
+            if (this.shouldUseBrowserMode() && this.vibiumClient) {
+                const browserResult = await checkContrastWithVibium(this.vibiumClient, url, this.config.defaultWCAGLevel, this.config.browserConfig);
                 if (browserResult.success) {
                     analyses = browserResult.value;
                 }
                 else {
-                    // Fall back to heuristic mode
-                    const errorMsg = this.getErrorMessage(browserResult);
+                    const errorMsg = getErrorMessage(browserResult);
                     console.warn(`Browser mode contrast check failed, falling back to heuristic mode: ${errorMsg}`);
-                    analyses = this.analyzeContrastForElements(url);
+                    analyses = analyzeContrastForElements(url);
                 }
             }
             else {
-                // Use heuristic-based analysis
-                analyses = this.analyzeContrastForElements(url);
+                analyses = analyzeContrastForElements(url);
             }
-            // Store results
-            await this.memory.set(cacheKey, analyses, {
-                namespace: 'visual-accessibility',
-                ttl: 3600,
-            });
+            await this.memory.set(cacheKey, analyses, { namespace: 'visual-accessibility', ttl: 3600 });
             return ok(analyses);
         }
         catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
+            return err(toError(error));
         }
     }
-    /**
-     * Check color contrast using browser via Vibium
-     *
-     * Runs axe-core color contrast checks against the actual rendered page
-     * to get accurate foreground/background color values and ratios.
-     */
-    async checkContrastWithBrowser(url) {
-        if (!this.vibiumClient) {
-            return err(new Error('Vibium client not available'));
-        }
-        try {
-            // Launch browser
-            const launchResult = await this.vibiumClient.launch({
-                headless: this.config.browserConfig.headless,
-            });
-            if (!launchResult.success) {
-                return err(new Error(`Failed to launch browser: ${this.getErrorMessage(launchResult)}`));
-            }
-            try {
-                // Navigate to URL
-                const navResult = await this.vibiumClient.navigate({
-                    url,
-                    waitUntil: 'networkidle',
-                    timeout: this.config.browserConfig.timeout,
-                });
-                if (!navResult.success) {
-                    return err(new Error(`Failed to navigate to ${url}: ${this.getErrorMessage(navResult)}`));
-                }
-                // Run accessibility checks - focus on color-contrast rules
-                const a11yResult = await this.vibiumClient.checkAccessibility({
-                    wcagLevel: this.config.defaultWCAGLevel,
-                    rules: {
-                        include: ['color-contrast'],
-                    },
-                });
-                if (!a11yResult.success) {
-                    return err(new Error(`Contrast check failed: ${this.getErrorMessage(a11yResult)}`));
-                }
-                // Extract contrast analysis from violations
-                const analyses = this.extractContrastFromVibiumResult(a11yResult.value);
-                return ok(analyses);
-            }
-            finally {
-                // Always clean up browser
-                await this.vibiumClient.quit();
-            }
-        }
-        catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
-        }
-    }
-    /**
-     * Extract contrast analysis from Vibium accessibility result
-     */
-    extractContrastFromVibiumResult(vibiumResult) {
-        const analyses = [];
-        // Process contrast violations
-        for (const violation of vibiumResult.violations) {
-            if (violation.rule.includes('contrast') || violation.id.includes('contrast')) {
-                for (const node of violation.nodes) {
-                    // Extract colors from failure summary if available
-                    const colorMatch = node.failureSummary.match(/foreground:?\s*([#\w\d]+).*?background:?\s*([#\w\d]+)/i);
-                    const ratioMatch = node.failureSummary.match(/ratio\s*[:\s]*(\d+\.?\d*)/i);
-                    analyses.push({
-                        element: node.selector,
-                        foreground: colorMatch?.[1] || '#000000',
-                        background: colorMatch?.[2] || '#ffffff',
-                        ratio: ratioMatch ? parseFloat(ratioMatch[1]) : 1.0,
-                        requiredRatio: this.config.defaultWCAGLevel === 'AAA' ? 7 : 4.5,
-                        passes: false,
-                        wcagLevel: this.config.defaultWCAGLevel,
-                    });
-                }
-            }
-        }
-        // If no violations, add passing analyses for common elements
-        if (analyses.length === 0 && vibiumResult.passedRules.some(r => r.includes('contrast'))) {
-            const commonElements = ['h1', 'p', 'a', 'button'];
-            for (const element of commonElements) {
-                analyses.push({
-                    element,
-                    foreground: '#333333',
-                    background: '#ffffff',
-                    ratio: 12.63, // High contrast ratio for passing
-                    requiredRatio: this.config.defaultWCAGLevel === 'AAA' ? 7 : 4.5,
-                    passes: true,
-                    wcagLevel: this.config.defaultWCAGLevel,
-                });
-            }
-        }
-        return analyses;
-    }
-    /**
-     * Validate against specific WCAG level
-     * Evaluates page compliance with WCAG 2.2 success criteria
-     */
+    // ============================================================================
+    // WCAG Validation
+    // ============================================================================
     async validateWCAGLevel(url, level) {
         try {
-            // Get applicable criteria for level
             const levelOrder = { A: 1, AA: 2, AAA: 3 };
             const targetLevel = levelOrder[level];
             const applicableCriteria = Object.values(WCAG_CRITERIA).filter((c) => levelOrder[c.level] <= targetLevel);
-            // Run rule-based validation for each criterion
             const failedCriteria = [];
             const passedCriteria = [];
-            // Use URL hash as seed for deterministic results
-            const urlHash = this.hashUrl(url);
+            const urlHash = hashUrl(url);
             const hashNum = parseInt(urlHash, 36);
             for (const criterion of applicableCriteria) {
-                // Determine pass/fail based on rule implementation status and URL hash
-                const ruleResult = this.validateCriterion(criterion, hashNum);
+                const ruleResult = validateCriterion(criterion, hashNum);
                 if (ruleResult.passed) {
                     passedCriteria.push(criterion);
                 }
@@ -882,814 +263,56 @@ export class AccessibilityTesterService {
             }
             const passed = failedCriteria.length === 0;
             const score = Math.round((passedCriteria.length / applicableCriteria.length) * 100);
-            return ok({
-                level,
-                passed,
-                failedCriteria,
-                passedCriteria,
-                score,
-            });
+            return ok({ level, passed, failedCriteria, passedCriteria, score });
         }
         catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
+            return err(toError(error));
         }
     }
-    /**
-     * Validate a specific WCAG criterion
-     */
-    validateCriterion(criterion, urlHash) {
-        // Define common failure scenarios based on criterion
-        const criterionFailureRates = {
-            '1.1.1': 0.12, // Non-text content - missing alt text common
-            '1.3.1': 0.08, // Info and relationships - heading structure issues
-            '1.4.1': 0.05, // Use of color - rare issue
-            '1.4.3': 0.15, // Contrast - very common issue
-            '1.4.6': 0.25, // Enhanced contrast - stricter, more failures
-            '2.1.1': 0.10, // Keyboard - mouse-only interactions
-            '2.1.2': 0.03, // No keyboard trap - uncommon but critical
-            '2.4.1': 0.08, // Bypass blocks - skip links often missing
-            '2.4.3': 0.06, // Focus order - usually correct
-            '2.4.4': 0.10, // Link purpose - generic link text
-            '2.4.7': 0.12, // Focus visible - custom styles hide focus
-            '3.1.1': 0.04, // Language of page - usually present
-            '4.1.1': 0.02, // Parsing - HTML validation
-            '4.1.2': 0.09, // Name, role, value - ARIA issues
-        };
-        const failureRate = criterionFailureRates[criterion.id] ?? 0.1;
-        // Use hash to determine pass/fail deterministically
-        // Different criterion IDs should produce different results
-        const criterionHashOffset = criterion.id.charCodeAt(0) * 100;
-        const determinant = ((urlHash + criterionHashOffset) % 100) / 100;
-        const passed = determinant >= failureRate;
-        return {
-            passed,
-            reason: passed ? undefined : `Criterion ${criterion.id} (${criterion.title}) not fully satisfied`,
-        };
-    }
-    /**
-     * Check keyboard navigation
-     * Analyzes focusable elements, tab order, and potential focus traps
-     *
-     * In browser mode, uses Vibium to inspect actual focusable elements.
-     * In heuristic mode, provides estimated analysis based on URL patterns.
-     *
-     * @param url - URL to check
-     * @returns KeyboardNavigationReport with tab order and issues
-     */
+    // ============================================================================
+    // Keyboard Navigation
+    // ============================================================================
     async checkKeyboardNavigation(url) {
         try {
-            // Check cache first
-            const cacheKey = `visual-accessibility:keyboard:${this.hashUrl(url)}`;
+            const cacheKey = `visual-accessibility:keyboard:${hashUrl(url)}`;
             const cached = await this.memory.get(cacheKey);
-            if (cached) {
+            if (cached)
                 return ok(cached);
-            }
             let report;
-            // Try browser-based keyboard check if available
-            if (this.shouldUseBrowserMode() && this.config.enableKeyboardCheck) {
-                const browserResult = await this.checkKeyboardWithBrowser(url);
+            if (this.shouldUseBrowserMode() && this.config.enableKeyboardCheck && this.vibiumClient) {
+                const browserResult = await checkKeyboardWithVibium(this.vibiumClient, url, this.config.defaultWCAGLevel, this.config.browserConfig);
                 if (browserResult.success) {
                     report = browserResult.value;
                 }
                 else {
-                    // Fall back to heuristic mode
-                    const errorMsg = this.getErrorMessage(browserResult);
+                    const errorMsg = getErrorMessage(browserResult);
                     console.warn(`Browser mode keyboard check failed, falling back to heuristic mode: ${errorMsg}`);
-                    report = this.generateKeyboardReportWithHeuristics(url);
+                    report = generateKeyboardReportWithHeuristics(url);
                 }
             }
             else {
-                // Use heuristic-based analysis
-                report = this.generateKeyboardReportWithHeuristics(url);
+                report = generateKeyboardReportWithHeuristics(url);
             }
-            // Store report
-            await this.memory.set(cacheKey, report, {
-                namespace: 'visual-accessibility',
-                ttl: 3600,
-            });
+            await this.memory.set(cacheKey, report, { namespace: 'visual-accessibility', ttl: 3600 });
             return ok(report);
         }
         catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
+            return err(toError(error));
         }
     }
-    /**
-     * Generate keyboard navigation report using heuristics
-     */
-    generateKeyboardReportWithHeuristics(url) {
-        const urlHash = this.hashUrl(url);
-        const tabOrder = this.generateTabOrder(url, urlHash);
-        const issues = this.detectKeyboardIssues(tabOrder);
-        const traps = this.detectFocusTraps(url, urlHash);
-        return {
-            url,
-            focusableElements: tabOrder.length,
-            tabOrder,
-            issues,
-            traps,
-        };
-    }
-    /**
-     * Check keyboard navigation using browser via Vibium
-     *
-     * Uses Vibium to find focusable elements and analyze their tab order.
-     */
-    async checkKeyboardWithBrowser(url) {
-        if (!this.vibiumClient) {
-            return err(new Error('Vibium client not available'));
-        }
-        try {
-            // Launch browser
-            const launchResult = await this.vibiumClient.launch({
-                headless: this.config.browserConfig.headless,
-            });
-            if (!launchResult.success) {
-                return err(new Error(`Failed to launch browser: ${this.getErrorMessage(launchResult)}`));
-            }
-            try {
-                // Navigate to URL
-                const navResult = await this.vibiumClient.navigate({
-                    url,
-                    waitUntil: 'networkidle',
-                    timeout: this.config.browserConfig.timeout,
-                });
-                if (!navResult.success) {
-                    return err(new Error(`Failed to navigate to ${url}: ${this.getErrorMessage(navResult)}`));
-                }
-                // Find all focusable elements
-                const focusableSelector = 'a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])';
-                const elementsResult = await this.vibiumClient.findElements({
-                    selector: focusableSelector,
-                    visible: true,
-                });
-                if (!elementsResult.success) {
-                    return err(new Error(`Failed to find focusable elements: ${this.getErrorMessage(elementsResult)}`));
-                }
-                // Build tab order from found elements
-                const tabOrder = elementsResult.value.map((elem, index) => ({
-                    index,
-                    selector: elem.selector,
-                    elementType: this.getElementType(elem.tagName),
-                    hasVisibleFocus: true, // Assume visible in browser mode (axe-core handles this)
-                }));
-                // Run accessibility checks for keyboard-related rules
-                const a11yResult = await this.vibiumClient.checkAccessibility({
-                    wcagLevel: this.config.defaultWCAGLevel,
-                    rules: {
-                        include: ['keyboard', 'focus-order', 'focus-trap', 'bypass-blocks'],
-                    },
-                });
-                // Extract keyboard issues from accessibility results
-                const issues = [];
-                const traps = [];
-                if (a11yResult.success) {
-                    for (const violation of a11yResult.value.violations) {
-                        if (violation.rule.includes('focus') || violation.rule.includes('keyboard')) {
-                            for (const node of violation.nodes) {
-                                if (violation.rule.includes('trap')) {
-                                    traps.push({
-                                        selector: node.selector,
-                                        description: node.failureSummary,
-                                        escapePath: 'Ensure Escape key or Tab can exit this element',
-                                    });
-                                }
-                                else {
-                                    issues.push({
-                                        type: this.mapKeyboardIssueType(violation.rule),
-                                        selector: node.selector,
-                                        description: node.failureSummary,
-                                    });
-                                }
-                            }
-                        }
-                    }
-                }
-                const report = {
-                    url,
-                    focusableElements: tabOrder.length,
-                    tabOrder,
-                    issues,
-                    traps,
-                };
-                return ok(report);
-            }
-            finally {
-                // Always clean up browser
-                await this.vibiumClient.quit();
-            }
-        }
-        catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
-        }
-    }
-    /**
-     * Get element type from tag name
-     */
-    getElementType(tagName) {
-        const tagMap = {
-            a: 'link',
-            button: 'button',
-            input: 'input',
-            select: 'input',
-            textarea: 'input',
-        };
-        return tagMap[tagName.toLowerCase()] || 'other';
-    }
-    /**
-     * Map violation rule to keyboard issue type
-     */
-    mapKeyboardIssueType(rule) {
-        if (rule.includes('focus-indicator') || rule.includes('visible')) {
-            return 'no-focus-indicator';
-        }
-        if (rule.includes('skip') || rule.includes('bypass')) {
-            return 'skip-link-missing';
-        }
-        if (rule.includes('order') || rule.includes('sequence')) {
-            return 'incorrect-tab-order';
-        }
-        return 'non-interactive-focusable';
-    }
     // ============================================================================
-    // Private Helper Methods
+    // Storage
     // ============================================================================
-    /**
-     * Extract error message from a Result
-     * Type-safe helper that checks success status and returns error message
-     */
-    getErrorMessage(result) {
-        if (result.success === false) {
-            return result.error?.message ?? 'Unknown error';
-        }
-        return 'Unknown error';
-    }
-    initializeRules() {
-        return [
-            {
-                id: 'image-alt',
-                description: 'Images must have alternate text',
-                wcagCriteria: ['1.1.1'],
-                impact: 'critical',
-                simulationFailureRate: 0.1,
-            },
-            {
-                id: 'button-name',
-                description: 'Buttons must have discernible text',
-                wcagCriteria: ['4.1.2'],
-                impact: 'critical',
-                simulationFailureRate: 0.05,
-            },
-            {
-                id: 'color-contrast',
-                description: 'Elements must have sufficient color contrast',
-                wcagCriteria: ['1.4.3'],
-                impact: 'serious',
-                simulationFailureRate: 0.15,
-            },
-            {
-                id: 'html-lang',
-                description: 'HTML element must have a lang attribute',
-                wcagCriteria: ['3.1.1'],
-                impact: 'serious',
-                simulationFailureRate: 0.02,
-            },
-            {
-                id: 'link-name',
-                description: 'Links must have discernible text',
-                wcagCriteria: ['2.4.4', '4.1.2'],
-                impact: 'serious',
-                simulationFailureRate: 0.08,
-            },
-            {
-                id: 'focus-visible',
-                description: 'Interactive elements must have visible focus indication',
-                wcagCriteria: ['2.4.7'],
-                impact: 'serious',
-                simulationFailureRate: 0.12,
-            },
-            {
-                id: 'bypass-blocks',
-                description: 'Page must have means to bypass repeated blocks',
-                wcagCriteria: ['2.4.1'],
-                impact: 'moderate',
-                simulationFailureRate: 0.1,
-            },
-            {
-                id: 'label',
-                description: 'Form elements must have labels',
-                wcagCriteria: ['1.3.1', '4.1.2'],
-                impact: 'critical',
-                simulationFailureRate: 0.07,
-            },
-            {
-                id: 'keyboard-trap',
-                description: 'Focus must not be trapped',
-                wcagCriteria: ['2.1.2'],
-                impact: 'critical',
-                simulationFailureRate: 0.02,
-            },
-            {
-                id: 'focus-order',
-                description: 'Focus order must be logical',
-                wcagCriteria: ['2.4.3'],
-                impact: 'moderate',
-                simulationFailureRate: 0.05,
-            },
-        ];
-    }
-    filterRulesByLevel(level) {
-        const levelOrder = { A: 1, AA: 2, AAA: 3 };
-        const targetLevel = levelOrder[level];
-        return this.rules.filter((rule) => {
-            return rule.wcagCriteria.some((criteriaId) => {
-                const criterion = WCAG_CRITERIA[criteriaId];
-                return criterion && levelOrder[criterion.level] <= targetLevel;
-            });
-        });
-    }
-    runRule(rule, context) {
-        // Simulation mode: use deterministic results based on URL hash
-        if (this.config.simulationMode) {
-            const nodes = this.checkRuleDeterministic(rule, context);
-            const checkedNodes = this.estimateCheckedNodes(rule, context);
-            return {
-                nodes,
-                passed: nodes.length === 0,
-                checkedNodes,
-            };
-        }
-        // Production mode: perform heuristic-based WCAG rule checking
-        // without browser automation (static analysis based on URL patterns)
-        const nodes = this.checkRuleWithHeuristics(rule, context);
-        const checkedNodes = this.estimateCheckedNodes(rule, context);
-        return {
-            nodes,
-            passed: nodes.length === 0,
-            checkedNodes,
-        };
-    }
-    /**
-     * Heuristic-based WCAG rule checking for production mode.
-     * Analyzes URL patterns and common accessibility issues without browser automation.
-     * This provides baseline checks; full auditing requires browser-based tools like axe-core.
-     */
-    checkRuleWithHeuristics(rule, context) {
-        const nodes = [];
-        const url = context.url.toLowerCase();
-        // Analyze URL patterns to identify likely accessibility issues
-        switch (rule.id) {
-            case 'image-alt':
-                // Check for image-heavy pages that commonly have alt text issues
-                if (this.isLikelyImageHeavyPage(url)) {
-                    nodes.push(...this.generateImageAltWarnings(context));
-                }
-                break;
-            case 'button-name':
-                // Check for interactive pages that may have unlabeled buttons
-                if (this.isLikelyInteractivePage(url)) {
-                    nodes.push(...this.generateButtonNameWarnings(context));
-                }
-                break;
-            case 'color-contrast':
-                // Contrast issues are common - flag for manual review
-                if (this.config.enableColorContrastCheck) {
-                    nodes.push(...this.generateContrastWarnings(context));
-                }
-                break;
-            case 'html-lang':
-                // Language attribute check based on URL patterns
-                if (this.isLikelyMissingLang(url)) {
-                    nodes.push({
-                        selector: 'html',
-                        html: '<html>',
-                        target: ['html'],
-                        failureSummary: 'Page may be missing lang attribute',
-                        fixSuggestion: 'Add lang attribute to <html> element (e.g., <html lang="en">)',
-                    });
-                }
-                break;
-            case 'link-name':
-                // Check for pages with navigation that may have empty links
-                if (this.hasNavigationPatterns(url)) {
-                    nodes.push(...this.generateLinkNameWarnings(context));
-                }
-                break;
-            case 'focus-visible':
-                // Focus visibility issues common in modern SPAs
-                if (this.isLikelySPA(url)) {
-                    nodes.push(...this.generateFocusVisibleWarnings(context));
-                }
-                break;
-            case 'bypass-blocks':
-                // Skip links commonly missing
-                if (!this.hasSkipLinkPattern(url)) {
-                    nodes.push({
-                        selector: 'body',
-                        html: '<body>',
-                        target: ['body'],
-                        failureSummary: 'Page may lack skip navigation mechanism',
-                        fixSuggestion: 'Add a skip link at the beginning of the page to bypass repeated content',
-                    });
-                }
-                break;
-            case 'label':
-                // Form label issues on form pages
-                if (this.isFormPage(url)) {
-                    nodes.push(...this.generateFormLabelWarnings(context));
-                }
-                break;
-            case 'keyboard-trap':
-                // Modal/dialog patterns that may trap focus
-                if (this.hasModalPatterns(url)) {
-                    nodes.push(...this.generateKeyboardTrapWarnings(context));
-                }
-                break;
-            case 'focus-order':
-                // Focus order issues in complex layouts
-                if (this.hasComplexLayoutPatterns(url)) {
-                    nodes.push(...this.generateFocusOrderWarnings(context));
-                }
-                break;
-        }
-        return nodes;
-    }
-    // URL pattern detection helpers for heuristic analysis
-    isLikelyImageHeavyPage(url) {
-        return url.includes('gallery') || url.includes('photo') || url.includes('image') ||
-            url.includes('product') || url.includes('portfolio') || url.includes('media');
-    }
-    isLikelyInteractivePage(url) {
-        return url.includes('app') || url.includes('dashboard') || url.includes('editor') ||
-            url.includes('tool') || url.includes('builder') || url.includes('widget');
-    }
-    isLikelyMissingLang(url) {
-        // Static file servers and CDNs often miss lang attribute
-        return url.includes('cdn') || url.includes('static') || url.includes('.html') ||
-            url.includes('file://');
-    }
-    hasNavigationPatterns(url) {
-        return url.includes('nav') || url.includes('menu') || url.includes('header') ||
-            url.includes('sidebar') || url.includes('footer');
-    }
-    isLikelySPA(url) {
-        return url.includes('app') || url.includes('dashboard') || url.includes('#/') ||
-            url.includes('react') || url.includes('angular') || url.includes('vue');
-    }
-    hasSkipLinkPattern(url) {
-        // Most well-designed sites include skip links
-        return url.includes('gov') || url.includes('edu') || url.includes('a11y') ||
-            url.includes('accessible');
-    }
-    isFormPage(url) {
-        return url.includes('form') || url.includes('contact') || url.includes('register') ||
-            url.includes('signup') || url.includes('login') || url.includes('checkout') ||
-            url.includes('submit') || url.includes('search');
-    }
-    hasModalPatterns(url) {
-        return url.includes('modal') || url.includes('dialog') || url.includes('popup') ||
-            url.includes('overlay') || url.includes('lightbox');
-    }
-    hasComplexLayoutPatterns(url) {
-        return url.includes('dashboard') || url.includes('admin') || url.includes('grid') ||
-            url.includes('layout') || url.includes('multi');
-    }
-    // Warning generators for heuristic checks
-    generateImageAltWarnings(context) {
-        return [{
-                selector: 'img',
-                html: '<img src="...">',
-                target: ['img'],
-                failureSummary: 'Images should have descriptive alt text',
-                fixSuggestion: 'Add alt attribute with meaningful description to all <img> elements',
-            }];
-    }
-    generateButtonNameWarnings(context) {
-        return [{
-                selector: 'button:not([aria-label])',
-                html: '<button>',
-                target: ['button'],
-                failureSummary: 'Buttons should have accessible names',
-                fixSuggestion: 'Ensure buttons have visible text or aria-label attribute',
-            }];
-    }
-    generateContrastWarnings(context) {
-        return [{
-                selector: '.text-content',
-                html: '<div class="text-content">',
-                target: ['.text-content'],
-                failureSummary: 'Text elements should meet WCAG 2.2 AA contrast ratio (4.5:1)',
-                fixSuggestion: 'Verify text color has sufficient contrast against background',
-            }];
-    }
-    generateLinkNameWarnings(context) {
-        return [{
-                selector: 'a:not([aria-label])',
-                html: '<a href="#">',
-                target: ['a'],
-                failureSummary: 'Links should have descriptive text',
-                fixSuggestion: 'Add meaningful link text or aria-label attribute',
-            }];
-    }
-    generateFocusVisibleWarnings(context) {
-        return [{
-                selector: ':focus',
-                html: '<element>:focus',
-                target: [':focus'],
-                failureSummary: 'Interactive elements should have visible focus indicators',
-                fixSuggestion: 'Do not remove outline on :focus; use :focus-visible for styling',
-            }];
-    }
-    generateFormLabelWarnings(context) {
-        return [{
-                selector: 'input:not([aria-label]):not([id])',
-                html: '<input type="text">',
-                target: ['input'],
-                failureSummary: 'Form inputs should have associated labels',
-                fixSuggestion: 'Add <label for="id"> or aria-label to form inputs',
-            }];
-    }
-    generateKeyboardTrapWarnings(context) {
-        return [{
-                selector: '[role="dialog"]',
-                html: '<div role="dialog">',
-                target: ['[role="dialog"]'],
-                failureSummary: 'Modal dialogs should not trap keyboard focus',
-                fixSuggestion: 'Ensure Escape key closes modal and Tab cycles within dialog',
-            }];
-    }
-    generateFocusOrderWarnings(context) {
-        return [{
-                selector: '[tabindex]',
-                html: '<div tabindex="...">',
-                target: ['[tabindex]'],
-                failureSummary: 'Focus order should follow logical reading sequence',
-                fixSuggestion: 'Avoid positive tabindex values; use tabindex="0" or "-1"',
-            }];
-    }
-    /**
-     * Deterministic rule check for simulation mode only.
-     * Uses URL hash to produce consistent results without Math.random().
-     */
-    checkRuleDeterministic(rule, context) {
-        const nodes = [];
-        const urlHash = this.hashUrl(context.url);
-        const hashNum = parseInt(urlHash, 36);
-        // Use URL hash + rule ID to determine element count (1-10)
-        const ruleIdHash = rule.id.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0);
-        const elementCount = 1 + ((hashNum + ruleIdHash) % 10);
-        for (let i = 0; i < elementCount; i++) {
-            // Deterministic failure based on hash, rule failure rate, and element index
-            const determinant = ((hashNum + ruleIdHash + i * 100) % 100) / 100;
-            if (determinant < rule.simulationFailureRate) {
-                const selector = this.generateDeterministicSelector(rule.id, i);
-                nodes.push({
-                    selector,
-                    html: `<element class="${rule.id}-element-${i}">Content</element>`,
-                    target: [selector],
-                    failureSummary: 'Element does not meet accessibility requirements',
-                    fixSuggestion: 'Review and update the element to meet WCAG guidelines',
-                });
-            }
-        }
-        return nodes;
-    }
-    /**
-     * Generate a deterministic selector based on rule ID and index
-     */
-    generateDeterministicSelector(ruleId, index) {
-        const tagsByRule = {
-            'image-alt': ['img'],
-            'button-name': ['button'],
-            'color-contrast': ['div', 'p', 'span'],
-            'html-lang': ['html'],
-            'link-name': ['a'],
-            'focus-visible': ['button', 'a', 'input'],
-            'bypass-blocks': ['main', 'nav'],
-            'label': ['input', 'select', 'textarea'],
-            'keyboard-trap': ['div', 'dialog'],
-            'focus-order': ['button', 'a', 'input'],
-        };
-        const tags = tagsByRule[ruleId] || ['div'];
-        const tag = tags[index % tags.length];
-        const classes = ['content', 'widget', 'component', 'item', 'element'];
-        const className = classes[index % classes.length];
-        return `${tag}.${className}`;
-    }
-    /**
-     * Estimate the number of elements checked based on rule category
-     */
-    estimateCheckedNodes(rule, context) {
-        // Base estimate on rule category - different rules check different element types
-        const ruleId = rule.id.toLowerCase();
-        // Image rules typically check fewer elements
-        if (ruleId.includes('image') || ruleId.includes('alt')) {
-            return 5 + (context.url.length % 10); // 5-14 elements
-        }
-        // Form rules check form elements
-        if (ruleId.includes('form') || ruleId.includes('label') || ruleId.includes('input')) {
-            return 8 + (context.url.length % 12); // 8-19 elements
-        }
-        // Link rules check all anchor elements
-        if (ruleId.includes('link') || ruleId.includes('anchor')) {
-            return 15 + (context.url.length % 20); // 15-34 elements
-        }
-        // Color/contrast rules check text elements
-        if (ruleId.includes('color') || ruleId.includes('contrast')) {
-            return 20 + (context.url.length % 15); // 20-34 elements
-        }
-        // Heading rules check heading hierarchy
-        if (ruleId.includes('heading') || ruleId.includes('h1') || ruleId.includes('h2')) {
-            return 6 + (context.url.length % 8); // 6-13 elements
-        }
-        // ARIA rules check interactive elements
-        if (ruleId.includes('aria') || ruleId.includes('role')) {
-            return 12 + (context.url.length % 18); // 12-29 elements
-        }
-        // Default: moderate number of elements
-        return 10 + (context.url.length % 10); // 10-19 elements
-    }
-    /**
-     * Analyze contrast for common UI elements
-     */
-    analyzeContrastForElements(url) {
-        const elements = ['h1', 'p', 'a', 'button', '.card-text', '.nav-link'];
-        const analyses = [];
-        const urlHash = this.hashUrl(url);
-        const hashNum = parseInt(urlHash, 36);
-        for (let i = 0; i < elements.length; i++) {
-            const element = elements[i];
-            // Calculate contrast ratio deterministically based on URL and element
-            // Using common website patterns: most sites have decent contrast
-            const baseRatio = 4.5 + ((hashNum + i * 1000) % 100) / 10; // 4.5 to 14.5
-            const ratio = Math.round(baseRatio * 100) / 100;
-            // Large text (h1, button) requires 3:1, normal text requires 4.5:1
-            const isLargeText = element === 'h1' || element === 'button';
-            const requiredRatio = isLargeText ? 3 : 4.5;
-            const passes = ratio >= requiredRatio;
-            // Generate representative colors based on hash (hex format for test compatibility)
-            const fgValue = 20 + ((hashNum + i * 50) % 30); // 20-50 (dark, ~0x14-0x32)
-            const bgValue = 200 + ((hashNum + i * 30) % 55); // 200-255 (light)
-            const fgHex = fgValue.toString(16).padStart(2, '0');
-            const bgHex = bgValue.toString(16).padStart(2, '0');
-            analyses.push({
-                element,
-                foreground: `#${fgHex}${fgHex}${fgHex}`, // Grayscale hex
-                background: `#${bgHex}${bgHex}${bgHex}`, // Grayscale hex
-                ratio,
-                requiredRatio,
-                passes,
-                wcagLevel: 'AA',
-            });
-        }
-        return analyses;
-    }
-    /**
-     * Generate tab order based on URL structure
-     */
-    generateTabOrder(url, urlHash) {
-        const items = [];
-        const hashNum = parseInt(urlHash, 36);
-        // Standard focusable elements in typical page structure
-        const elements = [
-            { selector: '#skip-link', type: 'link' },
-            { selector: 'header nav a.logo', type: 'link' },
-            { selector: 'header nav a.menu-item', type: 'link' },
-            { selector: '#search-input', type: 'input' },
-            { selector: '#search-button', type: 'button' },
-            { selector: 'main a', type: 'link' },
-            { selector: 'main button', type: 'button' },
-            { selector: 'form input', type: 'input' },
-            { selector: 'form select', type: 'input' },
-            { selector: 'form button[type="submit"]', type: 'button' },
-            { selector: 'footer a', type: 'link' },
-        ];
-        // Determine which elements have visible focus (deterministic based on URL)
-        elements.forEach((elem, index) => {
-            // Most elements should have visible focus, ~12% don't
-            const focusVisibleDeterminant = (hashNum + index * 17) % 100;
-            const hasVisibleFocus = focusVisibleDeterminant >= 12;
-            items.push({
-                index,
-                selector: elem.selector,
-                elementType: elem.type,
-                hasVisibleFocus,
-            });
-        });
-        return items;
-    }
-    detectKeyboardIssues(tabOrder) {
-        const issues = [];
-        // Check for missing focus indicators
-        for (const item of tabOrder) {
-            if (!item.hasVisibleFocus) {
-                issues.push({
-                    type: 'no-focus-indicator',
-                    selector: item.selector,
-                    description: `Element ${item.selector} does not have a visible focus indicator`,
-                });
-            }
-        }
-        // Check for skip link
-        if (!tabOrder.some((item) => item.selector.includes('skip'))) {
-            issues.push({
-                type: 'skip-link-missing',
-                selector: 'body',
-                description: 'Page is missing a skip navigation link',
-            });
-        }
-        // Check for logical focus order issues
-        const hasLogicalOrder = tabOrder.every((item, index) => {
-            if (index === 0)
-                return true;
-            // Check that navigation elements come before main content
-            const isNav = item.selector.includes('nav') || item.selector.includes('header');
-            const prevIsMain = tabOrder[index - 1].selector.includes('main');
-            return !(isNav && prevIsMain);
-        });
-        if (!hasLogicalOrder) {
-            issues.push({
-                type: 'incorrect-tab-order',
-                selector: 'body',
-                description: 'Focus order does not follow logical reading sequence',
-            });
-        }
-        return issues;
-    }
-    /**
-     * Detect focus traps based on URL patterns
-     */
-    detectFocusTraps(url, urlHash) {
-        const traps = [];
-        const hashNum = parseInt(urlHash, 36);
-        // Check for common focus trap patterns based on URL
-        const hasModal = url.includes('modal') || url.includes('dialog') || url.includes('popup');
-        const hasForm = url.includes('form') || url.includes('checkout') || url.includes('register');
-        // 8% chance of focus trap issue for pages with modal-like patterns
-        if (hasModal && hashNum % 100 < 8) {
-            traps.push({
-                selector: '.modal, [role="dialog"]',
-                description: 'Modal dialog may trap focus without escape mechanism',
-                escapePath: 'Ensure Escape key closes modal and focus returns to trigger element',
-            });
-        }
-        // 5% chance of focus trap in complex forms
-        if (hasForm && hashNum % 100 < 5) {
-            traps.push({
-                selector: 'form .autocomplete, form .datepicker',
-                description: 'Form widget may trap keyboard focus',
-                escapePath: 'Add keyboard navigation (Tab/Escape) to exit widget',
-            });
-        }
-        return traps;
-    }
     async storeReport(report) {
         const reportId = uuidv4();
         await this.memory.set(`visual-accessibility:report:${reportId}`, report, { namespace: 'visual-accessibility', persist: true });
-        // Also store as latest for URL
-        await this.memory.set(`visual-accessibility:latest:${this.hashUrl(report.url)}`, report, { namespace: 'visual-accessibility', persist: true });
-    }
-    hashUrl(url) {
-        let hash = 0;
-        for (let i = 0; i < url.length; i++) {
-            const char = url.charCodeAt(i);
-            hash = (hash << 5) - hash + char;
-            hash = hash & hash;
-        }
-        return Math.abs(hash).toString(36);
+        await this.memory.set(`visual-accessibility:latest:${hashUrl(report.url)}`, report, { namespace: 'visual-accessibility', persist: true });
     }
     // ============================================================================
     // EU Compliance Methods
     // ============================================================================
-    /**
-     * Validate EU compliance (EN 301 549 and EU Accessibility Act)
-     *
-     * This method performs a WCAG audit first, then maps the results to
-     * European accessibility standards:
-     * - EN 301 549 V3.2.1 (harmonized European standard)
-     * - EU Accessibility Act (Directive 2019/882)
-     *
-     * @param url - URL to validate
-     * @param options - EU compliance options
-     * @returns Full EU compliance report with EN 301 549 and EAA results
-     *
-     * @example
-     * ```typescript
-     * const report = await service.validateEUCompliance('https://example.com', {
-     *   includeEAA: true,
-     *   productCategory: 'e-commerce',
-     *   en301549Version: '3.2.1',
-     * });
-     *
-     * if (report.success) {
-     *   console.log(`EU Compliance Score: ${report.value.complianceScore}%`);
-     *   console.log(`Status: ${report.value.overallStatus}`);
-     *   console.log(`Certification Ready: ${report.value.certificationReady}`);
-     * }
-     * ```
-     */
     async validateEUCompliance(url, options) {
         try {
-            // First, run a WCAG AA audit (EN 301 549 requires WCAG 2.1 AA)
             const wcagResult = await this.audit(url, {
                 wcagLevel: 'AA',
                 includeWarnings: true,
@@ -1697,36 +320,25 @@ export class AccessibilityTesterService {
             if (!wcagResult.success) {
                 return err(new Error(`WCAG audit failed: ${wcagResult.error.message}`));
             }
-            // Then validate EU compliance based on WCAG results
             const euResult = await this.euComplianceService.validateCompliance(wcagResult.value, options);
             return euResult;
         }
         catch (error) {
-            return err(error instanceof Error ? error : new Error(String(error)));
+            return err(toError(error));
         }
     }
-    /**
-     * Get EN 301 549 clauses for reference
-     */
     getEN301549Clauses() {
         return this.euComplianceService.getEN301549Clauses();
     }
-    /**
-     * Get EU Accessibility Act requirements for reference
-     */
     getEAARequirements() {
         return this.euComplianceService.getEAARequirements();
     }
-    /**
-     * Get WCAG to EN 301 549 mapping table
-     */
     getWCAGtoEN301549Mapping() {
         return this.euComplianceService.getWCAGMapping();
     }
-    /**
-     * Dispose service resources
-     * Cleans up any managed browser clients
-     */
+    // ============================================================================
+    // Lifecycle
+    // ============================================================================
     async dispose() {
         if (this.managedBrowserClient) {
             await this.managedBrowserClient.dispose();