@weldsuite/helpdesk-widget-sdk 1.0.15 → 1.0.17

package/dist/index.umd.js

@@ -37,32 +37,6 @@
                 closeOnClick: true,
             },
         },
-        customization: {
-            primaryColor: '#000000',
-            accentColor: '#3b82f6',
-            backgroundColor: '#ffffff',
-            textColor: '#111827',
-            fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-            fontSize: '14px',
-            borderRadius: '12px',
-        },
-        features: {
-            attachments: true,
-            reactions: true,
-            typing: true,
-            readReceipts: true,
-            offlineMode: false,
-            fileUpload: true,
-            imageUpload: true,
-            voiceMessages: false,
-            videoMessages: false,
-        },
-        mobile: {
-            fullScreen: true,
-            scrollLock: true,
-            keyboardHandling: 'auto',
-            safeAreaInsets: true,
-        },
         auth: {
             enabled: true,
             mode: 'anonymous',
@@ -106,6 +80,7 @@
         validateConfig(config);
         return {
             widgetId: config.widgetId,
+            testMode: config.testMode,
             api: {
                 ...DEFAULT_CONFIG.api,
                 widgetId: config.widgetId,
@@ -135,18 +110,6 @@
                     ...config.iframes?.backdrop,
                 },
             },
-            customization: {
-                ...DEFAULT_CONFIG.customization,
-                ...config.customization,
-            },
-            features: {
-                ...DEFAULT_CONFIG.features,
-                ...config.features,
-            },
-            mobile: {
-                ...DEFAULT_CONFIG.mobile,
-                ...config.mobile,
-            },
             auth: {
                 ...DEFAULT_CONFIG.auth,
                 ...config.auth,
@@ -389,6 +352,8 @@
             this.modalContainer = null;
             this.styleElement = null;
             this.messageBroker = null;
+            // Guard flag to prevent double-binding event listeners
+            this.eventListenersBound = false;
             this.config = config;
             this.logger = new Logger(config.logging);
             this.deviceInfo = detectDevice();
@@ -428,18 +393,27 @@
         }
         /**
          * Create root container structure
+         * Reuses existing container if it has the same widgetId (singleton behavior)
          */
         createRootContainer() {
-            // Check if already exists
-            let existingContainer = document.getElementById('weld-container');
+            const existingContainer = document.getElementById('weld-container');
             if (existingContainer) {
-                this.logger.warn('Weld container already exists, removing old instance');
+                // Reuse if same widgetId
+                if (existingContainer.getAttribute('data-widget-id') === this.config.widgetId) {
+                    this.logger.debug('Reusing existing root container');
+                    this.rootContainer = existingContainer;
+                    this.appContainer = existingContainer.querySelector('.weld-app');
+                    this.modalContainer = document.getElementById('weld-modal-container');
+                    return;
+                }
+                this.logger.warn('Weld container already exists with different widgetId, removing old instance');
                 existingContainer.remove();
             }
             // Create root container
             this.rootContainer = document.createElement('div');
             this.rootContainer.id = 'weld-container';
             this.rootContainer.className = 'weld-namespace';
+            this.rootContainer.setAttribute('data-widget-id', this.config.widgetId);
             // Create app container
             this.appContainer = document.createElement('div');
             this.appContainer.className = 'weld-app';
@@ -474,17 +448,7 @@
          * Generate CSS for containers
          */
         generateCSS() {
-            const { customization } = this.config;
             return `
-      /* Weld Container */
-      #weld-container {
-        --weld-color-primary: ${customization.primaryColor};
-        --weld-color-accent: ${customization.accentColor};
-        --weld-font-family: ${customization.fontFamily};
-        --weld-font-size-base: ${customization.fontSize};
-        --weld-radius-xl: ${customization.borderRadius};
-      }
-
       /* Import main stylesheet */
       @import url('/styles/index.css');
 
@@ -508,20 +472,27 @@
          * Create launcher iframe
          */
         async createLauncherIframe() {
+            // Guard: skip if launcher iframe already exists
+            if (this.iframes.has(exports.IframeType.LAUNCHER)) {
+                this.logger.debug('Launcher iframe already exists, skipping creation');
+                return;
+            }
             const { iframes } = this.config;
             const { launcher } = iframes;
             // Create container
             const container = document.createElement('div');
             container.className = 'weld-launcher-frame';
             container.setAttribute('data-state', 'visible');
+            // Container is larger than the button to allow hover animations (scale, shadow) without clipping
+            const launcherPadding = 10;
             container.style.cssText = `
       position: fixed;
-      bottom: ${launcher.position.bottom};
-      right: ${launcher.position.right};
-      width: ${launcher.size};
-      height: ${launcher.size};
+      bottom: calc(${launcher.position.bottom} - ${launcherPadding}px);
+      right: calc(${launcher.position.right} - ${launcherPadding}px);
+      width: calc(${launcher.size} + ${launcherPadding * 2}px);
+      height: calc(${launcher.size} + ${launcherPadding * 2}px);
       z-index: 2147483003;
-      pointer-events: auto;
+      pointer-events: none;
       display: block;
     `;
             // Create iframe
@@ -533,8 +504,12 @@
       width: 100%;
       height: 100%;
       border: none;
-      background: transparent;
+      background: none;
+      color-scheme: none;
       display: block;
+      pointer-events: auto;
+      border-radius: 50%;
+      filter: drop-shadow(rgba(9, 14, 21, 0.54) 0px 1px 6px) drop-shadow(rgba(9, 14, 21, 0.9) 0px 2px 32px);
     `;
             iframe.setAttribute('allow', 'clipboard-write');
             iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-popups');
@@ -550,20 +525,36 @@
                 createdAt: Date.now(),
             });
             // When DOM loads, notify MessageBroker to send weld:init
+            let launcherRetried = false;
             iframe.onload = () => {
                 const metadata = this.iframes.get(exports.IframeType.LAUNCHER);
                 if (metadata) {
                     this.logger.debug('Launcher iframe DOM loaded');
-                    // Notify MessageBroker that DOM is loaded (triggers weld:init)
                     this.messageBroker?.setIframeDomLoaded(exports.IframeType.LAUNCHER);
                 }
             };
+            iframe.onerror = () => {
+                this.logger.error('Launcher iframe failed to load');
+                if (!launcherRetried) {
+                    launcherRetried = true;
+                    this.logger.info('Retrying launcher iframe load...');
+                    setTimeout(() => { iframe.src = this.buildIframeUrl(launcher.url); }, 3000);
+                }
+                else {
+                    this.config.onError?.(new Error('Failed to load widget launcher'));
+                }
+            };
             this.logger.debug('Launcher iframe created');
         }
         /**
          * Create widget iframe
          */
         async createWidgetIframe() {
+            // Guard: skip if widget iframe already exists
+            if (this.iframes.has(exports.IframeType.WIDGET)) {
+                this.logger.debug('Widget iframe already exists, skipping creation');
+                return;
+            }
             const { iframes } = this.config;
             const { widget } = iframes;
             // Create container
@@ -644,54 +635,32 @@
                 createdAt: Date.now(),
             });
             // When DOM loads, notify MessageBroker to send weld:init
