capacitor-app-lifecycle 0.0.0-stage → 0.0.1

package/CapacitorAppLifecycle.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapacitorAppLifecycle'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapacitorAppLifecycle",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "CapacitorAppLifecycle",
+            targets: ["AppLifecyclePlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "AppLifecyclePlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Sources/AppLifecyclePlugin"),
+        .testTarget(
+            name: "AppLifecyclePluginTests",
+            dependencies: ["AppLifecyclePlugin"],
+            path: "ios/Tests/AppLifecyclePluginTests")
+    ]
+)

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# capacitor-app-lifecycle
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Close a Capacitor app for good, from JavaScript, on iOS and Android.
+
+Sometimes an app gets into a state it cannot fix while it is running: a local database that has to be rebuilt, a native SDK that
+has to start again, a migration that needs a clean start. The usual way out is to ask the user to close the app and open it again.
+This plugin does the closing part. The process ends, and the next time the user taps the icon the app starts from scratch.
+
+It is a clean exit, not a crash. Crashing on purpose is a common workaround, and it fills your crash reporter with noise you then
+have to filter out. This plugin does not do that.
+
+## Install
+
+```bash
+npm install capacitor-app-lifecycle
+npx cap sync
+```
+
+Requires Capacitor 8. Android 8.0 (API 26) or newer, iOS 15 or newer. On iOS the plugin is a Swift package; CocoaPods works too.
+
+## Use
+
+```typescript
+import { AppLifecycle } from 'capacitor-app-lifecycle';
+
+async function restartFromScratch() {
+  // Tell the user first: the app disappears as soon as this runs.
+  await AppLifecycle.forceClose();
+}
+```
+
+Do anything that has to happen first (saving, flushing logs, telling the user) **before** the call. Nothing after it is
+guaranteed to run.
+
+## How it closes the app
+
+The two platforms do it differently, and that shows up in the promise.
+
+**iOS.** The promise resolves, then about 0.3 seconds later the process calls `exit(0)` on the main thread. The short wait lets the
+result reach JavaScript and lets any running animation finish, so code right after the `await` starts to run, but there is no
+promise it finishes.
+
+**Android.** The activity task is finished with `finishAffinity()`, which takes the app off the recents screen, and then the process
+is killed. The promise is resolved before that, but the process usually goes down before the answer reaches JavaScript, so on
+Android the `await` normally never returns. Do not wait on it for anything.
+
+Calling `forceClose()` again while an exit is already on its way does not schedule a second one.
+
+On the web the call rejects with the `UNIMPLEMENTED` error code. A page cannot close its own browser tab, so decide what your app
+should do there instead, for example reload:
+
+```typescript
+import { Capacitor } from '@capacitor/core';
+
+if (Capacitor.isNativePlatform()) {
+  await AppLifecycle.forceClose();
+} else {
+  window.location.href = '/';
+}
+```
+
+### A note on App Store review
+
+Apple's guidelines discourage apps that quit on their own. Use this for recovery, after telling the user what is about to happen,
+not as a normal way to leave the app.
+
+## Coming from the Cordova plugin
+
+If you used a Cordova plugin that exposed `cordova.plugins.appLifecycle.forceClose()`, the call maps one to one:
+
+| Cordova                                                   | Capacitor                         |
+| --------------------------------------------------------- | --------------------------------- |
+| `cordova.plugins.appLifecycle.forceClose(success, error)` | `await AppLifecycle.forceClose()` |
+
+The native behaviour is the same: `exit(0)` after 0.3 seconds on iOS, `finishAffinity()` and a process kill on Android.
+
+## API
+
+<docgen-index>
+
+* [`forceClose()`](#forceclose)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### forceClose()
+
+```typescript
+forceClose() => Promise<void>
+```
+
+Terminates the app process, so that the next launch starts from scratch.
+
+Use it when the app is in a state it cannot recover from in place, for
+example a local database that has to be rebuilt, and the user should simply
+open the app again. It is a clean exit, not a crash: nothing is reported to
+a crash reporter.
+
+The two platforms end the process differently, and the promise behaves
+accordingly:
+
+- **iOS**: the promise resolves, and the process exits with `exit(0)` about
+  0.3 seconds later, on the main thread.
+- **Android**: the activity task is finished with `finishAffinity()` and the
+  process is killed straight away. The promise is resolved first, but the
+  process usually goes down before the result reaches JavaScript, so do not
+  wait on it for anything.
+
+Calling it again while an exit is already on its way resolves without
+scheduling a second one.
+
+On the web it rejects with the `UNIMPLEMENTED` code.
+
+**Since:** 1.0.0
+
+--------------------
+
+</docgen-api>
+
+## Testing
+
+Everything that can be tested without ending the test process is tested on every change:
+
+```bash
+npm run test:unit      # TypeScript: the web rejects, native calls reach the right plugin and method
+npm run test:parity    # the API, the Swift, the Kotlin and this README name the same methods
+npm run test:android   # JUnit on the JVM: the order of the steps, the double-call guard
+npm run test:ios       # XCTest on a simulator: the delay, the double-call guard, the main thread
+```
+
+The native code takes the scheduler and the exit as arguments, so the tests hand it fakes and check what it would have done.
+
+What the tests cannot show is the process actually ending, because that would end the test too. That part needs a real app on a
+phone or a simulator: call `forceClose()`, check that the process is gone (`adb shell pidof <package>` prints nothing on Android;
+on iOS the app is no longer running), and check that no crash was reported. The example app in `example-app/` has a button for it.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,64 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    androidxCoreKTXVersion = project.hasProperty('androidxCoreKTXVersion') ? rootProject.ext.androidxCoreKTXVersion : '1.17.0'
+}
+
+buildscript {
+    ext.kotlin_version = project.hasProperty("kotlin_version") ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace = "io.github.maximbelov.applifecycle"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 26
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+    }
+    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
+    }
+}
+
+kotlin {
+    jvmToolchain(21)
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.core:core-ktx:$androidxCoreKTXVersion"
+    testImplementation "junit:junit:$junitVersion"
+}

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/kotlin/io/github/maximbelov/applifecycle/AppLifecycle.kt

