@onekeyfe/react-native-photo-library 0.0.0-stage → 3.0.165

package/LICENSE

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

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @onekeyfe/react-native-photo-library
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Minimal add-only image saving. [Contract and acceptance](docs/SPEC.md).
+
+```ts
+import PhotoLibrary from '@onekeyfe/react-native-photo-library';
+
+// Invoke only after the user explicitly chooses Save.
+const permission = await PhotoLibrary.requestSavePermission();
+if (permission.status === 'granted') {
+  await PhotoLibrary.saveToLibrary('file:///local/image.png');
+}
+```
+
+`getSavePermission()` checks without prompting. `saveToLibrary()` never requests
+permission, reads back assets, or removes its source. Inputs must be local images
+of at most 64 MiB. Keep the source until completion. General file IO remains in
+RNFS; use the separate OneKey picker for user selection and cropping.
+
+iOS uses Photos `.addOnly`; keep `NSPhotoLibraryAddUsageDescription` in the App.
+Android 10+ uses MediaStore with no storage permission. Android 8-9 requires App
+`WRITE_EXTERNAL_STORAGE` capped at `maxSdkVersion=28`; request it only on Save.
+iOS and Android 10+ do not request whole-library read authorization. On Android
+8-9, granting the legacy write permission also implicitly grants storage read
+access, and the system prompt describes access to photos, media and files.
+Permanent denial is returned as `{status: 'denied', canAskAgain: false}`.
+`PhotoLibraryError.code` identifies permission, missing input,
+activity/concurrency and save failures.

package/ReactNativePhotoLibrary.podspec

@@ -0,0 +1,36 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativePhotoLibrary"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/OneKeyHQ/app-modules/react-native-photo-library.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  s.exclude_files = "ios/tests/**/*"
+  s.frameworks = "Photos", "ImageIO", "UniformTypeIdentifiers"
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  s.dependency 'ReactNativeNativeLogger'
+
+  load 'nitrogen/generated/ios/ReactNativePhotoLibrary+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+  s.test_spec "Tests" do |test_spec|
+    test_spec.source_files = "ios/tests/**/*.swift"
+  end
+end

package/android/CMakeLists.txt

