@cognior/iap-sdk 0.1.0

package/src/core/flowEngine.ts

@@ -0,0 +1,1833 @@
+// src/core/flowEngine.ts
+// Enhanced flow execution engine with step-level trigger support
+
+import { LocationContextService } from '../services/locationContextService';
+import { userContextService } from '../services/userContextService';
+import { pageContextService, type PageChangeEvent } from '../services/pageContextService';
+import { resolveSelector } from '../utils/selectors';
+import { normalizeTrigger } from '../utils/triggerNormalizer';
+import { evaluateRuleBlock } from '../utils/ruleEvaluator';
+import { trackStepView, resetFlowTracking } from '../tracking';
+import { triggerManager, type EnhancedStepData } from './triggerManager';
+import type { 
+  RuleCondition, 
+  ConditionRuleBlock as RuleBlock, 
+  ConditionOperator, 
+  ConditionValueType,
+  TriggerDefinition,
+  TriggerEvaluationContext,
+  FlowExecutionMode,
+  StepType,
+  BranchType
+} from '../experiences/types';
+
+/**
+ * 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 flow model interfaces with trigger support
+export interface FlowData {
+  flowId: string;
+  flowName: string;
+  steps: EnhancedStepData[];
+  execution?: {
+    mode?: FlowExecutionMode;
+    frequencyType?: string;
+  };
+}
+
+export interface UXExperience {
+  uxExperienceType: string;
+  elementSelector?: string;
+  elementTrigger?: string;
+  elementLocation?: string;
+  position?: { x: string; y: string };
+  content: any;
+  modalContent?: any;
+}
+
+// Flow execution states
+type FlowExecutionState = 'ACTIVE' | 'WAITING_FOR_INPUT' | 'TRANSITIONING' | 'TERMINATED';
+
+interface FlowState {
+  activeFlowId: string | null;
+  flowInProgress: boolean;
+  activeStep: number;
+  activeStepTriggered: boolean;
+  executionState: FlowExecutionState;
+  executionMode: FlowExecutionMode;
+  triggeredSteps: Set<number>; // Track triggered steps for AnyOrder mode
+  stepAdvancing?: boolean; // Prevent concurrent step advancement
+}
+
+/**
+ * Core flow execution engine
+ * Handles step-by-step flow execution with page awareness
+ */
+export class FlowEngine {
+  private static _instance: FlowEngine;
+  private _locationService = LocationContextService.getInstance();
+  private _state: FlowState = {
+    activeFlowId: null,
+    flowInProgress: false,
+    activeStep: 0,
+    activeStepTriggered: false,
+    executionState: 'TERMINATED',
+    executionMode: 'Linear',
+    triggeredSteps: new Set()
+  };
+  
+  private _currentFlow: FlowData | null = null;
+  private _stepTriggerListeners: Map<string, () => void> = new Map();
+  private _pageChangeUnsubscribe: (() => void) | null = null;
+  private _domObservers: Map<string, MutationObserver> = new Map();
+
+  private constructor() {
+    // Initialize page context service and trigger manager
+    pageContextService.initialize();
+    triggerManager.initialize();
+    
+    // Listen for location-based page changes (legacy)
+    this._pageChangeUnsubscribe = this._locationService.subscribe((context) => {
+      this.checkFlowResumption();
+    });
+    
+    // Listen for page context changes (new page-aware system)
+    pageContextService.subscribe(this.handlePageChange.bind(this));
+  }
+
+  /**
+   * Handle page changes and re-evaluate active flows
+   */
+  private handlePageChange(event: PageChangeEvent): void {
+    console.debug('[DAP] FlowEngine: Handling page change:', event.type, {
+      from: event.previous?.pathname,
+      to: event.current.pathname,
+      activeFlow: this._state.activeFlowId
+    });
+
+    // If we have an active flow, re-register triggers for current step
+    if (this._state.flowInProgress && this._currentFlow) {
+      this.reRegisterActiveStepTriggers();
+    }
+    
+    // Also check legacy flow resumption
+    this.checkFlowResumption();
+  }
+
+  /**
+   * Re-register triggers for the currently active step(s) after page change
+   */
+  private reRegisterActiveStepTriggers(): void {
+    if (!this._currentFlow || !this._state.flowInProgress) {
+      return;
+    }
+
+    console.debug('[DAP] FlowEngine: Re-registering triggers after page change');
+
+    if (this._state.executionMode === 'Linear') {
+      // Re-register trigger for current step
+      if (this._state.activeStep < this._currentFlow.steps.length && !this._state.activeStepTriggered) {
+        const currentStep = this._currentFlow.steps[this._state.activeStep];
+        this.setupStepTrigger(currentStep, this._state.activeStep);
+      }
+    } else {
+      // AnyOrder mode: re-register triggers for all non-triggered steps
+      this._currentFlow.steps.forEach((step, index) => {
+        if (!this._state.triggeredSteps.has(step.stepOrder)) {
+          this.setupStepTrigger(step, index);
+        }
+      });
+    }
+  }
+
+  public static getInstance(): FlowEngine {
+    if (!this._instance) {
+      this._instance = new FlowEngine();
+    }
+    return this._instance;
+  }
+
+  /**
+   * Check if flow requires user context
+   * For now, allow anonymous flows unless rules specifically reference user properties
+   */
+  private flowRequiresUserContext(flowData: FlowData): boolean {
+    // Check if any step has rules that reference user properties
+    for (const step of flowData.steps) {
+      if (step.conditionRuleBlocks) {
+        for (const ruleBlock of step.conditionRuleBlocks) {
+          if (ruleBlock.conditions) {
+            for (const condition of ruleBlock.conditions) {
+              // Check if condition references user properties
+              if ((condition as any).property?.startsWith('user.')) {
+                console.debug(`[DAP] Flow ${flowData.flowId} requires user context due to rule: ${(condition as any).property}`);
+                return true;
+              }
+            }
+          }
+        }
+      }
+    }
+    
+    // For now, allow flows without explicit user property rules
+    return false;
+  }
+
+  /**
+   * Start a new flow
+   */
+  public async startFlow(flowData: FlowData): Promise<void> {
+    console.log(`[DAP] 🚀 Starting flow: ${flowData.flowId}`);
+    
+    // Analyze and log trigger usage for the entire flow
+    this.analyzeTriggerUsage(flowData);
+
+    // Analyze page context for multi-page flows
+    this.analyzeFlowPageContext(flowData);
+
+    // Check if flow requires user context
+    if (this.flowRequiresUserContext(flowData) && !userContextService.hasRealUser()) {
+      console.warn(`[DAP] Flow ${flowData.flowId} requires user context but none available - flow execution blocked`);
+      return;
+    }
+    
+    // Check for rule steps and analyze their page context
+    const ruleSteps = flowData.steps.filter(step => 
+      step.conditionRuleBlocks && step.conditionRuleBlocks.length > 0
+    );
+    console.debug(`[DAP] Flow has ${ruleSteps.length} rule steps:`, ruleSteps);
+    
+    if (ruleSteps.length > 0) {
+      this.analyzeRuleStepsPageContext(ruleSteps);
+    }
+    
+    // Abort current flow if any
+    if (this._state.flowInProgress) {
+      this.abortFlow();
+    }
+    
+    // Reset tracking state for new flow
+    resetFlowTracking(flowData.flowId);
+    
+    // Initialize new flow state
+    this._state = {
+      activeFlowId: flowData.flowId,
+      flowInProgress: true,
+      activeStep: 0,
+      activeStepTriggered: false,
+      executionState: 'ACTIVE',
+      executionMode: flowData.execution?.mode || 'Linear',
+      triggeredSteps: new Set()
+    };
+    
+    this._currentFlow = flowData;
+    
+    // Start executing steps from beginning
+    this.executeStep();
+  }
+
+  /**
+   * Abort current flow
+   */
+  public abortFlow(): void {
+    if (!this._state.flowInProgress) return;
+    
+    // Clean up current step
+    this.cleanupCurrentStep();
+    
+    // Reset trigger state for the flow
+    if (this._state.activeFlowId) {
+      triggerManager.resetOnceTriggersForFlow(this._state.activeFlowId);
+    }
+    
+    // Reset state
+    this._state = {
+      activeFlowId: null,
+      flowInProgress: false,
+      activeStep: 0,
+      activeStepTriggered: false,
+      executionState: 'TERMINATED',
+      executionMode: 'Linear',
+      triggeredSteps: new Set()
+    };
+    
+    this._currentFlow = null;
+  }
+
+  /**
+   * Execute current step in the flow with enhanced trigger support
+   */
+  private executeStep(): void {
+    if (!this._currentFlow || !this._state.flowInProgress) return;
+    
+    // Handle different execution modes
+    if (this._state.executionMode === 'Linear') {
+      this.executeLinearStep();
+    } else if (this._state.executionMode === 'AnyOrder') {
+      this.executeAnyOrderSteps();
+    }
+  }
+
+  /**
+   * Execute steps in linear order (traditional flow)
+   */
+  private executeLinearStep(): void {
+    if (!this._currentFlow) return;
+    
+    const step = this._currentFlow.steps[this._state.activeStep];
+    if (!step) {
+      console.debug(`[DAP] Flow completed`);
+      this.completeFlow();
+      return;
+    }
+    
+    this.executeStepWithTrigger(step);
+  }
+
+  /**
+   * Execute steps in any order (all steps listen simultaneously)
+   */
+  private executeAnyOrderSteps(): void {
+    if (!this._currentFlow) return;
+    
+    // Set up triggers for all untriggered steps
+    for (let i = 0; i < this._currentFlow.steps.length; i++) {
+      if (!this._state.triggeredSteps.has(i)) {
+        const step = this._currentFlow.steps[i];
+        this.setupStepTrigger(step, i);
+      }
+    }
+  }
+
+  /**
+   * Execute a step with enhanced trigger support
+   */
+  private executeStepWithTrigger(step: EnhancedStepData, stepIndex?: number): void {
+    console.log(`[DAP] ========== EXECUTING STEP ${step.stepId} ==========`);
+    
+    // Step 1: Resolve trigger (step-level or fallback to elementTrigger)
+    const trigger = triggerManager.resolveTrigger(step);
+    
+    if (!trigger) {
+      console.log(`[DAP] Step ${step.stepId}: NO TRIGGER - executing immediately`);
+      this.executeStepContent(step);
+      this.postStepTransition(step);
+      return;
+    }
+
+    console.log(`[DAP] Step ${step.stepId}: TRIGGER RESOLVED - setting up listeners`);
+    
+    // Step 2: Register trigger listeners with flow context
+    const actualStepIndex = stepIndex !== undefined ? stepIndex : this._state.activeStep;
+    const isCurrentActiveStep = actualStepIndex === this._state.activeStep;
+    
+    const flowContext = {
+      mode: this._state.executionMode,
+      currentStepActive: isCurrentActiveStep
+    };
+    
+    triggerManager.registerTriggerListeners(step.stepId, trigger, (context) => {
+      // Check if this step has already been triggered (prevent double-execution)
+      if (this._state.executionMode === 'Linear' && this._state.activeStepTriggered) {
+        return;
+      }
+
+      // Mark step as triggered in linear mode
+      if (this._state.executionMode === 'Linear') {
+        this._state.activeStepTriggered = true;
+      }
+
+      // Mark step as triggered in AnyOrder mode
+      if (this._state.executionMode === 'AnyOrder') {
+        this._state.triggeredSteps.add(actualStepIndex);
+      }
+
+      // Execute step content
+      this.executeStepContent(step);
+
+      // For rule-based steps (no UX experience), evaluate rules with the input value
+      if (!step.uxExperience && step.conditionRuleBlocks && step.conditionRuleBlocks.length > 0) {
+        console.log(`[DAP] Step ${step.stepId} is rule-based, waiting for conditions`);
+        console.log(`[DAP] Rule-based step triggered, evaluating rules with input value: ${context.userInput}`);
+        
+        // Validate page context before rule evaluation
+        if (step.userInputSelector) {
+          const inputElements = resolveSelectorAll(step.userInputSelector);
+          if (inputElements.length === 0) {
+            console.error(`[DAP] 🚨 CRITICAL: Rule-based step ${step.stepId} input selector not found: ${step.userInputSelector}`);
+            console.error(`[DAP] This indicates a cross-page navigation issue. Skipping rule evaluation.`);
+            this.advanceToNextStep();
+            return;
+          }
+        }
+        
+        this.evaluateStepRulesWithValue(step, context.userInput || '');
+      } else {
+        // Handle post-step transition for regular UX steps
+        this.postStepTransition(step);
+      }
+    }, flowContext);
+  }
+
+  /**
+   * Set up trigger for a specific step (used in AnyOrder mode)
+   */
+  private setupStepTrigger(step: EnhancedStepData, stepIndex: number): void {
+    const trigger = triggerManager.resolveTrigger(step);
+    
+    if (!trigger) {
+      
+      // If it's an optional step, mark as completed
+      if (step.stepType === 'Optional') {
+        this._state.triggeredSteps.add(stepIndex);
+      }
+      return;
+    }
+
+    const flowContext = {
+      mode: this._state.executionMode,
+      currentStepActive: true // In AnyOrder mode, all steps are considered "active"
+    };
+
+    triggerManager.registerTriggerListeners(step.stepId, trigger, (context) => {
+      
+      this._state.triggeredSteps.add(stepIndex);
+      this.executeStepContent(step);
+      this.postStepTransition(step);
+      
+      // Check if flow is complete
+      this.checkFlowCompletion();
+    }, flowContext);
+  }
+
+  /**
+   * Execute the actual step content (UX experience)
+   */
+  private executeStepContent(step: EnhancedStepData): void {
+    // Track step view
+    if (this._state.activeFlowId) {
+      trackStepView(this._state.activeFlowId, step.stepId);
+    }
+
+    if (step.uxExperience) {
+      this.triggerUXExperience(step);
+    } else {
+      console.log(`[DAP] Step ${step.stepId} is rule-based, waiting for conditions`);
+    }
+  }
+
+  /**
+   * Handle post-step transition (rules evaluation and flow control)
+   */
+  private postStepTransition(step: EnhancedStepData): void {
+    // For steps with rule blocks but no UX experience (like steps 9 & 10):
+    // Don't evaluate rules immediately - wait for input triggers to fire
+    if (step.conditionRuleBlocks && step.conditionRuleBlocks.length > 0 && !step.uxExperience) {
+      console.log(`[DAP] Step ${step.stepId} has rules but no UX - waiting for input trigger`);
+      // Don't advance - let the input trigger handle rule evaluation
+      return;
+    }
+    
+    // For steps with both rules AND UX experience:
+    // Evaluate rules after UX experience completes
+    if (step.conditionRuleBlocks && step.conditionRuleBlocks.length > 0 && step.uxExperience) {
+      this.evaluateStepRules(step);
+      return;
+    }
+
+    // For steps with UX experiences but no rules:
+    // Let the completion tracker handle advancement
+    if (step.uxExperience && (!step.conditionRuleBlocks || step.conditionRuleBlocks.length === 0)) {
+      // Advancement will be handled by completion tracker
+      return;
+    }
+
+    // For steps with neither UX experience nor rules:
+    // Advance immediately
+    if (!step.uxExperience && (!step.conditionRuleBlocks || step.conditionRuleBlocks.length === 0)) {
+      if (this._state.executionMode === 'Linear') {
+        this.advanceToNextStep();
+      }
+    }
+  }
+
+  /**
+   * Evaluate step rules with a specific input value
+   * Used for rule-based steps when triggered by input
+   */
+  private evaluateStepRulesWithValue(step: EnhancedStepData, inputValue: string) {
+    if (!step.conditionRuleBlocks || step.conditionRuleBlocks.length === 0) {
+      this.advanceToNextStep();
+      return;
+    }
+
+    console.log(`[DAP] Evaluating rules for step ${step.stepId} with input: "${inputValue}"`);
+
+    // Page context validation for rule-based steps
+    console.debug(`[DAP] 📄 Rule evaluation page context check for step: ${step.stepId}`);
+    
+    // Check if rule selectors exist on current page
+    let pageContextValid = true;
+    for (const ruleBlock of step.conditionRuleBlocks) {
+      if (ruleBlock.selector) {
+        const elements = resolveSelectorAll(ruleBlock.selector);
+        if (elements.length === 0) {
+          console.warn(`[DAP] ⚠️ Rule block selector not found on current page: ${ruleBlock.selector}`);
+          console.warn(`[DAP] This may indicate a cross-page navigation issue for rule-based step ${step.stepId}`);
+          pageContextValid = false;
+        }
+      }
+    }
+
+    if (!pageContextValid) {
+      console.warn(`[DAP] 🚨 Page context validation failed for rule-based step ${step.stepId}`);
+      console.warn(`[DAP] Skipping rule evaluation due to missing selectors - possible cross-page issue`);
+      
+      // For now, advance to next step rather than hanging
+      // TODO: Consider implementing page navigation waiting logic here
+      this.advanceToNextStep();
+      return;
+    }
+
+    try {
+      // Evaluate each rule block with the input value
+      for (const ruleBlock of step.conditionRuleBlocks) {
+        // Need to evaluate the rule with the input value
+        const ruleMatched = evaluateRuleBlock(ruleBlock, inputValue);
+        console.log(`[DAP] Rule block result for "${inputValue}": ${ruleMatched}`);
+        
+        if (ruleMatched) {
+          console.log(`[DAP] Rule matched for step ${step.stepId}, handling branching`);
+          this.handleRuleBranching(ruleBlock);
+          return; // First matching rule wins
+        }
+      }
+
+      console.log(`[DAP] No rules matched for step ${step.stepId}, continuing execution`);
+      this.advanceToNextStep();
+    } catch (error) {
+      console.error(`[DAP] Error evaluating rules for step ${step.stepId}:`, error);
+      this.advanceToNextStep(); // Continue on error
+    }
+  }
+
+  /**
+   * Evaluate a single rule block with a specific input value
+   */
+  private evaluateRuleBlockWithValue(ruleBlock: any, inputValue: string): boolean {
+    return evaluateRuleBlock(ruleBlock, inputValue);
+  }
+
+  /**
+   * Evaluate condition rule blocks and handle branching
+   */
+  private evaluateStepRules(step: EnhancedStepData): void {
+    console.debug(`[DAP] Evaluating rules for step: ${step.stepId}`);
+
+    if (!step.conditionRuleBlocks) return;
+
+    for (const ruleBlock of step.conditionRuleBlocks) {
+      try {
+        // Get input value for rule evaluation
+        let inputValue: string | number | boolean = '';
+        
+        if (step.userInputSelector) {
+          const inputElement = document.querySelector(step.userInputSelector) as HTMLInputElement;
+          if (inputElement) {
+            inputValue = inputElement.value;
+          }
+        }
+        
+        const ruleMatched = evaluateRuleBlock(ruleBlock, inputValue);
+        
+        if (ruleMatched) {
+          console.debug(`[DAP] Rule matched for step ${step.stepId}, handling branching`);
+          this.handleRuleBranching(ruleBlock);
+          return; // First matching rule wins
+        }
+      } catch (error) {
+        console.error(`[DAP] Error evaluating rule block:`, error);
+      }
+    }
+
+    // No rules matched, continue normal flow
+    if (this._state.executionMode === 'Linear') {
+      this.advanceToNextStep();
+    }
+  }
+
+  /**
+   * Handle rule-based branching based on BranchType
+   */
+  private handleRuleBranching(ruleBlock: any): void {
+    console.log(`[DAP] Handling rule-based branching for block:`, ruleBlock);
+    
+    const branchType = ruleBlock.branchType;
+    
+    switch (branchType) {
+      case 'Flow':
+        // Terminate current flow and start nextFlowId
+        const nextFlowId = ruleBlock.nextFlowId;
+        if (nextFlowId) {
+          console.log(`[DAP] Branching to new flow: ${nextFlowId}`);
+          this.terminateCurrentFlow();
+          this.startNewFlow(nextFlowId);
+        } else {
+          console.warn(`[DAP] Flow branch type specified but no nextFlowId found`);
+          this.continueToNextStep();
+        }
+        break;
+        
+      case 'Step':
+        // Jump to specific stepId
+        const targetStepId = ruleBlock.stepId;
+        if (targetStepId) {
+          console.log(`[DAP] Jumping to step: ${targetStepId}`);
+          this.jumpToStep(targetStepId);
+        } else {
+          console.warn(`[DAP] Step branch type specified but no stepId found`);
+          this.continueToNextStep();
+        }
+        break;
+        
+      case 'Continue':
+      default:
+        // Continue to next step in order
+        console.log(`[DAP] Continuing to next step`);
+        this.continueToNextStep();
+        break;
+    }
+  }
+
+  /**
+   * Terminate current flow execution
+   */
+  private terminateCurrentFlow(): void {
+    console.log(`[DAP] Terminating current flow: ${this._currentFlow?.flowId}`);
+    
+    // Clean up current flow state
+    this.resetFlowState();
+    
+    // Trigger flow completion event
+    if (this._currentFlow) {
+      resetFlowTracking(this._currentFlow.flowId);
+    }
+  }
+
+  /**
+   * Reset flow state to initial values
+   */
+  private resetFlowState(): void {
+    // Clean up current step
+    this.cleanupCurrentStep();
+    
+    // Reset trigger state for the flow
+    if (this._state.activeFlowId) {
+      triggerManager.resetOnceTriggersForFlow(this._state.activeFlowId);
+    }
+    
+    // Reset state
+    this._state = {
+      activeFlowId: null,
+      flowInProgress: false,
+      activeStep: 0,
+      activeStepTriggered: false,
+      executionState: 'TERMINATED',
+      executionMode: 'Linear',
+      triggeredSteps: new Set()
+    };
+    
+    this._currentFlow = null;
+  }
+
+  /**
+   * Start a new flow by ID
+   */
+  private startNewFlow(flowId: string): void {
+    console.log(`[DAP] Starting new flow: ${flowId}`);
+    
+    // Use the global DAP startFlow method if available
+    if (typeof window !== 'undefined' && (window as any).DAP && (window as any).DAP.startFlow) {
+      try {
+        (window as any).DAP.startFlow(flowId);
+      } catch (error) {
+        console.error(`[DAP] Error starting flow ${flowId}:`, error);
+      }
+    } else {
+      // Fallback: emit an event that can be caught by external flow manager
+      const event = new CustomEvent('dap:startFlow', {
+        detail: { flowId }
+      });
+      
+      window.dispatchEvent(event);
+    }
+  }
+
+  /**
+   * Jump to a specific step within current flow
+   */
+  private jumpToStep(stepId: string): void {
+    console.log(`[DAP] Jumping to step: ${stepId}`);
+    
+    if (!this._currentFlow) {
+      console.error(`[DAP] Cannot jump to step: no active flow`);
+      return;
+    }
+
+    // Find the step index by stepId
+    const targetStepIndex = this._currentFlow.steps.findIndex(step => step.stepId === stepId);
+    
+    if (targetStepIndex === -1) {
+      console.error(`[DAP] Step not found: ${stepId}`);
+      this.continueToNextStep();
+      return;
+    }
+
+    // Update state to target step
+    this._state.activeStep = targetStepIndex;
+    this._state.activeStepTriggered = false;
+    
+    // Execute target step
+    const targetStep = this._currentFlow.steps[targetStepIndex];
+    this.executeStepWithTrigger(targetStep, targetStepIndex);
+  }
+
+  /**
+   * Continue to next step in sequence
+   */
+  private continueToNextStep(): void {
+    if (this._state.executionMode === 'Linear') {
+      this.advanceToNextStep();
+    }
+  }
+
+  /**
+   * Check if AnyOrder flow is complete
+   */
+  private checkFlowCompletion(): void {
+    if (!this._currentFlow || this._state.executionMode !== 'AnyOrder') return;
+
+    // Count mandatory steps
+    const mandatorySteps = this._currentFlow.steps.filter((step, index) => 
+      step.stepType === 'Mandatory'
+    );
+
+    const triggeredMandatory = this._currentFlow.steps.filter((step, index) =>
+      step.stepType === 'Mandatory' && this._state.triggeredSteps.has(index)
+    );
+
+    console.debug(`[DAP] Flow completion check: ${triggeredMandatory.length}/${mandatorySteps.length} mandatory steps completed`);
+
+    if (triggeredMandatory.length === mandatorySteps.length) {
+      console.debug(`[DAP] All mandatory steps completed, flow complete`);
+      this.completeFlow();
+    }
+  }
+
+  /**
+   * Execute UX Experience step
+   */
+  private executeUXStep(step: EnhancedStepData): void {
+    const ux = step.uxExperience!;
+    
+    console.debug(`[DAP] Executing UX step: ${step.stepId}`, {
+      elementSelector: ux.elementSelector,
+      elementTrigger: ux.elementTrigger,
+      elementLocation: ux.elementLocation
+    });
+    
+    // Check page/location requirement
+    if (ux.elementLocation) {
+      const currentContext = this._locationService.getContext();
+      const locationMatches = this.matchesLocation(ux.elementLocation, currentContext);
+      
+      if (!locationMatches) {
+        console.debug(`[DAP] Step ${step.stepId} waiting for location: ${ux.elementLocation} (current: ${currentContext.currentPath})`);
+        return; // Wait for page change
+      }
+    }
+    
+    console.debug(`[DAP] Step ${step.stepId} location matches, setting up trigger`);
+    
+    // Handle different trigger types
+    const trigger = ux.elementTrigger?.toLowerCase() || 'on page load';
+    
+    if (trigger === 'on page load' || trigger === 'page load' || trigger === 'pageload') {
+      // Immediate trigger
+      console.debug(`[DAP] Step ${step.stepId} has immediate trigger`);
+      this.triggerUXExperience(step);
+    } else {
+      // DOM-based trigger
+      this.setupDOMTrigger(step);
+    }
+  }
+
+  /**
+   * Execute Rule step (DAP-standard)
+   */
+  private executeRuleStep(step: EnhancedStepData): void {
+    console.debug(`[DAP] === FLOWENGINE: Rule step initialized: ${step.stepId} ===`);
+    
+    // Testing alert for FlowEngine rule step
+    alert(`🔧 FlowEngine Rule Step!\n\nStep: ${step.stepId}\nUserInputSelector: ${step.userInputSelector}\nRule blocks: ${step.conditionRuleBlocks?.length || 0}`);
+    
+    if (!step.userInputSelector) {
+      console.warn(`[DAP] Rule step ${step.stepId} has no userInputSelector`);
+      alert(`❌ No userInputSelector for rule step ${step.stepId}`);
+      return; // Stay idle, don't advance
+    }
+    
+    if (!step.conditionRuleBlocks || step.conditionRuleBlocks.length === 0) {
+      console.warn(`[DAP] Rule step ${step.stepId} has no conditionRuleBlocks`);
+      alert(`❌ No conditionRuleBlocks for rule step ${step.stepId}`);
+      return; // Stay idle, don't advance
+    }
+
+    // Set flow state to waiting for input
+    this._state.executionState = 'WAITING_FOR_INPUT';
+    
+    // Try to set up rule monitoring immediately
+    this.setupRuleMonitoring(step);
+  }
+
+  private setupRuleMonitoring(step: EnhancedStepData): void {
+    // Clean up any existing listeners for this step first
+    const existingCleanup = this._stepTriggerListeners.get(step.stepId);
+    if (existingCleanup) {
+      existingCleanup();
+      this._stepTriggerListeners.delete(step.stepId);
+    }
+    
+    // Find input element
+    const inputElement = resolveSelector(step.userInputSelector!) as HTMLInputElement;
+    
+    if (!inputElement) {
+      console.warn(`[DAP] Input element not found: ${step.userInputSelector}`);
+      console.debug(`[DAP] Setting up page change listener to retry when page/component changes...`);
+      
+      alert(`⏳ Element Not Found - Waiting!\n\nSelector: ${step.userInputSelector}\n\nWill retry automatically when you navigate to the correct page/component.`);
+      
+      // Set up page change listener to retry
+      this.setupPageChangeRetry(step);
+      return;
+    }
+    
+    console.debug(`[DAP] ✅ Input element found: ${step.userInputSelector}`);
+    console.debug(`[DAP] Listening for input on ${step.userInputSelector}`);
+    
+    alert(`✅ Element Found!\n\nSelector: ${step.userInputSelector}\nElement: ${inputElement.tagName}\n\nRule monitoring active!`);
+
+    // Listen for input events - define cleanup first
+    const cleanup = () => {
+      inputElement.removeEventListener('input', evaluateRules);
+      inputElement.removeEventListener('change', evaluateRules);
+      inputElement.removeEventListener('blur', evaluateRules);
+      console.debug(`[DAP] ✅ Rule event listeners cleaned up for step: ${step.stepId}`);
+    };
+
+    // Set up rule evaluation on input change
+    let ruleMatched = false; // Prevent multiple rule matches
+    const evaluateRules = () => {
+      // Check location validity first (page navigation awareness)
+      if (step.uxExperience?.elementLocation && !this.isLocationValid(step.uxExperience.elementLocation)) {
+        console.debug(`[DAP] Rule evaluation paused - wrong location. Expected: ${step.uxExperience.elementLocation}`);
+        return;
+      }
+      
+      // Prevent multiple rule evaluations if already matched
+      if (ruleMatched) {
+        console.debug(`[DAP] Rule already matched for step ${step.stepId}, ignoring additional events`);
+        return;
+      }
+      
+      const inputValue = inputElement.value;
+      console.debug(`[DAP] Evaluating rules for input value: "${inputValue}"`);
+      
+      // Evaluate rule blocks in order - trigger FIRST satisfied rule
+      for (let i = 0; i < step.conditionRuleBlocks!.length; i++) {
+        const ruleBlock = step.conditionRuleBlocks![i];
+        if (evaluateRuleBlock(ruleBlock, inputValue)) {
+          console.debug(`[DAP] Rule matched → transitioning to flow ${ruleBlock.nextFlowId}`);
+          console.debug(`[DAP] Rule block ${i + 1} of ${step.conditionRuleBlocks!.length} triggered the transition`);
+          
+          // Mark rule as matched to prevent duplicates
+          ruleMatched = true;
+          
+          // Clean up event listeners IMMEDIATELY to prevent repeated alerts
+          cleanup();
+          
+          // Testing alert for rule evaluation success
+          alert(`🎯 FlowEngine Rule Matched!\n\nInput: "${inputValue}"\nNext Flow: ${ruleBlock.nextFlowId}\n\nRule evaluation successful!`);
+          
+          this.transitionToFlow(ruleBlock, step.stepId);
+          return;
+        }
+      }
+      
+      // If no rules matched, advance to next step in current flow
+      console.debug(`[DAP] No rules matched for input "${inputValue}", advancing to next step`);
+      console.debug(`[DAP] Current step: ${this._state.activeStep}, moving to: ${this._state.activeStep + 1}`);
+      
+      // Mark rule as processed to prevent duplicates
+      ruleMatched = true;
+      
+      // Clean up event listeners
+      cleanup();
+      
+      // Testing alert for rule not matching
+      alert(`⏭️ FlowEngine Rule Not Matched!\n\nInput: "${inputValue}"\nNo rules satisfied\n\nAdvancing to next step...`);
+      
+      // Move to next step in current flow
+      this.advanceToNextStep();
+    };
+    
+    // Attach comprehensive event listeners
+    inputElement.addEventListener('input', evaluateRules);   // Real-time typing
+    inputElement.addEventListener('change', evaluateRules);  // Value changes
+    inputElement.addEventListener('blur', evaluateRules);    // Focus loss (fallback)
+    
+    // Store cleanup function
+    this._stepTriggerListeners.set(step.stepId, cleanup);
+  }
+
+  private setupPageChangeRetry(step: EnhancedStepData): void {
+    let unsubscribeLocation: (() => void) | null = null;
+    
+    const retryOnPageChange = () => {
+      console.debug(`[DAP] Page/component changed - retrying element detection for rule step: ${step.stepId}`);
+      
+      // Clean up the current listener
+      if (unsubscribeLocation) {
+        unsubscribeLocation();
+        unsubscribeLocation = null;
+      }
+      
+      // Try to set up monitoring again
+      this.setupRuleMonitoring(step);
+    };
+
+    // Listen for page/component changes
+    unsubscribeLocation = this._locationService.subscribe(retryOnPageChange);
+    
+    // Also listen for DOM mutations (component changes within same page)
+    const observer = new MutationObserver((mutations) => {
+      // Check if significant DOM changes occurred
+      for (const mutation of mutations) {
+        if (mutation.type === 'childList' && mutation.addedNodes.length > 0) {
+          // Check if any added nodes contain our target selector
+          const addedNodes = Array.from(mutation.addedNodes);
+          for (const node of addedNodes) {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+              const element = node as Element;
+              // Check if target element is now available using resolveSelector
+              try {
+                const targetElement = resolveSelector(step.userInputSelector!);
+                if (targetElement) {
+                  console.debug(`[DAP] Target element appeared in DOM - retrying rule setup`);
+                  observer.disconnect();
+                  if (unsubscribeLocation) {
+                    unsubscribeLocation();
+                  }
+                  this.setupRuleMonitoring(step);
+                  return;
+                }
+              } catch (error) {
+                // Selector still not valid or element not found, continue observing
+                console.debug(`[DAP] Element still not available: ${error}`);
+              }
+            }
+          }
+        }
+      }
+    });
+
+    // Start observing DOM changes
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+
+    // Store observer for cleanup
+    const existingObserver = this._domObservers.get(step.stepId);
+    if (existingObserver) {
+      existingObserver.disconnect();
+    }
+    this._domObservers.set(step.stepId, observer);
+  }  /**
+   * Evaluate a rule block (DAP-standard)
+   */
+  /**
+   * Transition to next flow (DAP-standard)
+   */
+  private async transitionToFlow(ruleBlock: RuleBlock, fromStepId: string): Promise<void> {
+    console.debug(`[DAP] Current flow terminated`);
+    console.debug(`[DAP] Transitioning from step ${fromStepId} to flow ${ruleBlock.nextFlowId}`);
+    
+    // Set state to transitioning
+    this._state.executionState = 'TRANSITIONING';
+    
+    // Clean up current flow completely
+    this.cleanupCurrentStep();
+    this.abortFlow();
+    
+    try {
+      // Import flow fetching functions
+      const { fetchFlowById } = await import('../flows');
+      const config = (window as any).__DAP_CONFIG__;
+      
+      if (!config) {
+        console.error('[DAP] No config available for flow transition');
+        return;
+      }
+      
+      // Fetch and start new flow as FRESH flow
+      const flowData = await fetchFlowById(config, location.origin, ruleBlock.nextFlowId);
+      await this.startFlow(flowData);
+      
+    } catch (error) {
+      console.error(`[DAP] Failed to transition to flow ${ruleBlock.nextFlowId}:`, error);
+      this._state.executionState = 'TERMINATED';
+    }
+  }
+
+  /**
+   * Set up DOM trigger for UX step
+   */
+  private setupDOMTrigger(step: EnhancedStepData): void {
+    const ux = step.uxExperience!;
+    
+    if (!ux.elementSelector) {
+      console.warn(`[DAP] UX step ${step.stepId} has no elementSelector`);
+      this.advanceToNextStep();
+      return;
+    }
+    
+    // Wait for element to exist
+    this.waitForElement(ux.elementSelector, (element) => {
+      if (this._state.activeStepTriggered) return; // Already triggered
+      
+      const trigger = ux.elementTrigger?.toLowerCase() || 'click';
+      
+      // Use comprehensive trigger normalizer
+      const normalizedTrigger = normalizeTrigger(trigger);
+      
+      console.debug(`[DAP] Setting up trigger "${normalizedTrigger.eventType}" on ${ux.elementSelector}`);
+      
+      const triggerHandler = () => {
+        if (this._state.activeStepTriggered) return;
+        console.debug(`[DAP] Trigger fired for step: ${step.stepId}`);
+        this.triggerUXExperience(step);
+      };
+      
+      // Handle synthetic triggers (like page load)
+      if (normalizedTrigger.isSynthetic) {
+        if (normalizedTrigger.eventType === 'pageload') {
+          // Fire immediately for page load triggers
+          setTimeout(() => triggerHandler(), 0);
+        }
+      } else {
+        // Set up DOM event listener
+        element.addEventListener(normalizedTrigger.eventType, triggerHandler);
+        
+        // Store cleanup function
+        this._stepTriggerListeners.set(step.stepId, () => {
+          element.removeEventListener(normalizedTrigger.eventType, triggerHandler);
+        });
+      }
+    });
+  }
+
+  /**
+   * Trigger UX experience rendering
+   */
+  private triggerUXExperience(step: EnhancedStepData): void {
+    // Track step view when it's actually triggered/rendered
+    if (this._currentFlow) {
+      trackStepView(this._currentFlow.flowId, step.stepId).catch(error => {
+        console.debug(`[DAP] Step tracking failed: ${error.message}`);
+      });
+    }
+    
+    const ux = step.uxExperience!;
+    
+    // Import and use experience renderer
+    import('../experiences/registry').then(({ getRenderer }) => {
+      const experienceType = ux.uxExperienceType.toLowerCase();
+      // Route microsurvey to the unified survey system
+      const rendererType = experienceType === 'microsurvey' ? 'survey' : experienceType;
+      const renderer = getRenderer(rendererType);
+      
+      if (!renderer) {
+        console.error(`[DAP] No renderer found for: ${ux.uxExperienceType}`);
+        this.advanceToNextStep();
+        return;
+      }
+      
+      // Create proper payload based on experience type
+      let payload: any;
+      
+      if (experienceType === 'modal') {
+        // Transform modal content from API format to renderer format
+        let bodyContent: any[] = [];
+        
+        if (ux.modalContent) {
+          const modalContent = ux.modalContent;
+          const contentType = modalContent.contentType?.toLowerCase();
+          
+          switch (contentType) {
+            case 'text':
+              bodyContent.push({
+                kind: 'text',
+                html: modalContent.contentData || modalContent.presignedUrl || ''
+              });
+              break;
+              
+            case 'link':
+              bodyContent.push({
+                kind: 'link',
+                href: modalContent.contentData || modalContent.presignedUrl || '',
+                label: modalContent.contentName || 'Link'
+              });
+              break;
+              
+            case 'image':
+              bodyContent.push({
+                kind: 'image',
+                url: modalContent.presignedUrl || modalContent.contentData || '',
+                alt: modalContent.contentDescription || modalContent.contentName || 'Image'
+              });
+              break;
+              
+            case 'video':
+              bodyContent.push({
+                kind: 'video',
+                sources: [{ src: modalContent.presignedUrl || modalContent.contentData || '' }]
+              });
+              break;
+              
+            case 'youtube':
+              bodyContent.push({
+                kind: 'youtube',
+                href: modalContent.contentData || modalContent.presignedUrl || '',
+                title: modalContent.contentName,
+                thumbnail: modalContent.contentDescription
+              });
+              break;
+              
+            case 'article':
+              bodyContent.push({
+                kind: 'article',
+                url: modalContent.presignedUrl || modalContent.contentData || '',
+                fileName: modalContent.contentName,
+                mime: modalContent.mime || 'application/pdf'
+              });
+              break;
+
+              case 'knowledgebase':
+                // Map server KB items to renderer-friendly KB items
+                try {
+                  const raw = Array.isArray(modalContent.contentData) ? modalContent.contentData : [];
+                  const items = raw.map((it: any) => ({
+                    url: it?.presignedUrl || it?.contentData || '',
+                    title: it?.contentName || it?.contentTitle || '',
+                    description: it?.contentDescription || it?.description || '',
+                    fileName: it?.contentData || undefined
+                  })).filter((i: any) => i.url && i.title);
+
+                  bodyContent.push({
+                    kind: 'kb',
+                    title: modalContent.contentName || ux.content?.header || 'Knowledge Base',
+                    items
+                  });
+                } catch (e) {
+                  console.warn('[DAP] Failed to normalize KnowledgeBase modalContent:', e, modalContent);
+                  // fallback to default behavior below
+                  bodyContent.push({
+                    kind: 'text',
+                    html: modalContent.contentData || modalContent.contentDescription || ux.content?.body || ''
+                  });
+                }
+                break;
+              
+            default:
+              // Fallback to text content
+              bodyContent.push({
+                kind: 'text',
+                html: modalContent.contentData || modalContent.contentDescription || ux.content?.body || ''
+              });
+          }
+        } else if (ux.content?.body) {
+          // If no modalContent but has body text, use that
+          bodyContent.push({
+            kind: 'text',
+            html: ux.content.body
+          });
+        }
+        
+        payload = {
+          title: ux.content?.header,
+          body: bodyContent,
+          footerText: ux.content?.footer,
+          theme: {},
+          _completionTracker: {
+            onComplete: () => {
+              console.debug(`[DAP] UX experience completed for step: ${step.stepId}`);
+              
+              // Only advance if this step is still the active step (prevent race conditions)
+              if (this._state.activeStep < this._currentFlow!.steps.length && 
+                  this._currentFlow!.steps[this._state.activeStep].stepId === step.stepId) {
+                this.advanceToNextStep();
+              } else {
+                console.debug(`[DAP] Step ${step.stepId} is no longer active, skipping advancement`);
+              }
+            }
+          }
+        };
+      } else if (experienceType === 'tooltip') {
+        payload = {
+          targetSelector: ux.elementSelector,
+          text: ux.content?.text || ux.content?.body || 'Tooltip',
+          placement: ux.content?.placement || 'auto',
+          trigger: 'hover', // Ensure trigger is set correctly
+          stepId: step.stepId,
+          _completionTracker: {
+            onComplete: () => {
+              console.debug(`[DAP] UX experience completed for step: ${step.stepId}`);
+              this.advanceToNextStep();
+            }
+          }
+        };
+      } else if (experienceType === 'popover') {
+        payload = {
+          targetSelector: ux.elementSelector,
+          title: ux.content?.title || ux.content?.header,
+          body: ux.content?.body,
+          placement: ux.content?.placement || 'auto',
+          trigger: ux.elementTrigger || ux.content?.trigger || 'click',
+          showArrow: ux.content?.showArrow !== false,
+          stepId: step.stepId,
+          _completionTracker: {
+            onComplete: () => {
+              console.debug(`[DAP] UX experience completed for step: ${step.stepId}`);
+              this.advanceToNextStep();
+            }
+          }
+        };
+      } else if (experienceType === 'survey') {
+        payload = {
+          targetSelector: ux.elementSelector,
+          questions: ux.content?.questions || [],
+          header: ux.content?.header,
+          body: ux.content?.body,
+          stepId: step.stepId,
+          _completionTracker: {
+            onComplete: () => {
+              console.debug(`[DAP] UX experience completed for step: ${step.stepId}`);
+              this.advanceToNextStep();
+            }
+          }
+        };
+      } else if (experienceType === 'beacon') {
+        // Map position from backend format {x: "center", y: "center"} to string format
+        let positionString = 'top-right'; // default
+        if (ux.position) {
+          const { x, y } = ux.position;
+          if (x === 'center' && y === 'center') {
+            positionString = 'center';
+          } else if (y === 'top' && x === 'left') {
+            positionString = 'top-left';
+          } else if (y === 'top' && x === 'right') {
+            positionString = 'top-right';
+          } else if (y === 'bottom' && x === 'left') {
+            positionString = 'bottom-left';
+          } else if (y === 'bottom' && x === 'right') {
+            positionString = 'bottom-right';
+          }
+        }
+
+        payload = {
+          title: ux.content?.title || ux.content?.header,
+          body: ux.content?.body || ux.content?.tooltipText,
+          icon: ux.content?.icon,
+          position: positionString,
+          autoDismiss: ux.content?.autoDismiss,
+          action: ux.content?.action,
+          targetSelector: ux.elementSelector, // Add target selector for element-relative positioning
+          trigger: ux.elementTrigger || 'click',
+          beaconStyles: {
+            enabled: true,
+            color1: ux.content?.color || '#f59e0b',
+            color2: ux.content?.color2 || ux.content?.color || '#eab308',
+            duration: ux.content?.blinkRateMs ? `${ux.content.blinkRateMs / 1000}s` : '2s',
+            ...ux.content?.beaconStyles
+          },
+          stepId: step.stepId,
+          _completionTracker: {
+            onComplete: () => {
+              console.debug(`[DAP] UX experience completed for step: ${step.stepId}`);
+              this.advanceToNextStep();
+            }
+          }
+        };
+      } else if (experienceType === 'microsurvey') {
+        // MicroSurvey is now handled by the unified survey system
+        // Determine if this should be inline or modal based on content
+        const hasMultipleQuestions = ux.content?.questions && ux.content.questions.length > 1;
+        const hasComplexQuestions = ux.content?.questions?.some((q: any) => 
+          ['OpinionScaleChoice', 'NpsScale', 'NpsOptions', 'StarChoice'].includes(q.type)
+        );
+        const shouldUseModal = hasMultipleQuestions || hasComplexQuestions;
+        
+        console.debug(`[DAP] MicroSurvey mode detection:`, {
+          questionsCount: ux.content?.questions?.length || 0,
+          hasMultipleQuestions,
+          hasComplexQuestions,
+          shouldUseModal,
+          finalMode: shouldUseModal ? 'modal' : 'inline'
+        });
+        
+        payload = {
+          // Include both single question fields (for simple micro surveys)
+          question: ux.content?.question || ux.content?.title || ux.content?.header,
+          type: ux.content?.type || 'choice',
+          options: ux.content?.options,
+          placeholder: ux.content?.placeholder,
+          submitText: ux.content?.submitText,
+          cancelText: ux.content?.cancelText,
+          rating: ux.content?.rating,
+          
+          // Include full survey fields (for complex surveys)
+          header: ux.content?.header,
+          body: ux.content?.body,
+          questions: ux.content?.questions,
+          
+          // Positioning and behavior
+          targetSelector: ux.elementSelector,
+          position: ux.content?.position || 'center',
+          mode: shouldUseModal ? 'modal' : 'inline', // Smart mode detection
+          
+          // Survey submission fields
+          flowId: this._state.activeFlowId,
+          stepId: step.stepId,
+          _completionTracker: {
+            onComplete: () => {
+              console.debug(`[DAP] UX experience completed for step: ${step.stepId}`);
+              this.advanceToNextStep();
+            }
+          }
+        };
+      } else {
+        // Fallback - use modalSequence format
+        payload = {
+          steps: [{
+            stepId: step.stepId,
+            kind: experienceType,
+            [experienceType]: {
+              ...ux.content,
+              stepId: step.stepId
+            },
+            title: ux.content?.header || ux.content?.title || 'Info',
+            elementSelector: ux.elementSelector,
+            elementTrigger: ux.elementTrigger,
+            elementLocation: ux.elementLocation
+          }],
+          _completionTracker: {
+            onComplete: () => {
+              console.debug(`[DAP] UX experience completed for step: ${step.stepId}`);
+              this.advanceToNextStep();
+            }
+          }
+        };
+      }
+      
+      // Create flow structure for renderer
+      const flowForRenderer = {
+        id: `step-${step.stepId}`,
+        type: experienceType,
+        payload
+      };
+      
+      console.debug(`[DAP] Rendering ${experienceType} experience:`, flowForRenderer);
+      console.debug(`[DAP] Payload structure:`, {
+        type: experienceType,
+        targetSelector: payload.targetSelector,
+        trigger: payload.trigger,
+        elementSelector: ux.elementSelector,
+        elementTrigger: ux.elementTrigger
+      });
+      
+      // Normalize flow format based on experience type
+      if (experienceType === 'tooltip') {
+        // Ensure tooltip has proper trigger format
+        flowForRenderer.payload.trigger = payload.trigger || 'hover';
+        flowForRenderer.payload.targetSelector = payload.targetSelector || ux.elementSelector;
+      } else if (experienceType === 'popover') {
+        // Ensure popover has proper trigger format  
+        flowForRenderer.payload.trigger = payload.trigger || 'click';
+        flowForRenderer.payload.targetSelector = payload.targetSelector || ux.elementSelector;
+      } else if (experienceType === 'modal') {
+        // Modal doesn't need target selector normalization
+        console.debug(`[DAP] Modal content transformation:`, {
+          originalModalContent: ux.modalContent,
+          transformedBody: payload.body || payload.bodyBlocks,
+          contentType: ux.modalContent?.contentType
+        });
+      }
+      
+      renderer(flowForRenderer);
+      
+    }).catch(err => {
+      console.error('[DAP] Error loading experience renderer:', err);
+      this.advanceToNextStep();
+    });
+  }
+
+  /**
+   * Advance to next step intelligently (respects triggers)
+   */
+  private advanceToNextStep(): void {
+    // Prevent concurrent step advancement
+    if (this._state.stepAdvancing) {
+      return;
+    }
+    
+    this._state.stepAdvancing = true;
+    this.cleanupCurrentStep();
+    
+    this._state.activeStep++;
+    this._state.activeStepTriggered = false;
+    
+    console.debug(`[DAP] Advanced to step ${this._state.activeStep}`);
+    
+    // Check if we have more steps
+    if (this._currentFlow && this._state.activeStep < this._currentFlow.steps.length) {
+      const nextStep = this._currentFlow.steps[this._state.activeStep];
+      const nextStepTrigger = triggerManager.resolveTrigger(nextStep);
+      
+      if (nextStepTrigger) {        
+        // Set up the trigger and wait
+        this.executeStepWithTrigger(nextStep, this._state.activeStep);
+        
+        this._state.stepAdvancing = false;
+        return;
+      } else {
+        console.debug(`[DAP] Next step ${nextStep.stepId} has no trigger - executing immediately`);
+      }
+    } else {
+      console.debug(`[DAP] No more steps, flow completed`);
+      this._state.stepAdvancing = false;
+      this.completeFlow();
+      return;
+    }
+    
+    this._state.stepAdvancing = false;
+    // Continue execution for steps without triggers
+    this.executeStep();
+  }
+
+  /**
+   * Complete current flow
+   */
+  private completeFlow(): void {
+    console.debug(`[DAP] Flow completed: ${this._state.activeFlowId}`);
+    this.abortFlow();
+  }
+
+  /**
+   * Redirect to another flow
+   */
+  private async redirectToFlow(nextFlowId: string): Promise<void> {
+    console.debug(`[DAP] Redirecting to flow: ${nextFlowId}`);
+    
+    try {
+      // Import flow fetching functions
+      const { fetchFlowById } = await import('../flows');
+      const config = (window as any).__DAP_CONFIG__;
+      
+      if (!config) {
+        console.error('[DAP] No config available for flow redirect');
+        return;
+      }
+      
+      const flowData = await fetchFlowById(config, location.origin, nextFlowId);
+      this.startFlow(flowData);
+      
+    } catch (err) {
+      console.error(`[DAP] Failed to redirect to flow ${nextFlowId}:`, err);
+    }
+  }
+
+  /**
+   * Clean up current step listeners and state
+   */
+  private cleanupCurrentStep(): void {
+    // Only clean up trigger listeners for the CURRENT step, not all listeners
+    if (this._currentFlow && this._state.activeStep < this._currentFlow.steps.length) {
+      const currentStep = this._currentFlow.steps[this._state.activeStep];
+      if (currentStep) {
+        // Remove only this step's listeners
+        triggerManager.removeTriggerListeners(currentStep.stepId);
+        
+        // Clean up legacy listeners for this step
+        const cleanup = this._stepTriggerListeners.get(currentStep.stepId);
+        if (cleanup) {
+          cleanup();
+          this._stepTriggerListeners.delete(currentStep.stepId);
+        }
+      }
+    }
+
+    // Clean up DOM observers for current step only
+    if (this._currentFlow && this._state.activeStep < this._currentFlow.steps.length) {
+      const currentStep = this._currentFlow.steps[this._state.activeStep];
+      if (currentStep) {
+        const observer = this._domObservers.get(currentStep.stepId);
+        if (observer) {
+          observer.disconnect();
+          this._domObservers.delete(currentStep.stepId);
+        }
+      }
+    }
+  }
+
+  /**
+   * Check if flow can resume after page change
+   */
+  private checkFlowResumption(): void {
+    if (!this._state.flowInProgress || !this._currentFlow) return;
+    
+    console.debug('[DAP] Checking if current step can resume after page change');
+    
+    // Re-execute current step (will check location requirements)
+    this.executeStep();
+  }
+
+  /**
+   * Check if current location matches step requirement
+   */
+  private matchesLocation(elementLocation: string, context: any): boolean {
+    if (!elementLocation) return true;
+    
+    const normalizedRequired = elementLocation.replace(/^\/+/, '').toLowerCase();
+    const normalizedCurrent = (context.currentPath || '').replace(/^\/+/, '').toLowerCase();
+    const normalizedScreen = (context.screenId || '').replace(/^\/+/, '').toLowerCase();
+    
+    return normalizedRequired === normalizedCurrent || 
+           normalizedRequired === normalizedScreen ||
+           normalizedRequired === '*';
+  }
+
+  /**
+   * Wait for element to exist in DOM
+   */
+  private waitForElement(selector: string, callback: (element: Element) => void): void {
+    const check = () => {
+      const element = resolveSelector(selector);
+      if (element) {
+        callback(element);
+      } else {
+        setTimeout(check, 100); // Retry every 100ms
+      }
+    };
+    check();
+  }
+
+  /**
+   * Check if current page location allows rule evaluation
+   */
+  private isLocationValid(elementLocation?: string): boolean {
+    if (!elementLocation) return true; // No location restriction
+    
+    const currentContext = this._locationService.getContext();
+    const currentPath = currentContext.currentPath;
+    
+    // Simple path matching - can be enhanced for more complex location rules
+    return currentPath.includes(elementLocation) || elementLocation === 'dashboard';
+  }
+
+  /**
+   * Get current flow state for debugging
+   */
+  public getState() {
+    return {
+      ...this._state,
+      currentFlow: this._currentFlow?.flowId,
+      currentStepId: this._currentFlow?.steps[this._state.activeStep]?.stepId
+    };
+  }
+
+  /**
+   * Clean up resources and page context subscriptions
+   */
+  public destroy(): void {
+    console.debug('[DAP] FlowEngine: Destroying...');
+    
+    // Clean up current flow state
+    this.cleanupCurrentStep();
+    this._state = {
+      activeFlowId: null,
+      flowInProgress: false,
+      activeStep: 0,
+      activeStepTriggered: false,
+      executionState: 'TERMINATED',
+      executionMode: 'Linear',
+      triggeredSteps: new Set()
+    };
+    this._currentFlow = null;
+    
+    // Clean up page change subscription
+    if (this._pageChangeUnsubscribe) {
+      this._pageChangeUnsubscribe();
+      this._pageChangeUnsubscribe = null;
+    }
+    
+    // Clean up trigger manager
+    triggerManager.destroy();
+    
+    // Clean up page context service
+    pageContextService.destroy();
+    
+    console.debug('[DAP] FlowEngine: Destroyed');
+  }
+
+  /**
+   * Analyze flow page context to detect multi-page flows
+   */
+  private analyzeFlowPageContext(flowData: FlowData): void {
+    console.log(`[DAP] 📄 FLOW PAGE CONTEXT ANALYSIS: ${flowData.flowId}`);
+    console.log(`[DAP] ================================================================`);
+
+    const currentPage = pageContextService.getCurrentContext();
+    const selectors = new Set<string>();
+    const elementLocations = new Set<string>();
+    let selectorMismatches = 0;
+    let possibleMultiPage = false;
+
+    // Collect all selectors and element locations
+    for (const step of flowData.steps) {
+      // Check trigger selectors
+      if (step.trigger?.conditions) {
+        step.trigger.conditions.forEach(condition => {
+          if (condition.selector) {
+            selectors.add(condition.selector);
+          }
+        });
+      }
+
+      // Check UX experience selectors
+      if (step.uxExperience?.elementSelector) {
+        selectors.add(step.uxExperience.elementSelector);
+      }
+
+      // Check user input selectors (important for rule-based steps)
+      if (step.userInputSelector) {
+        selectors.add(step.userInputSelector);
+      }
+
+      // Check element locations
+      if (step.uxExperience?.elementLocation) {
+        elementLocations.add(step.uxExperience.elementLocation);
+      }
+    }
+
+    console.log(`[DAP] Total unique selectors in flow: ${selectors.size}`);
+    console.log(`[DAP] Element locations: ${Array.from(elementLocations).join(', ') || 'none specified'}`);
+
+    // Check if selectors exist on current page
+    for (const selector of selectors) {
+      try {
+        const elements = resolveSelectorAll(selector);
+        if (elements.length === 0) {
+          selectorMismatches++;
+          console.warn(`[DAP] ⚠️ Selector not found on current page: ${selector}`);
+        } else {
+          console.debug(`[DAP] ✅ Selector found (${elements.length} elements): ${selector}`);
+        }
+      } catch (error) {
+        selectorMismatches++;
+        console.warn(`[DAP] ⚠️ Invalid selector: ${selector}`, error);
+      }
+    }
+
+    // Determine if this might be a multi-page flow
+    if (selectorMismatches > 0) {
+      possibleMultiPage = true;
+      const missPercentage = Math.round((selectorMismatches / selectors.size) * 100);
+      console.warn(`[DAP] 🚨 ${selectorMismatches}/${selectors.size} (${missPercentage}%) selectors not found on current page`);
+      console.warn(`[DAP] This suggests a multi-page flow or cross-page navigation issue`);
+    }
+
+    // Check execution mode and provide recommendations
+    const executionMode = flowData.execution?.mode || 'Linear';
+    console.log(`[DAP] Flow execution mode: ${executionMode}`);
+    
+    if (possibleMultiPage && executionMode === 'Linear') {
+      console.warn(`[DAP] 💡 Recommendation: Consider enabling multiPage support for this flow`);
+      console.warn(`[DAP] Some steps may wait indefinitely for elements on other pages`);
+    }
+
+    console.log(`[DAP] Current page: ${currentPage?.pathname || 'unknown'}`);
+    console.log(`[DAP] ================================================================`);
+  }
+
+  /**
+   * Analyze rule-based steps for page context issues
+   */
+  private analyzeRuleStepsPageContext(ruleSteps: EnhancedStepData[]): void {
+    console.log(`[DAP] 🤖 RULE STEPS PAGE CONTEXT ANALYSIS`);
+    console.log(`[DAP] ================================================================`);
+
+    const currentPage = pageContextService.getCurrentContext();
+
+    for (const step of ruleSteps) {
+      console.log(`[DAP] Rule step ${step.stepId}:`);
+      
+      // Check trigger selector
+      const triggerSelectors = step.trigger?.conditions?.map(c => c.selector).filter(Boolean) || [];
+      console.log(`[DAP]   Trigger selectors: ${triggerSelectors.length}`);
+      
+      for (const selector of triggerSelectors) {
+        if (selector) {
+          const elements = resolveSelectorAll(selector);
+          if (elements.length === 0) {
+            console.error(`[DAP]   ❌ CRITICAL: Rule trigger selector not found: ${selector}`);
+            console.error(`[DAP]   This rule-based step will wait indefinitely!`);
+          } else {
+            console.debug(`[DAP]   ✅ Trigger selector found: ${selector}`);
+          }
+        }
+      }
+
+      // Check user input selector (critical for rule evaluation)
+      if (step.userInputSelector) {
+        const inputElements = resolveSelectorAll(step.userInputSelector);
+        if (inputElements.length === 0) {
+          console.error(`[DAP]   ❌ CRITICAL: Rule input selector not found: ${step.userInputSelector}`);
+          console.error(`[DAP]   Rule condition evaluation will fail!`);
+          console.error(`[DAP]   Possible cross-page navigation issue detected.`);
+        } else {
+          console.debug(`[DAP]   ✅ Input selector found: ${step.userInputSelector}`);
+        }
+      }
+
+      // Check rule block selectors
+      if (step.conditionRuleBlocks) {
+        for (let i = 0; i < step.conditionRuleBlocks.length; i++) {
+          const ruleBlock = step.conditionRuleBlocks[i];
+          if (ruleBlock.selector) {
+            const ruleElements = resolveSelectorAll(ruleBlock.selector);
+            if (ruleElements.length === 0) {
+              console.warn(`[DAP]   ⚠️ Rule block ${i} selector not found: ${ruleBlock.selector}`);
+            }
+          }
+        }
+      }
+    }
+
+    console.log(`[DAP] ================================================================`);
+  }
+
+  /**
+   * Analyze and log trigger usage for the entire flow
+   * This helps identify which steps use step-level vs element-level triggers
+   */
+  private analyzeTriggerUsage(flowData: FlowData): void {
+    console.log(`[DAP] 📊 TRIGGER USAGE ANALYSIS FOR FLOW: ${flowData.flowId}`);
+    console.log(`[DAP] ================================================================`);
+    
+    let stepLevelCount = 0;
+    let elementLevelCount = 0;
+    let noTriggerCount = 0;
+    let ruleBasedCount = 0;
+    
+    for (const step of flowData.steps) {
+      const hasStepTrigger = step.trigger && step.trigger.conditions && step.trigger.conditions.length > 0;
+      const hasElementTrigger = step.uxExperience?.elementTrigger;
+      const hasRuleBlocks = step.conditionRuleBlocks && step.conditionRuleBlocks.length > 0;
+      
+      if (hasStepTrigger) {
+        stepLevelCount++;
+        const triggerType = `${step.trigger?.conditions?.[0]?.kind}-${step.trigger?.conditions?.[0]?.event}`;
+        
+        if (hasRuleBlocks) {
+          console.log(`[DAP] 🤖 Step ${step.stepId}: STEP-LEVEL trigger (${triggerType}) + RULE-BASED decision`);
+          ruleBasedCount++;
+        } else {
+          console.log(`[DAP] ✅ Step ${step.stepId}: STEP-LEVEL trigger (${triggerType}) + UX experience`);
+        }
+        
+        if (hasElementTrigger) {
+          console.log(`[DAP]    └── ⚠️  elementTrigger "${step.uxExperience?.elementTrigger}" will be IGNORED`);
+        }
+        
+      } else if (hasElementTrigger) {
+        elementLevelCount++;
+        console.warn(`[DAP] ⚠️  Step ${step.stepId}: ELEMENT-LEVEL trigger "${step.uxExperience?.elementTrigger}" (LEGACY)`);
+        console.warn(`[DAP]    └── 🚨 This will BREAK when element-level triggers are removed!`);
+        
+      } else {
+        noTriggerCount++;
+        console.error(`[DAP] ❌ Step ${step.stepId}: NO TRIGGER - will execute immediately`);
+      }
+    }
+    
+    console.log(`[DAP] ================================================================`);
+    console.log(`[DAP] 📊 SUMMARY:`);
+    console.log(`[DAP]    ✅ Step-level triggers: ${stepLevelCount}`);
+    console.log(`[DAP]    ⚠️  Element-level triggers: ${elementLevelCount}`);
+    console.log(`[DAP]    ❌ No triggers: ${noTriggerCount}`);
+    console.log(`[DAP]    🤖 Rule-based decision steps: ${ruleBasedCount}`);
+    console.log(`[DAP] ================================================================`);
+    
+    if (elementLevelCount > 0) {
+      console.warn(`[DAP] 🚨 WARNING: ${elementLevelCount} steps use element-level triggers!`);
+      console.warn(`[DAP]    These will BREAK when element-level support is removed.`);
+      console.warn(`[DAP]    Please migrate to step-level triggers.`);
+    }
+    
+    if (noTriggerCount > 0) {
+      console.error(`[DAP] 🚨 ERROR: ${noTriggerCount} steps have no triggers!`);
+      console.error(`[DAP]    These steps will execute immediately without user interaction.`);
+    }
+    
+    if (stepLevelCount === flowData.steps.length) {
+      console.log(`[DAP] 🎉 PERFECT! All steps use step-level triggers. Ready for element-level trigger removal.`);
+    }
+  }
+}
+
+// Export singleton
+export const flowEngine = FlowEngine.getInstance();