@gaozh1024/photo-picker 0.1.1

package/README.md

@@ -0,0 +1,90 @@
+# @gaozh1024/photo-picker
+
+Permissionless Android system media selection for Expo and React Native.
+
+## Android behavior
+
+The native module selects the backend before launching the activity:
+
+| Android/device capability                                       | Backend                                                         | User-visible UI                                                                             |
+| --------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Android 13+ with the OS Photo Picker available                  | `android-photo-picker` / `android.provider.action.PICK_IMAGES`  | Android Photo Picker, including the `所有照片` / `相册` layout shown in the reference image |
+| Android 12 and below, or a device without a usable Photo Picker | `android-open-document` / `android.intent.action.OPEN_DOCUMENT` | Android DocumentsUI file picker                                                             |
+
+The Photo Picker is provided by the OS or OEM. Its colors, labels, tabs, privacy banner, album presentation, and exact layout are not controlled by this package. The reference image is therefore a device smoke-test target, not a drawable screen that the library can reproduce pixel-for-pixel.
+
+The package does not declare or request `READ_EXTERNAL_STORAGE`, `WRITE_EXTERNAL_STORAGE`, `READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`, or `READ_MEDIA_VISUAL_USER_SELECTED`. It returns the URIs selected in the current picker session and copies them into the app cache. It does not enumerate the device media library.
+
+The Android 14 limited-library permission flow is intentionally out of scope for this API. A future library-access capability must be a separate permission and MediaStore API; it must not change the meaning of `pickMedia()`.
+
+## Usage
+
+```tsx
+import { PhotoAlbumScreen } from '@gaozh1024/photo-picker';
+
+// Keep the existing route name if migrating from photo-album-picker.
+<Stack.Screen name="PhotoAlbum" component={PhotoAlbumScreen} />;
+```
+
+`PhotoAlbumScreen` preserves the existing selection, crop, callback, and upload flow. For custom flows, use the exported `pickMedia` API, the callback registry, and `PhotoCropScreen`.
+
+`maxSelection` must be a positive integer after normalization. The JavaScript flow does not impose the old arbitrary limit of `100`. The Android Photo Picker may reject a request above the OS-supported multi-select limit with `PICKER_SELECTION_LIMIT_UNSUPPORTED`; the caller should reduce the requested limit or use a compatible device/backend. Crop mode always selects one image.
+
+## Result and diagnostics
+
+`pickMedia()` resolves with:
+
+```ts
+{
+  cancelled: boolean;
+  assets: PhotoAlbumItem[];
+  source?: 'android-photo-picker' | 'android-open-document';
+  action?: string;
+}
+```
+
+`source` and `action` describe the backend that actually handled the request. A cancellation is still a successful result and should be checked through `cancelled`; it may include the same backend diagnostics. For selected assets, `source` is also retained on each asset.
+
+Native failures expose a stable `code` recognized by `isPhotoPickerNativeError`:
+
+- `PICKER_BUSY`: another picker request is already in flight; allow it to finish before retrying.
+- `PICKER_LAUNCH_FAILED`: the resolved activity could not be started; report the error and inspect the device/provider configuration.
+- `PICKER_SELECTION_LIMIT_UNSUPPORTED`: the requested multi-select limit exceeds the Photo Picker capability; reduce `maxSelection`.
+
+Unknown native/provider failures remain ordinary `Error` values. A failed selection/materialization must not be treated as a successful asset result.
+
+## Native rebuild requirement
+
+The package contains native Android code. After installing or updating it, rebuild and reinstall the Android application; an OTA JavaScript update cannot install or replace the native module.
+
+```sh
+pnpm --dir packages/photo-picker test
+pnpm --dir packages/photo-picker typecheck
+pnpm --dir packages/photo-picker build
+```
+
+For local Yalc development:
+
+```sh
+pnpm build
+pnpm exec yalc publish --push
+```
+
+Then, in the consuming application:
+
+```sh
+pnpm exec yalc add @gaozh1024/photo-picker
+```
+
+## Device smoke gate
+
+The TypeScript tests cover option normalization, crop/single-select behavior, result source/action shape, cancellation semantics, and native error-code discrimination. They cannot prove which Android activity an OEM launches.
+
+Before release, verify on real devices:
+
+1. Android 13 and 14/15 devices with Photo Picker: the picker opens as the OS Photo Picker, `source` is `android-photo-picker`, and `action` is `android.provider.action.PICK_IMAGES`.
+2. Android 12 or a device without a usable Photo Picker: the UI is DocumentsUI, `source` is `android-open-document`, and `action` is `android.intent.action.OPEN_DOCUMENT`.
+3. Single-select, mixed image/video, multi-select, crop, cancel, an over-limit request, repeated taps, and a provider launch failure.
+4. The app's merged manifest contains no media-read permission added by this package, and no runtime media permission prompt appears.
+
+Record the device model, Android version, selected backend, action, and error code for every failure. Do not use the appearance of a limited-library banner as proof of this package's `pickMedia()` behavior; limited-library support is a separate future capability.

