akanjs 3.0.0-beta.20 → 3.0.0-beta.21

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()
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/browser/ios/BrowserPlugin.swift

@@ -0,0 +1,63 @@
+import SafariServices
+import UIKit
+
+/// SFSafariViewController, presented full screen from the topmost controller
+/// (capacitor-plugins/browser/ios/Sources/BrowserPlugin/Browser.swift and BrowserPlugin.swift).
+/// - http/https only (Browser.swift:19): anything else crashes SFSafariViewController.
+/// - finished: safariViewControllerDidFinish, sent for Done and the edge swipe. It is not sent
+///   for a dismissal the app asks for, so close() never produces it. With .fullScreen there is no
+///   swipe-down dismissal that would bypass the delegate.
+/// - SFSafariViewController dismisses itself after Done; Capacitor dismisses the presenter again
+///   in didFinish (BrowserPlugin.swift:31-39), which can dismiss an unrelated controller. Not here.
+/// - toolbarColor is ignored: preferredBarTintColor is deprecated in iOS 26 (bar tinting fights
+///   the system's glass background).
+/// - SFSafariViewControllerDelegate is not main-actor annotated, but SafariServices calls it on the
+///   main thread: an isolated conformance (checked at run time).
+/// Arguments arrive decoded and type-checked by the generated BrowserPluginSpec (PL-10).
+final class BrowserPlugin: NSObject, BrowserPluginSpec, @MainActor SFSafariViewControllerDelegate {
+    static let id = "browser"
+    private let context: AkanNativePluginContext
+    private weak var safari: SFSafariViewController?
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+        super.init()
+    }
+
+    func open(_ args: BrowserOpenArgs, _ reply: AkanNativeReply<Void>) {
+        guard let parts = URLComponents(string: args.url),
+              let scheme = parts.scheme?.lowercased(), scheme == "http" || scheme == "https",
+              !(parts.host ?? "").isEmpty, let url = parts.url
+        else {
+            return reply.reject(.invalidArgs, "url must be an absolute http or https URL")
+        }
+        if let hex = args.toolbarColor {
+            guard hex.count == 7, hex.hasPrefix("#"), UInt32(hex.dropFirst(), radix: 16) != nil else {
+                return reply.reject(.invalidArgs, "toolbarColor must look like \"#1a2b3c\"")
+            }
+        }
+        if let safari, safari.presentingViewController != nil {
+            return reply.reject(.invalidArgs, "a browser is already open; close() it first")
+        }
+        let controller = SFSafariViewController(url: url)
+        controller.delegate = self
+        controller.modalPresentationStyle = .fullScreen
+        safari = controller
+        context.present(controller, completion: { reply.resolve() }) { [weak self] in
+            self?.safari = nil
+            reply.reject(.internalError, "nothing to present the browser from")
+        }
+    }
+
+    func close(_ reply: AkanNativeReply<Void>) {
+        guard let safari, safari.presentingViewController != nil else { return reply.resolve() }
+        self.safari = nil
+        safari.dismiss(animated: true) { reply.resolve() }
+    }
+
+    func safariViewControllerDidFinish(_ controller: SFSafariViewController) {
+        guard controller === safari else { return }
+        safari = nil
+        BrowserEvents(context).finished(BrowserFinishedEvent())
+    }
+}

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

@@ -0,0 +1,22 @@
+{
+  "id": "browser",
+  "apiVersion": 1,
+  "methods": ["open", "close"],
+  "events": ["finished"],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": {
+    "module": "./src/desktop.ts",
+    "methods": ["open"]
+  },
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "BrowserPlugin",
+    "frameworks": ["SafariServices"]
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.browser.BrowserPlugin",
+    "manifestXml": "<queries><intent><action android:name=\"android.support.customtabs.action.CustomTabsService\" /></intent><intent><action android:name=\"android.intent.action.VIEW\" /><category android:name=\"android.intent.category.BROWSABLE\" /><data android:scheme=\"https\" /></intent></queries>"
+  }
+}

package/vendor/@akanjs/native/plugins/browser/src/args.ts

