akanjs 3.0.0-beta.9 → 3.0.1

package/vendor/@akanjs/native/plugins/biometric/android/BiometricPlugin.kt

@@ -0,0 +1,179 @@
+package com.akanjs.plugins.biometric
+
+import android.app.Activity
+import android.app.KeyguardManager
+import android.content.pm.PackageManager
+import android.hardware.biometrics.BiometricManager
+import android.hardware.biometrics.BiometricManager.Authenticators.BIOMETRIC_WEAK
+import android.hardware.biometrics.BiometricManager.Authenticators.DEVICE_CREDENTIAL
+import android.hardware.biometrics.BiometricPrompt
+import android.os.Build
+import android.os.CancellationSignal
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * Framework android.hardware.biometrics.BiometricPrompt instead of androidx.biometric (plugins.md §2).
+ * tauri-plugins-workspace/plugins/biometric/android needs a separate AppCompat BiometricActivity
+ * because the androidx prompt is a Fragment; the framework prompt is system UI started from any
+ * Context, so it runs straight from the shell's Activity. Kept from Tauri:
+ * - BIOMETRIC_WEAK (Class 2) like Tauri's status(): plain presence checks need no Class 3 sensor.
+ *   BIOMETRIC_STRONG only matters for a CryptoObject-bound key, which this API does not offer.
+ * - A negative button cannot be combined with DEVICE_CREDENTIAL (the builder throws).
+ * - The sensor kind comes from PackageManager features (first of fingerprint, face, iris).
+ * - KeyguardManager.isDeviceSecure tells whether a PIN / pattern / password exists.
+ * USE_BIOMETRIC is a normal permission (granted at install).
+ * API 29 has one tier and no authenticator types (both 30): canAuthenticate() counts only strong
+ * biometrics and never the screen lock, so "credential allowed" is answered with isDeviceSecure, and
+ * without a usable biometric the screen lock is asked through KeyguardManager's confirm intent, as
+ * androidx.biometric does there (Tauri BiometricPlugin.kt:115-120, BiometricActivity.kt:56-65).
+ * Arguments arrive decoded and type-checked by the generated BiometricPluginSpec (PL-10).
+ */
+class BiometricPlugin(private val context: AkanNativePluginContext) : BiometricPluginSpec {
+    private var pending: CancellationSignal? = null
+
+    override fun isAvailable(reply: AkanNativeReply<BiometricStatus>) = reply.resolve(status())
+
+    override fun destroy() {
+        pending?.cancel()
+        pending = null
+    }
+
+    private val manager: BiometricManager? get() = context.activity.getSystemService(BiometricManager::class.java)
+
+    private fun sensor(): BiometricBiometryType {
+        val pm = context.activity.packageManager
+        return when {
+            pm.hasSystemFeature(PackageManager.FEATURE_FINGERPRINT) -> BiometricBiometryType.FINGERPRINT
+            pm.hasSystemFeature(PackageManager.FEATURE_FACE) -> BiometricBiometryType.FACE
+            pm.hasSystemFeature(PackageManager.FEATURE_IRIS) -> BiometricBiometryType.IRIS
+            else -> BiometricBiometryType.NONE
+        }
+    }
+
+    private fun deviceSecure(): Boolean = context.activity.getSystemService(KeyguardManager::class.java)?.isDeviceSecure == true
+
+    /** Biometrics only (BIOMETRIC_WEAK on 30+; API 29's single tier). */
+    private fun biometricCode(): Int {
+        val m = manager ?: return BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE
+        return if (Build.VERSION.SDK_INT >= 30) Api30.canAuthenticate(m, BIOMETRIC_WEAK) else @Suppress("DEPRECATION") m.canAuthenticate()
+    }
+
+    private fun status(): BiometricStatus {
+        val code = biometricCode()
+        val reason = when (code) {
+            BiometricManager.BIOMETRIC_SUCCESS -> null
+            BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> BiometricUnavailableReason.NOT_ENROLLED
+            BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> BiometricUnavailableReason.NO_HARDWARE
+            BiometricManager.BIOMETRIC_ERROR_NOT_ENABLED_FOR_APPS -> BiometricUnavailableReason.DENIED // Settings: "use for apps" off
+            else -> BiometricUnavailableReason.UNAVAILABLE // HW_UNAVAILABLE, SECURITY_UPDATE_REQUIRED, IDENTITY_CHECK_NOT_ACTIVE
+        }
+        return BiometricStatus(
+            available = code == BiometricManager.BIOMETRIC_SUCCESS,
+            type = if (code == BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE) BiometricBiometryType.NONE else sensor(),
+            reason = reason,
+            deviceCredential = deviceSecure(),
+        )
+    }
+
+    override fun authenticate(args: BiometricAuthenticateOptions, reply: AkanNativeVoidReply) {
+        val reason = args.reason
+        if (reason.isEmpty()) return reply.reject(AkanNativeErrorCode.INVALID_ARGS, "reason must be a non-empty string")
+        if (pending != null) return reply.reject(AkanNativeErrorCode.CANCELLED, "another authentication is in progress")
+        val allowCredential = args.allowDeviceCredential == true
+        val authenticators = if (allowCredential) BIOMETRIC_WEAK or DEVICE_CREDENTIAL else BIOMETRIC_WEAK
+        val activity = context.activity
+        val title = args.title?.takeIf { it.isNotEmpty() }
+        val code = when {
+            Build.VERSION.SDK_INT >= 30 -> manager?.let { Api30.canAuthenticate(it, authenticators) } ?: BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE
+            else -> biometricCode()
+        }
+        if (code != BiometricManager.BIOMETRIC_SUCCESS) {
+            // API 29: the screen lock alone, when allowed and set up.
+            if (Build.VERSION.SDK_INT < 30 && allowCredential && deviceSecure()) return confirmCredential(activity, title, reason, reply)
+            val (error, message) = unavailable(code, allowCredential)
+            return reply.reject(error, message)
+        }
+
+        val builder = BiometricPrompt.Builder(activity)
+            .setTitle(title ?: reason) // required: build() throws without a title
+        if (Build.VERSION.SDK_INT >= 30) Api30.allow(builder, authenticators)
+        else @Suppress("DEPRECATION") builder.setDeviceCredentialAllowed(allowCredential)
+        if (title != null) builder.setSubtitle(reason)
+        val signal = CancellationSignal()
+        var done = false
+        val finish = { settle: AkanNativeVoidReply.() -> Unit ->
+            if (!done) {
+                done = true
+                if (pending === signal) pending = null
+                reply.settle()
+            }
+        }
+        if (!allowCredential) {
+            val cancel = args.cancelTitle?.takeIf { it.isNotEmpty() } ?: activity.getString(android.R.string.cancel)
+            builder.setNegativeButton(cancel, activity.mainExecutor) { _, _ -> finish { reject(AkanNativeErrorCode.CANCELLED, "authentication was cancelled") } }
+        }
+        pending = signal
+        // The prompt belongs to its call: cancelled (AbortSignal) or with its page gone, it goes away.
+        reply.onCancel {
+            done = true
+            if (pending === signal) pending = null
+            signal.cancel()
+        }
+        try {
+            builder.build().authenticate(signal, activity.mainExecutor, object : BiometricPrompt.AuthenticationCallback() {
+                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) = finish { resolve() }
+
+                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) =
+                    finish { reject(errorFor(errorCode), errString.toString()) }
+
+                // onAuthenticationFailed: one attempt did not match; the prompt stays up for another try.
+            })
+        } catch (e: RuntimeException) { // IllegalArgumentException from the builder, SecurityException without USE_BIOMETRIC
+            finish { reject(AkanNativeErrorCode.INTERNAL, e.toString()) }
+        }
+    }
+
+    /** API 29 without a usable biometric: the system's screen lock confirmation. */
+    private fun confirmCredential(activity: Activity, title: String?, reason: String, reply: AkanNativeVoidReply) {
+        @Suppress("DEPRECATION")
+        val intent = activity.getSystemService(KeyguardManager::class.java)?.createConfirmDeviceCredentialIntent(title ?: reason, if (title != null) reason else null)
+            ?: return reply.reject(AkanNativeErrorCode.PERMISSION_DENIED, "no screen lock is set up")
+        try {
+            context.startActivityForResult("credential", intent) { result, _ ->
+                if (result == Activity.RESULT_OK) reply.resolve() else reply.reject(AkanNativeErrorCode.CANCELLED, "authentication was cancelled")
+            }
+        } catch (e: RuntimeException) {
+            reply.reject(AkanNativeErrorCode.INTERNAL, e.toString())
+        }
+    }
+
+    private object Api30 {
+        fun canAuthenticate(manager: BiometricManager, authenticators: Int): Int = manager.canAuthenticate(authenticators)
+
+        fun allow(builder: BiometricPrompt.Builder, authenticators: Int) {
+            builder.setAllowedAuthenticators(authenticators)
+        }
+    }
+
+    private fun unavailable(code: Int, allowCredential: Boolean): Pair<String, String> = when (code) {
+        BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED ->
+            AkanNativeErrorCode.PERMISSION_DENIED to if (allowCredential) "no biometrics and no screen lock are set up" else "no biometrics are enrolled"
+        BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> AkanNativeErrorCode.UNSUPPORTED to "this device has no biometric sensor"
+        BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE -> AkanNativeErrorCode.UNSUPPORTED to "the biometric sensor is unavailable"
+        BiometricManager.BIOMETRIC_ERROR_NOT_ENABLED_FOR_APPS -> AkanNativeErrorCode.PERMISSION_DENIED to "biometrics are turned off for apps"
+        else -> AkanNativeErrorCode.INTERNAL to "biometrics cannot be used (code $code)"
+    }
+
+    private fun errorFor(code: Int): String = when (code) {
+        BiometricPrompt.BIOMETRIC_ERROR_USER_CANCELED, BiometricPrompt.BIOMETRIC_ERROR_CANCELED, BiometricPrompt.BIOMETRIC_ERROR_TIMEOUT ->
+            AkanNativeErrorCode.CANCELLED
+        BiometricPrompt.BIOMETRIC_ERROR_LOCKOUT, BiometricPrompt.BIOMETRIC_ERROR_LOCKOUT_PERMANENT, BiometricPrompt.BIOMETRIC_ERROR_NO_BIOMETRICS,
+        BiometricPrompt.BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL, BiometricPrompt.BIOMETRIC_ERROR_NOT_ENABLED_FOR_APPS ->
+            AkanNativeErrorCode.PERMISSION_DENIED
+        BiometricPrompt.BIOMETRIC_ERROR_HW_NOT_PRESENT, BiometricPrompt.BIOMETRIC_ERROR_HW_UNAVAILABLE -> AkanNativeErrorCode.UNSUPPORTED
+        else -> AkanNativeErrorCode.INTERNAL
+    }
+}

