chrometools-mcp 1.8.2 → 2.2.0

package/recorder/scenario-executor.js

@@ -1,946 +1,970 @@
-/**
- * recorder/scenario-executor.js
- *
- * Executes recorded scenarios with:
- * 1. Action playback with error handling
- * 2. Parameter substitution
- * 3. Secret injection
- * 4. Dependency resolution and chaining
- * 5. Retry logic with fallback selectors
- */
-
-import { resolveDependencies, checkDependencyCondition } from './dependency-resolver.js';
-import { loadScenario, loadSecrets, loadIndex } from './scenario-storage.js';
-
-/**
- * Execute scenario with dependencies
- * @param {string} scenarioName - Scenario to execute
- * @param {Object} page - Puppeteer page instance
- * @param {Object} params - Parameters for scenario
- * @param {Object} options - Execution options { executeDependencies, skipConditions, maxRetries, timeout, baseDir }
- * @returns {Object} - Execution result
- */
-export async function executeScenario(scenarioName, page, params = {}, options = {}) {
-  const {
-    executeDependencies = true,  // NEW: Execute dependencies by default
-    skipConditions = false,
-    maxRetries = 3,
-    timeout = 30000,
-    baseDir  // Base directory for scenarios
-  } = options;
-
-  const result = {
-    success: false,
-    scenarioName,
-    executedScenarios: [],
-    errors: [],
-    outputs: {},
-    duration: 0
-  };
-
-  const startTime = Date.now();
-
-  try {
-    // Load scenario index
-    const path = await import('path');
-    const scenariosDir = path.join(baseDir, 'scenarios');
-    const scenarioIndex = await loadIndex(scenariosDir);
-
-    let chain = [scenarioName]; // Default: execute only the requested scenario
-
-    // Resolve and execute dependencies if enabled
-    if (executeDependencies) {
-      const resolution = resolveDependencies(scenarioName, scenarioIndex, { skipConditions });
-
-      if (resolution.errors.length > 0) {
-        result.errors.push(...resolution.errors);
-        return result;
-      }
-
-      chain = resolution.chain; // Use full dependency chain
-    }
-
-    // Execute chain in order
-    for (const name of chain) {
-      const scenario = await loadScenario(name, false, baseDir);
-      if (!scenario) {
-        result.errors.push(`Scenario "${name}" not found`);
-        return result;
-      }
-
-      // Check dependency conditions
-      if (scenario.metadata?.dependencies) {
-        for (const dep of scenario.metadata.dependencies) {
-          if (dep.condition) {
-            const context = { page, variables: params };
-            const shouldExecute = await checkDependencyCondition(dep.condition, context);
-
-            if (!shouldExecute) {
-              console.log(`Skipping scenario "${name}" due to condition`);
-              continue;
-            }
-          }
-        }
-      }
-
-      // Load secrets
-      const secretsDir = path.join(baseDir, 'secrets');
-      const secrets = await loadSecrets(name, secretsDir);
-
-      // Merge secrets with params
-      const executionParams = { ...params, ...secrets };
-
-      // Execute scenario
-      const scenarioResult = await executeSingleScenario(scenario, page, executionParams, {
-        maxRetries,
-        timeout
-      });
-
-      result.executedScenarios.push(name);
-
-      if (!scenarioResult.success) {
-        result.errors.push(...scenarioResult.errors);
-        return result;
-      }
-
-      // Collect outputs for next scenarios
-      if (scenarioResult.outputs) {
-        Object.assign(result.outputs, scenarioResult.outputs);
-        Object.assign(params, scenarioResult.outputs);
-      }
-    }
-
-    result.success = true;
-  } catch (error) {
-    result.errors.push(`Execution failed: ${error.message}`);
-  } finally {
-    result.duration = Date.now() - startTime;
-  }
-
-  return result;
-}
-
-/**
- * Execute single scenario (without dependencies)
- * @param {Object} scenario - Scenario data
- * @param {Object} page - Puppeteer page
- * @param {Object} params - Parameters
- * @param {Object} options - Options
- * @returns {Object} - Execution result
- */
-async function executeSingleScenario(scenario, page, params = {}, options = {}) {
-  const { maxRetries = 3, timeout = 30000 } = options;
-
-  const result = {
-    success: false,
-    errors: [],
-    outputs: {},
-    actionResults: []
-  };
-
-  try {
-    for (const action of scenario.chain) {
-      // Substitute parameters in action
-      const resolvedAction = substituteParameters(action, params);
-
-      // Execute action with retry
-      const actionResult = await executeActionWithRetry(
-        resolvedAction,
-        page,
-        maxRetries,
-        timeout
-      );
-
-      result.actionResults.push(actionResult);
-
-      if (!actionResult.success) {
-        result.errors.push(`Action failed: ${actionResult.error}`);
-        return result;
-      }
-
-      // Store outputs if action produces any
-      if (actionResult.output) {
-        Object.assign(result.outputs, actionResult.output);
-      }
-    }
-
-    // Validate final URL if exitUrl is specified in metadata
-    if (scenario.metadata?.exitUrl) {
-      const currentUrl = page.url();
-      const expectedUrl = scenario.metadata.exitUrl;
-
-      // Normalize URLs for comparison (remove trailing slashes, fragments)
-      const normalizeUrl = (url) => {
-        try {
-          const parsed = new URL(url);
-          // Remove fragment and trailing slash
-          return `${parsed.origin}${parsed.pathname.replace(/\/$/, '')}${parsed.search}`;
-        } catch {
-          return url.replace(/\/$/, '');
-        }
-      };
-
-      const normalizedCurrent = normalizeUrl(currentUrl);
-      const normalizedExpected = normalizeUrl(expectedUrl);
-
-      if (normalizedCurrent !== normalizedExpected) {
-        result.errors.push(
-          `❌ URL Validation Failed\n\n` +
-          `Expected final URL: ${expectedUrl}\n` +
-          `Actual final URL:   ${currentUrl}\n\n` +
-          `The scenario ended on a different page than expected.\n` +
-          `This may indicate:\n` +
-          `  - Navigation flow has changed\n` +
-          `  - An action failed silently\n` +
-          `  - Page redirected unexpectedly\n\n` +
-          `💡 Suggestion: Check if the page flow or redirects have changed since recording.`
-        );
-        return result;
-      }
-
-      // URL validation passed
-      result.urlValidation = {
-        success: true,
-        expectedUrl,
-        actualUrl: currentUrl
-      };
-    }
-
-    result.success = true;
-  } catch (error) {
-    result.errors.push(`Scenario execution error: ${error.message}`);
-  }
-
-  return result;
-}
-
-/**
- * Execute action with retry and fallback selectors
- */
-async function executeActionWithRetry(action, page, maxRetries, timeout) {
-  const result = {
-    success: false,
-    action: action.type,
-    error: null,
-    errorDetails: {
-      attempts: [],
-      selector: action.selector?.value || action.selector?.primary,
-      context: null
-    },
-    output: null,
-    attempts: 0
-  };
-
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    result.attempts = attempt;
-    const attemptInfo = {
-      number: attempt,
-      selector: action.selector?.value || action.selector?.primary,
-      error: null,
-      timestamp: new Date().toISOString()
-    };
-
-    try {
-      // Execute action based on type
-      const actionResult = await executeAction(action, page, timeout);
-
-      result.success = true;
-      result.output = actionResult.output;
-      attemptInfo.success = true;
-      result.errorDetails.attempts.push(attemptInfo);
-      return result;
-    } catch (error) {
-      attemptInfo.error = error.message;
-      attemptInfo.success = false;
-
-      // Capture page context for error reporting
-      if (attempt === maxRetries) {
-        try {
-          result.errorDetails.context = await capturePageContext(page, action);
-        } catch (contextError) {
-          console.error('Failed to capture page context:', contextError);
-        }
-      }
-
-      result.errorDetails.attempts.push(attemptInfo);
-      result.error = error.message;
-
-      // If this is a selector error and we have fallbacks, try them
-      if (action.selector?.fallbacks && action.selector.fallbacks.length > 0) {
-        const fallback = action.selector.fallbacks[0];
-        console.log(`[Retry ${attempt}] Trying fallback selector: ${fallback}`);
-
-        action.selector.value = fallback;
-        action.selector.fallbacks = action.selector.fallbacks.slice(1);
-        continue;
-      }
-
-      // If we have element description, try smartFindElement
-      if (action.selector?.elementInfo?.text && attempt < maxRetries) {
-        console.log(`[Retry ${attempt}] Selector failed, trying smartFindElement with description: ${action.selector.elementInfo.text}`);
-
-        try {
-          // Inject element finder utilities if not already done
-          await page.evaluate(elementFinderUtilsCode);
-
-          const smartResult = await page.evaluate((description) => {
-            return window.smartFindElement({ description, maxResults: 3 });
-          }, action.selector.elementInfo.text);
-
-          if (smartResult.candidates && smartResult.candidates.length > 0) {
-            action.selector.value = smartResult.candidates[0].selector;
-            action.selector.fallbacks = smartResult.candidates.slice(1).map(c => c.selector);
-            console.log(`[Retry ${attempt}] Found alternative selector: ${action.selector.value}`);
-            continue;
-          }
-        } catch (smartError) {
-          console.error('[Retry] smartFindElement failed:', smartError.message);
-        }
-      }
-
-      // Last attempt failed
-      if (attempt === maxRetries) {
-        // Create comprehensive error message
-        result.error = formatDetailedError(action, result.errorDetails);
-        return result;
-      }
-
-      // Wait before retry
-      await new Promise(resolve => setTimeout(resolve, 1000));
-    }
-  }
-
-  return result;
-}
-
-/**
- * Capture page context for error reporting
- */
-async function capturePageContext(page, action) {
-  try {
-    const context = {
-      url: page.url(),
-      title: await page.title(),
-      elementExists: false,
-      elementVisible: false,
-      elementInfo: null,
-      pageState: null
-    };
-
-    const selector = action.selector?.value || action.selector?.primary;
-
-    if (selector) {
-      // Check if element exists
-      context.elementExists = await page.evaluate((sel) => {
-        return document.querySelector(sel) !== null;
-      }, selector);
-
-      // If exists, check visibility and get info
-      if (context.elementExists) {
-        context.elementInfo = await page.evaluate((sel) => {
-          const el = document.querySelector(sel);
-          const rect = el.getBoundingClientRect();
-          const styles = window.getComputedStyle(el);
-
-          return {
-            tagName: el.tagName,
-            id: el.id,
-            className: el.className,
-            visible: rect.width > 0 && rect.height > 0 && styles.display !== 'none' && styles.visibility !== 'hidden',
-            disabled: el.disabled || el.getAttribute('aria-disabled') === 'true',
-            readonly: el.readOnly || el.getAttribute('aria-readonly') === 'true',
-            position: {
-              top: rect.top,
-              left: rect.left,
-              width: rect.width,
-              height: rect.height
-            },
-            styles: {
-              display: styles.display,
-              visibility: styles.visibility,
-              opacity: styles.opacity,
-              pointerEvents: styles.pointerEvents
-            }
-          };
-        }, selector);
-
-        context.elementVisible = context.elementInfo.visible;
-      }
-    }
-
-    // Get page state
-    context.pageState = await page.evaluate(() => {
-      return {
-        readyState: document.readyState,
-        hasModals: document.querySelector('[role="dialog"], .modal, .popup') !== null,
-        hasOverlays: document.querySelector('.overlay, .backdrop') !== null,
-        activeElement: document.activeElement ? {
-          tagName: document.activeElement.tagName,
-          id: document.activeElement.id,
-          className: document.activeElement.className
-        } : null
-      };
-    });
-
-    return context;
-  } catch (error) {
-    return { error: error.message };
-  }
-}
-
-/**
- * Format detailed error message for AI agent
- */
-function formatDetailedError(action, errorDetails) {
-  const parts = [
-    `❌ Action "${action.type}" failed after ${errorDetails.attempts.length} attempts`,
-    ``,
-    `📍 Selector: ${errorDetails.selector}`,
-  ];
-
-  if (errorDetails.context) {
-    parts.push(``, `📄 Page Context:`);
-    parts.push(`   URL: ${errorDetails.context.url}`);
-    parts.push(`   Title: ${errorDetails.context.title}`);
-
-    if (errorDetails.context.elementExists) {
-      parts.push(``, `🔍 Element Found But:`);
-      const info = errorDetails.context.elementInfo;
-
-      if (!info.visible) {
-        parts.push(`   ⚠️  Element is NOT VISIBLE`);
-        parts.push(`   - Display: ${info.styles.display}`);
-        parts.push(`   - Visibility: ${info.styles.visibility}`);
-        parts.push(`   - Opacity: ${info.styles.opacity}`);
-        parts.push(`   - Size: ${info.position.width}x${info.position.height}`);
-      }
-
-      if (info.disabled) {
-        parts.push(`   ⚠️  Element is DISABLED`);
-      }
-
-      if (info.readonly && action.type === 'type') {
-        parts.push(`   ⚠️  Element is READONLY`);
-      }
-
-      if (info.styles.pointerEvents === 'none') {
-        parts.push(`   ⚠️  Element has pointer-events: none`);
-      }
-    } else {
-      parts.push(``, `❌ Element NOT FOUND in DOM`);
-    }
-
-    if (errorDetails.context.pageState) {
-      const state = errorDetails.context.pageState;
-      if (state.hasModals) {
-        parts.push(``, `⚠️  Page has open modal/dialog`);
-      }
-      if (state.hasOverlays) {
-        parts.push(`⚠️  Page has overlay/backdrop`);
-      }
-    }
-  }
-
-  parts.push(``, `🔄 Retry History:`);
-  errorDetails.attempts.forEach(attempt => {
-    parts.push(`   Attempt ${attempt.number}: ${attempt.error || 'Unknown error'}`);
-    if (attempt.selector !== errorDetails.selector) {
-      parts.push(`      (tried selector: ${attempt.selector})`);
-    }
-  });
-
-  parts.push(``, `💡 Suggestions:`);
-  if (!errorDetails.context?.elementExists) {
-    parts.push(`   - Check if page has fully loaded`);
-    parts.push(`   - Verify the selector is correct`);
-    parts.push(`   - Element might be dynamically added - add wait condition`);
-  } else if (!errorDetails.context?.elementVisible) {
-    parts.push(`   - Element exists but is hidden - check CSS/JS conditions`);
-    parts.push(`   - Wait for element to become visible`);
-    parts.push(`   - Check if element is covered by modal/overlay`);
-  }
-
-  return parts.join('\n');
-}
-
-/**
- * Execute single action
- */
-async function executeAction(action, page, timeout) {
-  const result = { output: null };
-
-  switch (action.type) {
-    case 'click':
-      await executeClick(action, page, timeout);
-      break;
-
-    case 'type':
-      await executeType(action, page, timeout);
-      break;
-
-    case 'select':
-      await executeSelect(action, page, timeout);
-      break;
-
-    case 'scroll':
-      await executeScroll(action, page);
-      break;
-
-    case 'hover':
-      await executeHover(action, page);
-      break;
-
-    case 'keypress':
-      await executeKeypress(action, page);
-      break;
-
-    case 'wait':
-      await executeWait(action, page);
-      break;
-
-    case 'upload':
-      await executeUpload(action, page, timeout);
-      break;
-
-    case 'drag':
-      await executeDrag(action, page);
-      break;
-
-    case 'navigate':
-      await executeNavigate(action, page, timeout);
-      break;
-
-    case 'extract':
-      result.output = await executeExtract(action, page);
-      break;
-
-    default:
-      throw new Error(`Unknown action type: ${action.type}`);
-  }
-
-  return result;
-}
-
-/**
- * Action executors
- */
-
-async function executeClick(action, page, timeout) {
-  const selector = action.selector.value || action.selector.primary || action.selector;
-
-  try {
-    await page.waitForSelector(selector, { timeout, visible: true });
-    await page.click(selector);
-
-    // Smart waiting after click
-    if (action.data.requiresWait !== false) {
-      await smartWaitAfterClick(page, action, timeout);
-    }
-
-    // Additional wait if specified
-    if (action.data.waitAfter) {
-      await new Promise(resolve => setTimeout(resolve, action.data.waitAfter));
-    }
-  } catch (error) {
-    throw new Error(`Failed to click "${selector}": ${error.message}`);
-  }
-}
-
-/**
- * Smart waiting after click - waits for animations and network requests
- */
-async function smartWaitAfterClick(page, action, timeout) {
-  const startTime = Date.now();
-  const maxWaitTime = timeout || 30000;
-
-  try {
-    // Initial wait 500ms to let page respond
-    await new Promise(resolve => setTimeout(resolve, 500));
-
-    // Check if there's any activity (animations, network, DOM changes)
-    const hasActivity = await checkPageActivity(page);
-
-    if (!hasActivity) {
-      // No activity detected - we're done, fast exit
-      console.log('[Smart Wait] No activity detected, skipping extended wait');
-      return;
-    }
-
-    // Activity detected - wait minimum 2 seconds
-    console.log('[Smart Wait] Activity detected, waiting for completion');
-    const remainingMinWait = 2000 - 500; // Already waited 500ms
-    if (remainingMinWait > 0) {
-      await new Promise(resolve => setTimeout(resolve, remainingMinWait));
-    }
-
-    // Wait for animations to complete
-    await page.evaluate(() => {
-      return new Promise((resolve) => {
-        const checkAnimations = () => {
-          // Check for CSS animations/transitions
-          const elements = document.querySelectorAll('*');
-          let hasAnimations = false;
-
-          for (const el of elements) {
-            const computedStyle = window.getComputedStyle(el);
-            const animations = computedStyle.getPropertyValue('animation-name');
-            const transitions = computedStyle.getPropertyValue('transition-property');
-
-            if ((animations && animations !== 'none') ||
-                (transitions && transitions !== 'none' && transitions !== 'all')) {
-              hasAnimations = true;
-              break;
-            }
-          }
-
-          if (!hasAnimations) {
-            resolve();
-          } else {
-            setTimeout(checkAnimations, 100);
-          }
-        };
-
-        // Start checking immediately
-        checkAnimations();
-        // Timeout after 3 seconds
-        setTimeout(resolve, 3000);
-      });
-    });
-
-    // Wait for network to be idle (no pending requests for 500ms)
-    await Promise.race([
-      page.waitForNetworkIdle({ idleTime: 500, timeout: 5000 }),
-      new Promise(resolve => setTimeout(resolve, 5000)) // Max 5 seconds for network
-    ]);
-
-    // Wait for any DOM changes to settle
-    await page.evaluate(() => {
-      return new Promise((resolve) => {
-        let timeoutId;
-        const observer = new MutationObserver(() => {
-          clearTimeout(timeoutId);
-          timeoutId = setTimeout(() => {
-            observer.disconnect();
-            resolve();
-          }, 300); // 300ms of no DOM changes
-        });
-
-        observer.observe(document.body, {
-          childList: true,
-          subtree: true,
-          attributes: true,
-          attributeFilter: ['class', 'style', 'hidden', 'disabled']
-        });
-
-        // Start the timeout
-        timeoutId = setTimeout(() => {
-          observer.disconnect();
-          resolve();
-        }, 300);
-
-        // Max wait 3 seconds
-        setTimeout(() => {
-          observer.disconnect();
-          resolve();
-        }, 3000);
-      });
-    });
-
-  } catch (error) {
-    // If smart wait fails, just log and continue
-    console.error('[Smart Wait] Error during smart wait:', error.message);
-  }
-
-  // Ensure we don't exceed max wait time
-  const elapsed = Date.now() - startTime;
-  if (elapsed > maxWaitTime) {
-    console.warn(`[Smart Wait] Exceeded max wait time (${maxWaitTime}ms)`);
-  }
-}
-
-/**
- * Check if page has any ongoing activity (animations, network, DOM changes)
- * Returns true if activity detected, false otherwise
- */
-async function checkPageActivity(page) {
-  try {
-    const activity = await page.evaluate(() => {
-      // Check for animations
-      const elements = document.querySelectorAll('*');
-      for (const el of elements) {
-        const computedStyle = window.getComputedStyle(el);
-        const animations = computedStyle.getPropertyValue('animation-name');
-        const transitions = computedStyle.getPropertyValue('transition-property');
-
-        if ((animations && animations !== 'none') ||
-            (transitions && transitions !== 'none' && transitions !== 'all')) {
-          return { hasActivity: true, reason: 'animations' };
-        }
-      }
-
-      // Check for recent DOM changes (using performance API)
-      if (window.performance && window.performance.getEntriesByType) {
-        const entries = window.performance.getEntriesByType('measure');
-        if (entries.length > 0) {
-          const recentEntries = entries.filter(e =>
-            performance.now() - e.startTime < 500
-          );
-          if (recentEntries.length > 0) {
-            return { hasActivity: true, reason: 'performance_measures' };
-          }
-        }
-      }
-
-      return { hasActivity: false, reason: 'none' };
-    });
-
-    if (activity.hasActivity) {
-      console.log(`[Smart Wait] Activity detected: ${activity.reason}`);
-      return true;
-    }
-
-    // Check for pending network requests using CDP
-    try {
-      const client = await page.target().createCDPSession();
-      await client.send('Network.enable');
-
-      // Give a moment for network requests to start
-      await new Promise(resolve => setTimeout(resolve, 100));
-
-      const hasNetworkActivity = await new Promise((resolve) => {
-        let requestCount = 0;
-
-        const requestListener = () => {
-          requestCount++;
-        };
-
-        client.on('Network.requestWillBeSent', requestListener);
-
-        setTimeout(() => {
-          client.off('Network.requestWillBeSent', requestListener);
-          client.detach().catch(() => {});
-          resolve(requestCount > 0);
-        }, 200);
-      });
-
-      if (hasNetworkActivity) {
-        console.log('[Smart Wait] Network activity detected');
-        return true;
-      }
-    } catch (netError) {
-      // Network check failed, assume no activity
-      console.log('[Smart Wait] Network check failed, assuming no activity');
-    }
-
-    return false;
-  } catch (error) {
-    // If check fails, assume there's activity to be safe
-    console.error('[Smart Wait] Activity check failed, assuming activity exists:', error.message);
-    return true;
-  }
-}
-
-async function executeType(action, page, timeout) {
-  const selector = action.selector.value || action.selector.primary || action.selector;
-
-  try {
-    await page.waitForSelector(selector, { timeout, visible: true });
-
-    // Check if element is editable
-    const isEditable = await page.evaluate((sel) => {
-      const el = document.querySelector(sel);
-      if (!el) return false;
-
-      const isInput = el.tagName === 'INPUT' || el.tagName === 'TEXTAREA';
-      const isContentEditable = el.isContentEditable;
-
-      return isInput || isContentEditable;
-    }, selector);
-
-    if (!isEditable) {
-      throw new Error(`Element "${selector}" is not editable (not an input, textarea, or contenteditable)`);
-    }
-
-    // Clear field if specified
-    if (action.data.clearFirst !== false) {
-      await page.click(selector, { clickCount: 3 });
-      await page.keyboard.press('Backspace');
-    }
-
-    // Type text with optional delay
-    await page.type(selector, action.data.text, {
-      delay: action.data.delay || 0
-    });
-  } catch (error) {
-    throw new Error(`Failed to type into "${selector}": ${error.message}`);
-  }
-}
-
-async function executeSelect(action, page, timeout) {
-  const selector = action.selector.value || action.selector.primary || action.selector;
-
-  try {
-    if (action.data.selectType === 'custom') {
-      // Custom select (multi-step)
-      for (const step of action.data.steps) {
-        if (step.action === 'click') {
-          await page.waitForSelector(step.selector, { timeout });
-          await page.click(step.selector);
-        } else if (step.action === 'wait') {
-          await new Promise(resolve => setTimeout(resolve, step.duration));
-        }
-      }
-    } else {
-      // Native select
-      await page.waitForSelector(selector, { timeout, visible: true });
-
-      // Verify it's a select element
-      const isSelect = await page.evaluate((sel) => {
-        const el = document.querySelector(sel);
-        return el && el.tagName === 'SELECT';
-      }, selector);
-
-      if (!isSelect) {
-        throw new Error(`Element "${selector}" is not a <select> element`);
-      }
-
-      await page.select(selector, action.data.value);
-    }
-  } catch (error) {
-    throw new Error(`Failed to select option in "${selector}": ${error.message}`);
-  }
-}
-
-async function executeScroll(action, page) {
-  const selector = action.selector.value || action.selector.primary || action.selector;
-  await page.evaluate((selector, behavior) => {
-    const element = document.querySelector(selector);
-    if (element) {
-      element.scrollIntoView({ behavior: behavior || 'auto', block: 'center' });
-    }
-  }, selector, action.data.behavior);
-}
-
-async function executeHover(action, page) {
-  const selector = action.selector.value || action.selector.primary || action.selector;
-  await page.hover(selector);
-}
-
-async function executeKeypress(action, page) {
-  const key = action.data.key;
-  const modifiers = action.data.modifiers || [];
-
-  // Press modifiers
-  for (const mod of modifiers) {
-    await page.keyboard.down(mod);
-  }
-
-  // Press key
-  await page.keyboard.press(key);
-
-  // Release modifiers
-  for (const mod of modifiers.reverse()) {
-    await page.keyboard.up(mod);
-  }
-}
-
-async function executeWait(action, page) {
-  if (action.data.waitType === 'selector') {
-    await page.waitForSelector(action.data.selector, {
-      timeout: action.data.duration
-    });
-  } else {
-    await new Promise(resolve => setTimeout(resolve, action.data.duration));
-  }
-}
-
-async function executeUpload(action, page, timeout) {
-  const selector = action.selector.value || action.selector.primary || action.selector;
-  const fileInput = await page.waitForSelector(selector, { timeout });
-  await fileInput.uploadFile(action.data.filePath);
-}
-
-async function executeDrag(action, page) {
-  const { fromSelector, toSelector, fromX, fromY, toX, toY } = action.data;
-
-  if (fromSelector && toSelector) {
-    // Drag from element to element
-    const from = await page.$(fromSelector);
-    const to = await page.$(toSelector);
-
-    const fromBox = await from.boundingBox();
-    const toBox = await to.boundingBox();
-
-    await page.mouse.move(fromBox.x + fromBox.width / 2, fromBox.y + fromBox.height / 2);
-    await page.mouse.down();
-    await page.mouse.move(toBox.x + toBox.width / 2, toBox.y + toBox.height / 2);
-    await page.mouse.up();
-  } else {
-    // Drag by coordinates
-    await page.mouse.move(fromX, fromY);
-    await page.mouse.down();
-    await page.mouse.move(toX, toY);
-    await page.mouse.up();
-  }
-}
-
-async function executeNavigate(action, page, timeout) {
-  await page.goto(action.data.url, {
-    waitUntil: action.data.waitUntil || 'networkidle2',
-    timeout
-  });
-}
-
-async function executeExtract(action, page) {
-  const { selector, attribute, multiple } = action.data;
-
-  if (multiple) {
-    return await page.$$eval(selector, (elements, attr) => {
-      return elements.map(el => attr ? el.getAttribute(attr) : el.textContent.trim());
-    }, attribute);
-  } else {
-    return await page.$eval(selector, (el, attr) => {
-      return attr ? el.getAttribute(attr) : el.textContent.trim();
-    }, attribute);
-  }
-}
-
-/**
- * Substitute parameters in action
- * Replaces {{paramName}} with actual values
- */
-function substituteParameters(action, params) {
-  const resolved = JSON.parse(JSON.stringify(action));
-
-  // Substitute in action data
-  if (resolved.data) {
-    for (const [key, value] of Object.entries(resolved.data)) {
-      if (typeof value === 'string') {
-        resolved.data[key] = substituteString(value, params);
-      }
-    }
-  }
-
-  return resolved;
-}
-
-/**
- * Substitute {{param}} in string
- */
-function substituteString(str, params) {
-  return str.replace(/\{\{(\w+)\}\}/g, (match, paramName) => {
-    if (params[paramName] !== undefined) {
-      return params[paramName];
-    }
-    return match; // Keep original if param not found
-  });
-}
-
-/**
- * Element finder utils code (to be injected into page)
- * Will be loaded from utils/element-finder-utils.js
- */
-const elementFinderUtilsCode = `
-// This will be populated from element-finder-utils.js browser-side code
-// For now, placeholder
-`;
+/**
+ * recorder/scenario-executor.js
+ *
+ * Executes recorded scenarios with:
+ * 1. Action playback with error handling
+ * 2. Parameter substitution
+ * 3. Secret injection
+ * 4. Dependency resolution and chaining
+ * 5. Retry logic with fallback selectors
+ */
+
+import { resolveDependencies, checkDependencyCondition } from './dependency-resolver.js';
+import { loadScenario, loadSecrets, loadIndex } from './scenario-storage.js';
+
+// Debug mode - avoid polluting STDIO with logs (breaks MCP JSON-RPC)
+const DEBUG_MODE = process.env.CHROMETOOLS_DEBUG === 'true';
+const debugLog = DEBUG_MODE ? console.error : () => {};
+
+/**
+ * Execute scenario with dependencies
+ * @param {string} scenarioName - Scenario to execute
+ * @param {Object} page - Puppeteer page instance
+ * @param {Object} params - Parameters for scenario
+ * @param {Object} options - Execution options { executeDependencies, skipConditions, maxRetries, timeout }
+ * @returns {Object} - Execution result
+ */
+export async function executeScenario(scenarioName, page, params = {}, options = {}) {
+  const {
+    executeDependencies = true,  // Execute dependencies by default
+    skipConditions = false,
+    maxRetries = 3,
+    timeout = 30000,
+    projectId = null  // Optional projectId for disambiguation
+  } = options;
+
+  const result = {
+    success: false,
+    scenarioName,
+    executedScenarios: [],
+    errors: [],
+    outputs: {},
+    duration: 0
+  };
+
+  const startTime = Date.now();
+
+  try {
+    // Load scenario to get its metadata (needed for dependency resolution)
+    const initialScenario = await loadScenario(scenarioName, false, projectId);
+
+    if (!initialScenario) {
+      result.errors.push(`Scenario "${scenarioName}" not found`);
+      return result;
+    }
+
+    // Check for name collision
+    if (initialScenario.collision) {
+      result.errors.push(initialScenario.message);
+      result.availableProjectIds = initialScenario.availableProjectIds;
+      return result;
+    }
+
+    let chain = [{ name: scenarioName, projectId }]; // Default: execute only the requested scenario
+
+    // Resolve and execute dependencies if enabled
+    if (executeDependencies && initialScenario.metadata?.dependencies) {
+      // Build a simplified index from metadata for dependency resolution
+      // In the new system, we need to resolve cross-project dependencies
+      // Dependencies inherit parent's projectId unless they specify their own
+      chain = [
+        ...initialScenario.metadata.dependencies.map(dep => ({
+          name: dep.scenario,
+          projectId: dep.projectId || projectId // Use explicit projectId or inherit from parent
+        })),
+        { name: scenarioName, projectId }
+      ];
+    }
+
+    // Execute chain in order
+    for (const item of chain) {
+      const scenario = await loadScenario(item.name, true, item.projectId); // Load with secrets, using item's projectId
+
+      if (!scenario) {
+        result.errors.push(`Scenario "${item.name}" not found`);
+        return result;
+      }
+
+      // Check for name collision in dependencies
+      if (scenario.collision) {
+        result.errors.push(`Dependency "${item.name}": ${scenario.message}`);
+        result.availableProjectIds = scenario.availableProjectIds;
+        return result;
+      }
+
+      // Check dependency conditions
+      if (scenario.metadata?.dependencies) {
+        for (const dep of scenario.metadata.dependencies) {
+          if (dep.condition) {
+            const context = { page, variables: params };
+            const shouldExecute = await checkDependencyCondition(dep.condition, context);
+
+            if (!shouldExecute) {
+              debugLog(`Skipping scenario "${item.name}" due to condition`);
+              continue;
+            }
+          }
+        }
+      }
+
+      // Merge secrets with params
+      const executionParams = { ...params, ...(scenario.secrets || {}) };
+
+      // Execute scenario
+      const scenarioResult = await executeSingleScenario(scenario, page, executionParams, {
+        maxRetries,
+        timeout
+      });
+
+      result.executedScenarios.push(item.name);
+
+      if (!scenarioResult.success) {
+        result.errors.push(...scenarioResult.errors);
+        return result;
+      }
+
+      // Collect outputs for next scenarios
+      if (scenarioResult.outputs) {
+        Object.assign(result.outputs, scenarioResult.outputs);
+        Object.assign(params, scenarioResult.outputs);
+      }
+    }
+
+    result.success = true;
+  } catch (error) {
+    result.errors.push(`Execution failed: ${error.message}`);
+  } finally {
+    result.duration = Date.now() - startTime;
+  }
+
+  return result;
+}
+
+/**
+ * Execute single scenario (without dependencies)
+ * @param {Object} scenario - Scenario data
+ * @param {Object} page - Puppeteer page
+ * @param {Object} params - Parameters
+ * @param {Object} options - Options
+ * @returns {Object} - Execution result
+ */
+async function executeSingleScenario(scenario, page, params = {}, options = {}) {
+  const { maxRetries = 3, timeout = 30000 } = options;
+
+  const result = {
+    success: false,
+    errors: [],
+    outputs: {},
+    actionResults: []
+  };
+
+  try {
+    for (const action of scenario.chain) {
+      // Substitute parameters in action
+      const resolvedAction = substituteParameters(action, params);
+
+      // Execute action with retry
+      const actionResult = await executeActionWithRetry(
+        resolvedAction,
+        page,
+        maxRetries,
+        timeout
+      );
+
+      result.actionResults.push(actionResult);
+
+      if (!actionResult.success) {
+        result.errors.push(`Action failed: ${actionResult.error}`);
+        return result;
+      }
+
+      // Store outputs if action produces any
+      if (actionResult.output) {
+        Object.assign(result.outputs, actionResult.output);
+      }
+    }
+
+    // Validate final URL if exitUrl is specified in metadata
+    if (scenario.metadata?.exitUrl) {
+      // Wait a bit for any pending navigation/redirects to complete
+      await new Promise(resolve => setTimeout(resolve, 500));
+
+      // Get current URL from the page (more reliable than page.url() for recent navigation)
+      const currentUrl = await page.evaluate(() => window.location.href);
+      const expectedUrl = scenario.metadata.exitUrl;
+
+      // Normalize URLs for comparison (remove trailing slashes, fragments)
+      const normalizeUrl = (url) => {
+        try {
+          const parsed = new URL(url);
+          // Remove fragment and trailing slash
+          return `${parsed.origin}${parsed.pathname.replace(/\/$/, '')}${parsed.search}`;
+        } catch {
+          return url.replace(/\/$/, '');
+        }
+      };
+
+      const normalizedCurrent = normalizeUrl(currentUrl);
+      const normalizedExpected = normalizeUrl(expectedUrl);
+
+      if (normalizedCurrent !== normalizedExpected) {
+        result.errors.push(
+          `❌ URL Validation Failed\n\n` +
+          `Expected final URL: ${expectedUrl}\n` +
+          `Actual final URL:   ${currentUrl}\n\n` +
+          `The scenario ended on a different page than expected.\n` +
+          `This may indicate:\n` +
+          `  - Navigation flow has changed\n` +
+          `  - An action failed silently\n` +
+          `  - Page redirected unexpectedly\n\n` +
+          `💡 Suggestion: Check if the page flow or redirects have changed since recording.`
+        );
+        return result;
+      }
+
+      // URL validation passed
+      result.urlValidation = {
+        success: true,
+        expectedUrl,
+        actualUrl: currentUrl
+      };
+    }
+
+    result.success = true;
+  } catch (error) {
+    result.errors.push(`Scenario execution error: ${error.message}`);
+  }
+
+  return result;
+}
+
+/**
+ * Execute action with retry and fallback selectors
+ */
+async function executeActionWithRetry(action, page, maxRetries, timeout) {
+  const result = {
+    success: false,
+    action: action.type,
+    error: null,
+    errorDetails: {
+      attempts: [],
+      selector: action.selector?.value || action.selector?.primary,
+      context: null
+    },
+    output: null,
+    attempts: 0
+  };
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    result.attempts = attempt;
+    const attemptInfo = {
+      number: attempt,
+      selector: action.selector?.value || action.selector?.primary,
+      error: null,
+      timestamp: new Date().toISOString()
+    };
+
+    try {
+      // Execute action based on type
+      const actionResult = await executeAction(action, page, timeout);
+
+      result.success = true;
+      result.output = actionResult.output;
+      attemptInfo.success = true;
+      result.errorDetails.attempts.push(attemptInfo);
+      return result;
+    } catch (error) {
+      attemptInfo.error = error.message;
+      attemptInfo.success = false;
+
+      // Capture page context for error reporting
+      if (attempt === maxRetries) {
+        try {
+          result.errorDetails.context = await capturePageContext(page, action);
+        } catch (contextError) {
+          debugLog('Failed to capture page context:', contextError);
+        }
+      }
+
+      result.errorDetails.attempts.push(attemptInfo);
+      result.error = error.message;
+
+      // If this is a selector error and we have fallbacks, try them
+      if (action.selector?.fallbacks && action.selector.fallbacks.length > 0) {
+        const fallback = action.selector.fallbacks[0];
+        debugLog(`[Retry ${attempt}] Trying fallback selector: ${fallback}`);
+
+        action.selector.value = fallback;
+        action.selector.fallbacks = action.selector.fallbacks.slice(1);
+        continue;
+      }
+
+      // If we have element description, try smartFindElement
+      if (action.selector?.elementInfo?.text && attempt < maxRetries) {
+        debugLog(`[Retry ${attempt}] Selector failed, trying smartFindElement with description: ${action.selector.elementInfo.text}`);
+
+        try {
+          // Inject element finder utilities if not already done
+          await page.evaluate(elementFinderUtilsCode);
+
+          const smartResult = await page.evaluate((description) => {
+            return window.smartFindElement({ description, maxResults: 3 });
+          }, action.selector.elementInfo.text);
+
+          if (smartResult.candidates && smartResult.candidates.length > 0) {
+            action.selector.value = smartResult.candidates[0].selector;
+            action.selector.fallbacks = smartResult.candidates.slice(1).map(c => c.selector);
+            debugLog(`[Retry ${attempt}] Found alternative selector: ${action.selector.value}`);
+            continue;
+          }
+        } catch (smartError) {
+          debugLog('[Retry] smartFindElement failed:', smartError.message);
+        }
+      }
+
+      // Last attempt failed
+      if (attempt === maxRetries) {
+        // Create comprehensive error message
+        result.error = formatDetailedError(action, result.errorDetails);
+        return result;
+      }
+
+      // Wait before retry
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Capture page context for error reporting
+ */
+async function capturePageContext(page, action) {
+  try {
+    const context = {
+      url: page.url(),
+      title: await page.title(),
+      elementExists: false,
+      elementVisible: false,
+      elementInfo: null,
+      pageState: null
+    };
+
+    const selector = action.selector?.value || action.selector?.primary;
+
+    if (selector) {
+      // Check if element exists
+      context.elementExists = await page.evaluate((sel) => {
+        return document.querySelector(sel) !== null;
+      }, selector);
+
+      // If exists, check visibility and get info
+      if (context.elementExists) {
+        context.elementInfo = await page.evaluate((sel) => {
+          const el = document.querySelector(sel);
+          const rect = el.getBoundingClientRect();
+          const styles = window.getComputedStyle(el);
+
+          return {
+            tagName: el.tagName,
+            id: el.id,
+            className: el.className,
+            visible: rect.width > 0 && rect.height > 0 && styles.display !== 'none' && styles.visibility !== 'hidden',
+            disabled: el.disabled || el.getAttribute('aria-disabled') === 'true',
+            readonly: el.readOnly || el.getAttribute('aria-readonly') === 'true',
+            position: {
+              top: rect.top,
+              left: rect.left,
+              width: rect.width,
+              height: rect.height
+            },
+            styles: {
+              display: styles.display,
+              visibility: styles.visibility,
+              opacity: styles.opacity,
+              pointerEvents: styles.pointerEvents
+            }
+          };
+        }, selector);
+
+        context.elementVisible = context.elementInfo.visible;
+      }
+    }
+
+    // Get page state
+    context.pageState = await page.evaluate(() => {
+      return {
+        readyState: document.readyState,
+        hasModals: document.querySelector('[role="dialog"], .modal, .popup') !== null,
+        hasOverlays: document.querySelector('.overlay, .backdrop') !== null,
+        activeElement: document.activeElement ? {
+          tagName: document.activeElement.tagName,
+          id: document.activeElement.id,
+          className: document.activeElement.className
+        } : null
+      };
+    });
+
+    return context;
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+
+/**
+ * Format detailed error message for AI agent
+ */
+function formatDetailedError(action, errorDetails) {
+  const parts = [
+    `❌ Action "${action.type}" failed after ${errorDetails.attempts.length} attempts`,
+    ``,
+    `📍 Selector: ${errorDetails.selector}`,
+  ];
+
+  if (errorDetails.context) {
+    parts.push(``, `📄 Page Context:`);
+    parts.push(`   URL: ${errorDetails.context.url}`);
+    parts.push(`   Title: ${errorDetails.context.title}`);
+
+    if (errorDetails.context.elementExists) {
+      parts.push(``, `🔍 Element Found But:`);
+      const info = errorDetails.context.elementInfo;
+
+      if (!info.visible) {
+        parts.push(`   ⚠️  Element is NOT VISIBLE`);
+        parts.push(`   - Display: ${info.styles.display}`);
+        parts.push(`   - Visibility: ${info.styles.visibility}`);
+        parts.push(`   - Opacity: ${info.styles.opacity}`);
+        parts.push(`   - Size: ${info.position.width}x${info.position.height}`);
+      }
+
+      if (info.disabled) {
+        parts.push(`   ⚠️  Element is DISABLED`);
+      }
+
+      if (info.readonly && action.type === 'type') {
+        parts.push(`   ⚠️  Element is READONLY`);
+      }
+
+      if (info.styles.pointerEvents === 'none') {
+        parts.push(`   ⚠️  Element has pointer-events: none`);
+      }
+    } else {
+      parts.push(``, `❌ Element NOT FOUND in DOM`);
+    }
+
+    if (errorDetails.context.pageState) {
+      const state = errorDetails.context.pageState;
+      if (state.hasModals) {
+        parts.push(``, `⚠️  Page has open modal/dialog`);
+      }
+      if (state.hasOverlays) {
+        parts.push(`⚠️  Page has overlay/backdrop`);
+      }
+    }
+  }
+
+  parts.push(``, `🔄 Retry History:`);
+  errorDetails.attempts.forEach(attempt => {
+    parts.push(`   Attempt ${attempt.number}: ${attempt.error || 'Unknown error'}`);
+    if (attempt.selector !== errorDetails.selector) {
+      parts.push(`      (tried selector: ${attempt.selector})`);
+    }
+  });
+
+  parts.push(``, `💡 Suggestions:`);
+  if (!errorDetails.context?.elementExists) {
+    parts.push(`   - Check if page has fully loaded`);
+    parts.push(`   - Verify the selector is correct`);
+    parts.push(`   - Element might be dynamically added - add wait condition`);
+  } else if (!errorDetails.context?.elementVisible) {
+    parts.push(`   - Element exists but is hidden - check CSS/JS conditions`);
+    parts.push(`   - Wait for element to become visible`);
+    parts.push(`   - Check if element is covered by modal/overlay`);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Execute single action
+ */
+async function executeAction(action, page, timeout) {
+  const result = { output: null };
+
+  switch (action.type) {
+    case 'click':
+      await executeClick(action, page, timeout);
+      break;
+
+    case 'type':
+      await executeType(action, page, timeout);
+      break;
+
+    case 'select':
+      await executeSelect(action, page, timeout);
+      break;
+
+    case 'scroll':
+      await executeScroll(action, page);
+      break;
+
+    case 'hover':
+      await executeHover(action, page);
+      break;
+
+    case 'keypress':
+      await executeKeypress(action, page);
+      break;
+
+    case 'wait':
+      await executeWait(action, page);
+      break;
+
+    case 'upload':
+      await executeUpload(action, page, timeout);
+      break;
+
+    case 'drag':
+      await executeDrag(action, page);
+      break;
+
+    case 'navigate':
+      await executeNavigate(action, page, timeout);
+      break;
+
+    case 'extract':
+      result.output = await executeExtract(action, page);
+      break;
+
+    default:
+      throw new Error(`Unknown action type: ${action.type}`);
+  }
+
+  return result;
+}
+
+/**
+ * Action executors
+ */
+
+async function executeClick(action, page, timeout) {
+  const selector = action.selector.value || action.selector.primary || action.selector;
+
+  try {
+    await page.waitForSelector(selector, { timeout, visible: true });
+    await page.click(selector);
+
+    // Smart waiting after click
+    if (action.data.requiresWait !== false) {
+      await smartWaitAfterClick(page, action, timeout);
+    }
+
+    // Additional wait if specified
+    if (action.data.waitAfter) {
+      await new Promise(resolve => setTimeout(resolve, action.data.waitAfter));
+    }
+  } catch (error) {
+    throw new Error(`Failed to click "${selector}": ${error.message}`);
+  }
+}
+
+/**
+ * Smart waiting after click - waits for animations and network requests
+ */
+async function smartWaitAfterClick(page, action, timeout) {
+  const startTime = Date.now();
+  const maxWaitTime = timeout || 30000;
+
+  try {
+    // Initial wait 500ms to let page respond
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    // Check if there's any activity (animations, network, DOM changes)
+    const hasActivity = await checkPageActivity(page);
+
+    if (!hasActivity) {
+      // No activity detected - we're done, fast exit
+      debugLog('[Smart Wait] No activity detected, skipping extended wait');
+      return;
+    }
+
+    // Activity detected - wait minimum 2 seconds
+    debugLog('[Smart Wait] Activity detected, waiting for completion');
+    const remainingMinWait = 2000 - 500; // Already waited 500ms
+    if (remainingMinWait > 0) {
+      await new Promise(resolve => setTimeout(resolve, remainingMinWait));
+    }
+
+    // Wait for animations to complete
+    await page.evaluate(() => {
+      return new Promise((resolve) => {
+        const checkAnimations = () => {
+          // Check for CSS animations/transitions
+          const elements = document.querySelectorAll('*');
+          let hasAnimations = false;
+
+          for (const el of elements) {
+            const computedStyle = window.getComputedStyle(el);
+            const animations = computedStyle.getPropertyValue('animation-name');
+            const transitions = computedStyle.getPropertyValue('transition-property');
+
+            if ((animations && animations !== 'none') ||
+                (transitions && transitions !== 'none' && transitions !== 'all')) {
+              hasAnimations = true;
+              break;
+            }
+          }
+
+          if (!hasAnimations) {
+            resolve();
+          } else {
+            setTimeout(checkAnimations, 100);
+          }
+        };
+
+        // Start checking immediately
+        checkAnimations();
+        // Timeout after 3 seconds
+        setTimeout(resolve, 3000);
+      });
+    });
+
+    // Wait for network to be idle (no pending requests for 500ms)
+    await Promise.race([
+      page.waitForNetworkIdle({ idleTime: 500, timeout: 5000 }),
+      new Promise(resolve => setTimeout(resolve, 5000)) // Max 5 seconds for network
+    ]);
+
+    // Wait for any DOM changes to settle
+    await page.evaluate(() => {
+      return new Promise((resolve) => {
+        let timeoutId;
+        const observer = new MutationObserver(() => {
+          clearTimeout(timeoutId);
+          timeoutId = setTimeout(() => {
+            observer.disconnect();
+            resolve();
+          }, 300); // 300ms of no DOM changes
+        });
+
+        observer.observe(document.body, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeFilter: ['class', 'style', 'hidden', 'disabled']
+        });
+
+        // Start the timeout
+        timeoutId = setTimeout(() => {
+          observer.disconnect();
+          resolve();
+        }, 300);
+
+        // Max wait 3 seconds
+        setTimeout(() => {
+          observer.disconnect();
+          resolve();
+        }, 3000);
+      });
+    });
+
+  } catch (error) {
+    // If smart wait fails, just log and continue
+    debugLog('[Smart Wait] Error during smart wait:', error.message);
+  }
+
+  // Ensure we don't exceed max wait time
+  const elapsed = Date.now() - startTime;
+  if (elapsed > maxWaitTime) {
+    debugLog(`[Smart Wait] Exceeded max wait time (${maxWaitTime}ms)`);
+  }
+}
+
+/**
+ * Check if page has any ongoing activity (animations, network, DOM changes)
+ * Returns true if activity detected, false otherwise
+ */
+async function checkPageActivity(page) {
+  try {
+    const activity = await page.evaluate(() => {
+      // Check for animations
+      const elements = document.querySelectorAll('*');
+      for (const el of elements) {
+        const computedStyle = window.getComputedStyle(el);
+        const animations = computedStyle.getPropertyValue('animation-name');
+        const transitions = computedStyle.getPropertyValue('transition-property');
+
+        if ((animations && animations !== 'none') ||
+            (transitions && transitions !== 'none' && transitions !== 'all')) {
+          return { hasActivity: true, reason: 'animations' };
+        }
+      }
+
+      // Check for recent DOM changes (using performance API)
+      if (window.performance && window.performance.getEntriesByType) {
+        const entries = window.performance.getEntriesByType('measure');
+        if (entries.length > 0) {
+          const recentEntries = entries.filter(e =>
+            performance.now() - e.startTime < 500
+          );
+          if (recentEntries.length > 0) {
+            return { hasActivity: true, reason: 'performance_measures' };
+          }
+        }
+      }
+
+      return { hasActivity: false, reason: 'none' };
+    });
+
+    if (activity.hasActivity) {
+      debugLog(`[Smart Wait] Activity detected: ${activity.reason}`);
+      return true;
+    }
+
+    // Check for pending network requests using CDP
+    try {
+      const client = await page.target().createCDPSession();
+      await client.send('Network.enable');
+
+      // Give a moment for network requests to start
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      const hasNetworkActivity = await new Promise((resolve) => {
+        let requestCount = 0;
+
+        const requestListener = () => {
+          requestCount++;
+        };
+
+        client.on('Network.requestWillBeSent', requestListener);
+
+        setTimeout(() => {
+          client.off('Network.requestWillBeSent', requestListener);
+          client.detach().catch(() => {});
+          resolve(requestCount > 0);
+        }, 200);
+      });
+
+      if (hasNetworkActivity) {
+        debugLog('[Smart Wait] Network activity detected');
+        return true;
+      }
+    } catch (netError) {
+      // Network check failed, assume no activity
+      debugLog('[Smart Wait] Network check failed, assuming no activity');
+    }
+
+    return false;
+  } catch (error) {
+    // If check fails, assume there's activity to be safe
+    debugLog('[Smart Wait] Activity check failed, assuming activity exists:', error.message);
+    return true;
+  }
+}
+
+async function executeType(action, page, timeout) {
+  const selector = action.selector.value || action.selector.primary || action.selector;
+
+  try {
+    await page.waitForSelector(selector, { timeout, visible: true });
+
+    // Check if element is editable
+    const isEditable = await page.evaluate((sel) => {
+      const el = document.querySelector(sel);
+      if (!el) return false;
+
+      const isInput = el.tagName === 'INPUT' || el.tagName === 'TEXTAREA';
+      const isContentEditable = el.isContentEditable;
+
+      return isInput || isContentEditable;
+    }, selector);
+
+    if (!isEditable) {
+      throw new Error(`Element "${selector}" is not editable (not an input, textarea, or contenteditable)`);
+    }
+
+    // Clear field if specified
+    if (action.data.clearFirst !== false) {
+      await page.click(selector, { clickCount: 3 });
+      await page.keyboard.press('Backspace');
+    }
+
+    // Type text with optional delay
+    await page.type(selector, action.data.text, {
+      delay: action.data.delay || 0
+    });
+  } catch (error) {
+    throw new Error(`Failed to type into "${selector}": ${error.message}`);
+  }
+}
+
+async function executeSelect(action, page, timeout) {
+  const selector = action.selector.value || action.selector.primary || action.selector;
+
+  try {
+    if (action.data.selectType === 'custom') {
+      // Custom select (multi-step)
+      for (const step of action.data.steps) {
+        if (step.action === 'click') {
+          await page.waitForSelector(step.selector, { timeout });
+          await page.click(step.selector);
+        } else if (step.action === 'wait') {
+          await new Promise(resolve => setTimeout(resolve, step.duration));
+        }
+      }
+    } else {
+      // Native select
+      await page.waitForSelector(selector, { timeout, visible: true });
+
+      // Verify it's a select element
+      const isSelect = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        return el && el.tagName === 'SELECT';
+      }, selector);
+
+      if (!isSelect) {
+        throw new Error(`Element "${selector}" is not a <select> element`);
+      }
+
+      await page.select(selector, action.data.value);
+    }
+  } catch (error) {
+    throw new Error(`Failed to select option in "${selector}": ${error.message}`);
+  }
+}
+
+async function executeScroll(action, page) {
+  const selector = action.selector.value || action.selector.primary || action.selector;
+  await page.evaluate((selector, behavior) => {
+    const element = document.querySelector(selector);
+    if (element) {
+      element.scrollIntoView({ behavior: behavior || 'auto', block: 'center' });
+    }
+  }, selector, action.data.behavior);
+}
+
+async function executeHover(action, page) {
+  const selector = action.selector.value || action.selector.primary || action.selector;
+  await page.hover(selector);
+}
+
+async function executeKeypress(action, page) {
+  const key = action.data.key;
+  const modifiers = action.data.modifiers || [];
+
+  // Press modifiers
+  for (const mod of modifiers) {
+    await page.keyboard.down(mod);
+  }
+
+  // Press key
+  await page.keyboard.press(key);
+
+  // Release modifiers
+  for (const mod of modifiers.reverse()) {
+    await page.keyboard.up(mod);
+  }
+}
+
+async function executeWait(action, page) {
+  if (action.data.waitType === 'selector') {
+    await page.waitForSelector(action.data.selector, {
+      timeout: action.data.duration
+    });
+  } else {
+    await new Promise(resolve => setTimeout(resolve, action.data.duration));
+  }
+}
+
+async function executeUpload(action, page, timeout) {
+  const selector = action.selector.value || action.selector.primary || action.selector;
+  const fileInput = await page.waitForSelector(selector, { timeout });
+  await fileInput.uploadFile(action.data.filePath);
+}
+
+async function executeDrag(action, page) {
+  const { fromSelector, toSelector, fromX, fromY, toX, toY } = action.data;
+
+  if (fromSelector && toSelector) {
+    // Drag from element to element
+    const from = await page.$(fromSelector);
+    const to = await page.$(toSelector);
+
+    const fromBox = await from.boundingBox();
+    const toBox = await to.boundingBox();
+
+    await page.mouse.move(fromBox.x + fromBox.width / 2, fromBox.y + fromBox.height / 2);
+    await page.mouse.down();
+    await page.mouse.move(toBox.x + toBox.width / 2, toBox.y + toBox.height / 2);
+    await page.mouse.up();
+  } else {
+    // Drag by coordinates
+    await page.mouse.move(fromX, fromY);
+    await page.mouse.down();
+    await page.mouse.move(toX, toY);
+    await page.mouse.up();
+  }
+}
+
+async function executeNavigate(action, page, timeout) {
+  await page.goto(action.data.url, {
+    waitUntil: action.data.waitUntil || 'networkidle2',
+    timeout
+  });
+}
+
+async function executeExtract(action, page) {
+  const { selector, attribute, multiple } = action.data;
+
+  if (multiple) {
+    return await page.$$eval(selector, (elements, attr) => {
+      return elements.map(el => attr ? el.getAttribute(attr) : el.textContent.trim());
+    }, attribute);
+  } else {
+    return await page.$eval(selector, (el, attr) => {
+      return attr ? el.getAttribute(attr) : el.textContent.trim();
+    }, attribute);
+  }
+}
+
+/**
+ * Substitute parameters in action
+ * Replaces {{paramName}} with actual values
+ */
+function substituteParameters(action, params) {
+  const resolved = JSON.parse(JSON.stringify(action));
+
+  // Substitute in action data
+  if (resolved.data) {
+    for (const [key, value] of Object.entries(resolved.data)) {
+      if (typeof value === 'string') {
+        resolved.data[key] = substituteString(value, params);
+      }
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Substitute {{param}} in string
+ */
+function substituteString(str, params) {
+  return str.replace(/\{\{(\w+)\}\}/g, (match, paramName) => {
+    if (params[paramName] !== undefined) {
+      return params[paramName];
+    }
+    return match; // Keep original if param not found
+  });
+}
+
+/**
+ * Element finder utils code (to be injected into page)
+ * Will be loaded from utils/element-finder-utils.js
+ */
+const elementFinderUtilsCode = `
+// This will be populated from element-finder-utils.js browser-side code
+// For now, placeholder
+`;