+            let widgetRetried = false;
             iframe.onload = () => {
                 const metadata = this.iframes.get(exports.IframeType.WIDGET);
                 if (metadata) {
                     this.logger.debug('Widget iframe DOM loaded');
-                    // Notify MessageBroker that DOM is loaded (triggers weld:init)
                     this.messageBroker?.setIframeDomLoaded(exports.IframeType.WIDGET);
                 }
             };
+            iframe.onerror = () => {
+                this.logger.error('Widget iframe failed to load');
+                if (!widgetRetried) {
+                    widgetRetried = true;
+                    this.logger.info('Retrying widget iframe load...');
+                    setTimeout(() => { iframe.src = this.buildIframeUrl(widget.url); }, 3000);
+                }
+                else {
+                    this.config.onError?.(new Error('Failed to load widget'));
+                }
+            };
             this.logger.debug('Widget iframe created');
         }
         /**
-         * Create backdrop iframe
+         * Create backdrop iframe — disabled, widget stays non-modal so users can interact with the page
          */
         async createBackdropIframe() {
-            if (!this.config.iframes.backdrop?.enabled) {
-                this.logger.debug('Backdrop disabled, skipping creation');
-                return;
-            }
-            // Create container
-            const container = document.createElement('div');
-            container.className = 'weld-backdrop-frame';
-            container.setAttribute('data-state', 'hidden');
-            container.style.cssText = `
-      position: fixed;
-      top: 0;
-      left: 0;
-      right: 0;
-      bottom: 0;
-      z-index: 2147483000;
-      background: transparent;
-      pointer-events: none;
-      opacity: 0;
-      transition: opacity 200ms ease;
-    `;
-            this.appContainer?.appendChild(container);
-            // Store metadata (backdrop doesn't have an iframe, just a div)
-            // We'll create a minimal "iframe" reference for consistency
-            const dummyIframe = document.createElement('iframe');
-            dummyIframe.style.display = 'none';
-            this.iframes.set(exports.IframeType.BACKDROP, {
-                type: exports.IframeType.BACKDROP,
-                element: dummyIframe,
-                container,
-                ready: true, // Backdrop is always ready
-                visible: false,
-                createdAt: Date.now(),
-            });
-            this.logger.debug('Backdrop created');
+            this.logger.debug('Backdrop disabled, skipping creation');
         }
         /**
          * Build iframe URL with parameters
@@ -705,12 +674,21 @@
             url.searchParams.set('device', this.deviceInfo.type);
             url.searchParams.set('mobile', String(this.deviceInfo.isMobile));
             url.searchParams.set('parentOrigin', window.location.origin);
+            if (this.config.testMode) {
+                url.searchParams.set('testMode', 'true');
+            }
             return url.toString();
         }
         /**
          * Setup event listeners
          */
         setupEventListeners() {
+            // Guard: prevent double-binding
+            if (this.eventListenersBound) {
+                this.logger.debug('Event listeners already bound, skipping');
+                return;
+            }
+            this.eventListenersBound = true;
             // Window resize - use bound handler for proper cleanup
             window.addEventListener('resize', this.boundHandleResize);
             // Orientation change - use bound handler for proper cleanup
@@ -813,7 +791,7 @@
                 iframe.container.style.transform = 'scale(1) translateY(0)';
             }
             // Handle mobile scroll lock