package/vendor/@akanjs/native/plugins/biometric/ios/BiometricPlugin.swift

@@ -0,0 +1,129 @@
+import Foundation
+import LocalAuthentication
+
+/// LAContext (tauri-plugins-workspace/plugins/biometric/ios/Sources/BiometricPlugin.swift, with changes):
+/// - A fresh LAContext per call. Tauri computes the status once at load, which goes stale when the
+///   user enrolls or turns Face ID off for the app while it runs.
+/// - biometryType is valid after canEvaluatePolicy whatever it returns, so the sensor kind is known
+///   even when nothing is enrolled.
+/// - Face ID without NSFaceIDUsageDescription must not be evaluated (Tauri reports it as
+///   unavailable too); the manifest adds the text.
+/// - Biometrics only: localizedFallbackTitle = "" hides the "Enter Password" button that iOS shows
+///   after a failed match (tapping it ends with LAError.userFallback). allowDeviceCredential uses
+///   .deviceOwnerAuthentication, where the system handles the passcode itself.
+/// - The prompt belongs to its call: cancelled (AbortSignal) or with its page gone, the context is
+///   invalidated and the prompt goes away (LAError.appCancel, already answered).
+/// - Simulator: Features > Face ID > Enrolled / Matching Face / Non-matching Face. There is no simctl
+///   command; `xcrun simctl spawn <udid> notifyutil -s com.apple.BiometricKit.enrollmentChanged 1` +
+///   `notifyutil -p com.apple.BiometricKit.enrollmentChanged` toggles enrollment and
+///   `notifyutil -p com.apple.BiometricKit_Sim.pearl.match` (or .nomatch) answers a prompt.
+/// Arguments arrive decoded and type-checked by the generated BiometricPluginSpec (PL-10).
+final class BiometricPlugin: BiometricPluginSpec {
+    static let id = "biometric"
+    private var current: LAContext?
+
+    init(context: AkanNativePluginContext) {}
+
+    func isAvailable(_ reply: AkanNativeReply<BiometricStatus>) {
+        reply.resolve(Self.status())
+    }
+
+    private static var hasFaceIDUsageDescription: Bool {
+        Bundle.main.object(forInfoDictionaryKey: "NSFaceIDUsageDescription") != nil
+    }
+
+    nonisolated private static func name(_ type: LABiometryType) -> BiometricBiometryType {
+        switch type {
+        case .faceID: .face
+        case .touchID: .fingerprint
+        case .opticID: .iris
+        default: .none_
+        }
+    }
+
+    private static func status() -> BiometricStatus {
+        let context = LAContext()
+        var error: NSError?
+        let ok = context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error)
+        let type = context.biometryType
+        var result = BiometricStatus(
+            available: false,
+            type: name(type),
+            deviceCredential: LAContext().canEvaluatePolicy(.deviceOwnerAuthentication, error: nil)
+        )
+        if ok, type == .faceID, !hasFaceIDUsageDescription {
+            result.reason = .notConfigured
+        } else if ok {
+            result.available = true
+        } else {
+            result.reason = reason(error.map { LAError.Code(rawValue: $0.code) } ?? nil, type)
+        }
+        return result
+    }
+
+    nonisolated private static func reason(_ code: LAError.Code?, _ type: LABiometryType) -> BiometricUnavailableReason {
+        switch code {
+        case .biometryNotEnrolled?, .passcodeNotSet?: .notEnrolled
+        case .biometryLockout?: .lockedOut
+        // With a sensor present this is the per-app Face ID switch in Settings.
+        case .biometryNotAvailable?: type == .none ? .noHardware : .denied
+        default: .unavailable
+        }
+    }
+
+    func authenticate(_ args: BiometricAuthenticateOptions, _ reply: AkanNativeReply<Void>) {
+        let reason = args.reason
+        guard !reason.isEmpty else { return reply.reject(.invalidArgs, "reason must be a non-empty string") }
+        guard current == nil else { return reply.reject(.cancelled, "another authentication is in progress") }
+        let allowCredential = args.allowDeviceCredential ?? false
+        let policy: LAPolicy = allowCredential ? .deviceOwnerAuthentication : .deviceOwnerAuthenticationWithBiometrics
+        let context = LAContext()
+        var error: NSError?
+        guard context.canEvaluatePolicy(policy, error: &error) else {
+            let (code, message) = Self.failure(error, context.biometryType)
+            return reply.reject(code, message)
+        }
+        if context.biometryType == .faceID, !Self.hasFaceIDUsageDescription {
+            return reply.reject(.internalError, "Info.plist has no NSFaceIDUsageDescription")
+        }
+        if let cancel = args.cancelTitle, !cancel.isEmpty { context.localizedCancelTitle = cancel }
+        if !allowCredential { context.localizedFallbackTitle = "" }
+        let type = context.biometryType
+        current = context
+        reply.onCancel { [weak self] in
+            context.invalidate()
+            if self?.current === context { self?.current = nil }
+        }
+        let key = ObjectIdentifier(context) // Sendable, unlike LAContext
+        context.evaluatePolicy(policy, localizedReason: reason) { [weak self] success, error in
+            if success {
+                reply.resolve()
+            } else {
+                let (code, message) = Self.failure(error, type)
+                reply.reject(code, message)
+            }
+            DispatchQueue.main.async {
+                MainActor.assumeIsolated {
+                    if let current = self?.current, ObjectIdentifier(current) == key { self?.current = nil }
+                }
+            }
+        }
+    }
+
+    nonisolated private static func failure(_ error: (any Error)?, _ type: LABiometryType) -> (AkanNativeErrorCode, String) {
+        let message = error?.localizedDescription ?? "authentication failed"
+        guard let code = (error as? LAError)?.code else { return (.internalError, message) }
+        switch code {
+        case .userCancel, .systemCancel, .appCancel, .userFallback, .notInteractive:
+            return (.cancelled, message)
+        case .authenticationFailed, .biometryLockout, .biometryNotEnrolled, .passcodeNotSet:
+            return (.permissionDenied, message)
+        case .biometryNotAvailable:
+            return (type == .none ? .unsupported : .permissionDenied, message)
+        case .biometryDisconnected, .biometryNotPaired, .companionNotAvailable:
+            return (.unsupported, message)
+        default:
+            return (.internalError, message)
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/biometric/native-plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "biometric",
+  "apiVersion": 1,
+  "methods": ["isAvailable", "authenticate"],
+  "events": [],
+  "codegen": true,
+  "web": null,
+  "desktop": null,
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "BiometricPlugin",
+    "frameworks": ["LocalAuthentication"],
+    "infoPlist": {
+      "NSFaceIDUsageDescription": "Confirm that it is you with Face ID."
+    }
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.biometric.BiometricPlugin",
+    "permissions": ["android.permission.USE_BIOMETRIC"]
+  }
+}

