@veraxhq/verax 0.1.0 → 0.2.1

package/src/verax/observe/state-sensor.js

@@ -0,0 +1,393 @@
+/**
+ * State Sensor v1
+ * Safe, opt-in state change detection for Redux and Zustand.
+ * 
+ * SAFETY:
+ * - Keys only, no values
+ * - Opt-in via store detection
+ * - Cleanup after interaction
+ * - Non-destructive
+ */
+
+const MAX_DIFF_KEYS = 10;
+
+/**
+ * Computes a shallow diff between two state objects.
+ * Returns array of changed keys (no values for privacy).
+ */
+function computeStateDiff(before, after) {
+  const changed = [];
+  const allKeys = new Set([
+    ...Object.keys(before || {}),
+    ...Object.keys(after || {})
+  ]);
+  
+  for (const key of allKeys) {
+    if (before[key] !== after[key]) {
+      changed.push(key);
+      if (changed.length >= MAX_DIFF_KEYS) break;
+    }
+  }
+  
+  return changed;
+}
+
+/**
+ * Redux store sensor.
+ * Subscribes to store changes and captures state snapshots.
+ */
+class ReduxSensor {
+  constructor() {
+    this.store = null;
+    this.unsubscribe = null;
+    this.beforeState = null;
+    this.afterState = null;
+    this.active = false;
+  }
+  
+  /**
+   * Attempts to detect and hook into Redux store.
+   * Returns true if store found and hooked.
+   */
+  async detect(page) {
+    try {
+      // First, wait for the store to be initialized
+      await page.evaluate(() => {
+        return new Promise((resolve) => {
+          if (window.__REDUX_STORE__) {
+            resolve();
+          } else {
+            // Wait up to 5 seconds for store initialization
+            const timeout = setTimeout(() => {
+              clearInterval(check);
+              resolve();
+            }, 5000);
+            const check = setInterval(() => {
+              if (window.__REDUX_STORE__) {
+                clearInterval(check);
+                clearTimeout(timeout);
+                resolve();
+              }
+            }, 100);
+          }
+        });
+      });
+      
+      const hasRedux = await page.evaluate(() => {
+        // Try to find Redux store via common patterns
+        if (window.__REDUX_STORE__) return true;
+        if (window.store && typeof window.store.getState === 'function') return true;
+        
+        // Check React context provider (common pattern)
+        const reduxProvider = document.querySelector('[data-redux-provider]');
+        if (reduxProvider) return true;
+        
+        // Check for Redux DevTools extension
+        if (window.__REDUX_DEVTOOLS_EXTENSION__) return true;
+        
+        // Try to find store in React component tree (best-effort)
+        // This is a heuristic but safe - we only read, never modify
+        try {
+          const reactRoot = document.querySelector('#root, [data-reactroot], [id^="root"]');
+          if (reactRoot && window.__REACT_DEVTOOLS_GLOBAL_HOOK__) {
+            return true; // Likely Redux if React DevTools present
+          }
+        } catch (e) {
+          // Ignore
+        }
+        
+        return false;
+      });
+      
+      if (!hasRedux) {
+        return false;
+      }
+      
+      // Install sensor in page context
+      await page.evaluate(() => {
+        if (window.__VERAX_STATE_SENSOR__) {
+          return;
+        }
+        
+        window.__VERAX_STATE_SENSOR__ = {
+          type: 'redux',
+          snapshots: [],
+          store: null,
+          unsubscribe: null,
+          captureSnapshot() {
+            let state = null;
+            if (window.__REDUX_STORE__) {
+              state = window.__REDUX_STORE__.getState();
+              this.store = window.__REDUX_STORE__;
+            } else if (window.store && typeof window.store.getState === 'function') {
+              state = window.store.getState();
+              this.store = window.store;
+            }
+            
+            if (state && typeof state === 'object') {
+              // Shallow copy of top-level keys only (privacy: no values)
+              const snapshot = {};
+              for (const key in state) {
+                if (Object.prototype.hasOwnProperty.call(state, key)) {
+                  snapshot[key] = '[REDACTED]'; // Never store values, only keys
+                }
+              }
+              this.snapshots.push({ timestamp: Date.now(), state: snapshot });
+            }
+          },
+          getSnapshots() {
+            return this.snapshots;
+          },
+          reset() {
+            this.snapshots = [];
+            if (this.unsubscribe) {
+              this.unsubscribe();
+              this.unsubscribe = null;
+            }
+          }
+        };
+      });
+      
+      this.active = true;
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+  
+  async captureBefore(page) {
+    if (!this.active) return;
+    
+    try {
+      await page.evaluate(() => {
+        window.__VERAX_STATE_SENSOR__?.captureSnapshot();
+      });
+      
+      this.beforeState = await page.evaluate(() => {
+        const snapshots = window.__VERAX_STATE_SENSOR__?.getSnapshots() || [];
+        return snapshots[snapshots.length - 1]?.state || null;
+      });
+    } catch (error) {
+      this.beforeState = null;
+    }
+  }
+  
+  async captureAfter(page) {
+    if (!this.active) return;
+    
+    try {
+      await page.evaluate(() => {
+        window.__VERAX_STATE_SENSOR__?.captureSnapshot();
+      });
+      
+      this.afterState = await page.evaluate(() => {
+        const snapshots = window.__VERAX_STATE_SENSOR__?.getSnapshots() || [];
+        return snapshots[snapshots.length - 1]?.state || null;
+      });
+    } catch (error) {
+      this.afterState = null;
+    }
+  }
+  
+  getDiff() {
+    if (!this.beforeState || !this.afterState) {
+      return { changed: [], available: false };
+    }
+    
+    const changed = computeStateDiff(this.beforeState, this.afterState);
+    return { changed, available: true };
+  }
+  
+  cleanup() {
+    this.beforeState = null;
+    this.afterState = null;
+    this.active = false;
+  }
+}
+
+/**
+ * Zustand store sensor.
+ * Wraps set() calls to capture state changes.
+ */
+class ZustandSensor {
+  constructor() {
+    this.beforeState = null;
+    this.afterState = null;
+    this.active = false;
+  }
+  
+  async detect(page) {
+    try {
+      const hasZustand = await page.evaluate(() => {
+        // Check for Zustand store markers
+        if (window.__ZUSTAND_STORE__) return true;
+        
+        // Look for common Zustand patterns in window object
+        for (const key in window) {
+          if (key.startsWith('use') && typeof window[key] === 'function') {
+            // Dynamic property access on window for Zustand store detection (runtime property)
+            const store = /** @type {any} */ (window[key]);
+            if (store && typeof store === 'object' && 'getState' in store && typeof store.getState === 'function') {
+              return true;
+            }
+          }
+        }
+        
+        return false;
+      });
+      
+      if (!hasZustand) return false;
+      
+      // Install sensor
+      await page.evaluate(() => {
+        if (window.__VERAX_STATE_SENSOR__) return;
+        
+        window.__VERAX_STATE_SENSOR__ = {
+          type: 'zustand',
+          snapshots: [],
+          captureSnapshot() {
+            // Try to find and capture Zustand store state
+            if (window.__ZUSTAND_STORE__) {
+              const state = window.__ZUSTAND_STORE__.getState();
+              if (state && typeof state === 'object') {
+                const snapshot = {};
+                for (const key in state) {
+                  if (typeof state[key] !== 'function') {
+                    snapshot[key] = '[REDACTED]'; // Never store values, only keys
+                  }
+                }
+                this.snapshots.push({ timestamp: Date.now(), state: snapshot });
+              }
+            }
+          },
+          getSnapshots() {
+            return this.snapshots;
+          },
+          reset() {
+            this.snapshots = [];
+          }
+        };
+      });
+      
+      this.active = true;
+      return true;
+    } catch (error) {
+      return false;
+    }
+  }
+  
+  async captureBefore(page) {
+    if (!this.active) return;
+    
+    try {
+      await page.evaluate(() => {
+        window.__VERAX_STATE_SENSOR__?.captureSnapshot();
+      });
+      
+      this.beforeState = await page.evaluate(() => {
+        const snapshots = window.__VERAX_STATE_SENSOR__?.getSnapshots() || [];
+        return snapshots[snapshots.length - 1]?.state || null;
+      });
+    } catch (error) {
+      this.beforeState = null;
+    }
+  }
+  
+  async captureAfter(page) {
+    if (!this.active) return;
+    
+    try {
+      await page.evaluate(() => {
+        window.__VERAX_STATE_SENSOR__?.captureSnapshot();
+      });
+      
+      this.afterState = await page.evaluate(() => {
+        const snapshots = window.__VERAX_STATE_SENSOR__?.getSnapshots() || [];
+        return snapshots[snapshots.length - 1]?.state || null;
+      });
+    } catch (error) {
+      this.afterState = null;
+    }
+  }
+  
+  getDiff() {
+    if (!this.beforeState || !this.afterState) {
+      return { changed: [], available: false };
+    }
+    
+    const changed = computeStateDiff(this.beforeState, this.afterState);
+    return { changed, available: true };
+  }
+  
+  cleanup() {
+    this.beforeState = null;
+    this.afterState = null;
+    this.active = false;
+  }
+}
+
+/**
+ * State Sensor orchestrator.
+ * Detects store type and delegates to appropriate sensor.
+ */
+export class StateSensor {
+  constructor() {
+    this.reduxSensor = new ReduxSensor();
+    this.zustandSensor = new ZustandSensor();
+    this.activeType = null;
+  }
+  
+  /**
+   * Detects state stores and activates appropriate sensor.
+   * Returns { detected: bool, type: 'redux' | 'zustand' | null }
+   */
+  async detect(page) {
+    // Try Redux first
+    const reduxDetected = await this.reduxSensor.detect(page);
+    if (reduxDetected) {
+      this.activeType = 'redux';
+      return { detected: true, type: 'redux' };
+    }
+    
+    // Try Zustand
+    const zustandDetected = await this.zustandSensor.detect(page);
+    if (zustandDetected) {
+      this.activeType = 'zustand';
+      return { detected: true, type: 'zustand' };
+    }
+    
+    return { detected: false, type: null };
+  }
+  
+  async captureBefore(page) {
+    if (this.activeType === 'redux') {
+      await this.reduxSensor.captureBefore(page);
+    } else if (this.activeType === 'zustand') {
+      await this.zustandSensor.captureBefore(page);
+    }
+  }
+  
+  async captureAfter(page) {
+    if (this.activeType === 'redux') {
+      await this.reduxSensor.captureAfter(page);
+    } else if (this.activeType === 'zustand') {
+      await this.zustandSensor.captureAfter(page);
+    }
+  }
+  
+  getDiff() {
+    if (this.activeType === 'redux') {
+      return this.reduxSensor.getDiff();
+    } else if (this.activeType === 'zustand') {
+      return this.zustandSensor.getDiff();
+    }
+    
+    return { changed: [], available: false };
+  }
+  
+  cleanup() {
+    this.reduxSensor.cleanup();
+    this.zustandSensor.cleanup();
+    this.activeType = null;
+  }
+}

package/src/verax/observe/state-ui-sensor.js

@@ -22,13 +22,14 @@ export class StateUISensor {
    */
   async snapshot(page, contextSelector = null) {
     try {
-      const snapshot = await page.evaluate(({ selector }) => {
+      const snapshot = await page.evaluate(() => {
         const signals = {};
         const rawSnapshot = {};
 
         // 1. Dialog/Modal signals
         signals.dialogs = [];
         const dialogs = document.querySelectorAll('[role="dialog"]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const dialog of dialogs) {
           const isVisible = dialog.offsetParent !== null || dialog.hasAttribute('open');
           const ariaModal = dialog.getAttribute('aria-modal');
@@ -46,6 +47,7 @@ export class StateUISensor {
         // 2. Expansion state (aria-expanded)
         signals.expandedElements = [];
         const expandables = document.querySelectorAll('[aria-expanded]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const el of expandables) {
           const expanded = el.getAttribute('aria-expanded') === 'true';
           signals.expandedElements.push({
@@ -58,6 +60,7 @@ export class StateUISensor {
         // 3. Tab selection (role=tab with aria-selected)
         signals.selectedTabs = [];
         const tabs = document.querySelectorAll('[role="tab"]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const tab of tabs) {
           const selected = tab.getAttribute('aria-selected') === 'true';
           signals.selectedTabs.push({
@@ -70,6 +73,7 @@ export class StateUISensor {
         // 4. Checkbox/toggle state (aria-checked)
         signals.checkedElements = [];
         const checkables = document.querySelectorAll('[aria-checked]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const el of checkables) {
           const checked = el.getAttribute('aria-checked') === 'true';
           signals.checkedElements.push({
@@ -82,6 +86,7 @@ export class StateUISensor {
         // 5. Alert/Status changes (role=alert, role=status)
         signals.alerts = [];
         const alerts = document.querySelectorAll('[role="alert"], [role="status"]');
+        // @ts-expect-error - NodeListOf is iterable in browser context
         for (const alert of alerts) {
           const text = alert.textContent?.trim() || '';
           signals.alerts.push({
@@ -96,6 +101,7 @@ export class StateUISensor {
         // Count visible nodes and text nodes (excluding style/comment nodes)
         const countMeaningfulNodes = () => {
           let count = 0;
+          // @ts-expect-error - NodeListOf is iterable in browser context
           for (const node of document.querySelectorAll('*')) {
             if (node.offsetParent !== null) { // Visible
               count++;

package/src/verax/observe/timing-sensor.js

@@ -0,0 +1,228 @@
+/**
+ * Timing Sensor
+ * Tracks timing of feedback signals (UI changes, ARIA, loading indicators)
+ * Detects delayed or missing feedback after interactions
+ */
+
+export class TimingSensor {
+  constructor(options = {}) {
+    this.feedbackGapThresholdMs = options.feedbackGapThresholdMs || 1500;
+    this.freezeLikeThresholdMs = options.freezeLikeThresholdMs || 3000;
+    
+    this.t0 = null; // Interaction start time
+    this.tNetworkFirst = null; // First network request time
+    this.tLoadingStart = null; // Loading indicator appears
+    this.tAriaFirst = null; // First ARIA change
+    this.tUiFirst = null; // First DOM/UI change
+    this.tFeedback = null; // First feedback signal (min of above)
+    
+    this.networkActivityDetected = false;
+    this.feedbackDetected = false;
+    this.feedbackDelayMs = 0;
+    this.workStartMs = 0;
+  }
+
+  /**
+   * Start timing from interaction initiation
+   */
+  startTiming() {
+    this.t0 = Date.now();
+    return this.t0;
+  }
+
+  /**
+   * Monitor for feedback signals during interaction
+   * Call periodically or at key moments to track timing
+   */
+  async captureTimingSnapshot(page) {
+    if (!this.t0) {
+      this.t0 = Date.now();
+    }
+
+    const now = Date.now();
+    const elapsedMs = now - this.t0;
+
+    // Capture current state
+    const state = await page.evaluate(() => {
+      const result = {
+        loadingPresent: false,
+        ariaStatusPresent: false,
+        ariaLivePresent: false,
+        buttonDisabled: false,
+        domChanged: false
+      };
+
+      // Check for loading indicators
+      const loading = document.querySelectorAll('[aria-busy="true"], [class*="load"], [class*="spin"], .loader, .spinner');
+      result.loadingPresent = loading.length > 0;
+
+      // Check for ARIA status/alert
+      const ariaStatus = document.querySelectorAll('[role="status"], [role="alert"]');
+      ariaStatus.forEach(el => {
+        if (el.textContent?.length > 0) {
+          result.ariaStatusPresent = true;
+        }
+      });
+
+      // Check for ARIA live regions
+      const ariaLive = document.querySelectorAll('[aria-live]');
+      ariaLive.forEach(el => {
+        if (el.textContent?.length > 0) {
+          result.ariaLivePresent = true;
+        }
+      });
+
+      // Check for disabled submit buttons (common feedback)
+      const disabledButtons = document.querySelectorAll('button[type="submit"]:disabled, button:disabled');
+      result.buttonDisabled = disabledButtons.length > 0;
+
+      return result;
+    });
+
+    // First loading indicator
+    if (state.loadingPresent && !this.tLoadingStart) {
+      this.tLoadingStart = now;
+    }
+
+    // First ARIA change
+    if ((state.ariaStatusPresent || state.ariaLivePresent) && !this.tAriaFirst) {
+      this.tAriaFirst = now;
+    }
+
+    // Record button disabled state as feedback signal
+    if (state.buttonDisabled) {
+      if (!this.tFeedback) {
+        this.tFeedback = now;
+      }
+      // Also record as button disabled time
+      this.recordButtonDisabled(now);
+    }
+
+    // Determine first feedback signal
+    if (!this.tFeedback) {
+      const signals = [this.tLoadingStart, this.tAriaFirst, this.tUiFirst].filter(t => t !== null);
+      if (signals.length > 0) {
+        this.tFeedback = Math.min(...signals);
+      }
+    }
+
+    return {
+      elapsedMs,
+      state,
+      hasLoadingIndicator: state.loadingPresent,
+      hasAriaFeedback: state.ariaStatusPresent || state.ariaLivePresent,
+      hasButtonDisabled: state.buttonDisabled
+    };
+  }
+
+  /**
+   * Analyze network summary to detect if work started
+   * Records the time when first network request was detected
+   */
+  analyzeNetworkSummary(networkSummary) {
+    if (!networkSummary || networkSummary.totalRequests === 0) {
+      return;
+    }
+    
+    if (!this.tNetworkFirst) {
+      // Network requests started - estimate based on interaction start + small delay
+      // Network sensor tracks when requests were made, but we estimate based on t0
+      // Most network requests start within 50-200ms after interaction
+      const estimatedNetworkStart = this.t0 + 100; // Conservative estimate
+      this.tNetworkFirst = estimatedNetworkStart;
+      this.networkActivityDetected = true;
+    }
+  }
+
+  /**
+   * Record when loading sensor detected activity
+   * Called when loading indicators appear
+   */
+  recordLoadingStart(timestamp = null) {
+    if (!this.tLoadingStart) {
+      this.tLoadingStart = timestamp || Date.now();
+      // Loading indicates work started even if network not detected yet
+      if (!this.networkActivityDetected) {
+        this.networkActivityDetected = true;
+      }
+    }
+  }
+
+  /**
+   * Record when UI changed (from sensor)
+   */
+  recordUiChange(timestamp = null) {
+    if (!this.tUiFirst) {
+      this.tUiFirst = timestamp || Date.now();
+    }
+  }
+
+  /**
+   * Record when button disabled state detected (feedback signal)
+   */
+  recordButtonDisabled(timestamp = null) {
+    if (!this.tFeedback) {
+      const now = timestamp || Date.now();
+      // Check if this is earlier than other feedback signals
+      const signals = [this.tLoadingStart, this.tAriaFirst, this.tUiFirst].filter(t => t !== null);
+      if (signals.length === 0 || now < Math.min(...signals)) {
+        this.tFeedback = now;
+      }
+    }
+  }
+
+  /**
+   * Get final timing analysis
+   */
+  getTimingAnalysis() {
+    if (!this.t0) {
+      return null;
+    }
+
+    const now = Date.now();
+
+    // Determine when work started (network or loading indicator)
+    const workStartTime = this.tNetworkFirst || this.tLoadingStart;
+    this.workStartMs = workStartTime ? workStartTime - this.t0 : -1;
+
+    // Determine when feedback appeared (first of: loading, ARIA, UI change, button disabled)
+    const feedbackTimes = [this.tLoadingStart, this.tAriaFirst, this.tUiFirst].filter(t => t !== null);
+    if (this.tFeedback && !feedbackTimes.includes(this.tFeedback)) {
+      feedbackTimes.push(this.tFeedback);
+    }
+    this.tFeedback = feedbackTimes.length > 0 ? Math.min(...feedbackTimes) : null;
+    this.feedbackDelayMs = this.tFeedback ? this.tFeedback - this.t0 : -1;
+
+    // Check if feedback gap exists: work started but no feedback within threshold
+    const hasFeedbackGap = 
+      this.networkActivityDetected && 
+      (!this.tFeedback || this.feedbackDelayMs > this.feedbackGapThresholdMs);
+
+    // Check if freeze-like: significant delay (>3000ms) before feedback
+    const isFreezeLike = 
+      this.networkActivityDetected && 
+      this.tFeedback !== null &&
+      this.feedbackDelayMs > this.freezeLikeThresholdMs;
+
+    return {
+      t0: this.t0,
+      tNetworkFirst: this.tNetworkFirst,
+      tLoadingStart: this.tLoadingStart,
+      tAriaFirst: this.tAriaFirst,
+      tUiFirst: this.tUiFirst,
+      tFeedback: this.tFeedback,
+      
+      elapsedMs: now - this.t0,
+      workStartMs: this.workStartMs,
+      feedbackDelayMs: this.feedbackDelayMs,
+      
+      networkActivityDetected: this.networkActivityDetected,
+      feedbackDetected: this.tFeedback !== null,
+      hasFeedbackGap,
+      isFreezeLike,
+      
+      feedbackGapThreshold: this.feedbackGapThresholdMs,
+      freezeLikeThreshold: this.freezeLikeThresholdMs
+    };
+  }
+}