-            if (this.deviceInfo.isMobile && type === exports.IframeType.WIDGET && this.config.mobile.scrollLock) {
+            if (this.deviceInfo.isMobile && type === exports.IframeType.WIDGET) {
                 document.body.classList.add('weld-mobile-open');
             }
             // Hide launcher on mobile when widget is open (full-screen mode)
@@ -912,6 +890,8 @@
             this.iframes.clear();
             // Clear messageBroker reference
             this.messageBroker = null;
+            // Reset guard flag
+            this.eventListenersBound = false;
             this.logger.info('IframeManager destroyed');
         }
     }
@@ -979,6 +959,8 @@
         // Events
         MessageType["EVENT_TRACK"] = "weld:event:track";
         MessageType["ERROR_REPORT"] = "weld:error:report";
+        // Page tracking
+        MessageType["PAGE_CHANGE"] = "weld:page:change";
         // API responses
         MessageType["API_SUCCESS"] = "weld:api:success";
         MessageType["API_ERROR"] = "weld:api:error";
@@ -1557,8 +1539,6 @@
                 iframeType,
                 config: {
                     api: this.config.api,
-                    customization: this.config.customization,
-                    features: this.config.features,
                 },
             };
             const message = createMessage('weld:init', MessageOrigin.PARENT, initPayload);
