@capgo/capacitor-webview-crash 7.1.0

package/README.md

@@ -0,0 +1,293 @@
+# @capgo/capacitor-webview-crash
+
+<a href="https://capgo.app/">
+  <img
+    src="https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png"
+    alt="Capgo - Instant updates for Capacitor"
+  />
+</a>
+
+<div align="center">
+  <h2>
+    <a href="https://capgo.app/?ref=plugin_webview_crash"> ➡️ Get Instant updates for your App with Capgo</a>
+  </h2>
+  <h2>
+    <a href="https://capgo.app/consulting/?ref=plugin_webview_crash">
+      Missing a feature? We’ll build the plugin for you 💪
+    </a>
+  </h2>
+</div>
+
+Detect recovered Capacitor WebView crashes, restart dead WebViews natively, and optionally recycle long-running WebViews on a fixed interval before memory pressure turns into an OOM.
+
+## What It Does
+
+- Stores a native crash marker when Android reports `onRenderProcessGone`.
+- Hooks the iOS WebView termination callback and persists equivalent crash metadata.
+- Restarts the WebView natively after crashes so recovery does not depend on a still-running JavaScript runtime.
+- Can restart the WebView on a fixed native interval for kiosk, POS, signage, telemetry, and other always-on apps.
+- Lets JavaScript request a native WebView restart with `restartWebView()` when the app wants to proactively recycle memory.
+- Exposes the marker through an event, a polling method, and a simulation helper for testing recovery flows.
+- Ships a web implementation that simulates the same recovery flow with local storage.
+
+## What It Does Not Do
+
+- Prevent the underlying WebView crash from happening.
+- Restore lost in-memory JavaScript state automatically.
+- Replace application-level state persistence. Persist critical state before enabling scheduled restarts.
+
+## Compatibility
+
+| Plugin version | Capacitor compatibility | Maintained |
+| -------------- | ----------------------- | ---------- |
+| v8.\*.\*       | v8.\*.\*                | ✅         |
+| v7.\*.\*       | v7.\*.\*                | On demand  |
+| v6.\*.\*       | v6.\*.\*                | On demand  |
+
+Policy:
+
+- New plugins start at version `8.0.0` (Capacitor 8 baseline).
+- Backward compatibility for older Capacitor majors is supported on demand.
+
+## Install
+
+```bash
+npm install @capgo/capacitor-webview-crash
+npx cap sync
+```
+
+## Usage
+
+```typescript
+import { WebViewCrash } from '@capgo/capacitor-webview-crash';
+
+await WebViewCrash.addListener('webViewRestoredAfterCrash', async (info) => {
+  console.log('Recovered after a WebView crash', info);
+  await WebViewCrash.clearPendingCrashInfo();
+});
+
+await WebViewCrash.addListener('webViewRestoredAfterRestart', async (info) => {
+  console.log('Recovered after a native WebView restart', info);
+  await WebViewCrash.clearPendingCrashInfo();
+});
+
+const pending = await WebViewCrash.getPendingCrashInfo();
+if (pending.value) {
+  console.log('Pending crash or restart marker', pending.value);
+}
+```
+
+Use `simulateCrashRecovery()` in development or automated tests to exercise your recovery UI without forcing a real native WebView crash.
+
+Call `restartWebView()` when the current JavaScript runtime decides the native WebView should be replaced:
+
+```typescript
+await WebViewCrash.restartWebView();
+```
+
+The call writes a pending marker with `reason: 'manualRestart'`, then native code restarts the WebView. Android recreates the host Activity. iOS rebuilds the Capacitor bridge view so a new `WKWebView` is created instead of reloading the current page.
+
+## Native Auto Restart
+
+Configure the plugin in `capacitor.config.ts` so restart decisions happen in native code, even when the JavaScript runtime is unavailable:
+
+```typescript
+import type { CapacitorConfig } from '@capacitor/cli';
+import type { WebViewCrashPluginConfig } from '@capgo/capacitor-webview-crash';
+
+const webViewCrash: WebViewCrashPluginConfig = {
+  // Keep native crash recovery enabled. This is the default.
+  restartOnCrash: true,
+
+  // Use a 5-field cron schedule in the device local timezone.
+  // Do not combine restartCron with an active restartIntervalMs.
+  restartCron: '0 3 * * *',
+
+  // Optional delay before restarting after a crash.
+  restartAfterCrashDelayMs: 0,
+};
+
+const config: CapacitorConfig = {
+  plugins: {
+    WebViewCrash: webViewCrash,
+  },
+};
+
+export default config;
+```
+
+Use scheduled restarts for apps that stay open for days: kiosk screens, control-room dashboards, point-of-sale terminals, warehouse scanners, vehicle tablets, or any Capacitor app that cannot rely on users force-closing it. The restart is native, writes a pending marker with `reason: 'periodicRestart'`, and then creates a fresh WebView.
+
+Set `restartIntervalMs` to a maintenance window that your product can tolerate, or set `restartCron` for a wall-clock schedule such as `0 3 * * *` for a daily 03:00 restart. `restartCron` uses 5-field cron syntax in the device local timezone and supports `*`, lists, ranges, and steps. Do not configure both schedules at once: native initialization throws a fatal config error when `restartCron` is set and `restartIntervalMs` is greater than `0`. The user will get a fresh JavaScript runtime, so persist unsaved form state, queued events, and in-progress work before enabling a short interval or cron schedule.
+
+## Config Type
+
+```typescript
+export interface WebViewCrashPluginConfig {
+  restartOnCrash?: boolean;
+  restartIntervalMs?: number;
+  restartCron?: string;
+  restartAfterCrashDelayMs?: number;
+}
+```
+
+## Platform Notes
+
+- **iOS:** Uses method swizzling on Capacitor's `WebViewDelegationHandler` to persist crash metadata before Capacitor reloads the WebView. Manual and scheduled restarts rebuild the Capacitor bridge view so a new `WKWebView` instance is created. No extra permissions are required.
+- **Android:** Registers a Capacitor `WebViewListener` and persists crash metadata from `onRenderProcessGone`. Crash and scheduled restarts reset the bridge and recreate the host activity, giving the app a fresh WebView. No extra permissions are required.
+- **Web:** There is no real browser crash detection. The web implementation only simulates the recovery flow with local storage.
+
+## Documentation
+
+- [Plugin docs](https://capgo.app/docs/plugins/webview-crash/)
+- [Getting started guide](https://capgo.app/docs/plugins/webview-crash/getting-started/)
+- [Example app](./example-app)
+
+## API
+
+<docgen-index>
+
+- [`getPendingCrashInfo()`](#getpendingcrashinfo)
+- [`clearPendingCrashInfo()`](#clearpendingcrashinfo)
+- [`simulateCrashRecovery()`](#simulatecrashrecovery)
+- [`restartWebView()`](#restartwebview)
+- [`addListener('webViewRestoredAfterCrash' | 'webViewRestoredAfterRestart', ...)`](#addlistenerwebviewrestoredaftercrash--webviewrestoredafterrestart-)
+- [`removeAllListeners()`](#removealllisteners)
+- [Interfaces](#interfaces)
+- [Type Aliases](#type-aliases)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+Capacitor API for recovered WebView crash and restart detection.
+
+### getPendingCrashInfo()
+
+```typescript
+getPendingCrashInfo() => Promise<PendingCrashInfoResult>
+```
+
+Returns the pending native crash or restart marker, if one exists.
+
+**Returns:** <code>Promise&lt;<a href="#pendingcrashinforesult">PendingCrashInfoResult</a>&gt;</code>
+
+---
+
+### clearPendingCrashInfo()
+
+```typescript
+clearPendingCrashInfo() => Promise<void>
+```
+
+Clears the stored marker after the app has handled recovery.
+
+---
+
+### simulateCrashRecovery()
+
+```typescript
+simulateCrashRecovery() => Promise<PendingCrashInfoResult>
+```
+
+Creates a fake crash marker so recovery flows can be tested locally.
+
+**Returns:** <code>Promise&lt;<a href="#pendingcrashinforesult">PendingCrashInfoResult</a>&gt;</code>
+
+---
+
+### restartWebView()
+
+```typescript
+restartWebView() => Promise<PendingCrashInfoResult>
+```
+
+Stores a manual restart marker and asks native code to create a fresh WebView.
+
+On Android this recreates the host Activity. On iOS this rebuilds the Capacitor bridge view so a new `WKWebView`
+instance is created instead of reloading the current page.
+
+**Returns:** <code>Promise&lt;<a href="#pendingcrashinforesult">PendingCrashInfoResult</a>&gt;</code>
+
+---
+
+### addListener('webViewRestoredAfterCrash' | 'webViewRestoredAfterRestart', ...)
+
+```typescript
+addListener(eventName: 'webViewRestoredAfterCrash' | 'webViewRestoredAfterRestart', listenerFunc: (info: WebViewCrashInfo) => void) => Promise<PluginListenerHandle>
+```
+
+Fires after a new JavaScript runtime attaches a listener and a matching marker is still pending.
+
+| Param              | Type                                                                             |
+| ------------------ | -------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'webViewRestoredAfterCrash' \| 'webViewRestoredAfterRestart'</code>        |
+| **`listenerFunc`** | <code>(info: <a href="#webviewcrashinfo">WebViewCrashInfo</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+---
+
+### removeAllListeners()
+
+```typescript
+removeAllListeners() => Promise<void>
+```
+
+Removes all plugin listeners.
+
+---
+
+### Interfaces
+
+#### PendingCrashInfoResult
+
+Pending crash or restart marker returned to JavaScript.
+
+| Prop        | Type                                                                  | Description                                                            |
+| ----------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **`value`** | <code><a href="#webviewcrashinfo">WebViewCrashInfo</a> \| null</code> | Stored crash or restart metadata, or `null` when no marker is pending. |
+
+#### WebViewCrashInfo
+
+Metadata captured natively after the previous WebView process died or was restarted.
+
+| Prop                         | Type                                                                  | Description                                                      |
+| ---------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| **`platform`**               | <code><a href="#webviewcrashplatform">WebViewCrashPlatform</a></code> | Platform that detected and stored the marker.                    |
+| **`timestamp`**              | <code>number</code>                                                   | Unix timestamp in milliseconds for when the marker was written.  |
+| **`timestampISO`**           | <code>string</code>                                                   | ISO-8601 version of `timestamp`.                                 |
+| **`reason`**                 | <code><a href="#webviewcrashreason">WebViewCrashReason</a></code>     | Platform-specific reason for the crash or restart marker.        |
+| **`url`**                    | <code>string</code>                                                   | Last known WebView URL when the marker was written.              |
+| **`didCrash`**               | <code>boolean</code>                                                  | Android-only hint from `RenderProcessGoneDetail.didCrash()`.     |
+| **`rendererPriorityAtExit`** | <code>number</code>                                                   | Android-only renderer priority reported at exit.                 |
+| **`appState`**               | <code><a href="#webviewcrashappstate">WebViewCrashAppState</a></code> | iOS-only application state captured when the marker was written. |
+
+#### PluginListenerHandle
+
+| Prop         | Type                                      |
+| ------------ | ----------------------------------------- |
+| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |
+
+### Type Aliases
+
+#### WebViewCrashPlatform
+
+Platform that produced the stored marker.
+
+<code>'android' | 'ios' | 'web'</code>
+
+#### WebViewCrashReason
+
+Native reason reported for the previous WebView failure or restart.
+
+<code>'renderProcessGone' | 'webContentProcessDidTerminate' | 'periodicRestart' | 'manualRestart' | 'simulated'</code>
+
+#### WebViewCrashAppState
+
+Best-effort application state captured on iOS when the WebView process died.
+
+<code>'active' | 'inactive' | 'background' | 'unknown'</code>
+
+</docgen-api>

package/android/build.gradle

@@ -0,0 +1,59 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.7.2'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace = "app.capgo.webviewcrash"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    annotationProcessor project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/app/capgo/webviewcrash/WebViewCrash.java

@@ -0,0 +1,288 @@
+package app.capgo.webviewcrash;
+
+import android.content.Context;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.PluginConfig;
+import java.time.Duration;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
+import java.time.temporal.ChronoUnit;
+import org.json.JSONException;
+
+final class WebViewCrash {
+
+    static final String CRASH_EVENT_NAME = "webViewRestoredAfterCrash";
+    static final String RESTART_EVENT_NAME = "webViewRestoredAfterRestart";
+    static final String PERIODIC_RESTART_REASON = "periodicRestart";
+    static final String MANUAL_RESTART_REASON = "manualRestart";
+
+    private static final String PREFERENCES_NAME = "CapgoWebViewCrash";
+    private static final String PENDING_CRASH_KEY = "pendingCrashInfo";
+
+    JSObject buildCrashInfo(String reason, String url, Boolean didCrash, Integer rendererPriorityAtExit) {
+        long timestamp = System.currentTimeMillis();
+        JSObject crashInfo = new JSObject();
+        crashInfo.put("platform", "android");
+        crashInfo.put("timestamp", timestamp);
+        crashInfo.put("timestampISO", Instant.ofEpochMilli(timestamp).toString());
+        crashInfo.put("reason", reason);
+
+        if (url != null && !url.isBlank()) {
+            crashInfo.put("url", url);
+        }
+
+        if (didCrash != null) {
+            crashInfo.put("didCrash", didCrash);
+        }
+
+        if (rendererPriorityAtExit != null) {
+            crashInfo.put("rendererPriorityAtExit", rendererPriorityAtExit);
+        }
+
+        return crashInfo;
+    }
+
+    JSObject readPendingCrashInfo(Context context) {
+        String raw = context.getSharedPreferences(PREFERENCES_NAME, Context.MODE_PRIVATE).getString(PENDING_CRASH_KEY, null);
+        if (raw == null) {
+            return null;
+        }
+
+        try {
+            return new JSObject(raw);
+        } catch (JSONException ignored) {
+            return null;
+        }
+    }
+
+    void writePendingCrashInfo(Context context, JSObject value) {
+        context.getSharedPreferences(PREFERENCES_NAME, Context.MODE_PRIVATE).edit().putString(PENDING_CRASH_KEY, value.toString()).apply();
+    }
+
+    void clearPendingCrashInfo(Context context) {
+        context.getSharedPreferences(PREFERENCES_NAME, Context.MODE_PRIVATE).edit().remove(PENDING_CRASH_KEY).apply();
+    }
+
+    boolean shouldDispatchEvent(String eventName, JSObject crashInfo) {
+        if (RESTART_EVENT_NAME.equals(eventName)) {
+            return true;
+        }
+
+        if (!CRASH_EVENT_NAME.equals(eventName)) {
+            return false;
+        }
+
+        String reason = crashInfo.optString("reason", "");
+        return !PERIODIC_RESTART_REASON.equals(reason) && !MANUAL_RESTART_REASON.equals(reason);
+    }
+
+    RestartOptions readRestartOptions(PluginConfig config) {
+        int restartIntervalMs = Math.max(0, config.getInt("restartIntervalMs", 0));
+        String restartCronExpression = config.getString("restartCron", null);
+
+        validateRestartScheduleConfig(restartIntervalMs, restartCronExpression);
+
+        return new RestartOptions(
+            config.getBoolean("restartOnCrash", true),
+            restartIntervalMs,
+            CronSchedule.parse(restartCronExpression),
+            Math.max(0, config.getInt("restartAfterCrashDelayMs", 0))
+        );
+    }
+
+    static void validateRestartScheduleConfig(int restartIntervalMs, String restartCronExpression) {
+        if (restartIntervalMs > 0 && restartCronExpression != null && !restartCronExpression.isBlank()) {
+            throw new IllegalStateException("Invalid WebViewCrash config: set either restartIntervalMs or restartCron, not both.");
+        }
+    }
+
+    static final class RestartOptions {
+
+        final boolean restartOnCrash;
+        final int restartIntervalMs;
+        final CronSchedule restartCron;
+        final int restartAfterCrashDelayMs;
+
+        RestartOptions(boolean restartOnCrash, int restartIntervalMs, CronSchedule restartCron, int restartAfterCrashDelayMs) {
+            this.restartOnCrash = restartOnCrash;
+            this.restartIntervalMs = restartIntervalMs;
+            this.restartCron = restartCron;
+            this.restartAfterCrashDelayMs = restartAfterCrashDelayMs;
+        }
+
+        Long nextRestartDelayMs() {
+            if (restartCron != null) {
+                return restartCron.nextDelayMs();
+            }
+
+            return restartIntervalMs > 0 ? (long) restartIntervalMs : null;
+        }
+    }
+
+    static final class CronSchedule {
+
+        private static final int SEARCH_LIMIT_MINUTES = 366 * 24 * 60 * 5;
+
+        private final CronField minutes;
+        private final CronField hours;
+        private final CronField daysOfMonth;
+        private final CronField months;
+        private final CronField daysOfWeek;
+
+        private CronSchedule(CronField minutes, CronField hours, CronField daysOfMonth, CronField months, CronField daysOfWeek) {
+            this.minutes = minutes;
+            this.hours = hours;
+            this.daysOfMonth = daysOfMonth;
+            this.months = months;
+            this.daysOfWeek = daysOfWeek;
+        }
+
+        static CronSchedule parse(String expression) {
+            if (expression == null || expression.isBlank()) {
+                return null;
+            }
+
+            String[] parts = expression.trim().split("\\s+");
+            if (parts.length != 5) {
+                return null;
+            }
+
+            CronField minutes = CronField.parse(parts[0], 0, 59, false);
+            CronField hours = CronField.parse(parts[1], 0, 23, false);
+            CronField daysOfMonth = CronField.parse(parts[2], 1, 31, false);
+            CronField months = CronField.parse(parts[3], 1, 12, false);
+            CronField daysOfWeek = CronField.parse(parts[4], 0, 7, true);
+
+            if (minutes == null || hours == null || daysOfMonth == null || months == null || daysOfWeek == null) {
+                return null;
+            }
+
+            return new CronSchedule(minutes, hours, daysOfMonth, months, daysOfWeek);
+        }
+
+        Long nextDelayMs() {
+            ZonedDateTime now = ZonedDateTime.now(ZoneId.systemDefault());
+            ZonedDateTime candidate = now.truncatedTo(ChronoUnit.MINUTES).plusMinutes(1);
+
+            for (int index = 0; index < SEARCH_LIMIT_MINUTES; index++) {
+                if (matches(candidate)) {
+                    return Math.max(0, Duration.between(now, candidate).toMillis());
+                }
+
+                candidate = candidate.plusMinutes(1);
+            }
+
+            return null;
+        }
+
+        private boolean matches(ZonedDateTime value) {
+            if (!minutes.matches(value.getMinute()) || !hours.matches(value.getHour()) || !months.matches(value.getMonthValue())) {
+                return false;
+            }
+
+            boolean dayOfMonthMatches = daysOfMonth.matches(value.getDayOfMonth());
+            boolean dayOfWeekMatches = daysOfWeek.matches(value.getDayOfWeek().getValue() % 7);
+
+            if (daysOfMonth.restricted && daysOfWeek.restricted) {
+                return dayOfMonthMatches || dayOfWeekMatches;
+            }
+
+            return dayOfMonthMatches && dayOfWeekMatches;
+        }
+    }
+
+    private static final class CronField {
+
+        private final boolean[] values;
+        private final boolean restricted;
+
+        private CronField(boolean[] values, boolean restricted) {
+            this.values = values;
+            this.restricted = restricted;
+        }
+
+        static CronField parse(String expression, int min, int max, boolean normalizeSunday) {
+            boolean[] values = new boolean[normalizeSunday ? 7 : max + 1];
+
+            for (String part : expression.split(",", -1)) {
+                if (part.isBlank() || !applyPart(values, part, min, max, normalizeSunday)) {
+                    return null;
+                }
+            }
+
+            int selectedCount = 0;
+            for (boolean selected : values) {
+                if (selected) {
+                    selectedCount++;
+                }
+            }
+
+            if (selectedCount == 0) {
+                return null;
+            }
+
+            int allValueCount = normalizeSunday ? 7 : max - min + 1;
+            return new CronField(values, selectedCount != allValueCount);
+        }
+
+        boolean matches(int value) {
+            return value >= 0 && value < values.length && values[value];
+        }
+
+        private static boolean applyPart(boolean[] values, String part, int min, int max, boolean normalizeSunday) {
+            String[] stepParts = part.split("/", -1);
+            if (stepParts.length > 2) {
+                return false;
+            }
+
+            int step = 1;
+            if (stepParts.length == 2) {
+                step = parseNumber(stepParts[1]);
+                if (step <= 0) {
+                    return false;
+                }
+            }
+
+            String rangePart = stepParts[0];
+            int start;
+            int end;
+            if ("*".equals(rangePart)) {
+                start = min;
+                end = max;
+            } else if (rangePart.contains("-")) {
+                String[] range = rangePart.split("-", -1);
+                if (range.length != 2) {
+                    return false;
+                }
+                start = parseNumber(range[0]);
+                end = parseNumber(range[1]);
+            } else {
+                start = parseNumber(rangePart);
+                end = start;
+            }
+
+            if (start < min || end > max || start > end) {
+                return false;
+            }
+
+            for (int value = start; value <= end; value += step) {
+                values[normalizeValue(value, normalizeSunday)] = true;
+            }
+
+            return true;
+        }
+
+        private static int parseNumber(String value) {
+            try {
+                return Integer.parseInt(value);
+            } catch (NumberFormatException ignored) {
+                return -1;
+            }
+        }
+
+        private static int normalizeValue(int value, boolean normalizeSunday) {
+            return normalizeSunday && value == 7 ? 0 : value;
+        }
+    }
+}