react-native-ensys-camera-x 1.0.7

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

@@ -0,0 +1,782 @@
+package com.customcamera
+
+import android.content.Context
+import android.graphics.BitmapFactory
+import android.media.MediaMetadataRetriever
+import android.net.Uri
+import android.os.Build
+import android.provider.MediaStore
+import androidx.core.content.FileProvider
+import android.util.Log
+import java.io.File
+import java.io.IOException
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * MediaCacheManager handles all media caching operations.
+ *
+ * Key features:
+ * - Stores captured/selected media in app cache (not gallery)
+ * - Maintains metadata for each cached item
+ * - Supports overwriting edited versions (no version history)
+ * - Provides cache cleanup and management
+ * - Thread-safe operations
+ */
+class MediaCacheManager private constructor(private val context: Context) {
+
+  companion object {
+    private const val TAG = "MediaCacheManager"
+    private const val CACHE_DIR_NAME = "camera_media_cache"
+    private const val METADATA_FILE_NAME = "cache_metadata.json"
+    private const val MAX_CACHE_SIZE_MB = 500L // Maximum cache size in MB
+
+    @Volatile
+    private var instance: MediaCacheManager? = null
+
+    fun getInstance(context: Context): MediaCacheManager {
+      return instance ?: synchronized(this) {
+        instance ?: MediaCacheManager(context.applicationContext).also { instance = it }
+      }
+    }
+  }
+
+  // Cache directory for storing media files
+  private val cacheDir: File by lazy {
+    File(context.cacheDir, CACHE_DIR_NAME).apply {
+      if (!exists()) {
+        mkdirs()
+      }
+    }
+  }
+
+  // Metadata file for tracking cached items
+  private val metadataFile: File by lazy {
+    File(cacheDir, METADATA_FILE_NAME)
+  }
+
+  // In-memory cache of metadata for fast access
+  private val metadataCache = ConcurrentHashMap<String, MediaCacheMetadata>()
+
+  // Date format for generating unique identifiers
+  private val timestampFormat = SimpleDateFormat("yyyyMMdd_HHmmss_SSS", Locale.US).apply {
+    timeZone = TimeZone.getTimeZone("UTC")
+  }
+
+  /**
+   * Metadata for a cached media item
+   */
+  data class MediaCacheMetadata(
+    val id: String,
+    val fileName: String,
+    val cachePath: String,
+    val fileType: String, // "photo" or "video"
+    val fileSize: Long,
+    val width: Int?,
+    val height: Int?,
+    val duration: Long?, // For videos in milliseconds
+    val mimeType: String?,
+    val createdAt: Long,
+    val lastModified: Long,
+    val originalUri: String? = null // Original source URI if from gallery
+  )
+
+  init {
+    loadMetadata()
+  }
+
+  /**
+   * Load metadata from file into memory
+   */
+  private fun loadMetadata() {
+    try {
+      if (!metadataFile.exists()) {
+        return
+      }
+
+      val jsonContent = metadataFile.readText()
+      if (jsonContent.isBlank()) {
+        return
+      }
+
+      // Parse JSON and populate metadata cache
+      // For simplicity, we'll use a basic JSON parser
+      val lines = jsonContent.split("\n")
+      for (line in lines) {
+        if (line.isNotBlank()) {
+          try {
+            val metadata = parseMetadataLine(line)
+            metadataCache[metadata.id] = metadata
+          } catch (e: Exception) {
+            Log.w(TAG, "Failed to parse metadata line: $line", e)
+          }
+        }
+      }
+
+      Log.d(TAG, "Loaded ${metadataCache.size} metadata entries")
+    } catch (e: Exception) {
+      Log.e(TAG, "Failed to load metadata", e)
+    }
+  }
+
+  /**
+   * Save metadata to file
+   */
+  private fun saveMetadata() {
+    try {
+      val jsonContent = StringBuilder()
+      for (metadata in metadataCache.values) {
+        jsonContent.append(metadataToJsonLine(metadata)).append("\n")
+      }
+      metadataFile.writeText(jsonContent.toString())
+    } catch (e: Exception) {
+      Log.e(TAG, "Failed to save metadata", e)
+    }
+  }
+
+  /**
+   * Parse a metadata line from JSON format
+   */
+  private fun parseMetadataLine(line: String): MediaCacheMetadata {
+    // Simple JSON parsing for our specific format
+    val values = mutableMapOf<String, String>()
+
+    // Extract key-value pairs from JSON-like format
+    val pattern = "\"([^\"]+)\":\"?([^\"]+)\"?".toRegex()
+    pattern.findAll(line).forEach { match ->
+      val key = match.groupValues[1]
+      val value = match.groupValues[2].trimEnd(',')
+      values[key] = value
+    }
+
+    return MediaCacheMetadata(
+      id = values["id"] ?: "",
+      fileName = values["fileName"] ?: "",
+      cachePath = values["cachePath"] ?: "",
+      fileType = values["fileType"] ?: "photo",
+      fileSize = values["fileSize"]?.toLong() ?: 0L,
+      width = values["width"]?.toIntOrNull(),
+      height = values["height"]?.toIntOrNull(),
+      duration = values["duration"]?.toLongOrNull(),
+      mimeType = values["mimeType"],
+      createdAt = values["createdAt"]?.toLong() ?: System.currentTimeMillis(),
+      lastModified = values["lastModified"]?.toLong() ?: System.currentTimeMillis(),
+      originalUri = values["originalUri"]
+    )
+  }
+
+  /**
+   * Convert metadata to JSON line format
+   */
+  private fun metadataToJsonLine(metadata: MediaCacheMetadata): String {
+    return """{"id":"${metadata.id}","fileName":"${metadata.fileName}","cachePath":"${metadata.cachePath}","fileType":"${metadata.fileType}","fileSize":${metadata.fileSize},"width":${metadata.width ?: "null"},"height":${metadata.height ?: "null"},"duration":${metadata.duration ?: "null"},"mimeType":"${metadata.mimeType ?: ""}","createdAt":${metadata.createdAt},"lastModified":${metadata.lastModified},"originalUri":"${metadata.originalUri ?: ""}"}"""
+  }
+
+  /**
+   * Generate a unique ID based on timestamp
+   */
+  fun generateUniqueId(): String {
+    return "media_${timestampFormat.format(Date())}"
+  }
+
+  /**
+   * Generate a unique filename for cached media.
+   *
+   * [extension] (with the leading dot) overrides the per-type default. Callers that know the real
+   * container — anything copied in from the gallery — pass it so the cache file keeps the source's
+   * own format instead of being renamed to .jpg. See [MediaFormat.of].
+   */
+  fun generateFileName(fileType: String, id: String? = null, extension: String? = null): String {
+    val uniqueId = id ?: generateUniqueId()
+    val ext = extension ?: if (fileType == "video") ".mp4" else ".jpg"
+    return "${uniqueId}${ext}"
+  }
+
+  /**
+   * The container an incoming file is actually in — extension plus MIME type.
+   *
+   * Copying media into the cache is a byte-for-byte copy, so the bytes always keep their original
+   * format; only the NAME used to be forced to ".jpg" (with a hardcoded "image/jpeg" alongside it)
+   * for every non-video. That turned a picked GIF into `media_x.jpg` / image/jpeg the moment it
+   * entered the cache, and the lie travelled all the way to the published file and on to JS —
+   * consumers then failed to render a "JPEG" whose bytes start with GIF89a. Resolving the format
+   * here keeps a GIF a GIF end to end, and does the same for PNG/WebP/HEIC.
+   */
+  internal data class MediaFormat(val extension: String, val mimeType: String) {
+    companion object {
+      /**
+       * Resolve the format of [sourceUri] for a [fileType] asset. The MIME type the resolver
+       * reports wins (it is derived from the provider's own record); a content:// URI that
+       * reports nothing falls back to the extension in its path, then to the type default.
+       *
+       * The container table lives in [ImageFormatSupport] so that every path that names a file —
+       * caching here, publishing in [MediaPublisher], saving from the editor — agrees about what
+       * a given format is called. That is what keeps a HEIF a `.heif` and an AVIF an `.avif`
+       * instead of quietly becoming `.jpg` on the way into the cache.
+       */
+      fun of(context: Context, sourceUri: Uri?, fileType: String): MediaFormat {
+        if (fileType == "video") return MediaFormat(".mp4", "video/mp4")
+        if (fileType == "audio") return MediaFormat(".m4a", "audio/mp4")
+        if (sourceUri == null) return DEFAULT_IMAGE
+
+        val declaredMime = runCatching { context.contentResolver.getType(sourceUri) }
+          .getOrNull()
+          ?.lowercase(Locale.US)
+        ImageFormatSupport.fromMimeType(declaredMime)?.let {
+          // Preserve the exact MIME spelling the provider reported (image/heic vs image/heif)
+          // rather than normalising it — the bytes are copied verbatim, so the record should be
+          // verbatim too.
+          return MediaFormat(it.dottedExtension, declaredMime ?: it.mimeType)
+        }
+
+        ImageFormatSupport.fromFileName(sourceUri.path)?.let { format ->
+          // Keep the extension actually present in the path (.heic stays .heic) and pair it with
+          // that container's canonical MIME type.
+          val pathExtension = sourceUri.path
+            ?.substringAfterLast('/', "")
+            ?.substringAfterLast('.', "")
+            ?.lowercase(Locale.US)
+            ?.takeIf { it.isNotEmpty() }
+          return MediaFormat(".${pathExtension ?: format.extension}", format.mimeType)
+        }
+
+        return DEFAULT_IMAGE
+      }
+
+      /** Format of an on-disk [file], read from its extension alone. */
+      fun ofFile(file: File, fileType: String): MediaFormat {
+        if (fileType == "video") {
+          // A video is not automatically an MP4: the preview editor's "Export By" menu can
+          // produce a .webm or .3gp, and registering those as video/mp4 would put MP4's name on
+          // bytes that are not MP4 — the same class of bug the image branch below exists to
+          // prevent. Unrecognised extensions keep the historical MP4 default.
+          return MediaExportFormats.videoContainerFromFileName(file.name)
+            ?.let { MediaFormat(it.dottedExtension, it.mimeType) }
+            ?: MediaFormat(".mp4", "video/mp4")
+        }
+        val ext = file.extension.lowercase(Locale.US)
+        val format = ImageFormatSupport.fromFileName(file.name) ?: return DEFAULT_IMAGE
+        return MediaFormat(".$ext", format.mimeType)
+      }
+
+      /** Every camera capture is a JPEG, so that is the fallback for anything unrecognised. */
+      private val DEFAULT_IMAGE = MediaFormat(".jpg", "image/jpeg")
+    }
+  }
+
+  /**
+   * Cache a media file from a source URI
+   *
+   * @param sourceUri The source URI of the media file
+   * @param fileType The type of media ("photo" or "video")
+   * @param id Optional custom ID (will generate one if not provided)
+   * @param allowMove Set only when the source is a throwaway file this app just wrote and will
+   *   delete straight after caching — a freshly recorded clip or captured still. It lets the
+   *   source be MOVED into the cache instead of copied; see [ingestUriToFile].
+   * @return MediaCacheMetadata containing cache information
+   */
+  fun cacheMedia(
+    sourceUri: Uri,
+    fileType: String,
+    id: String? = null,
+    allowMove: Boolean = false
+  ): MediaCacheMetadata {
+    val uniqueId = id ?: generateUniqueId()
+    // Keep the source's real container (a picked GIF stays a .gif / image/gif) — the copy below
+    // is byte-for-byte, so naming it anything else would misdescribe the bytes on disk.
+    val format = MediaFormat.of(context, sourceUri, fileType)
+    val fileName = generateFileName(fileType, uniqueId, format.extension)
+    val cacheFile = File(cacheDir, fileName)
+
+    // Bring the file into the cache — moved when the caller owns the source, copied otherwise.
+    ingestUriToFile(sourceUri, cacheFile, allowMove)
+
+    // Extract metadata
+    val fileSize = cacheFile.length()
+    val (width, height, duration) = extractMediaMetadata(cacheFile, fileType)
+    val mimeType = format.mimeType
+
+    // Create metadata
+    val metadata = MediaCacheMetadata(
+      id = uniqueId,
+      fileName = fileName,
+      cachePath = cacheFile.absolutePath,
+      fileType = fileType,
+      fileSize = fileSize,
+      width = width,
+      height = height,
+      duration = duration,
+      mimeType = mimeType,
+      createdAt = System.currentTimeMillis(),
+      lastModified = System.currentTimeMillis(),
+      originalUri = sourceUri.toString()
+    )
+
+    // Store metadata
+    metadataCache[uniqueId] = metadata
+    saveMetadata()
+
+    Log.d(TAG, "Cached media: $uniqueId -> ${cacheFile.absolutePath}")
+    return metadata
+  }
+
+  /**
+   * Cache a media file and return CacheMediaResult for the workflow layer.
+   */
+  fun cacheMediaForStorage(
+    uri: Uri,
+    fileType: String,
+    fileName: String? = null,
+    allowMove: Boolean = false
+  ): MediaStorageWorkflow.CacheMediaResult {
+    return try {
+      val metadata = cacheMedia(
+        sourceUri = uri,
+        fileType = fileType,
+        id = null,
+        allowMove = allowMove
+      )
+      MediaStorageWorkflow.CacheMediaResult(
+        isSuccess = true,
+        mediaId = metadata.id,
+        fileName = metadata.fileName,
+        cachePath = metadata.cachePath,
+        fileSize = metadata.fileSize,
+        width = metadata.width,
+        height = metadata.height,
+        duration = metadata.duration,
+        mimeType = metadata.mimeType
+      )
+    } catch (e: Exception) {
+      Log.e(TAG, "Failed to cache media", e)
+      MediaStorageWorkflow.CacheMediaResult(
+        isSuccess = false,
+        mediaId = "",
+        fileName = fileName ?: "",
+        cachePath = "",
+        error = e.message
+      )
+    }
+  }
+
+  /**
+   * Cache a media file from a byte array
+   *
+   * @param data The byte array of the media file
+   * @param fileType The type of media ("photo" or "video")
+   * @param id Optional custom ID (will generate one if not provided)
+   * @return MediaCacheMetadata containing cache information
+   */
+  fun cacheMediaFromBytes(data: ByteArray, fileType: String, id: String? = null): MediaCacheMetadata {
+    val uniqueId = id ?: generateUniqueId()
+    // The bytes are written verbatim, so the entry must be named for what they actually are.
+    // Unlike cacheMedia there is no source URI to ask the resolver about, so the container is
+    // read from the bytes themselves — otherwise a GIF written through this path lands as
+    // `media_x.jpg` / image/jpeg and every consumer fails to render it (see MediaFormat).
+    val isGif = fileType != "video" && fileType != "audio" && GifSupport.hasGifSignature(data)
+    val fileName = generateFileName(fileType, uniqueId, if (isGif) ".gif" else null)
+    val cacheFile = File(cacheDir, fileName)
+
+    // Write bytes to cache file
+    cacheFile.writeBytes(data)
+
+    // Extract metadata
+    val fileSize = cacheFile.length()
+    val (width, height, duration) = extractMediaMetadata(cacheFile, fileType)
+    val mimeType = if (isGif) "image/gif" else getMimeType(fileType)
+
+    // Create metadata
+    val metadata = MediaCacheMetadata(
+      id = uniqueId,
+      fileName = fileName,
+      cachePath = cacheFile.absolutePath,
+      fileType = fileType,
+      fileSize = fileSize,
+      width = width,
+      height = height,
+      duration = duration,
+      mimeType = mimeType,
+      createdAt = System.currentTimeMillis(),
+      lastModified = System.currentTimeMillis()
+    )
+
+    // Store metadata
+    metadataCache[uniqueId] = metadata
+    saveMetadata()
+
+    Log.d(TAG, "Cached media from bytes: $uniqueId -> ${cacheFile.absolutePath}")
+    return metadata
+  }
+
+  /**
+   * Overwrite an existing cached media file with new data
+   * This replaces the existing file without creating a new entry
+   *
+   * @param id The ID of the media to overwrite
+   * @param newData The new byte data
+   * @return Updated MediaCacheMetadata
+   */
+  fun overwriteCachedMedia(id: String, newData: ByteArray): MediaCacheMetadata {
+    val existingMetadata = metadataCache[id]
+      ?: throw IllegalArgumentException("Media with id $id not found in cache")
+
+    val cacheFile = File(existingMetadata.cachePath)
+
+    // Overwrite file with new data
+    cacheFile.writeBytes(newData)
+
+    // Extract new metadata
+    val fileSize = cacheFile.length()
+    val (width, height, duration) = extractMediaMetadata(cacheFile, existingMetadata.fileType)
+
+    // Update metadata
+    val updatedMetadata = existingMetadata.copy(
+      fileSize = fileSize,
+      width = width,
+      height = height,
+      duration = duration,
+      lastModified = System.currentTimeMillis()
+    )
+
+    // Store updated metadata
+    metadataCache[id] = updatedMetadata
+    saveMetadata()
+
+    Log.d(TAG, "Overwrote cached media: $id")
+    return updatedMetadata
+  }
+
+  /**
+   * Overwrite an existing cached media file from a source URI
+   *
+   * @param id The ID of the media to overwrite
+   * @param sourceUri The source URI of the new media data
+   * @return Updated MediaCacheMetadata
+   */
+  fun overwriteCachedMediaFromUri(id: String, sourceUri: Uri): MediaCacheMetadata {
+    val existingMetadata = metadataCache[id]
+      ?: throw IllegalArgumentException("Media with id $id not found in cache")
+
+    var cacheFile = File(existingMetadata.cachePath)
+
+    // Copy file to cache, overwriting existing. Never a move: the source of an overwrite is an
+    // edit result whose lifetime belongs to the editor, not to us.
+    ingestUriToFile(sourceUri, cacheFile, allowMove = false)
+
+    // The new bytes may be in a DIFFERENT container than the entry they replace: baking edits
+    // into a GIF (or PNG/WebP) composites it to a flat JPEG, and leaving the entry named .gif
+    // would put JPEG bytes behind a GIF name and MIME type — the same lie, just in the other
+    // direction. Re-type the entry to match what was actually written. Same-format overwrites
+    // (trim/mute writing .mp4 over .mp4) resolve to the identical name and skip the rename.
+    val incoming = MediaFormat.of(context, sourceUri, existingMetadata.fileType)
+    var fileName = existingMetadata.fileName
+    var mimeType = existingMetadata.mimeType
+    if (!fileName.endsWith(incoming.extension, ignoreCase = true)) {
+      val retypedName = "${File(fileName).nameWithoutExtension}${incoming.extension}"
+      val retypedFile = File(cacheDir, retypedName)
+      if (runCatching { cacheFile.renameTo(retypedFile) }.getOrDefault(false)) {
+        cacheFile = retypedFile
+        fileName = retypedName
+        mimeType = incoming.mimeType
+        Log.d(TAG, "Re-typed cached media $id to $retypedName after format change")
+      }
+    }
+
+    // Extract new metadata
+    val fileSize = cacheFile.length()
+    val (width, height, duration) = extractMediaMetadata(cacheFile, existingMetadata.fileType)
+
+    // Update metadata
+    val updatedMetadata = existingMetadata.copy(
+      fileName = fileName,
+      cachePath = cacheFile.absolutePath,
+      mimeType = mimeType,
+      fileSize = fileSize,
+      width = width,
+      height = height,
+      duration = duration,
+      lastModified = System.currentTimeMillis()
+    )
+
+    // Store updated metadata
+    metadataCache[id] = updatedMetadata
+    saveMetadata()
+
+    Log.d(TAG, "Overwrote cached media from URI: $id")
+    return updatedMetadata
+  }
+
+  /**
+   * Get metadata for a cached media item
+   */
+  fun getMetadata(id: String): MediaCacheMetadata? {
+    return metadataCache[id]
+  }
+
+  /**
+   * Get all cached media metadata
+   */
+  fun getAllMetadata(): List<MediaCacheMetadata> {
+    return metadataCache.values.sortedByDescending { it.createdAt }
+  }
+
+  /**
+   * Get a cached media file
+   */
+  fun getCachedFile(id: String): File? {
+    val metadata = metadataCache[id] ?: return null
+    val file = File(metadata.cachePath)
+    return if (file.exists()) file else null
+  }
+
+  /**
+   * Get URI for a cached media file
+   */
+  fun getCachedUri(id: String): Uri? {
+    val file = getCachedFile(id) ?: return null
+    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+      try {
+        FileProvider.getUriForFile(
+          context,
+          "${context.packageName}.camera.fileprovider",
+          file
+        )
+      } catch (e: Exception) {
+        Uri.fromFile(file)
+      }
+    } else {
+      Uri.fromFile(file)
+    }
+  }
+
+  /**
+   * Delete a cached media item
+   */
+  fun deleteCachedMedia(id: String): Boolean {
+    val metadata = metadataCache[id] ?: return false
+    val file = File(metadata.cachePath)
+
+    val deleted = if (file.exists()) {
+      file.delete()
+    } else {
+      true // File doesn't exist, consider it deleted
+    }
+
+    if (deleted) {
+      metadataCache.remove(id)
+      saveMetadata()
+      Log.d(TAG, "Deleted cached media: $id")
+    }
+
+    return deleted
+  }
+
+  /**
+   * Clear all cached media
+   */
+  fun clearCache(): Boolean {
+    var success = true
+
+    // Delete all files in cache directory
+    cacheDir.listFiles()?.forEach { file ->
+      if (file.name != METADATA_FILE_NAME) {
+        if (!file.delete()) {
+          success = false
+          Log.w(TAG, "Failed to delete cache file: ${file.name}")
+        }
+      }
+    }
+
+    // Clear metadata
+    metadataCache.clear()
+    saveMetadata()
+
+    // Reclaim the persistent compression cache too — its master outputs live in a sibling cache
+    // dir (cache/compression_cache/) and its index is a separate encrypted DB, neither of which
+    // this loop above touches. Best-effort: a failure here never fails the media-cache clear.
+    runCatching { CompressionCacheStore.clearAll(context) }
+
+    Log.d(TAG, "Cleared cache, success: $success")
+    return success
+  }
+
+  /**
+   * Get total cache size in bytes
+   */
+  fun getCacheSize(): Long {
+    return metadataCache.values.sumOf { it.fileSize }
+  }
+
+  /**
+   * Get cache size in MB
+   */
+  fun getCacheSizeMB(): Double {
+    return getCacheSize() / (1024.0 * 1024.0)
+  }
+
+  /**
+   * Clean up old cache entries if cache size exceeds limit
+   * Removes oldest entries first
+   */
+  fun cleanupIfNeeded() {
+    val currentSizeMB = getCacheSizeMB()
+
+    if (currentSizeMB > MAX_CACHE_SIZE_MB) {
+      Log.d(TAG, "Cache size ($currentSizeMB MB) exceeds limit ($MAX_CACHE_SIZE_MB MB), cleaning up")
+
+      // Sort by creation time (oldest first)
+      val sortedMetadata = metadataCache.values.sortedBy { it.createdAt }
+      var sizeToRemove = currentSizeMB - (MAX_CACHE_SIZE_MB * 0.8) // Remove down to 80% of limit
+
+      for (metadata in sortedMetadata) {
+        if (sizeToRemove <= 0) break
+
+        val removedSize = metadata.fileSize / (1024.0 * 1024.0)
+        if (deleteCachedMedia(metadata.id)) {
+          sizeToRemove -= removedSize
+          Log.d(TAG, "Removed old cache entry: ${metadata.id} (${removedSize} MB)")
+        }
+      }
+    }
+  }
+
+  /**
+   * Bring the content behind [sourceUri] into [destFile].
+   *
+   * When [allowMove] is set AND the URI resolves to a plain file this app owns, the file is MOVED
+   * (a rename inside the cache volume) instead of copied. This is the difference between a large
+   * recording landing in the cache instantly and the app spending a full read+write pass over
+   * hundreds of megabytes — while also needing a second copy's worth of free space it does not
+   * have. Capture callers immediately delete their temp file afterwards, so the move is exactly
+   * what they meant; a deleted-by-us source simply makes their delete a no-op.
+   *
+   * Everything else (gallery picks, documents, anything behind a content provider) is copied, and
+   * a failed copy never leaves a truncated file behind — see [MediaFileIo.copyStream].
+   */
+  private fun ingestUriToFile(sourceUri: Uri, destFile: File, allowMove: Boolean) {
+    if (allowMove) {
+      sourceFileOrNull(sourceUri)?.let { source ->
+        if (MediaFileIo.relocate(source, destFile).succeeded) return
+        // Fall through to the stream path: the source is still intact either way, so a refused
+        // relocation (no room for a cross-volume copy) still gets one honest attempt that either
+        // works or throws a reportable IOException.
+      }
+    }
+    context.contentResolver.openInputStream(sourceUri)?.use { input ->
+      MediaFileIo.copyStream(input, destFile)
+    } ?: throw IOException("Failed to open input stream for URI: $sourceUri")
+  }
+
+  /**
+   * The on-disk file behind [uri], or null when there is not one we may relocate.
+   *
+   * Only `file://` URIs qualify. A `content://` URI is deliberately excluded even when it points
+   * at our own FileProvider: the provider is the only thing that knows how the authority maps to
+   * a path, and guessing wrong would move a file some other component still owns.
+   */
+  private fun sourceFileOrNull(uri: Uri): File? {
+    if (uri.scheme != null && uri.scheme != "file") return null
+    val path = uri.path?.takeIf { it.isNotBlank() } ?: return null
+    return File(path).takeIf { it.isFile }
+  }
+
+  /**
+   * Extract media metadata (dimensions, duration) from file
+   */
+  private fun extractMediaMetadata(file: File, fileType: String): Triple<Int?, Int?, Long?> {
+    return if (fileType == "video") {
+      extractVideoMetadata(file)
+    } else {
+      extractImageMetadata(file)
+    }
+  }
+
+  /**
+   * Extract image metadata
+   */
+  private fun extractImageMetadata(file: File): Triple<Int?, Int?, Long?> {
+    return try {
+      val options = BitmapFactory.Options().apply {
+        inJustDecodeBounds = true
+      }
+      BitmapFactory.decodeFile(file.absolutePath, options)
+      Triple(options.outWidth, options.outHeight, null)
+    } catch (e: Exception) {
+      Log.w(TAG, "Failed to extract image metadata", e)
+      Triple(null, null, null)
+    }
+  }
+
+  /**
+   * Extract video metadata
+   */
+  private fun extractVideoMetadata(file: File): Triple<Int?, Int?, Long?> {
+    return try {
+      val retriever = MediaMetadataRetriever()
+      // release() MUST run even if setDataSource/extractMetadata throws (corrupt or
+      // zero-byte cache file, unsupported codec) — otherwise the native retriever handle
+      // leaks. Rapidly caching many videos, some malformed, would accumulate leaked native
+      // allocations until MediaMetadataRetriever creation fails and the process crashes.
+      // Use try/finally, NOT Kotlin .use{} (MediaMetadataRetriever is only AutoCloseable on
+      // API 29+, so .use{} crashes on API 24-28).
+      try {
+        retriever.setDataSource(file.absolutePath)
+
+        var width = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)?.toIntOrNull()
+        var height = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)?.toIntOrNull()
+        val duration = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_DURATION)?.toLongOrNull()
+        val rotation = retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_ROTATION)?.toIntOrNull() ?: 0
+
+        if (rotation == 90 || rotation == 270) {
+          val temp = width
+          width = height
+          height = temp
+        }
+
+        Triple(width, height, duration)
+      } finally {
+        retriever.release()
+      }
+    } catch (e: Exception) {
+      Log.w(TAG, "Failed to extract video metadata", e)
+      Triple(null, null, null)
+    }
+  }
+
+  /**
+   * Get MIME type for file type
+   */
+  private fun getMimeType(fileType: String): String {
+    return when (fileType) {
+      "video" -> "video/mp4"
+      else -> "image/jpeg"
+    }
+  }
+
+  /**
+   * Check if a media item exists in cache
+   */
+  fun existsInCache(id: String): Boolean {
+    return metadataCache.containsKey(id) && getCachedFile(id)?.exists() == true
+  }
+
+  /**
+   * Get cache statistics
+   */
+  fun getCacheStats(): Map<String, Any> {
+    val allMetadata = getAllMetadata()
+    val photoCount = allMetadata.count { it.fileType == "photo" }
+    val videoCount = allMetadata.count { it.fileType == "video" }
+
+    return mapOf(
+      "totalItems" to allMetadata.size,
+      "photoCount" to photoCount,
+      "videoCount" to videoCount,
+      "totalSizeMB" to String.format("%.2f", getCacheSizeMB()),
+      "maxSizeMB" to MAX_CACHE_SIZE_MB
+    )
+  }
+}