@capgo/capacitor-updater 8.47.5 → 8.47.7

package/android/src/main/java/ee/forgr/capacitor_updater/CapacitorUpdaterPlugin.java

@@ -115,6 +115,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private static final int SPLASH_SCREEN_RETRY_DELAY_MS = 100;
     private static final int SPLASH_SCREEN_MAX_RETRIES = 20;
     private static final long PENDING_BUNDLE_APP_READY_MIN_TIMEOUT_MS = 30000L;
+    private static final long PREVIEW_TRANSITION_LOADER_TIMEOUT_MS = 60000L;
     static final int APPLICATION_EXIT_REASON_UNKNOWN = 0;
     static final int APPLICATION_EXIT_REASON_EXIT_SELF = 1;
     static final int APPLICATION_EXIT_REASON_SIGNALED = 2;
@@ -128,7 +129,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     static final int APPLICATION_EXIT_REASON_USER_REQUESTED = 10;
     static final int APPLICATION_EXIT_REASON_DEPENDENCY_DIED = 12;
 
-    private final String pluginVersion = "8.47.5";
+    private final String pluginVersion = "8.47.7";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -159,9 +160,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private volatile boolean onLaunchDirectUpdateUsed = false;
     Boolean shakeMenuEnabled = false;
     Boolean shakeChannelSelectorEnabled = false;
-    Boolean previewSessionEnabled = false;
+    volatile Boolean previewSessionEnabled = false;
     private Boolean previewSessionAlertPending = false;
-    private Boolean isLeavingPreviewForIncomingLink = false;
+    private volatile Boolean isLeavingPreviewForIncomingLink = false;
     private Boolean allowManualBundleError = false;
     private Boolean allowPreview = false;
     Boolean allowSetDefaultChannel = true;
@@ -170,6 +171,30 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return this.updateUrl;
     }
 
+    private boolean isPreviewSessionStateActive() {
+        return (
+            Boolean.TRUE.equals(this.previewSessionEnabled) ||
+            Boolean.TRUE.equals(this.isLeavingPreviewForIncomingLink) ||
+            (this.implementation != null && this.implementation.previewSession)
+        );
+    }
+
+    private boolean shouldBlockAutoUpdateForPreviewSession() {
+        if (!this.isPreviewSessionStateActive()) {
+            return false;
+        }
+
+        logger.info("Preview session is active. Skipping normal auto-update work.");
+        return true;
+    }
+
+    private void clearIncomingPreviewTransition() {
+        this.isLeavingPreviewForIncomingLink = false;
+        if (!Boolean.TRUE.equals(this.previewSessionEnabled) && this.implementation != null) {
+            this.implementation.previewSession = false;
+        }
+    }
+
     // Used for activity-based foreground/background detection on Android < 14
     private Boolean isPreviousMainActivity = true;
 
@@ -198,6 +223,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private final Handler mainHandler = new Handler(Looper.getMainLooper());
     private FrameLayout splashscreenLoaderOverlay;
     private Runnable splashscreenTimeoutRunnable;
+    private FrameLayout previewTransitionLoaderOverlay;
+    private Runnable previewTransitionLoaderTimeoutRunnable;
+    private boolean previewTransitionLoaderRequested = false;
     private WebViewListener webViewStatsListener;
 
     private static final class FireAndForgetPluginCall extends PluginCall {
@@ -513,7 +541,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 logger.info("Using preview appId " + previewAppId);
             }
             this.shakeMenuEnabled = true;
-            this.shakeChannelSelectorEnabled = false;
+            this.shakeChannelSelectorEnabled = this.prefs.contains(PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY)
+                ? this.prefs.getBoolean(PREVIEW_PREVIOUS_SHAKE_CHANNEL_SELECTOR_PREF_KEY, false)
+                : this.shakeChannelSelectorEnabled;
         }
         boolean resetWhenUpdate = this.getConfig().getBoolean("resetWhenUpdate", true);
 
@@ -658,6 +688,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
         if (this.autoSplashscreen) {
             this.hideSplashscreen();
         }
+        this.hidePreviewTransitionLoader("app-ready");
     }
 
     private void hideSplashscreen() {
@@ -769,6 +800,38 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return requestToken == this.splashscreenInvocationToken;
     }
 
