@veltdev/react 5.0.0-beta.2 → 5.0.0-beta.3

package/cjs/types/constants.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="react" />
-export declare const VELT_SDK_VERSION = "5.0.0-beta.2";
+export declare const VELT_SDK_VERSION = "5.0.0-beta.3";
 export declare const VELT_SDK_INIT_EVENT = "onVeltInit";
 export declare const VELT_TAB_ID = "veltTabId";
 export declare const INTEGRITY_MAP: Record<string, string>;

package/cjs/types/loadSnippyly.d.ts

@@ -1,2 +1,28 @@
-declare const loadVelt: (callback: Function, version?: string, staging?: boolean, develop?: boolean, proxyDomain?: string, integrity?: boolean, integrityValue?: string) => void;
+/**
+ * Loads the Velt script dynamically and calls the callback when ready.
+ * Returns a cleanup function to remove the event listener if component unmounts.
+ *
+ * ## Issue (Rapid Mount/Unmount with Slow Network)
+ *
+ * When VeltProvider is rapidly mounted/unmounted (e.g., conditional rendering,
+ * React Strict Mode, or route changes) while the Velt script is still loading
+ * over a slow network, multiple issues can occur:
+ *
+ * 1. First component mount creates the script tag and starts loading
+ * 2. Component unmounts before script loads (script tag remains in DOM)
+ * 3. Second component mount finds existing script tag
+ * 4. OLD BEHAVIOR: Immediately triggered callback assuming script was loaded
+ * 5. PROBLEM: Script wasn't actually loaded yet (still loading due to network delay)
+ * 6. This caused initVelt to run with window.Velt = undefined
+ *
+ * ## Fix
+ *
+ * 1. Check if window.Velt exists before triggering callback for existing scripts
+ * 2. If script tag exists but window.Velt doesn't, attach a new load event listener
+ * 3. Return a cleanup function that removes the event listener when component unmounts
+ * 4. This prevents orphaned callbacks from firing on destroyed component instances
+ *
+ * @returns Cleanup function to remove event listener (call on component unmount)
+ */
+declare const loadVelt: (callback: Function, version?: string, staging?: boolean, develop?: boolean, proxyDomain?: string, integrity?: boolean, integrityValue?: string) => (() => void);
 export default loadVelt;

package/esm/index.js

@@ -92,12 +92,44 @@ function useVeltClient() {
     return useContext(VeltContext);
 }
 
