react-native-ensys-camera-x 1.0.7

package/android/src/main/java/com/customcamera/CustomCameraModule.kt

@@ -0,0 +1,2479 @@
+package com.customcamera
+
+import android.Manifest
+import android.app.Activity
+import android.content.ContentResolver
+import android.content.ActivityNotFoundException
+import android.content.ClipData
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.net.Uri
+import android.os.Build
+import android.provider.DocumentsContract
+import android.provider.OpenableColumns
+import android.os.Bundle
+import android.provider.MediaStore.Video.VideoColumns
+import androidx.core.content.ContextCompat
+import androidx.core.content.FileProvider
+import android.util.Log
+import java.io.File
+import com.facebook.react.bridge.ActivityEventListener
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.BaseActivityEventListener
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableType
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.facebook.react.modules.core.PermissionAwareActivity
+import com.facebook.react.modules.core.PermissionListener
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+
+class CustomCameraModule(
+  reactContext: ReactApplicationContext
+) : NativeCustomCameraSpec(reactContext) {
+
+  private var pendingPickerPromise: Promise? = null
+  private var pendingBarcodePromise: Promise? = null
+  private var pendingDocumentPromise: Promise? = null
+  private var pendingAudioPromise: Promise? = null
+  private var pendingImageVideoPromise: Promise? = null
+  private var pendingMediaEditorPromise: Promise? = null
+
+  private val activityEventListener: ActivityEventListener =
+    object : BaseActivityEventListener() {
+      override fun onActivityResult(
+        activity: Activity,
+        requestCode: Int,
+        resultCode: Int,
+        data: Intent?
+      ) {
+        when (requestCode) {
+          CAMERA_PICKER_REQUEST -> {
+            val promise = pendingPickerPromise ?: return
+            pendingPickerPromise = null
+            promise.resolve(createResultMap(resultCode, data))
+          }
+          DOCUMENT_PICKER_REQUEST -> {
+            val promise = pendingDocumentPromise ?: return
+            pendingDocumentPromise = null
+            promise.resolve(buildPickedFilesResult(resultCode, data, "document"))
+          }
+          AUDIO_PICKER_REQUEST -> {
+            val promise = pendingAudioPromise ?: return
+            pendingAudioPromise = null
+            promise.resolve(buildPickedFilesResult(resultCode, data, "audio"))
+          }
+          BARCODE_SCAN_REQUEST -> {
+            val promise = pendingBarcodePromise ?: return
+            pendingBarcodePromise = null
+            val value = data?.getStringExtra(BarcodeScannerActivity.EXTRA_RESULT_VALUE)
+            if (resultCode == Activity.RESULT_OK && value != null) {
+              promise.resolve(value)
+            } else {
+              promise.reject("SCAN_CANCELLED", "Barcode scan cancelled")
+            }
+          }
+          IMAGE_VIDEO_PICKER_REQUEST -> {
+            val promise = pendingImageVideoPromise ?: return
+            pendingImageVideoPromise = null
+            promise.resolve(buildPickedMediaResult(resultCode, data))
+          }
+          MEDIA_EDITOR_REQUEST -> {
+            val promise = pendingMediaEditorPromise ?: return
+            pendingMediaEditorPromise = null
+            // Same result decoder as the camera picker: the editor finishes through the very same
+            // selection pipeline, so the payload is identical to a capture's.
+            promise.resolve(createResultMap(resultCode, data))
+          }
+        }
+      }
+    }
+
+  init {
+    reactApplicationContext.addActivityEventListener(activityEventListener)
+    Localization.init(reactApplicationContext)
+  }
+
+  override fun getName(): String = NAME
+
+  /**
+   * Generate a secure content URI using FileProvider for files that need to be shared
+   * outside the app. Falls back to file:// URI for older Android versions.
+   */
+  private fun getSecureUriForFile(file: android.net.Uri): String {
+    return file.toString() // This method already receives a Uri, so just return it as string
+  }
+
+  /**
+   * Generate a secure content URI using FileProvider for files that need to be shared
+   * outside the app. Falls back to file:// URI for older Android versions.
+   */
+  private fun getSecureUriForFile(file: java.io.File): String {
+    val context = reactApplicationContext
+    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+      try {
+        FileProvider.getUriForFile(
+          context,
+          "${context.packageName}.camera.fileprovider",
+          file
+        ).toString()
+      } catch (e: Exception) {
+        // Fallback to file:// URI if FileProvider fails
+        android.net.Uri.fromFile(file).toString()
+      }
+    } else {
+      // For Android versions before N, file:// URIs are acceptable
+      android.net.Uri.fromFile(file).toString()
+    }
+  }
+
+  @ReactMethod
+  override fun openCamera(promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("NO_ACTIVITY", "Activity not available")
+      return
+    }
+
+    val intent = CustomCameraActivity.createIntent(
+      activity = activity,
+      mediaTypes = "all",
+      selectionLimit = 1,
+      initialCamera = "back",
+      enableVideo = true,
+      enableVideoNotes = true,
+      enableFilter = true
+    )
+    try {
+      activity.startActivity(intent)
+      promise.resolve("opened")
+    } catch (exception: RuntimeException) {
+      promise.reject("CAMERA_PICKER_ERROR", "Unable to open camera picker", exception)
+    }
+  }
+
+  @ReactMethod
+  override fun setLocalization(map: ReadableMap, isRtl: Boolean, locale: String) {
+    val stringMap = mutableMapOf<String, String>()
+    val hashMap = map.toHashMap()
+    for ((key, value) in hashMap) {
+      if (value != null) {
+        stringMap[key] = value.toString()
+      }
+    }
+    Localization.setTranslations(reactApplicationContext, stringMap, isRtl, locale)
+  }
+
+  @ReactMethod
+  override fun openCameraPicker(options: ReadableMap, promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("NO_ACTIVITY", "Activity not available")
+      return
+    }
+
+    if (pendingPickerPromise != null) {
+      promise.reject("PICKER_ALREADY_OPEN", "Camera picker is already open")
+      return
+    }
+
+    val intent = CustomCameraActivity.createIntent(
+      activity = activity,
+      mediaTypes = options.getMediaTypesOrDefault("mediaTypes", "all"),
+      selectionLimit = options.getIntOrDefault("selectionLimit", 0),
+      initialCamera = options.getInitialCameraOrDefault("initialCamera", "back"),
+      enableVideo = options.getBooleanOrDefault("enableVideo", true),
+      enableVideoNotes = options.getBooleanOrDefault("enableVideoNotes", true),
+      enableFilter = options.getBooleanOrDefault("enableFilter", true),
+      // Hold-to-record. 0 for holdToRecordDelayMs means "use the system long-press timeout";
+      // the activity clamps both durations to sane bounds.
+      enableHoldToRecord = options.getBooleanOrDefault("enableHoldToRecord", true),
+      holdToRecordDelayMs = options.getIntOrDefault("holdToRecordDelayMs", 0),
+      minRecordDurationMs = options.getIntOrDefault("minRecordDurationMs", 1000),
+      enableRecordLock = options.getBooleanOrDefault("enableRecordLock", true),
+      enableRecordCancel = options.getBooleanOrDefault("enableRecordCancel", true)
+    )
+
+    pendingPickerPromise = promise
+    try {
+      activity.startActivityForResult(intent, CAMERA_PICKER_REQUEST)
+    } catch (exception: RuntimeException) {
+      pendingPickerPromise = null
+      promise.reject("CAMERA_PICKER_ERROR", "Unable to open camera picker", exception)
+    }
+  }
+
+  /**
+   * Open the system DOCUMENT picker via the Storage Access Framework (ACTION_OPEN_DOCUMENT).
+   *
+   * Mirrors [openCameraPicker]'s lifecycle exactly — stash the promise, launch for result, and
+   * resolve it from onActivityResult with the same `{ cancelled, assets }` shape. SAF is built into
+   * Android, so this needs NO third-party library and NO runtime storage permission (the system
+   * picker grants per-URI read access, which we make persistable so the uri stays valid after the
+   * picker closes). `selectionLimit` (0 / >1 = multi-select) and an optional `mimeTypes` override
+   * are read from [options]; the default MIME set covers the common document formats.
+   */
+  @ReactMethod
+  override fun openDocumentPicker(options: ReadableMap, promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("NO_ACTIVITY", "Activity not available")
+      return
+    }
+    if (pendingDocumentPromise != null) {
+      promise.reject("PICKER_ALREADY_OPEN", "Document picker is already open")
+      return
+    }
+
+    val mimeTypes = options.getStringArrayOrNull("mimeTypes") ?: DEFAULT_DOCUMENT_MIME_TYPES
+    val intent = buildOpenDocumentIntent(options, mimeTypes)
+
+    pendingDocumentPromise = promise
+    try {
+      activity.startActivityForResult(intent, DOCUMENT_PICKER_REQUEST)
+    } catch (exception: RuntimeException) {
+      pendingDocumentPromise = null
+      promise.reject("DOCUMENT_PICKER_ERROR", "Unable to open document picker", exception)
+    }
+  }
+
+  /**
+   * Open the system AUDIO picker via the Storage Access Framework (ACTION_OPEN_DOCUMENT), scoped to
+   * `audio/ *`. Identical lifecycle to [openDocumentPicker]; pass `mimeTypes` in [options] to narrow
+   * the selection (e.g. only `audio/mpeg`).
+   *
+   * Unlike the document picker, this one is steered to open ON THE AUDIO SECTION rather than the
+   * picker's default "Recent" view: EXTRA_INITIAL_URI (API 26+) points at the system media
+   * provider's Audio root, which AOSP DocumentsUI (and the OEM skins built on it) honours by
+   * landing directly in the audio browser. Pickers that don't recognise the hint ignore it and
+   * still apply the audio MIME filter, so the worst case everywhere is the old behavior.
+   */
+  @ReactMethod
+  override fun openAudioPicker(options: ReadableMap, promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("NO_ACTIVITY", "Activity not available")
+      return
+    }
+    if (pendingAudioPromise != null) {
+      promise.reject("PICKER_ALREADY_OPEN", "Audio picker is already open")
+      return
+    }
+
+    val mimeTypes = options.getStringArrayOrNull("mimeTypes") ?: DEFAULT_AUDIO_MIME_TYPES
+    val intent = buildOpenDocumentIntent(options, mimeTypes).apply {
+      // With several accepted types the shared builder falls back to a */* base type; re-anchor
+      // it to audio/* (when every entry is audio) so OEM pickers that route on the base type
+      // open their audio UI instead of a generic file browser. EXTRA_MIME_TYPES still governs
+      // exactly which files are selectable.
+      if (mimeTypes.size > 1 &&
+        mimeTypes.all { it.startsWith("audio/") || it in AUDIO_CONTAINER_MIME_TYPES }
+      ) {
+        type = "audio/*"
+      }
+      // Land the picker on the Audio section of the system media documents provider instead of
+      // the default Recents view. EXTRA_INITIAL_URI is honoured by DocumentsUI from API 26;
+      // providers that don't support it ignore the extra, so it is safe across third-party
+      // file managers. On API 24/25 the extra doesn't exist — skip it and rely on the MIME
+      // filter alone (the pre-26 picker has no Recents-vs-Audio landing distinction anyway).
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        putExtra(
+          DocumentsContract.EXTRA_INITIAL_URI,
+          DocumentsContract.buildRootUri(MEDIA_DOCUMENTS_AUTHORITY, MEDIA_DOCUMENTS_AUDIO_ROOT)
+        )
+      }
+    }
+
+    pendingAudioPromise = promise
+    try {
+      activity.startActivityForResult(intent, AUDIO_PICKER_REQUEST)
+    } catch (exception: RuntimeException) {
+      pendingAudioPromise = null
+      promise.reject("AUDIO_PICKER_ERROR", "Unable to open audio picker", exception)
+    }
+  }
+
+  /**
+   * Open the system image/video picker via the Storage Access Framework (ACTION_OPEN_DOCUMENT),
+   * scoped to `image/ *` and `video/ *` MIME types. Identical lifecycle to [openDocumentPicker].
+   * This allows selecting existing photos and videos from the device gallery.
+   */
+  @ReactMethod
+  override fun openImageVideoPicker(options: ReadableMap, promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("NO_ACTIVITY", "Activity not available")
+      return
+    }
+    if (pendingImageVideoPromise != null) {
+      promise.reject("PICKER_ALREADY_OPEN", "Image/Video picker is already open")
+      return
+    }
+
+    val selectionLimit = options.getIntOrDefault("selectionLimit", 0)
+    val allowMultiple = selectionLimit == 0 || selectionLimit > 1
+    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT)
+    intent.addCategory(Intent.CATEGORY_OPENABLE)
+    intent.type = "*/*"
+    intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("image/*", "video/*"))
+    intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, allowMultiple)
+    intent.addFlags(
+      Intent.FLAG_GRANT_READ_URI_PERMISSION or
+        Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION
+    )
+
+    pendingImageVideoPromise = promise
+    try {
+      activity.startActivityForResult(intent, IMAGE_VIDEO_PICKER_REQUEST)
+    } catch (exception: RuntimeException) {
+      pendingImageVideoPromise = null
+      promise.reject("IMAGE_VIDEO_PICKER_ERROR", "Unable to open image/video picker", exception)
+    }
+  }
+
+  /**
+   * Open an EXISTING photo or video — one the user just picked from the device gallery — on the
+   * camera's own preview/editor screen.
+   *
+   * This is the same Activity, the same [MediaPreviewEditor] controller and the same editing tools
+   * a freshly captured photo/video lands on; only the source of the file differs. It resolves with
+   * the identical `{ cancelled, assets }` shape as [openCameraPicker], produced by the identical
+   * send pipeline (cache → edit → publish to Documents), so a gallery item is indistinguishable
+   * from a capture to everything downstream.
+   *
+   * Item count drives the screen, exactly as it does for captures: ONE item opens the single-asset
+   * image/video editor, SEVERAL open the multi-media Add More + Send preview with the whole
+   * selection in the order it was given.
+   *
+   * `options`: either `uri` (single item) or `items` (an array of `{ uri, type?, fileName?,
+   * mimeType? }`, in pick order), plus the same optional `type` / `fileName` / `mimeType` hints for
+   * the single form and `enableFilter` for both. No usable uri rejects; a uri that is neither image
+   * nor video is dropped by the Activity (and comes back `cancelled: true` if none survive).
+   */
+  @ReactMethod
+  override fun openMediaEditor(options: ReadableMap, promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("NO_ACTIVITY", "Activity not available")
+      return
+    }
+    if (pendingMediaEditorPromise != null) {
+      promise.reject("EDITOR_ALREADY_OPEN", "Media editor is already open")
+      return
+    }
+
+    val items = options.readEditorMediaItems()
+    if (items.isEmpty()) {
+      promise.reject("INVALID_MEDIA_URI", "A media uri is required to open the editor")
+      return
+    }
+
+    val intent = CustomCameraActivity.createEditorIntent(
+      activity = activity,
+      items = items,
+      enableFilter = options.getBooleanOrDefault("enableFilter", true)
+    )
+
+    pendingMediaEditorPromise = promise
+    try {
+      activity.startActivityForResult(intent, MEDIA_EDITOR_REQUEST)
+    } catch (exception: RuntimeException) {
+      pendingMediaEditorPromise = null
+      promise.reject("MEDIA_EDITOR_ERROR", "Unable to open the media editor", exception)
+    }
+  }
+
+  /**
+   * Open a document uri in whatever external app can view it (PDF reader, editor, etc.) via
+   * ACTION_VIEW. Grants transient read permission so the target app can read the (possibly
+   * SAF-backed) uri, and picks up a FileProvider content uri automatically for file:// paths so
+   * we never leak a raw file uri to another process. Resolves `true` when an activity was
+   * launched, `false` when the device has no handler for the type.
+   */
+  @ReactMethod
+  override fun openDocument(uri: String, mimeType: String, promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+      ?: reactApplicationContext.applicationContext
+    try {
+      val parsed = Uri.parse(uri)
+      // A file:// path can't be shared with another app on API 24+ (FileUriExposedException),
+      // so wrap it in a FileProvider content uri; content:// and others are used as-is.
+      val viewUri: Uri = if (parsed.scheme == "file") {
+        val path = parsed.path
+        if (path != null) {
+          try {
+            FileProvider.getUriForFile(
+              reactApplicationContext,
+              "${reactApplicationContext.packageName}.camera.fileprovider",
+              java.io.File(path)
+            )
+          } catch (e: Exception) {
+            parsed
+          }
+        } else {
+          parsed
+        }
+      } else {
+        parsed
+      }
+
+      var resolvedMimeType = mimeType
+      if (resolvedMimeType.isEmpty()) {
+        val extension = android.webkit.MimeTypeMap.getFileExtensionFromUrl(uri)
+        if (extension != null) {
+            resolvedMimeType = android.webkit.MimeTypeMap.getSingleton().getMimeTypeFromExtension(extension.lowercase()) ?: ""
+        }
+      }
+
+      val viewIntent = Intent(Intent.ACTION_VIEW).apply {
+        if (resolvedMimeType.isNotEmpty()) {
+            setDataAndType(viewUri, resolvedMimeType)
+        } else {
+            data = viewUri
+        }
+        addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+      }
+      // Wrap in a chooser for a consistent "Open with" experience. NEW_TASK is required when we
+      // fall back to the application context (no foreground activity). We deliberately do NOT rely
+      // on resolveActivity(): on API 30+ package-visibility rules make it return null even when a
+      // capable app IS installed, so we just try to launch and report false only when the OS
+      // genuinely has no handler (ActivityNotFoundException).
+      val chooser = Intent.createChooser(
+        viewIntent,
+        Localization.getString("openWith", "Open with")
+      ).apply {
+        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+      }
+
+      try {
+        activity.startActivity(chooser)
+        promise.resolve(true)
+      } catch (notFound: android.content.ActivityNotFoundException) {
+        promise.resolve(false)
+      }
+    } catch (exception: Exception) {
+      promise.reject("OPEN_DOCUMENT_ERROR", "Unable to open document", exception)
+    }
+  }
+
+  @ReactMethod
+  override fun getUploadState(promise: Promise) {
+    try {
+      val context = reactApplicationContext.applicationContext
+      val intent = Intent(context, UploadService::class.java).apply {
+        action = UploadService.ACTION_GET_NOTIFICATION_HISTORY
+      }
+
+      // Use a REGULAR service start (never startForegroundService) for the history query.
+      // The ACTION_GET_NOTIFICATION_HISTORY branch only reads prefs and broadcasts — it
+      // never calls startForeground(). Starting it as a foreground service would arm the
+      // OS ~5s "must call startForeground()" deadline that this action never satisfies,
+      // and the resulting RemoteServiceException is thrown by the system OUTSIDE this
+      // try/catch → guaranteed release crash. A plain startService has no such deadline;
+      // if it is disallowed (app in background on API 31+) it throws here and is caught.
+      context.startService(intent)
+
+      // We'll handle the result via broadcast receiver
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("GET_UPLOAD_STATE_FAILED", "Failed to get upload state", e)
+    }
+  }
+
+  @ReactMethod
+  override fun getNotificationHistory(promise: Promise) {
+    try {
+      val context = reactApplicationContext.applicationContext
+      val sharedPrefs = context.getSharedPreferences("UploadServicePrefs", Context.MODE_PRIVATE)
+      val historyJson = sharedPrefs.getString("notification_history", "[]")
+      promise.resolve(historyJson)
+    } catch (e: Exception) {
+      promise.reject("GET_NOTIFICATION_HISTORY_FAILED", "Failed to get notification history", e)
+    }
+  }
+
+  /**
+   * Real device-memory facts from ActivityManager, for JS-side low-end tuning.
+   * `isLowRamDevice` is the OS's own declaration (Go-edition and 1-2GB phones),
+   * `memoryClass` is the per-app heap budget in MB, and totalMem/availMem
+   * describe the whole device. JS previously GUESSED all of this from screen
+   * size, which misclassified most phones — this is the ground truth.
+   */
+  @ReactMethod
+  override fun getDeviceCapabilities(promise: Promise) {
+    try {
+      val context = reactApplicationContext.applicationContext
+      val activityManager =
+        context.getSystemService(Context.ACTIVITY_SERVICE) as android.app.ActivityManager
+      val memoryInfo = android.app.ActivityManager.MemoryInfo()
+      activityManager.getMemoryInfo(memoryInfo)
+
+      val result = Arguments.createMap().apply {
+        putBoolean("isLowRamDevice", activityManager.isLowRamDevice)
+        putInt("memoryClassMb", activityManager.memoryClass)
+        putDouble("totalRamMb", (memoryInfo.totalMem / (1024.0 * 1024.0)))
+        putDouble("availableRamMb", (memoryInfo.availMem / (1024.0 * 1024.0)))
+        putBoolean("isCurrentlyLowMemory", memoryInfo.lowMemory)
+        putInt("cpuCores", Runtime.getRuntime().availableProcessors())
+      }
+      promise.resolve(result)
+    } catch (e: Exception) {
+      promise.reject("DEVICE_CAPABILITIES_FAILED", "Failed to read device capabilities", e)
+    }
+  }
+
+  @ReactMethod
+  override fun clearNotificationHistory(promise: Promise) {
+    try {
+      val context = reactApplicationContext.applicationContext
+      val sharedPrefs = context.getSharedPreferences("UploadServicePrefs", Context.MODE_PRIVATE)
+      sharedPrefs.edit().remove("notification_history").apply()
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("CLEAR_NOTIFICATION_HISTORY_FAILED", "Failed to clear notification history", e)
+    }
+  }
+
+  @ReactMethod
+  override fun startUpload(uris: ReadableArray, uploadUrl: String, promise: Promise) {
+    val context = reactApplicationContext.applicationContext
+    val uriList = ArrayList<String>()
+    // Read each element defensively: getString throws if JS passed a non-string element
+    // (e.g. a number/object), and that throw would escape the @ReactMethod before the
+    // promise settles → bridge crash + hung promise. Skip anything that isn't a string.
+    for (i in 0 until uris.size()) {
+      val item = try {
+        if (uris.getType(i) == ReadableType.String) uris.getString(i) else null
+      } catch (e: Exception) {
+        null
+      }
+      item?.let { uriList.add(it) }
+    }
+
+    // Never start the (foreground) upload service with nothing to upload. The service's
+    // ACTION_START_UPLOAD branch bails on empty URIs WITHOUT calling startForeground(),
+    // which — when launched via startForegroundService on API 26+ — crashes the app with
+    // RemoteServiceException. Reject cleanly instead of starting it at all.
+    if (uriList.isEmpty() || uploadUrl.isBlank()) {
+      promise.reject("UPLOAD_START_FAILED", "No valid media URIs to upload")
+      return
+    }
+
+    // Hand the service a React context so it can emit in-app "onUploadProgress"
+    // events (the replacement for the disabled system notifications). Same
+    // pattern as GlobalAudioPlayer.reactContext.
+    UploadService.reactContext = reactApplicationContext
+
+    fun launchUploadService() {
+      val intent = Intent(context, UploadService::class.java).apply {
+        action = UploadService.ACTION_START_UPLOAD
+        putStringArrayListExtra(UploadService.EXTRA_URIS, uriList)
+        putExtra(UploadService.EXTRA_UPLOAD_URL, uploadUrl)
+      }
+
+      try {
+        // startForegroundService OBLIGATES a startForeground() call (which requires
+        // posting a notification) within ~5s on API 26+. With system notifications
+        // disabled the service never calls startForeground, so it must be launched
+        // as a regular background service instead.
+        if (UploadService.SYSTEM_NOTIFICATIONS_ENABLED &&
+          Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
+        ) {
+          context.startForegroundService(intent)
+        } else {
+          context.startService(intent)
+        }
+        promise.resolve(null)
+      } catch (e: Exception) {
+        promise.reject("UPLOAD_START_FAILED", "Failed to start upload service", e)
+      }
+    }
+
+    // startUpload() can be called without the host app ever having opened the camera
+    // picker (the only other place that requests POST_NOTIFICATIONS), so the upload's
+    // progress/success/failure notifications could otherwise silently never appear on
+    // API 33+. Request it here too — best-effort, since the upload itself doesn't
+    // depend on the permission being granted, only its visible progress does.
+    // Skipped entirely while system notifications are disabled: progress is shown
+    // in-app, so the app must not prompt for notification permission.
+    if (UploadService.SYSTEM_NOTIFICATIONS_ENABLED &&
+      Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
+      ContextCompat.checkSelfPermission(context, Manifest.permission.POST_NOTIFICATIONS) !=
+        PackageManager.PERMISSION_GRANTED
+    ) {
+      val permissionAwareActivity = reactApplicationContext.currentActivity as? PermissionAwareActivity
+      if (permissionAwareActivity != null) {
+        permissionAwareActivity.requestPermissions(
+          arrayOf(Manifest.permission.POST_NOTIFICATIONS),
+          NOTIFICATION_PERMISSION_REQUEST,
+          PermissionListener { requestCode, _, _ ->
+            if (requestCode == NOTIFICATION_PERMISSION_REQUEST) {
+              launchUploadService()
+              true
+            } else {
+              false
+            }
+          }
+        )
+        return
+      }
+    }
+
+    launchUploadService()
+  }
+
+  @ReactMethod
+  override fun cropImage(uri: String, options: ReadableMap, promise: Promise) {
+    // Basic stub for image cropping
+    promise.resolve(uri)
+  }
+
+  @ReactMethod
+  override fun rotateImage(uri: String, degrees: Double, promise: Promise) {
+    try {
+      val parsedUri = android.net.Uri.parse(uri)
+      val bitmap = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+        val source = android.graphics.ImageDecoder.createSource(reactApplicationContext.contentResolver, parsedUri)
+        android.graphics.ImageDecoder.decodeBitmap(source)
+      } else {
+        @Suppress("DEPRECATION")
+        android.provider.MediaStore.Images.Media.getBitmap(reactApplicationContext.contentResolver, parsedUri)
+      }
+
+      val matrix = android.graphics.Matrix()
+      matrix.postRotate(degrees.toFloat())
+      val rotatedBitmap = android.graphics.Bitmap.createBitmap(bitmap, 0, 0, bitmap.width, bitmap.height, matrix, true)
+
+      val file = java.io.File(reactApplicationContext.cacheDir, "rotated_${System.currentTimeMillis()}.jpg")
+      val out = java.io.FileOutputStream(file)
+      rotatedBitmap.compress(android.graphics.Bitmap.CompressFormat.JPEG, 100, out)
+      out.flush()
+      out.close()
+
+      bitmap.recycle()
+      if (bitmap != rotatedBitmap) {
+        rotatedBitmap.recycle()
+      }
+
+      promise.resolve(getSecureUriForFile(file))
+    } catch (e: Exception) {
+      promise.reject("ROTATE_ERROR", e.message)
+    }
+  }
+
+  @ReactMethod
+  override fun applyFilter(uri: String, filterType: String, promise: Promise) {
+    // Basic stub for filter applying
+    promise.resolve(uri)
+  }
+
+  @ReactMethod
+  override fun createAlbum(albumName: String, promise: Promise) {
+    promise.resolve(true)
+  }
+
+  @ReactMethod
+  override fun moveMediaToAlbum(uris: ReadableArray, albumId: String, promise: Promise) {
+    promise.resolve(true)
+  }
+
+  /**
+   * Securely delete one or more media items.
+   *
+   * Every URI is routed through [SecureMediaDeleter], which overwrites the file's bytes with
+   * encrypted cryptographically secure random data 2 MiB longer than the file, flushes that to
+   * storage, unlinks it, and then sweeps every cached copy, derived variant and metadata reference
+   * the app holds for it. Callers that want the per-file security verdict should use
+   * [secureDeleteMedia]; this method keeps its historical `boolean` contract for existing callers.
+   *
+   * Runs on [Dispatchers.IO]: overwriting a large recording takes real seconds and must never
+   * touch the main thread.
+   */
+  @ReactMethod
+  override fun deleteMedia(uris: ReadableArray, promise: Promise) {
+    val uriList = (0 until uris.size()).mapNotNull { uris.getString(it) }
+    runOnBackgroundThread {
+      try {
+        var deletedCount = 0
+        var insecureCount = 0
+        for (uriStr in uriList) {
+          val report = SecureMediaDeleter.secureDelete(reactApplicationContext, uriStr)
+          if (report.deleted) deletedCount++
+          if (!report.fullySecure) insecureCount++
+        }
+        if (insecureCount > 0) {
+          // The boolean result cannot express "deleted but not securely", so the shortfall is at
+          // least made loud here. secureDeleteMedia() reports it to JS properly.
+          Log.e(
+            NAME,
+            "$insecureCount of ${uriList.size} deletions could not be verified as secure"
+          )
+        }
+        promise.resolve(deletedCount > 0)
+      } catch (e: Exception) {
+        Log.e(NAME, "Secure delete failed", e)
+        promise.reject("DELETE_ERROR", e.message, e)
+      }
+    }
+  }
+
+  /**
+   * Securely delete ONE media item, reporting exactly what was achieved.
+   *
+   * Unlike [deleteMedia] this never collapses the outcome to a boolean, so JS can distinguish
+   * "the file is gone and its bytes were destroyed" from "the file is gone but the overwrite
+   * failed" — the two must not be presented to the user the same way. Resolves with:
+   *
+   *  - `deleted` — the file is no longer on the filesystem
+   *  - `securelyOverwritten` — its bytes were overwritten AND flushed before it was unlinked
+   *  - `fullySecure` — the above, plus every derived copy also erased; the ONLY flag that
+   *    justifies telling a user the media was securely deleted
+   *  - `originalBytes` / `overwrittenBytes` — exact size, and how much garbage went over it
+   *  - `derivedFilesErased` / `derivedFilesFailed` — extra copies handled and missed
+   *  - `error` — present whenever any part fell short
+   *
+   * [assetId], [fileName] and [coverUri] are optional but strongly preferred: derived variants
+   * (compressed, exported, edited, cover frames) are named after the asset id, so omitting it
+   * leaves those copies of the same media on disk. `extraUris` erases additional copies the caller
+   * knows about — typically an asset's `cachePath` when its published document is the primary.
+   */
+  @ReactMethod
+  override fun secureDeleteMedia(uri: String, options: ReadableMap, promise: Promise) {
+    fun option(key: String): String? =
+      options.takeIf { it.hasKey(key) }?.getString(key)?.takeIf { it.isNotBlank() }
+
+    val assetId = option("assetId")
+    val fileName = option("fileName")
+    val coverUri = option("coverUri")
+    // Read off the bridge thread: a ReadableMap/ReadableArray must not be touched once the JS
+    // call returns, and the erase below runs long after that on Dispatchers.IO.
+    val extraUris = options.takeIf { it.hasKey("extraUris") }
+      ?.getArray("extraUris")
+      ?.let { array ->
+        (0 until array.size()).mapNotNull { array.getString(it)?.takeIf(String::isNotBlank) }
+      }
+      ?: emptyList()
+
+    runOnBackgroundThread {
+      try {
+        val report = SecureMediaDeleter.secureDelete(
+          context = reactApplicationContext,
+          uriString = uri,
+          assetId = assetId,
+          fileName = fileName,
+          coverUri = coverUri,
+          extraUris = extraUris
+        )
+        promise.resolve(Arguments.createMap().apply {
+          putBoolean("deleted", report.deleted)
+          putBoolean("securelyOverwritten", report.securelyOverwritten)
+          putBoolean("fullySecure", report.fullySecure)
+          putDouble("originalBytes", report.originalBytes.toDouble())
+          putDouble("overwrittenBytes", report.overwrittenBytes.toDouble())
+          putInt("derivedFilesErased", report.derivedFilesErased)
+          putInt("derivedFilesFailed", report.derivedFilesFailed)
+          report.error?.let { putString("error", it) }
+        })
+      } catch (e: Exception) {
+        Log.e(NAME, "Secure delete failed for $uri", e)
+        promise.reject("SECURE_DELETE_ERROR", e.message, e)
+      }
+    }
+  }
+
+  /** Wraps a `file://` path in a FileProvider content uri for cross-app sharing. */
+  private fun shareableUri(uriStr: String): Uri {
+    val parsed = Uri.parse(uriStr)
+    val scheme = parsed.scheme
+    if (scheme == "file" || scheme == null) {
+      val path = if (scheme == "file") parsed.path else uriStr
+      if (path != null) {
+        try {
+          return FileProvider.getUriForFile(
+            reactApplicationContext,
+            "${reactApplicationContext.packageName}.camera.fileprovider",
+            File(path)
+          )
+        } catch (e: Exception) {
+          // Fall through and share the original uri.
+        }
+      }
+    }
+    return parsed
+  }
+
+  /** Resolves a MIME type, falling back to the extension when it is empty/generic. */
+  private fun resolveShareMimeType(uriStr: String, mimeType: String): String {
+    var mime = mimeType.trim()
+    if (mime.isEmpty() || mime == "*/*") {
+      val extension = android.webkit.MimeTypeMap.getFileExtensionFromUrl(uriStr)
+      if (extension != null && extension.isNotBlank()) {
+        val guessed =
+          android.webkit.MimeTypeMap.getSingleton().getMimeTypeFromExtension(extension.lowercase())
+        if (!guessed.isNullOrBlank()) mime = guessed
+      }
+    }
+    return mime.ifBlank { "*/*" }
+  }
+
+  /**
+   * Share one or more media uris through the native Android share sheet using
+   * ACTION_SEND (single item) or ACTION_SEND_MULTIPLE (multiple items), with
+   * the correct MIME type for images, videos, documents and audio. File paths
+   * are wrapped in FileProvider content uris; read permission is granted to the
+   * launched chooser via FLAG_GRANT_READ_URI_PERMISSION + ClipData. Resolves
+   * `true` when the chooser was launched, `false` when no handler exists.
+   */
+  @ReactMethod
+  override fun shareMedia(uris: ReadableArray, mimeType: String, promise: Promise) {
+    try {
+      val shareUris = ArrayList<Uri>(uris.size())
+      for (i in 0 until uris.size()) {
+        val uriStr = uris.getString(i) ?: continue
+        shareUris.add(shareableUri(uriStr))
+      }
+      if (shareUris.isEmpty()) {
+        promise.resolve(false)
+        return
+      }
+
+      val resolvedMime = resolveShareMimeType(shareUris.first().toString(), mimeType)
+
+      val intent = if (shareUris.size == 1) {
+        Intent(Intent.ACTION_SEND).apply {
+          type = resolvedMime
+          putExtra(Intent.EXTRA_STREAM, shareUris[0])
+          clipData = ClipData.newUri(
+            reactApplicationContext.contentResolver,
+            "shared_media",
+            shareUris[0]
+          )
+        }
+      } else {
+        Intent(Intent.ACTION_SEND_MULTIPLE).apply {
+          type = resolvedMime
+          // Uri is a Parcelable; putParcelableArrayListExtra accepts ArrayList<out Parcelable>.
+          putParcelableArrayListExtra(Intent.EXTRA_STREAM, shareUris)
+          clipData = ClipData.newUri(
+            reactApplicationContext.contentResolver,
+            "shared_media",
+            shareUris.first()
+          )
+        }
+      }
+
+      intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+
+      val chooser = Intent.createChooser(
+        intent,
+        Localization.getString("share", "Share")
+      )
+      chooser.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+
+      // Explicitly grant URI read permission to all target apps that can handle
+      // the underlying share intent. Querying the chooser itself may only return
+      // the chooser activity rather than real share recipients.
+      try {
+        val pm = reactApplicationContext.packageManager
+        val resInfoList = pm.queryIntentActivities(intent, PackageManager.MATCH_DEFAULT_ONLY)
+        for (resolveInfo in resInfoList) {
+          val packageName = resolveInfo.activityInfo.packageName
+          for (uri in shareUris) {
+            try {
+              reactApplicationContext.grantUriPermission(packageName, uri, Intent.FLAG_GRANT_READ_URI_PERMISSION)
+            } catch (e: Exception) {
+              // Best-effort: ignore failures to grant to a particular package
+            }
+          }
+        }
+      } catch (e: Exception) {
+        // Ignore any failures querying package manager — fallback to intent flags
+      }
+
+      val activity = reactApplicationContext.currentActivity
+      if (activity != null) {
+        activity.startActivity(chooser)
+      } else {
+        val appContext = reactApplicationContext.applicationContext
+        chooser.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        appContext.startActivity(chooser)
+      }
+      promise.resolve(true)
+    } catch (e: ActivityNotFoundException) {
+      promise.resolve(false)
+    } catch (e: Exception) {
+      promise.reject("SHARE_ERROR", e.message)
+    }
+  }
+
+  @ReactMethod
+  override fun setCameraFlash(mode: String, promise: Promise) {
+    saveSetting("flashMode", mode)
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  override fun setCameraTimer(delaySeconds: Double, promise: Promise) {
+    saveSetting("timerDelay", delaySeconds.toInt())
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  override fun enableCameraGrid(enabled: Boolean, promise: Promise) {
+    saveSetting("gridEnabled", enabled)
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  override fun setMediaCaption(uri: String, caption: String, promise: Promise) {
+    promise.resolve(true)
+  }
+
+  @ReactMethod
+    override fun getMediaMetadata(uri: String, promise: Promise) {
+      try {
+        val parsedUri = android.net.Uri.parse(uri)
+        val map = Arguments.createMap()
+        map.putString("uri", uri)
+
+        reactApplicationContext.contentResolver.query(parsedUri, null, null, null, null)?.use { cursor ->
+          if (cursor.moveToFirst()) {
+            // Basic file info
+            val sizeIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.SIZE)
+            if (sizeIndex != -1) map.putDouble("size", cursor.getLong(sizeIndex).toDouble())
+
+            // Only accept POSITIVE geometry/duration from MediaStore. The columns exist but
+            // read back 0 for plenty of entries (anything not yet scanned, and every
+            // provider-backed derived file), and storing a 0 here would satisfy the hasKey()
+            // checks below — suppressing the file probe and handing the caller a zero-sized
+            // clip it can only fall back to stale dimensions for.
+            val widthIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.WIDTH)
+            if (widthIndex != -1) {
+              cursor.getInt(widthIndex).takeIf { it > 0 }?.let { map.putInt("width", it) }
+            }
+
+            val heightIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.HEIGHT)
+            if (heightIndex != -1) {
+              cursor.getInt(heightIndex).takeIf { it > 0 }?.let { map.putInt("height", it) }
+            }
+
+            // Media type and duration (for videos)
+            val durationIndex = cursor.getColumnIndex(VideoColumns.DURATION)
+            if (durationIndex != -1) {
+              cursor.getLong(durationIndex).takeIf { it > 0 }?.let { map.putLong("duration", it) }
+            }
+
+            // Date information
+            val dateTakenIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.DATE_TAKEN)
+            if (dateTakenIndex != -1) map.putLong("dateTaken", cursor.getLong(dateTakenIndex))
+
+            // Location information
+            val latitudeIndex = cursor.getColumnIndex(VideoColumns.LATITUDE)
+            if (latitudeIndex != -1) map.putDouble("latitude", cursor.getDouble(latitudeIndex))
+
+            val longitudeIndex = cursor.getColumnIndex(VideoColumns.LONGITUDE)
+            if (longitudeIndex != -1) map.putDouble("longitude", cursor.getDouble(longitudeIndex))
+
+            // MIME type
+            val mimeTypeIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.MIME_TYPE)
+            if (mimeTypeIndex != -1) map.putString("mimeType", cursor.getString(mimeTypeIndex))
+
+            // Display name
+            val displayNameIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.DISPLAY_NAME)
+            if (displayNameIndex != -1) map.putString("fileName", cursor.getString(displayNameIndex))
+          }
+        }
+        // MediaStore only knows WIDTH/HEIGHT/DURATION for media it indexed. A FileProvider
+        // (content://…camera.fileprovider/…) or file:// URI — e.g. the output of compressVideo —
+        // exposes none of them, so read them from the file itself. Without this the caller has no
+        // way to learn a derived clip's real geometry and would have to reuse the source's.
+        if (!map.hasKey("width") || !map.hasKey("height") || !map.hasKey("duration")) {
+          // First try the usual retriever probe which accepts a Context+Uri. Some providers
+          // (or OS/device combinations) may fail for FileProvider-backed content URIs, so
+          // fall back to probing via an open FileDescriptor if the first attempt returns null.
+          readVideoDisplayMetadata(parsedUri)?.let { (dims, durationMs) ->
+            val (w, h) = dims
+            if (!map.hasKey("width") && w != null) map.putInt("width", w)
+            if (!map.hasKey("height") && h != null) map.putInt("height", h)
+            if (!map.hasKey("duration") && durationMs != null) map.putDouble("duration", durationMs.toDouble())
+          }
+
+          // Judge the first probe by what it actually produced, not by whether it returned at
+          // all: a retriever that yields only a duration still leaves the caller without the
+          // geometry it asked for, so the descriptor probe must still get its turn.
+          if (!map.hasKey("width") || !map.hasKey("height")) {
+            // Fallback: try opening a file descriptor and probe from it. This works with
+            // FileProvider and other content URIs that grant read access via a descriptor.
+            var pfd: android.content.res.AssetFileDescriptor? = null
+            try {
+              pfd = reactApplicationContext.contentResolver.openAssetFileDescriptor(parsedUri, "r")
+              pfd?.fileDescriptor?.let { fd ->
+                val retriever = android.media.MediaMetadataRetriever()
+                try {
+                  retriever.setDataSource(fd)
+                  var w = retriever.extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)?.toIntOrNull()
+                  var h = retriever.extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)?.toIntOrNull()
+                  val duration = retriever.extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_DURATION)?.toLongOrNull()
+                  val rotation = retriever.extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_VIDEO_ROTATION)?.toIntOrNull() ?: 0
+                  if (rotation == 90 || rotation == 270) {
+                    val swap = w
+                    w = h
+                    h = swap
+                  }
+                  if (!map.hasKey("width") && w != null) map.putInt("width", w)
+                  if (!map.hasKey("height") && h != null) map.putInt("height", h)
+                  if (!map.hasKey("duration") && duration != null) map.putDouble("duration", duration.toDouble())
+                } finally {
+                  retriever.release()
+                }
+              }
+            } catch (e: Exception) {
+              // Best-effort only — ignore and return whatever we could find.
+              Log.w("CustomCameraModule", "Fallback metadata probe failed for $uri", e)
+            } finally {
+              try { pfd?.close() } catch (_: Exception) {}
+            }
+          }
+        }
+        promise.resolve(map)
+      } catch (e: Exception) {
+        promise.reject("METADATA_ERROR", e.message)
+      }
+    }
+
+  /**
+   * The byte length of the exact clip the recording process finalized under [mediaId], or 0 when
+   * the native layer remembers none.
+   *
+   * A just-recorded clip's cached file is replaced in the background by a smaller aspect-cropped
+   * re-encode (CustomCameraActivity.scheduleBackgroundVideoCrop), so a fresh stat of the file on
+   * disk no longer matches the size the recording counter approached. This returns the pre-crop
+   * recorded length so the JS preview can quote the SAME number the recording counter showed and
+   * the editor's "Original video" row shows (both read from [PendingCaptureCrops]), instead of the
+   * smaller cropped file now on disk.
+   *
+   * It is present only for a clip recorded in THIS session: a gallery import, a user-compressed
+   * copy (published under a fresh id), a trimmed/replaced clip (its remembered length forgotten),
+   * or any clip after an app restart all yield 0 — and the caller then falls back to the honest
+   * on-disk size, exactly as the native Original row falls back to its own measurement.
+   */
+  @ReactMethod
+  override fun getRecordedOriginalSize(mediaId: String, promise: Promise) {
+    promise.resolve(PendingCaptureCrops.recordedOriginalBytes(mediaId).toDouble())
+  }
+
+  @ReactMethod
+  override fun trimVideo(uri: String, startTime: Double, endTime: Double, promise: Promise) {
+    // Basic stub for video trimming
+    promise.resolve(uri)
+  }
+
+  /**
+   * Rotation-corrected display dimensions and duration of the video at [uri], read straight from
+   * the file. Width/height are swapped for 90/270 rotations (mirrors
+   * MediaCacheManager.extractVideoMetadata) so they describe the frame exactly as it appears on
+   * screen. Returns null when the URI isn't a readable video.
+   *
+   * MUST use try/finally, never Kotlin's `.use {}` — MediaMetadataRetriever is only AutoCloseable
+   * from API 29, so `.use {}` crashes on API 24-28.
+   */
+  private fun readVideoDisplayMetadata(
+    uri: android.net.Uri
+  ): Pair<Pair<Int?, Int?>, Long?>? {
+    return try {
+      val retriever = android.media.MediaMetadataRetriever()
+      try {
+        retriever.setDataSource(reactApplicationContext, uri)
+        var width = retriever
+          .extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)?.toIntOrNull()
+        var height = retriever
+          .extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)?.toIntOrNull()
+        val duration = retriever
+          .extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_DURATION)?.toLongOrNull()
+        val rotation = retriever
+          .extractMetadata(android.media.MediaMetadataRetriever.METADATA_KEY_VIDEO_ROTATION)?.toIntOrNull() ?: 0
+        if (rotation == 90 || rotation == 270) {
+          val swap = width
+          width = height
+          height = swap
+        }
+        if (width == null && height == null && duration == null) null
+        else Pair(Pair(width?.takeIf { it > 0 }, height?.takeIf { it > 0 }), duration?.takeIf { it > 0 })
+      } finally {
+        retriever.release()
+      }
+    } catch (e: Exception) {
+      Log.w("CustomCameraModule", "Failed to read video metadata for $uri", e)
+      null
+    }
+  }
+
+  /**
+   * A readable [File] for a source URI, plus whether it is a throwaway copy this call staged.
+   * A `content://` source has to be streamed into the cache first; that staging copy is a
+   * DERIVED temp and must be deleted once the operation is done — the caller owns it. A
+   * `file://` (or bare path) source is the caller's own file and is never touched.
+   */
+  private data class ResolvedInput(val file: File, val isTemporaryCopy: Boolean)
+
+  /**
+   * @param stagedExtension extension for the staging copy of a `content://` source. It matters:
+   *   the still-image decoders dispatch on the file name, so an image staged as `.mp4` decodes as
+   *   nothing at all. Defaults to the video case, which is what every caller but [compressImage]
+   *   wants.
+   */
+  private fun resolveInputFile(
+    context: android.content.Context,
+    uriString: String,
+    stagedExtension: String = "mp4"
+  ): ResolvedInput? {
+    return try {
+      val parsed = android.net.Uri.parse(uriString)
+      val scheme = parsed.scheme?.lowercase()
+      if (scheme == null || scheme == "file") {
+        val path = parsed.path ?: uriString
+        ResolvedInput(File(path), isTemporaryCopy = false)
+      } else if (scheme == "content") {
+        val tempFile = File(
+          context.cacheDir,
+          CompressionFileNameUtils.createUniqueFileName("temp_src", stagedExtension)
+        )
+        val inputStream = context.contentResolver.openInputStream(parsed)
+        if (inputStream != null) {
+          inputStream.use { input ->
+            java.io.FileOutputStream(tempFile).use { output ->
+              input.copyTo(output)
+            }
+          }
+        }
+        ResolvedInput(tempFile, isTemporaryCopy = true)
+      } else {
+        ResolvedInput(File(uriString), isTemporaryCopy = false)
+      }
+    } catch (e: Exception) {
+      Log.w("CustomCameraModule", "Failed to resolve input file for URI $uriString", e)
+      null
+    }
+  }
+
+  /**
+   * The quality ratio a menu option string asks for, in 0.05..1.0.
+   *
+   * Any "Original …" option ("Original Video", "Original Image") means "leave it alone" and maps
+   * to 1.0 — matched on the prefix so both media kinds are covered by the one rule.
+   */
+  private fun parseCompressionRatio(option: String): Float {
+    val clean = option.trim()
+    if (clean.startsWith("Original", ignoreCase = true)) return 1.0f
+    val digits = clean.replace("%", "").trim()
+    val parsed = digits.toFloatOrNull() ?: return 1.0f
+    return if (parsed > 1.0f) {
+      (parsed / 100.0f).coerceIn(0.05f, 1.0f)
+    } else {
+      parsed.coerceIn(0.05f, 1.0f)
+    }
+  }
+
+  @ReactMethod
+  override fun compressVideo(uri: String, qualityOrOption: String, promise: Promise) {
+    CoroutineScope(Dispatchers.IO).launch {
+      try {
+        val ratio = parseCompressionRatio(qualityOrOption)
+        if (ratio >= 1.0f) {
+          // Only a true "Original …" pick (quality ratio 1.0) is handed back untouched. Every
+          // level below it — including the lightest, 99% — still runs the transcode so the caller
+          // gets a genuinely re-encoded file at the requested quality.
+          promise.resolve(uri)
+          return@launch
+        }
+
+        val context = reactApplicationContext
+        val resolved = resolveInputFile(context, uri)
+        if (resolved == null || !resolved.file.exists()) {
+          promise.reject("FILE_NOT_FOUND", "Source video file not found for compression")
+          return@launch
+        }
+        val inputFile = resolved.file
+
+        try {
+          // Write into the FileProvider-covered cache/compressed/ subdirectory (see
+          // res/xml/file_paths.xml). The cache ROOT is not covered, so an output written there
+          // made FileProvider.getUriForFile throw and silently fall back to a file:// URI —
+          // a URI the caller cannot reliably read metadata from or hand to a player. The
+          // resolved content:// URI is what makes the compressed clip a first-class source.
+          val outputDir = File(context.cacheDir, "compressed").apply { mkdirs() }
+          val outputFile = File(
+            outputDir,
+            CompressionFileNameUtils.createUniqueFileName(
+              "compressed_${(ratio * 100).toInt()}",
+              "mp4"
+            )
+          )
+
+          // The source is only ever READ: compress() writes a separate file and never
+          // overwrites, moves, or deletes its input. The progress sink is display-only: the
+          // transcode never waits on the emit, and a JS side that ignores the event sees exactly
+          // the behaviour it saw before.
+          val success = VideoRotationTranscoder.compress(
+            inputFile,
+            outputFile,
+            ratio,
+            onProgress = { emitCompressionProgress(uri, qualityOrOption, it) }
+          )
+          if (success && outputFile.exists() && outputFile.length() > 0) {
+            promise.resolve(getSecureUriForFile(outputFile))
+          } else {
+            runCatching { outputFile.delete() }
+            promise.reject("COMPRESS_FAILED", "Failed to generate compressed video file")
+          }
+        } finally {
+          // Drop the staged copy of a content:// source (never the caller's own file).
+          if (resolved.isTemporaryCopy) runCatching { inputFile.delete() }
+        }
+      } catch (e: Exception) {
+        promise.reject("COMPRESS_ERROR", e.message ?: "Error during video compression")
+      }
+    }
+  }
+
+  /**
+   * Re-encode the still at [uri] smaller and resolve with a URI for the new file.
+   *
+   * The still-image twin of [compressVideo], and it follows the same contract exactly:
+   *
+   *  - [qualityOrOption] is a QUALITY RATIO — "25%" / "0.25" both mean "keep a quarter", and only
+   *    a true "Original …" option (quality ratio 1.0) resolves the input URI back untouched
+   *    without creating, modifying or deleting a single file. Every level below it — down to 5% and
+   *    up to 99% — runs the encoder.
+   *  - The source is only ever READ. The compressed copy is a separate file under the
+   *    FileProvider-covered `cache/compressed/` subdirectory, so the resolved `content://` URI is
+   *    one the caller can actually read metadata from and hand to an image view (the cache ROOT is
+   *    not covered by @xml/file_paths, and an output written there silently degrades to a `file://`
+   *    URI).
+   *
+   * The output's container is chosen by [ImageExporter.compressionFormatFor] — JPEG, or lossy WebP
+   * when the source could be carrying transparency — so the returned file's name always describes
+   * its bytes. A source that is already as small as it can get is not an error: there is nothing
+   * to gain from a bigger "compressed" copy, so the original URI is resolved instead.
+   */
+  @ReactMethod
+  override fun compressImage(uri: String, qualityOrOption: String, promise: Promise) {
+    CoroutineScope(Dispatchers.IO).launch {
+      try {
+        val ratio = parseCompressionRatio(qualityOrOption)
+        if (ratio >= 1.0f) {
+          // Original selected (quality ratio 1.0) — resolve the original URI without touching any
+          // file. 99% and every lighter-than-Original level still run the encoder below.
+          promise.resolve(uri)
+          return@launch
+        }
+
+        val context = reactApplicationContext
+        // Stage a content:// source under its OWN extension: BitmapFactory and ImageDecoder both
+        // dispatch on the file name, so a JPEG staged as "temp_src…mp4" decodes as nothing.
+        val sourceFormat = ImageFormatSupport.fromFileName(uri)
+          ?: ImageFormatSupport.fromMimeType(
+            runCatching { context.contentResolver.getType(android.net.Uri.parse(uri)) }.getOrNull()
+          )
+        val resolved = resolveInputFile(context, uri, sourceFormat?.extension ?: "jpg")
+        if (resolved == null || !resolved.file.exists()) {
+          promise.reject("FILE_NOT_FOUND", "Source image file not found for compression")
+          return@launch
+        }
+        val inputFile = resolved.file
+
+        try {
+          // Percent to SHAVE, which is what ImageExporter.compress takes — the inverse of the
+          // quality ratio this method's option string carries.
+          val percent = Math.round((1f - ratio) * 100f)
+          val outputDir = File(context.cacheDir, "compressed").apply { mkdirs() }
+          val outputFile = File(
+            outputDir,
+            CompressionFileNameUtils.createUniqueFileName(
+              "compressed_$percent",
+              ImageExporter.compressionFormatFor(inputFile).extension
+            )
+          )
+
+          // The source is only ever READ: compress() writes a separate file and never overwrites,
+          // moves or deletes its input.
+          val compressed = ImageExporter.compress(
+            inputFile,
+            outputFile,
+            percent,
+            onProgress = { emitCompressionProgress(uri, qualityOrOption, it) }
+          )
+          when (compressed) {
+            is ImageExporter.CompressOutcome.Success ->
+              promise.resolve(getSecureUriForFile(outputFile))
+            // Nothing smaller was achievable, so nothing was written. Hand back the original
+            // rather than a copy that would only be larger.
+            ImageExporter.CompressOutcome.AlreadyMinimal -> {
+              runCatching { outputFile.delete() }
+              promise.resolve(uri)
+            }
+            ImageExporter.CompressOutcome.Failed -> {
+              runCatching { outputFile.delete() }
+              promise.reject("COMPRESS_FAILED", "Failed to generate compressed image file")
+            }
+          }
+        } finally {
+          // Drop the staged copy of a content:// source (never the caller's own file).
+          if (resolved.isTemporaryCopy) runCatching { inputFile.delete() }
+        }
+      } catch (e: Exception) {
+        promise.reject("COMPRESS_ERROR", e.message ?: "Error during image compression")
+      }
+    }
+  }
+
+  /**
+   * Emit one measured compression-progress report to JS on the `onCompressionProgress` device
+   * event: `{ uri, option, progress }`, where `progress` is 0..1 and `uri` / `option` are the exact
+   * arguments the [compressVideo] / [compressImage] call was made with, so a screen running one
+   * compression at a time can tell a live report from a stale one.
+   *
+   * This is what lets a JS overlay show a REAL remaining time — `elapsed / progress` gives the
+   * total the job is actually on course for — instead of counting a fixed prediction down and
+   * either running out mid-compression or still promising seconds after it has finished.
+   *
+   * Fire-and-forget by design. The compressors throttle their own reporting, the emit is wrapped
+   * so a torn-down React instance cannot fail a compression that is otherwise fine, and nothing in
+   * either compression path reads the result: an unlistened event costs a map allocation.
+   */
+  private fun emitCompressionProgress(uri: String, option: String, progress: Float) {
+    runCatching {
+      val payload = Arguments.createMap().apply {
+        putString("uri", uri)
+        putString("option", option)
+        putDouble("progress", progress.coerceIn(0f, 1f).toDouble())
+      }
+      reactApplicationContext
+        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit(EVENT_COMPRESSION_PROGRESS, payload)
+    }
+  }
+
+  @ReactMethod
+  override fun scanQRCode(promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("NO_ACTIVITY", "Activity not available")
+      return
+    }
+
+    if (pendingBarcodePromise != null) {
+      promise.reject("SCAN_ALREADY_OPEN", "A scan is already in progress")
+      return
+    }
+
+    pendingBarcodePromise = promise
+    try {
+      activity.startActivityForResult(
+        BarcodeScannerActivity.createIntent(activity),
+        BARCODE_SCAN_REQUEST
+      )
+    } catch (exception: RuntimeException) {
+      pendingBarcodePromise = null
+      promise.reject("SCAN_ERROR", "Unable to open barcode scanner", exception)
+    }
+  }
+
+  @ReactMethod
+  override fun enableFaceDetection(enabled: Boolean, promise: Promise) {
+    saveSetting("faceDetectionEnabled", enabled)
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  override fun setFaceEffect(effectType: String, promise: Promise) {
+    saveSetting("faceEffect", effectType)
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  override fun setCameraTheme(theme: String, promise: Promise) {
+    saveSetting("cameraTheme", theme)
+    CameraTheme.invalidate()
+    promise.resolve(null)
+  }
+
+  @ReactMethod
+  override fun setCameraConfig(configJson: String, promise: Promise) {
+    saveSetting("cameraConfig", configJson)
+    CameraTheme.invalidate()
+    promise.resolve(null)
+  }
+
+  // ===== Audio Recording Methods =====
+
+  /**
+   * Start recording audio using the native MediaRecorder API.
+   *
+   * Supported options (all optional with sensible defaults):
+   * - `outputFormat` — `"mpeg4"` (default), `"aac_adts"`, `"amr_nb"`, `"amr_wb"`, `"three_gpp"`
+   * - `audioEncoder` — `"aac"` (default), `"amr_nb"`, `"amr_wb"`, `"he_aac"`
+   * - `audioSource` — `"mic"` (default), `"camcorder"`, `"voice_recognition"`, `"voice_communication"`
+   * - `bitRate` — e.g. `128000` (default)
+   * - `sampleRate` — e.g. `44100` (default)
+   * - `meteringIntervalMs` — ms between amplitude callbacks (0 = disabled)
+   *
+   * Resolves with `{ filePath, mimeType }` on success.
+   * Rejects with `RECORD_AUDIO_ERROR` on failure.
+   */
+  @ReactMethod
+  override fun startAudioRecording(options: ReadableMap, promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("RECORD_AUDIO_ERROR", "Activity not available")
+      return
+    }
+
+    try {
+      // Set the react context on the recorder so it can emit JS events.
+      AudioRecorder.setReactContext(reactApplicationContext)
+
+      val config = AudioRecorder.Config(
+        outputFormat = parseOutputFormat(options.getString("outputFormat")),
+        audioEncoder = parseAudioEncoder(options.getString("audioEncoder")),
+        audioSource = parseAudioSource(options.getString("audioSource")),
+        bitRate = if (options.hasKey("bitRate")) options.getInt("bitRate") else 128000,
+        sampleRate = if (options.hasKey("sampleRate")) options.getInt("sampleRate") else 44100,
+        fileName = if (options.hasKey("fileName")) options.getString("fileName") else null,
+        meteringIntervalMs = if (options.hasKey("meteringIntervalMs")) options.getDouble("meteringIntervalMs").toLong() else 0L,
+      )
+
+      val result = AudioRecorder.startRecording(activity, config)
+      promise.resolve(result)
+    } catch (e: SecurityException) {
+      promise.reject("RECORD_AUDIO_ERROR", "Microphone permission not granted: ${e.message}", e)
+    } catch (e: IllegalStateException) {
+      promise.reject("RECORD_AUDIO_ERROR", e.message, e)
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to start recording: ${e.message}", e)
+    }
+  }
+
+  /**
+   * Stop the active recording and finalise the audio file.
+   * Resolves with `{ filePath, durationMs, fileSizeBytes, mimeType }`.
+   */
+  @ReactMethod
+  override fun stopAudioRecording(promise: Promise) {
+    try {
+      val result = AudioRecorder.stopRecording()
+      promise.resolve(result)
+    } catch (e: IllegalStateException) {
+      promise.reject("RECORD_AUDIO_ERROR", e.message, e)
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to stop recording: ${e.message}", e)
+    }
+  }
+
+  /**
+   * Cancel the active recording and delete the temporary file.
+   * Resolves with `{ deleted: boolean }`.
+   */
+  @ReactMethod
+  override fun cancelAudioRecording(promise: Promise) {
+    try {
+      val deleted = AudioRecorder.cancelRecording()
+      val result = Arguments.createMap().apply {
+        putBoolean("deleted", deleted)
+      }
+      promise.resolve(result)
+    } catch (e: IllegalStateException) {
+      promise.reject("RECORD_AUDIO_ERROR", e.message, e)
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to cancel recording: ${e.message}", e)
+    }
+  }
+
+  /**
+   * Stop the active recording, validate the file, move it to the Documents
+   * directory, and return the finalized audio asset.
+   *
+   * The file is validated (must exist, be non-empty, and at least 200 bytes)
+   * before being moved. On success the temp file is deleted. The returned map
+   * contains the full asset metadata suitable for SQLCipher persistence.
+   *
+   * Resolves with an asset map: `{ id, uri, type, documentUri, fileName,
+   *   mimeType, size, duration, dateTaken }`.
+   * Rejects with `RECORD_AUDIO_ERROR` on validation or move failure.
+   */
+  @ReactMethod
+  override fun stopAndPublishAudioRecording(promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity == null) {
+      promise.reject("RECORD_AUDIO_ERROR", "Activity not available")
+      return
+    }
+
+    try {
+      // 1. Stop the recorder on the bridge thread (MediaRecorder is not thread-safe).
+      val raw = AudioRecorder.stopRecording()
+
+      val cachePath = raw.getString("filePath") ?: ""
+      val durationMs = raw.getDouble("durationMs")
+      val mimeType = raw.getString("mimeType") ?: "audio/mp4"
+
+      // 2. Move file to Documents + validate on a background thread to avoid
+      //    blocking the React Native bridge while the copy is in flight.
+      runOnBackgroundThread {
+        try {
+          val cacheFile = java.io.File(cachePath)
+          if (!cacheFile.exists()) {
+            promise.reject("RECORD_AUDIO_ERROR", "Recorded file does not exist")
+            return@runOnBackgroundThread
+          }
+          if (cacheFile.length() < 200L) {
+            cacheFile.delete()
+            promise.reject(
+              "RECORD_AUDIO_ERROR",
+              "Recording too short or empty (${cacheFile.length()} bytes)"
+            )
+            return@runOnBackgroundThread
+          }
+
+          // Derive extension from the actual MIME type so we never mislabel.
+          val ext = when (mimeType) {
+            "audio/aac"     -> "aac"
+            "audio/amr"     -> "amr"
+            "audio/amr-wb"  -> "amr"
+            "audio/3gpp"    -> "3gp"
+            else             -> "m4a"
+          }
+
+          val documentDir = reactApplicationContext.getExternalFilesDir(
+            android.os.Environment.DIRECTORY_DOCUMENTS
+          ) ?: reactApplicationContext.filesDir
+          val audioDir = java.io.File(documentDir, "media_documents/audio").apply { mkdirs() }
+          val fileName = "recording_${System.currentTimeMillis()}.$ext"
+          val targetFile = java.io.File(audioDir, fileName)
+
+          java.io.FileInputStream(cacheFile).use { input ->
+            java.io.FileOutputStream(targetFile).use { output ->
+              input.copyTo(output)
+            }
+          }
+
+          // Verify the target file, then clean up the cache file.
+          if (!targetFile.exists() || targetFile.length() < 200L) {
+            targetFile.delete()
+            promise.reject("RECORD_AUDIO_ERROR", "Target file invalid after move")
+            return@runOnBackgroundThread
+          }
+          cacheFile.delete()
+
+          // Generate a FileProvider content URI for the finalized file.
+          val documentUri = try {
+            androidx.core.content.FileProvider.getUriForFile(
+              reactApplicationContext,
+              "${reactApplicationContext.packageName}.camera.fileprovider",
+              targetFile
+            ).toString()
+          } catch (_: Exception) {
+            android.net.Uri.fromFile(targetFile).toString()
+          }
+
+          val assetId = "audio_${System.currentTimeMillis()}"
+          val asset = Arguments.createMap().apply {
+            putString("id", assetId)
+            putString("uri", documentUri)
+            putString("documentUri", documentUri)
+            putString("type", "audio")
+            putString("fileName", fileName)
+            putString("mimeType", mimeType)
+            putDouble("size", targetFile.length().toDouble())
+            putDouble("duration", durationMs)
+            putDouble("dateTaken", System.currentTimeMillis().toDouble())
+          }
+
+          Log.i(NAME, "Audio recording published: $documentUri (${targetFile.length()} bytes, ${durationMs}ms)")
+          promise.resolve(asset)
+        } catch (e: Exception) {
+          promise.reject("RECORD_AUDIO_ERROR", "Failed to publish recording: ${e.message}", e)
+        }
+      }
+    } catch (e: IllegalStateException) {
+      promise.reject("RECORD_AUDIO_ERROR", e.message, e)
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to stop and publish recording: ${e.message}", e)
+    }
+  }
+
+  /**
+   * Pause the active recording. Requires API 24+.
+   * On older API levels this rejects with `RECORD_AUDIO_ERROR`.
+   */
+  @ReactMethod
+  override fun pauseAudioRecording(promise: Promise) {
+    try {
+      AudioRecorder.pauseRecording()
+      promise.resolve(null)
+    } catch (e: UnsupportedOperationException) {
+      promise.reject("RECORD_AUDIO_ERROR", "Pause/resume requires Android 7.0 (API 24) or later", e)
+    } catch (e: IllegalStateException) {
+      promise.reject("RECORD_AUDIO_ERROR", e.message, e)
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to pause recording: ${e.message}", e)
+    }
+  }
+
+  /**
+   * Resume a paused recording. Requires API 24+.
+   */
+  @ReactMethod
+  override fun resumeAudioRecording(promise: Promise) {
+    try {
+      AudioRecorder.resumeRecording()
+      promise.resolve(null)
+    } catch (e: UnsupportedOperationException) {
+      promise.reject("RECORD_AUDIO_ERROR", "Pause/resume requires Android 7.0 (API 24) or later", e)
+    } catch (e: IllegalStateException) {
+      promise.reject("RECORD_AUDIO_ERROR", e.message, e)
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to resume recording: ${e.message}", e)
+    }
+  }
+
+  /**
+   * Get the current recording state as a map.
+   * Resolves with `{ state, filePath, durationMs, isPauseSupported }`.
+   */
+  @ReactMethod
+  override fun getAudioRecordingState(promise: Promise) {
+    try {
+      promise.resolve(AudioRecorder.getStateMap())
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to get recording state: ${e.message}", e)
+    }
+  }
+
+  /**
+   * Get the current maximum amplitude from the active MediaRecorder.
+   * Useful for building waveform visualisations.
+   */
+  @ReactMethod
+  override fun getAudioAmplitude(promise: Promise) {
+    try {
+      promise.resolve(AudioRecorder.getAmplitude())
+    } catch (e: Exception) {
+      promise.reject("RECORD_AUDIO_ERROR", "Failed to get amplitude: ${e.message}", e)
+    }
+  }
+
+  /** Parse output format string from JS into enum. */
+  private fun parseOutputFormat(value: String?): AudioRecorder.OutputFormat = when (value?.lowercase()) {
+    "mpeg4"    -> AudioRecorder.OutputFormat.MPEG_4
+    "aac_adts" -> AudioRecorder.OutputFormat.AAC_ADTS
+    "amr_nb"   -> AudioRecorder.OutputFormat.AMR_NB
+    "amr_wb"   -> AudioRecorder.OutputFormat.AMR_WB
+    "three_gpp" -> AudioRecorder.OutputFormat.THREE_GPP
+    else       -> AudioRecorder.OutputFormat.MPEG_4
+  }
+
+  /** Parse audio encoder string from JS into enum. */
+  private fun parseAudioEncoder(value: String?): AudioRecorder.AudioEncoder = when (value?.lowercase()) {
+    "aac"    -> AudioRecorder.AudioEncoder.AAC
+    "amr_nb" -> AudioRecorder.AudioEncoder.AMR_NB
+    "amr_wb" -> AudioRecorder.AudioEncoder.AMR_WB
+    "he_aac" -> AudioRecorder.AudioEncoder.HE_AAC
+    else     -> AudioRecorder.AudioEncoder.AAC
+  }
+
+  /** Parse audio source string from JS into enum. */
+  private fun parseAudioSource(value: String?): AudioRecorder.AudioSource = when (value?.lowercase()) {
+    "mic"                 -> AudioRecorder.AudioSource.MIC
+    "camcorder"            -> AudioRecorder.AudioSource.CAMCORDER
+    "voice_recognition"    -> AudioRecorder.AudioSource.VOICE_RECOGNITION
+    "voice_communication"  -> AudioRecorder.AudioSource.VOICE_COMMUNICATION
+    else                   -> AudioRecorder.AudioSource.MIC
+  }
+
+  // ===== Media Storage Methods =====
+
+  /**
+   * Initialize media storage workflow
+   */
+  @ReactMethod
+  override fun initializeMediaStorage(promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        workflow.initialize()
+        promise.resolve(Arguments.createMap().apply {
+          putBoolean("success", true)
+          putString("message", "Media storage initialized")
+        })
+      }
+    } catch (e: Exception) {
+      promise.reject("STORAGE_INIT_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Publish media (move/copy from cache to documents)
+   */
+  @ReactMethod
+  override fun publishMedia(mediaId: String, moveMode: Boolean, promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val result = workflow.publishMedia(mediaId, moveMode)
+        val resultMap = Arguments.createMap().apply {
+          putBoolean("success", result.success)
+          putString("mediaId", result.mediaId)
+          result.targetUri?.let { putString("targetUri", it) }
+          result.fileHash?.let { putString("fileHash", it) }
+          result.error?.let { putString("error", it) }
+        }
+        promise.resolve(resultMap)
+      }
+    } catch (e: Exception) {
+      promise.reject("PUBLISH_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Publish multiple media in batch
+   */
+  @ReactMethod
+  override fun publishBatch(mediaIds: ReadableArray, moveMode: Boolean, promise: Promise) {
+    try {
+      val ids = (0 until mediaIds.size()).mapNotNull { mediaIds.getString(it) }
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val result = workflow.publishBatch(ids, moveMode)
+        val resultMap = Arguments.createMap().apply {
+          putInt("totalCount", result.totalCount)
+          putInt("successCount", result.successCount)
+          putInt("failureCount", result.failureCount)
+          result.error?.let { putString("error", it) }
+        }
+        promise.resolve(resultMap)
+      }
+    } catch (e: Exception) {
+      promise.reject("BATCH_PUBLISH_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Get cached media list
+   */
+  @ReactMethod
+  override fun getCachedMedia(promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val cachedMedia = workflow.getCachedMedia()
+        val array = Arguments.createArray()
+        cachedMedia.forEach { media ->
+          array.pushMap(Arguments.createMap().apply {
+            putString("id", media.id)
+            putString("fileName", media.fileName)
+            putString("fileType", media.fileType)
+            putDouble("fileSize", media.fileSize.toDouble())
+            media.width?.let { putInt("width", it) }
+            media.height?.let { putInt("height", it) }
+            media.duration?.let { putDouble("duration", it.toDouble()) }
+            putDouble("cacheCreatedAt", media.cacheCreatedAt.toDouble())
+            putDouble("cacheLastModified", media.cacheLastModified.toDouble())
+          })
+        }
+        promise.resolve(array)
+      }
+    } catch (e: Exception) {
+      promise.reject("GET_CACHED_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Get published media list
+   */
+  @ReactMethod
+  override fun getPublishedMedia(promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val publishedMedia = workflow.getPublishedMedia()
+        val array = Arguments.createArray()
+        publishedMedia.forEach { media ->
+          array.pushMap(Arguments.createMap().apply {
+            putString("id", media.id)
+            putString("fileName", media.fileName)
+            putString("fileType", media.fileType)
+            putDouble("fileSize", media.fileSize.toDouble())
+            media.width?.let { putInt("width", it) }
+            media.height?.let { putInt("height", it) }
+            media.duration?.let { putDouble("duration", it.toDouble()) }
+            media.documentUri?.let { putString("documentUri", it) }
+            media.publishedAt?.let { putDouble("publishedAt", it.toDouble()) }
+          })
+        }
+        promise.resolve(array)
+      }
+    } catch (e: Exception) {
+      promise.reject("GET_PUBLISHED_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Get storage statistics
+   */
+  @ReactMethod
+  override fun getStorageStats(promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val stats = workflow.getStorageStats()
+        val resultMap = Arguments.createMap().apply {
+          putDouble("cacheUsedMB", stats.cacheUsedMB.toDouble())
+          putDouble("documentUsedMB", stats.documentUsedMB.toDouble())
+          putDouble("totalAvailableMB", stats.totalAvailableMB.toDouble())
+          putInt("cachedItemsCount", stats.cachedItemsCount)
+          putInt("publishedItemsCount", stats.publishedItemsCount)
+          putInt("duplicateItemsCount", stats.duplicateItemsCount)
+          putDouble("oldestCacheItemAge", stats.oldestCacheItemAge.toDouble())
+          putDouble("newestCacheItemAge", stats.newestCacheItemAge.toDouble())
+        }
+        promise.resolve(resultMap)
+      }
+    } catch (e: Exception) {
+      promise.reject("STORAGE_STATS_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Cleanup old cache files
+   */
+  @ReactMethod
+  override fun cleanupOldCache(olderThanDays: Double, promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val result = workflow.cleanupOldCache(olderThanDays)
+        val resultMap = Arguments.createMap().apply {
+          putBoolean("success", result.success)
+          putInt("filesRemoved", result.filesRemoved)
+          putDouble("spaceFreedMB", result.spaceFreedMB)
+          result.error?.let { putString("error", it) }
+        }
+        promise.resolve(resultMap)
+      }
+    } catch (e: Exception) {
+      promise.reject("CLEANUP_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Delete media by stored media id
+   */
+  @ReactMethod
+  override fun deleteStoredMedia(mediaId: String, promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val deleted = workflow.deleteMedia(mediaId)
+        promise.resolve(deleted)
+      }
+    } catch (e: Exception) {
+      promise.reject("DELETE_MEDIA_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Get failed transfers for retry
+   */
+  @ReactMethod
+  override fun getFailedTransfers(promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val failed = workflow.getFailedTransfers()
+        val array = Arguments.createArray()
+        failed.forEach { transfer ->
+          array.pushMap(Arguments.createMap().apply {
+            putString("mediaId", transfer.mediaId)
+            putString("error", transfer.error)
+            putDouble("failedAt", transfer.failedAt.toDouble())
+            putInt("retryCount", transfer.retryCount)
+          })
+        }
+        promise.resolve(array)
+      }
+    } catch (e: Exception) {
+      promise.reject("FAILED_TRANSFERS_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Retry failed transfers
+   */
+  @ReactMethod
+  override fun retryFailedTransfers(promise: Promise) {
+    try {
+      val workflow = MediaStorageWorkflow.getInstance(reactApplicationContext)
+      runOnBackgroundThread {
+        val results = workflow.retryFailedTransfers()
+        val array = Arguments.createArray()
+        results.forEach { result ->
+          array.pushMap(Arguments.createMap().apply {
+            putBoolean("success", result.success)
+            putString("mediaId", result.mediaId)
+            result.targetUri?.let { putString("targetUri", it) }
+            result.error?.let { putString("error", it) }
+          })
+        }
+        promise.resolve(array)
+      }
+    } catch (e: Exception) {
+      promise.reject("RETRY_FAILED_ERROR", e.message, e)
+    }
+  }
+
+  /**
+   * Run a task on background thread
+   */
+  private fun runOnBackgroundThread(task: suspend () -> Unit) {
+    val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
+    scope.launch {
+      try {
+        task()
+      } catch (e: Exception) {
+        Log.e(NAME, "Background task failed", e)
+      }
+    }
+  }
+
+  // ===== Global Audio Player Methods =====
+
+  @ReactMethod
+  override fun playAudio(uri: String, title: String, promise: Promise) {
+    try {
+      if (GlobalAudioPlayer.reactContext == null) {
+         GlobalAudioPlayer.reactContext = reactApplicationContext
+      }
+      val parsedUri = android.net.Uri.parse(uri)
+      reactApplicationContext.currentActivity?.let { activity ->
+          GlobalAudioPlayer.play(activity, parsedUri, title)
+      }
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("PLAY_AUDIO_ERROR", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  override fun pauseAudio(promise: Promise) {
+    try {
+      GlobalAudioPlayer.pause()
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("PAUSE_AUDIO_ERROR", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  override fun resumeAudio(promise: Promise) {
+    try {
+      GlobalAudioPlayer.resume()
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("RESUME_AUDIO_ERROR", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  override fun seekAudio(positionMs: Double, promise: Promise) {
+    try {
+      GlobalAudioPlayer.seekTo(positionMs.toInt())
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("SEEK_AUDIO_ERROR", e.message, e)
+    }
+  }
+
+  @ReactMethod
+  override fun stopAudio(promise: Promise) {
+    try {
+      GlobalAudioPlayer.release()
+      promise.resolve(null)
+    } catch (e: Exception) {
+      promise.reject("STOP_AUDIO_ERROR", e.message, e)
+    }
+  }
+
+  private fun saveSetting(key: String, value: Any) {
+    val prefs = reactApplicationContext.getSharedPreferences("CameraSettings", android.content.Context.MODE_PRIVATE)
+    val editor = prefs.edit()
+    when (value) {
+      is String -> editor.putString(key, value)
+      is Boolean -> editor.putBoolean(key, value)
+      is Int -> editor.putInt(key, value)
+      is Float -> editor.putFloat(key, value)
+      else -> throw IllegalArgumentException("Unsupported setting value type: ${value::class.java}")
+    }
+    editor.apply()
+  }
+
+  override fun invalidate() {
+    reactApplicationContext.removeActivityEventListener(activityEventListener)
+    pendingPickerPromise?.reject("PICKER_INVALIDATED", "Camera picker was invalidated")
+    pendingPickerPromise = null
+    super.invalidate()
+  }
+
+  private fun rejectUnsupported(promise: Promise, methodName: String) {
+    promise.reject("UNIMPLEMENTED", "$methodName is not implemented in this module")
+  }
+
+  private fun createResultMap(resultCode: Int, data: Intent?): WritableMap {
+    val result = Arguments.createMap()
+    if (resultCode != Activity.RESULT_OK || data == null) {
+      result.putBoolean("cancelled", true)
+      result.putArray("assets", Arguments.createArray())
+      return result
+    }
+
+    result.putBoolean("cancelled", data.getBooleanExtra(EXTRA_CANCELLED, false))
+    result.putArray("assets", data.getAssetBundles().toWritableArray())
+    return result
+  }
+
+  private fun Intent.getAssetBundles(): ArrayList<Bundle> {
+    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+      getParcelableArrayListExtra(EXTRA_ASSETS, Bundle::class.java) ?: arrayListOf()
+    } else {
+      @Suppress("DEPRECATION")
+      getParcelableArrayListExtra(EXTRA_ASSETS) ?: arrayListOf()
+    }
+  }
+
+  private fun ArrayList<Bundle>.toWritableArray(): WritableArray {
+    val array = Arguments.createArray()
+    forEach { bundle ->
+      val asset = Arguments.createMap()
+      asset.putString("id", bundle.getString("id"))
+      asset.putString("uri", bundle.getString("uri"))
+      asset.putString("type", bundle.getString("type"))
+      bundle.getString("fileName")?.let { asset.putString("fileName", it) }
+      bundle.getString("mimeType")?.let { asset.putString("mimeType", it) }
+      bundle.getString("caption")?.let { asset.putString("caption", it) }
+      putOptionalInt(asset, "width", bundle)
+      putOptionalInt(asset, "height", bundle)
+      putOptionalDouble(asset, "duration", bundle)
+      putOptionalDouble(asset, "size", bundle)
+      putOptionalDouble(asset, "dateTaken", bundle)
+      // Cache metadata (if present) — ensure JS receives updated cache path and flags
+      bundle.getString("cachePath")?.let { asset.putString("cachePath", it) }
+      if (bundle.containsKey("isCached")) asset.putBoolean("isCached", bundle.getBoolean("isCached"))
+      if (bundle.containsKey("cacheCreatedAt")) asset.putDouble("cacheCreatedAt", bundle.getDouble("cacheCreatedAt"))
+      if (bundle.containsKey("cacheLastModified")) asset.putDouble("cacheLastModified", bundle.getDouble("cacheLastModified"))
+      bundle.getString("originalUri")?.let { asset.putString("originalUri", it) }
+      putOptionalDouble(asset, "previewAspectRatio", bundle)
+      bundle.getString("coverUri")?.let { asset.putString("coverUri", it) }
+      putOptionalInt(asset, "captureContainerWidth", bundle)
+      putOptionalInt(asset, "captureContainerHeight", bundle)
+      if (bundle.containsKey("sizeIsDisplayEstimate")) {
+        asset.putBoolean("sizeIsDisplayEstimate", bundle.getBoolean("sizeIsDisplayEstimate"))
+      }
+      array.pushMap(asset)
+    }
+    return array
+  }
+
+  private fun putOptionalInt(map: WritableMap, key: String, bundle: Bundle) {
+    if (bundle.containsKey(key)) {
+      map.putInt(key, bundle.getInt(key))
+    }
+  }
+
+  private fun putOptionalDouble(map: WritableMap, key: String, bundle: Bundle) {
+    if (bundle.containsKey(key)) {
+      map.putDouble(key, bundle.getDouble(key))
+    }
+  }
+
+  /**
+   * Builds the SAF ACTION_OPEN_DOCUMENT intent shared by the document and audio pickers. A
+   * `selectionLimit` of 0 (unlimited) or > 1 enables multi-select; the accepted [mimeTypes] are
+   * applied via EXTRA_MIME_TYPES over a broad wildcard base type so the filter is honoured across
+   * the various OEM document providers.
+   */
+  private fun buildOpenDocumentIntent(options: ReadableMap, mimeTypes: Array<String>): Intent {
+    val selectionLimit = options.getIntOrDefault("selectionLimit", 0)
+    val allowMultiple = selectionLimit == 0 || selectionLimit > 1
+    val intent = Intent(Intent.ACTION_OPEN_DOCUMENT)
+    intent.addCategory(Intent.CATEGORY_OPENABLE)
+    intent.type = if (mimeTypes.size == 1) mimeTypes[0] else "*_/*".replace("_", "")
+    if (mimeTypes.size > 1) intent.putExtra(Intent.EXTRA_MIME_TYPES, mimeTypes)
+    intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, allowMultiple)
+    intent.addFlags(
+      Intent.FLAG_GRANT_READ_URI_PERMISSION or
+        Intent.FLAG_GRANT_PERSISTABLE_URI_PERMISSION
+    )
+    return intent
+  }
+
+  /**
+   * Builds the `{ cancelled, assets }` result for a SAF picker, mirroring [createResultMap]. Reads
+   * the single (`data.data`) or multiple (`data.clipData`) selected uris, persists read access to
+   * each, and resolves lightweight metadata (name / size / mime type) via the ContentResolver.
+   */
+  private fun buildPickedFilesResult(resultCode: Int, data: Intent?, assetType: String): WritableMap {
+    val result = Arguments.createMap()
+    if (resultCode != Activity.RESULT_OK || data == null) {
+      result.putBoolean("cancelled", true)
+      result.putArray("assets", Arguments.createArray())
+      return result
+    }
+
+    val uris = ArrayList<Uri>()
+    val clip = data.clipData
+    if (clip != null) {
+      for (i in 0 until clip.itemCount) {
+        clip.getItemAt(i)?.uri?.let { uris.add(it) }
+      }
+    } else {
+      data.data?.let { uris.add(it) }
+    }
+
+    val resolver = reactApplicationContext.contentResolver
+    val assets = Arguments.createArray()
+    uris.forEachIndexed { index, uri ->
+      // Persist read access so the uri stays valid after the picker's activity finishes.
+      try {
+        resolver.takePersistableUriPermission(uri, Intent.FLAG_GRANT_READ_URI_PERMISSION)
+      } catch (_: Exception) {
+        // Some providers don't support persistable grants; the transient grant still covers
+        // immediate reads, so this is non-fatal.
+      }
+      assets.pushMap(buildAssetFromUri(uri, assetType, index, resolver))
+    }
+
+    // RESULT_OK but nothing chosen (rare) is treated the same as a cancel by the JS layer.
+    result.putBoolean("cancelled", assets.size() == 0)
+    result.putArray("assets", assets)
+    return result
+  }
+
+  /**
+   * Builds the result for the image/video picker, determining the actual media type (photo/video)
+   * from the MIME type of each selected file.
+   */
+  private fun buildPickedMediaResult(resultCode: Int, data: Intent?): WritableMap {
+    val result = Arguments.createMap()
+    if (resultCode != Activity.RESULT_OK || data == null) {
+      result.putBoolean("cancelled", true)
+      result.putArray("assets", Arguments.createArray())
+      return result
+    }
+
+    val uris = ArrayList<Uri>()
+    val clip = data.clipData
+    if (clip != null) {
+      for (i in 0 until clip.itemCount) {
+        clip.getItemAt(i)?.uri?.let { uris.add(it) }
+      }
+    } else {
+      data.data?.let { uris.add(it) }
+    }
+
+    val resolver = reactApplicationContext.contentResolver
+    val assets = Arguments.createArray()
+    uris.forEachIndexed { index, uri ->
+      // Persist read access so the uri stays valid after the picker's activity finishes.
+      try {
+        resolver.takePersistableUriPermission(uri, Intent.FLAG_GRANT_READ_URI_PERMISSION)
+      } catch (_: Exception) {
+        // Some providers don't support persistable grants; the transient grant still covers
+        // immediate reads, so this is non-fatal.
+      }
+
+      val mimeType = resolver.getType(uri) ?: ""
+      val assetType = when {
+        mimeType.startsWith("video/") -> "video"
+        mimeType.startsWith("image/") -> "photo"
+        else -> "photo" // Default to photo for unknown types
+      }
+
+      assets.pushMap(buildMediaAssetFromUri(uri, assetType, index, resolver))
+    }
+
+    // RESULT_OK but nothing chosen (rare) is treated the same as a cancel by the JS layer.
+    result.putBoolean("cancelled", assets.size() == 0)
+    result.putArray("assets", assets)
+    return result
+  }
+
+  private fun buildMediaAssetFromUri(
+    uri: Uri,
+    assetType: String,
+    index: Int,
+    resolver: ContentResolver
+  ): WritableMap {
+    var displayName: String? = null
+    var size = -1L
+    var mimeType: String? = null
+    var width = 0
+    var height = 0
+    var duration = 0L
+
+    try {
+      resolver.query(
+        uri,
+        arrayOf(
+          OpenableColumns.DISPLAY_NAME,
+          OpenableColumns.SIZE,
+          android.provider.MediaStore.MediaColumns.MIME_TYPE,
+          android.provider.MediaStore.MediaColumns.WIDTH,
+          android.provider.MediaStore.MediaColumns.HEIGHT,
+          android.provider.MediaStore.Video.VideoColumns.DURATION
+        ),
+        null,
+        null,
+        null
+      )?.use { cursor ->
+        if (cursor.moveToFirst()) {
+          val nameIndex = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)
+          if (nameIndex >= 0 && !cursor.isNull(nameIndex)) displayName = cursor.getString(nameIndex)
+
+          val sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE)
+          if (sizeIndex >= 0 && !cursor.isNull(sizeIndex)) size = cursor.getLong(sizeIndex)
+
+          val mimeTypeIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.MIME_TYPE)
+          if (mimeTypeIndex >= 0 && !cursor.isNull(mimeTypeIndex)) mimeType = cursor.getString(mimeTypeIndex)
+
+          val widthIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.WIDTH)
+          if (widthIndex >= 0 && !cursor.isNull(widthIndex)) width = cursor.getInt(widthIndex)
+
+          val heightIndex = cursor.getColumnIndex(android.provider.MediaStore.MediaColumns.HEIGHT)
+          if (heightIndex >= 0 && !cursor.isNull(heightIndex)) height = cursor.getInt(heightIndex)
+
+          if (assetType == "video") {
+            val durationIndex = cursor.getColumnIndex(android.provider.MediaStore.Video.VideoColumns.DURATION)
+            if (durationIndex >= 0 && !cursor.isNull(durationIndex)) duration = cursor.getLong(durationIndex)
+          }
+        }
+      }
+    } catch (e: Exception) {
+      Log.w("CustomCameraModule", "Failed to read metadata for $uri", e)
+    }
+
+    val asset = Arguments.createMap()
+    asset.putString("id", "gallery_${System.currentTimeMillis()}_$index")
+    asset.putString("uri", uri.toString())
+    asset.putString("type", assetType)
+    // documentUri mirrors the persistent SAF uri so the JS storage layer treats it as final.
+    asset.putString("documentUri", uri.toString())
+    displayName?.let { asset.putString("fileName", it) }
+    mimeType?.let { asset.putString("mimeType", it) }
+    if (size >= 0L) asset.putDouble("size", size.toDouble())
+    if (width > 0) asset.putInt("width", width)
+    if (height > 0) asset.putInt("height", height)
+    if (duration > 0L) asset.putDouble("duration", duration.toDouble())
+    asset.putDouble("dateTaken", System.currentTimeMillis().toDouble())
+    return asset
+  }
+
+  private fun buildAssetFromUri(
+    uri: Uri,
+    assetType: String,
+    index: Int,
+    resolver: ContentResolver
+  ): WritableMap {
+    var displayName: String? = null
+    var size = -1L
+    try {
+      resolver.query(
+        uri,
+        arrayOf(OpenableColumns.DISPLAY_NAME, OpenableColumns.SIZE),
+        null,
+        null,
+        null
+      )?.use { cursor ->
+        if (cursor.moveToFirst()) {
+          val nameIndex = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME)
+          if (nameIndex >= 0 && !cursor.isNull(nameIndex)) displayName = cursor.getString(nameIndex)
+          val sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE)
+          if (sizeIndex >= 0 && !cursor.isNull(sizeIndex)) size = cursor.getLong(sizeIndex)
+        }
+      }
+    } catch (e: Exception) {
+      Log.w("CustomCameraModule", "Failed to read metadata for $uri", e)
+    }
+
+    // Clip length for picked audio, so its preview header can show a duration the same way a
+    // recorded clip's does (stopAndPublishAudioRecording already reports one).
+    //
+    // Deliberately a SEPARATE query from the one above: DISPLAY_NAME/SIZE are OpenableColumns
+    // and universally supported, while DURATION is not — a provider that doesn't have the column
+    // makes query() throw, and folding it into the projection above would cost this asset its
+    // file name and size too. Best-effort: no duration simply means the field is omitted.
+    var duration = -1L
+    if (assetType == "audio") {
+      try {
+        resolver.query(
+          uri,
+          arrayOf(android.provider.MediaStore.Audio.AudioColumns.DURATION),
+          null,
+          null,
+          null
+        )?.use { cursor ->
+          if (cursor.moveToFirst()) {
+            val durationIndex =
+              cursor.getColumnIndex(android.provider.MediaStore.Audio.AudioColumns.DURATION)
+            if (durationIndex >= 0 && !cursor.isNull(durationIndex)) {
+              duration = cursor.getLong(durationIndex)
+            }
+          }
+        }
+      } catch (e: Exception) {
+        Log.w("CustomCameraModule", "Failed to read audio duration for $uri", e)
+      }
+    }
+
+    val asset = Arguments.createMap()
+    asset.putString("id", "${assetType}_${System.currentTimeMillis()}_$index")
+    asset.putString("uri", uri.toString())
+    asset.putString("type", assetType)
+    // documentUri mirrors the persistent SAF uri so the JS storage layer treats it as final.
+    asset.putString("documentUri", uri.toString())
+    displayName?.let { asset.putString("fileName", it) }
+    resolver.getType(uri)?.let { asset.putString("mimeType", it) }
+    if (size >= 0L) asset.putDouble("size", size.toDouble())
+    if (duration > 0L) asset.putDouble("duration", duration.toDouble())
+    asset.putDouble("dateTaken", System.currentTimeMillis().toDouble())
+    return asset
+  }
+
+  /**
+   * The editor's media list, in the order JS gave it: the `items` array when present, otherwise the
+   * single `uri` form. Entries without a parseable, schemed uri are dropped — a bad element must
+   * not cost the user the rest of the selection.
+   */
+  private fun ReadableMap.readEditorMediaItems(): List<Bundle> {
+    val array = if (hasKey("items") && !isNull("items")) getArray("items") else null
+    if (array != null) {
+      val items = ArrayList<Bundle>(array.size())
+      for (index in 0 until array.size()) {
+        if (array.getType(index) != ReadableType.Map) continue
+        val entry = array.getMap(index) ?: continue
+        items.add(entry.toEditorMediaItem() ?: continue)
+      }
+      return items
+    }
+    return listOfNotNull(toEditorMediaItem())
+  }
+
+  /** One `{ uri, type?, fileName?, mimeType? }` map as an editor item, or null when unusable. */
+  private fun ReadableMap.toEditorMediaItem(): Bundle? {
+    val rawUri = getStringOrDefault("uri", "").trim()
+    if (rawUri.isEmpty()) return null
+    val uri = runCatching { Uri.parse(rawUri) }.getOrNull()
+    if (uri == null || uri.scheme.isNullOrEmpty()) return null
+    return CustomCameraActivity.editorMediaItem(
+      uri = uri.toString(),
+      mediaType = getStringOrDefault("type", "").takeIf { it == "photo" || it == "video" },
+      fileName = getStringOrDefault("fileName", "").takeIf { it.isNotBlank() },
+      mimeType = getStringOrDefault("mimeType", "").takeIf { it.isNotBlank() }
+    )
+  }
+
+  private fun ReadableMap.getStringArrayOrNull(key: String): Array<String>? {
+    if (!hasKey(key) || isNull(key)) return null
+    val array = getArray(key) ?: return null
+    val values = ArrayList<String>()
+    for (i in 0 until array.size()) {
+      if (array.getType(i) == ReadableType.String) array.getString(i)?.let { values.add(it) }
+    }
+    return if (values.isEmpty()) null else values.toTypedArray()
+  }
+
+  private fun ReadableMap.getStringOrDefault(key: String, fallback: String): String =
+    if (hasKey(key) && !isNull(key)) getString(key) ?: fallback else fallback
+
+  private fun ReadableMap.getMediaTypesOrDefault(key: String, fallback: String): String {
+    val value = getStringOrDefault(key, fallback)
+    return when (value) {
+      "photo", "video", "all" -> value
+      else -> fallback
+    }
+  }
+
+  private fun ReadableMap.getInitialCameraOrDefault(key: String, fallback: String): String {
+    val value = getStringOrDefault(key, fallback)
+    return when (value) {
+      "front", "back" -> value
+      else -> fallback
+    }
+  }
+
+  private fun ReadableMap.getBooleanOrDefault(key: String, fallback: Boolean): Boolean {
+    return if (hasKey(key) && !isNull(key)) getBoolean(key) else fallback
+  }
+
+  // NOTE: selectionLimit follows the contract 0 = unlimited multi-selection, >= 1 = capped
+  // selection. Clamp to a minimum of 0 (never 1) so an explicit `selectionLimit: 0` from JS —
+  // which CameraPreview always sends via `selectionLimit ?? 0` — is preserved as "unlimited"
+  // instead of being silently forced into single-selection. Negative values collapse to 0,
+  // which the activity also treats as unlimited (isSelectionUnlimited = selectionLimit <= 0).
+  private fun ReadableMap.getIntOrDefault(key: String, fallback: Int): Int {
+    return if (hasKey(key) && !isNull(key)) getDouble(key).toInt().coerceAtLeast(0) else fallback
+  }
+
+  companion object {
+    private const val CAMERA_PICKER_REQUEST = 7101
+    private const val NOTIFICATION_PERMISSION_REQUEST = 7102
+    private const val BARCODE_SCAN_REQUEST = 7103
+    private const val DOCUMENT_PICKER_REQUEST = 7104
+    private const val AUDIO_PICKER_REQUEST = 7105
+    private const val IMAGE_VIDEO_PICKER_REQUEST = 7106
+    private const val MEDIA_EDITOR_REQUEST = 7107
+    /** Device event carrying measured compression progress — see [emitCompressionProgress]. */
+    private const val EVENT_COMPRESSION_PROGRESS = "onCompressionProgress"
+    // Default MIME filters for the SAF pickers. Kept broad so the common formats are selectable;
+    // callers can override via the `mimeTypes` option.
+    private val DEFAULT_DOCUMENT_MIME_TYPES = arrayOf(
+      "application/pdf",
+      "application/msword",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "application/vnd.ms-excel",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "application/vnd.ms-powerpoint",
+      "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      "text/plain",
+      "application/rtf",
+      "application/zip"
+    )
+    // The audio picker accepts the whole audio/* tree (MP3, WAV, AAC, M4A, OGG, FLAC, …) plus the
+    // container types some providers report for audio files without an audio/ prefix (.ogg/.opus
+    // as application/ogg, .m4a occasionally as video/mp4 metadata quirks are handled by the
+    // asset-type mapping, not here).
+    private val DEFAULT_AUDIO_MIME_TYPES = arrayOf("audio/*", "application/ogg")
+    // MIME types that are audio in practice but don't start with "audio/" — used when deciding
+    // whether a custom `mimeTypes` set is still audio-only (→ keep the intent's base type audio/*).
+    private val AUDIO_CONTAINER_MIME_TYPES = setOf("application/ogg", "application/x-ogg")
+    // ACTION_OPEN_DOCUMENT landing hint: the Audio root of the built-in media documents provider
+    // (com.android.providers.media.documents), i.e. the "Audio" entry in the system picker's
+    // sidebar. Authority + root id are stable AOSP values used by DocumentsUI itself.
+    private const val MEDIA_DOCUMENTS_AUTHORITY = "com.android.providers.media.documents"
+    private const val MEDIA_DOCUMENTS_AUDIO_ROOT = "audio_root"
+    const val EXTRA_CANCELLED = "com.customcamera.extra.CANCELLED"
+    const val EXTRA_ASSETS = "com.customcamera.extra.ASSETS"
+    const val NAME = NativeCustomCameraSpec.NAME
+    /** Gallery sub-folder used by both capture and download so they always land in the same album. */
+    const val GALLERY_FOLDER = "EnsysCameraX"
+  }
+}