@@ -0,0 +1,24 @@
+project(reactnativephotolibrary)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME reactnativephotolibrary)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/reactnativephotolibrary+autolinking.cmake)
+
+# Set up local includes
+include_directories("src/main/cpp" "../cpp")
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,132 @@
+buildscript {
+  ext.getExtOrDefault = {name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['ReactNativePhotoLibrary_' + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/reactnativephotolibrary+autolinking.gradle'
+
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["ReactNativePhotoLibrary_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.reactnativephotolibrary"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "androidx.activity:activity:1.10.1"
+
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+  implementation project(":react-native-nitro-modules")
+
+  implementation project(":onekeyfe_react-native-native-logger")
+}

package/android/gradle.properties

@@ -0,0 +1,4 @@
+ReactNativePhotoLibrary_kotlinVersion=1.9.25
+ReactNativePhotoLibrary_compileSdkVersion=35
+ReactNativePhotoLibrary_targetSdkVersion=35
+ReactNativePhotoLibrary_minSdkVersion=24

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "reactnativephotolibraryOnLoad.hpp"
+
+extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::reactnativephotolibrary::initialize(vm);
+}

package/android/src/main/java/com/margelo/nitro/reactnativephotolibrary/ImagePhotoLibrary.kt

@@ -0,0 +1,207 @@
+package com.margelo.nitro.reactnativephotolibrary
+
+import android.Manifest
+import android.app.Activity
+import android.graphics.BitmapFactory
+import com.facebook.react.ReactApplication
+import android.content.ContentValues
+import android.content.Context
+import android.content.pm.PackageManager
+import android.media.MediaScannerConnection
+import android.net.Uri
+import android.os.Build
+import android.os.Environment
+import android.os.Handler
+import android.os.Looper
+import android.provider.MediaStore
+import android.webkit.MimeTypeMap
+import androidx.activity.ComponentActivity
+import androidx.activity.result.ActivityResultLauncher
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.core.app.ActivityCompat
+import androidx.core.content.ContextCompat
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.Promise
+import java.io.File
+import java.util.UUID
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+
+internal object ImagePhotoLibrary {
+  private val mainHandler = Handler(Looper.getMainLooper())
+  private val saveExecutor = Executors.newSingleThreadExecutor()
+  private var permissionPending = false
+  private const val REQUESTED = "writePermissionRequested"
+
+  private fun context(): Context = NitroModules.applicationContext ?: throw PhotoLibraryException.noActivity()
+
+  private fun foregroundActivity(): Activity? {
+    // Nitro's global context can belong to bg; ReactHost owns the UI activity.
+    return (context().applicationContext as? ReactApplication)?.reactHost?.currentReactContext?.currentActivity
+      ?: NitroModules.applicationContext?.currentActivity
+  }
+
+  private fun imageMime(file: File): String {
+    if (!file.isFile || file.length() <= 0 || file.length() > 64 * 1024 * 1024) {
+      throw PhotoLibraryException.noImageData()
+    }
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeFile(file.absolutePath, bounds)
+    val mime = bounds.outMimeType
+    if (bounds.outWidth <= 0 || bounds.outHeight <= 0 || mime?.startsWith("image/") != true) {
+      throw PhotoLibraryException.noImageData()
+    }
+    return mime
+  }
+
+  fun permission(): PhotoSavePermission {
+    if (Build.VERSION.SDK_INT >= 29) return PhotoSavePermission(PhotoSavePermissionStatus.GRANTED, true)
+    val context = context()
+    if (ContextCompat.checkSelfPermission(context, Manifest.permission.WRITE_EXTERNAL_STORAGE) == PackageManager.PERMISSION_GRANTED) {
+      return PhotoSavePermission(PhotoSavePermissionStatus.GRANTED, true)
+    }
+    val requested = context.getSharedPreferences("onekey-photo-library", Context.MODE_PRIVATE).getBoolean(REQUESTED, false)
+    if (!requested) return PhotoSavePermission(PhotoSavePermissionStatus.UNDETERMINED, true)
+    val activity = foregroundActivity() ?: throw PhotoLibraryException.noActivity()
+    return PhotoSavePermission(
+      PhotoSavePermissionStatus.DENIED,
+      ActivityCompat.shouldShowRequestPermissionRationale(activity, Manifest.permission.WRITE_EXTERNAL_STORAGE),
+    )
+  }
+
+  fun getPermission(): Promise<PhotoSavePermission> {
+    val promise = Promise<PhotoSavePermission>()
+    mainHandler.post {
+      try { promise.resolve(permission()) } catch (error: Exception) { promise.reject(error) }
+    }
+    return promise
+  }
+
+  fun requestPermission(): Promise<PhotoSavePermission> {
+    val promise = Promise<PhotoSavePermission>()
+    mainHandler.post {
+      var launcher: ActivityResultLauncher<String>? = null
+      var observer: DefaultLifecycleObserver? = null
+      val activity = foregroundActivity() as? ComponentActivity
+      var finished = false
+      var ownsRequest = false
+      fun finish(error: Exception? = null) {
+        if (finished) return
+        finished = true
+        if (ownsRequest) permissionPending = false
+        observer?.let { activity?.lifecycle?.removeObserver(it) }
+        mainHandler.post { launcher?.unregister() }
+        try {
+          if (error == null) promise.resolve(permission()) else promise.reject(error)
+        } catch (failure: Exception) { promise.reject(failure) }
+      }
+      try {
+        val current = permission()
+        if (current.status == PhotoSavePermissionStatus.GRANTED || !current.canAskAgain) {
+          promise.resolve(current)
+          return@post
+        }
+        if (permissionPending) {
+          promise.reject(PhotoLibraryException.inProgress())
+          return@post
+        }
+        if (activity == null || activity.isFinishing || activity.isDestroyed) {
+          promise.reject(PhotoLibraryException.noActivity())
+          return@post
+        }
+        permissionPending = true
+        ownsRequest = true
+        observer = object : DefaultLifecycleObserver {
+          override fun onDestroy(owner: LifecycleOwner) { finish(PhotoLibraryException.noActivity()) }
+        }
+        activity.lifecycle.addObserver(observer!!)
+        launcher = activity.activityResultRegistry.register(
+          "onekey-photo-save-${UUID.randomUUID()}", ActivityResultContracts.RequestPermission(),
+        ) { finish() }
+        val preferences = context().getSharedPreferences("onekey-photo-library", Context.MODE_PRIVATE)
+        val previouslyRequested = preferences.getBoolean(REQUESTED, false)
+        preferences.edit().putBoolean(REQUESTED, true).apply()
+        try {
+          launcher!!.launch(Manifest.permission.WRITE_EXTERNAL_STORAGE)
+        } catch (error: Exception) {
+          preferences.edit().putBoolean(REQUESTED, previouslyRequested).apply()
+          throw error
+        }
+      } catch (error: Exception) { finish(error) }
+    }
+    return promise
+  }
+
+  fun save(path: String): Promise<Unit> {
+    val promise = Promise<Unit>()
+    saveExecutor.execute {
+      try {
+        val context = context()
+        if (Build.VERSION.SDK_INT < 29 && ContextCompat.checkSelfPermission(context, Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {
+          throw PhotoLibraryException.noLibraryPermission()
+        }
+        val file = when {
+          path.startsWith("/") -> File(path)
+          path.startsWith("file://") -> Uri.parse(path).let { uri ->
+            if (uri.authority.isNullOrEmpty() || uri.authority == "localhost") uri.path?.let { File(it) } else null
+          }
+          else -> null
+        } ?: throw PhotoLibraryException.noImageData()
+        val mime = imageMime(file)
+        val extension = MimeTypeMap.getSingleton().getExtensionFromMimeType(mime) ?: "img"
+        val name = "onekey-${UUID.randomUUID()}.$extension"
+        if (Build.VERSION.SDK_INT >= 29) saveModern(context, file, mime, name) else saveLegacy(context, file, mime, name)
+        promise.resolve(Unit)
+      } catch (error: PhotoLibraryException) {
+        promise.reject(error)
+      } catch (error: Exception) {
+        promise.reject(PhotoLibraryException.cannotSaveImage(error))
+      }
+    }
+    return promise
+  }
+
+  private fun saveModern(context: Context, source: File, mime: String, name: String) {
+    val resolver = context.contentResolver
+    val values = ContentValues().apply {
+      put(MediaStore.Images.Media.DISPLAY_NAME, name)
+      put(MediaStore.Images.Media.MIME_TYPE, mime)
+      put(MediaStore.Images.Media.RELATIVE_PATH, "${Environment.DIRECTORY_PICTURES}/OneKey")
+      put(MediaStore.Images.Media.IS_PENDING, 1)
+    }
+    val uri = resolver.insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values)
+      ?: throw PhotoLibraryException.cannotSaveImage()
+    try {
+      val stream = resolver.openOutputStream(uri) ?: throw PhotoLibraryException.cannotSaveImage()
+      stream.use { output -> source.inputStream().use { it.copyTo(output) } }
+      val published = ContentValues().apply { put(MediaStore.Images.Media.IS_PENDING, 0) }
+      if (resolver.update(uri, published, null, null) != 1) throw PhotoLibraryException.cannotSaveImage()
+    } catch (error: Exception) {
+      try { resolver.delete(uri, null, null) } catch (_: Exception) { }
+      throw error
+    }
+  }
+
+  @Suppress("DEPRECATION")
+  private fun saveLegacy(context: Context, source: File, mime: String, name: String) {
+    val directory = File(Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES), "OneKey")
+    if (!directory.isDirectory && !directory.mkdirs()) throw PhotoLibraryException.cannotSaveImage()
+    val destination = File(directory, name)
+    try {
+      source.inputStream().use { input -> destination.outputStream().use { input.copyTo(it) } }
+      val scanned = CountDownLatch(1)
+      var savedUri: Uri? = null
+      MediaScannerConnection.scanFile(context, arrayOf(destination.absolutePath), arrayOf(mime)) { _, uri ->
+        savedUri = uri
+        scanned.countDown()
+      }
+      if (!scanned.await(30, TimeUnit.SECONDS) || savedUri == null) throw PhotoLibraryException.cannotSaveImage()
+    } catch (error: Exception) {
+      destination.delete()
+      throw error
+    }
+  }
+}

package/android/src/main/java/com/margelo/nitro/reactnativephotolibrary/PhotoLibraryException.kt

@@ -0,0 +1,12 @@
+package com.margelo.nitro.reactnativephotolibrary
+
+internal class PhotoLibraryException(code: String, message: String, cause: Throwable? = null) :
+  Exception("$code: $message", cause) {
+  companion object {
+    fun noActivity() = PhotoLibraryException("E_ACTIVITY_DOES_NOT_EXIST", "Activity doesn't exist")
+    fun inProgress() = PhotoLibraryException("E_PERMISSION_IN_PROGRESS", "Another save permission request is pending")
+    fun noImageData() = PhotoLibraryException("E_NO_IMAGE_DATA_FOUND", "Cannot find image data")
+    fun noLibraryPermission() = PhotoLibraryException("E_NO_LIBRARY_PERMISSION", "Adding photos is not authorized")
+    fun cannotSaveImage(cause: Throwable? = null) = PhotoLibraryException("E_CANNOT_SAVE_IMAGE", "Cannot save image", cause)
+  }
+}

package/android/src/main/java/com/margelo/nitro/reactnativephotolibrary/ReactNativePhotoLibrary.kt

@@ -0,0 +1,11 @@
+package com.margelo.nitro.reactnativephotolibrary
+
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.core.Promise
+
+@DoNotStrip
+class ReactNativePhotoLibrary : HybridReactNativePhotoLibrarySpec() {
+  override fun getSavePermission(): Promise<PhotoSavePermission> = ImagePhotoLibrary.getPermission()
+  override fun requestSavePermission(): Promise<PhotoSavePermission> = ImagePhotoLibrary.requestPermission()
+  override fun saveToLibrary(path: String): Promise<Unit> = ImagePhotoLibrary.save(path)
+}

package/android/src/main/java/com/margelo/nitro/reactnativephotolibrary/ReactNativePhotoLibraryPackage.kt

@@ -0,0 +1,22 @@
+package com.margelo.nitro.reactnativephotolibrary
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class ReactNativePhotoLibraryPackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider { HashMap() }
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("reactnativephotolibrary")
+        }
+    }
+}