@@ -0,0 +1,38 @@
+package io.github.maximbelov.applifecycle
+
+/**
+ * Ends the app process: finishes the activity task, then kills the process.
+ *
+ * The three steps are passed in so that the order and the guard can be tested on the JVM without ending the test process.
+ * [AppLifecyclePlugin] passes the real ones.
+ */
+class AppLifecycle(
+    private val runOnMainThread: (Runnable) -> Unit,
+    private val finishTask: () -> Unit,
+    private val killProcess: () -> Unit,
+) {
+    private var closing = false
+
+    /**
+     * Schedules the exit on the main thread. Returns false, and schedules nothing, when an exit is already scheduled.
+     */
+    @Synchronized
+    fun forceClose(): Boolean {
+        if (closing) {
+            return false
+        }
+        closing = true
+        runOnMainThread(
+            Runnable {
+                // Finishing the task first removes it from the recents screen; killing the process is what actually ends it,
+                // because finishAffinity() on its own leaves the process (and the web view) alive.
+                try {
+                    finishTask()
+                } finally {
+                    killProcess()
+                }
+            },
+        )
+        return true
+    }
+}

package/android/src/main/kotlin/io/github/maximbelov/applifecycle/AppLifecyclePlugin.kt

@@ -0,0 +1,30 @@
+package io.github.maximbelov.applifecycle
+
+import android.os.Process
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+
+@CapacitorPlugin(name = "AppLifecycle")
+class AppLifecyclePlugin : Plugin() {
+
+    private val implementation by lazy {
+        AppLifecycle(
+            runOnMainThread = { task ->
+                val activity = getActivity()
+                if (activity != null) activity.runOnUiThread(task) else task.run()
+            },
+            finishTask = { getActivity()?.finishAffinity() },
+            killProcess = { Process.killProcess(Process.myPid()) },
+        )
+    }
+
+    @PluginMethod
+    fun forceClose(call: PluginCall) {
+        // Resolved before the exit is scheduled, as the Cordova plugin did. The process usually dies before the result reaches
+        // JavaScript, so callers must not depend on it.
+        call.resolve()
+        implementation.forceClose()
+    }
+}