+    private FrameLayout createLoaderOverlay(final Activity activity, final boolean blocksTouches, final int backgroundColor) {
+        final ProgressBar progressBar = new ProgressBar(activity);
+        progressBar.setIndeterminate(true);
+
+        final FrameLayout overlay = new FrameLayout(activity);
+        overlay.setLayoutParams(new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
+        overlay.setClickable(blocksTouches);
+        overlay.setFocusable(blocksTouches);
+        overlay.setBackgroundColor(backgroundColor);
+        overlay.setImportantForAccessibility(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS);
+
+        final FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
+            ViewGroup.LayoutParams.WRAP_CONTENT,
+            ViewGroup.LayoutParams.WRAP_CONTENT
+        );
+        params.gravity = Gravity.CENTER;
+        overlay.addView(progressBar, params);
+        return overlay;
+    }
+
+    private void attachLoaderOverlay(final Activity activity, final FrameLayout overlay) {
+        final ViewGroup decorView = (ViewGroup) activity.getWindow().getDecorView();
+        decorView.addView(overlay);
+    }
+
+    private void removeLoaderOverlay(final FrameLayout overlay) {
+        final ViewGroup parent = (ViewGroup) overlay.getParent();
+        if (parent != null) {
+            parent.removeView(overlay);
+        }
+    }
+
     private void addSplashscreenLoaderIfNeeded() {
         if (!Boolean.TRUE.equals(this.autoSplashscreenLoader)) {
             return;
@@ -785,26 +848,8 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 return;
             }
 
-            ProgressBar progressBar = new ProgressBar(activity);
-            progressBar.setIndeterminate(true);
-
-            FrameLayout overlay = new FrameLayout(activity);
-            overlay.setLayoutParams(new FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
-            overlay.setClickable(false);
-            overlay.setFocusable(false);
-            overlay.setBackgroundColor(Color.TRANSPARENT);
-            overlay.setImportantForAccessibility(View.IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS);
-
-            FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
-                ViewGroup.LayoutParams.WRAP_CONTENT,
-                ViewGroup.LayoutParams.WRAP_CONTENT
-            );
-            params.gravity = Gravity.CENTER;
-            overlay.addView(progressBar, params);
-
-            ViewGroup decorView = (ViewGroup) activity.getWindow().getDecorView();
-            decorView.addView(overlay);
-
+            FrameLayout overlay = createLoaderOverlay(activity, false, Color.TRANSPARENT);
+            attachLoaderOverlay(activity, overlay);
             this.splashscreenLoaderOverlay = overlay;
         };
 
@@ -818,10 +863,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private void removeSplashscreenLoader() {
         Runnable removeLoader = () -> {
             if (this.splashscreenLoaderOverlay != null) {
-                ViewGroup parent = (ViewGroup) this.splashscreenLoaderOverlay.getParent();
-                if (parent != null) {
-                    parent.removeView(this.splashscreenLoaderOverlay);
-                }
+                removeLoaderOverlay(this.splashscreenLoaderOverlay);
                 this.splashscreenLoaderOverlay = null;
             }
         };
@@ -833,6 +875,84 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
     }
 