package/android/build.gradle

@@ -0,0 +1,19 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'com.gaozh1024'
+version = '0.1.1'
+
+android {
+  namespace "com.gaozh1024.photopicker"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.1"
+  }
+}
+
+dependencies {
+  implementation 'androidx.activity:activity-ktx:1.11.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <queries>
+    <intent>
+      <action android:name="android.provider.action.PICK_IMAGES" />
+    </intent>
+  </queries>
+</manifest>

package/android/src/main/java/com/gaozh1024/photopicker/PhotoPickerContract.kt

@@ -0,0 +1,82 @@
+package com.gaozh1024.photopicker
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.provider.MediaStore
+import expo.modules.kotlin.activityresult.AppContextActivityResultContract
+import java.io.Serializable
+
+internal data class PickerBackend(
+  val source: String,
+  val action: String,
+) : Serializable
+
+internal data class PhotoPickerContractOptions(
+  val mediaType: String,
+  val maxSelection: Int,
+  val allowsMultipleSelection: Boolean,
+  val backend: PickerBackend,
+) : Serializable
+
+internal sealed class PhotoPickerContractResult {
+  data class Success(val uris: List<Uri>, val backend: PickerBackend) : PhotoPickerContractResult()
+  data class Cancelled(val backend: PickerBackend) : PhotoPickerContractResult()
+}
+
+internal class PhotoPickerContract : AppContextActivityResultContract<PhotoPickerContractOptions, PhotoPickerContractResult> {
+  override fun createIntent(context: Context, input: PhotoPickerContractOptions): Intent {
+    val intent = Intent(input.backend.action)
+
+    val mediaType = when (input.mediaType) {
+      "photo" -> "image/*"
+      "video" -> "video/*"
+      else -> "*/*"
+    }
+    intent.type = mediaType
+    if (input.mediaType == "all") {
+      intent.putExtra(Intent.EXTRA_MIME_TYPES, arrayOf("image/*", "video/*"))
+    }
+    if (input.backend.source == "android-open-document") {
+      intent.addCategory(Intent.CATEGORY_OPENABLE)
+    }
+    intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+
+    if (input.allowsMultipleSelection && input.maxSelection > 1) {
+      intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, true)
+      if (input.backend.source == "android-photo-picker") {
+        intent.putExtra(
+          MediaStore.EXTRA_PICK_IMAGES_MAX,
+          input.maxSelection,
+        )
+      }
+    }
+    return intent
+  }
+
+  override fun parseResult(
+    input: PhotoPickerContractOptions,
+    resultCode: Int,
+    intent: Intent?,
+  ): PhotoPickerContractResult {
+    if (resultCode != Activity.RESULT_OK || intent == null) {
+      return PhotoPickerContractResult.Cancelled(input.backend)
+    }
+
+    val uris = buildList {
+      intent.data?.let(::add)
+      intent.clipData?.let { clipData ->
+        for (index in 0 until clipData.itemCount) {
+          add(clipData.getItemAt(index).uri)
+        }
+      }
+    }.distinct().take(input.maxSelection)
+
+    return if (uris.isEmpty()) {
+      PhotoPickerContractResult.Cancelled(input.backend)
+    } else {
+      PhotoPickerContractResult.Success(uris, input.backend)
+    }
+  }
+}