package/dist/docs.json

@@ -0,0 +1,30 @@
+{
+  "api": {
+    "name": "AppLifecyclePlugin",
+    "slug": "applifecycleplugin",
+    "docs": "",
+    "tags": [],
+    "methods": [
+      {
+        "name": "forceClose",
+        "signature": "() => Promise<void>",
+        "parameters": [],
+        "returns": "Promise<void>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "1.0.0"
+          }
+        ],
+        "docs": "Terminates the app process, so that the next launch starts from scratch.\n\nUse it when the app is in a state it cannot recover from in place, for\nexample a local database that has to be rebuilt, and the user should simply\nopen the app again. It is a clean exit, not a crash: nothing is reported to\na crash reporter.\n\nThe two platforms end the process differently, and the promise behaves\naccordingly:\n\n- **iOS**: the promise resolves, and the process exits with `exit(0)` about\n  0.3 seconds later, on the main thread.\n- **Android**: the activity task is finished with `finishAffinity()` and the\n  process is killed straight away. The promise is resolved first, but the\n  process usually goes down before the result reaches JavaScript, so do not\n  wait on it for anything.\n\nCalling it again while an exit is already on its way resolves without\nscheduling a second one.\n\nOn the web it rejects with the `UNIMPLEMENTED` code.",
+        "complexTypes": [],
+        "slug": "forceclose"
+      }
+    ],
+    "properties": []
+  },
+  "interfaces": [],
+  "enums": [],
+  "typeAliases": [],
+  "pluginConfigs": []
+}

package/dist/esm/definitions.d.ts

