@vibecheckai/cli 3.2.5 → 3.3.0

package/bin/runners/lib/reality/safety-rails.js

@@ -1,463 +1,463 @@
-/**
- * Safety Rails v2
- * 
- * False-positive prevention for UI change detection.
- * Handles hydration suppression, action stabilization, duplicate filtering.
- */
-
-"use strict";
-
-// =============================================================================
-// CONFIGURATION
-// =============================================================================
-
-const DEFAULT_CONFIG = {
-  // Hydration suppression
-  hydration: {
-    suppressionWindowMs: 2000,    // Ignore changes in first 2s after navigation
-    ignoreInitialRender: true,
-  },
-  
-  // Action stabilization
-  stabilization: {
-    quietMs: 300,                 // Wait for no DOM mutations
-    settleMs: 250,                // Wait after action before snapshot
-    actionWindowMs: 8000,         // Max wait for action effects
-    networkIdleMs: 500,           // Wait for network idle
-  },
-  
-  // Duplicate filtering
-  duplicates: {
-    debounceMs: 100,              // Ignore repeated clicks within 100ms
-    sameElementDebounceMs: 500,   // Same element clicks
-  },
-  
-  // Toast filtering
-  toast: {
-    maxLifetimeMs: 15000,         // Ignore persistent banners
-    minVisibleMs: 100,            // Ignore flash toasts
-  },
-  
-  // Ignore selectors (user configurable)
-  ignoreSelectors: [
-    "[data-hydration]",
-    "[data-nextjs-scroll-focus-boundary]",
-    "nextjs-portal",
-    "#__next-build-watcher",
-    "#__next-prerender-indicator",
-    ".dev-overlay",
-    "[data-hot-reload]",
-  ],
-  
-  // Text noise patterns (timestamps, counters)
-  textNoisePatterns: [
-    /^\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?$/i,     // 12:34, 12:34:56, 12:34 PM
-    /^\d+(\.\d+)?\s*(s|ms|sec|seconds?)$/i,      // 3s, 100ms
-    /^(just now|now|ago|\d+\s*(min|hour|day)s?\s*ago)$/i,
-    /^\d+$/,                                      // Pure numbers
-  ],
-};
-
-// =============================================================================
-// HYDRATION SUPPRESSION
-// =============================================================================
-
-/**
- * Create hydration tracker for a page
- */
-function createHydrationTracker(options = {}) {
-  const config = { ...DEFAULT_CONFIG.hydration, ...options };
-  
-  return {
-    navigationTime: null,
-    isHydrating: false,
-    
-    /**
-     * Mark navigation start
-     */
-    startNavigation() {
-      this.navigationTime = Date.now();
-      this.isHydrating = true;
-    },
-    
-    /**
-     * Check if still in hydration window
-     */
-    inHydrationWindow() {
-      if (!this.navigationTime || !config.ignoreInitialRender) {
-        return false;
-      }
-      const elapsed = Date.now() - this.navigationTime;
-      return elapsed < config.suppressionWindowMs;
-    },
-    
-    /**
-     * Mark hydration complete (e.g., after first meaningful paint)
-     */
-    markHydrationComplete() {
-      this.isHydrating = false;
-    },
-    
-    /**
-     * Should suppress this change?
-     */
-    shouldSuppress(change) {
-      if (!this.inHydrationWindow()) return false;
-      
-      // During hydration, suppress semantic-only changes
-      // Still allow route changes and toasts
-      if (change.routeChanged) return false;
-      if (change.reasons?.includes("toast_success") || change.reasons?.includes("toast_error")) {
-        return false;
-      }
-      
-      return true;
-    },
-  };
-}
-
-// =============================================================================
-// ACTION STABILIZATION
-// =============================================================================
-
-/**
- * Create action stabilizer for DOM mutations
- */
-function createActionStabilizer(page, options = {}) {
-  const config = { ...DEFAULT_CONFIG.stabilization, ...options };
-  
-  return {
-    mutationCount: 0,
-    lastMutationTime: 0,
-    pendingRequests: new Set(),
-    
-    /**
-     * Wait for DOM to be quiet before action
-     */
-    async waitForQuiet() {
-      const startTime = Date.now();
-      
-      while (Date.now() - startTime < config.quietMs * 3) {
-        // Check if DOM has been quiet
-        const timeSinceLastMutation = Date.now() - this.lastMutationTime;
-        const hasPendingRequests = this.pendingRequests.size > 0;
-        
-        if (timeSinceLastMutation >= config.quietMs && !hasPendingRequests) {
-          return { stable: true, waitedMs: Date.now() - startTime };
-        }
-        
-        await sleep(50);
-      }
-      
-      return { stable: false, waitedMs: Date.now() - startTime };
-    },
-    
-    /**
-     * Wait for effects after action
-     */
-    async waitForSettle() {
-      await sleep(config.settleMs);
-      
-      // Additional wait if network is active
-      if (this.pendingRequests.size > 0) {
-        const networkStart = Date.now();
-        while (this.pendingRequests.size > 0 && Date.now() - networkStart < config.networkIdleMs) {
-          await sleep(50);
-        }
-      }
-    },
-    
-    /**
-     * Record mutation
-     */
-    recordMutation() {
-      this.mutationCount++;
-      this.lastMutationTime = Date.now();
-    },
-    
-    /**
-     * Track request start
-     */
-    trackRequestStart(requestId) {
-      this.pendingRequests.add(requestId);
-    },
-    
-    /**
-     * Track request end
-     */
-    trackRequestEnd(requestId) {
-      this.pendingRequests.delete(requestId);
-    },
-    
-    /**
-     * Reset for new action
-     */
-    reset() {
-      this.mutationCount = 0;
-      this.lastMutationTime = Date.now();
-    },
-  };
-}
-
-// =============================================================================
-// DUPLICATE ACTION FILTERING
-// =============================================================================
-
-/**
- * Create duplicate action filter
- */
-function createDuplicateFilter(options = {}) {
-  const config = { ...DEFAULT_CONFIG.duplicates, ...options };
-  const recentActions = [];
-  
-  return {
-    /**
-     * Check if action is duplicate
-     */
-    isDuplicate(action) {
-      const now = Date.now();
-      
-      // Clean old entries
-      while (recentActions.length > 0 && now - recentActions[0].time > config.sameElementDebounceMs) {
-        recentActions.shift();
-      }
-      
-      // Check for duplicate
-      const isDupe = recentActions.some(recent => {
-        const timeDiff = now - recent.time;
-        
-        // Same element within debounce window
-        if (recent.selector === action.selector && timeDiff < config.sameElementDebounceMs) {
-          return true;
-        }
-        
-        // Any click within short debounce
-        if (timeDiff < config.debounceMs) {
-          return true;
-        }
-        
-        return false;
-      });
-      
-      // Record this action
-      recentActions.push({
-        selector: action.selector,
-        type: action.type,
-        time: now,
-      });
-      
-      return isDupe;
-    },
-    
-    /**
-     * Clear history
-     */
-    clear() {
-      recentActions.length = 0;
-    },
-  };
-}
-
-// =============================================================================
-// TOAST FALSE-POSITIVE FILTERING
-// =============================================================================
-
-/**
- * Filter toast false positives
- */
-function filterToastFalsePositives(toasts, options = {}) {
-  const config = { ...DEFAULT_CONFIG.toast, ...options };
-  
-  return toasts.filter(toast => {
-    // Ignore if visible too long (persistent banner)
-    if (toast.visibleDuration && toast.visibleDuration > config.maxLifetimeMs) {
-      return false;
-    }
-    
-    // Ignore if flash (too short to be intentional)
-    if (toast.visibleDuration && toast.visibleDuration < config.minVisibleMs) {
-      return false;
-    }
-    
-    // Ignore common false positive patterns
-    const text = (toast.message || "").toLowerCase();
-    const falsePositivePatterns = [
-      /cookie.*consent/i,
-      /accept.*cookies/i,
-      /privacy.*policy/i,
-      /subscribe.*newsletter/i,
-      /sign.*up.*newsletter/i,
-      /promotional/i,
-    ];
-    
-    if (falsePositivePatterns.some(p => p.test(text))) {
-      return false;
-    }
-    
-    return true;
-  });
-}
-
-// =============================================================================
-// TEXT NOISE FILTERING
-// =============================================================================
-
-/**
- * Check if text is noise (timestamp, counter, etc.)
- */
-function isTextNoise(text, options = {}) {
-  const patterns = options.textNoisePatterns || DEFAULT_CONFIG.textNoisePatterns;
-  
-  const trimmed = (text || "").trim();
-  if (!trimmed) return true;
-  
-  return patterns.some(pattern => pattern.test(trimmed));
-}
-
-/**
- * Filter noise from semantic diff
- */
-function filterSemanticDiffNoise(diff, options = {}) {
-  const filtered = {
-    added: diff.added?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
-    removed: diff.removed?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
-    changed: diff.changed?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
-  };
-  
-  // Preserve original flags
-  filtered.routeChanged = diff.routeChanged;
-  filtered.dialogOpened = diff.dialogOpened;
-  filtered.dialogClosed = diff.dialogClosed;
-  filtered.errorsChanged = diff.errorsChanged;
-  filtered.errorDelta = diff.errorDelta;
-  
-  return filtered;
-}
-
-function extractTextFromDiffItem(item) {
-  // "button: Save" -> "Save"
-  const match = item.match(/:\s*(.+)$/);
-  return match ? match[1] : item;
-}
-
-// =============================================================================
-// SELECTOR IGNORE LIST
-// =============================================================================
-
-/**
- * Check if element should be ignored
- */
-function shouldIgnoreElement(selector, options = {}) {
-  const ignoreSelectors = options.ignoreSelectors || DEFAULT_CONFIG.ignoreSelectors;
-  
-  if (!selector) return false;
-  
-  return ignoreSelectors.some(pattern => {
-    if (pattern.startsWith("[") || pattern.startsWith("#") || pattern.startsWith(".")) {
-      return selector.includes(pattern);
-    }
-    return selector === pattern;
-  });
-}
-
-/**
- * Build ignore selector for Playwright
- */
-function buildIgnoreSelector(options = {}) {
-  const ignoreSelectors = options.ignoreSelectors || DEFAULT_CONFIG.ignoreSelectors;
-  return ignoreSelectors.map(s => `:not(${s})`).join("");
-}
-
-// =============================================================================
-// MEANINGFUL CHANGE VALIDATION
-// =============================================================================
-
-/**
- * Validate that a UI change is truly meaningful (with safety rails applied)
- */
-function validateMeaningfulChange(uiChange, options = {}) {
-  const {
-    hydrationTracker = null,
-    meaningfulScoreThreshold = 0.6,
-  } = options;
-  
-  // Check hydration suppression
-  if (hydrationTracker?.shouldSuppress(uiChange)) {
-    return {
-      valid: false,
-      suppressed: true,
-      reason: "hydration_window",
-      original: uiChange,
-    };
-  }
-  
-  // Filter noise from diff
-  if (uiChange.semanticDiffSummary) {
-    uiChange.semanticDiffSummary = filterSemanticDiffNoise(uiChange.semanticDiffSummary, options);
-  }
-  
-  // Recalculate score after filtering
-  const filteredDiffSize = (uiChange.semanticDiffSummary?.added?.length || 0) +
-                           (uiChange.semanticDiffSummary?.removed?.length || 0) +
-                           (uiChange.semanticDiffSummary?.changed?.length || 0);
-  
-  // If only minor changes remain after filtering, downgrade
-  if (!uiChange.routeChanged && 
-      !uiChange.dialogOpened && 
-      !uiChange.dialogClosed &&
-      !uiChange.reasons?.some(r => r.startsWith("toast_")) &&
-      filteredDiffSize === 0) {
-    return {
-      valid: false,
-      suppressed: true,
-      reason: "noise_only",
-      original: uiChange,
-    };
-  }
-  
-  return {
-    valid: uiChange.meaningful || uiChange.score >= meaningfulScoreThreshold,
-    suppressed: false,
-    uiChange,
-  };
-}
-
-// =============================================================================
-// HELPERS
-// =============================================================================
-
-function sleep(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-// =============================================================================
-// EXPORTS
-// =============================================================================
-
-module.exports = {
-  // Configuration
-  DEFAULT_CONFIG,
-  
-  // Hydration
-  createHydrationTracker,
-  
-  // Stabilization
-  createActionStabilizer,
-  
-  // Duplicates
-  createDuplicateFilter,
-  
-  // Toast filtering
-  filterToastFalsePositives,
-  
-  // Text noise
-  isTextNoise,
-  filterSemanticDiffNoise,
-  
-  // Selector ignore
-  shouldIgnoreElement,
-  buildIgnoreSelector,
-  
-  // Validation
-  validateMeaningfulChange,
-};
+/**
+ * Safety Rails v2
+ * 
+ * False-positive prevention for UI change detection.
+ * Handles hydration suppression, action stabilization, duplicate filtering.
+ */
+
+"use strict";
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+const DEFAULT_CONFIG = {
+  // Hydration suppression
+  hydration: {
+    suppressionWindowMs: 2000,    // Ignore changes in first 2s after navigation
+    ignoreInitialRender: true,
+  },
+  
+  // Action stabilization
+  stabilization: {
+    quietMs: 300,                 // Wait for no DOM mutations
+    settleMs: 250,                // Wait after action before snapshot
+    actionWindowMs: 8000,         // Max wait for action effects
+    networkIdleMs: 500,           // Wait for network idle
+  },
+  
+  // Duplicate filtering
+  duplicates: {
+    debounceMs: 100,              // Ignore repeated clicks within 100ms
+    sameElementDebounceMs: 500,   // Same element clicks
+  },
+  
+  // Toast filtering
+  toast: {
+    maxLifetimeMs: 15000,         // Ignore persistent banners
+    minVisibleMs: 100,            // Ignore flash toasts
+  },
+  
+  // Ignore selectors (user configurable)
+  ignoreSelectors: [
+    "[data-hydration]",
+    "[data-nextjs-scroll-focus-boundary]",
+    "nextjs-portal",
+    "#__next-build-watcher",
+    "#__next-prerender-indicator",
+    ".dev-overlay",
+    "[data-hot-reload]",
+  ],
+  
+  // Text noise patterns (timestamps, counters)
+  textNoisePatterns: [
+    /^\d{1,2}:\d{2}(:\d{2})?\s*(AM|PM)?$/i,     // 12:34, 12:34:56, 12:34 PM
+    /^\d+(\.\d+)?\s*(s|ms|sec|seconds?)$/i,      // 3s, 100ms
+    /^(just now|now|ago|\d+\s*(min|hour|day)s?\s*ago)$/i,
+    /^\d+$/,                                      // Pure numbers
+  ],
+};
+
+// =============================================================================
+// HYDRATION SUPPRESSION
+// =============================================================================
+
+/**
+ * Create hydration tracker for a page
+ */
+function createHydrationTracker(options = {}) {
+  const config = { ...DEFAULT_CONFIG.hydration, ...options };
+  
+  return {
+    navigationTime: null,
+    isHydrating: false,
+    
+    /**
+     * Mark navigation start
+     */
+    startNavigation() {
+      this.navigationTime = Date.now();
+      this.isHydrating = true;
+    },
+    
+    /**
+     * Check if still in hydration window
+     */
+    inHydrationWindow() {
+      if (!this.navigationTime || !config.ignoreInitialRender) {
+        return false;
+      }
+      const elapsed = Date.now() - this.navigationTime;
+      return elapsed < config.suppressionWindowMs;
+    },
+    
+    /**
+     * Mark hydration complete (e.g., after first meaningful paint)
+     */
+    markHydrationComplete() {
+      this.isHydrating = false;
+    },
+    
+    /**
+     * Should suppress this change?
+     */
+    shouldSuppress(change) {
+      if (!this.inHydrationWindow()) return false;
+      
+      // During hydration, suppress semantic-only changes
+      // Still allow route changes and toasts
+      if (change.routeChanged) return false;
+      if (change.reasons?.includes("toast_success") || change.reasons?.includes("toast_error")) {
+        return false;
+      }
+      
+      return true;
+    },
+  };
+}
+
+// =============================================================================
+// ACTION STABILIZATION
+// =============================================================================
+
+/**
+ * Create action stabilizer for DOM mutations
+ */
+function createActionStabilizer(page, options = {}) {
+  const config = { ...DEFAULT_CONFIG.stabilization, ...options };
+  
+  return {
+    mutationCount: 0,
+    lastMutationTime: 0,
+    pendingRequests: new Set(),
+    
+    /**
+     * Wait for DOM to be quiet before action
+     */
+    async waitForQuiet() {
+      const startTime = Date.now();
+      
+      while (Date.now() - startTime < config.quietMs * 3) {
+        // Check if DOM has been quiet
+        const timeSinceLastMutation = Date.now() - this.lastMutationTime;
+        const hasPendingRequests = this.pendingRequests.size > 0;
+        
+        if (timeSinceLastMutation >= config.quietMs && !hasPendingRequests) {
+          return { stable: true, waitedMs: Date.now() - startTime };
+        }
+        
+        await sleep(50);
+      }
+      
+      return { stable: false, waitedMs: Date.now() - startTime };
+    },
+    
+    /**
+     * Wait for effects after action
+     */
+    async waitForSettle() {
+      await sleep(config.settleMs);
+      
+      // Additional wait if network is active
+      if (this.pendingRequests.size > 0) {
+        const networkStart = Date.now();
+        while (this.pendingRequests.size > 0 && Date.now() - networkStart < config.networkIdleMs) {
+          await sleep(50);
+        }
+      }
+    },
+    
+    /**
+     * Record mutation
+     */
+    recordMutation() {
+      this.mutationCount++;
+      this.lastMutationTime = Date.now();
+    },
+    
+    /**
+     * Track request start
+     */
+    trackRequestStart(requestId) {
+      this.pendingRequests.add(requestId);
+    },
+    
+    /**
+     * Track request end
+     */
+    trackRequestEnd(requestId) {
+      this.pendingRequests.delete(requestId);
+    },
+    
+    /**
+     * Reset for new action
+     */
+    reset() {
+      this.mutationCount = 0;
+      this.lastMutationTime = Date.now();
+    },
+  };
+}
+
+// =============================================================================
+// DUPLICATE ACTION FILTERING
+// =============================================================================
+
+/**
+ * Create duplicate action filter
+ */
+function createDuplicateFilter(options = {}) {
+  const config = { ...DEFAULT_CONFIG.duplicates, ...options };
+  const recentActions = [];
+  
+  return {
+    /**
+     * Check if action is duplicate
+     */
+    isDuplicate(action) {
+      const now = Date.now();
+      
+      // Clean old entries
+      while (recentActions.length > 0 && now - recentActions[0].time > config.sameElementDebounceMs) {
+        recentActions.shift();
+      }
+      
+      // Check for duplicate
+      const isDupe = recentActions.some(recent => {
+        const timeDiff = now - recent.time;
+        
+        // Same element within debounce window
+        if (recent.selector === action.selector && timeDiff < config.sameElementDebounceMs) {
+          return true;
+        }
+        
+        // Any click within short debounce
+        if (timeDiff < config.debounceMs) {
+          return true;
+        }
+        
+        return false;
+      });
+      
+      // Record this action
+      recentActions.push({
+        selector: action.selector,
+        type: action.type,
+        time: now,
+      });
+      
+      return isDupe;
+    },
+    
+    /**
+     * Clear history
+     */
+    clear() {
+      recentActions.length = 0;
+    },
+  };
+}
+
+// =============================================================================
+// TOAST FALSE-POSITIVE FILTERING
+// =============================================================================
+
+/**
+ * Filter toast false positives
+ */
+function filterToastFalsePositives(toasts, options = {}) {
+  const config = { ...DEFAULT_CONFIG.toast, ...options };
+  
+  return toasts.filter(toast => {
+    // Ignore if visible too long (persistent banner)
+    if (toast.visibleDuration && toast.visibleDuration > config.maxLifetimeMs) {
+      return false;
+    }
+    
+    // Ignore if flash (too short to be intentional)
+    if (toast.visibleDuration && toast.visibleDuration < config.minVisibleMs) {
+      return false;
+    }
+    
+    // Ignore common false positive patterns
+    const text = (toast.message || "").toLowerCase();
+    const falsePositivePatterns = [
+      /cookie.*consent/i,
+      /accept.*cookies/i,
+      /privacy.*policy/i,
+      /subscribe.*newsletter/i,
+      /sign.*up.*newsletter/i,
+      /promotional/i,
+    ];
+    
+    if (falsePositivePatterns.some(p => p.test(text))) {
+      return false;
+    }
+    
+    return true;
+  });
+}
+
+// =============================================================================
+// TEXT NOISE FILTERING
+// =============================================================================
+
+/**
+ * Check if text is noise (timestamp, counter, etc.)
+ */
+function isTextNoise(text, options = {}) {
+  const patterns = options.textNoisePatterns || DEFAULT_CONFIG.textNoisePatterns;
+  
+  const trimmed = (text || "").trim();
+  if (!trimmed) return true;
+  
+  return patterns.some(pattern => pattern.test(trimmed));
+}
+
+/**
+ * Filter noise from semantic diff
+ */
+function filterSemanticDiffNoise(diff, options = {}) {
+  const filtered = {
+    added: diff.added?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
+    removed: diff.removed?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
+    changed: diff.changed?.filter(item => !isTextNoise(extractTextFromDiffItem(item), options)) || [],
+  };
+  
+  // Preserve original flags
+  filtered.routeChanged = diff.routeChanged;
+  filtered.dialogOpened = diff.dialogOpened;
+  filtered.dialogClosed = diff.dialogClosed;
+  filtered.errorsChanged = diff.errorsChanged;
+  filtered.errorDelta = diff.errorDelta;
+  
+  return filtered;
+}
+
+function extractTextFromDiffItem(item) {
+  // "button: Save" -> "Save"
+  const match = item.match(/:\s*(.+)$/);
+  return match ? match[1] : item;
+}
+
+// =============================================================================
+// SELECTOR IGNORE LIST
+// =============================================================================
+
+/**
+ * Check if element should be ignored
+ */
+function shouldIgnoreElement(selector, options = {}) {
+  const ignoreSelectors = options.ignoreSelectors || DEFAULT_CONFIG.ignoreSelectors;
+  
+  if (!selector) return false;
+  
+  return ignoreSelectors.some(pattern => {
+    if (pattern.startsWith("[") || pattern.startsWith("#") || pattern.startsWith(".")) {
+      return selector.includes(pattern);
+    }
+    return selector === pattern;
+  });
+}
+
+/**
+ * Build ignore selector for Playwright
+ */
+function buildIgnoreSelector(options = {}) {
+  const ignoreSelectors = options.ignoreSelectors || DEFAULT_CONFIG.ignoreSelectors;
+  return ignoreSelectors.map(s => `:not(${s})`).join("");
+}
+
+// =============================================================================
+// MEANINGFUL CHANGE VALIDATION
+// =============================================================================
+
+/**
+ * Validate that a UI change is truly meaningful (with safety rails applied)
+ */
+function validateMeaningfulChange(uiChange, options = {}) {
+  const {
+    hydrationTracker = null,
+    meaningfulScoreThreshold = 0.6,
+  } = options;
+  
+  // Check hydration suppression
+  if (hydrationTracker?.shouldSuppress(uiChange)) {
+    return {
+      valid: false,
+      suppressed: true,
+      reason: "hydration_window",
+      original: uiChange,
+    };
+  }
+  
+  // Filter noise from diff
+  if (uiChange.semanticDiffSummary) {
+    uiChange.semanticDiffSummary = filterSemanticDiffNoise(uiChange.semanticDiffSummary, options);
+  }
+  
+  // Recalculate score after filtering
+  const filteredDiffSize = (uiChange.semanticDiffSummary?.added?.length || 0) +
+                           (uiChange.semanticDiffSummary?.removed?.length || 0) +
+                           (uiChange.semanticDiffSummary?.changed?.length || 0);
+  
+  // If only minor changes remain after filtering, downgrade
+  if (!uiChange.routeChanged && 
+      !uiChange.dialogOpened && 
+      !uiChange.dialogClosed &&
+      !uiChange.reasons?.some(r => r.startsWith("toast_")) &&
+      filteredDiffSize === 0) {
+    return {
+      valid: false,
+      suppressed: true,
+      reason: "noise_only",
+      original: uiChange,
+    };
+  }
+  
+  return {
+    valid: uiChange.meaningful || uiChange.score >= meaningfulScoreThreshold,
+    suppressed: false,
+    uiChange,
+  };
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+module.exports = {
+  // Configuration
+  DEFAULT_CONFIG,
+  
+  // Hydration
+  createHydrationTracker,
+  
+  // Stabilization
+  createActionStabilizer,
+  
+  // Duplicates
+  createDuplicateFilter,
+  
+  // Toast filtering
+  filterToastFalsePositives,
+  
+  // Text noise
+  isTextNoise,
+  filterSemanticDiffNoise,
+  
+  // Selector ignore
+  shouldIgnoreElement,
+  buildIgnoreSelector,
+  
+  // Validation
+  validateMeaningfulChange,
+};