@capgo/capacitor-updater 8.47.5 → 8.47.7

package/ios/Sources/CapacitorUpdaterPlugin/CapacitorUpdaterPlugin.swift

@@ -79,7 +79,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "completeFlexibleUpdate", returnType: CAPPluginReturnPromise)
     ]
     public var implementation = CapgoUpdater()
-    private let pluginVersion: String = "8.47.5"
+    private let pluginVersion: String = "8.47.7"
     static let updateUrlDefault = "https://plugin.capgo.app/updates"
     static let statsUrlDefault = "https://plugin.capgo.app/stats"
     static let channelUrlDefault = "https://plugin.capgo.app/channel_self"
@@ -89,6 +89,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     static let autoUpdateModeLaunch = "onLaunch"
     static let autoUpdateModeAlways = "always"
     static let autoUpdateModeOnlyDownload = "onlyDownload"
+    private static let previewLoaderTimeoutMs = 60000
     private let keepUrlPathFlagKey = "__capgo_keep_url_path_after_reload"
     private let customIdDefaultsKey = "CapacitorUpdater.customId"
     private let updateUrlDefaultsKey = "CapacitorUpdater.updateUrl"
@@ -131,6 +132,10 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     private var autoSplashscreenTimeoutWorkItem: DispatchWorkItem?
     private var splashscreenLoaderView: UIActivityIndicatorView?
     private var splashscreenLoaderContainer: UIView?
+    private var previewTransitionLoaderView: UIActivityIndicatorView?
+    private var previewTransitionLoaderContainer: UIView?
+    private var previewTransitionLoaderTimeoutWorkItem: DispatchWorkItem?
+    private var previewTransitionLoaderRequested = false
     private let splashscreenPluginName = "SplashScreen"
     private let splashscreenRetryDelayMilliseconds = 100
     private let splashscreenMaxRetries = 20
@@ -165,6 +170,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     public var previewSessionEnabled = false
     private var previewSessionAlertPending = false
     private var isLeavingPreviewForIncomingLink = false
+    private var previewTransitionClearWorkItem: DispatchWorkItem?
     let semaphoreReady = DispatchSemaphore(value: 0)
 
     private var delayUpdateUtils: DelayUpdateUtils!
@@ -242,7 +248,8 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         if previewSessionEnabled {
             previewSessionAlertPending = UserDefaults.standard.object(forKey: previewSessionAlertPendingDefaultsKey) as? Bool ?? true
             shakeMenuEnabled = true
-            shakeChannelSelectorEnabled = false
+            shakeChannelSelectorEnabled = UserDefaults.standard.object(forKey: previewPreviousShakeChannelSelectorDefaultsKey) as? Bool
+                ?? shakeChannelSelectorEnabled
         }
         periodCheckDelay = Self.normalizedPeriodCheckDelaySeconds(getConfig().getInt("periodCheckDelay", 0))
 
@@ -986,7 +993,10 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         let current: BundleInfo = self.implementation.getCurrentBundle()
         let next: BundleInfo? = self.implementation.getNextBundle()
 