@@ -0,0 +1,28 @@
+export interface AppLifecyclePlugin {
+    /**
+     * Terminates the app process, so that the next launch starts from scratch.
+     *
+     * Use it when the app is in a state it cannot recover from in place, for
+     * example a local database that has to be rebuilt, and the user should simply
+     * open the app again. It is a clean exit, not a crash: nothing is reported to
+     * a crash reporter.
+     *
+     * The two platforms end the process differently, and the promise behaves
+     * accordingly:
+     *
+     * - **iOS**: the promise resolves, and the process exits with `exit(0)` about
+     *   0.3 seconds later, on the main thread.
+     * - **Android**: the activity task is finished with `finishAffinity()` and the
+     *   process is killed straight away. The promise is resolved first, but the
+     *   process usually goes down before the result reaches JavaScript, so do not
+     *   wait on it for anything.
+     *
+     * Calling it again while an exit is already on its way resolves without
+     * scheduling a second one.
+     *
+     * On the web it rejects with the `UNIMPLEMENTED` code.
+     *
+     * @since 1.0.0
+     */
+    forceClose(): Promise<void>;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export interface AppLifecyclePlugin {\n  /**\n   * Terminates the app process, so that the next launch starts from scratch.\n   *\n   * Use it when the app is in a state it cannot recover from in place, for\n   * example a local database that has to be rebuilt, and the user should simply\n   * open the app again. It is a clean exit, not a crash: nothing is reported to\n   * a crash reporter.\n   *\n   * The two platforms end the process differently, and the promise behaves\n   * accordingly:\n   *\n   * - **iOS**: the promise resolves, and the process exits with `exit(0)` about\n   *   0.3 seconds later, on the main thread.\n   * - **Android**: the activity task is finished with `finishAffinity()` and the\n   *   process is killed straight away. The promise is resolved first, but the\n   *   process usually goes down before the result reaches JavaScript, so do not\n   *   wait on it for anything.\n   *\n   * Calling it again while an exit is already on its way resolves without\n   * scheduling a second one.\n   *\n   * On the web it rejects with the `UNIMPLEMENTED` code.\n   *\n   * @since 1.0.0\n   */\n  forceClose(): Promise<void>;\n}\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+import type { AppLifecyclePlugin } from './definitions';
+declare const AppLifecycle: AppLifecyclePlugin;
+export * from './definitions';
+export { AppLifecycle };

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { registerPlugin } from '@capacitor/core';
+const AppLifecycle = registerPlugin('AppLifecycle', {
+    web: () => import('./web').then((m) => new m.AppLifecycleWeb()),
+});
+export * from './definitions';
+export { AppLifecycle };
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,YAAY,GAAG,cAAc,CAAqB,cAAc,EAAE;IACtE,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;CAChE,CAAC,CAAC;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,CAAC","sourcesContent":["import { registerPlugin } from '@capacitor/core';\n\nimport type { AppLifecyclePlugin } from './definitions';\n\nconst AppLifecycle = registerPlugin<AppLifecyclePlugin>('AppLifecycle', {\n  web: () => import('./web').then((m) => new m.AppLifecycleWeb()),\n});\n\nexport * from './definitions';\nexport { AppLifecycle };\n"]}

package/dist/esm/web.d.ts

@@ -0,0 +1,5 @@
+import { WebPlugin } from '@capacitor/core';
+import type { AppLifecyclePlugin } from './definitions';
+export declare class AppLifecycleWeb extends WebPlugin implements AppLifecyclePlugin {
+    forceClose(): Promise<void>;
+}

package/dist/esm/web.js

@@ -0,0 +1,7 @@
+import { WebPlugin } from '@capacitor/core';
+export class AppLifecycleWeb extends WebPlugin {
+    async forceClose() {
+        throw this.unimplemented('forceClose is not available on the web.');
+    }
+}
+//# sourceMappingURL=web.js.map

package/dist/esm/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAC5C,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,CAAC,aAAa,CAAC,yCAAyC,CAAC,CAAC;IACtE,CAAC;CACF","sourcesContent":["import { WebPlugin } from '@capacitor/core';\n\nimport type { AppLifecyclePlugin } from './definitions';\n\nexport class AppLifecycleWeb extends WebPlugin implements AppLifecyclePlugin {\n  async forceClose(): Promise<void> {\n    throw this.unimplemented('forceClose is not available on the web.');\n  }\n}\n"]}

package/dist/plugin.cjs.js

@@ -0,0 +1,21 @@
+'use strict';
+
+var core = require('@capacitor/core');
+
+const AppLifecycle = core.registerPlugin('AppLifecycle', {
+    web: () => Promise.resolve().then(function () { return web; }).then((m) => new m.AppLifecycleWeb()),
+});
+
+class AppLifecycleWeb extends core.WebPlugin {
+    async forceClose() {
+        throw this.unimplemented('forceClose is not available on the web.');
+    }
+}
+
+var web = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    AppLifecycleWeb: AppLifecycleWeb
+});
+
+exports.AppLifecycle = AppLifecycle;
+//# sourceMappingURL=plugin.cjs.js.map

package/dist/plugin.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.cjs.js","sources":["esm/index.js","esm/web.js"],"sourcesContent":["import { registerPlugin } from '@capacitor/core';\nconst AppLifecycle = registerPlugin('AppLifecycle', {\n    web: () => import('./web').then((m) => new m.AppLifecycleWeb()),\n});\nexport * from './definitions';\nexport { AppLifecycle };\n//# sourceMappingURL=index.js.map","import { WebPlugin } from '@capacitor/core';\nexport class AppLifecycleWeb extends WebPlugin {\n    async forceClose() {\n        throw this.unimplemented('forceClose is not available on the web.');\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["registerPlugin","WebPlugin"],"mappings":";;;;AACK,MAAC,YAAY,GAAGA,mBAAc,CAAC,cAAc,EAAE;AACpD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;AACnE,CAAC;;ACFM,MAAM,eAAe,SAASC,cAAS,CAAC;AAC/C,IAAI,MAAM,UAAU,GAAG;AACvB,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,yCAAyC,CAAC;AAC3E,IAAI;AACJ;;;;;;;"}