package/vendor/@akanjs/native/plugins/biometric/src/index.ts

@@ -0,0 +1,100 @@
+import { createLiveValue, definePlugin, shallowEqual } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+
+/** The kind of biometric sensor. iOS Optic ID counts as "iris". */
+export type BiometryType = "face" | "fingerprint" | "iris" | "none";
+
+/**
+ * Why biometrics cannot be used right now.
+ * - noHardware: no sensor
+ * - notEnrolled: nothing enrolled, or (iOS) no passcode, which biometrics require
+ * - lockedOut: too many failed attempts; the passcode unlocks it again (allowDeviceCredential)
+ * - denied: the user turned biometrics off for this app (iOS Face ID setting, Android "use for apps")
+ * - notConfigured: the app lacks NSFaceIDUsageDescription (iOS; the manifest adds it)
+ * - unavailable: anything else (sensor busy, security update required)
+ */
+export type BiometricUnavailableReason =
+  | "noHardware"
+  | "notEnrolled"
+  | "lockedOut"
+  | "denied"
+  | "notConfigured"
+  | "unavailable";
+
+export interface BiometricStatus {
+  /** Whether authenticate() can use biometrics now. */
+  available: boolean;
+  /** The sensor kind, also when nothing is enrolled. On Android with several sensors, the first of fingerprint, face, iris. */
+  type: BiometryType;
+  /** Set when not available. */
+  reason?: BiometricUnavailableReason;
+  /** Whether a passcode / PIN / pattern is set, i.e. whether allowDeviceCredential can succeed. */
+  deviceCredential: boolean;
+}
+
+export interface AuthenticateOptions {
+  /** Why the app asks. iOS shows it under "Face ID"; Android uses it as the title, or as the subtitle when `title` is set. */
+  reason: string;
+  /** Android: prompt title. */
+  title?: string;
+  /** Label of the cancel button. Android ignores it with allowDeviceCredential (the system prompt has its own). */
+  cancelTitle?: string;
+  /**
+   * Also accept the device passcode / PIN / pattern (iOS .deviceOwnerAuthentication, Android
+   * DEVICE_CREDENTIAL). Default false: biometrics only, and iOS hides its "Enter Password" button.
+   */
+  allowDeviceCredential?: boolean;
+}
+
+/**
+ * Local user verification (Face ID, Touch ID, fingerprint, face unlock). A successful
+ * authenticate() proves presence to this app only; it unlocks no key and must not replace a
+ * server-side login.
+ *
+ * authenticate() rejects with
+ * - CANCELLED: the user or the system cancelled (app sent to the background, another prompt)
+ * - PERMISSION_DENIED: not enrolled, locked out, turned off for the app, or (iOS) failed attempts
+ * - UNSUPPORTED: no sensor (and no allowed passcode fallback); every call on the web and macOS
+ * - INTERNAL: NSFaceIDUsageDescription missing (iOS) and other platform failures
+ */
+export interface BiometricApi {
+  isAvailable(): Promise<BiometricStatus>;
+  authenticate(options: AuthenticateOptions): Promise<void>;
+}
+
+export const biometric = definePlugin<BiometricApi>("biometric", {
+  methods: ["isAvailable", "authenticate"],
+});
+
+const status = createLiveValue<BiometricStatus | null>(
+  null,
+  (set) => {
+    if (!biometric.isSupported("isAvailable")) return;
+    let live = true;
+    const refresh = () => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+      biometric
+        .isAvailable()
+        .then((next) => live && set(next))
+        .catch((error) => console.warn("[akan-native] biometric.isAvailable failed", error));
+    };
+    refresh();
+    if (typeof window === "undefined")
+      return () => {
+        live = false;
+      };
+    document.addEventListener("visibilitychange", refresh);
+    window.addEventListener("focus", refresh);
+    return () => {
+      live = false;
+      document.removeEventListener("visibilitychange", refresh);
+      window.removeEventListener("focus", refresh);
+    };
+  },
+  (a, b) => a === b || (a !== null && b !== null && shallowEqual(a, b)),
+);
+
+/** The biometric status, or null while it loads and where the platform has no biometric plugin (web, macOS). */
+export function useBiometricStatus(): BiometricStatus | null {
+  return useLiveValue(status);
+}