-        if let next = next, !next.isErrorStatus(), next.getId() != current.getId() {
+        if !self.isPreviewSessionStateActive(),
+           let next = next,
+           !next.isErrorStatus(),
+           next.getId() != current.getId() {
             let previousState = self.implementation.captureResetState()
             let previousBundleName = self.implementation.getCurrentBundle().getVersionName()
             logger.info("Applying pending bundle before reload: \(next.toString())")
@@ -1025,6 +1035,28 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    private func applyDownloadedBundleForDirectUpdate(_ next: BundleInfo) -> Bool {
+        let previousState = self.implementation.captureResetState()
+        let previousBundleName = self.implementation.getCurrentBundle().getVersionName()
+
+        guard self.implementation.stagePendingReload(bundle: next) else {
+            self.implementation.restoreResetState(previousState)
+            logger.error("Direct update failed to stage downloaded bundle: \(next.toString())")
+            return false
+        }
+
+        if self._reload() {
+            self.implementation.finalizePendingReload(bundle: next, previousBundleName: previousBundleName)
+            _ = self.implementation.setNextBundle(next: Optional<String>.none)
+            return true
+        }
+
+        self.implementation.restoreResetState(previousState)
+        self.restoreLiveBundleStateAfterFailedReload()
+        logger.error("Direct update reload failed after staging bundle: \(next.toString())")
+        return false
+    }
+
     @objc func next(_ call: CAPPluginCall) {
         guard let id = call.getString("id") else {
             logger.error("Next called without id")
@@ -1060,8 +1092,40 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    private func isPreviewSessionStateActive() -> Bool {
+        self.previewSessionEnabled || self.isLeavingPreviewForIncomingLink || self.implementation.previewSession
+    }
+
+    private func shouldBlockAutoUpdateForPreviewSession() -> Bool {
+        guard self.isPreviewSessionStateActive() else {
+            return false
+        }
+
+        logger.info("Preview session is active. Skipping normal auto-update work.")
+        return true
+    }
+
+    private func clearIncomingPreviewTransition() {
+        self.previewTransitionClearWorkItem?.cancel()
+        self.previewTransitionClearWorkItem = nil
+        self.isLeavingPreviewForIncomingLink = false
+        if !self.previewSessionEnabled {
+            self.implementation.previewSession = false
+        }
+    }
+
+    private func scheduleIncomingPreviewTransitionFallbackClear() {
+        self.previewTransitionClearWorkItem?.cancel()
+        let workItem = DispatchWorkItem { [weak self] in
+            self?.clearIncomingPreviewTransition()
+        }
+        self.previewTransitionClearWorkItem = workItem
+        DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(self.appReadyTimeout), execute: workItem)
+    }
+
     @objc func startPreviewSession(_ call: CAPPluginCall) {
         guard self.allowPreview else {
+            self.hidePreviewTransitionLoader(reason: "preview-session-not-allowed")
             logger.error("startPreviewSession called without allowPreview")
             call.reject("startPreviewSession not allowed. Set allowPreview to true in your config to enable it.")
             return
@@ -1070,6 +1134,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         let rawPayloadUrl = call.getString("payloadUrl")
         let previewPayloadUrl = self.normalizedPreviewPayloadUrl(rawPayloadUrl)
         if let rawPayloadUrl = rawPayloadUrl, !rawPayloadUrl.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty, previewPayloadUrl == nil {
+            self.hidePreviewTransitionLoader(reason: "preview-session-invalid-payload")
             logger.error("startPreviewSession called with invalid payloadUrl")
             call.reject("Invalid preview payloadUrl")
             return
@@ -1078,6 +1143,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         if !self.previewSessionEnabled {
             let current = self.implementation.getCurrentBundle()
             guard self.implementation.setPreviewFallbackBundle(fallback: current.getId()) else {
+                self.hidePreviewTransitionLoader(reason: "preview-session-fallback-failed")
                 logger.error("Could not save current bundle as preview fallback")
                 call.reject("Could not save current bundle as preview fallback")
                 return
@@ -1117,11 +1183,12 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             UserDefaults.standard.removeObject(forKey: self.previewPayloadUrlDefaultsKey)
         }
 
+        self.clearIncomingPreviewTransition()
+        self.hidePreviewTransitionLoader(reason: "preview-session-started")
         self.previewSessionEnabled = true
         self.previewSessionAlertPending = true
         self.implementation.previewSession = true
         self.shakeMenuEnabled = true
-        self.shakeChannelSelectorEnabled = false
         UserDefaults.standard.set(true, forKey: self.previewSessionDefaultsKey)
         UserDefaults.standard.set(true, forKey: self.previewSessionAlertPendingDefaultsKey)
         UserDefaults.standard.synchronize()
@@ -1131,8 +1198,10 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     func leavePreviewSessionFromShakeMenu() -> Bool {
         let previewBundle = self.implementation.getCurrentBundle()
 
+        self.showPreviewTransitionLoader(reason: "leave-preview-session")
         let didReset = self.resetToPreviewFallbackBundle()
         guard didReset else {
+            self.hidePreviewTransitionLoader(reason: "leave-preview-session-failed")
             return false
         }
 
@@ -1152,14 +1221,16 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         }
 
         self.isLeavingPreviewForIncomingLink = true
+        self.showPreviewTransitionLoader(reason: "preview-launch-deeplink")
         logger.info("Preview deeplink launch detected while preview session is active; restoring fallback before initial load")
         if !self.leavePreviewSessionWithoutReload() {
             logger.error("Could not leave preview session before initial preview deeplink routing")
             self.isLeavingPreviewForIncomingLink = false
+            self.hidePreviewTransitionLoader(reason: "preview-launch-deeplink-failed")
         }
     }
 
-    private func leavePreviewSessionWithoutReload() -> Bool {
+    private func leavePreviewSessionWithoutReload(keepPreviewGuard: Bool = false) -> Bool {
         let previewBundle = self.implementation.getCurrentBundle()
         guard let previewFallbackBundle = self.implementation.getPreviewFallbackBundle(), !previewFallbackBundle.isErrorStatus() else {
             logger.error("No preview fallback bundle available")
@@ -1174,12 +1245,55 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             return false
         }
 
-        self.endPreviewSession()
+        self.endPreviewSession(keepPreviewGuard: keepPreviewGuard)
         let restoredNextBundle = self.implementation.getNextBundle()
         self.deletePreviewBundleIfUnused(previewBundle, previewFallbackBundle: previewFallbackBundle, restoredNextBundle: restoredNextBundle)
         return true
     }
 
+    private func leavePreviewSessionForIncomingPreviewLink() -> Bool {
+        self.showPreviewTransitionLoader(reason: "incoming-preview-deeplink")
+        let previewBundle = self.implementation.getCurrentBundle()
+        guard let previewFallbackBundle = self.implementation.getPreviewFallbackBundle(), !previewFallbackBundle.isErrorStatus() else {
+            logger.error("No preview fallback bundle available")
+            self.clearIncomingPreviewTransition()
+            self.hidePreviewTransitionLoader(reason: "incoming-preview-deeplink-failed")
+            return false
+        }
+        guard self.implementation.canSet(bundle: previewFallbackBundle) else {
+            logger.error("Preview fallback bundle is not installable")
+            self.clearIncomingPreviewTransition()
+            self.hidePreviewTransitionLoader(reason: "incoming-preview-deeplink-failed")
+            return false
+        }
+
+        let previousState = self.implementation.captureResetState()
+        guard self.implementation.stagePreviewFallbackReload(bundle: previewFallbackBundle) else {
+            logger.error("Could not stage preview fallback bundle")
+            self.clearIncomingPreviewTransition()
+            self.hidePreviewTransitionLoader(reason: "incoming-preview-deeplink-failed")
+            return false
+        }
+
+        let didReload = self._reload()
+        if didReload {
+            self.endPreviewSession(keepPreviewGuard: true)
+            let restoredNextBundle = self.implementation.getNextBundle()
+            self.deletePreviewBundleIfUnused(
+                previewBundle,
+                previewFallbackBundle: previewFallbackBundle,
+                restoredNextBundle: restoredNextBundle
+            )
+            self.scheduleIncomingPreviewTransitionFallbackClear()
+        } else {
+            self.implementation.restoreResetState(previousState)
+            self.restoreLiveBundleStateAfterFailedReload()
+            self.clearIncomingPreviewTransition()
+            self.hidePreviewTransitionLoader(reason: "incoming-preview-deeplink-reload-failed")
+        }
+        return didReload
+    }
+
     private func deletePreviewBundleIfUnused(
         _ previewBundle: BundleInfo,
         previewFallbackBundle: BundleInfo?,
@@ -1193,11 +1307,18 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     func reloadPreviewSessionFromShakeMenu() -> Bool {
+        self.showPreviewTransitionLoader(reason: "reload-preview-session")
+        let didReload: Bool
         if let payloadUrl = self.storedPreviewPayloadUrl() {
-            return self.refreshPreviewSessionFromPayloadUrl(payloadUrl)
+            didReload = self.refreshPreviewSessionFromPayloadUrl(payloadUrl)
+        } else {
+            didReload = self._reload()
         }
 
-        return self._reload()
+        if !didReload {
+            self.hidePreviewTransitionLoader(reason: "reload-preview-session-failed")
+        }
+        return didReload
     }
 
     func hasActivePreviewSession() -> Bool {
@@ -1228,7 +1349,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         return false
     }
 
-    private func endPreviewSession() {
+    private func endPreviewSession(keepPreviewGuard: Bool = false) {
         let previousShakeMenuEnabled = UserDefaults.standard.object(forKey: self.previewPreviousShakeMenuDefaultsKey) as? Bool
             ?? getConfig().getBoolean("shakeMenu", false)
         let previousShakeChannelSelectorEnabled = UserDefaults.standard.object(forKey: self.previewPreviousShakeChannelSelectorDefaultsKey) as? Bool
@@ -1239,8 +1360,11 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
 
         self.previewSessionEnabled = false
         self.previewSessionAlertPending = false
-        self.isLeavingPreviewForIncomingLink = false
-        self.implementation.previewSession = false
+        if keepPreviewGuard {
+            self.implementation.previewSession = true
+        } else {
+            self.clearIncomingPreviewTransition()
+        }
         self.shakeMenuEnabled = previousShakeMenuEnabled
         self.shakeChannelSelectorEnabled = previousShakeChannelSelectorEnabled
         _ = self.implementation.setPreviewFallbackBundle(fallback: nil)
@@ -1271,6 +1395,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         self.previewSessionAlertPending = false
         self.isLeavingPreviewForIncomingLink = false
         self.implementation.previewSession = false
+        self.hidePreviewTransitionLoader(reason: "preview-session-disabled")
         self.shakeMenuEnabled = getConfig().getBoolean("shakeMenu", false)
         self.shakeChannelSelectorEnabled = getConfig().getBoolean("allowShakeChannelSelector", false)
         self.clearPreviewSessionPreferences()
@@ -1393,12 +1518,14 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         }
 
         self.isLeavingPreviewForIncomingLink = true
+        self.showPreviewTransitionLoader(reason: "incoming-preview-deeplink")
         logger.info("Preview deeplink received while preview session is active; restoring fallback before routing")
         DispatchQueue.global(qos: .userInitiated).async {
-            let didLeave = self.leavePreviewSessionFromShakeMenu()
+            let didLeave = self.leavePreviewSessionForIncomingPreviewLink()
             if !didLeave {
                 self.logger.error("Could not leave preview session before routing incoming preview deeplink")
                 self.isLeavingPreviewForIncomingLink = false
+                self.hidePreviewTransitionLoader(reason: "incoming-preview-deeplink-failed")
             }
         }
     }
@@ -1701,6 +1828,9 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             logger.error("Error no url or wrong format")
             return "unavailable"
         }
+        if self.shouldBlockAutoUpdateForPreviewSession() {
+            return "preview_session"
+        }
         if self.isDownloadStuckOrTimedOut() {
             logger.info("Download already in progress, skipping duplicate download request")
             return "already_running"
@@ -1937,6 +2067,8 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         let bundle = self.implementation.getCurrentBundle()
         self.implementation.setSuccess(bundle: bundle, autoDeletePrevious: self.autoDeletePrevious)
         logger.info("Current bundle loaded successfully. [notifyAppReady was called] \(bundle.toString())")
+        self.clearIncomingPreviewTransition()
+        self.hidePreviewTransitionLoader(reason: "notify-app-ready")
 
         call.resolve(["bundle": bundle.toJSON()])
     }
@@ -1987,6 +2119,9 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     // Note: _checkCancelDelay method has been moved to DelayUpdateUtils class
 
     private func _isAutoUpdateEnabled() -> Bool {
+        if self.isPreviewSessionStateActive() {
+            return false
+        }
         let instanceDescriptor = (self.bridge?.viewController as? CAPBridgeViewController)?.instanceDescriptor()
         if instanceDescriptor?.serverURL != nil {
             logger.warn("AutoUpdate is automatic disabled when serverUrl is set.")
@@ -2024,6 +2159,10 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             logger.info("Built-in bundle is active. We skip the check for notifyAppReady.")
             return
         }
+        if self.isPreviewSessionStateActive() {
+            logger.info("Preview session is active. We skip the check for notifyAppReady.")
+            return
+        }
 
         logger.info("Current bundle is: \(current.toString())")
 
@@ -2076,6 +2215,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
             if self.autoSplashscreen {
                 self.hideSplashscreen()
             }
+            self.hidePreviewTransitionLoader(reason: "app-ready")
         }
     }
 
@@ -2243,6 +2383,51 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    private func createLoaderOverlay(
+        backgroundColor: UIColor,
+        isUserInteractionEnabled: Bool,
+        indicatorColor: UIColor?
+    ) -> (container: UIView, indicator: UIActivityIndicatorView) {
+        let container = UIView()
+        container.translatesAutoresizingMaskIntoConstraints = false
+        container.backgroundColor = backgroundColor
+        container.isUserInteractionEnabled = isUserInteractionEnabled
+
+        let indicatorStyle: UIActivityIndicatorView.Style
+        if #available(iOS 13.0, *) {
+            indicatorStyle = .large
+        } else {
+            indicatorStyle = .whiteLarge
+        }
+
+        let indicator = UIActivityIndicatorView(style: indicatorStyle)
+        indicator.translatesAutoresizingMaskIntoConstraints = false
+        indicator.hidesWhenStopped = false
+        if let indicatorColor = indicatorColor {
+            indicator.color = indicatorColor
+        }
+        indicator.startAnimating()
+
+        return (container, indicator)
+    }
+
+    private func attachLoaderOverlay(
+        _ overlay: (container: UIView, indicator: UIActivityIndicatorView),
+        to rootView: UIView
+    ) {
+        overlay.container.addSubview(overlay.indicator)
+        rootView.addSubview(overlay.container)
+
+        NSLayoutConstraint.activate([
+            overlay.container.leadingAnchor.constraint(equalTo: rootView.leadingAnchor),
+            overlay.container.trailingAnchor.constraint(equalTo: rootView.trailingAnchor),
+            overlay.container.topAnchor.constraint(equalTo: rootView.topAnchor),
+            overlay.container.bottomAnchor.constraint(equalTo: rootView.bottomAnchor),
+            overlay.indicator.centerXAnchor.constraint(equalTo: overlay.container.centerXAnchor),
+            overlay.indicator.centerYAnchor.constraint(equalTo: overlay.container.centerYAnchor)
+        ])
+    }
+
     private func addSplashscreenLoaderIfNeeded() {
         guard self.autoSplashscreenLoader else {
             return
@@ -2257,40 +2442,20 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                 return
             }
 
-            let container = UIView()
-            container.translatesAutoresizingMaskIntoConstraints = false
-            container.backgroundColor = UIColor.clear
-            container.isUserInteractionEnabled = false
-
-            let indicatorStyle: UIActivityIndicatorView.Style
+            let indicatorColor: UIColor?
             if #available(iOS 13.0, *) {
-                indicatorStyle = .large
+                indicatorColor = UIColor.label
             } else {
-                indicatorStyle = .whiteLarge
-            }
-
-            let indicator = UIActivityIndicatorView(style: indicatorStyle)
-            indicator.translatesAutoresizingMaskIntoConstraints = false
-            indicator.hidesWhenStopped = false
-            if #available(iOS 13.0, *) {
-                indicator.color = UIColor.label
+                indicatorColor = nil
             }
-            indicator.startAnimating()
-
-            container.addSubview(indicator)
-            rootView.addSubview(container)
-
-            NSLayoutConstraint.activate([
-                container.leadingAnchor.constraint(equalTo: rootView.leadingAnchor),
-                container.trailingAnchor.constraint(equalTo: rootView.trailingAnchor),
-                container.topAnchor.constraint(equalTo: rootView.topAnchor),
-                container.bottomAnchor.constraint(equalTo: rootView.bottomAnchor),
-                indicator.centerXAnchor.constraint(equalTo: container.centerXAnchor),
-                indicator.centerYAnchor.constraint(equalTo: container.centerYAnchor)
-            ])
-
-            self.splashscreenLoaderContainer = container
-            self.splashscreenLoaderView = indicator
+            let overlay = self.createLoaderOverlay(
+                backgroundColor: UIColor.clear,
+                isUserInteractionEnabled: false,
+                indicatorColor: indicatorColor
+            )
+            self.attachLoaderOverlay(overlay, to: rootView)
+            self.splashscreenLoaderContainer = overlay.container
+            self.splashscreenLoaderView = overlay.indicator
         }
 
         if Thread.isMainThread {
@@ -2319,6 +2484,97 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
+    private func showPreviewTransitionLoader(reason: String) {
+        self.previewTransitionLoaderRequested = true
+        let showLoader = {
+            guard self.previewTransitionLoaderRequested else {
+                return
+            }
+
+            if let container = self.previewTransitionLoaderContainer {
+                self.previewTransitionLoaderTimeoutWorkItem?.cancel()
+                self.schedulePreviewTransitionLoaderTimeout()
+                container.superview?.bringSubviewToFront(container)
+                return
+            }
+
+            guard let rootView = self.bridge?.viewController?.view else {
+                self.logger.warn("Preview transition loader unavailable: root view missing for \(reason)")
+                self.previewTransitionLoaderRequested = false
+                return
+            }
+
+            self.previewTransitionLoaderTimeoutWorkItem?.cancel()
+            self.schedulePreviewTransitionLoaderTimeout()
+
+            let indicatorColor: UIColor?
+            if #available(iOS 13.0, *) {
+                indicatorColor = UIColor.white
+            } else {
+                indicatorColor = nil
+            }
+            let overlay = self.createLoaderOverlay(
+                backgroundColor: UIColor.black.withAlphaComponent(0.18),
+                isUserInteractionEnabled: true,
+                indicatorColor: indicatorColor
+            )
+            self.attachLoaderOverlay(overlay, to: rootView)
+            self.previewTransitionLoaderContainer = overlay.container
+            self.previewTransitionLoaderView = overlay.indicator
+            self.logger.info("Preview transition loader shown: \(reason)")
+        }
+
+        if Thread.isMainThread {
+            showLoader()
+        } else {
+            DispatchQueue.main.async {
+                showLoader()
+            }
+        }
+    }
+
+    private func hidePreviewTransitionLoader(reason: String) {
+        if !self.previewTransitionLoaderRequested &&
+            self.previewTransitionLoaderContainer == nil &&
+            self.previewTransitionLoaderTimeoutWorkItem == nil {
+            return
+        }
+
+        let hideLoader = {
+            self.previewTransitionLoaderRequested = false
+            self.previewTransitionLoaderTimeoutWorkItem?.cancel()
+            self.previewTransitionLoaderTimeoutWorkItem = nil
+            guard self.previewTransitionLoaderContainer != nil else {
+                return
+            }
+            self.previewTransitionLoaderView?.stopAnimating()
+            self.previewTransitionLoaderContainer?.removeFromSuperview()
+            self.previewTransitionLoaderView = nil
+            self.previewTransitionLoaderContainer = nil
+            self.logger.info("Preview transition loader hidden: \(reason)")
+        }
+
+        if Thread.isMainThread {
+            hideLoader()
+        } else {
+            DispatchQueue.main.async {
+                hideLoader()
+            }
+        }
+    }
+
+    private func schedulePreviewTransitionLoaderTimeout() {
+        self.previewTransitionLoaderTimeoutWorkItem?.cancel()
+        let workItem = DispatchWorkItem { [weak self] in
+            self?.hidePreviewTransitionLoader(reason: "preview-transition-timeout")
+        }
+        self.previewTransitionLoaderTimeoutWorkItem = workItem
+        DispatchQueue.main.asyncAfter(
+            deadline: .now() + .milliseconds(Self.previewLoaderTimeoutMs),
+            execute: workItem
+        )
+    }
+
     private func scheduleSplashscreenTimeout() {
         guard self.autoSplashscreenTimeout > 0 else {
             return
@@ -2693,6 +2949,13 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         return true
     }
 
+    private func clearDownloadInProgressState() {
+        downloadLock.lock()
+        defer { downloadLock.unlock() }
+        downloadInProgress = false
+        downloadStartTime = nil
+    }
+
     func runBackgroundDownloadWork(_ work: @escaping () -> Void) {
         // Live update checks/downloads are user-visible work. Using `.background`
         // lets the scheduler starve them for minutes while the app is active.
@@ -2718,6 +2981,9 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     func backgroundDownload() {
+        if self.shouldBlockAutoUpdateForPreviewSession() {
+            return
+        }
         // Set download in progress flag (thread-safe)
         downloadLock.lock()
         downloadInProgress = true
@@ -2746,10 +3012,19 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
         self.runBackgroundDownloadWork {
             // Wait for cleanup to complete before starting download
             self.waitForCleanupIfNeeded()
+            if self.shouldBlockAutoUpdateForPreviewSession() {
+                self.clearDownloadInProgressState()
+                return
+            }
             self.beginDownloadBackgroundTask()
             self.logger.info("Check for update via \(self.updateUrl)")
             let res = self.implementation.getLatest(url: url, channel: nil)
             let current = self.implementation.getCurrentBundle()
+            if self.shouldBlockAutoUpdateForPreviewSession() {
+                self.clearDownloadInProgressState()
+                self.endBackGroundTask()
+                return
+            }
 
             // Handle network errors and other failures first
             let backendError = res.error ?? ""
@@ -2861,6 +3136,11 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                         )
                         return
                     }
+                    if self.shouldBlockAutoUpdateForPreviewSession() {
+                        self.clearDownloadInProgressState()
+                        self.endBackGroundTask()
+                        return
+                    }
                     res.checksum = try CryptoCipher.decryptChecksum(checksum: res.checksum, publicKey: self.implementation.publicKey)
                     CryptoCipher.logChecksumInfo(label: "Bundle checksum", hexChecksum: next.getChecksum())
                     CryptoCipher.logChecksumInfo(label: "Expected checksum", hexChecksum: res.checksum)
@@ -2880,6 +3160,11 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                         )
                         return
                     }
+                    if self.shouldBlockAutoUpdateForPreviewSession() {
+                        self.clearDownloadInProgressState()
+                        self.endBackGroundTask()
+                        return
+                    }
                     let directUpdateAllowed = plannedDirectUpdate && !self.autoSplashscreenTimedOut
                     if directUpdateAllowed {
                         let delayUpdatePreferences = UserDefaults.standard.string(forKey: DelayUpdateUtils.DELAY_CONDITION_PREFERENCES) ?? "[]"
@@ -2899,7 +3184,7 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                             )
                             return
                         }
-                        if self.implementation.set(bundle: next) && self._reload() {
+                        if self.applyDownloadedBundleForDirectUpdate(next) {
                             self.notifyBundleSet(next)
                             self.endBackGroundTaskWithNotif(
                                 msg: "update installed",
@@ -2909,10 +3194,13 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                                 plannedDirectUpdate: plannedDirectUpdate
                             )
                         } else {
+                            _ = self.implementation.setNextBundle(next: next.getId())
+                            self.notifyListeners("updateAvailable", data: ["bundle": next.toJSON()])
                             self.endBackGroundTaskWithNotif(
-                                msg: "Update install failed",
+                                msg: "Direct update reload failed, update will install next background",
                                 latestVersionName: latestVersionName,
-                                current: next,
+                                current: self.implementation.getCurrentBundle(),
+                                error: false,
                                 plannedDirectUpdate: plannedDirectUpdate
                             )
                         }
@@ -2968,6 +3256,9 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
     }
 
     private func installNext() {
+        if self.shouldBlockAutoUpdateForPreviewSession() {
+            return
+        }
         let delayUpdatePreferences = UserDefaults.standard.string(forKey: DelayUpdateUtils.DELAY_CONDITION_PREFERENCES) ?? "[]"
         let delayConditionList: [DelayCondition] = fromJsonArr(json: delayUpdatePreferences).map { obj -> DelayCondition in
             let kind: String = obj.value(forKey: "kind") as! String
@@ -3059,8 +3350,14 @@ public class CapacitorUpdaterPlugin: CAPPlugin, CAPBridgedPlugin {
                 return
             }
             DispatchQueue.global(qos: .utility).async {
+                if self.shouldBlockAutoUpdateForPreviewSession() {
+                    return
+                }
                 let res = self.implementation.getLatest(url: url, channel: nil)
                 let current = self.implementation.getCurrentBundle()
+                if self.shouldBlockAutoUpdateForPreviewSession() {
+                    return
+                }
 
                 if res.version != current.getVersionName() {
                     self.logger.info("New version found: \(res.version)")

package/ios/Sources/CapacitorUpdaterPlugin/CapgoUpdater.swift

@@ -2431,7 +2431,7 @@ import UIKit
         if let channels = responseValue.channels {
             listChannels.channels = channels.map { channel in
                 var channelDict: [String: Any] = [:]
-                channelDict["id"] = channel.id ?? ""
+                channelDict["id"] = channel.id
                 channelDict["name"] = channel.name ?? ""
                 channelDict["public"] = channel.public ?? false
                 channelDict["allow_self_set"] = channel.allow_self_set ?? false