package/docs/SPEC.md

@@ -0,0 +1,108 @@
+# Add-only photo saving
+
+Status: Implemented extraction of the picker save implementation. After the
+latest main merge, JS tests, types, codegen and Android native builds passed;
+all nine iOS SDK XCTest suites, including the three photo-library
+validation/permission-mapping cases, passed in CI at `a8e9fd9d`. API 36 saves
+through MediaStore without a permission prompt, and
+failed input rejects with the documented code. API 28 saving and first
+grant/denial were exercised; permanent denial and lifecycle/failure cases remain
+pending. Actual iOS App add-only authorization and saving are unverified because
+the local App build failed in ExpoModulesJSI. SDK checks do not replace App UI
+acceptance or final release artifact inspection.
+
+## Purpose and boundaries
+
+Save one caller-owned local image to the system photo library on iOS/Android.
+Only getSavePermission, requestSavePermission and saveToLibrary are public
+operations. No selection, cropping, album listing, asset readback, deletion,
+remote download, video or general filesystem API is provided. Generic app file
+operations remain in RNFS. OS-required stream writes are part of the save
+transaction; no intermediate image copy is created. Picker item-provider copies
+remain in the picker because they must finish before the native callback returns;
+there is no second consumer requiring a shared temporary-copy helper.
+
+Callers use the foreground/main JS runtime. main and bg initialize independently
+and have separate JS objects/heaps. Native save queues and Android pending
+permission ownership are process-shared; no bg readiness is assumed. Import is
+lazy and performs no I/O or permission request.
+
+## Public API and defaults
+
+- getSavePermission(): Promise<PhotoSavePermission>, no prompt.
+- requestSavePermission(): Promise<PhotoSavePermission>, called only after an
+  explicit user save action. Permission is never requested by import or save.
+- saveToLibrary(path: string): Promise<void>, requires existing save permission.
+  Accepts an absolute local path or file:// URI, and resolves after OS completion.
+- PhotoSavePermission: {status: 'granted' | 'denied' | 'undetermined',
+  canAskAgain: boolean}. Denied is never translated to successful save.
+- PhotoLibraryError.code is E_NO_LIBRARY_PERMISSION, E_NO_IMAGE_DATA_FOUND,
+  E_CANNOT_SAVE_IMAGE, E_PERMISSION_IN_PROGRESS, E_ACTIVITY_DOES_NOT_EXIST or
+  E_UNKNOWN. No raw native stack or file path is exposed in library errors.
+- Missing, non-image or over-64-MiB input rejects E_NO_IMAGE_DATA_FOUND. Metadata
+  must identify an image with positive dimensions; no full pixel decode occurs.
+  Callers must keep the source unchanged and present until the promise settles.
+
+## Platform contract
+
+| Behavior | iOS | Android |
+| --- | --- | --- |
+| Authorization | PHPhotoLibrary .addOnly | API 29+: granted without prompt; API 26-28: WRITE_EXTERNAL_STORAGE |
+| Permanent denial | denied/restricted, canAskAgain false | Previously requested plus OS rationale false |
+| Save | PHAssetCreationRequest.addResource, no readback | API 29+: MediaStore pending insert/write/publish; API 26-28: Pictures/OneKey + scan |
+| Declaration | App keeps NSPhotoLibraryAddUsageDescription | App declares WRITE_EXTERNAL_STORAGE with maxSdkVersion 28 |
+
+The module declares no Android storage/media-read permission. App configuration
+owns the legacy write declaration and iOS usage strings. No NSPhotoLibraryUsageDescription
+is needed. Android permission launch resolves the UI ReactHost activity rather
+than relying on the global Nitro context (which may belong to bg).
+
+On Android 8-9, the OS legacy storage permission group is broader than the APK
+declaration: granting WRITE_EXTERNAL_STORAGE also grants implicit read access.
+The maxSdkVersion cap limits this compatibility behavior to API 28 and below.
+API 29+ uses MediaStore without a storage permission request.
+
+## Lifecycle, concurrency and ownership
+
+Permissions launch on the UI thread. Android owns at most one pending request
+process-wide, rejects overlapping requests with E_PERMISSION_IN_PROGRESS, and
+unregisters the launcher/observer on completion or activity destruction. Teardown
+rejects E_ACTIVITY_DOES_NOT_EXIST. Each promise settles at most once.
+Saves run serially on one background queue per platform; no retry or app cache.
+Android persists only whether legacy write authorization has been requested, in
+onekey-photo-library/writePermissionRequested (preserved from the picker).
+UUID destination names avoid overwriting another save. Source files are never
+removed. No JS cache, DB schema, migration or asset index is introduced.
+
+## Failure and resources
+
+Modern Android deletes failed pending rows best-effort and publishes only after
+stream completion. Legacy Android removes failed output, waits at most 30 seconds
+for media scanning, and rejects null/late scan results. A late OS callback can
+leave a stale OS index entry after timeout; the failed file is removed.
+iOS failures reject without fetching the newly created asset. No automatic retry.
+Streaming uses bounded buffers; metadata and save I/O stay off the UI thread.
+Input cap is 64 MiB. No unmeasured memory/latency claim is made. Paths and image
+bytes are never logged by this package. Queued sources remain caller-owned.
+
+## Conformance and acceptance
+
+Contract locations: Nitro spec, lazy JS wrapper, platform ReactNativePhotoLibrary
+and ImagePhotoLibrary implementations. Focused JS checks cover native permission
+results, save-error mapping, and absence of implicit permission requests. Native
+checks cover input validation and iOS permission mapping; bridge generation,
+TypeScript and native builds cover registration and compilation.
+Required runtime cases: iOS first add-only grant/deny/permanent deny and saved
+asset, with full-library access denied; Android API 28 first grant/deny/permanent
+deny and scan completion; API 29+ save without prompt and no media-read grants;
+concurrent permission request, activity teardown, missing/oversized source,
+cleanup after failed write. Final App APK/AAB and iOS Info.plist must be inspected
+independently. Automated/source checks do not prove those UI cases.
+
+## Template deviations
+
+The repository create:module template is used. Placeholder add API is replaced
+with the three save APIs. Local package Babel removes an undeclared module-resolver
+plugin, ESLint uses the repository's working FlatCompat setup, and RN devDependency
+matches the root patched RN version. A Photos test spec/frameworks and Android
+activity-result dependency are required for the extracted behavior.