package/vendor/@akanjs/native/plugins/browser/android/BrowserPlugin.kt

@@ -0,0 +1,178 @@
+package com.akanjs.plugins.browser
+
+import android.app.Activity
+import android.app.Application
+import android.content.ActivityNotFoundException
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.graphics.Color
+import android.net.Uri
+import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * Custom Tabs without androidx.browser (plugins.md §2 AndroidX table): an ACTION_VIEW intent with
+ * the extras CustomTabsIntent.Builder would add.
+ * - EXTRA_SESSION with a null binder is what makes the browser open a Custom Tab instead of a
+ *   normal tab; plus the toolbar color, share button on and the app as referrer, as
+ *   capacitor-plugins/browser/android/.../Browser.java:113-134 sets them.
+ * - The package is picked like CustomTabsClient.getPackageName: the default browser if it has a
+ *   Custom Tabs service, else the first one that has. Both lookups need the <queries> in
+ *   native-plugin.json (Android 11 package visibility; Capacitor's manifest has the same).
+ *   No Custom Tabs browser: a plain browser in its own task, which close() cannot close.
+ * - close(): Custom Tabs have no close API. Capacitor restarts its singleTask trampoline
+ *   (BrowserControllerActivity.java:49-55), which clears the tab above it. Since Android 15 that
+ *   start is a background activity launch and is blocked for apps targeting 35+ while the tab
+ *   covers the app (verified: "Background activity launch blocked", BAL_BLOCK). finishActivity(requestCode)
+ *   is not a launch and closes the tab (verified), so the tab is started with this plugin's own
+ *   request code: AkanNativePluginContext.startActivityForResult does not expose the one it picks.
+ * - finished: the shell activity resumes, which in this task only happens once the tab above it is
+ *   gone (Done, back, or the launcher icon). The result of the tab would say the same, but it goes
+ *   to the shell's result map only for requests started through the context. Capacitor reports a
+ *   minimized (picture-in-picture) tab as finished on Android < 14 (Browser.java:190-200); here
+ *   that should happen on every version, since the app is back in front (not verified).
+ * - open() needs the app in front: a page timer calling it from the background would be a blocked
+ *   launch as well (PERMISSION_DENIED), and it resolves once the tab covers the app.
+ * Arguments arrive decoded and type-checked by the generated BrowserPluginSpec (PL-10).
+ */
+class BrowserPlugin(private val context: AkanNativePluginContext) : BrowserPluginSpec {
+    private enum class State { NONE, OPENING, SHOWING }
+
+    private val main = Handler(Looper.getMainLooper())
+    private var state = State.NONE
+    private var customTab = false
+    private var resumed = false
+    private val events = BrowserEvents(context)
+    private var opening: AkanNativeVoidReply? = null
+    private var closing: AkanNativeVoidReply? = null
+
+    private val openTimeout = Runnable {
+        if (state != State.OPENING) return@Runnable
+        state = State.NONE
+        opening?.reject(AkanNativeErrorCode.INTERNAL, "the browser did not open")
+        opening = null
+    }
+    private val closeTimeout = Runnable {
+        closing?.reject(AkanNativeErrorCode.INTERNAL, "the browser did not close")
+        closing = null
+    }
+
+    private val lifecycle = object : Application.ActivityLifecycleCallbacks {
+        override fun onActivityPaused(activity: Activity) {
+            resumed = false
+            if (state != State.OPENING) return
+            state = State.SHOWING
+            main.removeCallbacks(openTimeout)
+            opening?.resolve()
+            opening = null
+        }
+
+        override fun onActivityResumed(activity: Activity) {
+            resumed = true
+            if (state != State.SHOWING) return
+            state = State.NONE
+            main.removeCallbacks(closeTimeout)
+            val reply = closing
+            closing = null
+            if (reply != null) reply.resolve() else events.finished(BrowserFinishedEvent())
+        }
+
+        override fun onActivityStarted(activity: Activity) {}
+        override fun onActivityStopped(activity: Activity) {}
+        override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
+        override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
+        override fun onActivityDestroyed(activity: Activity) {}
+    }
+
+    init {
+        // Created in the shell's onCreate: the first onResume is still to come.
+        context.activity.registerActivityLifecycleCallbacks(lifecycle)
+    }
+
+    override fun open(args: BrowserOpenArgs, reply: AkanNativeVoidReply) {
+        val uri = checkedUri(args.url, reply) ?: return
+        val color = args.toolbarColor?.let { hex ->
+            if (!COLOR.matches(hex)) return reply.reject(AkanNativeErrorCode.INVALID_ARGS, "toolbarColor must look like \"#1a2b3c\"")
+            Color.parseColor(hex)
+        }
+        if (state != State.NONE) return reply.reject(AkanNativeErrorCode.INVALID_ARGS, "a browser is already open; close() it first")
+        if (!resumed) return reply.reject(AkanNativeErrorCode.PERMISSION_DENIED, "the browser can only be opened while the app is in front")
+        val activity = context.activity
+        val provider = customTabsPackage(activity)
+        try {
+            if (provider != null) {
+                val intent = Intent(Intent.ACTION_VIEW, uri).setPackage(provider)
+                intent.putExtras(Bundle().apply { putBinder(EXTRA_SESSION, null) })
+                intent.putExtra(EXTRA_SHARE_STATE, SHARE_STATE_ON)
+                intent.putExtra(Intent.EXTRA_REFERRER, Uri.parse("android-app://${activity.packageName}"))
+                if (color != null) intent.putExtra(EXTRA_TOOLBAR_COLOR, color)
+                activity.startActivityForResult(intent, REQUEST_TAB)
+            } else {
+                activity.startActivity(Intent(Intent.ACTION_VIEW, uri).addCategory(Intent.CATEGORY_BROWSABLE).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
+            }
+        } catch (e: ActivityNotFoundException) {
+            return reply.reject(AkanNativeErrorCode.NOT_FOUND, "no browser can open $uri")
+        } catch (e: SecurityException) {
+            return reply.reject(AkanNativeErrorCode.PERMISSION_DENIED, e.message ?: "not allowed to open $uri")
+        }
+        customTab = provider != null
+        state = State.OPENING
+        opening = reply
+        main.postDelayed(openTimeout, OPEN_TIMEOUT_MS)
+    }
+
+    override fun close(reply: AkanNativeVoidReply) {
+        if (state == State.NONE) return reply.resolve()
+        if (!customTab) return reply.reject(AkanNativeErrorCode.UNSUPPORTED, "the browser runs as its own app (no Custom Tabs support) and cannot be closed")
+        closing?.resolve() // an earlier close() still waiting: the same tab
+        main.removeCallbacks(closeTimeout)
+        closing = reply
+        context.activity.finishActivity(REQUEST_TAB)
+        main.postDelayed(closeTimeout, CLOSE_TIMEOUT_MS)
+    }
+
+    override fun destroy() {
+        main.removeCallbacks(openTimeout)
+        main.removeCallbacks(closeTimeout)
+        context.activity.unregisterActivityLifecycleCallbacks(lifecycle)
+    }
+
+    private fun checkedUri(text: String, reply: AkanNativeVoidReply): Uri? {
+        val uri = if (text.isEmpty()) null else Uri.parse(text).normalizeScheme()
+        val problem = when {
+            uri == null || !uri.isAbsolute -> "url must be an absolute URL"
+            uri.scheme != "http" && uri.scheme != "https" -> "only http and https URLs open in the in-app browser (got ${uri.scheme}:)"
+            uri.host.isNullOrEmpty() -> "$text has no host"
+            else -> return uri
+        }
+        reply.reject(AkanNativeErrorCode.INVALID_ARGS, problem)
+        return null
+    }
+
+    companion object {
+        const val ACTION_CUSTOM_TABS_SERVICE = "android.support.customtabs.action.CustomTabsService"
+        const val EXTRA_SESSION = "android.support.customtabs.extra.SESSION"
+        const val EXTRA_TOOLBAR_COLOR = "android.support.customtabs.extra.TOOLBAR_COLOR"
+        const val EXTRA_SHARE_STATE = "androidx.browser.customtabs.extra.SHARE_STATE"
+        const val SHARE_STATE_ON = 1
+        /** Far from the shell's own request codes, which count up from 1000. */
+        private const val REQUEST_TAB = 0x6F6D0B01
+        private const val OPEN_TIMEOUT_MS = 3000L
+        private const val CLOSE_TIMEOUT_MS = 3000L
+        private val COLOR = Regex("^#[0-9a-fA-F]{6}$")
+
+        /** The browser to open Custom Tabs in, or null when none supports them. */
+        fun customTabsPackage(activity: Activity): String? {
+            val pm = activity.packageManager
+            val providers = pm.queryIntentServices(Intent(ACTION_CUSTOM_TABS_SERVICE), 0).mapNotNull { it.serviceInfo?.packageName }
+            if (providers.isEmpty()) return null
+            val browse = Intent(Intent.ACTION_VIEW, Uri.parse("https://")).addCategory(Intent.CATEGORY_BROWSABLE)
+            val default = pm.resolveActivity(browse, PackageManager.MATCH_DEFAULT_ONLY)?.activityInfo?.packageName
+            return if (default != null && default in providers) default else providers.first()
+        }
+    }
+}