package/dist/plugin.js

@@ -0,0 +1,24 @@
+var capacitorAppLifecycle = (function (exports, core) {
+    'use strict';
+
+    const AppLifecycle = core.registerPlugin('AppLifecycle', {
+        web: () => Promise.resolve().then(function () { return web; }).then((m) => new m.AppLifecycleWeb()),
+    });
+
+    class AppLifecycleWeb extends core.WebPlugin {
+        async forceClose() {
+            throw this.unimplemented('forceClose is not available on the web.');
+        }
+    }
+
+    var web = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        AppLifecycleWeb: AppLifecycleWeb
+    });
+
+    exports.AppLifecycle = AppLifecycle;
+
+    return exports;
+
+})({}, capacitorExports);
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sources":["esm/index.js","esm/web.js"],"sourcesContent":["import { registerPlugin } from '@capacitor/core';\nconst AppLifecycle = registerPlugin('AppLifecycle', {\n    web: () => import('./web').then((m) => new m.AppLifecycleWeb()),\n});\nexport * from './definitions';\nexport { AppLifecycle };\n//# sourceMappingURL=index.js.map","import { WebPlugin } from '@capacitor/core';\nexport class AppLifecycleWeb extends WebPlugin {\n    async forceClose() {\n        throw this.unimplemented('forceClose is not available on the web.');\n    }\n}\n//# sourceMappingURL=web.js.map"],"names":["registerPlugin","WebPlugin"],"mappings":";;;AACK,UAAC,YAAY,GAAGA,mBAAc,CAAC,cAAc,EAAE;IACpD,IAAI,GAAG,EAAE,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;IACnE,CAAC;;ICFM,MAAM,eAAe,SAASC,cAAS,CAAC;IAC/C,IAAI,MAAM,UAAU,GAAG;IACvB,QAAQ,MAAM,IAAI,CAAC,aAAa,CAAC,yCAAyC,CAAC;IAC3E,IAAI;IACJ;;;;;;;;;;;"}

package/ios/Sources/AppLifecyclePlugin/AppLifecycle.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+/// Ends the app process with `exit(0)`, a short moment after it is asked to.
+///
+/// The delay lets the resolved call travel back to the web view before the process goes, and keeps `exit` from racing a UIKit
+/// transition that is still running. The scheduler and the exit are passed in so that the delay and the guard can be tested
+/// without ending the test process; `AppLifecyclePlugin` uses the real ones.
+@objc public class AppLifecycle: NSObject {
+    public static let defaultDelay: TimeInterval = 0.3
+
+    public typealias Scheduler = (_ delay: TimeInterval, _ work: @escaping () -> Void) -> Void
+
+    private let delay: TimeInterval
+    private let schedule: Scheduler
+    private let terminate: () -> Void
+    private let lock = NSLock()
+    private var closing = false
+
+    public init(
+        delay: TimeInterval = AppLifecycle.defaultDelay,
+        schedule: @escaping Scheduler = AppLifecycle.onMainQueue,
+        terminate: @escaping () -> Void = { exit(0) }
+    ) {
+        self.delay = delay
+        self.schedule = schedule
+        self.terminate = terminate
+    }
+
+    /// Schedules the exit. Returns false, and schedules nothing, when an exit is already scheduled.
+    @discardableResult
+    @objc public func forceClose() -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        if closing {
+            return false
+        }
+        closing = true
+        schedule(delay, terminate)
+        return true
+    }
+
+    public static func onMainQueue(_ delay: TimeInterval, _ work: @escaping () -> Void) {
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
+    }
+}

package/ios/Sources/AppLifecyclePlugin/AppLifecyclePlugin.swift