@@ -2401,7 +2381,7 @@
         }
     }
 
-    var version = "1.0.15";
+    var version = "1.0.17";
     var packageJson = {
     	version: version};
 
@@ -2409,6 +2389,16 @@
      * Weld SDK - Main Entry Point
      * Public API for the Weld helpdesk widget
      */
+    /**
+     * Module-level singleton registry keyed by widgetId
+     */
+    const sdkRegistry = new Map();
+    /**
+     * SessionStorage key helpers
+     */
+    function openStateKey(widgetId) {
+        return `weld-widget-open-${widgetId}`;
+    }
     /**
      * SDK initialization status
      */
@@ -2431,6 +2421,8 @@
             this.readyResolve = null;
             // Subscription IDs for cleanup
             this.subscriptionIds = [];
+            // Page tracking cleanup
+            this.pageTrackingCleanup = null;
             /**
              * Update user attributes (Intercom-style, with rate limiting)
              * Limited to 20 calls per page load to prevent abuse
@@ -2469,6 +2461,13 @@
                 console.log('[Weld SDK] Received message:', event.data.type);
             }
             if (event.data?.type === 'launcher:clicked') {
+                if (this.status !== SDKStatus.READY) {
+                    console.log('[Weld SDK] Launcher clicked but SDK not ready yet — waiting...');
+                    this.readyPromise?.then(() => {
+                        this.handleLauncherClickMessage(event);
+                    });
+                    return;
+                }
                 // Toggle behavior - if widget is open, close it; if closed, open it
                 const state = this.stateCoordinator.getState();
                 if (state.widget.isOpen) {
@@ -2481,9 +2480,260 @@
                 }
             }
             if (event.data?.type === 'weld:close') {
+                if (this.status !== SDKStatus.READY)
+                    return;
                 console.log('[Weld SDK] Widget close requested');
                 this.close();
             }
+            if (event.data?.type === 'weld:unread-count') {
+                const count = event.data.count ?? 0;
+                // Forward to launcher iframe
+                const launcherIframe = this.iframeManager.getIframe(exports.IframeType.LAUNCHER);
+                if (launcherIframe?.element?.contentWindow) {
+                    launcherIframe.element.contentWindow.postMessage({
+                        type: 'weld:unread-count',
+                        count
+                    }, '*');
+                }
+                // Update state coordinator for external API consumers
+                this.stateCoordinator.setBadgeCount(count);
+            }
+            if (event.data?.type === 'weld:image:open' && event.data?.url) {
+                this.showImageLightbox(event.data.url);
+            }
+        }
+        /**
+         * Show fullscreen image lightbox on the parent page
+         */
+        showImageLightbox(url) {
+            // Remove existing lightbox if any
+            const existing = document.getElementById('weld-image-lightbox');
+            if (existing)
+                existing.remove();
+            // Zoom / pan state
+            let scale = 1;
+            let translateX = 0;
+            let translateY = 0;
+            let isDragging = false;
+            let dragStartX = 0;
+            let dragStartY = 0;
+            let lastTranslateX = 0;
+            let lastTranslateY = 0;
+            const applyTransform = () => {
+                img.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})`;
+            };
+            const resetTransform = () => {
+                scale = 1;
+                translateX = 0;
+                translateY = 0;
+                applyTransform();
+                img.style.cursor = 'zoom-in';
+            };
+            const overlay = document.createElement('div');
+            overlay.id = 'weld-image-lightbox';
+            overlay.style.cssText = `
+      position: fixed;
+      inset: 0;
+      z-index: 2147483647;
+      background: rgba(0, 0, 0, 0.92);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 16px;
+      cursor: pointer;
+      overflow: hidden;
+    `;
+            // Close button
+            const closeBtn = document.createElement('button');
+            closeBtn.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"></line><line x1="6" y1="6" x2="18" y2="18"></line></svg>`;
+            closeBtn.style.cssText = `
+      position: absolute;
+      top: 16px;
+      right: 16px;
+      width: 40px;
+      height: 40px;
+      border-radius: 50%;
+      border: none;
+      background: rgba(255, 255, 255, 0.1);
+      color: white;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: background 0.15s;
+    `;
+            closeBtn.onmouseenter = () => { closeBtn.style.background = 'rgba(255, 255, 255, 0.2)'; };
+            closeBtn.onmouseleave = () => { closeBtn.style.background = 'rgba(255, 255, 255, 0.1)'; };
+            // Download button
+            const downloadBtn = document.createElement('a');
+            downloadBtn.href = url;
+            downloadBtn.download = '';
+            downloadBtn.target = '_blank';
+            downloadBtn.rel = 'noopener noreferrer';
+            downloadBtn.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"></path><polyline points="7 10 12 15 17 10"></polyline><line x1="12" y1="15" x2="12" y2="3"></line></svg>`;
+            downloadBtn.style.cssText = `
+      position: absolute;
+      top: 16px;
+      right: 64px;
+      width: 40px;
+      height: 40px;
+      border-radius: 50%;
+      border: none;
+      background: rgba(255, 255, 255, 0.1);
+      color: white;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: background 0.15s;
+      text-decoration: none;
+    `;
+            downloadBtn.onmouseenter = () => { downloadBtn.style.background = 'rgba(255, 255, 255, 0.2)'; };
+            downloadBtn.onmouseleave = () => { downloadBtn.style.background = 'rgba(255, 255, 255, 0.1)'; };
+            // Image
+            const img = document.createElement('img');
+            img.src = url;
+            img.alt = 'Full size';
+            img.draggable = false;
+            img.style.cssText = `
+      max-width: 100%;
+      max-height: 100%;
+      object-fit: contain;
+      border-radius: 8px;
+      cursor: zoom-in;
+      transition: transform 0.2s ease;
+      user-select: none;
+    `;
+            // Click to toggle zoom
+            img.addEventListener('click', (e) => {
+                e.stopPropagation();
+                if (scale === 1) {
+                    // Zoom in to 2.5x centered on click position
+                    const rect = img.getBoundingClientRect();
+                    const clickX = e.clientX - rect.left - rect.width / 2;
+                    const clickY = e.clientY - rect.top - rect.height / 2;
+                    scale = 2.5;
+                    translateX = -clickX * 1.5;
+                    translateY = -clickY * 1.5;
+                    applyTransform();
+                    img.style.cursor = 'zoom-out';
+                }
+                else {
+                    // Zoom out - reset
+                    resetTransform();
+                }
+            });
+            // Mouse wheel zoom
+            overlay.addEventListener('wheel', (e) => {
+                e.preventDefault();
+                const delta = e.deltaY > 0 ? -0.25 : 0.25;
+                const newScale = Math.min(Math.max(scale + delta, 1), 5);
+                if (newScale === 1) {
+                    resetTransform();
+                }
+                else {
+                    scale = newScale;
+                    applyTransform();
+                    img.style.cursor = 'zoom-out';
+                }
+            }, { passive: false });
+            // Drag to pan when zoomed
+            img.addEventListener('mousedown', (e) => {
+                if (scale <= 1)
+                    return;
+                e.preventDefault();
+                isDragging = true;
+                dragStartX = e.clientX;
+                dragStartY = e.clientY;
+                lastTranslateX = translateX;
+                lastTranslateY = translateY;
+                img.style.cursor = 'grabbing';
+                img.style.transition = 'none';
+            });
+            window.addEventListener('mousemove', (e) => {
+                if (!isDragging)
+                    return;
+                translateX = lastTranslateX + (e.clientX - dragStartX);
+                translateY = lastTranslateY + (e.clientY - dragStartY);
+                applyTransform();
+            });
+            window.addEventListener('mouseup', () => {
+                if (!isDragging)
+                    return;
+                isDragging = false;
+                img.style.cursor = scale > 1 ? 'zoom-out' : 'zoom-in';
+                img.style.transition = 'transform 0.2s ease';
+            });
+            // Touch: pinch to zoom + drag to pan
+            let lastTouchDist = 0;
+            let lastTouchScale = 1;
+            overlay.addEventListener('touchstart', (e) => {
+                if (e.touches.length === 2) {
+                    e.preventDefault();
+                    const dx = e.touches[0].clientX - e.touches[1].clientX;
+                    const dy = e.touches[0].clientY - e.touches[1].clientY;
+                    lastTouchDist = Math.hypot(dx, dy);
+                    lastTouchScale = scale;
+                }
+                else if (e.touches.length === 1 && scale > 1) {
+                    isDragging = true;
+                    dragStartX = e.touches[0].clientX;
+                    dragStartY = e.touches[0].clientY;
+                    lastTranslateX = translateX;
+                    lastTranslateY = translateY;
+                    img.style.transition = 'none';
+                }
+            }, { passive: false });
+            overlay.addEventListener('touchmove', (e) => {
+                if (e.touches.length === 2) {
+                    e.preventDefault();
+                    const dx = e.touches[0].clientX - e.touches[1].clientX;
+                    const dy = e.touches[0].clientY - e.touches[1].clientY;
+                    const dist = Math.hypot(dx, dy);
+                    scale = Math.min(Math.max(lastTouchScale * (dist / lastTouchDist), 1), 5);
+                    if (scale === 1) {
+                        translateX = 0;
+                        translateY = 0;
+                    }
+                    applyTransform();
+                }
+                else if (e.touches.length === 1 && isDragging) {
+                    e.preventDefault();
+                    translateX = lastTranslateX + (e.touches[0].clientX - dragStartX);
+                    translateY = lastTranslateY + (e.touches[0].clientY - dragStartY);
+                    applyTransform();
+                }
+            }, { passive: false });
+            overlay.addEventListener('touchend', (e) => {
+                if (e.touches.length < 2) {
+                    lastTouchDist = 0;
+                }
+                if (e.touches.length === 0) {
+                    isDragging = false;
+                    img.style.transition = 'transform 0.2s ease';
+                }
+            });
+            const close = () => {
+                document.removeEventListener('keydown', handleKeyDown);
+                overlay.remove();
+            };
+            // Only close on backdrop click when not zoomed (prevent accidental close while panning)
+            overlay.addEventListener('click', (e) => {
+                if (e.target === overlay && scale <= 1)
+                    close();
+            });
+            downloadBtn.addEventListener('click', (e) => e.stopPropagation());
+            closeBtn.addEventListener('click', (e) => { e.stopPropagation(); close(); });
+            // Close on Escape
+            const handleKeyDown = (e) => {
+                if (e.key === 'Escape')
+                    close();
+            };
+            document.addEventListener('keydown', handleKeyDown);
+            overlay.appendChild(closeBtn);
+            overlay.appendChild(downloadBtn);
+            overlay.appendChild(img);
+            document.body.appendChild(overlay);
         }
         /**
          * Initialize the SDK and render widget
@@ -2509,6 +2759,13 @@
                 this.logger.info('WeldSDK ready');
                 // Call onReady callback
                 this.config.onReady?.();
+                // Start tracking page URL changes
+                this.startPageTracking();
+                // Auto-open if widget was previously open (persisted in sessionStorage)
+                if (this.wasOpen()) {
+                    this.logger.info('Restoring previously open widget from sessionStorage');
+                    this.open();
+                }
             }
             catch (error) {
                 this.status = SDKStatus.ERROR;
@@ -2587,6 +2844,58 @@
         isReady() {
             return this.status === SDKStatus.READY;
         }
+        /**
+         * Update callbacks on an existing instance (used by singleton reuse)
+         */
+        updateCallbacks(config) {
+            if (config.onReady !== undefined)
+                this.config.onReady = config.onReady;
+            if (config.onOpen !== undefined)
+                this.config.onOpen = config.onOpen;
+            if (config.onClose !== undefined)
+                this.config.onClose = config.onClose;
+            if (config.onError !== undefined)
+                this.config.onError = config.onError;
+            if (config.onDestroy !== undefined)
+                this.config.onDestroy = config.onDestroy;
+            if (config.onMinimize !== undefined)
+                this.config.onMinimize = config.onMinimize;
+            if (config.onMaximize !== undefined)
+                this.config.onMaximize = config.onMaximize;
+        }
+        /**
+         * Persist open/closed state to sessionStorage
+         */
+        persistOpenState(isOpen) {
+            try {
+                sessionStorage.setItem(openStateKey(this.config.widgetId), isOpen ? 'true' : 'false');
+            }
+            catch {
+                // sessionStorage might not be available
+            }
+        }
+        /**
+         * Clear persisted state from sessionStorage
+         */
+        clearPersistedState() {
+            try {
+                sessionStorage.removeItem(openStateKey(this.config.widgetId));
+            }
+            catch {
+                // sessionStorage might not be available
+            }
+        }
+        /**
+         * Check if widget was previously open (from sessionStorage)
+         */
+        wasOpen() {
+            try {
+                return sessionStorage.getItem(openStateKey(this.config.widgetId)) === 'true';
+            }
+            catch {
+                return false;
+            }
+        }
         /**
          * Open the widget
          */
