@cognior/iap-sdk 0.1.0

package/src/core/triggerManager.ts

@@ -0,0 +1,1011 @@
+// src/core/triggerManager.ts
+// Enhanced trigger system for step-level triggers with fallback support
+
+import type { 
+  TriggerDefinition, 
+  TriggerCondition, 
+  TriggerEvaluationContext, 
+  TriggerEvaluationResult,
+  TriggerConditionKind,
+  TriggerType,
+  LogicalOperator,
+  RuleOperator
+} from '../experiences/types';
+import { resolveSelector, waitForElement } from '../utils/selectors';
+import { pageContextService, type PageChangeEvent } from '../services/pageContextService';
+
+/**
+ * Resolve selector to multiple elements (handles both CSS and XPath)
+ */
+function resolveSelectorAll(selector: string, root: Document | Element = document): Element[] {
+  if (!selector || typeof selector !== 'string') return [];
+
+  // Try CSS
+  try {
+    const cssElements = (root as Document | Element).querySelectorAll(selector);
+    if (cssElements.length > 0) return Array.from(cssElements);
+  } catch {
+    // ignore invalid CSS: we'll try XPath next
+  }
+
+  // Try XPath
+  try {
+    const doc = root instanceof Document ? root : root.ownerDocument ?? document;
+    const result = doc.evaluate(
+      selector,
+      root as Node,
+      null,
+      XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
+      null
+    );
+    
+    const elements: Element[] = [];
+    for (let i = 0; i < result.snapshotLength; i++) {
+      const element = result.snapshotItem(i) as Element;
+      if (element) elements.push(element);
+    }
+    return elements;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Enhanced step interface with trigger support
+ */
+export interface EnhancedStepData {
+  stepId: string;
+  stepOrder: number;
+  stepType: string; // "Mandatory" | "Optional"
+  trigger?: TriggerDefinition;
+  uxExperience?: {
+    uxExperienceType: string;
+    elementSelector?: string;
+    elementTrigger?: string;
+    elementLocation?: string;
+    position?: { x: string; y: string };
+    content: any;
+    modalContent?: any;
+  };
+  conditionRuleBlocks?: any[];
+  userInputSelector?: string | null;
+}
+
+/**
+ * Trigger Manager handles step-level trigger resolution and evaluation
+ * with page-aware context management for SPA and multi-page applications
+ */
+export class TriggerManager {
+  private static _instance: TriggerManager;
+  private _activeListeners: Map<string, (() => void)[]> = new Map();
+  private _triggeredOnceSet: Set<string> = new Set();
+  private _pageContextUnsubscribe: (() => void) | null = null;
+  private _initialized = false;
+  private _registeredTriggers: Record<string, {
+    trigger: TriggerDefinition;
+    onTrigger: (context: TriggerEvaluationContext) => void;
+    flowContext?: { mode: 'Linear' | 'AnyOrder', currentStepActive: boolean };
+  }> = {};
+  private _waitTimeouts: Map<string, number> = new Map();
+  private _selectorWaitTimeout: number = 30000; // 30 seconds default
+
+  private constructor() {}
+
+  public static getInstance(): TriggerManager {
+    if (!this._instance) {
+      this._instance = new TriggerManager();
+    }
+    return this._instance;
+  }
+
+  /**
+   * Initialize trigger manager with page context tracking
+   */
+  public initialize(): void {
+    if (this._initialized) return;
+    
+    // Initialize page context service
+    pageContextService.initialize();
+    
+    // Subscribe to page changes
+    this._pageContextUnsubscribe = pageContextService.subscribe(this.handlePageChange.bind(this));
+    
+    this._initialized = true;
+  }
+
+  /**
+   * Handle page change events - re-evaluate all registered triggers
+   */
+  private handlePageChange(event: PageChangeEvent): void {
+    console.debug(`[DAP] 📄 Page changed from ${event.previous?.pathname} to ${event.current.pathname}`);
+    console.debug('[DAP] Re-evaluating all registered triggers for new page context');
+
+    // Clear existing timeouts as page context changed
+    this.clearAllTimeouts();
+
+    // Clear triggered-once set on page changes for lifecycle triggers
+    if (event.type !== 'initial') {
+      this.clearLifecycleTriggers();
+    }
+
+    // Re-evaluate all registered triggers for new page
+    for (const [stepId, registration] of Object.entries(this._registeredTriggers)) {
+      console.debug(`[DAP] Re-registering triggers for step ${stepId} on new page`);
+      
+      // Remove old listeners first
+      this.removeTriggerListeners(stepId);
+      
+      // Re-register with new page context
+      this.registerTriggerListeners(
+        stepId,
+        registration.trigger,
+        registration.onTrigger,
+        registration.flowContext
+      );
+    }
+  }
+
+  /**
+   * Clear triggered-once set for lifecycle triggers on page change
+   */
+  private clearLifecycleTriggers(): void {
+    const lifecycleKeys = Array.from(this._triggeredOnceSet).filter(key => 
+      key.includes(':Lifecycle:')
+    );
+    
+    lifecycleKeys.forEach(key => {
+      this._triggeredOnceSet.delete(key);
+    });
+  }
+
+  /**
+   * Re-evaluate active triggers on page change
+   */
+  private reEvaluateActiveTriggers(event: PageChangeEvent): void {
+    // Re-check all registered steps after page change
+    Object.entries(this._registeredTriggers).forEach(([stepId, { trigger, onTrigger, flowContext }]) => {
+      this.registerTriggerListeners(stepId, trigger, onTrigger, flowContext);
+    });
+  }
+
+  /**
+   * Re-register all triggers for page context changes
+   */
+  public reRegisterAllTriggers(): void {
+    Object.entries(this._registeredTriggers).forEach(([stepId, { trigger, onTrigger, flowContext }]) => {
+      this.registerTriggerListeners(stepId, trigger, onTrigger, flowContext);
+    });
+  }
+
+  /**
+   * Clean up resources
+   */
+  public destroy(): void {
+    if (!this._initialized) return;
+    
+    // Clean up all active listeners
+    for (const stepId of this._activeListeners.keys()) {
+      this.removeTriggerListeners(stepId);
+    }
+    
+    // Unsubscribe from page changes
+    if (this._pageContextUnsubscribe) {
+      this._pageContextUnsubscribe();
+      this._pageContextUnsubscribe = null;
+    }
+    
+    this._activeListeners.clear();
+    this._triggeredOnceSet.clear();
+    this._registeredTriggers = {};
+    this._initialized = false;
+  }
+
+  /**
+   * Resolve trigger for a step following the priority rules:
+   * 1. Use step.trigger if it exists and has valid conditions
+   * 2. Fallback to uxExperience.elementTrigger if available
+   * 3. Return null if no trigger is resolvable
+   */
+  public resolveTrigger(step: EnhancedStepData): TriggerDefinition | null {
+    console.debug(`[DAP] Resolving trigger for step: ${step.stepId}`);
+
+    // Rule 1: Check if step has trigger with valid conditions
+    if (step.trigger && step.trigger.conditions && step.trigger.conditions.length > 0) {
+      console.log(`✅ [DAP] Step ${step.stepId}: Using STEP-LEVEL trigger with ${step.trigger.conditions.length} conditions`);
+      console.log(`   └── Trigger type: ${step.trigger.type}, Event: ${step.trigger.conditions[0]?.event}, Kind: ${step.trigger.conditions[0]?.kind}`);
+      
+      // Also log if elementTrigger exists (it will be ignored)
+      if (step.uxExperience?.elementTrigger) {
+        console.log(`   ⚠️  Note: elementTrigger "${step.uxExperience.elementTrigger}" is present but IGNORED (step-level takes priority)`);
+      }
+      
+      return step.trigger;
+    }
+
+    // Rule 2: Fallback to elementTrigger if available
+    if (step.uxExperience?.elementTrigger) {
+      console.warn(`⚠️  [DAP] Step ${step.stepId}: Falling back to ELEMENT-LEVEL trigger: "${step.uxExperience.elementTrigger}"`);
+      console.warn(`   └── This fallback will be removed in the future! Please add step-level trigger.`);
+      console.warn(`   └── Element selector: ${step.uxExperience.elementSelector}`);
+      
+      const fallbackTrigger = this.convertElementTriggerToTriggerDefinition(
+        step.uxExperience.elementTrigger,
+        step.uxExperience.elementSelector
+      );
+      return fallbackTrigger;
+    }
+
+    // Rule 3: No trigger available
+    console.error(`❌ [DAP] Step ${step.stepId}: NO TRIGGER FOUND! Step will execute immediately.`);
+    console.error(`   └── Consider adding either step-level trigger or elementTrigger`);
+    return null;
+  }
+
+  /**
+   * Convert legacy elementTrigger to TriggerDefinition
+   */
+  private convertElementTriggerToTriggerDefinition(
+    elementTrigger: string,
+    elementSelector?: string
+  ): TriggerDefinition {
+    let condition: TriggerCondition;
+
+    // Map legacy elementTrigger values
+    switch (elementTrigger.toLowerCase().trim()) {
+      case "on click":
+      case "click":
+        condition = {
+          kind: "Dom",
+          event: "click",
+          selector: elementSelector
+        };
+        break;
+
+      case "on hover":
+      case "hover":
+        condition = {
+          kind: "Dom",
+          event: "hover",
+          selector: elementSelector
+        };
+        break;
+
+      case "on page load":
+      case "page load":
+        condition = {
+          kind: "Lifecycle",
+          event: "page-load"
+        };
+        break;
+
+      case "on focus":
+      case "focus":
+        condition = {
+          kind: "Dom",
+          event: "focus",
+          selector: elementSelector
+        };
+        break;
+
+      default:
+        // Default to click if unrecognized
+        console.warn(`[DAP] Unknown elementTrigger: ${elementTrigger}, defaulting to click`);
+        condition = {
+          kind: "Dom",
+          event: "click",
+          selector: elementSelector
+        };
+    }
+
+    return {
+      type: "Single",
+      operator: "And",
+      once: true,
+      conditions: [condition]
+    };
+  }
+
+  /**
+   * Register trigger listeners for a step (page-aware)
+   */
+  public registerTriggerListeners(
+    stepId: string,
+    trigger: TriggerDefinition,
+    onTrigger: (context: TriggerEvaluationContext) => void,
+    flowContext?: { mode: 'Linear' | 'AnyOrder', currentStepActive: boolean }
+  ): void {
+    const currentPage = pageContextService.getPageId();
+
+    // Store trigger registration for re-evaluation on page changes
+    this._registeredTriggers[stepId] = { trigger, onTrigger, flowContext };
+
+    // Remove any existing listeners for this step
+    this.removeTriggerListeners(stepId);
+
+    const listeners: (() => void)[] = [];
+
+    for (const condition of trigger.conditions) {
+      const listener = this.createConditionListener(stepId, condition, trigger, onTrigger, flowContext);
+      if (listener) {
+        listeners.push(listener);
+      }
+    }
+
+    // Store listeners for cleanup
+    if (listeners.length > 0) {
+      this._activeListeners.set(stepId, listeners);
+    }
+  }
+
+  /**
+   * Create listener for individual trigger condition
+   */
+  private createConditionListener(
+    stepId: string,
+    condition: TriggerCondition,
+    trigger: TriggerDefinition,
+    onTrigger: (context: TriggerEvaluationContext) => void,
+    flowContext?: { mode: 'Linear' | 'AnyOrder', currentStepActive: boolean }
+  ): (() => void) | null {
+
+    switch (condition.kind) {
+      case "Dom":
+        return this.createDomListener(stepId, condition, trigger, onTrigger);
+
+      case "Lifecycle":
+        return this.createLifecycleListener(stepId, condition, trigger, onTrigger, flowContext);
+
+      case "Input":
+        return this.createInputListener(stepId, condition, trigger, onTrigger);
+
+      case "Time":
+        return this.createTimeListener(stepId, condition, trigger, onTrigger);
+
+      default:
+        console.warn(`[DAP] Unsupported condition kind: ${condition.kind}`);
+        return null;
+    }
+  }
+
+  /**
+   * Map trigger events to actual DOM events
+   */
+  private mapTriggerEventToDOMEvents(triggerEvent: string): string[] {
+    switch (triggerEvent) {
+      case 'hover':
+        return ['mouseenter'];
+      case 'click':
+        return ['click'];
+      case 'focus':
+        return ['focus'];
+      case 'blur':
+        return ['blur'];
+      case 'change':
+        return ['change'];
+      case 'input':
+        return ['input'];
+      case 'submit':
+        return ['submit'];
+      default:
+        // Return the event as-is for custom events
+        return [triggerEvent];
+    }
+  }
+
+  /**
+   * Create DOM event listener
+   */
+  private createDomListener(
+    stepId: string,
+    condition: TriggerCondition,
+    trigger: TriggerDefinition,
+    onTrigger: (context: TriggerEvaluationContext) => void
+  ): (() => void) | null {
+    if (!condition.selector) {
+      console.warn(`[DAP] DOM condition missing selector for step: ${stepId}`);
+      return null;
+    }
+
+    // Page context validation
+    const validation = this.validateSelectorOnCurrentPage(condition.selector);
+    console.debug(`[DAP] 📄 Page context validation for ${stepId}: selector exists=${validation.exists}, count=${validation.elementCount}`);
+
+    let targetElement: HTMLElement | null = null;
+    let observer: MutationObserver | null = null;
+    let timeoutCleanup: (() => void) | null = null;
+
+    // Function to attach listener to element
+    const attachListener = (element: HTMLElement) => {
+      // Clear timeout since we found the element
+      if (timeoutCleanup) {
+        timeoutCleanup();
+        timeoutCleanup = null;
+      }
+
+      // Map trigger event to appropriate DOM events
+      const eventNames = this.mapTriggerEventToDOMEvents(condition.event);
+      const cleanupFunctions: (() => void)[] = [];
+
+      console.debug(`[DAP] Mapping trigger event "${condition.event}" to DOM events:`, eventNames);
+
+      for (const eventName of eventNames) {
+        const eventHandler = (event: Event) => {
+          console.debug(`[DAP] DOM event triggered:`, event.type, condition.selector);
+
+          // Check if this is a "once" trigger and already fired
+          const onceKey = `${stepId}:${condition.kind}:${condition.event}`;
+          if (trigger.once && this._triggeredOnceSet.has(onceKey)) {
+            console.debug(`[DAP] Trigger already fired once for: ${onceKey}`);
+            return;
+          }
+
+          // Debouncing
+          if (condition.debounceMs) {
+            const debounceKey = `debounce:${stepId}:${condition.event}`;
+            const lastFired = this.getLastFiredTime(debounceKey);
+            const now = Date.now();
+            if (lastFired && (now - lastFired) < condition.debounceMs) {
+              console.debug(`[DAP] Event debounced for step: ${stepId}`);
+              return;
+            }
+            this.setLastFiredTime(debounceKey, now);
+          }
+
+          // Evaluate trigger
+          const context: TriggerEvaluationContext = {
+            stepId,
+            flowId: '', // Will be set by caller
+            element,
+            event
+          };
+
+          // For input events, capture the current input value
+          if (element && (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement)) {
+            if (condition.event === 'input' || condition.event === 'change' || condition.event === 'keyup') {
+              context.userInput = element.value;
+              console.debug(`[DAP] Captured input value: "${context.userInput}" for step: ${stepId}`);
+            }
+          }
+
+          const result = this.evaluateTrigger(trigger, context);
+          if (result.triggered) {
+            if (trigger.once) {
+              this._triggeredOnceSet.add(onceKey);
+            }
+            onTrigger(context);
+          }
+        };
+
+        element.addEventListener(eventName, eventHandler);
+        
+        cleanupFunctions.push(() => {
+          element.removeEventListener(eventName, eventHandler);
+        });
+      }
+
+      return () => {
+        cleanupFunctions.forEach(cleanup => cleanup());
+      };
+    };
+
+    // Try to find element immediately if validation passed
+    if (validation.exists) {
+      try {
+        targetElement = resolveSelector<HTMLElement>(condition.selector);
+        if (targetElement) {
+          console.debug(`[DAP] Element found immediately for selector: ${condition.selector}`);
+          return attachListener(targetElement);
+        }
+      } catch (error) {
+        console.warn(`[DAP] Invalid selector: ${condition.selector}`, error);
+        return null;
+      }
+    }
+
+    // Element not found, set up observer with timeout
+    console.debug(`[DAP] Element not found, waiting for: ${condition.selector}`);
+
+    let listenerCleanup: (() => void) | null = null;
+
+    // Set up timeout for element waiting
+    this.setupSelectorTimeout(stepId, condition.selector, () => {
+      console.warn(`[DAP] ⚠️ Selector timeout for step ${stepId}: ${condition.selector}`);
+      
+      // Disconnect observer
+      if (observer) {
+        observer.disconnect();
+        observer = null;
+      }
+      
+      // Emit telemetry event
+      console.warn(`[DAP] 📊 Telemetry: selector-not-found - Step: ${stepId}, Selector: ${condition.selector}`);
+      
+      // TODO: Based on step type, either skip (Optional) or fail safely (Mandatory)
+      // For now, we just clean up and let the flow continue
+    });
+
+    // Keep reference to timeout cleanup
+    timeoutCleanup = () => this.clearTimeoutForStep(stepId);
+
+    observer = new MutationObserver(() => {
+      try {
+        const element = resolveSelector<HTMLElement>(condition.selector!);
+        if (element && element !== targetElement) {
+          targetElement = element;
+          console.debug(`[DAP] Element appeared: ${condition.selector}`);
+          
+          // Cleanup observer and attach listener
+          if (observer) {
+            observer.disconnect();
+          }
+          
+          listenerCleanup = attachListener(element);
+        }
+      } catch (error) {
+        // Ignore selector errors during observation
+      }
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+
+    // Return cleanup function
+    return () => {
+      if (observer) {
+        observer.disconnect();
+      }
+      if (listenerCleanup) {
+        listenerCleanup();
+      }
+    };
+  }
+
+  /**
+   * Create lifecycle event listener (page-aware)
+   */
+  private createLifecycleListener(
+    stepId: string,
+    condition: TriggerCondition,
+    trigger: TriggerDefinition,
+    onTrigger: (context: TriggerEvaluationContext) => void,
+    flowContext?: { mode: 'Linear' | 'AnyOrder', currentStepActive: boolean }
+  ): (() => void) | null {
+    switch (condition.event) {
+      case "page-load":
+        // Check if this trigger should fire immediately
+        const onceKey = `${stepId}:${condition.kind}:${condition.event}`;
+        const shouldFireImmediately = !trigger.once || !this._triggeredOnceSet.has(onceKey);
+        
+        if (shouldFireImmediately) {
+          // Fire immediately for current page
+          setTimeout(() => {
+            const context: TriggerEvaluationContext = {
+              stepId,
+              flowId: '', // Will be set by caller
+              pageState: { 
+                loaded: true,
+                pageId: pageContextService.getPageId()
+              }
+            };
+
+            const result = this.evaluateTrigger(trigger, context);
+            if (result.triggered) {
+              if (trigger.once) {
+                this._triggeredOnceSet.add(onceKey);
+              }
+              onTrigger(context);
+            }
+          }, 100); // Small delay to ensure page is ready
+        }
+
+        // Also listen for future page changes
+        const pageChangeUnsubscribe = pageContextService.subscribe((event) => {
+          // Only fire on navigation events, not initial load
+          if (event.type === 'navigation' || event.type === 'reload') {
+            console.debug(`[DAP] Page change detected for page-load trigger, step: ${stepId}`);
+            
+            const pageLoadOnceKey = `${stepId}:${condition.kind}:${condition.event}`;
+            
+            // For page-load triggers, reset the "once" flag on page changes
+            if (trigger.once && event.type === 'navigation') {
+              this._triggeredOnceSet.delete(pageLoadOnceKey);
+            }
+            
+            // Check if we should fire again
+            const shouldFire = !trigger.once || !this._triggeredOnceSet.has(pageLoadOnceKey);
+            
+            if (shouldFire) {
+              const context: TriggerEvaluationContext = {
+                stepId,
+                flowId: '',
+                pageState: { 
+                  loaded: true,
+                  pageId: pageContextService.getPageId(),
+                  navigationEvent: event
+                }
+              };
+
+              const result = this.evaluateTrigger(trigger, context);
+              if (result.triggered) {
+                if (trigger.once) {
+                  this._triggeredOnceSet.add(pageLoadOnceKey);
+                }
+                onTrigger(context);
+              }
+            }
+          }
+        });
+
+        return () => {
+          pageChangeUnsubscribe();
+        };
+
+      case "page-unload":
+        const unloadHandler = () => {
+          const context: TriggerEvaluationContext = {
+            stepId,
+            flowId: '',
+            pageState: { 
+              unloading: true,
+              pageId: pageContextService.getPageId()
+            }
+          };
+
+          const result = this.evaluateTrigger(trigger, context);
+          if (result.triggered) {
+            onTrigger(context);
+          }
+        };
+
+        window.addEventListener('beforeunload', unloadHandler);
+        return () => {
+          window.removeEventListener('beforeunload', unloadHandler);
+        };
+
+      default:
+        console.warn(`[DAP] Unsupported lifecycle event: ${condition.event}`);
+        return null;
+    }
+  }
+
+  /**
+   * Create input event listener
+   */
+  private createInputListener(
+    stepId: string,
+    condition: TriggerCondition,
+    trigger: TriggerDefinition,
+    onTrigger: (context: TriggerEvaluationContext) => void
+  ): (() => void) | null {
+    if (!condition.selector) {
+      console.warn(`[DAP] Input condition missing selector for step: ${stepId}`);
+      return null;
+    }
+
+    // Page context validation for input selectors
+    const validation = this.validateSelectorOnCurrentPage(condition.selector);
+    console.debug(`[DAP] 📄 Input page context validation for ${stepId}: selector exists=${validation.exists}, count=${validation.elementCount}`);
+
+    const inputHandler = (event: Event) => {
+      const target = event.target as HTMLInputElement;
+      const value = target.value;
+
+      // Evaluate condition based on operator
+      let conditionMet = false;
+      if (condition.operator && condition.value !== undefined) {
+        conditionMet = this.evaluateCondition(value, condition.operator, condition.value);
+      } else {
+        conditionMet = true; // No specific condition, just trigger on input
+      }
+
+      if (conditionMet) {
+        const context: TriggerEvaluationContext = {
+          stepId,
+          flowId: '',
+          element: target,
+          event,
+          userInput: value
+        };
+
+        const result = this.evaluateTrigger(trigger, context);
+        if (result.triggered) {
+          onTrigger(context);
+        }
+      }
+    };
+
+    const elements = resolveSelectorAll(condition.selector!);
+    
+    if (elements.length === 0) {
+      console.log(`[DAP] Input elements not found, waiting: ${condition.selector}`);
+      
+      // Set up timeout for input element waiting
+      this.setupSelectorTimeout(stepId, condition.selector, () => {
+        console.warn(`[DAP] ⚠️ Input selector timeout for step ${stepId}: ${condition.selector}`);
+        console.warn(`[DAP] 📊 Telemetry: input-selector-not-found - Step: ${stepId}, Selector: ${condition.selector}`);
+        
+        // Input elements critical for rule-based steps - this might indicate cross-page issue
+        if (stepId.includes('rule') || stepId.includes('condition')) {
+          console.error(`[DAP] 🚨 Rule-based step ${stepId} cannot find input selector - possible cross-page navigation issue`);
+        }
+      });
+      
+      // Set up a MutationObserver to wait for the elements to appear
+      const observer = new MutationObserver(() => {
+        const foundElements = resolveSelectorAll(condition.selector!);
+        if (foundElements.length > 0) {
+          console.log(`[DAP] Input elements appeared: ${condition.selector}`);
+          
+          // Clear timeout since elements found
+          this.clearTimeoutForStep(stepId);
+          
+          foundElements.forEach(element => {
+            element.addEventListener('input', inputHandler);
+            element.addEventListener('change', inputHandler);
+          });
+          observer.disconnect();
+        }
+      });
+      
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true
+      });
+      
+      // Return cleanup function that disconnects the observer and clears timeout
+      return () => {
+        this.clearTimeoutForStep(stepId);
+        observer.disconnect();
+        const foundElements = resolveSelectorAll(condition.selector!);
+        foundElements.forEach(element => {
+          element.removeEventListener('input', inputHandler);
+          element.removeEventListener('change', inputHandler);
+        });
+      };
+    }
+    
+    // Elements found immediately
+    console.debug(`[DAP] ✅ Input elements found immediately: ${elements.length} element(s)`);
+    elements.forEach(element => {
+      element.addEventListener('input', inputHandler);
+      element.addEventListener('change', inputHandler);
+    });
+
+    return () => {
+      elements.forEach(element => {
+        element.removeEventListener('input', inputHandler);
+        element.removeEventListener('change', inputHandler);
+      });
+    };
+  }
+
+  /**
+   * Create time-based listener
+   */
+  private createTimeListener(
+    stepId: string,
+    condition: TriggerCondition,
+    trigger: TriggerDefinition,
+    onTrigger: (context: TriggerEvaluationContext) => void
+  ): (() => void) | null {
+    const delay = typeof condition.value === 'number' ? condition.value : 1000;
+
+    const timeoutId = setTimeout(() => {
+      const context: TriggerEvaluationContext = {
+        stepId,
+        flowId: '',
+        pageState: { timeElapsed: delay }
+      };
+
+      const result = this.evaluateTrigger(trigger, context);
+      if (result.triggered) {
+        onTrigger(context);
+      }
+    }, delay);
+
+    return () => {
+      clearTimeout(timeoutId);
+    };
+  }
+
+  /**
+   * Evaluate complete trigger (all conditions with logical operator)
+   */
+  public evaluateTrigger(
+    trigger: TriggerDefinition,
+    context: TriggerEvaluationContext
+  ): TriggerEvaluationResult {
+    const startTime = Date.now();
+    let matchedConditions = 0;
+    const totalConditions = trigger.conditions.length;
+
+    // For single condition triggers, just check if we have one condition
+    if (trigger.type === "Single" && totalConditions === 1) {
+      matchedConditions = 1; // Assume the condition was met if we're evaluating
+    } else if (trigger.type === "Composite") {
+      // For composite triggers, we need more sophisticated evaluation
+      // For now, we'll assume if we got here, at least one condition was met
+      matchedConditions = 1;
+    }
+
+    let triggered = false;
+    if (trigger.operator === "And") {
+      triggered = matchedConditions === totalConditions;
+    } else if (trigger.operator === "Or") {
+      triggered = matchedConditions > 0;
+    }
+
+    const result: TriggerEvaluationResult = {
+      triggered,
+      matchedConditions,
+      totalConditions,
+      evaluationTime: Date.now() - startTime,
+      debugInfo: {
+        triggerType: trigger.type,
+        operator: trigger.operator,
+        once: trigger.once
+      }
+    };
+
+    console.debug(`[DAP] Trigger evaluation result:`, result);
+    return result;
+  }
+
+  /**
+   * Evaluate individual condition value
+   */
+  private evaluateCondition(actualValue: any, operator: RuleOperator, expectedValue: any): boolean {
+    switch (operator) {
+      case "Equals":
+        return actualValue === expectedValue;
+      case "NotEquals":
+        return actualValue !== expectedValue;
+      case "Contains":
+        return String(actualValue).includes(String(expectedValue));
+      case "NotContains":
+        return !String(actualValue).includes(String(expectedValue));
+      case "StartsWith":
+        return String(actualValue).startsWith(String(expectedValue));
+      case "EndsWith":
+        return String(actualValue).endsWith(String(expectedValue));
+      case "GreaterThan":
+        return Number(actualValue) > Number(expectedValue);
+      case "LessThan":
+        return Number(actualValue) < Number(expectedValue);
+      case "GreaterThanOrEqual":
+        return Number(actualValue) >= Number(expectedValue);
+      case "LessThanOrEqual":
+        return Number(actualValue) <= Number(expectedValue);
+      case "Empty":
+        return !actualValue || String(actualValue).trim() === '';
+      case "In":
+        if (Array.isArray(expectedValue)) {
+          return expectedValue.includes(actualValue);
+        }
+        return false;
+      case "NotIn":
+        if (Array.isArray(expectedValue)) {
+          return !expectedValue.includes(actualValue);
+        }
+        return true;
+      case "Regex":
+        try {
+          const regex = new RegExp(String(expectedValue));
+          return regex.test(String(actualValue));
+        } catch {
+          return false;
+        }
+      default:
+        console.warn(`[DAP] Unsupported operator: ${operator}`);
+        return false;
+    }
+  }
+
+  /**
+   * Remove all listeners for a step
+   */
+  public removeTriggerListeners(stepId: string): void {
+    const listeners = this._activeListeners.get(stepId);
+    if (listeners) {
+      listeners.forEach(cleanup => cleanup());
+      this._activeListeners.delete(stepId);
+    }
+    // Note: Don't remove from _registeredTriggers as we need it for re-registration
+  }
+
+  /**
+   * Clear all listeners
+   */
+  public clearAllListeners(): void {
+    for (const [stepId, listeners] of this._activeListeners) {
+      listeners.forEach(cleanup => cleanup());
+    }
+    this._activeListeners.clear();
+    this._triggeredOnceSet.clear();
+    this._registeredTriggers = {};
+    this.clearAllTimeouts();
+  }
+
+  /**
+   * Clear all active timeouts
+   */
+  private clearAllTimeouts(): void {
+    for (const timeoutId of this._waitTimeouts.values()) {
+      clearTimeout(timeoutId);
+    }
+    this._waitTimeouts.clear();
+  }
+
+  /**
+   * Clear specific timeout for a step
+   */
+  private clearTimeoutForStep(stepId: string): void {
+    const timeoutId = this._waitTimeouts.get(stepId);
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      this._waitTimeouts.delete(stepId);
+    }
+  }
+
+  /**
+   * Validate if selector exists on current page
+   */
+  private validateSelectorOnCurrentPage(selector: string): {
+    exists: boolean;
+    elementCount: number;
+    validationTimestamp: number;
+  } {
+    const elements = resolveSelectorAll(selector);
+    return {
+      exists: elements.length > 0,
+      elementCount: elements.length,
+      validationTimestamp: Date.now()
+    };
+  }
+
+  /**
+   * Set up timeout for selector waiting with proper cleanup
+   */
+  private setupSelectorTimeout(
+    stepId: string, 
+    selector: string, 
+    onTimeout: () => void,
+    timeoutMs: number = this._selectorWaitTimeout
+  ): void {
+    // Clear any existing timeout
+    this.clearTimeoutForStep(stepId);
+    
+    const timeoutId = setTimeout(() => {
+      console.warn(`[DAP] ⏰ Timeout: Selector not found within ${timeoutMs}ms for step ${stepId}: ${selector}`);
+      console.warn(`[DAP] Triggering timeout handler and cleaning up for step: ${stepId}`);
+      this._waitTimeouts.delete(stepId);
+      onTimeout();
+    }, timeoutMs);
+    
+    this._waitTimeouts.set(stepId, timeoutId);
+    console.debug(`[DAP] ⏱️  Set ${timeoutMs}ms timeout for selector waiting: ${stepId}`);
+  }
+
+  /**
+   * Reset once-fired triggers for a new flow
+   */
+  public resetOnceTriggersForFlow(flowId: string): void {
+    // Clear all once-fired triggers (we could be more selective in the future)
+    this._triggeredOnceSet.clear();
+  }
+
+  // Helper methods for debouncing
+  private _debounceTimestamps: Map<string, number> = new Map();
+
+  private getLastFiredTime(key: string): number | undefined {
+    return this._debounceTimestamps.get(key);
+  }
+
+  private setLastFiredTime(key: string, timestamp: number): void {
+    this._debounceTimestamps.set(key, timestamp);
+  }
+}
+
+export const triggerManager = TriggerManager.getInstance();