@cognior/iap-sdk 0.1.0

package/src/services/flowManager.ts

@@ -0,0 +1,905 @@
+// src/services/flowManager.ts
+// Service for managing contextual flows and experience indicators
+// Supports both CSS and XPath selectors for targeting elements
+
+import { LocationContextService } from './locationContextService';
+import type { ModalSequencePayload } from '../experiences/types';
+import { resolveSelector } from '../utils/selectors';
+
+/**
+ * Interface for flows with contextual triggering properties
+ */
+export interface ContextualFlow {
+  id: string;
+  type: string;
+  payload: any;
+  elementSelector?: string;
+  elementTrigger?: string;
+  elementLocation?: string;
+  originalData?: any; // Store original flow data for reference
+}
+
+/**
+ * Manager for contextual flows and experience indicators
+ */
+export class FlowManager {
+  private static _instance: FlowManager;
+  private _flows: ContextualFlow[] = [];
+  private _pendingFlows: ContextualFlow[] = []; // Flows with selectors not found in current page
+  private _locationService = LocationContextService.getInstance();
+  private _activeIndicators: Map<string, HTMLElement> = new Map();
+  private _activeListeners: Map<string, { element: HTMLElement, eventType: string, handler: EventListener }[]> = new Map();
+  private _indicatorStyle: HTMLStyleElement | null = null;
+  private _previousScreenId: string | undefined;
+
+  // Track active flow to prevent multiple flows from running simultaneously
+  private _activeFlowId: string | null = null;
+  private _flowInProgress: boolean = false;
+
+  // Step-level execution guards (NEW)
+  private _activeStepTriggered: boolean = false;
+  private _currentActiveStep: string | null = null;
+
+  // Track retry attempts to avoid infinite loops
+  private _retryAttempts: Map<string, number> = new Map();
+  private _maxRetryAttempts: number = 5; // Maximum number of retries per flow
+  private _domObserver: MutationObserver | null = null;
+  private _domChangeTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private constructor() {
+    console.debug('[DAP] Initializing FlowManager');
+    
+    // Subscribe to location changes
+    this._locationService.subscribe(this.handleLocationChange.bind(this));
+    
+    // Add indicator styles
+    this.injectIndicatorStyles();
+    console.debug('[DAP] Indicator styles injected');
+    
+    // Ensure we re-evaluate flows when DOM is fully ready
+    if (document.readyState !== 'complete') {
+      console.debug('[DAP] Document not complete, adding load event listener');
+      window.addEventListener('load', () => {
+        console.debug('[DAP] Window fully loaded, refreshing flow visibility');
+        this.refreshFlowVisibility(true);
+      });
+    } else {
+      console.debug('[DAP] Document already complete');
+    }
+    
+    // Set up DOM observer for dynamic content changes
+    this.setupDomObserver();
+    
+    console.debug('[DAP] FlowManager initialized');
+  }
+  
+  /**
+   * Set up an observer to watch for DOM changes that might affect flow indicators
+   */
+  private setupDomObserver(): void {
+    try {
+      this._domObserver = new MutationObserver((mutations) => {
+        // Only process significant DOM changes when we have pending flows
+        if (this._pendingFlows.length === 0) return;
+        
+        let significantChanges = false;
+        
+        // Check if these mutations are significant enough to re-evaluate flows
+        for (const mutation of mutations) {
+          // Added or removed nodes might affect our selectors
+          if (mutation.type === 'childList' && 
+              (mutation.addedNodes.length > 0 || mutation.removedNodes.length > 0)) {
+            significantChanges = true;
+            break;
+          }
+        }
+        
+        if (significantChanges) {
+          // Debounce the refresh to avoid excessive processing
+          if (this._domChangeTimer !== null) {
+            clearTimeout(this._domChangeTimer);
+          }
+          
+          this._domChangeTimer = setTimeout(() => {
+            console.debug('[DAP] Significant DOM changes detected, rechecking pending flows');
+            this.checkPendingFlows();
+          }, 200);
+        }
+      });
+      
+      // Start observing the document body
+      if (document.body) {
+        this._domObserver.observe(document.body, {
+          childList: true,
+          subtree: true
+        });
+      }
+    } catch (err) {
+      console.warn('[DAP] Unable to setup DOM observer:', err);
+    }
+  }
+  
+  /**
+   * Check if any pending flows can now be displayed after DOM changes
+   */
+  private checkPendingFlows(): void {
+    if (this._pendingFlows.length === 0) return;
+    
+    console.debug(`[DAP] Checking ${this._pendingFlows.length} pending flows after DOM changes`);
+    
+    // Copy the array to avoid modification issues during iteration
+    const pendingFlows = [...this._pendingFlows];
+    
+    // Clear the pending flows list before processing
+    this._pendingFlows = [];
+    
+    // Try to display each pending flow with the updated DOM
+    pendingFlows.forEach(flow => {
+      console.debug(`[DAP] Rechecking flow after DOM changes: ${flow.id}`);
+      this.evaluateFlowVisibility(flow);
+    });
+  }
+
+  /**
+   * Get the singleton instance of the FlowManager
+   */
+  public static getInstance(): FlowManager {
+    if (!this._instance) {
+      this._instance = new FlowManager();
+    }
+    return this._instance;
+  }
+
+  /**
+   * Register a single flow with the manager
+   * @param flow The flow to register
+   */
+  public registerFlow(flow: ContextualFlow): void {
+    this._flows.push(flow);
+    this.evaluateFlowVisibility(flow);
+  }
+
+  /**
+   * Register multiple flows with the manager
+   * @param flows The flows to register
+   */
+  public registerFlows(flows: ContextualFlow[]): void {
+    this._flows.push(...flows);
+    this.refreshFlowVisibility();
+  }
+
+  /**
+   * Get flows that match the specified context
+   * @param context Context to match against
+   * @returns Array of matching flows
+   */
+  public getFlowsForContext(context: { screenId?: string; elementSelector?: string }): ContextualFlow[] {
+    return this._flows.filter(flow => {
+      // Match by screen ID if specified, normalizing paths by removing leading slashes
+      if (context.screenId && flow.elementLocation) {
+        const normalizedContextId = context.screenId.replace(/^\/+/, '');
+        const normalizedFlowLocation = flow.elementLocation.replace(/^\/+/, '');
+        
+        if (normalizedFlowLocation !== normalizedContextId && normalizedFlowLocation !== '*') {
+          return false;
+        }
+      }
+      
+      // Match by element selector if specified
+      if (context.elementSelector && flow.elementSelector) {
+        return flow.elementSelector === context.elementSelector;
+      }
+      
+      return true;
+    });
+  }
+
+  /**
+   * Get all registered flows
+   */
+  public getAllFlows(): ContextualFlow[] {
+    return [...this._flows];
+  }
+  
+  /**
+   * Get all pending flows (flows with selectors not found in the current page)
+   */
+  public getPendingFlows(): ContextualFlow[] {
+    return [...this._pendingFlows];
+  }
+
+  /**
+   * Clear all registered flows
+   */
+  public clearFlows(): void {
+    this._flows = [];
+    this._pendingFlows = [];
+    this.clearAllIndicators();
+  }
+  
+  /**
+   * Manually add a flow to the pending list
+   * @param flow The flow to mark as pending
+   */
+  public addPendingFlow(flow: ContextualFlow): void {
+    if (!this._pendingFlows.some(pFlow => pFlow.id === flow.id)) {
+      this._pendingFlows.push(flow);
+    }
+  }
+
+  /**
+   * Handle location context change
+   */
+  private handleLocationChange(context: { currentPath: string; screenId?: string }): void {
+    console.debug('[DAP] Location context changed:', context);
+    
+    // Store the previous screen ID for context tracking
+    this._previousScreenId = context.screenId;
+    
+    // Clear all current indicators since we're potentially on a new page
+    this.clearAllIndicators();
+    
+    // Give the DOM a moment to update before evaluating flows
+    // This helps with single page applications where route changes don't fully reload the page
+    setTimeout(() => {
+      console.debug(`[DAP] Evaluating flows for new location context`);
+      
+      // Re-evaluate all flows for the new context (both registered and pending)
+      const allFlows = [...this._flows, ...this._pendingFlows];
+      
+      // Clear pending flows before re-evaluation
+      this._pendingFlows = [];
+      
+      // Process each flow for the new location
+      allFlows.forEach(flow => {
+        console.debug(`[DAP] Re-evaluating flow for new location: ${flow.id}`);
+        this.evaluateFlowVisibility(flow);
+      });
+      
+      console.debug(`[DAP] Location change evaluation complete. Pending flows: ${this._pendingFlows.length}`);
+    }, 100); // Small delay to allow DOM updates
+  }
+
+  /**
+   * Refresh visibility for all registered flows
+   * @param forceRetry Force retry even for indicators that were previously not found
+   */
+  private refreshFlowVisibility(forceRetry: boolean = false): void {
+    // Remove all indicators
+    this.clearAllIndicators();
+    
+    // Reset retry counters if forcing retry
+    if (forceRetry) {
+      this._retryAttempts.clear();
+    }
+    
+    // Re-evaluate all flows for the current context
+    this._flows.forEach(flow => this.evaluateFlowVisibility(flow));
+    
+    // If we want to force retry for all flows that weren't found
+    if (forceRetry && document.readyState === 'complete') {
+      // Schedule another check after everything is loaded
+      setTimeout(() => {
+        console.debug('[DAP] Running secondary flow visibility check after page load');
+        
+        // Try again for any flows that might have been missed
+        if (this._pendingFlows.length > 0) {
+          const pendingFlows = [...this._pendingFlows];
+          this._pendingFlows = [];
+          
+          pendingFlows.forEach(flow => {
+            console.debug(`[DAP] Re-attempting to display pending flow: ${flow.id}`);
+            this.evaluateFlowVisibility(flow);
+          });
+        }
+      }, 500);
+    }
+  }
+
+  /**
+   * Evaluate whether a flow should be visible in the current context
+   */
+  private evaluateFlowVisibility(flow: ContextualFlow): void {
+    const currentContext = this._locationService.getContext();
+    
+    console.debug(`[DAP] Evaluating flow visibility:`, {
+      flowId: flow.id,
+      elementSelector: flow.elementSelector,
+      elementLocation: flow.elementLocation,
+      currentLocation: currentContext
+    });
+    
+    // Handle flows without element selectors (immediate trigger flows)
+    if (!flow.elementSelector) {
+      console.debug(`[DAP] Flow ${flow.id} has no elementSelector - checking location constraints`);
+      
+      // Check location constraints for immediate flows
+      if (this.matchesLocationConstraint(flow, currentContext)) {
+        console.debug(`[DAP] Immediate flow ${flow.id} matches location, triggering`);
+        // Trigger immediately if location matches
+        this.triggerFlow(flow);
+      } else {
+        console.debug(`[DAP] Immediate flow ${flow.id} doesn't match location, adding to pending`);
+        this.addToPendingIfNotExists(flow);
+      }
+      return;
+    }
+    
+    // Handle flows with element selectors
+    const matchesLocation = this.matchesLocationConstraint(flow, currentContext);
+    
+    if (matchesLocation) {
+      console.debug(`[DAP] Flow ${flow.id} matches location, attempting to add indicator`);
+      // Try to add the flow indicator
+      const wasAdded = this.addFlowIndicator(flow);
+      
+      // If the flow couldn't be added (selector not found),
+      // add it to pending flows for when the element appears
+      if (!wasAdded) {
+        console.debug(`[DAP] Indicator not added for flow ${flow.id}, adding to pending`);
+        this.addToPendingIfNotExists(flow);
+      }
+    } else {
+      console.debug(`[DAP] Flow ${flow.id} doesn't match current location, adding to pending for future pages`);
+      // Flow doesn't match current location - add to pending for other pages
+      this.addToPendingIfNotExists(flow);
+    }
+  }
+  
+  /**
+   * Check if flow matches location constraint
+   */
+  private matchesLocationConstraint(flow: ContextualFlow, currentContext: any): boolean {
+    // If flow has no location constraint, always consider it for current screen
+    if (!flow.elementLocation) {
+      return true;
+    }
+    
+    // Normalize paths by removing leading forward slashes
+    const normalizedFlowLocation = flow.elementLocation.replace(/^\/+/, '');
+    const normalizedScreenId = currentContext.screenId ? currentContext.screenId.replace(/^\/+/, '') : '';
+    const normalizedCurrentPath = currentContext.currentPath ? currentContext.currentPath.replace(/^\/+/, '') : '';
+    
+    // Check if flow should be visible on current screen
+    return normalizedFlowLocation === normalizedScreenId || 
+           normalizedFlowLocation === '*' ||
+           normalizedFlowLocation === normalizedCurrentPath;
+  }
+  
+  /**
+   * Add flow to pending list if it doesn't already exist
+   */
+  private addToPendingIfNotExists(flow: ContextualFlow): void {
+    if (!this._pendingFlows.some(pFlow => pFlow.id === flow.id)) {
+      this._pendingFlows.push(flow);
+    }
+  }
+
+  /**
+   * Add a visual indicator for an available flow
+   * @returns boolean indicating whether the indicator was successfully added
+   */
+  private addFlowIndicator(flow: ContextualFlow): boolean {
+    if (!flow.elementSelector) return false;
+    
+    try {
+      // Check if the selector looks like XPath
+      const isXPath = flow.elementSelector.startsWith('/') || 
+                     flow.elementSelector.startsWith('./') || 
+                     flow.elementSelector.startsWith('//') || 
+                     flow.elementSelector.includes('@') || 
+                     /\[\d+\]/.test(flow.elementSelector);
+      
+      if (isXPath) {
+        console.debug(`[DAP] Using XPath selector: ${flow.elementSelector}`);
+      }
+      
+      // Use resolveSelector instead of document.querySelector to support XPath
+      const element = resolveSelector(flow.elementSelector);
+      if (!element) {
+        console.debug(`[DAP] Element not found for selector: ${flow.elementSelector}`);
+        
+        // Page is still loading or element might be part of dynamic content
+        // Use retry logic instead of immediately failing
+        if (!flow.id) {
+          console.debug(`[DAP] Cannot schedule retry for flow without ID`);
+          return false;
+        }
+        
+        // Get current retry count
+        const retryCount = this._retryAttempts.get(flow.id) || 0;
+        
+        // Check if we've hit the max retry count
+        if (retryCount >= this._maxRetryAttempts) {
+          console.debug(`[DAP] Maximum retry attempts (${this._maxRetryAttempts}) reached for flow: ${flow.id}`);
+          this._retryAttempts.delete(flow.id); // Reset for future attempts
+          return false;
+        }
+        
+        // Schedule a retry with exponential backoff
+        const delay = Math.min(300 * Math.pow(2, retryCount), 5000); // Cap at 5 seconds
+        console.debug(`[DAP] Scheduling retry ${retryCount + 1}/${this._maxRetryAttempts} in ${delay}ms for flow: ${flow.id}`);
+        
+        // Update retry counter
+        this._retryAttempts.set(flow.id, retryCount + 1);
+        
+        // Schedule retry
+        setTimeout(() => {
+          // Try again
+          const retryResult = this.addFlowIndicator(flow);
+          
+          // If we've successfully added the flow on retry, remove it from pending
+          if (retryResult && flow.id && this._pendingFlows.some(pFlow => pFlow.id === flow.id)) {
+            this._pendingFlows = this._pendingFlows.filter(pFlow => pFlow.id !== flow.id);
+          }
+        }, delay);
+        
+        // Return true so we don't immediately mark as pending
+        return true;
+      }
+      
+      // Create indicator if it doesn't exist for this element
+      if (!this._activeIndicators.has(flow.elementSelector)) {
+        // Get the parent element position and style
+        const targetElement = element as HTMLElement;
+        
+        // Create container for positioning - this will be relative to the parent
+        const container = document.createElement('div');
+        container.className = 'dap-indicator-container';
+        container.style.position = 'relative'; 
+        container.style.zIndex = '9999';
+        container.style.width = '0';
+        container.style.height = '0';
+        container.style.overflow = 'visible';
+        
+        // Create the indicator
+        const indicator = document.createElement('div');
+        indicator.className = 'dap-experience-indicator';
+        indicator.setAttribute('role', 'button');
+        indicator.setAttribute('aria-label', 'View available content');
+        indicator.setAttribute('tabindex', '0');
+        indicator.dataset.selector = flow.elementSelector;
+        
+        // SVG light bulb icon (beautified)
+        indicator.innerHTML = `
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <path d="M12 2C7.58172 2 4 5.58172 4 10C4 12.8492 5.62545 15.3373 8 16.584V19C8 19.5523 8.44772 20 9 20H15C15.5523 20 16 19.5523 16 19V16.584C18.3745 15.3373 20 12.8492 20 10C20 5.58172 16.4183 2 12 2Z" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/>
+            <path d="M10 22H14" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+          </svg>
+        `;
+        
+        // Add the indicator to the container
+        container.appendChild(indicator);
+        
+        // The magic: insert the container directly after the target element in the DOM
+        // This ensures the indicator will always follow its parent during scroll/layout changes
+        if (targetElement.parentNode) {
+          targetElement.parentNode.insertBefore(container, targetElement.nextSibling);
+          console.debug(`[DAP] Added indicator container to DOM after target element`);
+          
+          // Position the indicator relative to its parent
+          this.positionIndicatorRelative(indicator, targetElement);
+          
+          // Watch for resize changes to reposition
+          const resizeObserver = new ResizeObserver(() => {
+            this.positionIndicatorRelative(indicator, targetElement);
+          });
+          
+          try {
+            resizeObserver.observe(targetElement);
+          } catch (err) {
+            console.warn('[DAP] ResizeObserver not supported, indicator may not reposition correctly');
+          }
+          
+          // Add mutation observer to detect style/attribute changes
+          try {
+            const mutationObserver = new MutationObserver((mutations) => {
+              // Only check for style or class changes that might affect positioning
+              const shouldUpdate = mutations.some(m => 
+                m.type === 'attributes' && 
+                (m.attributeName === 'style' || m.attributeName === 'class')
+              );
+              
+              if (shouldUpdate) {
+                this.positionIndicatorRelative(indicator, targetElement);
+              }
+            });
+            
+            mutationObserver.observe(targetElement, { 
+              attributes: true,
+              attributeFilter: ['style', 'class']
+            });
+          } catch (err) {
+            console.warn('[DAP] MutationObserver not supported, indicator may not update on style changes');
+          }
+          
+          // Attach event listeners for the flow
+          this.attachTriggerHandler(indicator, targetElement, flow);
+          
+          // Store the container for later cleanup
+          this._activeIndicators.set(flow.elementSelector, container);
+          
+          // Add window resize handler to ensure positioning stays correct
+          const windowResizeHandler = () => this.positionIndicatorRelative(indicator, targetElement);
+          window.addEventListener('resize', windowResizeHandler);
+          
+          if (!this._activeListeners.has('resize')) {
+            this._activeListeners.set('resize', []);
+          }
+          this._activeListeners.get('resize')!.push({
+            element: window as any as HTMLElement,
+            eventType: 'resize',
+            handler: windowResizeHandler
+          });
+        } else {
+          console.warn(`[DAP] Target element has no parent, cannot attach indicator`);
+          return false;
+        }
+        
+        console.debug(`[DAP] Added indicator for flow: ${flow.id} at selector: ${flow.elementSelector}`);
+      }
+      
+      // Successfully added indicator
+      return true;
+    } catch (err) {
+      console.error('[DAP] Error adding flow indicator:', err);
+      return false;
+    }
+  }
+
+  // This method has been incorporated directly into addFlowIndicator
+  
+  /**
+   * Position indicator directly relative to its target element
+   * This uses absolute positioning relative to the target's box model
+   */
+  private positionIndicatorRelative(indicator: HTMLElement, targetElement: HTMLElement): void {
+    // Skip if elements are no longer in the DOM
+    if (!document.body.contains(indicator) || !document.body.contains(targetElement)) {
+      return;
+    }
+    
+    // Use requestAnimationFrame for smoother positioning
+    requestAnimationFrame(() => {
+      try {
+        // Get target element dimensions
+        const rect = targetElement.getBoundingClientRect();
+        const indicatorWidth = indicator.offsetWidth || 36;
+        const indicatorHeight = indicator.offsetHeight || 36;
+        
+        // Position at the top-right corner of the target element
+        indicator.style.position = 'absolute';
+        indicator.style.top = `-${indicatorHeight / 2}px`; 
+        indicator.style.left = `${rect.width - (indicatorWidth / 2)}px`;
+        indicator.style.zIndex = '9999';
+        
+        // Add debug logging
+        console.debug(`[DAP] Positioned indicator relative to target element`);
+      } catch (err) {
+        console.error('[DAP] Error positioning indicator:', err);
+      }
+    });
+  }
+
+  /**
+   * Attach event handlers based on trigger type
+   */
+  private attachTriggerHandler(
+    indicator: HTMLElement, 
+    targetElement: HTMLElement, 
+    flow: ContextualFlow
+  ): void {
+    const trigger = flow.elementTrigger?.toLowerCase() || '';
+    let eventType: string;
+    
+    // Map trigger to event type
+    if (trigger.includes('click')) {
+      eventType = 'click';
+    } else if (trigger.includes('hover')) {
+      eventType = 'mouseenter';
+    } else if (trigger.includes('focus')) {
+      eventType = 'focus';
+    } else {
+      // Default to click
+      eventType = 'click';
+    }
+    
+    // Attach event listener to both indicator and target if needed
+    const triggerHandler = () => this.triggerFlow(flow);
+    
+    // Indicator always uses click and keydown (for accessibility)
+    indicator.addEventListener('click', triggerHandler);
+    indicator.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        triggerHandler();
+      }
+    });
+    
+    // For hover/focus triggers, also attach to the target element
+    if (eventType !== 'click') {
+      targetElement.addEventListener(eventType, triggerHandler);
+      
+      // Track this additional handler for cleanup
+      if (!this._activeListeners.has(flow.elementSelector!)) {
+        this._activeListeners.set(flow.elementSelector!, []);
+      }
+      
+      this._activeListeners.get(flow.elementSelector!)!.push({
+        element: targetElement,
+        eventType,
+        handler: triggerHandler
+      });
+    }
+  }
+
+  /**
+   * Trigger a flow
+   */
+  private triggerFlow(flow: ContextualFlow): void {
+    console.debug(`[DAP] triggerFlow called for flow: ${flow.id}, _flowInProgress: ${this._flowInProgress}`);
+    
+    // Special handling for flows without elementSelector (immediate flows)
+    if (!flow.elementSelector) {
+      console.debug(`[DAP] Triggering immediate flow (no elementSelector): ${flow.id}`);
+      this.renderFlow(flow, true); // Always treat as new flow
+      return;
+    }
+    
+    // If no active flow, this is a new flow start
+    if (!this._flowInProgress) {
+      this.startNewFlow(flow);
+      return;
+    }
+    
+    // If a flow is already active, this should be a step trigger within that flow
+    // Check if this trigger belongs to the current active step
+    const stepId = this.extractStepIdFromFlow(flow);
+    
+    if (!stepId) {
+      console.debug(`[DAP] Ignoring trigger - no step ID found for flow: ${flow.id}`);
+      return;
+    }
+    
+    // Check if this is the current active step
+    if (this._currentActiveStep && this._currentActiveStep !== stepId) {
+      console.debug(`[DAP] Trigger ignored - not for current active step. Current: ${this._currentActiveStep}, Trigger: ${stepId}`);
+      return;
+    }
+    
+    // Check if current step has already been triggered
+    if (this._activeStepTriggered) {
+      console.debug(`[DAP] Trigger ignored because step already triggered: ${stepId}`);
+      return;
+    }
+    
+    // Valid step trigger - execute it
+    this.executeStepTrigger(flow, stepId);
+  }
+  
+  /**
+   * Start a new flow
+   */
+  private startNewFlow(flow: ContextualFlow): void {
+    console.debug(`[DAP] Starting new flow: ${flow.id}, setting _flowInProgress = true`);
+    
+    // Mark flow as in progress
+    this._flowInProgress = true;
+    this._activeFlowId = flow.id;
+    this._activeStepTriggered = false;
+    this._currentActiveStep = this.extractStepIdFromFlow(flow);
+    
+    console.debug(`[DAP] Flow state: _flowInProgress=${this._flowInProgress}, _activeFlowId=${this._activeFlowId}`);
+    
+    this.renderFlow(flow, true); // true = new flow
+  }
+  
+  /**
+   * Execute a step trigger within an active flow
+   */
+  private executeStepTrigger(flow: ContextualFlow, stepId: string): void {
+    // Mark this step as triggered
+    this._activeStepTriggered = true;
+    
+    console.debug(`[DAP] Executing step trigger: ${stepId} in flow: ${flow.id}`);
+    
+    this.renderFlow(flow, false); // false = step trigger, not new flow
+  }
+  
+  /**
+   * Extract step ID from flow (helper method)
+   */
+  private extractStepIdFromFlow(flow: ContextualFlow): string | null {
+    // Try to get step ID from payload or flow structure
+    if (flow.payload?.steps && Array.isArray(flow.payload.steps)) {
+      // For multi-step flows, get the current step ID
+      const currentStep = flow.payload.steps[0]; // Assuming first step for triggers
+      return currentStep?.stepId || null;
+    }
+    
+    // For single-step flows, use flow ID as step ID
+    return flow.id;
+  }
+  
+  /**
+   * Render a flow (common logic for new flows and step triggers)
+   */
+  private renderFlow(flow: ContextualFlow, isNewFlow: boolean): void {
+    // Import dynamically to avoid circular dependencies
+    import('../experiences/registry').then(({ getRenderer }) => {
+      const renderer = getRenderer(flow.type);
+      if (renderer) {
+        // Create a wrapped renderer that handles flow completion
+        const completionTracker = {
+          onComplete: () => {
+            console.debug(`[DAP] Flow ${flow.id} completed`);
+            this.onFlowComplete();
+          },
+          onStepAdvance: (stepId: string) => {
+            // Called when advancing to next step - reset step-level trigger state
+            console.debug(`[DAP] Advancing to step: ${stepId}`);
+            this.onStepAdvance(stepId);
+          }
+        };
+        
+        // Pass the flow and completion tracker to the renderer
+        renderer({
+          id: flow.id,
+          type: flow.type,
+          payload: {
+            ...flow.payload,
+            _completionTracker: completionTracker
+          }
+        });
+        
+        // Reset step trigger state after successful rendering
+        // This allows subsequent step triggers to execute properly
+        if (!isNewFlow) {
+          this._activeStepTriggered = false;
+        }
+      } else {
+        console.warn(`[DAP] No renderer found for flow type: ${flow.type}`);
+        // Reset the flow state if no renderer found
+        if (isNewFlow) {
+          this.onFlowComplete();
+        } else {
+          // Reset step trigger state for step triggers with no renderer
+          this._activeStepTriggered = false;
+        }
+      }
+    }).catch(err => {
+      console.error('[DAP] Error triggering flow:', err);
+      // Reset the flow state on error
+      if (isNewFlow) {
+        this.onFlowComplete();
+      } else {
+        // Reset step trigger state on error
+        this._activeStepTriggered = false;
+      }
+    });
+  }
+  
+  /**
+   * Handle flow completion
+   */
+  private onFlowComplete(): void {
+    console.debug(`[DAP] Flow completed: ${this._activeFlowId}, setting _flowInProgress = false`);
+    this._flowInProgress = false;
+    this._activeFlowId = null;
+    this._activeStepTriggered = false;
+    this._currentActiveStep = null;
+    console.debug(`[DAP] Flow state reset: _flowInProgress=${this._flowInProgress}`);
+  }
+  
+  /**
+   * Handle step advancement
+   */
+  private onStepAdvance(stepId: string): void {
+    this._activeStepTriggered = false; // Reset for new step
+    this._currentActiveStep = stepId;
+  }
+
+  /**
+   * Clear all indicators and event listeners
+   */
+  private clearAllIndicators(): void {
+    // Remove all indicator container elements
+    this._activeIndicators.forEach((element, key) => {
+      if (element.tagName) {
+        // Remove any type of container/indicator element
+        if (element.className === 'dap-indicator-container' || 
+            element.className === 'dap-indicator-wrapper' ||
+            element.className === 'dap-experience-indicator') {
+          element.remove();
+        }
+      }
+    });
+    this._activeIndicators.clear();
+    
+    // Remove all attached event listeners
+    this._activeListeners.forEach((listeners, selector) => {
+      listeners.forEach(({ element, eventType, handler }) => {
+        element.removeEventListener(eventType, handler);
+      });
+    });
+    this._activeListeners.clear();
+    
+    console.debug('[DAP] Cleared all indicators and event listeners');
+  }
+
+  /**
+   * Inject indicator styles into the document
+   */
+  private injectIndicatorStyles(): void {
+    if (this._indicatorStyle) return;
+    
+    this._indicatorStyle = document.createElement('style');
+    this._indicatorStyle.id = 'dap-experience-indicator-style';
+    this._indicatorStyle.type = 'text/css';
+    this._indicatorStyle.textContent = `
+      .dap-indicator-container {
+        pointer-events: none;
+        z-index: 9999;
+        position: relative;
+        display: block;
+      }
+      
+      .dap-experience-indicator {
+        width: 36px;
+        height: 36px;
+        cursor: pointer;
+        background-color: rgba(255, 196, 0, 0.95); /* Yellow color */
+        border-radius: 50%;
+        padding: 6px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        color: #000000;
+        box-shadow: 0 2px 6px rgba(0,0,0,0.25);
+        transition: all 0.2s ease-in-out;
+        animation: dap-indicator-pulse 2s infinite;
+        pointer-events: auto;
+      }
+
+      .dap-experience-indicator:hover,
+      .dap-experience-indicator:focus {
+        transform: scale(1.1);
+        background-color: rgba(255, 196, 0, 1);
+        outline: none;
+        box-shadow: 0 4px 8px rgba(0,0,0,0.3);
+      }
+
+      .dap-experience-indicator svg {
+        width: 20px;
+        height: 20px;
+        fill: none;
+        stroke: currentColor;
+        filter: drop-shadow(0 1px 1px rgba(0,0,0,0.2));
+      }
+      
+      @keyframes dap-indicator-pulse {
+        0% { box-shadow: 0 0 0 0 rgba(255, 196, 0, 0.4); }
+        70% { box-shadow: 0 0 0 8px rgba(255, 196, 0, 0); }
+        100% { box-shadow: 0 0 0 0 rgba(255, 196, 0, 0); }
+      }
+      
+      @media (max-width: 768px) {
+        .dap-experience-indicator {
+          width: 42px;
+          height: 42px;
+          padding: 8px;
+        }
+        
+        .dap-experience-indicator svg {
+          width: 24px;
+          height: 24px;
+        }
+      }
+    `;
+    
+    document.head.appendChild(this._indicatorStyle);
+  }
+}
+
+// Export singleton instance
+export const flowManager = FlowManager.getInstance();