@@ -0,0 +1,18 @@
+import Foundation
+import Capacitor
+
+@objc(AppLifecyclePlugin)
+public class AppLifecyclePlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "AppLifecyclePlugin"
+    public let jsName = "AppLifecycle"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "forceClose", returnType: CAPPluginReturnPromise)
+    ]
+    private let implementation = AppLifecycle()
+
+    @objc func forceClose(_ call: CAPPluginCall) {
+        // Resolved first, so the promise settles in JavaScript before the process exits.
+        call.resolve()
+        implementation.forceClose()
+    }
+}

package/ios/Tests/AppLifecyclePluginTests/AppLifecyclePluginTests.swift

@@ -0,0 +1,23 @@
+import XCTest
+import Capacitor
+@testable import AppLifecyclePlugin
+
+// The JavaScript reaches the plugin by jsName and the method by its name; a rename on either side fails only at run time on a
+// phone, so it is pinned here.
+final class AppLifecyclePluginTests: XCTestCase {
+    func testIsRegisteredUnderTheNameTheJavaScriptUses() {
+        let plugin = AppLifecyclePlugin()
+        XCTAssertEqual(plugin.jsName, "AppLifecycle")
+    }
+
+    func testExposesForceCloseAsAPromiseMethodAndNothingElse() {
+        let methods = AppLifecyclePlugin().pluginMethods
+        XCTAssertEqual(methods.map { $0.name }, ["forceClose"])
+        XCTAssertEqual(methods.first?.returnType, CAPPluginReturnPromise)
+    }
+
+    func testTheMethodNameHasAnObjectiveCSelector() {
+        // Capacitor calls the method through the selector "forceClose:"; a missing @objc compiles fine and fails on the phone.
+        XCTAssertTrue(AppLifecyclePlugin().responds(to: NSSelectorFromString("forceClose:")))
+    }
+}

package/ios/Tests/AppLifecyclePluginTests/AppLifecycleTests.swift

@@ -0,0 +1,68 @@
+import XCTest
+@testable import AppLifecyclePlugin
+
+final class AppLifecycleTests: XCTestCase {
+    private var scheduled: [(delay: TimeInterval, work: () -> Void)] = []
+    private var exits = 0
+
+    private func lifecycle(delay: TimeInterval = AppLifecycle.defaultDelay) -> AppLifecycle {
+        AppLifecycle(
+            delay: delay,
+            schedule: { delay, work in self.scheduled.append((delay, work)) },
+            terminate: { self.exits += 1 }
+        )
+    }
+
+    override func setUp() {
+        super.setUp()
+        scheduled = []
+        exits = 0
+    }
+
+    func testNothingExitsBeforeTheScheduledWorkRuns() {
+        XCTAssertTrue(lifecycle().forceClose())
+        XCTAssertEqual(scheduled.count, 1)
+        XCTAssertEqual(exits, 0)
+    }
+
+    func testExitsWhenTheScheduledWorkRuns() {
+        lifecycle().forceClose()
+        scheduled.forEach { $0.work() }
+        XCTAssertEqual(exits, 1)
+    }
+
+    func testWaitsTheDefaultDelay() {
+        lifecycle().forceClose()
+        XCTAssertEqual(scheduled.first?.delay, 0.3)
+    }
+
+    func testASecondCallSchedulesNothing() {
+        let lifecycle = lifecycle()
+        XCTAssertTrue(lifecycle.forceClose())
+        XCTAssertFalse(lifecycle.forceClose())
+        scheduled.forEach { $0.work() }
+        XCTAssertEqual(scheduled.count, 1)
+        XCTAssertEqual(exits, 1)
+    }
+
+    func testConcurrentCallsScheduleOneExit() {
+        let lifecycle = lifecycle()
+        let results = UnsafeMutableBufferPointer<Bool>.allocate(capacity: 50)
+        defer { results.deallocate() }
+        DispatchQueue.concurrentPerform(iterations: 50) { index in
+            results[index] = lifecycle.forceClose()
+        }
+        XCTAssertEqual(results.filter { $0 }.count, 1)
+    }
+
+    func testTheMainQueueSchedulerRunsTheWorkOnTheMainThreadAfterTheDelay() {
+        let ran = expectation(description: "scheduled work ran")
+        let start = Date()
+        AppLifecycle.onMainQueue(0.05) {
+            XCTAssertTrue(Thread.isMainThread)
+            XCTAssertGreaterThanOrEqual(Date().timeIntervalSince(start), 0.05)
+            ran.fulfill()
+        }
+        wait(for: [ran], timeout: 2)
+    }
+}