@@ -2595,8 +2904,6 @@
             console.log('[Weld SDK] Opening widget...');
             this.stateCoordinator.openWidget();
             this.iframeManager.showIframe(exports.IframeType.WIDGET);
-            this.iframeManager.showIframe(exports.IframeType.BACKDROP);
-            // Keep launcher visible so user can click it to close the widget
             // Send open message to the widget iframe
             const widgetIframe = this.iframeManager.getIframe(exports.IframeType.WIDGET);
             if (widgetIframe?.element?.contentWindow) {
@@ -2607,6 +2914,7 @@
             if (launcherIframe?.element?.contentWindow) {
                 launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-opened' }, '*');
             }
+            this.persistOpenState(true);
             this.config.onOpen?.();
         }
         /**
@@ -2617,8 +2925,6 @@
             console.log('[Weld SDK] Closing widget...');
             this.stateCoordinator.closeWidget();
             this.iframeManager.hideIframe(exports.IframeType.WIDGET);
-            this.iframeManager.hideIframe(exports.IframeType.BACKDROP);
-            // Launcher stays visible
             // Send close message to the widget iframe
             const widgetIframe = this.iframeManager.getIframe(exports.IframeType.WIDGET);
             if (widgetIframe?.element?.contentWindow) {
@@ -2629,6 +2935,7 @@
             if (launcherIframe?.element?.contentWindow) {
                 launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-closed' }, '*');
             }
+            this.persistOpenState(false);
             this.config.onClose?.();
         }
         /**
@@ -2817,6 +3124,8 @@
             });
             // Broadcast logout to iframes
             this.messageBroker.broadcast('weld:auth:logout', {});
+            // Clear persisted widget state
+            this.clearPersistedState();
             // Clear any stored session data
             try {
                 const prefix = 'weld-';
@@ -2958,6 +3267,63 @@
             this.logger.setLevel('warn');
             this.logger.info('Debug mode disabled');
         }
+        /**
+         * Send a page change message to the widget iframe
+         */
+        sendPageChange(url, title) {
+            const widgetIframe = this.iframeManager.getIframe(exports.IframeType.WIDGET);
+            if (widgetIframe?.element?.contentWindow) {
+                widgetIframe.element.contentWindow.postMessage({
+                    type: 'weld:page:change',
+                    url,
+                    title,
+                    timestamp: Date.now(),
+                }, '*');
+            }
+        }
+        /**
+         * Start tracking page URL changes (SPA navigations + popstate)
+         */
+        startPageTracking() {
+            let lastUrl = window.location.href;
+            let debounceTimer = null;
+            const notifyChange = () => {
+                const currentUrl = window.location.href;
+                if (currentUrl !== lastUrl) {
+                    lastUrl = currentUrl;
+                    this.sendPageChange(currentUrl, document.title);
+                }
+            };
+            const debouncedNotify = () => {
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(notifyChange, 300);
+            };
+            // Send initial page
+            this.sendPageChange(window.location.href, document.title);
+            // Monkey-patch history.pushState and history.replaceState
+            const origPushState = history.pushState.bind(history);
+            const origReplaceState = history.replaceState.bind(history);
+            history.pushState = function (...args) {
+                origPushState(...args);
+                debouncedNotify();
+            };
+            history.replaceState = function (...args) {
+                origReplaceState(...args);
+                debouncedNotify();
+            };
+            // Listen for popstate (browser back/forward)
+            const handlePopstate = () => debouncedNotify();
+            window.addEventListener('popstate', handlePopstate);
+            // Store cleanup
+            this.pageTrackingCleanup = () => {
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                window.removeEventListener('popstate', handlePopstate);
+                history.pushState = origPushState;
+                history.replaceState = origReplaceState;
+            };
+        }
         /**
          * Ensure SDK is ready before operation
          */