@@ -0,0 +1,34 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+
+/**
+ * http and https only: SFSafariViewController takes nothing else (capacitor-plugins/browser/ios/
+ * Sources/BrowserPlugin/Browser.swift:19) and Custom Tabs are browser tabs. Other schemes belong
+ * to the opener plugin. The native implementations check the same rules.
+ */
+export function checkUrl(url: unknown): URL {
+  if (typeof url !== "string" || url.length === 0)
+    throw new AkanNativeError("INVALID_ARGS", "url must be a non-empty string");
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new AkanNativeError("INVALID_ARGS", `${url} is not an absolute URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new AkanNativeError(
+      "INVALID_ARGS",
+      `only http and https URLs open in the in-app browser (got ${parsed.protocol})`,
+    );
+  }
+  if (!parsed.hostname) throw new AkanNativeError("INVALID_ARGS", `${url} has no host`);
+  return parsed;
+}
+
+/** "#rrggbb" or undefined. Capacitor logs and ignores a bad color; here it is INVALID_ARGS. */
+export function checkColor(color: unknown): string | undefined {
+  if (color === undefined || color === null) return undefined;
+  if (typeof color !== "string" || !/^#[0-9a-fA-F]{6}$/.test(color)) {
+    throw new AkanNativeError("INVALID_ARGS", `toolbarColor must look like "#1a2b3c" (got ${JSON.stringify(color)})`);
+  }
+  return color;
+}

package/vendor/@akanjs/native/plugins/browser/src/desktop.ts

@@ -0,0 +1,40 @@
+
+
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+import { defineDesktopPlugin, externalOpenAllowed } from "../../../packages/desktop/src/plugin.ts";
+import { checkColor, checkUrl } from "./args.ts";
+import type { BrowserApi, BrowserEvents } from "./index.ts";
+
+export type Runner = (argv: string[]) => Promise<{ code: number; stderr: string }>;
+
+const spawnRunner: Runner = async (argv) => {
+  const proc = Bun.spawn(argv, { stdin: "ignore", stdout: "ignore", stderr: "pipe" });
+  const [stderr, code] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+  return { code, stderr };
+};
+
+/** `run` is replaceable so tests can check the command without opening a browser, `platform` to test the shell op path. */
+export function createDesktopBrowser(run: Runner = spawnRunner, platform: NodeJS.Platform = process.platform) {
+  return defineDesktopPlugin<BrowserApi, BrowserEvents>({
+    id: "browser",
+    methods: {
+      async open(args, ctx) {
+        const url = checkUrl(args?.url);
+        checkColor(args?.toolbarColor);
+        if (!externalOpenAllowed())
+          throw new AkanNativeError("NOT_ALLOWED", "at most one URL per second leaves the app; try again later");
+        if (platform !== "darwin") {
+          await ctx.shell("shell.open", { url: url.href });
+          return;
+        }
+        const { code, stderr } = await run(["/usr/bin/open", "-u", url.href]);
+        if (code !== 0) throw new AkanNativeError("INTERNAL", `open failed (${code}): ${stderr.trim()}`);
+      },
+    },
+    events: {
+      finished: () => () => {},
+    },
+  });
+}
+
+export default createDesktopBrowser();

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

@@ -0,0 +1,47 @@
+import { definePlugin } from "../../../packages/core/src/index.ts";
+import { usePluginEvent } from "../../../packages/react/src/index.ts";
+import { web } from "./web.ts";
+
+export { checkColor, checkUrl } from "./args.ts";
+
+/**
+ * In-app browser (plugins.md §4.5): a system browser view over the app, sharing the browser's
+ * cookies and passwords, with the page's URL visible to the user. For signing in, use
+ * auth-session instead, which also returns the redirect.
+ *
+ * | host    | view                                   | close()     | finished                 |
+ * |---------|----------------------------------------|-------------|--------------------------|
+ * | iOS     | SFSafariViewController                 | ✓           | ✓                        |
+ * | Android | Custom Tab                             | ✓           | ✓                        |
+ * | Android | plain browser (no Custom Tabs browser) | UNSUPPORTED | never                    |
+ * | web     | new window (popup)                     | ✓           | ✓ (polled, ≤ 0.5 s late) |
+ * | desktop | the default browser                    | UNSUPPORTED | never                    |
+ */
+export interface BrowserApi {
+  /**
+   * Shows `url` (http or https) and resolves once the browser is up. One at a time: rejects
+   * INVALID_ARGS while a browser opened here is still showing. `toolbarColor` ("#rrggbb") colors the
+   * Custom Tab toolbar on Android; iOS 26 no longer tints Safari's bars and ignores it.
+   * PERMISSION_DENIED on the web when the popup was blocked (call it from a click) and on Android
+   * while the app is not in front (Android 15+ blocks activity starts from the background).
+   */
+  open(args: { url: string; toolbarColor?: string }): Promise<void>;
+  /** Closes the browser opened by open(). Resolves also when none is showing. Does not send `finished`. */
+  close(): Promise<void>;
+}
+
+export interface BrowserEvents {
+  /** The user closed the browser (Done, back, or closed the window). */
+  finished: Record<string, never>;
+}
+
+export const browser = definePlugin<BrowserApi, BrowserEvents>("browser", {
+  methods: ["open", "close"],
+  events: ["finished"],
+  web,
+});
+
+/** Calls `handler` whenever the user closes the in-app browser, while mounted. */
+export function useBrowserFinished(handler: () => void): void {
+  usePluginEvent(browser, "finished", () => handler());
+}