+    private void showPreviewTransitionLoader(final String reason) {
+        this.previewTransitionLoaderRequested = true;
+        final Runnable showLoader = () -> {
+            if (!this.previewTransitionLoaderRequested) {
+                return;
+            }
+
+            if (this.previewTransitionLoaderOverlay != null) {
+                cancelPreviewTransitionLoaderTimeout();
+                schedulePreviewTransitionLoaderTimeout();
+                this.previewTransitionLoaderOverlay.bringToFront();
+                return;
+            }
+
+            final Activity activity = getActivity();
+            if (activity == null) {
+                logger.warn("Preview transition loader unavailable: activity missing for " + reason);
+                this.previewTransitionLoaderRequested = false;
+                return;
+            }
+
+            cancelPreviewTransitionLoaderTimeout();
+            schedulePreviewTransitionLoaderTimeout();
+
+            final FrameLayout overlay = createLoaderOverlay(activity, true, Color.argb(46, 0, 0, 0));
+            attachLoaderOverlay(activity, overlay);
+            this.previewTransitionLoaderOverlay = overlay;
+            logger.info("Preview transition loader shown: " + reason);
+        };
+
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            showLoader.run();
+        } else {
+            this.mainHandler.post(showLoader);
+        }
+    }
+
+    private void hidePreviewTransitionLoader(final String reason) {
+        if (
+            !this.previewTransitionLoaderRequested &&
+            this.previewTransitionLoaderOverlay == null &&
+            this.previewTransitionLoaderTimeoutRunnable == null
+        ) {
+            return;
+        }
+
+        final Runnable hideLoader = () -> {
+            this.previewTransitionLoaderRequested = false;
+            cancelPreviewTransitionLoaderTimeout();
+            if (this.previewTransitionLoaderOverlay == null) {
+                return;
+            }
+
+            removeLoaderOverlay(this.previewTransitionLoaderOverlay);
+            this.previewTransitionLoaderOverlay = null;
+            logger.info("Preview transition loader hidden: " + reason);
+        };
+
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            hideLoader.run();
+        } else {
+            this.mainHandler.post(hideLoader);
+        }
+    }
+
+    private void schedulePreviewTransitionLoaderTimeout() {
+        cancelPreviewTransitionLoaderTimeout();
+        this.previewTransitionLoaderTimeoutRunnable = () -> hidePreviewTransitionLoader("preview-transition-timeout");
+        this.mainHandler.postDelayed(this.previewTransitionLoaderTimeoutRunnable, PREVIEW_TRANSITION_LOADER_TIMEOUT_MS);
+    }
+
+    private void cancelPreviewTransitionLoaderTimeout() {
+        if (this.previewTransitionLoaderTimeoutRunnable != null) {
+            this.mainHandler.removeCallbacks(this.previewTransitionLoaderTimeoutRunnable);
+            this.previewTransitionLoaderTimeoutRunnable = null;
+        }
+    }
+
     private void scheduleSplashscreenTimeout() {
         if (this.autoSplashscreenTimeout == null || this.autoSplashscreenTimeout <= 0) {
             return;
@@ -1329,9 +1449,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 );
             }
         } else {
-            final boolean enabled = configuredMode != null
-                ? "true".equals(configuredMode)
-                : Boolean.TRUE.equals(this.getConfig().getBoolean("autoUpdate", true));
+            final boolean enabled =
+                configuredMode != null
+                    ? "true".equals(configuredMode)
+                    : Boolean.TRUE.equals(this.getConfig().getBoolean("autoUpdate", true));
             this.autoUpdateMode = enabled
                 ? autoUpdateModeForLegacyDirectUpdateMode(this.resolveLegacyDirectUpdateModeFromConfig())
                 : AUTO_UPDATE_MODE_OFF;
@@ -1506,6 +1627,12 @@ public class CapacitorUpdaterPlugin extends Plugin {
     void scheduleDirectUpdateFinish(final BundleInfo latest) {
         startNewThread(() -> {
             try {
+                if (this.shouldBlockAutoUpdateForPreviewSession()) {
+                    logger.info("Skipping direct update install while preview session state is active");
+                    this.implementation.directUpdate = false;
+                    this.clearBackgroundDownloadState();
+                    return;
+                }
                 Activity currentActivity = this.getActivity();
                 if (currentActivity != null) {
                     this.implementation.activity = currentActivity;
@@ -1520,14 +1647,52 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     private void directUpdateFinish(final BundleInfo latest) {
+        if (this.shouldBlockAutoUpdateForPreviewSession()) {
+            logger.info("Skipping direct update finish while preview session state is active");
+            this.implementation.directUpdate = false;
+            this.clearBackgroundDownloadState();
+            return;
+        }
         if ("onLaunch".equals(this.directUpdateMode)) {
             this.onLaunchDirectUpdateUsed = true;
             this.implementation.directUpdate = false;
         }
-        if (CapacitorUpdaterPlugin.this.implementation.set(latest) && CapacitorUpdaterPlugin.this._reload()) {
+        if (this.applyDownloadedBundleForDirectUpdate(latest)) {
+            this.implementation.setNextBundle(null);
             this.notifyBundleSet(latest);
             sendReadyToJs(latest, "update installed", true);
+        } else {
+            this.implementation.setNextBundle(latest.getId());
+            final JSObject ret = new JSObject();
+            ret.put("bundle", InternalUtils.mapToJSObject(latest.toJSONMap()));
+            this.notifyListeners("updateAvailable", ret);
+            sendReadyToJs(
+                this.implementation.getCurrentBundle(),
+                "Direct update reload failed, update will install next background",
+                false
+            );
+        }
+    }
+
+    private boolean applyDownloadedBundleForDirectUpdate(final BundleInfo latest) {
+        final CapgoUpdater.ResetState previousState = this.implementation.captureResetState();
+        final String previousBundleName = this.implementation.getCurrentBundle().getVersionName();
+
+        if (!this.implementation.stagePendingReload(latest)) {
+            this.implementation.restoreResetState(previousState);
+            logger.error("Direct update failed to stage downloaded bundle: " + latest.toString());
+            return false;
         }
+
+        if (this._reload()) {
+            this.implementation.finalizePendingReload(latest, previousBundleName);
+            return true;
+        }
+
+        this.implementation.restoreResetState(previousState);
+        this.restoreLiveBundleStateAfterFailedReload();
+        logger.error("Direct update reload failed after staging bundle: " + latest.toString());
+        return false;
     }
 
     private void cleanupObsoleteVersions() {
@@ -2135,6 +2300,15 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return this.semaphoreWait(phase, waitTimeMs);
     }
 
+    protected boolean reloadWithoutWaitingForAppReady() {
+        this.applyCurrentBundleToBridge();
+
+        final long waitTimeMs = this.resolveAppReadyCheckTimeoutMs();
+        this.checkAppReady(waitTimeMs);
+        this.notifyListeners("appReloaded", new JSObject());
+        return true;
+    }
+
     @PluginMethod
     public void reload(final PluginCall call) {
         startNewThread(() -> {
@@ -2142,7 +2316,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 final BundleInfo current = this.implementation.getCurrentBundle();
                 final BundleInfo next = this.implementation.getNextBundle();
 
-                if (next != null && !next.isErrorStatus() && !next.getId().equals(current.getId())) {
+                if (!this.isPreviewSessionStateActive() && next != null && !next.isErrorStatus() && !next.getId().equals(current.getId())) {
                     final CapgoUpdater.ResetState previousState = this.implementation.captureResetState();
                     final String previousBundleName = this.implementation.getCurrentBundle().getVersionName();
                     logger.info("Applying pending bundle before reload: " + next.getVersionName());
@@ -2222,6 +2396,12 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 if (!this.implementation.set(id)) {
                     logger.info("No such bundle " + id);
                     call.reject("Update failed, id " + id + " does not exist.");
+                } else if (Boolean.TRUE.equals(this.previewSessionEnabled)) {
+                    logger.info("Preview session set active bundle " + id + " without waiting for preview app readiness");
+                    this.reloadWithoutWaitingForAppReady();
+                    this.notifyBundleSet(this.implementation.getBundleInfo(id));
+                    this.showPreviewSessionNoticeIfNeeded();
+                    call.resolve();
                 } else if (!this._reload()) {
                     logger.error("Reload failed after setting bundle " + id);
                     call.reject("Reload failed after setting bundle " + id);
@@ -2241,6 +2421,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     @PluginMethod
     public void startPreviewSession(final PluginCall call) {
         if (!Boolean.TRUE.equals(this.allowPreview)) {
+            this.hidePreviewTransitionLoader("preview-session-not-allowed");
             logger.error("startPreviewSession not allowed set allowPreview in your config to true to enable it");
             call.reject("startPreviewSession not allowed");
             return;
@@ -2249,6 +2430,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
         final String rawPayloadUrl = call.getString("payloadUrl");
         final String previewPayloadUrl = this.normalizePreviewPayloadUrl(rawPayloadUrl);
         if (this.hasPreviewPayloadUrl(rawPayloadUrl) && previewPayloadUrl == null) {
+            this.hidePreviewTransitionLoader("preview-session-invalid-payload");
             logger.error("startPreviewSession called with invalid payloadUrl");
             call.reject("Invalid preview payloadUrl");
             return;
@@ -2258,6 +2440,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 if (!Boolean.TRUE.equals(this.previewSessionEnabled)) {
                     final BundleInfo current = this.implementation.getCurrentBundle();
                     if (!this.implementation.setPreviewFallbackBundle(current.getId())) {
+                        this.hidePreviewTransitionLoader("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;
@@ -2302,17 +2485,18 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     this.editor.remove(PREVIEW_PAYLOAD_URL_PREF_KEY);
                 }
 
+                this.hidePreviewTransitionLoader("preview-session-started");
                 this.previewSessionEnabled = true;
                 this.previewSessionAlertPending = true;
                 this.implementation.previewSession = true;
                 this.shakeMenuEnabled = true;
-                this.shakeChannelSelectorEnabled = false;
                 this.editor.putBoolean(PREVIEW_SESSION_PREF_KEY, true);
                 this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, true);
                 this.editor.apply();
                 this.ensureShakeMenuStarted();
                 call.resolve();
             } catch (final Exception e) {
+                this.hidePreviewTransitionLoader("preview-session-failed");
                 logger.error("Could not start preview session " + e.getMessage());
                 call.reject("Could not start preview session", e);
             }
@@ -2322,8 +2506,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
     public boolean leavePreviewSessionFromShakeMenu() {
         final BundleInfo previewBundle = this.implementation.getCurrentBundle();
 
+        this.showPreviewTransitionLoader("leave-preview-session");
         final boolean didReset = this.resetToPreviewFallbackBundle();
         if (!didReset) {
+            this.hidePreviewTransitionLoader("leave-preview-session-failed");
             return false;
         }
 
@@ -2334,6 +2520,47 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return true;
     }
 
+    private boolean leavePreviewSessionForIncomingPreviewLink() {
+        this.showPreviewTransitionLoader("incoming-preview-deeplink");
+        final BundleInfo previewBundle = this.implementation.getCurrentBundle();
+        final BundleInfo previewFallbackBundle = this.implementation.getPreviewFallbackBundle();
+        boolean didReload = false;
+
+        try {
+            if (previewFallbackBundle == null || previewFallbackBundle.isErrorStatus()) {
+                logger.error("No preview fallback bundle available");
+                return false;
+            }
+            if (!this.implementation.canSet(previewFallbackBundle)) {
+                logger.error("Preview fallback bundle is not installable");
+                return false;
+            }
+
+            final CapgoUpdater.ResetState previousState = this.implementation.captureResetState();
+            if (!this.implementation.stagePreviewFallbackReload(previewFallbackBundle)) {
+                logger.error("Could not stage preview fallback bundle");
+                return false;
+            }
+
+            if (!this._reload()) {
+                this.implementation.restoreResetState(previousState);
+                this.restoreLiveBundleStateAfterFailedReload();
+                return false;
+            }
+            didReload = true;
+
+            this.endPreviewSession(true);
+            final BundleInfo restoredNextBundle = this.implementation.getNextBundle();
+            this.deletePreviewBundleIfUnused(previewBundle, previewFallbackBundle, restoredNextBundle);
+            return true;
+        } finally {
+            this.clearIncomingPreviewTransition();
+            if (!didReload) {
+                this.hidePreviewTransitionLoader("incoming-preview-deeplink-failed");
+            }
+        }
+    }
+
     private void leavePreviewSessionForLaunchIntentIfNeeded() {
         final Intent intent = getActivity() == null ? null : getActivity().getIntent();
         if (
@@ -2348,14 +2575,20 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
 
         this.isLeavingPreviewForIncomingLink = true;
+        this.showPreviewTransitionLoader("preview-launch-deeplink");
         logger.info("Preview deeplink launch detected while preview session is active; restoring fallback before initial load");
         if (!this.leavePreviewSessionWithoutReload()) {
             logger.error("Could not leave preview session before initial preview deeplink routing");
             this.isLeavingPreviewForIncomingLink = false;
+            this.hidePreviewTransitionLoader("preview-launch-deeplink-failed");
         }
     }
 
     private boolean leavePreviewSessionWithoutReload() {
+        return this.leavePreviewSessionWithoutReload(false);
+    }
+
+    private boolean leavePreviewSessionWithoutReload(final boolean keepPreviewGuard) {
         final BundleInfo previewBundle = this.implementation.getCurrentBundle();
         final BundleInfo previewFallbackBundle = this.implementation.getPreviewFallbackBundle();
         if (previewFallbackBundle == null || previewFallbackBundle.isErrorStatus()) {
@@ -2371,7 +2604,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
             return false;
         }
 
-        this.endPreviewSession();
+        this.endPreviewSession(keepPreviewGuard);
         final BundleInfo restoredNextBundle = this.implementation.getNextBundle();
         this.deletePreviewBundleIfUnused(previewBundle, previewFallbackBundle, restoredNextBundle);
         return true;
@@ -2396,12 +2629,19 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     public boolean reloadPreviewSessionFromShakeMenu() {
+        this.showPreviewTransitionLoader("reload-preview-session");
+        final boolean didReload;
         final String payloadUrl = this.storedPreviewPayloadUrl();
         if (payloadUrl != null) {
-            return this.refreshPreviewSessionFromPayloadUrl(payloadUrl);
+            didReload = this.refreshPreviewSessionFromPayloadUrl(payloadUrl);
+        } else {
+            didReload = this.reloadWithoutWaitingForAppReady();
         }
 
-        return this._reload();
+        if (!didReload) {
+            this.hidePreviewTransitionLoader("reload-preview-session-failed");
+        }
+        return didReload;
     }
 
     public boolean hasActivePreviewSession() {
@@ -2433,6 +2673,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     private void endPreviewSession() {
+        this.endPreviewSession(false);
+    }
+
+    private void endPreviewSession(final boolean keepPreviewGuard) {
         final boolean previousShakeMenuEnabled = this.prefs.getBoolean(
             PREVIEW_PREVIOUS_SHAKE_MENU_PREF_KEY,
             this.getConfig().getBoolean("shakeMenu", false)
@@ -2447,10 +2691,14 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
         this.previewSessionEnabled = false;
         this.previewSessionAlertPending = false;
-        this.isLeavingPreviewForIncomingLink = false;
-        this.implementation.previewSession = false;
+        if (keepPreviewGuard) {
+            this.implementation.previewSession = true;
+        } else {
+            this.clearIncomingPreviewTransition();
+        }
         this.shakeMenuEnabled = previousShakeMenuEnabled;
         this.shakeChannelSelectorEnabled = previousShakeChannelSelectorEnabled;
+        this.syncShakeMenuLifecycle();
         this.implementation.setPreviewFallbackBundle(null);
         this.clearPreviewSessionPreferences();
         logger.info("Preview session ended");
@@ -2459,9 +2707,8 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private void clearPreviewSessionBecauseDisabled() {
         logger.info("Preview session disabled by config; restoring preview fallback");
         final BundleInfo fallback = this.implementation.getPreviewFallbackBundle();
-        final BundleInfo bundleToRestore = fallback == null || fallback.isErrorStatus()
-            ? this.implementation.getBundleInfo(BundleInfo.ID_BUILTIN)
-            : fallback;
+        final BundleInfo bundleToRestore =
+            fallback == null || fallback.isErrorStatus() ? this.implementation.getBundleInfo(BundleInfo.ID_BUILTIN) : fallback;
 
         if (this.implementation.canSet(bundleToRestore)) {
             this.implementation.stagePreviewFallbackReload(bundleToRestore);
@@ -2476,8 +2723,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.previewSessionAlertPending = false;
         this.isLeavingPreviewForIncomingLink = false;
         this.implementation.previewSession = false;
+        this.hidePreviewTransitionLoader("preview-session-disabled");
         this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
         this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
+        this.syncShakeMenuLifecycle();
         this.clearPreviewSessionPreferences();
     }
 
@@ -2670,7 +2919,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
             if (version.equals(this.implementation.getCurrentBundle().getVersionName())) {
                 logger.info("Preview payload unchanged, reloading current bundle");
-                return this._reload();
+                return this.reloadWithoutWaitingForAppReady();
             }
 
             final BundleInfo next = this.downloadPreviewPayloadBundle(payload);
@@ -2682,7 +2931,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
             }
 
             this.notifyBundleSet(next);
-            return this._reload();
+            return this.reloadWithoutWaitingForAppReady();
         } catch (final Exception err) {
             logger.error("Could not refresh preview session: " + err.getMessage());
             return false;
@@ -2700,6 +2949,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.implementation.previewSession = false;
         this.shakeMenuEnabled = this.getConfig().getBoolean("shakeMenu", false);
         this.shakeChannelSelectorEnabled = this.getConfig().getBoolean("allowShakeChannelSelector", false);
+        this.syncShakeMenuLifecycle();
         this.restorePreviewPreviousAppId();
         this.restorePreviewPreviousDefaultChannel();
         this.implementation.setPreviewFallbackBundle(null);
@@ -2730,6 +2980,24 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
     }
 
+    private void syncShakeMenuLifecycle() {
+        if (this.shouldListenForShake()) {
+            this.ensureShakeMenuStarted();
+        } else if (shakeMenu != null) {
+            try {
+                shakeMenu.stop();
+                shakeMenu = null;
+                logger.info("Shake menu stopped");
+            } catch (Exception e) {
+                logger.error("Failed to stop shake menu: " + e.getMessage());
+            }
+        }
+    }
+
+    private boolean shouldListenForShake() {
+        return Boolean.TRUE.equals(this.shakeMenuEnabled) || Boolean.TRUE.equals(this.shakeChannelSelectorEnabled);
+    }
+
     private void showPreviewSessionNoticeIfNeeded() {
         if (!Boolean.TRUE.equals(this.previewSessionEnabled) || !Boolean.TRUE.equals(this.previewSessionAlertPending)) {
             return;
@@ -2738,33 +3006,30 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, false);
         this.editor.apply();
 
-        new Handler(Looper.getMainLooper()).postDelayed(
-            () -> {
-                try {
-                    if (!Boolean.TRUE.equals(this.previewSessionEnabled)) {
-                        return;
-                    }
-                    if (getActivity() == null || getActivity().isFinishing()) {
-                        this.previewSessionAlertPending = true;
-                        this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, true);
-                        this.editor.apply();
-                        return;
-                    }
-
-                    new AlertDialog.Builder(getActivity())
-                        .setTitle("Preview started")
-                        .setMessage("Shake your device anytime to reload or leave the test app.")
-                        .setPositiveButton("Got it", (dialog, which) -> dialog.dismiss())
-                        .show();
-                } catch (final Exception e) {
+        new Handler(Looper.getMainLooper()).postDelayed(() -> {
+            try {
+                if (!Boolean.TRUE.equals(this.previewSessionEnabled)) {
+                    return;
+                }
+                if (getActivity() == null || getActivity().isFinishing()) {
                     this.previewSessionAlertPending = true;
                     this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, true);
                     this.editor.apply();
-                    logger.warn("Could not show preview session notice: " + e.getMessage());
+                    return;
                 }
-            },
-            600
-        );
+
+                new AlertDialog.Builder(getActivity())
+                    .setTitle("Preview started")
+                    .setMessage("Shake your device anytime to reload or leave the test app.")
+                    .setPositiveButton("Got it", (dialog, which) -> dialog.dismiss())
+                    .show();
+            } catch (final Exception e) {
+                this.previewSessionAlertPending = true;
+                this.editor.putBoolean(PREVIEW_SESSION_ALERT_PENDING_PREF_KEY, true);
+                this.editor.apply();
+                logger.warn("Could not show preview session notice: " + e.getMessage());
+            }
+        }, 600);
     }
 
     @PluginMethod
@@ -2970,6 +3235,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
             logger.error("Error no url or wrong format");
             return "unavailable";
         }
+        if (this.shouldBlockAutoUpdateForPreviewSession()) {
+            return "preview_session";
+        }
         if (this.isDownloadStuckOrTimedOut()) {
             logger.info("Download already in progress, skipping duplicate download request");
             return "already_running";
@@ -3138,7 +3406,13 @@ public class CapacitorUpdaterPlugin extends Plugin {
                 @Override
                 public void run() {
                     try {
+                        if (CapacitorUpdaterPlugin.this.shouldBlockAutoUpdateForPreviewSession()) {
+                            return;
+                        }
                         CapacitorUpdaterPlugin.this.implementation.getLatest(CapacitorUpdaterPlugin.this.updateUrl, null, (res) -> {
+                            if (CapacitorUpdaterPlugin.this.shouldBlockAutoUpdateForPreviewSession()) {
+                                return;
+                            }
                             JSObject jsRes = InternalUtils.mapToJSObject(res);
                             if (jsRes.has("error") || jsRes.has("kind")) {
                                 final BundleInfo current = CapacitorUpdaterPlugin.this.implementation.getCurrentBundle();
@@ -3201,6 +3475,8 @@ public class CapacitorUpdaterPlugin extends Plugin {
             logger.info("semaphoreReady countDown");
             this.semaphoreDown();
             logger.info("semaphoreReady countDown done");
+            this.clearIncomingPreviewTransition();
+            this.hidePreviewTransitionLoader("notify-app-ready");
             final JSObject ret = new JSObject();
             ret.put("bundle", InternalUtils.mapToJSObject(bundle.toJSONMap()));
             call.resolve(ret);
@@ -3248,6 +3524,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     private Boolean _isAutoUpdateEnabled() {
+        if (this.isPreviewSessionStateActive()) {
+            return false;
+        }
         final CapConfig config = CapConfig.loadDefault(this.getActivity());
         String serverUrl = config.getServerUrl();
         if (serverUrl != null && !serverUrl.isEmpty()) {
@@ -3446,6 +3725,11 @@ public class CapacitorUpdaterPlugin extends Plugin {
         logger.info("endBackGroundTaskWithNotif " + msg);
     }
 
+    private void clearBackgroundDownloadState() {
+        this.backgroundDownloadTask = null;
+        this.downloadStartTimeMs = 0;
+    }
+
     private boolean isDownloadStuckOrTimedOut() {
         if (this.backgroundDownloadTask == null || !this.backgroundDownloadTask.isAlive()) {
             return false;
@@ -3472,6 +3756,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     private Thread backgroundDownload() {
+        if (this.shouldBlockAutoUpdateForPreviewSession()) {
+            return null;
+        }
         final boolean plannedDirectUpdate = this.shouldUseDirectUpdate();
         final boolean initialDirectUpdateAllowed = this.isDirectUpdateCurrentlyAllowed(plannedDirectUpdate);
         final String messageUpdate = initialDirectUpdateAllowed
@@ -3482,9 +3769,17 @@ public class CapacitorUpdaterPlugin extends Plugin {
         Thread newTask = startNewThread(() -> {
             // Wait for cleanup to complete before starting download
             waitForCleanupIfNeeded();
+            if (CapacitorUpdaterPlugin.this.shouldBlockAutoUpdateForPreviewSession()) {
+                CapacitorUpdaterPlugin.this.clearBackgroundDownloadState();
+                return;
+            }
             logger.info("Check for update via: " + CapacitorUpdaterPlugin.this.updateUrl);
             try {
                 CapacitorUpdaterPlugin.this.implementation.getLatest(CapacitorUpdaterPlugin.this.updateUrl, null, (res) -> {
+                    if (CapacitorUpdaterPlugin.this.shouldBlockAutoUpdateForPreviewSession()) {
+                        CapacitorUpdaterPlugin.this.clearBackgroundDownloadState();
+                        return;
+                    }
                     JSObject jsRes = InternalUtils.mapToJSObject(res);
                     final BundleInfo current = CapacitorUpdaterPlugin.this.implementation.getCurrentBundle();
 
@@ -3709,6 +4004,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
                                 : initialDirectUpdateAllowed;
                             startNewThread(() -> {
                                 try {
+                                    if (CapacitorUpdaterPlugin.this.shouldBlockAutoUpdateForPreviewSession()) {
+                                        CapacitorUpdaterPlugin.this.clearBackgroundDownloadState();
+                                        return;
+                                    }
                                     logger.info(
                                         "New bundle: " +
                                             latestVersionName +
@@ -3795,6 +4094,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
     private void installNext() {
         try {
+            if (this.shouldBlockAutoUpdateForPreviewSession()) {
+                return;
+            }
             String delayUpdatePreferences = prefs.getString(DelayUpdateUtils.DELAY_CONDITION_PREFERENCES, "[]");
             ArrayList<DelayCondition> delayConditionList = delayUpdateUtils.parseDelayConditions(delayUpdatePreferences);
             if (!delayConditionList.isEmpty()) {
@@ -3830,6 +4132,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
             logger.info("Built-in bundle is active. We skip the check for notifyAppReady.");
             return;
         }
+        if (this.isPreviewSessionStateActive()) {
+            logger.info("Preview session is active. We skip the check for notifyAppReady.");
+            return;
+        }
         logger.debug("Current bundle is: " + current);
 
         if (BundleStatus.SUCCESS != current.getStatus()) {
@@ -4019,15 +4325,17 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
 
         this.isLeavingPreviewForIncomingLink = true;
+        this.showPreviewTransitionLoader("incoming-preview-deeplink");
         if (getActivity() != null) {
             getActivity().setIntent(intent);
         }
         logger.info("Preview deeplink received while preview session is active; restoring fallback before routing");
         startNewThread(() -> {
-            final boolean didLeave = this.leavePreviewSessionFromShakeMenu();
+            final boolean didLeave = this.leavePreviewSessionForIncomingPreviewLink();
             if (!didLeave) {
                 logger.error("Could not leave preview session before routing incoming preview deeplink");
                 this.isLeavingPreviewForIncomingLink = false;
+                this.hidePreviewTransitionLoader("incoming-preview-deeplink-failed");
             }
         });
     }
@@ -4048,13 +4356,8 @@ public class CapacitorUpdaterPlugin extends Plugin {
             }
 
             // Initialize shake menu if enabled and activity is BridgeActivity
-            if (shakeMenuEnabled && getActivity() instanceof com.getcapacitor.BridgeActivity && shakeMenu == null) {
-                try {
-                    shakeMenu = new ShakeMenu(this, (com.getcapacitor.BridgeActivity) getActivity(), logger);
-                    logger.info("Shake menu initialized");
-                } catch (Exception e) {
-                    logger.error("Failed to initialize shake menu: " + e.getMessage());
-                }
+            if (this.shouldListenForShake()) {
+                this.ensureShakeMenuStarted();
             }
         } catch (Exception e) {
             logger.error("Failed to run handleOnStart: " + e.getMessage());
@@ -4113,23 +4416,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.shakeMenuEnabled = enabled;
         logger.info("Shake menu " + (enabled ? "enabled" : "disabled"));
 
-        // Manage shake menu instance based on enabled state
-        if (enabled && getActivity() instanceof com.getcapacitor.BridgeActivity && shakeMenu == null) {
-            try {
-                shakeMenu = new ShakeMenu(this, (com.getcapacitor.BridgeActivity) getActivity(), logger);
-                logger.info("Shake menu initialized");
-            } catch (Exception e) {
-                logger.error("Failed to initialize shake menu: " + e.getMessage());
-            }
-        } else if (!enabled && shakeMenu != null) {
-            try {
-                shakeMenu.stop();
-                shakeMenu = null;
-                logger.info("Shake menu stopped");
-            } catch (Exception e) {
-                logger.error("Failed to stop shake menu: " + e.getMessage());
-            }
-        }
+        this.syncShakeMenuLifecycle();
 
         call.resolve();
     }
@@ -4157,6 +4444,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
 
         this.shakeChannelSelectorEnabled = enabled;
         logger.info("Shake channel selector " + (enabled ? "enabled" : "disabled"));
+        this.syncShakeMenuLifecycle();
         call.resolve();
     }