+/**
+ * Loads the Velt script dynamically and calls the callback when ready.
+ * Returns a cleanup function to remove the event listener if component unmounts.
+ *
+ * ## Issue (Rapid Mount/Unmount with Slow Network)
+ *
+ * When VeltProvider is rapidly mounted/unmounted (e.g., conditional rendering,
+ * React Strict Mode, or route changes) while the Velt script is still loading
+ * over a slow network, multiple issues can occur:
+ *
+ * 1. First component mount creates the script tag and starts loading
+ * 2. Component unmounts before script loads (script tag remains in DOM)
+ * 3. Second component mount finds existing script tag
+ * 4. OLD BEHAVIOR: Immediately triggered callback assuming script was loaded
+ * 5. PROBLEM: Script wasn't actually loaded yet (still loading due to network delay)
+ * 6. This caused initVelt to run with window.Velt = undefined
+ *
+ * ## Fix
+ *
+ * 1. Check if window.Velt exists before triggering callback for existing scripts
+ * 2. If script tag exists but window.Velt doesn't, attach a new load event listener
+ * 3. Return a cleanup function that removes the event listener when component unmounts
+ * 4. This prevents orphaned callbacks from firing on destroyed component instances
+ *
+ * @returns Cleanup function to remove event listener (call on component unmount)
+ */
 var loadVelt = function (callback, version, staging, develop, proxyDomain, integrity, integrityValue) {
     if (version === void 0) { version = 'latest'; }
     if (staging === void 0) { staging = false; }
     if (develop === void 0) { develop = false; }
     var existingScript = document.getElementById('veltScript');
+    // Store reference to the handler so we can remove it on cleanup.
+    // This is essential for proper cleanup - we need the exact same function
+    // reference to remove the event listener later.
+    var loadHandler = null;
+    var scriptElement = null;
     if (!existingScript) {
+        // No script tag exists - this is the first component to request Velt
         var script = document.createElement('script');
         if (staging) {
             script.src = "https://us-central1-snipply-sdk-staging.cloudfunctions.net/getprivatenpmpackagefile?packageName=sdk-staging&packageVersion=".concat((!version || version === 'latest') ? '1.0.1' : version, "&filePath=velt.js&orgName=@veltdev");
@@ -124,26 +156,61 @@ var loadVelt = function (callback, version, staging, develop, proxyDomain, integ
             script.crossOrigin = 'anonymous';
         }
         document.body.appendChild(script);
-        script.onload = function () {
+        // Create handler and store reference for cleanup.
+        // We store the reference so we can remove this exact listener on cleanup.
+        loadHandler = function () {
             if (callback) {
                 callback();
             }
         };
+        scriptElement = script;
+        script.addEventListener('load', loadHandler);
     }
     else {
-        if (callback) {
-            callback();
+        // Script tag already exists in DOM (created by a previous component instance).
+        // We need to check if it's actually finished loading or still in progress.
+        if (window.Velt) {
+            // Script has finished loading - window.Velt is available.
+            // Trigger callback directly without attaching any event listener.
+            if (callback) {
+                callback();
+            }
+        }
+        else {
+            // IMPORTANT: Script tag exists but window.Velt is undefined.
+            // This means the script is still loading (slow network scenario).
+            // 
+            // Previous bug: We used to trigger callback immediately here,
+            // which caused initVelt to run with window.Velt = undefined.
+            // 
+            // Fix: Attach a load event listener to wait for the script to finish loading.
+            // Using addEventListener (not onload) to avoid overwriting existing handlers.
+            loadHandler = function () {
+                if (callback) {
+                    callback();
+                }
+            };
+            scriptElement = existingScript;
+            existingScript.addEventListener('load', loadHandler);
         }
     }
+    // Return cleanup function to remove event listener when component unmounts.
+    // This prevents the callback from firing on destroyed component instances,
+    // which would cause React state updates on unmounted components.
+    return function () {
+        if (loadHandler && scriptElement) {
+            scriptElement.removeEventListener('load', loadHandler);
+        }
+    };
 };
 
-var VELT_SDK_VERSION = '5.0.0-beta.2';
+var VELT_SDK_VERSION = '5.0.0-beta.3';
 var VELT_SDK_INIT_EVENT = 'onVeltInit';
 var VELT_TAB_ID = 'veltTabId';
 // integrity map for the Velt SDK
 // Note: generate integrity hashes with: https://www.srihash.org/
 var INTEGRITY_MAP = {
-    '5.0.0-beta.2': 'sha384-P/mj/JAXeU39QESjJFT6yJxpd5CIMt1DuS3dL4T5t5x0/163T/HONIKocpSIEXQ9',
+    '5.0.0-beta.3': 'sha384-3BZ1+ii93NtGRH5pECR6FaGd6IJpz4VUHE503QnPQcIIb+nuw6C0HGSxbt0D9h9x',
 };
 
 var validProps = ['veltIf', 'veltClass', 'className', 'variant'];
@@ -209,7 +276,43 @@ var SnippylyProvider = function (props) {
     var prevUserDataProviderRef = useRef(undefined);
     var prevDataProvidersRef = useRef(undefined);
     var prevPermissionProviderRef = useRef(undefined);
+    /**
+     * Tracks whether the component is currently mounted.
+     * Used to prevent state updates and async operations on unmounted components.
+     *
+     * ## Issue (Rapid Mount/Unmount)
+     * When VeltProvider is rapidly mounted/unmounted (e.g., conditional rendering
+     * based on state changes, React Strict Mode, or route transitions), multiple
+     * component instances can have async operations (like Velt.init()) in flight.
+     * When these async operations complete, they try to call setClient() on
+     * unmounted component instances, causing React warnings and incorrect state.
+     *
+     * ## Fix
+     * Track mount state and check it before/after async operations to bail out
+     * if the component has been unmounted.
+     */
+    var isMountedRef = useRef(true);
     useEffect(function () {
+        // IMPORTANT: Reset isMountedRef to true on every mount/remount.
+        // This is critical for React Strict Mode which simulates unmount/remount:
+        // 
+        // React Strict Mode sequence:
+        // 1. Mount → isMountedRef = true (initial value)
+        // 2. Effect runs
+        // 3. Strict Mode simulates unmount → cleanup sets isMountedRef = false
+        // 4. Strict Mode simulates remount → effect runs again
+        // 
+        // Without this reset, step 4 would still see isMountedRef = false from step 3,
+        // causing initVelt to skip even though the component is actually mounted.
+        isMountedRef.current = true;
+        // Cleanup: mark component as unmounted
+        return function () {
+            isMountedRef.current = false;
+        };
+    }, []);
+    useEffect(function () {
+        // Store cleanup function returned from loadVelt to remove event listeners on unmount
+        var cleanupLoadVelt;
         if (apiKey) {
             var staging = config === null || config === void 0 ? void 0 : config.staging;
             var develop = config === null || config === void 0 ? void 0 : config.develop;
@@ -228,10 +331,34 @@ var SnippylyProvider = function (props) {
                     }
                 }
             }
-            loadVelt(function () {
+            // Rapid mount/unmount issue found in OpenEnvoy client code with slow network.
+            // 
+            // Scenario: VeltProvider is conditionally rendered and toggles rapidly while
+            // the Velt script is loading over a slow network connection.
+            // 
+            // We check if Velt is already loaded (window.Velt exists) and call initVelt
+            // directly. If not loaded, we call loadVelt which handles the script loading
+            // and returns a cleanup function to remove event listeners.
+            if (window === null || window === void 0 ? void 0 : window.Velt) {
                 initVelt();
-            }, version, staging, develop, config === null || config === void 0 ? void 0 : config.proxyDomain, integrity, integrityValue);
+            }
+            else {
+                // loadVelt returns a cleanup function that removes the load event listener.
+                // This prevents the callback from firing on destroyed component instances.
+                cleanupLoadVelt = loadVelt(function () {
+                    initVelt();
+                }, version, staging, develop, config === null || config === void 0 ? void 0 : config.proxyDomain, integrity, integrityValue);
+            }
         }
+        // Cleanup: remove event listener when component unmounts.
+        // This is critical for rapid mount/unmount scenarios - without this cleanup,
+        // the load callback would fire on destroyed component instances and try to
+        // call initVelt, which would then try to update state on an unmounted component.
+        return function () {
+            if (cleanupLoadVelt) {
+                cleanupLoadVelt();
+            }
+        };
     }, []);
     useEffect(function () {
         if (!deepCompare(prevUserDataProviderRef.current, userDataProvider)) {
@@ -306,12 +433,29 @@ var SnippylyProvider = function (props) {
             }
         }
     }, [client, permissionProvider]);
+    /**
+     * Initializes the Velt SDK with proper mount state checks.
+     *
+     * ## Async Safety Pattern
+     * This function contains async operations (Velt.init). During the await,
+     * the component might unmount. We must check isMountedRef:
+     * 1. BEFORE starting - skip if already unmounted
+     * 2. AFTER await completes - abort if unmounted during the wait
+     *
+     * Without these checks, setClient() would be called on unmounted components,
+     * causing React warnings and potential memory leaks.
+     */
     var initVelt = function () { return __awaiter(void 0, void 0, void 0, function () {
         var velt, event;
         var _a, _b;
         return __generator(this, function (_c) {
             switch (_c.label) {
                 case 0:
+                    // CHECK 1: Skip initialization if component has already been unmounted.
+                    // This handles the case where cleanup ran before initVelt was called.
+                    if (!isMountedRef.current) {
+                        return [2 /*return*/];
+                    }
                     if (!config) return [3 /*break*/, 2];
                     if (config.staging) {
                         delete config.staging;
@@ -334,6 +478,13 @@ var SnippylyProvider = function (props) {
                     velt = _c.sent();
                     _c.label = 4;
                 case 4:
+                    // CHECK 2: Abort if component unmounted during the await.
+                    // Velt.init() is async and can take time. The component might have
+                    // been unmounted while we were waiting. Check again before proceeding
+                    // with state updates and side effects.
+                    if (!isMountedRef.current) {
+                        return [2 /*return*/];
+                    }
                     // Set language
                     if (language && (velt === null || velt === void 0 ? void 0 : velt.setLanguage)) {
                         velt === null || velt === void 0 ? void 0 : velt.setLanguage(language);