@@ -2966,11 +3332,26 @@
                 throw new Error('SDK not ready. Call init() first.');
             }
         }
+        /**
+         * Detach from the current component lifecycle without destroying the widget.
+         * Use this as a React useEffect cleanup — the widget stays alive across navigations.
+         */
+        detach() {
+            // No-op: widget stays alive in the singleton registry
+            this.logger.debug('WeldSDK detached (no-op, widget stays alive)');
+        }
         /**
          * Destroy SDK and cleanup
          */
         destroy() {
             this.logger.info('Destroying WeldSDK');
+            // Remove from singleton registry
+            sdkRegistry.delete(this.config.widgetId);
+            // Clear persisted state
+            this.clearPersistedState();
+            // Stop page tracking
+            this.pageTrackingCleanup?.();
+            this.pageTrackingCleanup = null;
             // Remove event listener using bound handler
             window.removeEventListener('message', this.boundHandleLauncherClick);
             // Unsubscribe from all message broker subscriptions
@@ -2990,13 +3371,33 @@
         }
     }
     /**
-     * Create and initialize WeldSDK instance
+     * Create and initialize WeldSDK instance.
+     * Uses singleton pattern — if an instance for the same widgetId already exists
+     * and is not destroyed, updates callbacks and returns the existing instance.
      */
     async function createWeldSDK(config) {
+        const widgetId = config.widgetId;
+        // Check for existing, non-destroyed instance
+        const existing = sdkRegistry.get(widgetId);
+        if (existing && existing.getStatus() !== 'destroyed') {
+            existing.updateCallbacks(config);
+            return existing;
+        }
         const sdk = new WeldSDK(config);
+        sdkRegistry.set(widgetId, sdk);
         await sdk.init();
         return sdk;
     }
+    /**
+     * Explicitly destroy a WeldSDK instance by widgetId.
+     * Use this for logout or when you need to fully remove the widget.
+     */
+    function destroyWeldSDK(widgetId) {
+        const sdk = sdkRegistry.get(widgetId);
+        if (sdk) {
+            sdk.destroy();
+        }
+    }
 
     exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
     exports.HelpdeskWidget = WeldSDK;
@@ -3015,6 +3416,8 @@
     exports.deepMerge = deepMerge;
     exports.default = WeldSDK;
     exports.defaultLogger = defaultLogger;
+    exports.destroyHelpdeskWidget = destroyWeldSDK;
+    exports.destroyWeldSDK = destroyWeldSDK;
     exports.formatFileSize = formatFileSize;
     exports.getStateValue = getStateValue;
     exports.hasRequiredProperties = hasRequiredProperties;