package/android/src/main/java/com/gaozh1024/photopicker/PhotoPickerModule.kt

@@ -0,0 +1,291 @@
+package com.gaozh1024.photopicker
+
+import android.content.ActivityNotFoundException
+import android.content.ContentResolver
+import android.content.Context
+import android.content.Intent
+import android.graphics.BitmapFactory
+import android.media.MediaMetadataRetriever
+import android.net.Uri
+import android.os.Build
+import android.provider.MediaStore
+import android.provider.OpenableColumns
+import expo.modules.kotlin.activityresult.AppContextActivityResultLauncher
+import expo.modules.kotlin.activityresult.AppContextActivityResultFallbackCallback
+import expo.modules.kotlin.exception.CodedException
+import expo.modules.kotlin.exception.Exceptions
+import expo.modules.kotlin.functions.Coroutine
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import java.io.File
+import java.io.FileOutputStream
+import java.text.SimpleDateFormat
+import java.security.MessageDigest
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import java.util.UUID
+import java.util.concurrent.atomic.AtomicBoolean
+
+private class PickerException(
+  code: String,
+  message: String,
+  cause: Throwable? = null,
+) : CodedException(code, message, cause)
+
+class PhotoPickerModule : Module() {
+  private val context: Context
+    get() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
+
+  private val pickerCacheDirectory: File
+    get() = File(appContext.cacheDirectory, "photo-picker")
+
+  private lateinit var pickerLauncher: AppContextActivityResultLauncher<PhotoPickerContractOptions, PhotoPickerContractResult>
+  private val pickerInFlight = AtomicBoolean(false)
+
+  override fun definition() = ModuleDefinition {
+    Name("PhotoPickerModule")
+
+    RegisterActivityContracts {
+      pickerLauncher = registerForActivityResult(
+        PhotoPickerContract(),
+        AppContextActivityResultFallbackCallback { _, _ ->
+          // The original JS coroutine cannot survive process/context replacement,
+          // but the restored launcher must not leave this module permanently busy.
+          pickerInFlight.set(false)
+        },
+      )
+    }
+
+    AsyncFunction("pickMedia") Coroutine { options: Map<String, Any?>? ->
+      if (!pickerInFlight.compareAndSet(false, true)) {
+        throw PickerException("PICKER_BUSY", "A media picker request is already in progress")
+      }
+
+      try {
+        val backend = resolveBackend()
+        val normalized = normalizeOptions(options, backend)
+        validateSelectionLimit(normalized, backend)
+        val input = normalized.copy(backend = backend)
+        val result = try {
+          pickerLauncher.launch(input)
+        } catch (error: ActivityNotFoundException) {
+          throw PickerException(
+            "PICKER_LAUNCH_FAILED",
+            "Unable to launch the resolved media picker (${backend.action})",
+            error,
+          )
+        } catch (error: SecurityException) {
+          throw PickerException(
+            "PICKER_LAUNCH_FAILED",
+            "The resolved media picker rejected the launch (${backend.action})",
+            error,
+          )
+        } catch (error: IllegalArgumentException) {
+          throw PickerException(
+            "PICKER_LAUNCH_FAILED",
+            "The resolved media picker received invalid launch arguments (${backend.action})",
+            error,
+          )
+        }
+        when (result) {
+          is PhotoPickerContractResult.Cancelled -> mapOf(
+            "cancelled" to true,
+            "assets" to emptyList<Map<String, Any?>>(),
+            "source" to result.backend.source,
+            "action" to result.backend.action,
+          )
+          is PhotoPickerContractResult.Success -> mapOf(
+            "cancelled" to false,
+            "assets" to result.uris.map { materialize(it, result.backend) },
+            "source" to result.backend.source,
+            "action" to result.backend.action,
+          )
+        }
+      } finally {
+        pickerInFlight.set(false)
+      }
+    }
+
+    AsyncFunction("releaseMedia") { uris: List<String> ->
+      val root = pickerCacheDirectory.canonicalFile
+      uris.forEach { uriString ->
+        val file = uriString.toFileOrNull() ?: return@forEach
+        if (file.canonicalFile.path.startsWith(root.path)) {
+          file.delete()
+        }
+      }
+    }
+
+    AsyncFunction("clearPickerCache") {
+      pickerCacheDirectory.deleteRecursively()
+    }
+  }
+
+  private fun normalizeOptions(options: Map<String, Any?>?, backend: PickerBackend): PhotoPickerContractOptions {
+    val mediaType = (options?.get("mediaType") as? String).let {
+      if (it == "photo" || it == "video") it else "all"
+    }
+    val requestedMax = (options?.get("maxSelection") as? Number)?.toInt() ?: 1
+    val allowsMultiple = (options?.get("allowsMultipleSelection") as? Boolean) ?: (requestedMax > 1)
+    val maxSelection = if (allowsMultiple) requestedMax.coerceAtLeast(1) else 1
+    return PhotoPickerContractOptions(mediaType, maxSelection, allowsMultiple, backend)
+  }
+
+  private fun resolveBackend(): PickerBackend {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+      val photoPickerIntent = Intent(MediaStore.ACTION_PICK_IMAGES)
+      if (photoPickerIntent.resolveActivity(context.packageManager) != null) {
+        return PickerBackend("android-photo-picker", MediaStore.ACTION_PICK_IMAGES)
+      }
+    }
+    return PickerBackend("android-open-document", Intent.ACTION_OPEN_DOCUMENT)
+  }
+
+  private fun validateSelectionLimit(options: PhotoPickerContractOptions, backend: PickerBackend) {
+    if (!options.allowsMultiple || options.maxSelection <= 1 || backend.source != "android-photo-picker") return
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) return
+
+    val systemLimit = MediaStore.getPickImagesMaxLimit()
+    if (options.maxSelection > systemLimit) {
+      throw PickerException(
+        "PICKER_SELECTION_LIMIT_UNSUPPORTED",
+        "Requested ${options.maxSelection} media items, but this Photo Picker supports at most $systemLimit",
+      )
+    }
+  }
+
+  private fun materialize(sourceUri: Uri, backend: PickerBackend): Map<String, Any?> {
+    val resolver = context.contentResolver
+    val mimeType = resolver.getType(sourceUri) ?: "application/octet-stream"
+    val sourceName = queryDisplayName(resolver, sourceUri) ?: defaultFileName(mimeType)
+    val safeName = sanitizeFileName(sourceName)
+    val destinationDirectory = File(pickerCacheDirectory, UUID.randomUUID().toString()).apply { mkdirs() }
+    val destination = File(destinationDirectory, safeName)
+
+    resolver.openInputStream(sourceUri).use { input ->
+      requireNotNull(input) { "Unable to read selected media URI" }
+      FileOutputStream(destination).use { output -> input.copyTo(output) }
+    }
+
+    val dimensions = readDimensions(resolver, sourceUri, mimeType)
+    val durationMs = readDuration(resolver, sourceUri, mimeType)
+    val capturedAt = readCapturedAt(resolver, sourceUri)
+    val mediaType = if (mimeType.startsWith("video/")) "video" else "photo"
+    val fileUri = Uri.fromFile(destination).toString()
+
+    return mapOf(
+      "id" to sha256(sourceUri.toString()),
+      "uri" to fileUri,
+      "localUri" to fileUri,
+      "originalUri" to sourceUri.toString(),
+      "filename" to safeName,
+      "fileName" to safeName,
+      "mimeType" to mimeType,
+      "mediaType" to mediaType,
+      "fileSize" to destination.length(),
+      "width" to dimensions.first,
+      "height" to dimensions.second,
+      "duration" to (durationMs?.toDouble()?.div(1000.0)),
+      "durationMs" to durationMs,
+      "metadata" to capturedAt?.let { mapOf("capturedAt" to it) },
+      "source" to backend.source,
+      "action" to backend.action,
+    )
+  }
+
+  private fun readCapturedAt(resolver: ContentResolver, uri: Uri): String? {
+    return try {
+      resolver.query(
+        uri,
+        // MediaStore uses the legacy `datetaken` column name. Some picker
+        // providers do not expose it; the query is intentionally best-effort
+        // and the server can still enrich image EXIF metadata after upload.
+        arrayOf("datetaken", "date_modified"),
+        null,
+        null,
+        null,
+      )?.use { cursor ->
+        if (!cursor.moveToFirst()) return@use null
+        val dateTakenIndex = cursor.getColumnIndex("datetaken")
+        val dateModifiedIndex = cursor.getColumnIndex("date_modified")
+        val dateTaken = if (dateTakenIndex >= 0 && !cursor.isNull(dateTakenIndex)) cursor.getLong(dateTakenIndex) else 0L
+        val dateModifiedSeconds = if (dateModifiedIndex >= 0 && !cursor.isNull(dateModifiedIndex)) cursor.getLong(dateModifiedIndex) else 0L
+        val timestampMs = when {
+          dateTaken > 0L -> dateTaken
+          dateModifiedSeconds > 0L -> dateModifiedSeconds * 1000L
+          else -> 0L
+        }
+        if (timestampMs > 0L) formatRFC3339(timestampMs) else null
+      }
+    } catch (_: Exception) {
+      null
+    }
+  }
+
+  private fun formatRFC3339(timestampMs: Long): String {
+    return SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US).apply {
+      timeZone = TimeZone.getTimeZone("UTC")
+    }.format(Date(timestampMs))
+  }
+
+  private fun queryDisplayName(resolver: ContentResolver, uri: Uri): String? {
+    return resolver.query(uri, arrayOf(OpenableColumns.DISPLAY_NAME), null, null, null)?.use { cursor ->
+      if (cursor.moveToFirst()) cursor.getString(0) else null
+    }
+  }
+
+  private fun readDimensions(resolver: ContentResolver, uri: Uri, mimeType: String): Pair<Int, Int> {
+    if (mimeType.startsWith("image/")) {
+      return resolver.openFileDescriptor(uri, "r")?.use { descriptor ->
+        val options = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+        BitmapFactory.decodeFileDescriptor(descriptor.fileDescriptor, null, options)
+        Pair(options.outWidth.coerceAtLeast(0), options.outHeight.coerceAtLeast(0))
+      } ?: Pair(0, 0)
+    }
+    val retriever = MediaMetadataRetriever()
+    return try {
+      retriever.setDataSource(context, uri)
+      Pair(
+        retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)?.toIntOrNull() ?: 0,
+        retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)?.toIntOrNull() ?: 0,
+      )
+    } catch (_: Exception) {
+      Pair(0, 0)
+    } finally {
+      retriever.release()
+    }
+  }
+
+  private fun readDuration(resolver: ContentResolver, uri: Uri, mimeType: String): Long? {
+    if (!mimeType.startsWith("video/")) return null
+    val retriever = MediaMetadataRetriever()
+    return try {
+      retriever.setDataSource(context, uri)
+      retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_DURATION)?.toLongOrNull()
+    } catch (_: Exception) {
+      null
+    } finally {
+      retriever.release()
+    }
+  }
+
+  private fun sanitizeFileName(name: String): String {
+    val cleaned = name.replace(Regex("[^A-Za-z0-9._-]"), "_").trim('_')
+    return if (cleaned.isBlank()) "media-${UUID.randomUUID()}" else cleaned.take(180)
+  }
+
+  private fun defaultFileName(mimeType: String): String {
+    val extension = mimeType.substringAfter('/', "bin").lowercase(Locale.ROOT)
+    return "media-${UUID.randomUUID()}.$extension"
+  }
+
+  private fun sha256(value: String): String {
+    val digest = MessageDigest.getInstance("SHA-256").digest(value.toByteArray())
+    return digest.joinToString("") { byte -> "%02x".format(byte) }
+  }
+
+  private fun String.toFileOrNull(): File? {
+    return if (startsWith("file://")) runCatching { File(Uri.parse(this).path ?: return null) }.getOrNull() else null
+  }
+}