craft-native 0.0.90 → 0.0.92

package/dist/android/templates/CraftNative.kt.template

@@ -0,0 +1,2250 @@
+package com.craft.runtime
+
+import android.app.Activity
+import android.content.IntentSender
+import com.google.android.gms.location.Priority
+import com.google.android.gms.location.LocationServices
+import com.google.android.gms.location.LocationResult
+import com.google.android.gms.location.LocationRequest
+import com.google.android.gms.location.LocationCallback
+import com.google.android.gms.location.FusedLocationProviderClient
+import com.google.android.gms.common.ConnectionResult
+import com.google.android.gms.common.GoogleApiAvailability
+import android.location.Location
+import android.annotation.SuppressLint
+import android.Manifest
+import android.content.pm.PackageManager
+import android.os.Bundle
+import android.speech.RecognitionListener
+import android.speech.RecognizerIntent
+import android.speech.SpeechRecognizer
+import java.util.Locale
+import android.media.MediaRecorder
+import java.io.File
+import android.graphics.Bitmap
+import android.webkit.WebView
+import java.io.ByteArrayOutputStream
+import com.android.billingclient.api.*
+import android.graphics.BitmapFactory
+import android.util.Base64
+import com.google.mlkit.vision.common.InputImage
+import com.google.mlkit.vision.label.ImageLabeling
+import com.google.mlkit.vision.label.defaults.ImageLabelerOptions
+import com.google.mlkit.vision.objects.ObjectDetection
+import com.google.mlkit.vision.objects.defaults.ObjectDetectorOptions
+import com.google.mlkit.vision.text.TextRecognition
+import com.google.mlkit.vision.text.latin.TextRecognizerOptions
+import org.json.JSONArray
+import androidx.biometric.BiometricManager
+import androidx.biometric.BiometricPrompt
+import androidx.fragment.app.FragmentActivity
+import android.hardware.SensorManager
+import android.hardware.SensorEventListener
+import android.hardware.SensorEvent
+import android.hardware.Sensor
+import androidx.core.app.ActivityCompat
+import android.os.Build
+import android.bluetooth.le.ScanResult
+import android.bluetooth.le.ScanCallback
+import android.bluetooth.le.BluetoothLeScanner
+import android.bluetooth.BluetoothManager
+import androidx.lifecycle.ProcessLifecycleOwner
+import androidx.lifecycle.LifecycleEventObserver
+import android.net.NetworkRequest
+import android.net.NetworkCapabilities
+import android.net.Network
+import android.net.ConnectivityManager
+import android.content.Context
+import androidx.core.content.ContextCompat
+import com.google.android.play.core.review.ReviewManagerFactory
+import android.content.Intent
+import android.os.Handler
+import android.os.Looper
+import android.content.SharedPreferences
+import android.database.sqlite.SQLiteDatabase
+import org.json.JSONObject
+
+/**
+ * The Zig runtime's native methods.
+ *
+ * This class exists for one reason: its package is fixed. `CraftBridge` is
+ * generated with a templated package declaration, so its name differs per app,
+ * and the prebuilt `libcraft.so` cannot know it — neither JNI's
+ * `Java_<package>_...` symbol mangling nor a `FindClass` inside `JNI_OnLoad`
+ * can name a class chosen at generation time. Binding to
+ * `com.craft.runtime.CraftNative` instead lets one library serve every app
+ * unchanged.
+ *
+ * Nothing in this file is substituted. A template marker appearing here would
+ * make the library app-specific and the registration in `android_dispatch.zig`
+ * would stop finding this class.
+ *
+ * ## Every method may answer "not mine"
+ *
+ * A null return means Zig does not serve that action in this build, and the
+ * caller falls through to `CraftBridge`'s own Kotlin. That is the same
+ * hand-back the iOS seam performs, and it is what makes the migration
+ * incremental: an app on a build where Zig serves one action behaves exactly
+ * like one where it serves none.
+ *
+ * ## Why the natives are not `@JvmStatic`
+ *
+ * In a Kotlin `object`, `@JvmStatic` generates a static bridge alongside the
+ * instance method, and which of the two carries the `native` flag is a detail
+ * of the compiler rather than something this can rely on. `RegisterNatives`
+ * binds one specific method, and a static native takes `(JNIEnv*, jclass)`
+ * where an instance native takes `(JNIEnv*, jobject)` — so guessing wrong is
+ * a signature mismatch at load. Declaring them as ordinary instance methods on
+ * the singleton removes the question.
+ */
+object CraftNative {
+
+    /**
+     * True when `libcraft.so` loaded.
+     *
+     * The library is genuinely optional: an app can be built with no Zig
+     * runtime in `jniLibs`, and that is the shim-only configuration rather
+     * than an error. So the failure is caught and remembered — an
+     * `UnsatisfiedLinkError` escaping a static initialiser would take the
+     * whole class down and turn "no native runtime" into a crash on the first
+     * bridge call.
+     */
+    val isAvailable: Boolean = try {
+        System.loadLibrary("craft")
+        // Said out loud, because the two outcomes below are otherwise
+        // indistinguishable from outside: a library that never shipped and a
+        // library that loaded and then failed to bind both end with the shim
+        // answering every call. Zig logs its own registration under the same
+        // tag, so the pair reads as a sequence.
+        android.util.Log.i("CraftNative", "craft: libcraft.so loaded")
+        true
+    } catch (e: UnsatisfiedLinkError) {
+        // The reason, not just the fact. This used to be a bare `false`, and
+        // the first time the runtime was genuinely shipped and genuinely
+        // failed to load, the only evidence anywhere was that nothing
+        // happened — no linker line, no exception, nothing in logcat at all.
+        // The message carries the dynamic linker's own complaint, which is the
+        // one thing that says *why*.
+        android.util.Log.w("CraftNative", "craft: libcraft.so did not load: ${e.message}")
+        false
+    } catch (e: SecurityException) {
+        android.util.Log.w("CraftNative", "craft: libcraft.so was refused: ${e.message}")
+        false
+    }
+
+    /**
+     * How Zig reaches the page.
+     *
+     * Zig cannot make a `Runnable`, and `evaluateJavascript` is main-thread
+     * only — JNI can only produce a `Runnable` by registering natives on a
+     * class that already exists in the APK, which means shipping Kotlin to
+     * avoid writing Kotlin. So the hop stays here: Zig owns what to say, this
+     * owns which thread says it.
+     *
+     * Installed by `CraftBridge` once its WebView exists, and `@Volatile`
+     * because Zig calls `deliver` from whatever thread a device callback
+     * arrives on.
+     */
+    @Volatile
+    private var deliverer: ((String) -> Unit)? = null
+
+    private val lifecycleGeneration = java.util.concurrent.atomic.AtomicLong(0)
+    private var biometricPrompt: BiometricPrompt? = null
+
+    fun setDeliverer(deliver: ((String) -> Unit)?) {
+        deliverer = deliver
+    }
+
+    /** Release platform objects owned by native-backed actions. */
+    fun close(activity: Activity) {
+        lifecycleGeneration.incrementAndGet()
+        deliverer = null
+
+        runCatching { speechRecognizer?.cancel() }
+        runCatching { speechRecognizer?.destroy() }
+        speechRecognizer = null
+        runCatching { biometricPrompt?.cancelAuthentication() }
+        biometricPrompt = null
+
+        audioRecorder?.let { recorder ->
+            runCatching { recorder.stop() }
+            runCatching { recorder.release() }
+        }
+        audioRecorder = null
+        audioFile?.delete()
+        audioFile = null
+
+        runCatching { productBillingClient?.endConnection() }
+        productBillingClient = null
+        runCatching { restoreBillingClient?.endConnection() }
+        restoreBillingClient = null
+
+        networkWatch?.let { watch ->
+            val manager = activity.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+            runCatching { manager.unregisterNetworkCallback(watch) }
+        }
+        networkWatch = null
+        ProcessLifecycleOwner.get().lifecycle.removeObserver(appStateObserver)
+
+        bleScanCallback?.let { callback ->
+            runCatching { bleScanner?.stopScan(callback) }
+        }
+        bleScanCallback = null
+        bleScanner = null
+
+        motionListener?.let { listener ->
+            runCatching { sensorManager?.unregisterListener(listener) }
+        }
+        motionListener = null
+        sensorManager = null
+
+        currentLocationCallbacks.forEach { (callback, client) ->
+            runCatching { client.removeLocationUpdates(callback) }
+        }
+        currentLocationCallbacks.clear()
+        currentLocationTimeouts.values.forEach { timeout ->
+            currentLocationHandler.removeCallbacks(timeout)
+        }
+        currentLocationTimeouts.clear()
+        currentPositionSequence.incrementAndGet()
+    }
+
+    /**
+     * Run `script` in the page. Called from Zig, on any thread.
+     *
+     * Silent when no deliverer is installed — which is every moment before the
+     * WebView exists, and after it is torn down. A throw here would cross back
+     * into Zig as a pending exception on a thread that has nowhere to report
+     * it, and the caller already counts what it could not deliver.
+     */
+    @JvmStatic
+    fun deliver(script: String) {
+        runCatching { deliverer?.invoke(script) }
+    }
+
+    private external fun nativeGetDeviceInfo(activity: Activity): String?
+    private external fun nativeGetMemoryUsage(): String?
+    private external fun nativeLog(message: String): Boolean
+    private external fun nativeClipboardRead(activity: Activity): String?
+    private external fun nativeClipboardWrite(activity: Activity, text: String): Boolean
+    private external fun nativeOpenUrl(activity: Activity, url: String): Boolean
+    private external fun nativeShare(activity: Activity, text: String, title: String, chosen: IntentSender, requestCode: Int): Boolean
+    private external fun nativeOpenCamera(activity: Activity): Boolean
+    private external fun nativePickImage(activity: Activity): Boolean
+    private external fun nativePickFile(activity: Activity): Boolean
+    private external fun nativeStartVideoRecording(activity: Activity): Boolean
+    private external fun nativeReviewSucceeded()
+    private external fun nativeReviewError(message: String)
+    private external fun nativeRequestReview(activity: Activity): Boolean
+    private external fun nativeSpeechReady(activity: Activity)
+    private external fun nativeSpeechError(activity: Activity, error: Int)
+    private external fun nativeSpeechResult(activity: Activity, transcript: String, isFinal: Boolean)
+    private external fun nativeStartListening(activity: Activity, available: Boolean): Boolean
+    private external fun nativeStopListening(activity: Activity): Boolean
+    private external fun nativeAudioStarted()
+    private external fun nativeAudioStartError(message: String)
+    private external fun nativeAudioStopped(bytes: ByteArray)
+    private external fun nativeAudioStopError(message: String)
+    private external fun nativeStartAudioRecording(activity: Activity): Boolean
+    private external fun nativeStopAudioRecording(activity: Activity): Boolean
+    private external fun nativeResetDeepLinks(): Boolean
+    private external fun nativeSetInitialURL(url: String?): Boolean
+    private external fun nativeGetInitialURL(): Boolean
+    private external fun nativeDispatchDeepLink(url: String, initial: Boolean): Boolean
+    private external fun nativeScreenshotReady(bytes: ByteArray)
+    private external fun nativeScreenshotError(message: String)
+    private external fun nativeTakeScreenshot(activity: Activity, webView: WebView): Boolean
+    private external fun nativeProductsReady(productsJson: String)
+    private external fun nativeProductsError(message: String)
+    private external fun nativeRestoreReady(purchasesJson: String)
+    private external fun nativeRestoreError(message: String)
+    private external fun nativeGetProducts(activity: Activity, productIdsJson: String): Boolean
+    private external fun nativeRestorePurchases(activity: Activity): Boolean
+    private external fun nativeMlReady(resultsJson: String)
+    private external fun nativeMlError(message: String)
+    private external fun nativeClassifyImage(imageBase64: String): Boolean
+    private external fun nativeDetectObjects(imageBase64: String): Boolean
+    private external fun nativeRecognizeText(imageBase64: String): Boolean
+    private external fun nativePdfOpened()
+    private external fun nativePdfError(message: String)
+    private external fun nativeOpenPDF(activity: Activity, source: String, page: Int): Boolean
+    private external fun nativeBiometricSucceeded()
+    private external fun nativeBiometricError(message: String)
+    private external fun nativeAuthenticate(activity: Activity, reason: String, supported: Boolean): Boolean
+    private external fun nativeGetNetworkStatus(activity: Activity): String?
+    private external fun nativeSecureSet(prefs: SharedPreferences, key: String, value: String): Boolean
+    private external fun nativeSecureGet(prefs: SharedPreferences, key: String): String?
+    private external fun nativeSecureRemove(prefs: SharedPreferences, key: String): Boolean
+    private external fun nativeSecureClear(prefs: SharedPreferences): Boolean
+    private external fun nativeHaptic(activity: Activity, style: String): Boolean
+    private external fun nativeVibrate(activity: Activity, patternJson: String): Boolean
+    private external fun nativeCancelNotification(activity: Activity, id: String): Boolean
+    private external fun nativeCancelAllNotifications(activity: Activity): Boolean
+    private external fun nativeDeleteCalendarEvent(activity: Activity, eventId: String): Boolean
+    private external fun nativeGetCalendarEvents(activity: Activity, startDateMs: Long, endDateMs: Long): Boolean
+    private external fun nativeCreateCalendarEvent(activity: Activity, eventJson: String): Boolean
+    private external fun nativeDbExecute(database: SQLiteDatabase, sql: String, paramsJson: String): Boolean
+    private external fun nativeDbQuery(database: SQLiteDatabase, sql: String, paramsJson: String): Boolean
+    private external fun nativeSetSharedItem(activity: Activity, key: String, value: String, group: String): Boolean
+    private external fun nativeGetSharedItem(activity: Activity, key: String, group: String): Boolean
+    private external fun nativeRemoveSharedItem(activity: Activity, key: String, group: String): Boolean
+    private external fun nativeGetContacts(activity: Activity): Boolean
+    private external fun nativeAddContact(activity: Activity, contactJson: String): Boolean
+    private external fun nativePickContact(activity: Activity): Boolean
+    private external fun nativeUpdateWidget(activity: Activity, action: String, dataJson: String): Boolean
+    private external fun nativeReloadWidgets(activity: Activity, action: String): Boolean
+    private external fun nativeSetShortcuts(activity: Activity, shortcutsJson: String): Boolean
+    private external fun nativeClearShortcuts(activity: Activity): Boolean
+    private external fun nativeScheduleNotification(activity: Activity, notificationJson: String): Boolean
+    private external fun nativeRunTask(activity: Activity, token: Long)
+    private external fun nativeCancelTask(token: Long)
+    private external fun nativeLockOrientation(activity: Activity, orientation: String): Boolean
+    private external fun nativeUnlockOrientation(activity: Activity): Boolean
+    private external fun nativeSetKeepAwake(activity: Activity, enabled: Boolean): Boolean
+    private external fun nativeDownloadFile(activity: Activity, url: String, filename: String): Boolean
+    private external fun nativeSaveFile(activity: Activity, data: String, filename: String): Boolean
+    private external fun nativeGetLocationRecordingState(activity: Activity): String?
+    private external fun nativeReadLocationRecording(activity: Activity): String?
+    private external fun nativeStartLocationRecording(activity: Activity): String?
+    private external fun nativeStopLocationRecording(activity: Activity): String?
+    private external fun nativePauseLocationRecording(activity: Activity): String?
+    private external fun nativeResumeLocationRecording(activity: Activity): String?
+    private external fun nativeNetworkChanged(activity: Activity)
+    private external fun nativeStartNetworkMonitoring(activity: Activity): Boolean
+    private external fun nativeStopNetworkMonitoring(activity: Activity): Boolean
+    private external fun nativeAppStateEvent(eventName: String)
+    private external fun nativeStartAppStateMonitoring(activity: Activity): Boolean
+    private external fun nativeStopAppStateMonitoring(activity: Activity): Boolean
+    private external fun nativeGetAppState(): String?
+    private external fun nativeBluetoothDevice(address: String, name: String?, rssi: Int)
+    private external fun nativeStartBluetoothScan(activity: Activity): Boolean
+    private external fun nativeStopBluetoothScan(activity: Activity): Boolean
+    private external fun nativeMotionSample(isAccelerometer: Boolean, x: Float, y: Float, z: Float)
+    private external fun nativeStartMotionUpdates(activity: Activity, intervalMs: Int): Boolean
+    private external fun nativeStopMotionUpdates(activity: Activity): Boolean
+    private external fun nativeLocationResult(
+        latitude: Double,
+        longitude: Double,
+        accuracy: Double,
+        altitude: Double,
+        speed: Double,
+        bearing: Double,
+        time: Long
+    )
+    private external fun nativeLocationFailed(message: String?)
+    private external fun nativeGetCurrentPosition(activity: Activity): Boolean
+
+    /**
+     * `getDeviceInfo`, or null to use the Kotlin implementation.
+     *
+     * The catch is not belt-and-braces. The library can load while
+     * `JNI_OnLoad` still fails to bind — a missing class, a signature that
+     * does not match — and an unbound `external fun` throws
+     * `UnsatisfiedLinkError` at the call rather than at load. Turning that
+     * into null is what keeps a half-registered runtime behaving like no
+     * runtime at all.
+     */
+    fun getDeviceInfo(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeGetDeviceInfo(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    /** The JVM heap as JSON, or null to use the Kotlin implementation. */
+    fun getMemoryUsage(): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeGetMemoryUsage()
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    /**
+     * Write a log line, reporting whether it was written.
+     *
+     * The only native here that answers with a boolean rather than a nullable
+     * result, because there is no value to return and "not mine" still has to
+     * be sayable — a void native would leave the caller unable to tell a
+     * written line from a declined one, and it would log twice or not at all.
+     */
+    fun log(message: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeLog(message)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * The clipboard's text, or null to use the Kotlin implementation.
+     *
+     * Null and `""` are different answers and both are normal: null means Zig
+     * did not serve this call, `""` means the clipboard is empty — which since
+     * Android 10 is what an app without focus sees every time. Collapsing them
+     * would make an empty clipboard fall through and be read twice.
+     */
+    fun clipboardRead(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeClipboardRead(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    /** Returns whether Zig wrote the clipboard; false falls through. */
+    fun clipboardWrite(activity: Activity, text: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeClipboardWrite(activity, text)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig opened the URL.
+     *
+     * False is ambiguous here in a way it is not elsewhere: it covers both
+     * "Zig did not serve this" and "nothing on the device handles that
+     * scheme". Both lead to the same place — the Kotlin runs its own
+     * implementation and answers false for the second reason itself — so the
+     * ambiguity costs nothing and a richer return would have to be unpacked
+     * at every call site to reach the same outcome.
+     */
+    fun openURL(activity: Activity, url: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeOpenUrl(activity, url)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig launched the share menu for a result; false falls
+     * through. `chosen` fires on a pick and `requestCode` routes the result
+     * back to CraftBridge, which settles the page's promise from the two.
+     */
+    fun share(activity: Activity, text: String, title: String, chosen: IntentSender, requestCode: Int): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeShare(activity, text, title, chosen, requestCode)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Launch the camera; its result is still decoded by CraftBridge. */
+    fun openCamera(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeOpenCamera(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Launch the system image picker; CraftBridge owns the result callback. */
+    fun pickImage(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativePickImage(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun pickFile(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativePickFile(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun startVideoRecording(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStartVideoRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    // ==================== In-app review ====================
+    //
+    // Play Core's Task listeners are Java objects and remain here. Every
+    // observable outcome crosses back into Zig; completing the launched flow
+    // resolves regardless of whether Google Play displayed a review card.
+
+    @JvmStatic
+    fun startReviewFlow(activity: Activity) {
+        val requestGeneration = lifecycleGeneration.get()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+
+        fun resolveReviewRequest() {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            try {
+                nativeReviewSucceeded()
+            } catch (e: UnsatisfiedLinkError) {
+                // The library went away while Play owned the flow.
+            }
+        }
+
+        fun rejectReviewRequest(message: String) {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            try {
+                nativeReviewError(message)
+            } catch (e: UnsatisfiedLinkError) {
+            }
+        }
+
+        try {
+            val reviewManager = ReviewManagerFactory.create(activity)
+            val request = reviewManager.requestReviewFlow()
+
+            request.addOnCompleteListener { task ->
+                if (task.isSuccessful) {
+                    try {
+                        reviewManager.launchReviewFlow(activity, task.result)
+                            .addOnCompleteListener { resolveReviewRequest() }
+                    } catch (error: Exception) {
+                        rejectReviewRequest(error.message ?: "Review flow failed")
+                    }
+                } else {
+                    rejectReviewRequest(task.exception?.message ?: "Review flow failed")
+                }
+            }
+        } catch (error: Exception) {
+            rejectReviewRequest(error.message ?: "Review flow failed")
+        }
+    }
+
+    fun requestReview(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeRequestReview(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    // ==================== Speech recognition ====================
+    //
+    // SpeechRecognizer is main-thread-only and RecognitionListener is a Java
+    // interface. The holder owns both; callbacks hand only stable values back
+    // to Zig, which owns every event and haptic decision.
+
+    private var speechRecognizer: SpeechRecognizer? = null
+
+    @JvmStatic
+    fun beginSpeechRecognition(activity: Activity) {
+        activity.runOnUiThread {
+            if (ContextCompat.checkSelfPermission(activity, Manifest.permission.RECORD_AUDIO)
+                != PackageManager.PERMISSION_GRANTED) {
+                ActivityCompat.requestPermissions(activity, arrayOf(Manifest.permission.RECORD_AUDIO), 100)
+                return@runOnUiThread
+            }
+
+            speechRecognizer = SpeechRecognizer.createSpeechRecognizer(activity)
+            speechRecognizer?.setRecognitionListener(object : RecognitionListener {
+                override fun onReadyForSpeech(params: Bundle?) {
+                    try {
+                        nativeSpeechReady(activity)
+                    } catch (e: UnsatisfiedLinkError) {
+                    }
+                }
+
+                override fun onBeginningOfSpeech() {}
+                override fun onRmsChanged(rmsdB: Float) {}
+                override fun onBufferReceived(buffer: ByteArray?) {}
+                override fun onEndOfSpeech() {}
+
+                override fun onError(error: Int) {
+                    try {
+                        nativeSpeechError(activity, error)
+                    } catch (e: UnsatisfiedLinkError) {
+                    }
+                }
+
+                override fun onResults(results: Bundle?) {
+                    val matches = results?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
+                    try {
+                        nativeSpeechResult(activity, matches?.firstOrNull() ?: "", true)
+                    } catch (e: UnsatisfiedLinkError) {
+                    }
+                }
+
+                override fun onPartialResults(partialResults: Bundle?) {
+                    val matches = partialResults?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
+                    try {
+                        nativeSpeechResult(activity, matches?.firstOrNull() ?: "", false)
+                    } catch (e: UnsatisfiedLinkError) {
+                    }
+                }
+
+                override fun onEvent(eventType: Int, params: Bundle?) {}
+            })
+
+            val intent = Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
+                putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, RecognizerIntent.LANGUAGE_MODEL_FREE_FORM)
+                putExtra(RecognizerIntent.EXTRA_LANGUAGE, Locale.getDefault())
+                putExtra(RecognizerIntent.EXTRA_PARTIAL_RESULTS, true)
+                putExtra(RecognizerIntent.EXTRA_MAX_RESULTS, 1)
+            }
+            speechRecognizer?.startListening(intent)
+        }
+    }
+
+    @JvmStatic
+    fun endSpeechRecognition(activity: Activity) {
+        activity.runOnUiThread {
+            speechRecognizer?.stopListening()
+            speechRecognizer?.destroy()
+            speechRecognizer = null
+        }
+    }
+
+    fun startListening(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStartListening(activity, SpeechRecognizer.isRecognitionAvailable(activity))
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun stopListening(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStopListening(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    // ==================== Audio recording ====================
+    //
+    // The long-lived Java objects stay here. Zig owns permission handling and
+    // all four promise outcomes, including encoding the bytes returned on stop.
+
+    private var audioRecorder: MediaRecorder? = null
+    private var audioFile: File? = null
+
+    @JvmStatic
+    fun beginAudioRecording(activity: Activity) {
+        try {
+            audioFile = File.createTempFile("recording_", ".m4a", activity.cacheDir)
+            audioRecorder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                MediaRecorder(activity)
+            } else {
+                @Suppress("DEPRECATION")
+                MediaRecorder()
+            }
+
+            audioRecorder?.apply {
+                setAudioSource(MediaRecorder.AudioSource.MIC)
+                setOutputFormat(MediaRecorder.OutputFormat.MPEG_4)
+                setAudioEncoder(MediaRecorder.AudioEncoder.AAC)
+                setOutputFile(audioFile?.absolutePath)
+                prepare()
+                start()
+            }
+            nativeAudioStarted()
+        } catch (e: Exception) {
+            nativeAudioStartError(e.message ?: "null")
+        }
+    }
+
+    @JvmStatic
+    fun endAudioRecording() {
+        try {
+            audioRecorder?.stop()
+            audioRecorder?.release()
+            audioRecorder = null
+
+            val file = audioFile
+            if (file != null) {
+                nativeAudioStopped(file.readBytes())
+            } else {
+                nativeAudioStopError("No recording")
+            }
+        } catch (e: Exception) {
+            nativeAudioStopError(e.message ?: "null")
+        }
+    }
+
+    fun startAudioRecording(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStartAudioRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun stopAudioRecording(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStopAudioRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun resetDeepLinks(): Boolean {
+        if (!isAvailable) return false
+        return try { nativeResetDeepLinks() } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    fun setInitialURL(url: String?): Boolean {
+        if (!isAvailable) return false
+        return try { nativeSetInitialURL(url) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    fun getInitialURL(): Boolean {
+        if (!isAvailable) return false
+        return try { nativeGetInitialURL() } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    fun dispatchDeepLink(url: String, initial: Boolean): Boolean {
+        if (!isAvailable) return false
+        return try { nativeDispatchDeepLink(url, initial) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    @JvmStatic
+    fun captureScreenshot(activity: Activity, webView: WebView) {
+        val requestGeneration = lifecycleGeneration.get()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+
+        fun resolveScreenshotRequest(bytes: ByteArray) {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            nativeScreenshotReady(bytes)
+        }
+
+        fun rejectScreenshotRequest(message: String) {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            nativeScreenshotError(message)
+        }
+
+        activity.runOnUiThread {
+            if (requestGeneration != lifecycleGeneration.get()) return@runOnUiThread
+            try {
+                val view = webView.rootView
+                val bitmap = try {
+                    view.isDrawingCacheEnabled = true
+                    view.buildDrawingCache()
+                    Bitmap.createBitmap(view.drawingCache)
+                } finally {
+                    view.isDrawingCacheEnabled = false
+                }
+
+                val outputStream = ByteArrayOutputStream()
+                bitmap.compress(Bitmap.CompressFormat.PNG, 100, outputStream)
+                resolveScreenshotRequest(outputStream.toByteArray())
+            } catch (e: Exception) {
+                rejectScreenshotRequest(e.message ?: "Screenshot failed")
+            }
+        }
+    }
+
+    fun takeScreenshot(activity: Activity, webView: WebView): Boolean {
+        if (!isAvailable) return false
+        return try { nativeTakeScreenshot(activity, webView) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    // ==================== Play Billing ====================
+
+    private var productBillingClient: BillingClient? = null
+    private var restoreBillingClient: BillingClient? = null
+
+    @JvmStatic
+    fun queryProducts(activity: Activity, productIdsJson: String) {
+        val requestGeneration = lifecycleGeneration.get()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+
+        fun resolveProductRequest(productsJson: String) {
+            if (!settled.compareAndSet(false, true)) return
+            if (requestGeneration != lifecycleGeneration.get()) return
+            nativeProductsReady(productsJson)
+        }
+
+        fun rejectProductRequest(message: String) {
+            if (!settled.compareAndSet(false, true)) return
+            if (requestGeneration != lifecycleGeneration.get()) return
+            nativeProductsError(message)
+        }
+
+        try {
+            val productIds = org.json.JSONArray(productIdsJson)
+            val productList = mutableListOf<String>()
+            for (i in 0 until productIds.length()) productList.add(productIds.getString(i))
+
+            runCatching { productBillingClient?.endConnection() }
+            val client = BillingClient.newBuilder(activity)
+                .setListener { _, _ -> }
+                .enablePendingPurchases()
+                .build()
+            productBillingClient = client
+
+            client.startConnection(object : BillingClientStateListener {
+                override fun onBillingSetupFinished(billingResult: BillingResult) {
+                    if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
+                        val params = QueryProductDetailsParams.newBuilder()
+                            .setProductList(productList.map { productId ->
+                                QueryProductDetailsParams.Product.newBuilder()
+                                    .setProductId(productId)
+                                    .setProductType(BillingClient.ProductType.INAPP)
+                                    .build()
+                            })
+                            .build()
+
+                        try {
+                            client.queryProductDetailsAsync(params) { result, detailsList ->
+                                if (result.responseCode == BillingClient.BillingResponseCode.OK) {
+                                    val products = org.json.JSONArray()
+                                    detailsList.forEach { details ->
+                                        products.put(JSONObject().apply {
+                                            put("id", details.productId)
+                                            put("title", details.name)
+                                            put("displayName", details.name)
+                                            put("description", details.description)
+                                            put("price", details.oneTimePurchaseOfferDetails?.formattedPrice ?: "")
+                                        })
+                                    }
+                                    resolveProductRequest(products.toString())
+                                } else {
+                                    rejectProductRequest("Product query failed: ${result.debugMessage}")
+                                }
+                            }
+                        } catch (error: Exception) {
+                            rejectProductRequest(error.message ?: "Product query failed")
+                        }
+                    } else {
+                        rejectProductRequest("Billing setup failed: ${billingResult.debugMessage}")
+                    }
+                }
+
+                override fun onBillingServiceDisconnected() {
+                    rejectProductRequest("Billing disconnected")
+                }
+            })
+        } catch (e: Exception) {
+            rejectProductRequest(e.message ?: "Product query failed")
+        }
+    }
+
+    @JvmStatic
+    fun queryRestoredPurchases(activity: Activity) {
+        val requestGeneration = lifecycleGeneration.get()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+
+        fun resolveRestoreRequest(purchasesJson: String) {
+            if (!settled.compareAndSet(false, true)) return
+            if (requestGeneration != lifecycleGeneration.get()) return
+            nativeRestoreReady(purchasesJson)
+        }
+
+        fun rejectRestoreRequest(message: String) {
+            if (!settled.compareAndSet(false, true)) return
+            if (requestGeneration != lifecycleGeneration.get()) return
+            nativeRestoreError(message)
+        }
+
+        val connectedClient = restoreBillingClient
+        if (connectedClient != null && connectedClient.isReady) {
+            queryRestoredPurchases(connectedClient, ::resolveRestoreRequest, ::rejectRestoreRequest)
+            return
+        }
+
+        try {
+            val client = connectedClient ?: BillingClient.newBuilder(activity)
+                .setListener { _, _ -> }
+                .enablePendingPurchases()
+                .build()
+                .also { restoreBillingClient = it }
+
+            client.startConnection(object : BillingClientStateListener {
+                override fun onBillingSetupFinished(billingResult: BillingResult) {
+                    if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
+                        queryRestoredPurchases(client, ::resolveRestoreRequest, ::rejectRestoreRequest)
+                    } else {
+                        rejectRestoreRequest("Billing setup failed: ${billingResult.debugMessage}")
+                    }
+                }
+
+                override fun onBillingServiceDisconnected() {
+                    rejectRestoreRequest("Billing disconnected")
+                }
+            })
+        } catch (error: Exception) {
+            rejectRestoreRequest(error.message ?: "Billing connection failed")
+        }
+    }
+
+    private fun queryRestoredPurchases(
+        client: BillingClient,
+        resolve: (String) -> Unit,
+        reject: (String) -> Unit
+    ) {
+        try {
+            client.queryPurchasesAsync(
+                QueryPurchasesParams.newBuilder().setProductType(BillingClient.ProductType.INAPP).build()
+            ) { result, purchases ->
+                if (result.responseCode == BillingClient.BillingResponseCode.OK) {
+                    val restored = org.json.JSONArray()
+                    purchases.forEach { purchase ->
+                        restored.put(JSONObject().apply {
+                            put("productId", purchase.products.firstOrNull())
+                            put("orderId", purchase.orderId)
+                        })
+                    }
+                    resolve(restored.toString())
+                } else {
+                    reject("Restore failed: ${result.debugMessage}")
+                }
+            }
+        } catch (error: Exception) {
+            reject(error.message ?: "Restore failed")
+        }
+    }
+
+    fun getProducts(activity: Activity, productIdsJson: String): Boolean {
+        if (!isAvailable) return false
+        return try { nativeGetProducts(activity, productIdsJson) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    fun restorePurchases(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try { nativeRestorePurchases(activity) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    // ==================== ML Kit ====================
+
+    private fun createMlSettlement(): Pair<(String) -> Unit, (String) -> Unit> {
+        val requestGeneration = lifecycleGeneration.get()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+        val resolve: (String) -> Unit = { resultsJson ->
+            if (requestGeneration == lifecycleGeneration.get() && settled.compareAndSet(false, true)) {
+                nativeMlReady(resultsJson)
+            }
+        }
+        val reject: (String) -> Unit = { message ->
+            if (requestGeneration == lifecycleGeneration.get() && settled.compareAndSet(false, true)) {
+                nativeMlError(message)
+            }
+        }
+        return resolve to reject
+    }
+
+    @JvmStatic
+    fun runImageClassification(imageBase64: String) {
+        val (resolve, reject) = createMlSettlement()
+        try {
+            val imageBytes = Base64.decode(imageBase64, Base64.DEFAULT)
+            val bitmap = BitmapFactory.decodeByteArray(imageBytes, 0, imageBytes.size)
+            val inputImage = InputImage.fromBitmap(bitmap, 0)
+            val labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS)
+            labeler.process(inputImage)
+                .addOnSuccessListener { labels ->
+                    try {
+                        val results = JSONArray()
+                        for (label in labels) {
+                            results.put(JSONObject().apply {
+                                put("label", label.text)
+                                put("confidence", label.confidence)
+                                put("index", label.index)
+                            })
+                        }
+                        resolve(results.toString())
+                    } catch (error: Exception) {
+                        reject(error.message ?: "Image classification failed")
+                    }
+                }
+                .addOnFailureListener { error -> reject(error.message ?: "Image classification failed") }
+                .addOnCompleteListener { labeler.close() }
+        } catch (e: Exception) {
+            reject(e.message ?: "Image classification failed")
+        }
+    }
+
+    @JvmStatic
+    fun runObjectDetection(imageBase64: String) {
+        val (resolve, reject) = createMlSettlement()
+        try {
+            val imageBytes = Base64.decode(imageBase64, Base64.DEFAULT)
+            val bitmap = BitmapFactory.decodeByteArray(imageBytes, 0, imageBytes.size)
+            val inputImage = InputImage.fromBitmap(bitmap, 0)
+            val options = ObjectDetectorOptions.Builder()
+                .setDetectorMode(ObjectDetectorOptions.SINGLE_IMAGE_MODE)
+                .enableMultipleObjects()
+                .enableClassification()
+                .build()
+
+            val detector = ObjectDetection.getClient(options)
+            detector.process(inputImage)
+                .addOnSuccessListener { detectedObjects ->
+                    try {
+                        val results = JSONArray()
+                        for (obj in detectedObjects) {
+                            val objJson = JSONObject()
+                            objJson.put("boundingBox", JSONObject().apply {
+                                put("x", obj.boundingBox.left)
+                                put("y", obj.boundingBox.top)
+                                put("width", obj.boundingBox.width())
+                                put("height", obj.boundingBox.height())
+                            })
+                            val labels = JSONArray()
+                            for (label in obj.labels) {
+                                labels.put(JSONObject().apply {
+                                    put("label", label.text)
+                                    put("confidence", label.confidence)
+                                    put("index", label.index)
+                                })
+                            }
+                            objJson.put("labels", labels)
+                            objJson.put("trackingId", obj.trackingId)
+                            results.put(objJson)
+                        }
+                        resolve(results.toString())
+                    } catch (error: Exception) {
+                        reject(error.message ?: "Object detection failed")
+                    }
+                }
+                .addOnFailureListener { error -> reject(error.message ?: "Object detection failed") }
+                .addOnCompleteListener { detector.close() }
+        } catch (e: Exception) {
+            reject(e.message ?: "Object detection failed")
+        }
+    }
+
+    @JvmStatic
+    fun runTextRecognition(imageBase64: String) {
+        val (resolve, reject) = createMlSettlement()
+        try {
+            val imageBytes = Base64.decode(imageBase64, Base64.DEFAULT)
+            val bitmap = BitmapFactory.decodeByteArray(imageBytes, 0, imageBytes.size)
+            val inputImage = InputImage.fromBitmap(bitmap, 0)
+            val recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)
+            recognizer.process(inputImage)
+                .addOnSuccessListener { visionText ->
+                    try {
+                        val results = JSONArray()
+                        for (block in visionText.textBlocks) {
+                            for (line in block.lines) {
+                                val lineJson = JSONObject()
+                                lineJson.put("text", line.text)
+                                lineJson.put("confidence", line.confidence ?: 0.0)
+                                line.boundingBox?.let { box ->
+                                    lineJson.put("boundingBox", JSONObject().apply {
+                                        put("x", box.left)
+                                        put("y", box.top)
+                                        put("width", box.width())
+                                        put("height", box.height())
+                                    })
+                                }
+                                results.put(lineJson)
+                            }
+                        }
+                        resolve(results.toString())
+                    } catch (error: Exception) {
+                        reject(error.message ?: "Text recognition failed")
+                    }
+                }
+                .addOnFailureListener { error -> reject(error.message ?: "Text recognition failed") }
+                .addOnCompleteListener { recognizer.close() }
+        } catch (e: Exception) {
+            reject(e.message ?: "Text recognition failed")
+        }
+    }
+
+    fun classifyImage(imageBase64: String): Boolean {
+        if (!isAvailable) return false
+        return try { nativeClassifyImage(imageBase64) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    fun detectObjects(imageBase64: String): Boolean {
+        if (!isAvailable) return false
+        return try { nativeDetectObjects(imageBase64) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    fun recognizeText(imageBase64: String): Boolean {
+        if (!isAvailable) return false
+        return try { nativeRecognizeText(imageBase64) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    // ==================== External PDF viewer ====================
+
+    @JvmStatic
+    fun openPdfExternal(activity: Activity, source: String) {
+        val requestGeneration = lifecycleGeneration.get()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+
+        fun resolvePdfRequest() {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            nativePdfOpened()
+        }
+
+        fun rejectPdfRequest(message: String) {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            nativePdfError(message)
+        }
+
+        activity.runOnUiThread {
+            if (requestGeneration != lifecycleGeneration.get()) return@runOnUiThread
+            try {
+                val uri = if (source.startsWith("data:")) {
+                    val base64Data = source.substringAfter(",")
+                    val bytes = Base64.decode(base64Data, Base64.DEFAULT)
+                    val tempFile = File.createTempFile("craft_pdf_", ".pdf", activity.cacheDir)
+                    tempFile.writeBytes(bytes)
+                    android.net.Uri.fromFile(tempFile)
+                } else {
+                    android.net.Uri.parse(source)
+                }
+
+                val intent = Intent(Intent.ACTION_VIEW).apply {
+                    setDataAndType(uri, "application/pdf")
+                    addFlags(Intent.FLAG_ACTIVITY_NO_HISTORY)
+                    addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+                }
+                activity.startActivity(intent)
+                resolvePdfRequest()
+            } catch (e: Exception) {
+                rejectPdfRequest(e.message ?: "PDF could not be opened")
+            }
+        }
+    }
+
+    fun openPDF(activity: Activity, source: String, page: Int): Boolean {
+        if (!isAvailable) return false
+        return try { nativeOpenPDF(activity, source, page) } catch (e: UnsatisfiedLinkError) { false }
+    }
+
+    // ==================== Biometric authentication ====================
+    //
+    // AuthenticationCallback is an abstract Java class and the prompt must be
+    // presented on the main thread. Those two Java-shaped pieces stay here;
+    // the decision and both promise payloads are Zig's.
+
+    @JvmStatic
+    fun showBiometricPrompt(activity: Activity, reason: String) {
+        val requestGeneration = lifecycleGeneration.get()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+
+        fun resolveBiometricRequest() {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            biometricPrompt = null
+            try {
+                nativeBiometricSucceeded()
+            } catch (e: UnsatisfiedLinkError) {
+                // The library went away while the prompt was open.
+            }
+        }
+
+        fun rejectBiometricRequest(message: String) {
+            if (requestGeneration != lifecycleGeneration.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            biometricPrompt = null
+            try {
+                nativeBiometricError(message)
+            } catch (e: UnsatisfiedLinkError) {
+            }
+        }
+
+        activity.runOnUiThread {
+            if (requestGeneration != lifecycleGeneration.get()) return@runOnUiThread
+            try {
+                val promptInfo = BiometricPrompt.PromptInfo.Builder()
+                    .setTitle("Authenticate")
+                    .setSubtitle(reason)
+                    .setNegativeButtonText("Cancel")
+                    .setAllowedAuthenticators(BiometricManager.Authenticators.BIOMETRIC_STRONG)
+                    .build()
+
+                runCatching { biometricPrompt?.cancelAuthentication() }
+                val prompt = BiometricPrompt(
+                    activity as FragmentActivity,
+                    ContextCompat.getMainExecutor(activity),
+                    object : BiometricPrompt.AuthenticationCallback() {
+                        override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+                            resolveBiometricRequest()
+                        }
+
+                        override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+                            rejectBiometricRequest(errString.toString())
+                        }
+
+                        override fun onAuthenticationFailed() {
+                            // Do not reject: the prompt remains open for a retry.
+                        }
+                    }
+                )
+                biometricPrompt = prompt
+                prompt.authenticate(promptInfo)
+            } catch (error: Exception) {
+                rejectBiometricRequest(error.message ?: "Biometric authentication failed")
+            }
+        }
+    }
+
+    fun authenticate(activity: Activity, reason: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            // Kotlin can observe this type without a reflective class lookup;
+            // Zig owns what the unsupported case means to the page.
+            nativeAuthenticate(activity, reason, activity is FragmentActivity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** The active network as JSON, or null to use the Kotlin implementation. */
+    fun getNetworkStatus(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeGetNetworkStatus(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    /**
+     * The three answers a secure read can give.
+     *
+     * `secureGet` returns `String?` to the page, where null means "no such
+     * key". The seam needs to say "Zig did not serve this" as well, and a
+     * nullable String cannot carry both — an absent key and a declined call
+     * lead to different code. There is no spare value to steal either: `""` is
+     * a legitimate stored value, and so is any sentinel a caller could have
+     * saved.
+     */
+    sealed class SecureRead {
+        /** Zig did not serve the call; run the Kotlin implementation. */
+        object Declined : SecureRead()
+
+        /** Zig served it and the key is not present. */
+        object NotFound : SecureRead()
+
+        /** Zig served it and the key holds [value], which may be empty. */
+        data class Found(val value: String) : SecureRead()
+    }
+
+    fun secureSet(prefs: SharedPreferences, key: String, value: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeSecureSet(prefs, key, value)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun secureGet(prefs: SharedPreferences, key: String): SecureRead {
+        if (!isAvailable) return SecureRead.Declined
+        val envelope = try {
+            nativeSecureGet(prefs, key)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        } ?: return SecureRead.Declined
+
+        // A malformed envelope is Zig's bug, and declining is the safe answer:
+        // the Kotlin then reads the store itself and the page sees the truth.
+        return try {
+            val json = JSONObject(envelope)
+            if (json.getBoolean("found")) SecureRead.Found(json.getString("value"))
+            else SecureRead.NotFound
+        } catch (e: Exception) {
+            SecureRead.Declined
+        }
+    }
+
+    fun secureRemove(prefs: SharedPreferences, key: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeSecureRemove(prefs, key)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun secureClear(prefs: SharedPreferences): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeSecureClear(prefs)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Returns whether Zig played the haptic; false falls through. */
+    fun haptic(activity: Activity, style: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeHaptic(activity, style)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig played the pattern.
+     *
+     * False also covers a pattern Zig could not parse — deliberately, so the
+     * Kotlin runs, throws the JSONException it would have thrown anyway, and
+     * writes its "Vibration error" line. Handling it here would reach the same
+     * silence and lose the log.
+     */
+    fun vibrate(activity: Activity, patternJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeVibrate(activity, patternJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Returns whether Zig cancelled it; false falls through. */
+    fun cancelNotification(activity: Activity, id: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeCancelNotification(activity, id)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Returns whether Zig cancelled them all; false falls through. */
+    fun cancelAllNotifications(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeCancelAllNotifications(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig *took* the action, not whether the delete worked.
+     *
+     * The first native here that answers asynchronously: the outcome reaches
+     * the page through the reply channel, so true means "do not also run the
+     * Kotlin" and nothing more. Running both would settle the promise twice.
+     */
+    fun deleteCalendarEvent(activity: Activity, eventId: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeDeleteCalendarEvent(activity, eventId)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig took the action, not whether the read found anything.
+     *
+     * An empty calendar still answers — with `[]`, through the reply channel —
+     * so a false here means Zig did not run, never that there was nothing to
+     * report.
+     */
+    fun getCalendarEvents(activity: Activity, startDateMs: Long, endDateMs: Long): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeGetCalendarEvents(activity, startDateMs, endDateMs)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig took the action.
+     *
+     * A false here is routine rather than exceptional: Zig serves the shape
+     * `NewCalendarEvent` declares and hands anything else back, because
+     * `org.json` coerces where a strict parser refuses. The Kotlin below is
+     * what answers those.
+     */
+    fun createCalendarEvent(activity: Activity, eventJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeCreateCalendarEvent(activity, eventJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig took the statement.
+     *
+     * The connection is passed in rather than opened: the Kotlin caches one
+     * `SQLiteDatabase` so that a BEGIN in one call and a COMMIT in the next
+     * reach the same connection, and a second one opened by Zig would take
+     * locks against the first for no visible reason.
+     */
+    fun dbExecute(database: SQLiteDatabase, sql: String, paramsJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeDbExecute(database, sql, paramsJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** The same, for a statement that returns rows. */
+    fun dbQuery(database: SQLiteDatabase, sql: String, paramsJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeDbQuery(database, sql, paramsJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * The shared-preferences trio behind the page's `_craftSharedKeychain*`
+     * globals. Each returns whether Zig took the action; the outcome reaches
+     * the page through the reply channel.
+     */
+    fun setSharedItem(activity: Activity, key: String, value: String, group: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeSetSharedItem(activity, key, value, group)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun getSharedItem(activity: Activity, key: String, group: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeGetSharedItem(activity, key, group)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun removeSharedItem(activity: Activity, key: String, group: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeRemoveSharedItem(activity, key, group)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig took the read, not whether it found anyone.
+     *
+     * An empty address book still answers — with `[]`, through the reply
+     * channel — so a false here means Zig did not run.
+     */
+    fun getContacts(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeGetContacts(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig took the write.
+     *
+     * A false is routine rather than exceptional: Zig serves the shape the
+     * page's own SDK sends and hands anything else back, because `org.json`
+     * coerces where a strict parser refuses.
+     */
+    fun addContact(activity: Activity, contactJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeAddContact(activity, contactJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Launches the single-contact picker on the main looper. */
+    fun pickContact(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativePickContact(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * The widget pair. `action` is the caller's own broadcast constant.
+     *
+     * Zig could build it from `activity.packageName`, and today that is the
+     * same string — but an `applicationIdSuffix` on a build type would move
+     * the package name and leave the constant where it was, and the widget
+     * would silently stop updating. Only one side gets to decide.
+     */
+    fun updateWidget(activity: Activity, action: String, dataJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeUpdateWidget(activity, action, dataJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun reloadWidgets(activity: Activity, action: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeReloadWidgets(activity, action)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * The launcher's long-press menu.
+     *
+     * Both handle the pre-25 case themselves, and asymmetrically, because the
+     * Kotlin does: setting rejects with a message and clearing resolves true.
+     */
+    fun setShortcuts(activity: Activity, shortcutsJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeSetShortcuts(activity, shortcutsJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun clearShortcuts(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeClearShortcuts(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * Returns whether Zig posted the notification.
+     *
+     * A false is routine on one path in particular: a `delay` above zero needs
+     * `Handler.postDelayed`, and Zig cannot make a `Runnable`. It hands those
+     * back before creating the channel, so the Kotlin below does the whole
+     * thing rather than half of it twice.
+     */
+    fun scheduleNotification(activity: Activity, notificationJson: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeScheduleNotification(activity, notificationJson)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * How Zig reaches the main looper.
+     *
+     * `Window.addFlags` and `setRequestedOrientation` have to run there, and
+     * the shim wraps each in `runOnUiThread { ... }` — which takes a
+     * `Runnable`, a Java object implementing a Java interface. JNI cannot make
+     * one: `RegisterNatives` binds methods onto a class that already exists in
+     * the APK, so a native can be *called* from Java but cannot be handed to
+     * Java as an object.
+     *
+     * So the `Runnable` is here, the work is there, and a token says which
+     * work. The Activity goes across with it rather than being held by Zig
+     * over the hop, which is what would need a global reference and a matching
+     * release.
+     *
+     * Called from Zig, never from the Kotlin below.
+     */
+    @JvmStatic
+    fun runOnMain(activity: Activity, token: Long, delayMs: Long) {
+        val taskGeneration = lifecycleGeneration.get()
+        val block = Runnable {
+            try {
+                if (taskGeneration != lifecycleGeneration.get() || activity.isFinishing || activity.isDestroyed) {
+                    nativeCancelTask(token)
+                    return@Runnable
+                }
+                nativeRunTask(activity, token)
+            } catch (e: UnsatisfiedLinkError) {
+                // The library went away between the post and the looper. There
+                // is nothing to answer to here and nothing to retry.
+            }
+        }
+        if (delayMs > 0) {
+            Handler(Looper.getMainLooper()).postDelayed(block, delayMs)
+        } else {
+            activity.runOnUiThread(block)
+        }
+    }
+
+    /**
+     * Returns whether Zig queued the work, not whether the device has turned.
+     *
+     * The shim returns true after `runOnUiThread` for the same reason: the
+     * JavaBridge thread is never the main thread, so the block always runs
+     * later than the answer.
+     */
+    fun lockOrientation(activity: Activity, orientation: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeLockOrientation(activity, orientation)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun unlockOrientation(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeUnlockOrientation(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun setKeepAwake(activity: Activity, enabled: Boolean): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeSetKeepAwake(activity, enabled)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Both answer through the reply channel; true means Zig took the action. */
+    fun downloadFile(activity: Activity, url: String, filename: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeDownloadFile(activity, url, filename)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun saveFile(activity: Activity, data: String, filename: String): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeSaveFile(activity, data, filename)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /**
+     * The read side of the recording store. Null is "Zig declined", not "no
+     * recording" — an absent recording is a state object saying so.
+     */
+    fun getLocationRecordingState(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeGetLocationRecordingState(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    fun readLocationRecording(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeReadLocationRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    /**
+     * The four controls. Each returns the store's state as JSON, or null when
+     * Zig declined and the Kotlin below should answer instead.
+     */
+    fun startLocationRecording(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeStartLocationRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    fun stopLocationRecording(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeStopLocationRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    fun pauseLocationRecording(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativePauseLocationRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    fun resumeLocationRecording(activity: Activity): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeResumeLocationRecording(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    /**
+     * Start and stop the recording service.
+     *
+     * Called from Zig, and here rather than there because
+     * `LocationRecordingService::class.java` names a class in this holder's
+     * fixed runtime package. Keeping both classes together lets the prebuilt
+     * native runtime call these helpers without guessing the generated app's
+     * package or confusing it with an `applicationIdSuffix`.
+     */
+    @JvmStatic
+    fun startRecordingService(activity: Activity) {
+        ContextCompat.startForegroundService(
+            activity,
+            Intent(activity, LocationRecordingService::class.java)
+                .setAction(LocationRecordingService.ACTION_START)
+        )
+    }
+
+    @JvmStatic
+    fun stopRecordingService(activity: Activity) {
+        activity.stopService(
+            Intent(activity, LocationRecordingService::class.java)
+                .setAction(LocationRecordingService.ACTION_STOP)
+        )
+    }
+
+    // ==================== Network monitoring ====================
+    //
+    // The first listener shim. `ConnectivityManager.NetworkCallback` is an
+    // abstract Java class, and JNI cannot subclass one — `RegisterNatives`
+    // binds methods onto a class that already exists in the APK, so a native
+    // can be *called* from Java but cannot be a Java object of a type the
+    // framework demands.
+    //
+    // The split is the one `runOnMain` uses: the object lives here, the work
+    // lives in Zig. This class holds the callback and the registration; every
+    // override forwards to `nativeNetworkChanged`, which reads the status and
+    // sends the event.
+    //
+    // Unlike `runOnMain` there is no token, because there is only ever one
+    // watch. Repeated starts keep that existing registration so the callback
+    // remains reachable and each network change is delivered once.
+
+    private var networkWatch: ConnectivityManager.NetworkCallback? = null
+
+    /** Register the process-wide network callback once. */
+    @JvmStatic
+    fun startNetworkWatch(activity: Activity) {
+        if (networkWatch != null) return
+
+        val manager =
+            activity.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+
+        val watch = object : ConnectivityManager.NetworkCallback() {
+            override fun onAvailable(network: Network) = changed(activity)
+            override fun onLost(network: Network) = changed(activity)
+            override fun onCapabilitiesChanged(
+                network: Network,
+                networkCapabilities: NetworkCapabilities
+            ) = changed(activity)
+        }
+
+        val request = NetworkRequest.Builder()
+            .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
+            .build()
+
+        manager.registerNetworkCallback(request, watch)
+        networkWatch = watch
+    }
+
+    @JvmStatic
+    fun stopNetworkWatch(activity: Activity) {
+        val manager =
+            activity.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+        networkWatch?.let { manager.unregisterNetworkCallback(it) }
+        networkWatch = null
+    }
+
+    /**
+     * Every override lands here.
+     *
+     * This runs on a Binder thread, not the main one — which is fine, because
+     * the reply channel attaches the thread it is called on and hops to the
+     * main looper itself.
+     */
+    private fun changed(activity: Activity) {
+        try {
+            nativeNetworkChanged(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            // The library went away. There is no promise waiting on this and
+            // nothing to retry.
+        }
+    }
+
+    fun startNetworkMonitoring(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStartNetworkMonitoring(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun stopNetworkMonitoring(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStopNetworkMonitoring(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    // ==================== App state ====================
+    //
+    // The second listener shim. `LifecycleEventObserver` is a Java interface,
+    // so the object is here; the mapping, the state and the two deliveries are
+    // in Zig.
+    //
+    // One observer instance, added and removed — `LifecycleRegistry` keys its
+    // observers by identity, so adding twice is a no-op. That is why this one
+    // has no leak to reproduce, unlike the network watch.
+    //
+    // The native takes no Activity: everything it does is state and the reply
+    // channel, and neither needs one.
+
+    private val appStateObserver = LifecycleEventObserver { _, event ->
+        try {
+            nativeAppStateEvent(event.name)
+        } catch (e: UnsatisfiedLinkError) {
+            // The library went away. Nothing is waiting on this.
+        }
+    }
+
+    @JvmStatic
+    fun startAppStateWatch(activity: Activity) {
+        activity.runOnUiThread {
+            ProcessLifecycleOwner.get().lifecycle.addObserver(appStateObserver)
+        }
+    }
+
+    @JvmStatic
+    fun stopAppStateWatch(activity: Activity) {
+        activity.runOnUiThread {
+            ProcessLifecycleOwner.get().lifecycle.removeObserver(appStateObserver)
+        }
+    }
+
+    fun startAppStateMonitoring(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStartAppStateMonitoring(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun stopAppStateMonitoring(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStopAppStateMonitoring(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    /** Null is "Zig declined"; the state itself is never null. */
+    fun getAppState(): String? {
+        if (!isAvailable) return null
+        return try {
+            nativeGetAppState()
+        } catch (e: UnsatisfiedLinkError) {
+            null
+        }
+    }
+
+    // ==================== Bluetooth scanning ====================
+    //
+    // The third listener shim. `ScanCallback` is an abstract Java class, so
+    // the object is here and every result forwards to Zig — with the device
+    // name still nullable, so the "Unknown" default stays one decision in one
+    // place rather than two that have to agree.
+
+    private var bleScanner: BluetoothLeScanner? = null
+    private var bleScanCallback: ScanCallback? = null
+
+    /**
+     * Start scanning and report whether `startScan` was actually reached.
+     * The status crosses JNI so Zig can reject with the same reason as the
+     * Kotlin fallback instead of resolving an unavailable radio as success.
+     */
+    @JvmStatic
+    fun startBluetoothWatch(activity: Activity): Int {
+        val manager = activity.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager
+            ?: return BLUETOOTH_NO_ADAPTER
+        val adapter = try {
+            manager.adapter
+        } catch (e: SecurityException) {
+            return BLUETOOTH_PERMISSION_DENIED
+        } ?: return BLUETOOTH_NO_ADAPTER
+        val enabled = try {
+            adapter.isEnabled
+        } catch (e: SecurityException) {
+            return BLUETOOTH_PERMISSION_DENIED
+        }
+        if (!enabled) return BLUETOOTH_POWERED_OFF
+        val scanner = try {
+            adapter.bluetoothLeScanner
+        } catch (e: SecurityException) {
+            return BLUETOOTH_PERMISSION_DENIED
+        } ?: return BLUETOOTH_SCANNER_UNAVAILABLE
+
+        val callback = object : ScanCallback() {
+            override fun onScanResult(callbackType: Int, result: ScanResult) {
+                try {
+                    nativeBluetoothDevice(
+                        result.device.address,
+                        result.device.name,
+                        result.rssi
+                    )
+                } catch (e: UnsatisfiedLinkError) {
+                    // The library went away. Nothing is waiting on this.
+                } catch (e: SecurityException) {
+                    // `device.name` needs BLUETOOTH_CONNECT on API 31+, which
+                    // this scan does not require. The shim would throw out of
+                    // the callback here; dropping the result is the smaller
+                    // difference, and it is the only one.
+                }
+            }
+        }
+
+        return try {
+            scanner.startScan(callback)
+            bleScanner = scanner
+            bleScanCallback = callback
+            BLUETOOTH_STARTED
+        } catch (e: SecurityException) {
+            BLUETOOTH_PERMISSION_DENIED
+        } catch (e: RuntimeException) {
+            BLUETOOTH_FAILED
+        }
+    }
+
+    @JvmStatic
+    fun stopBluetoothWatch(activity: Activity) {
+        bleScanCallback?.let { bleScanner?.stopScan(it) }
+        bleScanCallback = null
+    }
+
+    /**
+     * Ask for BLUETOOTH_SCAN, but only where it exists.
+     *
+     * The permission arrived in API 31. Below that the shim does not ask at
+     * all — it rejects and leaves it — so the version check lives here, next
+     * to the call that would throw without it.
+     */
+    @JvmStatic
+    fun requestBluetoothScanPermission(activity: Activity) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            ActivityCompat.requestPermissions(
+                activity,
+                arrayOf(android.Manifest.permission.BLUETOOTH_SCAN),
+                REQUEST_BLUETOOTH
+            )
+        }
+    }
+
+    /** `CraftBridge.REQUEST_BLUETOOTH`, which this has to match. */
+    private const val REQUEST_BLUETOOTH = 1009
+    private const val BLUETOOTH_STARTED = 0
+    private const val BLUETOOTH_NO_ADAPTER = 1
+    private const val BLUETOOTH_POWERED_OFF = 2
+    private const val BLUETOOTH_PERMISSION_DENIED = 3
+    private const val BLUETOOTH_SCANNER_UNAVAILABLE = 4
+    private const val BLUETOOTH_FAILED = 5
+
+    fun startBluetoothScan(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStartBluetoothScan(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun stopBluetoothScan(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStopBluetoothScan(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    // ==================== Motion sensors ====================
+    //
+    // The fourth listener shim. `SensorEventListener` is a Java interface, so
+    // the object is here — but only the object: which sensor a sample came
+    // from is passed across as a boolean and everything else, including the
+    // last-value bookkeeping and the delay the interval maps to, is Zig's.
+    //
+    // `registerListener` without a Handler delivers on the main looper, so
+    // every sample arrives on one thread and the state on the other side
+    // needs no lock.
+
+    private var sensorManager: SensorManager? = null
+    private var motionListener: SensorEventListener? = null
+
+    @JvmStatic
+    fun startMotionWatch(activity: Activity, delay: Int) {
+        val manager = activity.getSystemService(Context.SENSOR_SERVICE) as SensorManager
+        sensorManager = manager
+
+        val accelerometer = manager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER)
+        val gyroscope = manager.getDefaultSensor(Sensor.TYPE_GYROSCOPE)
+
+        val listener = object : SensorEventListener {
+            override fun onSensorChanged(event: SensorEvent) {
+                try {
+                    nativeMotionSample(
+                        event.sensor.type == Sensor.TYPE_ACCELEROMETER,
+                        event.values[0],
+                        event.values[1],
+                        event.values[2]
+                    )
+                } catch (e: UnsatisfiedLinkError) {
+                    // The library went away. Nothing is waiting on this.
+                }
+            }
+
+            override fun onAccuracyChanged(sensor: Sensor?, accuracy: Int) {}
+        }
+
+        accelerometer?.let { manager.registerListener(listener, it, delay) }
+        gyroscope?.let { manager.registerListener(listener, it, delay) }
+        motionListener = listener
+    }
+
+    @JvmStatic
+    fun stopMotionWatch(activity: Activity) {
+        motionListener?.let { sensorManager?.unregisterListener(it) }
+        motionListener = null
+    }
+
+    fun startMotionUpdates(activity: Activity, intervalMs: Int): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStartMotionUpdates(activity, intervalMs)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    fun stopMotionUpdates(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeStopMotionUpdates(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+
+    // ==================== Current position ====================
+    //
+    // The fifth listener shim, and the first with two Java interfaces in one
+    // flow: `OnSuccessListener` and `OnFailureListener` on the Play Services
+    // task, plus a `LocationCallback` for the fresh-location fallback.
+    //
+    // Every value crosses as a Double, including the three the framework types
+    // as Float. That is not a convenience: `CraftBridge` writes them with
+    // `put(name, value)`, and the overload Kotlin picks there is
+    // `put(String, double)` — primitive widening beats boxing — so they print
+    // as doubles. Passing them as Float and boxing them on the other side
+    // would print `0.1` where the shim prints `0.10000000149011612`.
+
+    @JvmStatic
+    fun requestLocationPermissions(activity: Activity) {
+        ActivityCompat.requestPermissions(
+            activity,
+            arrayOf(
+                android.Manifest.permission.ACCESS_FINE_LOCATION,
+                android.Manifest.permission.ACCESS_COARSE_LOCATION
+            ),
+            REQUEST_LOCATION
+        )
+    }
+
+    /** `CraftBridge.REQUEST_LOCATION`, which this has to match. */
+    private const val REQUEST_LOCATION = 1003
+    private val currentLocationCallbacks = mutableMapOf<LocationCallback, FusedLocationProviderClient>()
+    private val currentLocationHandler = Handler(Looper.getMainLooper())
+    private val currentLocationTimeouts = mutableMapOf<LocationCallback, Runnable>()
+    private val currentPositionSequence = java.util.concurrent.atomic.AtomicLong(0)
+    private const val LOCATION_REQUEST_TIMEOUT_MS = 15_000L
+
+    @JvmStatic
+    @SuppressLint("MissingPermission")
+    fun requestCurrentPosition(activity: Activity) {
+        val requestId = currentPositionSequence.incrementAndGet()
+        val settled = java.util.concurrent.atomic.AtomicBoolean(false)
+
+        fun resolveLocationRequest(location: Location) {
+            if (requestId != currentPositionSequence.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            deliverLocation(location)
+        }
+
+        fun rejectLocationRequest(message: String?) {
+            if (requestId != currentPositionSequence.get()) return
+            if (!settled.compareAndSet(false, true)) return
+            failLocation(message)
+        }
+
+        currentLocationCallbacks.forEach { (callback, client) ->
+            runCatching { client.removeLocationUpdates(callback) }
+        }
+        currentLocationCallbacks.clear()
+        currentLocationTimeouts.values.forEach { timeout ->
+            currentLocationHandler.removeCallbacks(timeout)
+        }
+        currentLocationTimeouts.clear()
+
+        if (GoogleApiAvailability.getInstance().isGooglePlayServicesAvailable(activity) != ConnectionResult.SUCCESS) {
+            rejectLocationRequest("Google Play Services is unavailable")
+            return
+        }
+        try {
+            val client = LocationServices.getFusedLocationProviderClient(activity)
+            client.lastLocation
+                .addOnSuccessListener { location: Location? ->
+                    if (requestId != currentPositionSequence.get()) return@addOnSuccessListener
+                    if (location != null) {
+                        resolveLocationRequest(location)
+                    } else {
+                        requestFreshPosition(
+                            activity,
+                            client,
+                            requestId,
+                            ::resolveLocationRequest,
+                            ::rejectLocationRequest
+                        )
+                    }
+                }
+                .addOnFailureListener { error -> rejectLocationRequest(error.message) }
+        } catch (error: Exception) {
+            rejectLocationRequest(error.message)
+        }
+    }
+
+    /**
+     * The fallback when there is no cached fix.
+     *
+     * One update, then the callback removes itself — as `CraftBridge`'s does.
+     * The page owns the provider-silence timeout; the request sequence here
+     * ensures a callback arriving after that timeout cannot settle its successor.
+     */
+    @SuppressLint("MissingPermission")
+    private fun requestFreshPosition(
+        activity: Activity,
+        client: FusedLocationProviderClient,
+        requestId: Long,
+        resolve: (Location) -> Unit,
+        reject: (String?) -> Unit
+    ) {
+        val request = LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, 1000)
+            .setWaitForAccurateLocation(false)
+            .setMinUpdateIntervalMillis(500)
+            .setMaxUpdateDelayMillis(1000)
+            .setMaxUpdates(1)
+            .build()
+
+        val callback = object : LocationCallback() {
+            override fun onLocationResult(result: LocationResult) {
+                clearCurrentLocationCallback(client, this)
+                if (requestId != currentPositionSequence.get()) return
+                result.lastLocation?.let(resolve)
+                    ?: reject("Location provider returned no position")
+            }
+        }
+        currentLocationCallbacks[callback] = client
+        val timeout = Runnable {
+            if (!currentLocationCallbacks.containsKey(callback)) return@Runnable
+            clearCurrentLocationCallback(client, callback)
+            reject("Location request timed out; provider returned no position")
+        }
+        currentLocationTimeouts[callback] = timeout
+        currentLocationHandler.postDelayed(timeout, LOCATION_REQUEST_TIMEOUT_MS)
+        try {
+            client.requestLocationUpdates(request, callback, activity.mainLooper)
+                .addOnFailureListener { error ->
+                    clearCurrentLocationCallback(client, callback)
+                    reject(error.message)
+                }
+        } catch (error: Exception) {
+            clearCurrentLocationCallback(client, callback)
+            reject(error.message)
+        }
+    }
+
+    private fun clearCurrentLocationCallback(
+        client: FusedLocationProviderClient,
+        callback: LocationCallback
+    ) {
+        runCatching { client.removeLocationUpdates(callback) }
+        currentLocationCallbacks.remove(callback)
+        currentLocationTimeouts.remove(callback)?.let { timeout ->
+            currentLocationHandler.removeCallbacks(timeout)
+        }
+    }
+
+    private fun deliverLocation(location: Location) {
+        try {
+            nativeLocationResult(
+                location.latitude,
+                location.longitude,
+                location.accuracy.toDouble(),
+                location.altitude,
+                location.speed.toDouble(),
+                location.bearing.toDouble(),
+                location.time
+            )
+        } catch (e: UnsatisfiedLinkError) {
+            // The library went away mid-flight. Nothing to answer to.
+        }
+    }
+
+    private fun failLocation(message: String?) {
+        try {
+            nativeLocationFailed(message)
+        } catch (e: UnsatisfiedLinkError) {
+        }
+    }
+
+    fun getCurrentPosition(activity: Activity): Boolean {
+        if (!isAvailable) return false
+        return try {
+            nativeGetCurrentPosition(activity)
+        } catch (e: UnsatisfiedLinkError) {
+            false
+        }
+    }
+}