package/package.json

@@ -1,6 +1,98 @@
 {
   "name": "capacitor-app-lifecycle",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Cleanly terminate the app process on iOS and Android from a Capacitor app",
+  "main": "dist/plugin.cjs.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "unpkg": "dist/plugin.js",
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "dist/",
+    "ios/Sources",
+    "ios/Tests",
+    "Package.swift",
+    "CapacitorAppLifecycle.podspec"
+  ],
+  "author": "Maxim Belov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaximBelov/capacitor-app-lifecycle.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MaximBelov/capacitor-app-lifecycle/issues"
+  },
+  "keywords": [
+    "capacitor",
+    "plugin",
+    "native",
+    "exit",
+    "force close",
+    "terminate",
+    "app lifecycle"
+  ],
+  "scripts": {
+    "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",
+    "verify:ios": "xcodebuild build -scheme CapacitorAppLifecycle -destination generic/platform=iOS -derivedDataPath build/ios-device",
+    "verify:android": "cd android && ./gradlew clean build test",
+    "verify:web": "npm run build",
+    "lint": "npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint",
+    "fmt": "npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format",
+    "eslint": "eslint . --ext ts",
+    "prettier": "prettier \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
+    "swiftlint": "node-swiftlint",
+    "docgen": "docgen --api AppLifecyclePlugin --output-readme README.md --output-json dist/docs.json",
+    "build": "npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs",
+    "clean": "rimraf ./dist",
+    "watch": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "npm run test:unit",
+    "test:unit": "vitest run",
+    "test:unit:coverage": "vitest run --coverage",
+    "test:parity": "node --test test/unit/platform-parity.test.mjs",
+    "test:android": "cd android && ./gradlew test",
+    "test:ios": "./scripts/test-ios.sh",
+    "example:install": "cd example-app && npm install --no-audit --no-fund",
+    "example:android:build": "npm run example:install && cd example-app && npm run build && npx cap sync android && cd android && ./gradlew assembleDebug",
+    "example:ios:build": "npm run example:install && cd example-app && npm run build && npx cap sync ios && xcodebuild build -project ios/App/App.xcodeproj -scheme App -destination generic/platform=iOS\\ Simulator -derivedDataPath ../build/example-ios CODE_SIGNING_ALLOWED=NO"
+  },
+  "devDependencies": {
+    "@capacitor/android": "^8.0.0",
+    "@capacitor/core": "^8.0.0",
+    "@capacitor/docgen": "^0.3.1",
+    "@capacitor/ios": "^8.0.0",
+    "@ionic/eslint-config": "^0.4.0",
+    "@ionic/prettier-config": "^4.0.0",
+    "@ionic/swiftlint-config": "^2.0.0",
+    "@vitest/coverage-v8": "^4.1.12",
+    "eslint": "^8.57.1",
+    "prettier": "^3.6.2",
+    "prettier-plugin-java": "^2.7.7",
+    "rimraf": "^6.1.0",
+    "rollup": "^4.53.2",
+    "swiftlint": "^2.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
+  },
+  "peerDependencies": {
+    "@capacitor/core": ">=8.0.0"
+  },
+  "prettier": "@ionic/prettier-config",
+  "swiftlint": "@ionic/swiftlint-config",
+  "eslintConfig": {
+    "extends": "@ionic/eslint-config/recommended"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}