@weldsuite/helpdesk-widget-sdk 1.0.15 → 1.0.17

package/dist/index.esm.js

@@ -31,32 +31,6 @@ const DEFAULT_CONFIG = {
             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',
@@ -100,6 +74,7 @@ function resolveConfig(config) {
     validateConfig(config);
     return {
         widgetId: config.widgetId,
+        testMode: config.testMode,
         api: {
             ...DEFAULT_CONFIG.api,
             widgetId: config.widgetId,
@@ -129,18 +104,6 @@ function resolveConfig(config) {
                 ...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,
@@ -383,6 +346,8 @@ class IframeManager {
         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();
@@ -422,18 +387,27 @@ class IframeManager {
     }
     /**
      * 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';
@@ -468,17 +442,7 @@ class IframeManager {
      * 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');
 
@@ -502,20 +466,27 @@ class IframeManager {
      * Create launcher iframe
      */
     async createLauncherIframe() {
+        // Guard: skip if launcher iframe already exists
+        if (this.iframes.has(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
@@ -527,8 +498,12 @@ class IframeManager {
       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');
@@ -544,20 +519,36 @@ class IframeManager {
             createdAt: Date.now(),
         });
         // When DOM loads, notify MessageBroker to send weld:init
+        let launcherRetried = false;
         iframe.onload = () => {
             const metadata = this.iframes.get(IframeType.LAUNCHER);
             if (metadata) {
                 this.logger.debug('Launcher iframe DOM loaded');
-                // Notify MessageBroker that DOM is loaded (triggers weld:init)
                 this.messageBroker?.setIframeDomLoaded(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(IframeType.WIDGET)) {
+            this.logger.debug('Widget iframe already exists, skipping creation');
+            return;
+        }
         const { iframes } = this.config;
         const { widget } = iframes;
         // Create container
@@ -638,54 +629,32 @@ class IframeManager {
             createdAt: Date.now(),
         });
         // When DOM loads, notify MessageBroker to send weld:init
+        let widgetRetried = false;
         iframe.onload = () => {
             const metadata = this.iframes.get(IframeType.WIDGET);
             if (metadata) {
                 this.logger.debug('Widget iframe DOM loaded');
-                // Notify MessageBroker that DOM is loaded (triggers weld:init)
                 this.messageBroker?.setIframeDomLoaded(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(IframeType.BACKDROP, {
-            type: 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
@@ -699,12 +668,21 @@ class IframeManager {
         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
@@ -807,7 +785,7 @@ class IframeManager {
             iframe.container.style.transform = 'scale(1) translateY(0)';
         }
         // Handle mobile scroll lock
-        if (this.deviceInfo.isMobile && type === IframeType.WIDGET && this.config.mobile.scrollLock) {
+        if (this.deviceInfo.isMobile && type === IframeType.WIDGET) {
             document.body.classList.add('weld-mobile-open');
         }
         // Hide launcher on mobile when widget is open (full-screen mode)
@@ -906,6 +884,8 @@ class IframeManager {
         this.iframes.clear();
         // Clear messageBroker reference
         this.messageBroker = null;
+        // Reset guard flag
+        this.eventListenersBound = false;
         this.logger.info('IframeManager destroyed');
     }
 }
@@ -973,6 +953,8 @@ var MessageType;
     // 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";
@@ -1551,8 +1533,6 @@ class MessageBroker {
             iframeType,
             config: {
                 api: this.config.api,
-                customization: this.config.customization,
-                features: this.config.features,
             },
         };
         const message = createMessage('weld:init', MessageOrigin.PARENT, initPayload);
@@ -2395,7 +2375,7 @@ class StateCoordinator {
     }
 }
 
-var version = "1.0.15";
+var version = "1.0.17";
 var packageJson = {
 	version: version};
 
@@ -2403,6 +2383,16 @@ var packageJson = {
  * 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
  */
@@ -2425,6 +2415,8 @@ class WeldSDK {
         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
@@ -2463,6 +2455,13 @@ class WeldSDK {
             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) {
@@ -2475,9 +2474,260 @@ class WeldSDK {
             }
         }
         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(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
@@ -2503,6 +2753,13 @@ class WeldSDK {
             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;
@@ -2581,6 +2838,58 @@ class WeldSDK {
     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
      */
@@ -2589,8 +2898,6 @@ class WeldSDK {
         console.log('[Weld SDK] Opening widget...');
         this.stateCoordinator.openWidget();
         this.iframeManager.showIframe(IframeType.WIDGET);
-        this.iframeManager.showIframe(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(IframeType.WIDGET);
         if (widgetIframe?.element?.contentWindow) {
@@ -2601,6 +2908,7 @@ class WeldSDK {
         if (launcherIframe?.element?.contentWindow) {
             launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-opened' }, '*');
         }
+        this.persistOpenState(true);
         this.config.onOpen?.();
     }
     /**
@@ -2611,8 +2919,6 @@ class WeldSDK {
         console.log('[Weld SDK] Closing widget...');
         this.stateCoordinator.closeWidget();
         this.iframeManager.hideIframe(IframeType.WIDGET);
-        this.iframeManager.hideIframe(IframeType.BACKDROP);
-        // Launcher stays visible
         // Send close message to the widget iframe
         const widgetIframe = this.iframeManager.getIframe(IframeType.WIDGET);
         if (widgetIframe?.element?.contentWindow) {
@@ -2623,6 +2929,7 @@ class WeldSDK {
         if (launcherIframe?.element?.contentWindow) {
             launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-closed' }, '*');
         }
+        this.persistOpenState(false);
         this.config.onClose?.();
     }
     /**
@@ -2811,6 +3118,8 @@ class WeldSDK {
         });
         // 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-';
@@ -2952,6 +3261,63 @@ class WeldSDK {
         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(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
      */
@@ -2960,11 +3326,26 @@ class WeldSDK {
             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
@@ -2984,13 +3365,33 @@ class WeldSDK {
     }
 }
 /**
- * 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();
+    }
+}
 
-export { DEFAULT_CONFIG, WeldSDK as HelpdeskWidget, IframeManager, IframeType, LogLevel, Logger, MessageBroker, RateLimiter, SecurityManager, StateCoordinator, TokenValidator, WeldSDK, createInitialState, createMessage, createWeldSDK, deepClone, deepMerge, WeldSDK as default, defaultLogger, formatFileSize, getStateValue, hasRequiredProperties, createWeldSDK as initHelpdeskWidget, isBaseMessage, isInRange, isPayloadMessage, isPlainObject, isValidApiKey, isValidArrayLength, isValidColor, isValidEmail, isValidFileSize, isValidFileType, isValidLength, isValidMessageText, isValidUrl, isValidWorkspaceId, resolveConfig, sanitizeHtml, sanitizeInput, setStateValue, validateConfig };
+export { DEFAULT_CONFIG, WeldSDK as HelpdeskWidget, IframeManager, IframeType, LogLevel, Logger, MessageBroker, RateLimiter, SecurityManager, StateCoordinator, TokenValidator, WeldSDK, createInitialState, createMessage, createWeldSDK, deepClone, deepMerge, WeldSDK as default, defaultLogger, destroyWeldSDK as destroyHelpdeskWidget, destroyWeldSDK, formatFileSize, getStateValue, hasRequiredProperties, createWeldSDK as initHelpdeskWidget, isBaseMessage, isInRange, isPayloadMessage, isPlainObject, isValidApiKey, isValidArrayLength, isValidColor, isValidEmail, isValidFileSize, isValidFileType, isValidLength, isValidMessageText, isValidUrl, isValidWorkspaceId, resolveConfig, sanitizeHtml, sanitizeInput, setStateValue, validateConfig };
 //# sourceMappingURL=index.esm.js.map