@sigx/lynx-permissions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @sigx/lynx-permissions
+
+**Android-only infrastructure module.** Provides the shared `PermissionHelper` + `MediaCapture` classes that `@sigx/lynx-camera`, `@sigx/lynx-image-picker`, `@sigx/lynx-location`, and `@sigx/lynx-notifications` all dispatch through to show OS permission dialogs and receive Activity Result callbacks. iOS doesn't need this — `UIImagePickerController`/`CLLocationManager`/etc. handle their own prompts.
+
+You typically don't import this package directly — pull it in transitively by listing it after the modules that need it. Most apps that use Camera/ImagePicker/Location/Notifications will end up declaring it explicitly because the autolinker doesn't currently dedup peer requirements.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-permissions
+```
+
+```ts
+// sigx.lynx.config.ts
+export default defineLynxConfig({
+    modules: [
+        '@sigx/lynx-permissions',
+        '@sigx/lynx-camera',
+        '@sigx/lynx-image-picker',
+        // ...
+    ],
+});
+```
+
+`sigx prebuild` copies the Kotlin sources (`PermissionHelper.kt` + `MediaCapture.kt`) into your Android source tree.
+
+## How it works
+
+The app template's `MainActivity.kt` reflectively wires this module on lifecycle hooks:
+
+- `onResume` → `PermissionHelper.setActivity(this)`
+- `onPause` → `PermissionHelper.clearActivity()`
+- `onCreate` → `MediaCapture.register(this)` (Activity Result API launchers — must be wired before `STARTED` state)
+- `onRequestPermissionsResult` → `PermissionHelper.onRequestPermissionsResult(...)`
+
+The `try { Class.forName(...).getDeclaredField("INSTANCE").get(null) } catch { /* not present */ }` pattern means the wiring silently no-ops in apps that don't have this module on the classpath — so adding/removing it is a one-line change in `sigx.lynx.config.ts`.
+
+## Public API
+
+The Kotlin classes are consumed by other native modules, not by JS. There's no `index.ts` export here — JS callers go through `@sigx/lynx-camera.requestPermission()` etc.
+
+If you're authoring a new native module that needs runtime permissions on Android, reach into:
+
+```kotlin
+import com.sigx.permissions.PermissionHelper
+
+// In a coroutine-friendly context:
+val granted = PermissionHelper.request(arrayOf(Manifest.permission.CAMERA))
+```
+
+…and for `ActivityResultContracts`:
+
+```kotlin
+import com.sigx.permissions.MediaCapture
+
+// MediaCapture.takePicture(uri) etc. — wraps the system intents through
+// pre-registered launchers so the call site doesn't need to deal with
+// Activity Result lifecycle.
+```
+
+## Why a separate module
+
+Camera + ImagePicker + Location + Notifications all need the same `requestPermissions()` plumbing on Android. Without a shared layer, each module would re-implement Activity Result wiring, hold its own static `Activity` reference, and fight over `onRequestPermissionsResult` request codes. Centralizing it here keeps each consumer module trivially small and avoids overlapping request-code namespaces.
+
+iOS has no equivalent because the OS-level pickers (`UIImagePickerController`, `PHPickerViewController`, `CLLocationManager`) all handle their own permission flows internally.
+
+## Reference
+
+The wiring in `packages/lynx-cli/templates/android/app/src/main/kotlin/__package__/MainActivity.kt` is the canonical example of how an `Activity` integrates with this module via reflection.

package/android/com/sigx/permissions/MediaCapture.kt

@@ -0,0 +1,203 @@
+package com.sigx.permissions
+
+import android.content.Context
+import android.net.Uri
+import android.util.Log
+import androidx.activity.ComponentActivity
+import androidx.activity.result.ActivityResultLauncher
+import androidx.activity.result.PickVisualMediaRequest
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.core.content.FileProvider
+import com.lynx.react.bridge.JavaOnlyMap
+import java.io.File
+import java.lang.ref.WeakReference
+
+/**
+ * Module-level registry for Activity Result launchers. Camera + ImagePicker
+ * (and any future module needing Activity-result flows) delegate here so a
+ * single MainActivity hook covers them all.
+ *
+ * Design constraint: ActivityResultLaunchers MUST be registered BEFORE the
+ * Activity reaches STARTED state. So `register(activity)` has to be called
+ * from `onCreate()`, not lazily on first use. The MainActivity template
+ * wires this via the same reflective `callPermissionHelper(...)` path used
+ * for setActivity / clearActivity.
+ *
+ * Callbacks resolve once the user finishes the system UI (or cancels). We
+ * stash the pending callback on the singleton because the Activity-result
+ * launcher's own callback runs on the main thread but doesn't carry context;
+ * the module-side caller registered its callback via `takePicture(callback)`
+ * just before launching, and we route the result back to that callback.
+ *
+ * Concurrency: `pendingTakePictureCallback` and `pendingPickMediaCallback`
+ * are guarded by their nullness — only one camera launch or one picker
+ * launch at a time. Re-entrant calls overwrite the previous pending callback;
+ * the pre-empted callback is invoked with `error="cancelled"`.
+ */
+object MediaCapture {
+
+    private const val TAG = "MediaCapture"
+
+    private var activityRef: WeakReference<ComponentActivity>? = null
+    private var takePictureLauncher: ActivityResultLauncher<Uri>? = null
+    private var pickMediaLauncher: ActivityResultLauncher<PickVisualMediaRequest>? = null
+
+    private var pendingPhotoUri: Uri? = null
+    private var pendingTakePictureCallback: ((JavaOnlyMap) -> Unit)? = null
+    private var pendingPickMediaCallback: ((JavaOnlyMap) -> Unit)? = null
+
+    /**
+     * Wire this Activity into the registry. Call from MainActivity.onCreate
+     * BEFORE super.onCreate() returns OR at the very top of onCreate (after
+     * super) — registerForActivityResult requires the host to be in INITIALIZED
+     * or CREATED state, throws afterwards.
+     */
+    fun register(activity: ComponentActivity) {
+        activityRef = WeakReference(activity)
+
+        takePictureLauncher = activity.registerForActivityResult(
+            ActivityResultContracts.TakePicture()
+        ) { success ->
+            val uri = pendingPhotoUri
+            val cb = pendingTakePictureCallback
+            pendingPhotoUri = null
+            pendingTakePictureCallback = null
+            val result = JavaOnlyMap()
+            if (success && uri != null) {
+                result.putString("uri", uri.toString())
+                result.putBoolean("canceled", false)
+            } else {
+                result.putString("error", "cancelled")
+                result.putBoolean("canceled", true)
+            }
+            cb?.invoke(result)
+        }
+
+        pickMediaLauncher = activity.registerForActivityResult(
+            ActivityResultContracts.PickVisualMedia()
+        ) { uri ->
+            val cb = pendingPickMediaCallback
+            pendingPickMediaCallback = null
+            val result = JavaOnlyMap()
+            if (uri != null) {
+                val assets = com.lynx.react.bridge.JavaOnlyArray()
+                val asset = JavaOnlyMap().apply {
+                    putString("uri", uri.toString())
+                    putString("type", "image")
+                }
+                assets.pushMap(asset)
+                result.putArray("assets", assets)
+                result.putBoolean("canceled", false)
+            } else {
+                result.putBoolean("canceled", true)
+            }
+            cb?.invoke(result)
+        }
+
+        Log.i(TAG, "registered launchers on ${activity.javaClass.simpleName}")
+    }
+
+    /**
+     * Clear the Activity reference. Call from MainActivity.onDestroy.
+     */
+    fun unregister() {
+        activityRef = null
+        takePictureLauncher = null
+        pickMediaLauncher = null
+        // Resolve any pending callbacks with cancel so JS Promises don't hang.
+        pendingTakePictureCallback?.invoke(JavaOnlyMap().apply {
+            putString("error", "activity destroyed")
+            putBoolean("canceled", true)
+        })
+        pendingPickMediaCallback?.invoke(JavaOnlyMap().apply {
+            putString("error", "activity destroyed")
+            putBoolean("canceled", true)
+        })
+        pendingTakePictureCallback = null
+        pendingPickMediaCallback = null
+        pendingPhotoUri = null
+    }
+
+    /**
+     * Launch the system camera. Requires CAMERA permission + a configured
+     * FileProvider authority "${packageName}.fileprovider" (the MainActivity
+     * AndroidManifest template seeds this). The captured photo lands at
+     * cacheDir/sigx-camera-<timestamp>.jpg; the JS callback receives a
+     * content:// URI pointing at it.
+     */
+    fun takePicture(context: Context, callback: (JavaOnlyMap) -> Unit) {
+        val activity = activityRef?.get()
+        val launcher = takePictureLauncher
+        if (activity == null || launcher == null) {
+            callback(JavaOnlyMap().apply {
+                putString("error", "MediaCapture not registered — wire MediaCapture.register(this) into MainActivity.onCreate")
+                putBoolean("canceled", true)
+            })
+            return
+        }
+        // Pre-empt any prior pending call.
+        pendingTakePictureCallback?.invoke(JavaOnlyMap().apply {
+            putString("error", "cancelled by new takePicture")
+            putBoolean("canceled", true)
+        })
+
+        val photoFile = File(context.cacheDir, "sigx-camera-${System.currentTimeMillis()}.jpg")
+        val authority = "${context.packageName}.fileprovider"
+        val photoUri = try {
+            FileProvider.getUriForFile(context, authority, photoFile)
+        } catch (e: Throwable) {
+            callback(JavaOnlyMap().apply {
+                putString("error", "FileProvider authority '$authority' not configured: ${e.message}")
+                putBoolean("canceled", true)
+            })
+            return
+        }
+
+        pendingPhotoUri = photoUri
+        pendingTakePictureCallback = callback
+        try {
+            launcher.launch(photoUri)
+        } catch (e: Throwable) {
+            pendingPhotoUri = null
+            pendingTakePictureCallback = null
+            callback(JavaOnlyMap().apply {
+                putString("error", e.message ?: "launcher.launch failed")
+                putBoolean("canceled", true)
+            })
+        }
+    }
+
+    /**
+     * Launch the system photo picker. No CAMERA / READ_MEDIA_IMAGES permission
+     * needed — Android 13+'s photo picker grants per-pick access on the fly.
+     * Returns a content:// URI for the picked image (or canceled=true).
+     */
+    fun pickImage(callback: (JavaOnlyMap) -> Unit) {
+        val launcher = pickMediaLauncher
+        if (launcher == null) {
+            callback(JavaOnlyMap().apply {
+                putString("error", "MediaCapture not registered — wire MediaCapture.register(this) into MainActivity.onCreate")
+                putBoolean("canceled", true)
+            })
+            return
+        }
+        pendingPickMediaCallback?.invoke(JavaOnlyMap().apply {
+            putString("error", "cancelled by new pickImage")
+            putBoolean("canceled", true)
+        })
+        pendingPickMediaCallback = callback
+        try {
+            launcher.launch(
+                PickVisualMediaRequest.Builder()
+                    .setMediaType(ActivityResultContracts.PickVisualMedia.ImageOnly)
+                    .build()
+            )
+        } catch (e: Throwable) {
+            pendingPickMediaCallback = null
+            callback(JavaOnlyMap().apply {
+                putString("error", e.message ?: "launcher.launch failed")
+                putBoolean("canceled", true)
+            })
+        }
+    }
+}

package/android/com/sigx/permissions/PermissionHelper.kt

@@ -0,0 +1,251 @@
+package com.sigx.permissions
+
+import android.Manifest
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
+import android.provider.Settings
+import android.util.Log
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+import com.lynx.react.bridge.JavaOnlyMap
+import java.lang.ref.WeakReference
+
+/**
+ * Shared permission utility for sigx-lynx-go native modules.
+ *
+ * NOT a LynxModule — a Kotlin utility class that other modules (CameraModule,
+ * LocationModule, etc.) call internally to check and request permissions.
+ *
+ * Requires [setActivity] to be called from MainActivity.onResume() so that
+ * runtime permission requests can show the OS dialog.
+ */
+object PermissionHelper {
+
+    private const val TAG = "PermissionHelper"
+
+    private var activityRef: WeakReference<Activity>? = null
+    private var requestCode = 1000
+    private val pendingCallbacks = mutableMapOf<Int, (JavaOnlyMap) -> Unit>()
+
+    /**
+     * Set the current Activity reference. Call from MainActivity.onResume().
+     */
+    fun setActivity(activity: Activity) {
+        activityRef = WeakReference(activity)
+    }
+
+    /**
+     * Clear the Activity reference. Call from MainActivity.onPause().
+     */
+    fun clearActivity() {
+        activityRef = null
+    }
+
+    /**
+     * Map a sigx permission key to Android permission string(s).
+     * Handles API-level branching (e.g., READ_MEDIA_IMAGES on API 33+).
+     */
+    fun resolveAndroidPermissions(permission: String): List<String> {
+        return when (permission) {
+            "camera" -> listOf(Manifest.permission.CAMERA)
+            "microphone" -> listOf(Manifest.permission.RECORD_AUDIO)
+            "location_when_in_use", "location" -> listOf(
+                Manifest.permission.ACCESS_FINE_LOCATION,
+                Manifest.permission.ACCESS_COARSE_LOCATION
+            )
+            "location_always" -> listOf(Manifest.permission.ACCESS_BACKGROUND_LOCATION)
+            "photo_library" -> {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                    listOf(
+                        Manifest.permission.READ_MEDIA_IMAGES,
+                        Manifest.permission.READ_MEDIA_VIDEO
+                    )
+                } else {
+                    @Suppress("DEPRECATION")
+                    listOf(Manifest.permission.READ_EXTERNAL_STORAGE)
+                }
+            }
+            "notifications" -> {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                    listOf(Manifest.permission.POST_NOTIFICATIONS)
+                } else {
+                    emptyList() // No runtime permission needed pre-API 33
+                }
+            }
+            "contacts" -> listOf(Manifest.permission.READ_CONTACTS)
+            "calendar" -> listOf(Manifest.permission.READ_CALENDAR)
+            "bluetooth" -> {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+                    listOf(
+                        Manifest.permission.BLUETOOTH_SCAN,
+                        Manifest.permission.BLUETOOTH_CONNECT
+                    )
+                } else {
+                    @Suppress("DEPRECATION")
+                    listOf(Manifest.permission.BLUETOOTH)
+                }
+            }
+            else -> {
+                // Allow raw Android permission strings (e.g., "android.permission.CAMERA")
+                if (permission.startsWith("android.permission.")) {
+                    listOf(permission)
+                } else {
+                    Log.w(TAG, "Unknown permission key: $permission")
+                    emptyList()
+                }
+            }
+        }
+    }
+
+    /**
+     * Check permission status without prompting.
+     * Returns a map with { status, canAskAgain }.
+     */
+    fun checkPermission(context: Context, permission: String): JavaOnlyMap {
+        val androidPerms = resolveAndroidPermissions(permission)
+        val result = JavaOnlyMap()
+
+        if (androidPerms.isEmpty()) {
+            // No runtime permission required (e.g., notifications pre-API 33)
+            result.putString("status", "granted")
+            result.putBoolean("canAskAgain", false)
+            return result
+        }
+
+        val allGranted = androidPerms.all { perm ->
+            ContextCompat.checkSelfPermission(context, perm) == PackageManager.PERMISSION_GRANTED
+        }
+
+        if (allGranted) {
+            result.putString("status", "granted")
+            result.putBoolean("canAskAgain", false)
+            return result
+        }
+
+        // Check if we can ask again (only meaningful if we have an Activity)
+        val activity = activityRef?.get()
+        val canAskAgain = if (activity != null) {
+            androidPerms.any { perm ->
+                ActivityCompat.shouldShowRequestPermissionRationale(activity, perm)
+            }
+        } else {
+            true // Assume we can ask if no Activity to check
+        }
+
+        // Determine if blocked (denied + can't ask again) vs undetermined (never asked)
+        val anyDeniedPermanently = activity != null && androidPerms.any { perm ->
+            ContextCompat.checkSelfPermission(context, perm) != PackageManager.PERMISSION_GRANTED &&
+                !ActivityCompat.shouldShowRequestPermissionRationale(activity, perm)
+        }
+
+        // If permission was never requested, shouldShowRationale returns false too,
+        // so we use SharedPreferences to track if we've asked before
+        val prefs = context.getSharedPreferences("sigx_permissions", Context.MODE_PRIVATE)
+        val hasAskedBefore = prefs.getBoolean("asked_$permission", false)
+
+        if (!hasAskedBefore) {
+            result.putString("status", "undetermined")
+            result.putBoolean("canAskAgain", true)
+        } else if (anyDeniedPermanently && !canAskAgain) {
+            result.putString("status", "blocked")
+            result.putBoolean("canAskAgain", false)
+        } else {
+            result.putString("status", "denied")
+            result.putBoolean("canAskAgain", canAskAgain)
+        }
+
+        return result
+    }
+
+    /**
+     * Request a permission, showing the OS dialog if possible.
+     * Calls back with { status, canAskAgain }.
+     */
+    fun requestPermission(context: Context, permission: String, callback: (JavaOnlyMap) -> Unit) {
+        val androidPerms = resolveAndroidPermissions(permission)
+
+        if (androidPerms.isEmpty()) {
+            val result = JavaOnlyMap()
+            result.putString("status", "granted")
+            result.putBoolean("canAskAgain", false)
+            callback(result)
+            return
+        }
+
+        // Check if already granted
+        val allGranted = androidPerms.all { perm ->
+            ContextCompat.checkSelfPermission(context, perm) == PackageManager.PERMISSION_GRANTED
+        }
+        if (allGranted) {
+            val result = JavaOnlyMap()
+            result.putString("status", "granted")
+            result.putBoolean("canAskAgain", false)
+            callback(result)
+            return
+        }
+
+        val activity = activityRef?.get()
+        if (activity == null) {
+            Log.w(TAG, "No Activity available to request permission: $permission")
+            val result = JavaOnlyMap()
+            result.putString("status", "denied")
+            result.putBoolean("canAskAgain", true)
+            callback(result)
+            return
+        }
+
+        // Mark that we've asked for this permission
+        val prefs = context.getSharedPreferences("sigx_permissions", Context.MODE_PRIVATE)
+        prefs.edit().putBoolean("asked_$permission", true).apply()
+
+        // Request the permission
+        val code = requestCode++
+        pendingCallbacks[code] = callback
+        ActivityCompat.requestPermissions(activity, androidPerms.toTypedArray(), code)
+    }
+
+    /**
+     * Called from MainActivity.onRequestPermissionsResult() to resolve pending callbacks.
+     */
+    fun onRequestPermissionsResult(
+        requestCode: Int,
+        permissions: Array<out String>,
+        grantResults: IntArray
+    ) {
+        val callback = pendingCallbacks.remove(requestCode) ?: return
+
+        val allGranted = grantResults.isNotEmpty() && grantResults.all {
+            it == PackageManager.PERMISSION_GRANTED
+        }
+
+        val result = JavaOnlyMap()
+        if (allGranted) {
+            result.putString("status", "granted")
+            result.putBoolean("canAskAgain", false)
+        } else {
+            val activity = activityRef?.get()
+            val canAskAgain = activity != null && permissions.any { perm ->
+                ActivityCompat.shouldShowRequestPermissionRationale(activity, perm)
+            }
+            result.putString("status", if (canAskAgain) "denied" else "blocked")
+            result.putBoolean("canAskAgain", canAskAgain)
+        }
+
+        callback(result)
+    }
+
+    /**
+     * Open the app's system settings page (for when permissions are blocked).
+     */
+    fun openSettings(context: Context) {
+        val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
+            data = Uri.fromParts("package", context.packageName, null)
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+        context.startActivity(intent)
+    }
+}

package/android/com/sigx/permissions/PermissionsActivityHook.kt

@@ -0,0 +1,47 @@
+package com.sigx.permissions
+
+import android.app.Activity
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+
+/**
+ * Activity-lifecycle hook for `@sigx/lynx-permissions`.
+ *
+ * Discovered by the auto-linker via `sigx-module.json`'s
+ * `android.activityHook`. Wires the host Activity into [PermissionHelper]
+ * (so runtime permission prompts can show their OS dialog) and registers
+ * Activity-result launchers used by Camera + ImagePicker.
+ *
+ * `MediaCapture.register` MUST run before the Activity reaches STARTED — the
+ * Android Activity-result API enforces this — so we call it from `onCreate`
+ * rather than `onResume`.
+ */
+object PermissionsActivityHook {
+
+    @JvmStatic
+    fun onCreate(activity: Activity, savedInstanceState: Bundle?) {
+        if (activity is ComponentActivity) {
+            MediaCapture.register(activity)
+        }
+    }
+
+    @JvmStatic
+    fun onResume(activity: Activity) {
+        PermissionHelper.setActivity(activity)
+    }
+
+    @JvmStatic
+    fun onPause(activity: Activity) {
+        PermissionHelper.clearActivity()
+    }
+
+    @JvmStatic
+    fun onRequestPermissionsResult(
+        activity: Activity,
+        requestCode: Int,
+        permissions: Array<String>,
+        grantResults: IntArray,
+    ) {
+        PermissionHelper.onRequestPermissionsResult(requestCode, permissions, grantResults)
+    }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@sigx/lynx-permissions",
+  "version": "0.1.0",
+  "description": "Shared Android permission helper for sigx-lynx native modules",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./sigx-module.json": "./sigx-module.json"
+  },
+  "files": [
+    "src",
+    "android",
+    "sigx-module.json"
+  ],
+  "author": "Andreas Ekdahl",
+  "license": "MIT"
+}

package/sigx-module.json

@@ -0,0 +1,13 @@
+{
+    "name": "Permissions",
+    "package": "@sigx/lynx-permissions",
+    "description": "Shared Android permission helper (peer dep for camera/location/etc.)",
+    "platforms": ["android"],
+    "android": {
+        "activityHook": {
+            "class": "com.sigx.permissions.PermissionsActivityHook",
+            "methods": ["onCreate", "onResume", "onPause", "onRequestPermissionsResult"]
+        },
+        "sourceDir": "android"
+    }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @sigx/lynx-permissions — shared Android permission helper.
+ *
+ * This package ships only Android Kotlin source (PermissionHelper.kt). It is
+ * a peer dependency of camera/location/imagepicker/notifications/filesystem
+ * modules that need to check or request runtime permissions. The host's
+ * Activity must call:
+ *
+ *   - `PermissionHelper.setActivity(this)` in `onResume()`
+ *   - `PermissionHelper.clearActivity()` in `onPause()`
+ *   - `PermissionHelper.onRequestPermissionsResult(requestCode, permissions, grantResults)`
+ *     in `onRequestPermissionsResult(...)`
+ *
+ * No JS surface today — modules call the Kotlin helper internally. If a
+ * cross-platform JS-side `permissions.request('camera')` API ever lands, it
+ * goes here.
+ */
+export {};