@aladinbs/react-guided-tour 1.0.2 → 1.1.0

package/dist/index.esm.js

@@ -1,4 +1,4 @@
-import require$$0, { useMemo, useState, useEffect, useCallback, createContext, useContext, useRef } from 'react';
+import React, { useRef, useCallback, useMemo, useState, useEffect, createContext, useContext, Component } from 'react';
 
 class TourStorage {
     constructor(key) {
@@ -95,6 +95,10 @@ class TourStorage {
     }
 }
 
+/**
+ * Core tour engine that manages tour state, navigation, and lifecycle.
+ * Handles step progression, state persistence, and event emission.
+ */
 class TourEngine {
     constructor(config) {
         this.listeners = new Map();
@@ -125,6 +129,9 @@ class TourEngine {
     getConfig() {
         return { ...this.config };
     }
+    /**
+     * Starts the tour from the current step index.
+     */
     async start() {
         try {
             this.setState({
@@ -134,14 +141,22 @@ class TourEngine {
             });
             this.emit('tour-start', { tourId: this.config.id });
             await this.goToStep(this.state.currentStepIndex);
-            // STOP HERE - don't auto-advance
             return;
         }
         catch (error) {
-            console.error('Error in TourEngine.start():', error);
-            this.handleError(error);
+            const errorObj = error;
+            console.error('Error in TourEngine.start():', errorObj);
+            this.handleError(errorObj);
+            this.setState({
+                isRunning: false,
+                isLoading: false
+            });
+            throw errorObj;
         }
     }
+    /**
+     * Advances to the next step in the tour.
+     */
     async next() {
         if (!this.state.isRunning) {
             return;
@@ -149,28 +164,34 @@ class TourEngine {
         try {
             const currentStep = this.getCurrentStep();
             if (!currentStep) {
-                return;
+                throw new Error('No current step available for next operation');
             }
-            // Execute after step hook
             if (currentStep.afterStep) {
-                await currentStep.afterStep();
+                try {
+                    await currentStep.afterStep();
+                }
+                catch (hookError) {
+                    console.warn('Error in afterStep hook:', hookError);
+                }
             }
-            // Mark step as completed
             this.markStepCompleted(currentStep.id);
-            // Check if this is the last step
             if (this.state.currentStepIndex >= this.state.totalSteps - 1) {
                 await this.complete();
                 return;
             }
-            // Go to next step
             const nextStepIndex = this.state.currentStepIndex + 1;
             await this.goToStep(nextStepIndex);
         }
         catch (error) {
-            console.error('Error in TourEngine.next():', error);
-            this.handleError(error);
+            const errorObj = error;
+            console.error('Error in TourEngine.next():', errorObj);
+            this.handleError(errorObj);
+            throw errorObj;
         }
     }
+    /**
+     * Goes back to the previous step in the tour.
+     */
     async previous() {
         if (!this.state.isRunning || this.state.currentStepIndex <= 0)
             return;
@@ -181,40 +202,65 @@ class TourEngine {
             this.handleError(error);
         }
     }
+    /**
+     * Navigates to a specific step by index.
+     */
     async goToStep(index) {
-        if (index < 0 || index >= this.state.totalSteps)
-            return;
+        if (index < 0 || index >= this.state.totalSteps) {
+            throw new Error(`Invalid step index: ${index}. Must be between 0 and ${this.state.totalSteps - 1}`);
+        }
         try {
             this.setState({ isLoading: true });
             const step = this.config.steps[index];
-            // Execute before step hook
             if (step.beforeStep) {
-                await step.beforeStep();
+                try {
+                    await step.beforeStep();
+                }
+                catch (hookError) {
+                    console.warn('Error in beforeStep hook:', hookError);
+                }
             }
-            // Wait for element if specified
             if (step.waitForElement && step.target) {
-                await this.waitForElement(step.target, step.waitTimeout || 5000);
+                try {
+                    await this.waitForElement(step.target, step.waitTimeout || 5000);
+                }
+                catch (waitError) {
+                    console.warn(`Element not found: ${step.target}. Continuing anyway.`);
+                }
             }
             this.setState({
                 currentStepIndex: index,
                 currentStep: step,
                 isLoading: false,
             });
-            // Save state if persistence is enabled
             if (this.config.storage?.remember) {
-                this.storage.saveState(this.state);
+                try {
+                    this.storage.saveState(this.state);
+                }
+                catch (storageError) {
+                    console.warn('Failed to save tour state:', storageError);
+                }
             }
-            // Emit step change event
             this.emit('step-change', { step, index });
             if (this.config.onStepChange) {
-                this.config.onStepChange(step, index);
+                try {
+                    this.config.onStepChange(step, index);
+                }
+                catch (callbackError) {
+                    console.warn('Error in onStepChange callback:', callbackError);
+                }
             }
         }
         catch (error) {
             this.setState({ isLoading: false });
-            this.handleError(error);
+            const errorObj = error;
+            this.handleError(errorObj);
+            throw errorObj;
         }
     }
+    /**
+     * Skips the current tour and marks it as skipped.
+     */
     async skip() {
         if (!this.state.isRunning)
             return;
@@ -228,7 +274,6 @@ class TourEngine {
             if (this.config.onSkip) {
                 this.config.onSkip();
             }
-            // Save skip state to localStorage
             if (this.config.storage?.remember) {
                 this.storage.saveSkip();
             }
@@ -239,6 +284,9 @@ class TourEngine {
             this.handleError(error);
         }
     }
+    /**
+     * Completes the tour and marks it as finished.
+     */
     async complete() {
         try {
             this.setState({ isRunning: false, isCompleted: true });
@@ -246,7 +294,6 @@ class TourEngine {
             if (this.config.onComplete) {
                 this.config.onComplete();
             }
-            // Save completion state to localStorage
             if (this.config.storage?.remember) {
                 this.storage.saveCompletion();
             }
@@ -277,11 +324,17 @@ class TourEngine {
     canGoPrevious() {
         return this.state.isRunning && !this.isFirstStep() && !this.state.isLoading;
     }
+    /**
+     * Determines if the tour should be shown based on completion/skip state.
+     */
     shouldShowTour() {
         if (!this.config.storage?.remember)
             return true;
         return !this.storage.isCompleted() && !this.storage.isSkipped();
     }
+    /**
+     * Resets tour state and clears localStorage.
+     */
     resetTourState() {
         if (this.config.storage?.remember) {
             this.storage.clearState();
@@ -328,18 +381,32 @@ class TourEngine {
         }
     }
     handleError(error) {
+        const errorMessage = error.message || 'Unknown error occurred';
+        const currentStep = this.getCurrentStep();
         this.setState({
-            error: error.message,
+            error: errorMessage,
             isLoading: false,
         });
-        this.emit('error', { error, step: this.getCurrentStep() || undefined });
+        this.emit('error', {
+            error,
+            step: currentStep || undefined,
+            tourId: this.config.id,
+            stepIndex: this.state.currentStepIndex,
+            timestamp: new Date().toISOString()
+        });
+        console.error('TourEngine Error Details:', {
+            message: errorMessage,
+            stack: error.stack,
+            tourId: this.config.id,
+            currentStep: currentStep?.id,
+            stepIndex: this.state.currentStepIndex,
+            state: this.state
+        });
     }
     setState(updates) {
         this.state = { ...this.state, ...updates };
-        // Emit state change event to notify subscribers
         this.emit('state-change', this.state);
     }
-    // Event system
     on(event, callback) {
         if (!this.listeners.has(event)) {
             this.listeners.set(event, new Set());
@@ -358,16 +425,18 @@ class TourEngine {
             callbacks.forEach(callback => callback(data));
         }
     }
+    /**
+     * Subscribes to tour state changes.
+     * Returns an unsubscribe function.
+     */
     subscribe(callback) {
         const handler = () => callback(this.getState());
-        // Listen to all events that might change state
         this.on('step-change', handler);
         this.on('tour-start', handler);
         this.on('tour-complete', handler);
         this.on('tour-skip', handler);
         this.on('error', handler);
         this.on('state-change', handler);
-        // Return unsubscribe function
         return () => {
             this.off('step-change', handler);
             this.off('tour-start', handler);
@@ -379,6 +448,10 @@ class TourEngine {
     }
 }
 
+/**
+ * Manages and executes tour actions with pluggable integration support.
+ * Handles clicks, navigation, and custom actions through registered integrations.
+ */
 class TourActions {
     constructor() {
         this.integrations = new Map();
@@ -389,11 +462,12 @@ class TourActions {
     unregisterIntegration(name) {
         this.integrations.delete(name);
     }
+    /**
+     * Executes a tour action using the appropriate integration or default handler.
+     */
     async execute(action, element) {
-        // Find the appropriate integration for this action
         const integration = this.findIntegration(action);
         if (!integration) {
-            // Fallback to default action handling
             await this.executeDefault(action, element);
             return;
         }
@@ -402,7 +476,6 @@ class TourActions {
         }
         catch (error) {
             console.error(`Integration ${integration.name} failed to execute action:`, error);
-            // Fallback to default action handling
             await this.executeDefault(action, element);
         }
     }
@@ -414,6 +487,9 @@ class TourActions {
         }
         return null;
     }
+    /**
+     * Default action handler for built-in action types.
+     */
     async executeDefault(action, element) {
         const delay = action.delay || 0;
         if (delay > 0) {
@@ -427,7 +503,6 @@ class TourActions {
                 await this.handleNavigate(action);
                 break;
             case 'highlight':
-                // Highlighting is handled by the UI components
                 break;
             case 'custom':
                 if (action.handler) {
@@ -446,11 +521,8 @@ class TourActions {
         if (!targetElement) {
             throw new Error(`Click target not found: ${action.target}`);
         }
-        // Ensure element is visible and clickable
         targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
-        // Wait a bit for scroll to complete
         await this.sleep(300);
-        // Dispatch click event
         const clickEvent = new MouseEvent('click', {
             bubbles: true,
             cancelable: true,
@@ -462,17 +534,14 @@ class TourActions {
         if (!action.target) {
             throw new Error('Navigate action requires a target URL');
         }
-        // Check if it's a hash navigation (same page)
         if (action.target.startsWith('#')) {
             window.location.hash = action.target;
             return;
         }
-        // Check if it's a relative path
         if (action.target.startsWith('/')) {
             window.location.pathname = action.target;
             return;
         }
-        // Full URL navigation
         window.location.href = action.target;
     }
     sleep(ms) {
@@ -822,7 +891,7 @@ function requireReactJsxRuntime_development () {
 	        object.$$typeof === REACT_ELEMENT_TYPE
 	      );
 	    }
-	    var React = require$$0,
+	    var React$1 = React,
 	      REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element"),
 	      REACT_PORTAL_TYPE = Symbol.for("react.portal"),
 	      REACT_FRAGMENT_TYPE = Symbol.for("react.fragment"),
@@ -838,7 +907,7 @@ function requireReactJsxRuntime_development () {
 	      REACT_ACTIVITY_TYPE = Symbol.for("react.activity"),
 	      REACT_CLIENT_REFERENCE = Symbol.for("react.client.reference"),
 	      ReactSharedInternals =
-	        React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+	        React$1.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
 	      hasOwnProperty = Object.prototype.hasOwnProperty,
 	      isArrayImpl = Array.isArray,
 	      createTask = console.createTask
@@ -846,15 +915,15 @@ function requireReactJsxRuntime_development () {
 	        : function () {
 	            return null;
 	          };
-	    React = {
+	    React$1 = {
 	      react_stack_bottom_frame: function (callStackForError) {
 	        return callStackForError();
 	      }
 	    };
 	    var specialPropKeyWarningShown;
 	    var didWarnAboutElementRef = {};
-	    var unknownOwnerDebugStack = React.react_stack_bottom_frame.bind(
-	      React,
+	    var unknownOwnerDebugStack = React$1.react_stack_bottom_frame.bind(
+	      React$1,
 	      UnknownOwner
 	    )();
 	    var unknownOwnerDebugTask = createTask(getTaskName(UnknownOwner));
@@ -900,7 +969,124 @@ if (process.env.NODE_ENV === 'production') {
 
 var jsxRuntimeExports = jsxRuntime.exports;
 
+function useErrorHandler(options = {}) {
+    const { onError, logErrors = true, retryAttempts = 0, retryDelay = 1000, } = options;
+    const retryCountRef = useRef(new Map());
+    const handleError = useCallback((error, context) => {
+        if (logErrors) {
+            console.error(`Tour Error${context ? ` in ${context}` : ''}:`, error);
+        }
+        if (onError) {
+            try {
+                onError(error, context);
+            }
+            catch (handlerError) {
+                console.error('Error in custom error handler:', handlerError);
+            }
+        }
+    }, [onError, logErrors]);
+    const handleAsyncError = useCallback(async (asyncFn, context, fallback) => {
+        const contextKey = context || 'unknown';
+        const currentRetries = retryCountRef.current.get(contextKey) || 0;
+        try {
+            const result = await asyncFn();
+            retryCountRef.current.delete(contextKey);
+            return result;
+        }
+        catch (error) {
+            handleError(error, context);
+            if (currentRetries < retryAttempts) {
+                retryCountRef.current.set(contextKey, currentRetries + 1);
+                await new Promise(resolve => setTimeout(resolve, retryDelay));
+                return handleAsyncError(asyncFn, context, fallback);
+            }
+            retryCountRef.current.delete(contextKey);
+            return fallback;
+        }
+    }, [handleError, retryAttempts, retryDelay]);
+    const wrapFunction = useCallback((fn, context) => {
+        return ((...args) => {
+            try {
+                return fn(...args);
+            }
+            catch (error) {
+                handleError(error, context);
+                throw error;
+            }
+        });
+    }, [handleError]);
+    const wrapAsyncFunction = useCallback((fn, context) => {
+        return (async (...args) => {
+            try {
+                return await fn(...args);
+            }
+            catch (error) {
+                handleError(error, context);
+                throw error; // Re-throw to maintain original behavior
+            }
+        });
+    }, [handleError]);
+    return {
+        handleError,
+        handleAsyncError,
+        wrapFunction,
+        wrapAsyncFunction,
+    };
+}
+// Utility function for creating error-safe async operations
+function createSafeAsyncOperation(operation, options = {}) {
+    const { context, fallback, onError, retryAttempts = 0, retryDelay = 1000, } = options;
+    return async () => {
+        let attempts = 0;
+        while (attempts <= retryAttempts) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                const errorObj = error;
+                // Log error
+                console.error(`Error in ${context || 'async operation'} (attempt ${attempts + 1}):`, errorObj);
+                // Call custom error handler
+                if (onError) {
+                    onError(errorObj);
+                }
+                attempts++;
+                // If we've exhausted retries, return fallback
+                if (attempts > retryAttempts) {
+                    return fallback;
+                }
+                // Wait before retrying
+                if (retryDelay > 0) {
+                    await new Promise(resolve => setTimeout(resolve, retryDelay));
+                }
+            }
+        }
+        return fallback;
+    };
+}
+// Error boundary hook for functional components
+function useErrorBoundary() {
+    const handleError = useCallback((error, _errorInfo) => {
+        // This will be caught by the nearest ErrorBoundary
+        throw error;
+    }, []);
+    return { handleError };
+}
+
+/**
+ * Hook that creates and manages a tour engine instance.
+ * Provides tour control methods and state management with error handling.
+ */
 function useTourEngine(config) {
+    // Use regular error handler to avoid ToastProvider dependency issues
+    const errorHandler = useErrorHandler({
+        onError: (error, context) => {
+            console.error(`Tour Engine Error in ${context}:`, error);
+        },
+        retryAttempts: 1,
+        retryDelay: 500,
+    });
+    const { handleAsyncError } = errorHandler;
     const actions = useMemo(() => new TourActions(), []);
     const engine = useMemo(() => {
         const tourEngine = new TourEngine(config);
@@ -912,34 +1098,31 @@ function useTourEngine(config) {
         return unsubscribe;
     }, [engine]);
     const start = useCallback(async () => {
-        try {
-            await engine.start();
-        }
-        catch (error) {
-            console.error('Error in useTourEngine.start():', error);
-        }
-    }, [engine]);
+        await handleAsyncError(() => engine.start(), 'tour start');
+    }, [engine, handleAsyncError]);
     const stop = useCallback(async () => {
         await engine.stop();
     }, [engine]);
     const next = useCallback(async () => {
-        const currentStep = engine.getCurrentStep();
-        if (currentStep?.action) {
-            // Execute the step action first
-            await actions.execute(currentStep.action);
-        }
-        await engine.next();
-    }, [engine, actions]);
+        await handleAsyncError(async () => {
+            const currentStep = engine.getCurrentStep();
+            if (currentStep?.action) {
+                // Execute the step action first
+                await actions.execute(currentStep.action);
+            }
+            await engine.next();
+        }, 'tour next');
+    }, [engine, actions, handleAsyncError]);
     const previous = useCallback(async () => {
-        await engine.previous();
-    }, [engine]);
+        await handleAsyncError(() => engine.previous(), 'tour previous');
+    }, [engine, handleAsyncError]);
     const skip = useCallback(async () => {
-        await engine.skip();
-    }, [engine]);
+        await handleAsyncError(() => engine.skip(), 'tour skip');
+    }, [engine, handleAsyncError]);
     const goToStep = useCallback(async (index) => {
-        await engine.goToStep(index);
-    }, [engine]);
-    return {
+        await handleAsyncError(() => engine.goToStep(index), `tour goToStep(${index})`);
+    }, [engine, handleAsyncError]);
+    const memoizedReturn = useMemo(() => ({
         state,
         start,
         stop,
@@ -954,7 +1137,8 @@ function useTourEngine(config) {
         currentStep: engine.getCurrentStep(),
         engine,
         actions,
-    };
+    }), [state, start, stop, next, previous, skip, goToStep, engine, actions]);
+    return memoizedReturn;
 }
 
 const TourContext = createContext(null);
@@ -983,16 +1167,24 @@ const defaultTheme = {
         maxWidth: '384px',
     },
 };
-function TourProvider({ config, children }) {
+/**
+ * Main provider component that initializes the tour system and provides context.
+ * Wraps the application with tour functionality.
+ */
+const TourProvider = React.memo(function TourProvider({ config, children }) {
     const tourEngine = useTourEngine(config);
-    const theme = { ...defaultTheme, ...config.theme };
-    const contextValue = {
+    const theme = useMemo(() => ({ ...defaultTheme, ...config.theme }), [config.theme]);
+    const contextValue = useMemo(() => ({
         ...tourEngine,
         config,
         theme,
-    };
+    }), [tourEngine, config, theme]);
     return (jsxRuntimeExports.jsx(TourContext.Provider, { value: contextValue, children: children }));
-}
+});
+/**
+ * Hook to access tour functionality and state.
+ * Must be used within a TourProvider.
+ */
 function useTour() {
     const context = useContext(TourContext);
     if (!context) {
@@ -1001,6 +1193,9 @@ function useTour() {
     return context;
 }
 
+/**
+ * Gets the absolute position of an element relative to the document.
+ */
 function getElementPosition(element) {
     const rect = element.getBoundingClientRect();
     const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
@@ -1014,6 +1209,10 @@ function getElementPosition(element) {
         bottom: rect.bottom + scrollTop,
     };
 }
+/**
+ * Calculates the optimal position for a popover relative to a target element.
+ * Falls back to alternative placements if the preferred placement doesn't fit.
+ */
 function calculatePopoverPosition(targetElement, popoverElement, preferredPlacement = 'top') {
     const targetPos = getElementPosition(targetElement);
     const popoverRect = popoverElement.getBoundingClientRect();
@@ -1023,7 +1222,7 @@ function calculatePopoverPosition(targetElement, popoverElement, preferredPlacem
         scrollTop: window.pageYOffset || document.documentElement.scrollTop,
         scrollLeft: window.pageXOffset || document.documentElement.scrollLeft,
     };
-    const spacing = 12; // Gap between target and popover
+    const spacing = 12;
     const positions = {
         top: {
             top: targetPos.top - popoverRect.height - spacing,
@@ -1051,12 +1250,12 @@ function calculatePopoverPosition(targetElement, popoverElement, preferredPlacem
             placement: 'center',
         },
     };
-    // Check if preferred placement fits in viewport
+    // Try preferred placement first
     const preferred = positions[preferredPlacement];
     if (isPositionInViewport(preferred, popoverRect, viewport)) {
         return preferred;
     }
-    // Try other placements in order of preference
+    // Try fallback placements in order of preference
     const fallbackOrder = ['bottom', 'top', 'right', 'left', 'center'];
     for (const placement of fallbackOrder) {
         if (placement === preferredPlacement)
@@ -1066,16 +1265,18 @@ function calculatePopoverPosition(targetElement, popoverElement, preferredPlacem
             return position;
         }
     }
-    // If nothing fits, use center as fallback
     return positions.center;
 }
 function isPositionInViewport(position, popoverRect, viewport) {
-    const margin = 16; // Minimum margin from viewport edges
+    const margin = 16;
     return (position.left >= viewport.scrollLeft + margin &&
         position.left + popoverRect.width <= viewport.scrollLeft + viewport.width - margin &&
         position.top >= viewport.scrollTop + margin &&
         position.top + popoverRect.height <= viewport.scrollTop + viewport.height - margin);
 }
+/**
+ * Smoothly scrolls an element into view.
+ */
 function scrollToElement(element, behavior = 'smooth') {
     element.scrollIntoView({
         behavior,
@@ -1083,6 +1284,9 @@ function scrollToElement(element, behavior = 'smooth') {
         inline: 'center',
     });
 }
+/**
+ * Checks if an element is currently visible in the viewport.
+ */
 function isElementInViewport(element) {
     const rect = element.getBoundingClientRect();
     return (rect.top >= 0 &&
@@ -1097,6 +1301,10 @@ function getViewportCenter() {
     };
 }
 
+/**
+ * Hook that manages element highlighting for tour steps.
+ * Finds target elements, positions highlights, and handles dynamic content.
+ */
 function useTourHighlight(step) {
     const [targetElement, setTargetElement] = useState(null);
     const [highlightStyle, setHighlightStyle] = useState({});
@@ -1108,6 +1316,7 @@ function useTourHighlight(step) {
             setIsVisible(false);
             return;
         }
+        // Find target element and update highlight styling
         const findAndHighlightElement = () => {
             const element = step.highlight?.element ||
                 document.querySelector(step.target);
@@ -1115,7 +1324,6 @@ function useTourHighlight(step) {
                 setTargetElement(element);
                 updateHighlightStyle(element, step.highlight);
                 setIsVisible(true);
-                // Scroll to element if not in viewport
                 if (!isElementInViewport(element)) {
                     scrollToElement(element);
                 }
@@ -1125,9 +1333,8 @@ function useTourHighlight(step) {
                 setIsVisible(false);
             }
         };
-        // Initial attempt to find element
         findAndHighlightElement();
-        // Set up mutation observer to watch for DOM changes
+        // Watch for DOM changes if element not found initially
         if (!targetElement && step.waitForElement !== false) {
             observerRef.current = new MutationObserver(() => {
                 findAndHighlightElement();
@@ -1146,7 +1353,7 @@ function useTourHighlight(step) {
             }
         };
     }, [step?.target, step?.highlight, step?.waitForElement, targetElement]);
-    // Update highlight position when element moves (e.g., during animations)
+    // Update highlight position when element moves
     useEffect(() => {
         if (!targetElement || !isVisible)
             return;
@@ -1157,7 +1364,6 @@ function useTourHighlight(step) {
         const handleResize = () => updatePosition();
         window.addEventListener('scroll', handleScroll, { passive: true });
         window.addEventListener('resize', handleResize, { passive: true });
-        // Use ResizeObserver to watch for element size changes
         let resizeObserver = null;
         if (window.ResizeObserver) {
             resizeObserver = new ResizeObserver(updatePosition);
@@ -1171,6 +1377,9 @@ function useTourHighlight(step) {
             }
         };
     }, [targetElement, isVisible, step?.highlight]);
+    /**
+     * Updates the highlight style based on element position and configuration.
+     */
     const updateHighlightStyle = (element, config) => {
         const position = getElementPosition(element);
         const padding = config?.padding || 4;
@@ -1204,13 +1413,23 @@ function useTourHighlight(step) {
     };
 }
 
-function TourOverlay({ className }) {
-    const { state, theme, stop } = useTour();
+const TourOverlay = React.memo(function TourOverlay({ className }) {
+    const { state, theme, stop, config, next } = useTour();
     const { targetElement, highlightStyle, isVisible } = useTourHighlight(state.currentStep);
-    if (!state.isRunning || !state.currentStep) {
-        return null;
-    }
-    const overlayStyle = {
+    const [scrollTrigger, setScrollTrigger] = useState(0);
+    // Determine if interactions should be blocked
+    const shouldBlockInteractions = useMemo(() => {
+        const stepBlocking = state.currentStep?.blockInteractions;
+        const globalBlocking = config.blockInteractions;
+        return stepBlocking !== undefined ? stepBlocking : globalBlocking;
+    }, [state.currentStep?.blockInteractions, config.blockInteractions]);
+    // Determine if click-to-advance is enabled
+    const shouldClickToAdvance = useMemo(() => {
+        const stepClickToAdvance = state.currentStep?.clickToAdvance;
+        const globalClickToAdvance = config.clickToAdvance;
+        return stepClickToAdvance !== undefined ? stepClickToAdvance : globalClickToAdvance;
+    }, [state.currentStep?.clickToAdvance, config.clickToAdvance]);
+    const overlayStyle = useMemo(() => ({
         position: 'fixed',
         top: 0,
         left: 0,
@@ -1220,13 +1439,151 @@ function TourOverlay({ className }) {
         opacity: theme.overlay?.opacity || 0.5,
         zIndex: (theme.zIndex || 9999) - 1,
         pointerEvents: 'auto',
-    };
-    const handleOverlayClick = () => {
-        if (state.currentStep?.canSkip !== false) {
+    }), [theme.overlay?.backgroundColor, theme.overlay?.opacity, theme.zIndex]);
+    // Create cutout style for the highlighted element
+    const cutoutOverlayStyle = useMemo(() => {
+        if ((!shouldBlockInteractions && !shouldClickToAdvance) || !targetElement || !isVisible) {
+            return overlayStyle;
+        }
+        // Use getBoundingClientRect for viewport-relative coordinates (perfect for fixed overlay)
+        const rect = targetElement.getBoundingClientRect();
+        const padding = state.currentStep?.highlight?.padding || 8;
+        // Ensure coordinates are within viewport bounds
+        const left = Math.max(0, rect.left - padding);
+        const top = Math.max(0, rect.top - padding);
+        const right = Math.min(window.innerWidth, rect.right + padding);
+        const bottom = Math.min(window.innerHeight, rect.bottom + padding);
+        return {
+            ...overlayStyle,
+            clipPath: `polygon(
+        0% 0%, 
+        0% 100%, 
+        ${left}px 100%, 
+        ${left}px ${top}px, 
+        ${right}px ${top}px, 
+        ${right}px ${bottom}px, 
+        ${left}px ${bottom}px, 
+        ${left}px 100%, 
+        100% 100%, 
+        100% 0%
+      )`,
+        };
+    }, [overlayStyle, shouldBlockInteractions, shouldClickToAdvance, targetElement, isVisible, state.currentStep?.highlight?.padding, scrollTrigger]); // eslint-disable-line react-hooks/exhaustive-deps
+    // Force re-render of cutout overlay on scroll to maintain proper positioning
+    useEffect(() => {
+        if (!shouldBlockInteractions && !shouldClickToAdvance) {
+            return;
+        }
+        const handleScroll = () => {
+            // Force recalculation by updating scroll trigger
+            setScrollTrigger(prev => prev + 1);
+        };
+        window.addEventListener('scroll', handleScroll, { passive: true });
+        window.addEventListener('resize', handleScroll, { passive: true });
+        return () => {
+            window.removeEventListener('scroll', handleScroll);
+            window.removeEventListener('resize', handleScroll);
+        };
+    }, [shouldBlockInteractions, shouldClickToAdvance]);
+    const handleOverlayClick = useCallback((e) => {
+        // If interactions are blocked, prevent the click from propagating
+        if (shouldBlockInteractions) {
+            e.preventDefault();
+            e.stopPropagation();
+            return;
+        }
+        // Allow clicking outside to close tour if not blocking interactions
+        if (config.allowClickOutside !== false && state.currentStep?.canSkip !== false) {
             stop();
         }
-    };
-    return (jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: [jsxRuntimeExports.jsx("div", { style: overlayStyle, onClick: handleOverlayClick, className: className, "data-tour-overlay": true }), isVisible && targetElement && (jsxRuntimeExports.jsx("div", { style: highlightStyle, "data-tour-highlight": true })), jsxRuntimeExports.jsx("style", { children: `
+    }, [shouldBlockInteractions, config.allowClickOutside, state.currentStep?.canSkip, stop]);
+    // Handle click-to-advance functionality
+    useEffect(() => {
+        if (!shouldClickToAdvance || !targetElement || !state.isRunning) {
+            return;
+        }
+        // Ensure target element is above the overlay when click-to-advance is enabled
+        const originalZIndex = targetElement.style.zIndex;
+        const originalPosition = targetElement.style.position;
+        targetElement.style.position = targetElement.style.position || 'relative';
+        targetElement.style.zIndex = String((theme.zIndex || 9999) + 1);
+        const handleTargetClick = (_e) => {
+            // Don't prevent default or stop propagation - let the element's normal behavior work
+            // Just advance the tour after a small delay to allow the click to be processed
+            setTimeout(() => {
+                next();
+            }, 100);
+        };
+        targetElement.addEventListener('click', handleTargetClick, true);
+        return () => {
+            targetElement.removeEventListener('click', handleTargetClick, true);
+            // Restore original styles
+            targetElement.style.zIndex = originalZIndex;
+            targetElement.style.position = originalPosition;
+        };
+    }, [shouldClickToAdvance, targetElement, state.isRunning, next, theme.zIndex]);
+    // Block interactions on the entire page when blocking is enabled
+    useEffect(() => {
+        if (!shouldBlockInteractions || !state.isRunning) {
+            return;
+        }
+        const handleGlobalClick = (e) => {
+            const target = e.target;
+            // Allow clicks on the tour target element and its children
+            if (targetElement && (targetElement.contains(target) || targetElement === target)) {
+                // If click-to-advance is enabled, let the target click handler deal with it
+                if (shouldClickToAdvance) {
+                    return;
+                }
+                return;
+            }
+            // Allow clicks on tour UI elements (popover, buttons, etc.)
+            if (target.closest('[data-tour-popover]') ||
+                target.closest('[data-tour-highlight]') ||
+                target.closest('[data-tour-overlay]')) {
+                return;
+            }
+            // Block all other clicks
+            e.preventDefault();
+            e.stopPropagation();
+        };
+        const handleGlobalKeydown = (e) => {
+            // Allow tour navigation keys
+            if (['Escape', 'ArrowLeft', 'ArrowRight', 'Enter', 'Space'].includes(e.key)) {
+                return;
+            }
+            // Block other keyboard interactions
+            e.preventDefault();
+            e.stopPropagation();
+        };
+        // Add event listeners to capture phase to block interactions early
+        document.addEventListener('click', handleGlobalClick, true);
+        document.addEventListener('keydown', handleGlobalKeydown, true);
+        document.addEventListener('mousedown', handleGlobalClick, true);
+        document.addEventListener('touchstart', handleGlobalClick, true);
+        return () => {
+            document.removeEventListener('click', handleGlobalClick, true);
+            document.removeEventListener('keydown', handleGlobalKeydown, true);
+            document.removeEventListener('mousedown', handleGlobalClick, true);
+            document.removeEventListener('touchstart', handleGlobalClick, true);
+        };
+    }, [shouldBlockInteractions, state.isRunning, targetElement, shouldClickToAdvance]);
+    if (!state.isRunning || !state.currentStep) {
+        return null;
+    }
+    return (jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: [jsxRuntimeExports.jsx("div", { style: (shouldBlockInteractions || shouldClickToAdvance) ? cutoutOverlayStyle : overlayStyle, onClick: handleOverlayClick, className: className, "data-tour-overlay": true }), isVisible && targetElement && (jsxRuntimeExports.jsx("div", { style: highlightStyle, "data-tour-highlight": true })), shouldBlockInteractions && (jsxRuntimeExports.jsx("div", { style: {
+                    position: 'fixed',
+                    top: '20px',
+                    right: '20px',
+                    backgroundColor: 'rgba(0, 0, 0, 0.8)',
+                    color: 'white',
+                    padding: '8px 12px',
+                    borderRadius: '4px',
+                    fontSize: '12px',
+                    zIndex: (theme.zIndex || 9999) + 1,
+                    pointerEvents: 'none',
+                    animation: 'tour-fade-in 0.3s ease-out',
+                }, "data-tour-blocking-indicator": true, children: "\uD83D\uDD12 Interactions blocked" })), jsxRuntimeExports.jsx("style", { children: `
         @keyframes tour-highlight-pulse {
           0%, 100% {
             box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.2), 0 0 20px rgba(59, 130, 246, 0.3);
@@ -1254,39 +1611,54 @@ function TourOverlay({ className }) {
         [data-tour-highlight] {
           animation: tour-fade-in 0.3s ease-out;
         }
+        
+        [data-tour-blocking-indicator] {
+          animation: tour-fade-in 0.3s ease-out;
+        }
       ` })] }));
-}
+});
 
 function r(e){var t,f,n="";if("string"==typeof e||"number"==typeof e)n+=e;else if("object"==typeof e)if(Array.isArray(e)){var o=e.length;for(t=0;t<o;t++)e[t]&&(f=r(e[t]))&&(n&&(n+=" "),n+=f);}else for(f in e)e[f]&&(n&&(n+=" "),n+=f);return n}function clsx(){for(var e,t,f=0,n="",o=arguments.length;f<o;f++)(e=arguments[f])&&(t=r(e))&&(n&&(n+=" "),n+=t);return n}
 
-function TourPopover({ className }) {
-    const { state, theme, next, previous, skip, stop, isFirstStep, isLastStep, canGoNext, canGoPrevious } = useTour();
+const TourPopover = React.memo(function TourPopover({ className }) {
+    const { state, theme, next, previous, skip, stop, isFirstStep, isLastStep, canGoNext, canGoPrevious, config } = useTour();
     const { targetElement } = useTourHighlight(state.currentStep);
     const popoverRef = useRef(null);
     const [position, setPosition] = useState({ top: 0, left: 0, placement: 'top' });
-    useEffect(() => {
-        if (!popoverRef.current || !targetElement || !state.currentStep)
+    const updatePosition = useCallback(() => {
+        if (!popoverRef.current || !state.currentStep)
             return;
-        const updatePosition = () => {
-            const newPosition = calculatePopoverPosition(targetElement, popoverRef.current, state.currentStep.placement || 'top');
-            setPosition(newPosition);
-        };
-        updatePosition();
-        const handleResize = () => updatePosition();
-        const handleScroll = () => updatePosition();
-        window.addEventListener('resize', handleResize);
-        window.addEventListener('scroll', handleScroll, { passive: true });
-        return () => {
-            window.removeEventListener('resize', handleResize);
-            window.removeEventListener('scroll', handleScroll);
-        };
+        // For center placement without target element, calculate center position directly
+        if (state.currentStep.placement === 'center' && !targetElement) {
+            const popoverRect = popoverRef.current.getBoundingClientRect();
+            const viewport = {
+                width: window.innerWidth,
+                height: window.innerHeight,
+                scrollTop: window.pageYOffset || document.documentElement.scrollTop,
+                scrollLeft: window.pageXOffset || document.documentElement.scrollLeft,
+            };
+            setPosition({
+                top: viewport.scrollTop + (viewport.height - popoverRect.height) / 2,
+                left: viewport.scrollLeft + (viewport.width - popoverRect.width) / 2,
+                placement: 'center',
+            });
+            return;
+        }
+        // For other placements, require target element
+        if (!targetElement)
+            return;
+        const newPosition = calculatePopoverPosition(targetElement, popoverRef.current, state.currentStep.placement || 'top');
+        setPosition(newPosition);
     }, [targetElement, state.currentStep]);
-    if (!state.isRunning || !state.currentStep) {
-        return null;
-    }
     const step = state.currentStep;
-    const popoverConfig = step.popover || {};
-    const popoverStyle = {
+    const popoverConfig = useMemo(() => step?.popover || {}, [step?.popover]);
+    // Determine if click-to-advance is enabled for this step
+    const shouldClickToAdvance = useMemo(() => {
+        const stepClickToAdvance = step?.clickToAdvance;
+        const globalClickToAdvance = config.clickToAdvance;
+        return stepClickToAdvance !== undefined ? stepClickToAdvance : globalClickToAdvance;
+    }, [step?.clickToAdvance, config.clickToAdvance]);
+    const popoverStyle = useMemo(() => ({
         position: 'absolute',
         top: position.top,
         left: position.left,
@@ -1311,23 +1683,41 @@ function TourPopover({ className }) {
         color: theme.textColor || '#1f2937',
         zIndex: theme.zIndex || 9999,
         animation: 'tour-fade-in 0.3s ease-out',
-    };
-    const handleNext = async () => {
+    }), [position.top, position.left, theme]);
+    const handleNext = useCallback(async () => {
         if (canGoNext || isLastStep) {
             await next();
         }
-    };
-    const handlePrevious = async () => {
+    }, [canGoNext, isLastStep, next]);
+    const handlePrevious = useCallback(async () => {
         if (canGoPrevious) {
             await previous();
         }
-    };
-    const handleSkip = async () => {
+    }, [canGoPrevious, previous]);
+    const handleSkip = useCallback(async () => {
         await skip();
-    };
-    const handleClose = async () => {
+    }, [skip]);
+    const handleClose = useCallback(async () => {
         await stop();
-    };
+    }, [stop]);
+    useEffect(() => {
+        // Small delay to ensure popover is rendered and has dimensions
+        const timeoutId = setTimeout(() => {
+            updatePosition();
+        }, 10);
+        const handleResize = () => updatePosition();
+        const handleScroll = () => updatePosition();
+        window.addEventListener('resize', handleResize);
+        window.addEventListener('scroll', handleScroll, { passive: true });
+        return () => {
+            clearTimeout(timeoutId);
+            window.removeEventListener('resize', handleResize);
+            window.removeEventListener('scroll', handleScroll);
+        };
+    }, [updatePosition]);
+    if (!state.isRunning || !state.currentStep) {
+        return null;
+    }
     return (jsxRuntimeExports.jsxs("div", { ref: popoverRef, style: {
             ...popoverStyle,
             pointerEvents: 'auto',
@@ -1362,22 +1752,22 @@ function TourPopover({ className }) {
                             borderRadius: '12px',
                             fontSize: '12px',
                             fontWeight: '500',
-                        }, children: [state.currentStepIndex + 1, " of ", state.totalSteps] }))] }), jsxRuntimeExports.jsxs("div", { style: { padding: '16px 20px' }, children: [(popoverConfig.title || step.title) && (jsxRuntimeExports.jsx("h3", { style: {
+                        }, children: [state.currentStepIndex + 1, " of ", state.totalSteps] }))] }), jsxRuntimeExports.jsxs("div", { style: { padding: '16px 20px' }, children: [(popoverConfig.title || step?.title) && (jsxRuntimeExports.jsx("h3", { style: {
                             margin: '0 0 8px 0',
                             fontSize: '16px',
                             fontWeight: '600',
                             color: theme.textColor || '#1f2937',
-                        }, children: popoverConfig.title || step.title })), jsxRuntimeExports.jsx("div", { style: {
+                        }, children: popoverConfig.title || step?.title })), jsxRuntimeExports.jsx("div", { style: {
                             margin: '0 0 16px 0',
                             lineHeight: '1.5',
                             color: theme.textColor || '#374151',
-                        }, children: popoverConfig.content || step.content })] }), jsxRuntimeExports.jsxs("div", { style: {
+                        }, children: popoverConfig.content || step?.content })] }), jsxRuntimeExports.jsxs("div", { style: {
                     display: 'flex',
                     justifyContent: 'space-between',
                     alignItems: 'center',
                     padding: '0 20px 20px 20px',
                     gap: '12px',
-                }, children: [(popoverConfig.showSkip !== false && step.canSkip !== false) && (jsxRuntimeExports.jsx("button", { onClick: (_e) => {
+                }, children: [(popoverConfig.showSkip !== false && step?.canSkip !== false) && (jsxRuntimeExports.jsx("button", { onClick: (_e) => {
                             handleSkip();
                         }, style: {
                             background: 'none',
@@ -1417,7 +1807,7 @@ function TourPopover({ className }) {
                                     fontWeight: '500',
                                     opacity: canGoPrevious ? 1 : 0.5,
                                     transition: 'all 0.2s ease',
-                                }, children: "Previous" })), jsxRuntimeExports.jsx("button", { onClick: (e) => {
+                                }, children: "Previous" })), !shouldClickToAdvance && (jsxRuntimeExports.jsx("button", { onClick: (e) => {
                                     e.preventDefault();
                                     e.stopPropagation();
                                     handleNext();
@@ -1440,7 +1830,18 @@ function TourPopover({ className }) {
                                     zIndex: 99999,
                                 }, children: isLastStep
                                     ? (popoverConfig.finishLabel || 'Finish')
-                                    : (popoverConfig.nextLabel || 'Next') })] })] }), position.placement !== 'center' && (jsxRuntimeExports.jsx("div", { style: {
+                                    : (popoverConfig.nextLabel || 'Next') })), shouldClickToAdvance && (jsxRuntimeExports.jsx("div", { style: {
+                                    backgroundColor: 'rgba(59, 130, 246, 0.1)',
+                                    border: '1px solid rgba(59, 130, 246, 0.3)',
+                                    color: theme.primaryColor || '#3b82f6',
+                                    padding: '8px 16px',
+                                    borderRadius: '8px',
+                                    fontSize: '14px',
+                                    fontWeight: '500',
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    gap: '6px',
+                                }, children: "\uD83D\uDC46 Click the highlighted element to continue" }))] })] }), position.placement !== 'center' && (jsxRuntimeExports.jsx("div", { style: {
                     position: 'absolute',
                     width: '12px',
                     height: '12px',
@@ -1460,7 +1861,7 @@ function TourPopover({ className }) {
                     transform: 'rotate(45deg)',
                     ...getArrowPosition(position.placement),
                 }, "data-tour-arrow": true }))] }));
-}
+});
 function getArrowPosition(placement) {
     switch (placement) {
         case 'top':
@@ -1500,13 +1901,92 @@ function getArrowPosition(placement) {
     }
 }
 
-function TourRunner({ className }) {
+class ErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.retryTimeoutId = null;
+        this.retry = () => {
+            this.setState({
+                hasError: false,
+                error: null,
+                errorInfo: null,
+            });
+        };
+        this.state = {
+            hasError: false,
+            error: null,
+            errorInfo: null,
+        };
+    }
+    static getDerivedStateFromError(error) {
+        return {
+            hasError: true,
+            error,
+        };
+    }
+    componentDidCatch(error, errorInfo) {
+        this.setState({
+            error,
+            errorInfo,
+        });
+        if (this.props.onError) {
+            this.props.onError(error, errorInfo);
+        }
+        console.error('Tour ErrorBoundary caught an error:', error, errorInfo);
+    }
+    componentWillUnmount() {
+        if (this.retryTimeoutId) {
+            clearTimeout(this.retryTimeoutId);
+        }
+    }
+    render() {
+        if (this.state.hasError && this.state.error && this.state.errorInfo) {
+            if (this.props.fallback) {
+                return this.props.fallback(this.state.error, this.state.errorInfo, this.retry);
+            }
+            return (jsxRuntimeExports.jsxs("div", { style: {
+                    padding: '20px',
+                    margin: '20px',
+                    border: '2px solid #ff6b6b',
+                    borderRadius: '8px',
+                    backgroundColor: '#fff5f5',
+                    color: '#c92a2a',
+                    fontFamily: 'system-ui, sans-serif'
+                }, children: [jsxRuntimeExports.jsx("h2", { style: { margin: '0 0 10px 0', fontSize: '18px' }, children: "Something went wrong" }), jsxRuntimeExports.jsxs("details", { style: { marginBottom: '15px' }, children: [jsxRuntimeExports.jsx("summary", { style: { cursor: 'pointer', fontWeight: 'bold' }, children: "Error Details" }), jsxRuntimeExports.jsxs("pre", { style: {
+                                    marginTop: '10px',
+                                    padding: '10px',
+                                    backgroundColor: '#f8f8f8',
+                                    borderRadius: '4px',
+                                    fontSize: '12px',
+                                    overflow: 'auto'
+                                }, children: [this.state.error.message, this.state.error.stack && (jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: ['\n\n', this.state.error.stack] })), this.state.errorInfo.componentStack && (jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: ['\n\nComponent Stack:', this.state.errorInfo.componentStack] }))] })] }), jsxRuntimeExports.jsx("button", { onClick: this.retry, style: {
+                            padding: '8px 16px',
+                            backgroundColor: '#228be6',
+                            color: 'white',
+                            border: 'none',
+                            borderRadius: '4px',
+                            cursor: 'pointer',
+                            fontSize: '14px'
+                        }, children: "Try Again" })] }));
+        }
+        return this.props.children;
+    }
+}
+function withErrorBoundary(Component, errorBoundaryProps) {
+    const WrappedComponent = (props) => (jsxRuntimeExports.jsx(ErrorBoundary, { ...errorBoundaryProps, children: jsxRuntimeExports.jsx(Component, { ...props }) }));
+    WrappedComponent.displayName = `withErrorBoundary(${Component.displayName || Component.name})`;
+    return WrappedComponent;
+}
+
+const TourRunner = React.memo(function TourRunner({ className }) {
     const { state } = useTour();
     if (!state.isRunning) {
         return null;
     }
-    return (jsxRuntimeExports.jsxs(jsxRuntimeExports.Fragment, { children: [jsxRuntimeExports.jsx(TourOverlay, { className: className }), jsxRuntimeExports.jsx(TourPopover, { className: className })] }));
-}
+    return (jsxRuntimeExports.jsxs(ErrorBoundary, { onError: (error, errorInfo) => {
+            console.error('TourRunner error:', error, errorInfo);
+        }, children: [jsxRuntimeExports.jsx(TourOverlay, { className: className }), jsxRuntimeExports.jsx(TourPopover, { className: className })] }));
+});
 
 class TabIntegration {
     constructor() {
@@ -1523,33 +2003,26 @@ class TabIntegration {
         if (!targetElement) {
             throw new Error(`Tab element not found: ${action.target}`);
         }
-        // Handle different tab implementations
         const tabValue = typeof action.value === 'string' ? action.value : undefined;
         await this.handleTabClick(targetElement, tabValue);
     }
     async handleTabClick(tabElement, tabValue) {
-        // Check for common tab patterns
-        // 1. Radix UI Tabs
         if (this.isRadixTab(tabElement)) {
             await this.handleRadixTab(tabElement);
             return;
         }
-        // 2. Material UI Tabs
         if (this.isMaterialUITab(tabElement)) {
             await this.handleMaterialUITab(tabElement);
             return;
         }
-        // 3. React Router tabs (links)
         if (this.isRouterTab(tabElement)) {
             await this.handleRouterTab(tabElement);
             return;
         }
-        // 4. Custom tabs with data attributes
         if (this.isCustomTab(tabElement)) {
             await this.handleCustomTab(tabElement, tabValue);
             return;
         }
-        // 5. Generic button/clickable tab
         await this.handleGenericTab(tabElement);
     }
     isRadixTab(element) {
@@ -2093,5 +2566,5 @@ class NavigationIntegration {
     }
 }
 
-export { NavigationIntegration, TabIntegration, TourActions, TourEngine, TourOverlay, TourPopover, TourProvider, TourRunner, TourStorage, WizardIntegration, calculatePopoverPosition, getElementPosition, getViewportCenter, isElementInViewport, scrollToElement, useTour, useTourEngine, useTourHighlight };
+export { ErrorBoundary, NavigationIntegration, TabIntegration, TourActions, TourEngine, TourOverlay, TourPopover, TourProvider, TourRunner, TourStorage, WizardIntegration, calculatePopoverPosition, createSafeAsyncOperation, getElementPosition, getViewportCenter, isElementInViewport, scrollToElement, useErrorBoundary, useErrorHandler, useTour, useTourEngine, useTourHighlight, withErrorBoundary };
 //# sourceMappingURL=index.esm.js.map