@weldsuite/helpdesk-widget-sdk 1.0.15 → 1.0.17

package/dist/index.js

@@ -35,32 +35,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',
@@ -104,6 +78,7 @@ function resolveConfig(config) {
     validateConfig(config);
     return {
         widgetId: config.widgetId,
+        testMode: config.testMode,
         api: {
             ...DEFAULT_CONFIG.api,
             widgetId: config.widgetId,
@@ -133,18 +108,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,
@@ -387,6 +350,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();
@@ -426,18 +391,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';
@@ -472,17 +446,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');
 
@@ -506,20 +470,27 @@ class IframeManager {
      * 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
@@ -531,8 +502,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');
@@ -548,20 +523,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(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
@@ -642,54 +633,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(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
@@ -703,12 +672,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
@@ -811,7 +789,7 @@ class IframeManager {
             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)
@@ -910,6 +888,8 @@ class IframeManager {
         this.iframes.clear();
         // Clear messageBroker reference
         this.messageBroker = null;
+        // Reset guard flag
+        this.eventListenersBound = false;
         this.logger.info('IframeManager destroyed');
     }
 }
@@ -977,6 +957,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";
@@ -1555,8 +1537,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);
@@ -2399,7 +2379,7 @@ class StateCoordinator {
     }
 }
 
-var version = "1.0.15";
+var version = "1.0.17";
 var packageJson = {
 	version: version};
 
@@ -2407,6 +2387,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
  */
@@ -2429,6 +2419,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
@@ -2467,6 +2459,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) {
@@ -2479,9 +2478,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(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
@@ -2507,6 +2757,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;
@@ -2585,6 +2842,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
      */
@@ -2593,8 +2902,6 @@ class WeldSDK {
         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) {
@@ -2605,6 +2912,7 @@ class WeldSDK {
         if (launcherIframe?.element?.contentWindow) {
             launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-opened' }, '*');
         }
+        this.persistOpenState(true);
         this.config.onOpen?.();
     }
     /**
@@ -2615,8 +2923,6 @@ class WeldSDK {
         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) {
@@ -2627,6 +2933,7 @@ class WeldSDK {
         if (launcherIframe?.element?.contentWindow) {
             launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-closed' }, '*');
         }
+        this.persistOpenState(false);
         this.config.onClose?.();
     }
     /**
@@ -2815,6 +3122,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-';
@@ -2956,6 +3265,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(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
      */
@@ -2964,11 +3330,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
@@ -2988,13 +3369,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();
+    }
+}
 
 exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 exports.HelpdeskWidget = WeldSDK;
@@ -3013,6 +3414,8 @@ exports.deepClone = deepClone;
 exports.deepMerge = deepMerge;
 exports.default = WeldSDK;
 exports.defaultLogger = defaultLogger;
+exports.destroyHelpdeskWidget = destroyWeldSDK;
+exports.destroyWeldSDK = destroyWeldSDK;
 exports.formatFileSize = formatFileSize;
 exports.getStateValue = getStateValue;
 exports.hasRequiredProperties = hasRequiredProperties;