@capgo/capacitor-updater 8.50.2 → 8.51.0

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

@@ -13,7 +13,14 @@ import android.content.pm.PackageManager;
 import android.os.Build;
 import androidx.annotation.NonNull;
 import androidx.lifecycle.LifecycleOwner;
+import androidx.work.Constraints;
 import androidx.work.Data;
+import androidx.work.ExistingPeriodicWorkPolicy;
+import androidx.work.ExistingWorkPolicy;
+import androidx.work.ListenableWorker;
+import androidx.work.NetworkType;
+import androidx.work.OneTimeWorkRequest;
+import androidx.work.PeriodicWorkRequest;
 import androidx.work.WorkInfo;
 import androidx.work.WorkManager;
 import com.google.common.util.concurrent.Futures;
@@ -69,6 +76,7 @@ public class CapgoUpdater {
     private static final String TEMP_UNZIP_PREFIX = "capgo_unzip_";
     private static final String CAPACITOR_CONFIG_ASSET = "capacitor.config.json";
     private static final String BACKGROUND_RUNNER_CONFIG_KEY = "BackgroundRunner";
+    private static final String BACKGROUND_RUNNER_WORKER_CLASS = "io.ionic.backgroundrunner.plugin.RunnerWorker";
 
     public static final String TAG = "Capacitor-updater";
     public SharedPreferences.Editor editor;
@@ -656,6 +664,9 @@ public class CapgoUpdater {
                                 if ("low_mem_fail".equals(error)) {
                                     sendStats("low_mem_fail", failedVersion);
                                 }
+                                if ("insufficient_disk_space".equals(error)) {
+                                    sendStats("insufficient_disk_space", failedVersion);
+                                }
                                 ret.put("error", error != null ? error : "download_fail");
                                 sendStats("download_fail", failedVersion);
                                 notifyListeners("downloadFailed", ret);
@@ -983,7 +994,7 @@ public class CapgoUpdater {
     }
 
     private void setCurrentBundle(final File bundle) {
-        this.cancelBackgroundRunnerWorkBeforeBundleSwitch();
+        this.resetBackgroundRunnerWorkForBundleSwitch(bundle);
         this.editor.putString(this.CAP_SERVER_PATH, bundle.getPath());
         logger.info("Current bundle set to: " + bundle);
         this.editor.commit();
@@ -993,7 +1004,33 @@ public class CapgoUpdater {
         return bundlePath != null && !bundlePath.trim().isEmpty() && !isBuiltin && !hasStoredBundleInfo;
     }
 
-    static String getBackgroundRunnerLabelFromConfig(final String configJson) {
+    static final class BackgroundRunnerWorkConfig {
+
+        final String label;
+        final String src;
+        final String event;
+        final boolean autoStart;
+        final boolean repeat;
+        final int interval;
+
+        BackgroundRunnerWorkConfig(
+            final String label,
+            final String src,
+            final String event,
+            final boolean autoStart,
+            final boolean repeat,
+            final int interval
+        ) {
+            this.label = label;
+            this.src = src;
+            this.event = event;
+            this.autoStart = autoStart;
+            this.repeat = repeat;
+            this.interval = interval;
+        }
+    }
+
+    static BackgroundRunnerWorkConfig getBackgroundRunnerWorkConfigFromConfig(final String configJson) {
         if (configJson == null || configJson.trim().isEmpty()) {
             return null;
         }
@@ -1011,12 +1048,30 @@ public class CapgoUpdater {
             }
 
             final String label = backgroundRunner.optString("label", "").trim();
-            return label.isEmpty() ? null : label;
+            if (label.isEmpty()) {
+                return null;
+            }
+
+            final String src = backgroundRunner.optString("src", "").trim();
+            final String event = backgroundRunner.optString("event", "").trim();
+            return new BackgroundRunnerWorkConfig(
+                label,
+                src,
+                event,
+                backgroundRunner.optBoolean("autoStart", false),
+                backgroundRunner.optBoolean("repeat", false),
+                backgroundRunner.optInt("interval", 0)
+            );
         } catch (JSONException ignored) {
             return null;
         }
     }
 
+    static String getBackgroundRunnerLabelFromConfig(final String configJson) {
+        final BackgroundRunnerWorkConfig config = getBackgroundRunnerWorkConfigFromConfig(configJson);
+        return config == null ? null : config.label;
+    }
+
     private String readAssetAsString(final String assetPath) throws IOException {
         final StringBuilder buffer = new StringBuilder();
         try (
@@ -1032,32 +1087,128 @@ public class CapgoUpdater {
         return buffer.toString();
     }
 
-    private void cancelBackgroundRunnerWorkBeforeBundleSwitch() {
+    private void copyFileAtomically(final File source, final File dest) throws IOException {
+        final File parent = dest.getParentFile();
+        if (parent != null && !parent.exists() && !parent.mkdirs()) {
+            throw new IOException("Failed to create parent directory: " + parent.getAbsolutePath());
+        }
+
+        final File tempFile = new File(parent, dest.getName() + ".capgo_tmp");
+        try (final FileInputStream input = new FileInputStream(source); final FileOutputStream output = new FileOutputStream(tempFile)) {
+            final byte[] buffer = new byte[1024 * 1024];
+            int length;
+            while ((length = input.read(buffer)) != -1) {
+                output.write(buffer, 0, length);
+            }
+        }
+
+        if (!tempFile.renameTo(dest)) {
+            if (!dest.delete() || !tempFile.renameTo(dest)) {
+                tempFile.delete();
+                throw new IOException("Failed to replace file: " + dest.getAbsolutePath());
+            }
+        }
+    }
+
+    private void syncBackgroundRunnerScriptFromBundle(final File bundle, final BackgroundRunnerWorkConfig config) {
+        if (this.activity == null || bundle == null || config == null || config.src == null || config.src.isEmpty()) {
+            return;
+        }
+
+        if (bundle.getPath().endsWith("/public") || "public".equals(bundle.getName())) {
+            return;
+        }
+
+        try {
+            final File source = resolvePathInsideDirectory(bundle, config.src);
+            if (!source.isFile()) {
+                return;
+            }
+
+            final File publicDir = new File(this.activity.getFilesDir(), "public");
+            final File dest = resolvePathInsideDirectory(publicDir, config.src);
+            this.copyFileAtomically(source, dest);
+            logger.info("Synced Background Runner script into native public storage before bundle switch.");
+            logger.debug("Background Runner script path: " + dest.getAbsolutePath());
+        } catch (Exception e) {
+            logger.debug("Background Runner script sync skipped: " + e.getMessage());
+        }
+    }
+
+    private void resetBackgroundRunnerWorkForBundleSwitch(final File bundle) {
         if (this.activity == null) {
             return;
         }
 
-        final String label;
+        final BackgroundRunnerWorkConfig config;
         try {
-            label = getBackgroundRunnerLabelFromConfig(this.readAssetAsString(CAPACITOR_CONFIG_ASSET));
+            config = getBackgroundRunnerWorkConfigFromConfig(this.readAssetAsString(CAPACITOR_CONFIG_ASSET));
         } catch (IOException ignored) {
             return;
         }
 
-        if (label == null) {
+        if (config == null) {
             return;
         }
 
         try {
             final WorkManager workManager = WorkManager.getInstance(this.activity.getApplicationContext());
-            workManager.cancelUniqueWork(label);
-            workManager.cancelAllWorkByTag(label);
+            workManager.cancelUniqueWork(config.label);
+            workManager.cancelAllWorkByTag(config.label);
             logger.info("Cancelled Background Runner work before bundle switch.");
-            logger.debug("Background Runner label: " + label);
+            logger.debug("Background Runner label: " + config.label);
         } catch (Exception e) {
             logger.warn("Failed to cancel Background Runner work before bundle switch.");
             logger.debug("Background Runner cancellation error: " + e.getMessage());
         }
+
+        this.syncBackgroundRunnerScriptFromBundle(bundle, config);
+        this.rescheduleBackgroundRunnerWork(config);
+    }
+
+    private void rescheduleBackgroundRunnerWork(final BackgroundRunnerWorkConfig config) {
+        if (!config.autoStart || config.interval <= 0 || config.src.isEmpty()) {
+            return;
+        }
+
+        try {
+            @SuppressWarnings("unchecked")
+            final Class<? extends ListenableWorker> workerClass = (Class<? extends ListenableWorker>) Class.forName(
+                BACKGROUND_RUNNER_WORKER_CLASS
+            );
+            final Data data = new Data.Builder()
+                .putString("label", config.label)
+                .putString("src", config.src)
+                .putString("event", config.event)
+                .build();
+            final Constraints constraints = new Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build();
+            final WorkManager workManager = WorkManager.getInstance(this.activity.getApplicationContext());
+
+            if (!config.repeat) {
+                final OneTimeWorkRequest work = new OneTimeWorkRequest.Builder(workerClass)
+                    .setInitialDelay(config.interval, TimeUnit.MINUTES)
+                    .setInputData(data)
+                    .addTag(config.label)
+                    .setConstraints(constraints)
+                    .build();
+                workManager.enqueueUniqueWork(config.label, ExistingWorkPolicy.REPLACE, work);
+            } else {
+                final PeriodicWorkRequest work = new PeriodicWorkRequest.Builder(workerClass, config.interval, TimeUnit.MINUTES)
+                    .setInitialDelay(config.interval, TimeUnit.MINUTES)
+                    .setInputData(data)
+                    .addTag(config.label)
+                    .setConstraints(constraints)
+                    .build();
+                workManager.enqueueUniquePeriodicWork(config.label, ExistingPeriodicWorkPolicy.UPDATE, work);
+            }
+
+            logger.info("Rescheduled Background Runner work after bundle switch.");
+        } catch (ClassNotFoundException ignored) {
+            logger.debug("Background Runner plugin not installed, skipping reschedule.");
+        } catch (Exception e) {
+            logger.warn("Failed to reschedule Background Runner work after bundle switch.");
+            logger.debug("Background Runner reschedule error: " + e.getMessage());
+        }
     }
 
     private boolean hasStoredBundleInfo(final String id) {

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

@@ -174,7 +174,9 @@ public class DownloadService extends Worker {
     }
 
     static File resolveManifestBuiltinFile(final File builtinFolder, final String fileName) throws IOException {
-        return CapgoUpdater.resolvePathInsideDirectory(builtinFolder, fileName);
+        final boolean isBrotli = fileName.endsWith(".br");
+        final String resolvedName = isBrotli ? fileName.substring(0, fileName.length() - 3) : fileName;
+        return CapgoUpdater.resolvePathInsideDirectory(builtinFolder, resolvedName);
     }
 
     private String getInputString(String key, String fallback) {
@@ -642,14 +644,29 @@ public class DownloadService extends Worker {
     }
 
     private void copyFile(File source, File dest) throws IOException {
+        final File parent = dest.getParentFile();
+        if (parent != null && !parent.exists() && !parent.mkdirs()) {
+            throw new IOException("Failed to create parent directory: " + parent.getAbsolutePath());
+        }
+
+        final File tempFile = new File(parent, dest.getName() + ".capgo_tmp");
         try (
             FileInputStream inStream = new FileInputStream(source);
-            FileOutputStream outStream = new FileOutputStream(dest);
+            FileOutputStream outStream = new FileOutputStream(tempFile);
             FileChannel inChannel = inStream.getChannel();
             FileChannel outChannel = outStream.getChannel()
         ) {
             inChannel.transferTo(0, inChannel.size(), outChannel);
         }
+
+        try {
+            Files.move(tempFile.toPath(), dest.toPath(), StandardCopyOption.REPLACE_EXISTING);
+        } catch (IOException e) {
+            if (tempFile.exists()) {
+                tempFile.delete();
+            }
+            throw e;
+        }
     }
 
     private void downloadAndVerify(

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

@@ -13,6 +13,7 @@ import android.hardware.SensorManager;
 import android.text.Editable;
 import android.text.TextWatcher;
 import android.widget.ArrayAdapter;
+import android.widget.Button;
 import android.widget.EditText;
 import android.widget.LinearLayout;
 import android.widget.ListView;
@@ -117,65 +118,8 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
                     isShowing = false;
                     return;
                 }
-                if (Boolean.TRUE.equals(plugin.shakeChannelSelectorEnabled)) {
-                    showCombinedPreviewMenu();
-                    return;
-                }
-                String appName = activity.getPackageManager().getApplicationLabel(activity.getApplicationInfo()).toString();
-                String title = "Preview " + appName + " Menu";
-                String message = "Reload, switch, or leave the current preview.";
-                List<String> actions = new ArrayList<>();
-                actions.add("Reload preview");
-                if (plugin.previewMenuPreviews().length() > 0) {
-                    actions.add("Switch preview");
-                }
-                actions.add("Leave test app");
-                final boolean[] openingNestedSelector = { false };
-                final boolean[] previewActionRunning = { false };
 
-                AlertDialog.Builder builder = new AlertDialog.Builder(activity);
-                builder.setTitle(title);
-                builder.setMessage(message);
-                builder.setItems(actions.toArray(new String[0]), (dialogInterface, which) -> {
-                    AlertDialog dialog = (AlertDialog) dialogInterface;
-                    String action = actions.get(which);
-                    if ("Reload preview".equals(action)) {
-                        previewActionRunning[0] = true;
-                        logger.info("Reloading webview");
-                        runPreviewMenuAction(dialog, "Could not reload the test app.", "Error reloading test app: ", () ->
-                            plugin.reloadPreviewSessionFromShakeMenu()
-                        );
-                    } else if ("Switch preview".equals(action)) {
-                        openingNestedSelector[0] = true;
-                        dialog.dismiss();
-                        showPreviewSelector();
-                    } else {
-                        previewActionRunning[0] = true;
-                        runPreviewMenuAction(dialog, "Could not leave the test app.", "Error leaving test app: ", () ->
-                            plugin.leavePreviewSessionFromShakeMenu()
-                        );
-                    }
-                });
-
-                // Cancel button
-                builder.setNegativeButton(
-                    "Close menu",
-                    new DialogInterface.OnClickListener() {
-                        public void onClick(DialogInterface dialog, int id) {
-                            logger.info("Shake menu cancelled");
-                            dialog.dismiss();
-                            isShowing = false;
-                        }
-                    }
-                );
-
-                AlertDialog dialog = builder.create();
-                dialog.setOnDismissListener((dialogInterface) -> {
-                    if (!openingNestedSelector[0] && !previewActionRunning[0]) {
-                        isShowing = false;
-                    }
-                });
-                dialog.show();
+                showPreviewActionsMenu(Boolean.TRUE.equals(plugin.shakeChannelSelectorEnabled));
             } catch (Exception e) {
                 logger.error("Error showing shake menu: " + e.getMessage());
                 isShowing = false;
@@ -183,65 +127,95 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
         });
     }
 
-    private void showCombinedPreviewMenu() {
-        try {
-            String appName = activity.getPackageManager().getApplicationLabel(activity.getApplicationInfo()).toString();
-            String title = "Preview " + appName + " Menu";
-            String message = "Reload, switch, or leave the current preview.";
-            List<String> actions = new ArrayList<>();
-            actions.add("Reload preview");
-            if (plugin.previewMenuPreviews().length() > 0) {
-                actions.add("Switch preview");
-            }
-            actions.add("Leave test app");
-            actions.add("Switch channel");
-            final boolean[] openingNestedSelector = { false };
-            final boolean[] previewActionRunning = { false };
+    private void showPreviewActionsMenu(boolean includeChannelSelector) {
+        String appName = activity.getPackageManager().getApplicationLabel(activity.getApplicationInfo()).toString();
+        String title = "Preview " + appName + " Menu";
+        String message = "Reload, switch, or leave the current preview.";
+        final boolean[] openingNestedSelector = { false };
+        final boolean[] previewActionRunning = { false };
+        final AlertDialog[] dialogRef = { null };
+        List<Button> buttons = new ArrayList<>();
+
+        LinearLayout layout = new LinearLayout(activity);
+        layout.setOrientation(LinearLayout.VERTICAL);
+        int horizontalPadding = dpToPx(16);
+        int verticalPadding = dpToPx(8);
+        layout.setPadding(horizontalPadding, verticalPadding, horizontalPadding, verticalPadding);
+
+        addPreviewMenuButton(layout, buttons, "Reload preview", () -> {
+            AlertDialog dialog = dialogRef[0];
+            previewActionRunning[0] = true;
+            setPreviewMenuButtonsEnabled(buttons, false);
+            logger.info("Reloading webview");
+            runPreviewMenuAction(dialog, "Could not reload the test app.", "Error reloading test app: ", () ->
+                plugin.reloadPreviewSessionFromShakeMenu()
+            );
+        });
 
-            AlertDialog.Builder builder = new AlertDialog.Builder(activity);
-            builder.setTitle(title);
-            builder.setMessage(message);
-            builder.setItems(actions.toArray(new String[0]), (dialogInterface, which) -> {
-                AlertDialog dialog = (AlertDialog) dialogInterface;
-                String action = actions.get(which);
-                if ("Reload preview".equals(action)) {
-                    previewActionRunning[0] = true;
-                    logger.info("Reloading webview");
-                    runPreviewMenuAction(dialog, "Could not reload the test app.", "Error reloading test app: ", () ->
-                        plugin.reloadPreviewSessionFromShakeMenu()
-                    );
-                } else if ("Leave test app".equals(action)) {
-                    previewActionRunning[0] = true;
-                    runPreviewMenuAction(dialog, "Could not leave the test app.", "Error leaving test app: ", () ->
-                        plugin.leavePreviewSessionFromShakeMenu()
-                    );
-                } else if ("Switch preview".equals(action)) {
-                    openingNestedSelector[0] = true;
-                    dialog.dismiss();
-                    showPreviewSelector();
-                } else {
-                    openingNestedSelector[0] = true;
-                    dialog.dismiss();
-                    showChannelSelector();
-                }
-            });
-            builder.setNegativeButton("Close menu", (dialog, id) -> {
-                logger.info("Shake menu cancelled");
+        if (plugin.previewMenuPreviews().length() > 0) {
+            addPreviewMenuButton(layout, buttons, "Switch preview", () -> {
+                AlertDialog dialog = dialogRef[0];
+                openingNestedSelector[0] = true;
                 dialog.dismiss();
-                isShowing = false;
+                showPreviewSelector();
             });
+        }
 
-            AlertDialog dialog = builder.create();
-            dialog.setOnDismissListener((dialogInterface) -> {
-                if (!openingNestedSelector[0] && !previewActionRunning[0]) {
-                    isShowing = false;
-                }
+        if (includeChannelSelector) {
+            addPreviewMenuButton(layout, buttons, "Switch channel", () -> {
+                AlertDialog dialog = dialogRef[0];
+                openingNestedSelector[0] = true;
+                dialog.dismiss();
+                showChannelSelector();
             });
-            dialog.show();
-        } catch (Exception e) {
-            logger.error("Error showing combined shake menu: " + e.getMessage());
-            isShowing = false;
         }
+
+        addPreviewMenuButton(layout, buttons, "Leave test app", () -> {
+            AlertDialog dialog = dialogRef[0];
+            previewActionRunning[0] = true;
+            setPreviewMenuButtonsEnabled(buttons, false);
+            runPreviewMenuAction(dialog, "Could not leave the test app.", "Error leaving test app: ", () ->
+                plugin.leavePreviewSessionFromShakeMenu()
+            );
+        });
+
+        addPreviewMenuButton(layout, buttons, "Close menu", () -> {
+            AlertDialog dialog = dialogRef[0];
+            if (dialog != null) {
+                logger.info("Shake menu cancelled");
+                dialog.dismiss();
+                isShowing = false;
+            }
+        });
+
+        AlertDialog.Builder builder = new AlertDialog.Builder(activity);
+        builder.setTitle(title);
+        builder.setMessage(message);
+        builder.setView(layout);
+
+        AlertDialog dialog = builder.create();
+        dialogRef[0] = dialog;
+        dialog.setOnDismissListener((dialogInterface) -> {
+            if (!openingNestedSelector[0] && !previewActionRunning[0]) {
+                isShowing = false;
+            }
+        });
+        dialog.show();
+    }
+
+    private void addPreviewMenuButton(LinearLayout layout, List<Button> buttons, String title, Runnable action) {
+        Button button = new Button(activity);
+        button.setAllCaps(false);
+        button.setText(title);
+        LinearLayout.LayoutParams params = new LinearLayout.LayoutParams(
+            LinearLayout.LayoutParams.MATCH_PARENT,
+            LinearLayout.LayoutParams.WRAP_CONTENT
+        );
+        params.setMargins(0, 0, 0, dpToPx(8));
+        button.setLayoutParams(params);
+        button.setOnClickListener((view) -> action.run());
+        buttons.add(button);
+        layout.addView(button);
     }
 
     private void runPreviewMenuAction(AlertDialog dialog, String failureMessage, String errorPrefix, PreviewMenuAction action) {
@@ -262,10 +236,10 @@ public class ShakeMenu implements ShakeDetector.Listener, ThreeFingerPinchDetect
         }).start();
     }
 
-    private void setPreviewMenuButtonsEnabled(AlertDialog dialog, boolean enabled) {
-        dialog.getButton(AlertDialog.BUTTON_POSITIVE).setEnabled(enabled);
-        dialog.getButton(AlertDialog.BUTTON_NEUTRAL).setEnabled(enabled);
-        dialog.getButton(AlertDialog.BUTTON_NEGATIVE).setEnabled(enabled);
+    private void setPreviewMenuButtonsEnabled(List<Button> buttons, boolean enabled) {
+        for (Button button : buttons) {
+            button.setEnabled(enabled);
+        }
     }
 
     private void showPreviewSelector() {

package/dist/docs.json

@@ -156,7 +156,7 @@
             "text": "{Error} If the download fails or the bundle is invalid."
           }
         ],
-        "docs": "Download a new bundle from the provided URL for later installation.\n\nThe downloaded bundle is stored locally but not activated. To use it:\n- Call {@link next} to set it for installation on next app backgrounding/restart\n- Call {@link set} to activate it immediately (destroys current JavaScript context)\n\nThe URL should point to a zip file containing either:\n- Your app files directly in the zip root, or\n- A single folder containing all your app files\n\nThe bundle must include an `index.html` file at the root level.\n\nFor encrypted bundles, provide the `sessionKey` and `checksum` parameters.\nFor multi-file delta updates, provide the `manifest` array.\n\n**Android Background Runner note:** `@capacitor/background-runner` loads its\nconfigured runner script from native APK assets. Live updates cannot replace\nthat runner script. Keep it stable across OTA updates and ship a native app\nupdate when the runner code changes.",
+        "docs": "Download a new bundle from the provided URL for later installation.\n\nThe downloaded bundle is stored locally but not activated. To use it:\n- Call {@link next} to set it for installation on next app backgrounding/restart\n- Call {@link set} to activate it immediately (destroys current JavaScript context)\n\nThe URL should point to a zip file containing either:\n- Your app files directly in the zip root, or\n- A single folder containing all your app files\n\nThe bundle must include an `index.html` file at the root level.\n\nFor encrypted bundles, provide the `sessionKey` and `checksum` parameters.\nFor multi-file delta updates, provide the `manifest` array.\n\n**Android Background Runner note:** `@capacitor/background-runner` loads its\nconfigured runner script from native APK assets. Live updates cannot replace\nthat runner script. Keep it stable across OTA updates and ship a native app\nupdate when the runner code changes. When a bundle switch happens, Capacitor\nUpdater cancels and reschedules configured Background Runner WorkManager jobs\nand syncs the bundled runner script into native `public/` storage when present.",
         "complexTypes": [
           "BundleInfo",
           "DownloadOptions"
@@ -4623,7 +4623,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure how the plugin checks for, downloads, and applies live updates.\n\nThe plugin checks for updates when the app moves to the foreground and, if\n{@link periodCheckDelay} is set, on a repeating timer while the app stays open.\n\nBoolean values keep their existing behavior:\n- `true`: Same as `\"atBackground\"`.\n- `false`: Same as `\"off\"`.\n\nString values merge the previous Auto Update and Direct Update configuration:\n- `\"off\"`: Disable automatic update checks.\n- `\"atBackground\"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background.\n- `\"atInstall\"`: Apply immediately only after a fresh install or native app store update; otherwise use `\"atBackground\"` behavior.\n- `\"onLaunch\"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `\"atBackground\"` behavior.\n- `\"always\"`: Check on every foreground transition and apply immediately whenever an update is available.\n- `\"onlyDownload\"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically.\n\nOnly available for Android and iOS.",
+          "docs": "Configure how the plugin checks for, downloads, and applies live updates.\n\nThe plugin checks for updates when the app moves to the foreground. When\n{@link periodCheckDelay} is greater than 0, it also checks on a repeating timer\nwhile the app stays open.\n\nBoolean values keep their existing behavior:\n- `true`: Same as `\"atBackground\"`.\n- `false`: Same as `\"off\"`.\n\nString values merge the previous Auto Update and Direct Update configuration:\n- `\"off\"`: Disable automatic update checks.\n- `\"atBackground\"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background.\n- `\"atInstall\"`: Apply immediately only after a fresh install or native app store update; otherwise use `\"atBackground\"` behavior.\n- `\"onLaunch\"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `\"atBackground\"` behavior.\n- `\"always\"`: Check on every foreground transition and apply immediately whenever an update is available.\n- `\"onlyDownload\"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically.\n\nOnly available for Android and iOS.",
           "complexTypes": [],
           "type": "boolean | 'always' | 'off' | 'atBackground' | 'atInstall' | 'onLaunch' | 'onlyDownload' | undefined"
         },
@@ -4687,7 +4687,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.\nNative stats include update lifecycle events, app health signals such as crashes,\nAndroid ANRs, low-memory exits, iOS memory warnings, and WebView health signals\nsuch as JavaScript errors, unhandled promise rejections, resource load failures,\nWebView renderer exits, and unclean WebView restarts when available.",
+          "docs": "Configure the URL / endpoint to which update statistics are sent.\n\nOnly available for Android and iOS. Set to \"\" to disable stats reporting.\nNative stats include update lifecycle events, app health signals such as crashes,\nAndroid ANRs, low-memory exits, iOS memory warnings, and WebView health signals\nsuch as JavaScript errors, unhandled promise rejections, resource load failures,\nWebView renderer exits, unclean WebView restarts, app launch readiness timing,\nand WebView load milestones when available.",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -4727,7 +4727,7 @@
           "name": "directUpdate",
           "tags": [
             {
-              "text": "Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.\nWorks well for apps less than 10MB and with uploads done using --delta flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates (use default behavior: download on foreground check, apply when backgrounded)\n- atInstall: Direct update only after app install or native app store update, otherwise act as directUpdate = false\n- onLaunch: Direct update only when the app is brought to the foreground from a killed state, otherwise act as directUpdate = false\n- always: Direct update on every foreground check whenever an update is available, never act as directUpdate = false\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nActivate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.\nOnly available for Android and iOS.",
+              "text": "Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.\nWorks well for apps less than 10MB and with uploads done using --delta flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates\n- atInstall: Same as `\"atInstall\"` for {@link autoUpdate}\n- onLaunch: Same as `\"onLaunch\"` for {@link autoUpdate}\n- always: Same as `\"always\"` for {@link autoUpdate}\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nActivate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.\nOnly available for Android and iOS.",
               "name": "deprecated"
             },
             {
@@ -4807,7 +4807,7 @@
               "name": "example"
             }
           ],
-          "docs": "Configure the delay period for period update check. the unit is in seconds.\n\nOnly available for Android and iOS.\nCannot be less than 600 seconds (10 minutes).",
+          "docs": "Configure the interval in seconds for repeating update checks while the app stays open.\nForeground checks still run when this is 0. Values below 600 are normalized to 600.\n\nOnly available for Android and iOS.\nCannot be less than 600 seconds (10 minutes).",
           "complexTypes": [],
           "type": "number | undefined"
         },

package/dist/esm/definitions.d.ts

@@ -44,8 +44,9 @@ declare module '@capacitor/cli' {
             /**
              * Configure how the plugin checks for, downloads, and applies live updates.
              *
-             * The plugin checks for updates when the app moves to the foreground and, if
-             * {@link periodCheckDelay} is set, on a repeating timer while the app stays open.
+             * The plugin checks for updates when the app moves to the foreground. When
+             * {@link periodCheckDelay} is greater than 0, it also checks on a repeating timer
+             * while the app stays open.
              *
              * Boolean values keep their existing behavior:
              * - `true`: Same as `"atBackground"`.
@@ -99,7 +100,8 @@ declare module '@capacitor/cli' {
              * Native stats include update lifecycle events, app health signals such as crashes,
              * Android ANRs, low-memory exits, iOS memory warnings, and WebView health signals
              * such as JavaScript errors, unhandled promise rejections, resource load failures,
-             * WebView renderer exits, and unclean WebView restarts when available.
+             * WebView renderer exits, unclean WebView restarts, app launch readiness timing,
+             * and WebView load milestones when available.
              *
              * @default https://plugin.capgo.app/stats
              * @example https://example.com/api/stats
@@ -130,10 +132,10 @@ declare module '@capacitor/cli' {
              * @deprecated Use {@link PluginsConfig.CapacitorUpdater.autoUpdate} string modes instead.
              * Works well for apps less than 10MB and with uploads done using --delta flag.
              * Zip or apps more than 10MB will be relatively slow for users to update.
-             * - false: Never do direct updates (use default behavior: download on foreground check, apply when backgrounded)
-             * - atInstall: Direct update only after app install or native app store update, otherwise act as directUpdate = false
-             * - onLaunch: Direct update only when the app is brought to the foreground from a killed state, otherwise act as directUpdate = false
-             * - always: Direct update on every foreground check whenever an update is available, never act as directUpdate = false
+             * - false: Never do direct updates
+             * - atInstall: Same as `"atInstall"` for {@link autoUpdate}
+             * - onLaunch: Same as `"onLaunch"` for {@link autoUpdate}
+             * - always: Same as `"always"` for {@link autoUpdate}
              * - true: (deprecated) Same as "always" for backward compatibility
              *
              * Activate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads.
@@ -181,7 +183,8 @@ declare module '@capacitor/cli' {
              */
             autoSplashscreenTimeout?: number;
             /**
-             * Configure the delay period for period update check. the unit is in seconds.
+             * Configure the interval in seconds for repeating update checks while the app stays open.
+             * Foreground checks still run when this is 0. Values below 600 are normalized to 600.
              *
              * Only available for Android and iOS.
              * Cannot be less than 600 seconds (10 minutes).
@@ -485,7 +488,9 @@ export interface CapacitorUpdaterPlugin {
      * **Android Background Runner note:** `@capacitor/background-runner` loads its
      * configured runner script from native APK assets. Live updates cannot replace
      * that runner script. Keep it stable across OTA updates and ship a native app
-     * update when the runner code changes.
+     * update when the runner code changes. When a bundle switch happens, Capacitor
+     * Updater cancels and reschedules configured Background Runner WorkManager jobs
+     * and syncs the bundled runner script into native `public/` storage when present.
      *
      * @example
      * const bundle = await CapacitorUpdater.download({