react-native-picture-selector 1.0.1 → 1.0.6

package/README.md

@@ -1,11 +1,11 @@
 # react-native-picture-selector
 
-High-performance photo and video picker for React Native, built on **[Nitro Modules](https://github.com/mrousavy/nitro)** (JSI, zero bridge overhead).
+High-performance photo and video picker for React Native, built on **Nitro Modules** (JSI, zero bridge overhead).
 
 | Platform | Native library | Min OS |
 |----------|---------------|--------|
-| Android  | [LuckSiege/PictureSelector](https://github.com/LuckSiege/PictureSelector) v3.11.2 | Android 7.0 (API 24) |
-| iOS      | [SilenceLove/HXPhotoPicker](https://github.com/SilenceLove/HXPhotoPicker) v5.0.5  | iOS 13.0 |
+| Android  | LuckSiege/PictureSelector v3.11.2 | Android 7.0 (API 24) |
+| iOS      | SilenceLove/HXPhotoPicker v5.0.5  | iOS 13.0 |
 
 ---
 
@@ -58,22 +58,7 @@ Add required keys to **`ios/YourApp/Info.plist`**:
 
 Permissions are declared in the library manifest and merged automatically. If you target **Android 13+ (API 33)** and also support older versions you need no extra steps — the manifest already uses `maxSdkVersion` to apply the right permission per API level.
 
-Add the FileProvider authority to your app's `AndroidManifest.xml` if you override the default:
-
-```xml
-<!-- Only needed if you customise the FileProvider authority -->
-<provider
-  android:name="androidx.core.content.FileProvider"
-  android:authorities="${applicationId}.fileprovider"
-  android:exported="false"
-  android:grantUriPermissions="true">
-  <meta-data
-    android:name="android.support.FILE_PROVIDER_PATHS"
-    android:resource="@xml/file_paths" />
-</provider>
-```
-
-#### Manual package registration (non-autolinking setups)
+For apps that don't use autolinking, register the package manually:
 
 ```kotlin
 // android/app/src/main/java/.../MainApplication.kt
@@ -93,8 +78,9 @@ const assets = await PictureSelector.openPicker({
   maxCount: 1,
 })
 
-console.log(assets[0].uri)   // file:///...
-console.log(assets[0].width) // 1280
+console.log(assets[0].uri)      // file:///data/user/0/.../image.jpg
+console.log(assets[0].width)    // 4032
+console.log(assets[0].fileSize) // 2457600
 ```
 
 ---
@@ -103,24 +89,30 @@ console.log(assets[0].width) // 1280
 
 ### `PictureSelector.openPicker(options?)`
 
-Opens the native gallery picker. Returns a `Promise<MediaAsset[]>`.
+Opens the native gallery picker. Returns `Promise<MediaAsset[]>`.
+
+The promise rejects with `PickerError` when the user dismisses the picker without making a selection.
 
 ```ts
+import { PictureSelector, MediaType, toPickerError } from 'react-native-picture-selector'
+
+// Basic usage
+const assets = await PictureSelector.openPicker()
+
+// With options
 const assets = await PictureSelector.openPicker({
   mediaType: MediaType.ALL,
   maxCount: 9,
   compress: { enabled: true, quality: 0.7 },
 })
-```
-
-Rejects with `PickerError` when the user dismisses without selecting:
 
-```ts
+// Handle cancel
 try {
   const assets = await PictureSelector.openPicker()
-} catch (e) {
-  if ((e as PickerError).code === 'CANCELLED') {
-    // user tapped back / cancel — not an error
+} catch (err) {
+  const e = toPickerError(err)
+  if (e.code === 'CANCELLED') {
+    // user tapped back — not an error
   }
 }
 ```
@@ -129,9 +121,21 @@ try {
 
 ### `PictureSelector.openCamera(options?)`
 
-Opens the device camera for capture. Returns `Promise<MediaAsset[]>` (always one item).
+Opens the device camera. Returns `Promise<MediaAsset[]>` (always one item).
 
 ```ts
+// Take a photo
+const [photo] = await PictureSelector.openCamera({
+  mediaType: MediaType.IMAGE,
+})
+
+// Record a short video
+const [video] = await PictureSelector.openCamera({
+  mediaType: MediaType.VIDEO,
+  maxVideoDuration: 30,
+})
+
+// Take a photo and crop it immediately
 const [photo] = await PictureSelector.openCamera({
   mediaType: MediaType.IMAGE,
   crop: { enabled: true, ratioX: 1, ratioY: 1 },
@@ -142,7 +146,7 @@ const [photo] = await PictureSelector.openCamera({
 
 ### `usePictureSelector(defaultOptions?)`
 
-React hook that manages loading state and the selected asset list.
+React hook that wraps the picker with loading, error, and asset state.
 
 ```tsx
 import { usePictureSelector, MediaType } from 'react-native-picture-selector'
@@ -156,10 +160,10 @@ function PhotoPicker() {
   return (
     <>
       <Button onPress={() => pick()} title="Gallery" disabled={loading} />
-      <Button onPress={() => shoot()} title="Camera" disabled={loading} />
-      <Button onPress={clear} title="Clear" />
+      <Button onPress={() => shoot()} title="Camera"  disabled={loading} />
+      <Button onPress={clear}         title="Clear" />
 
-      {error && <Text>Error: {error.message}</Text>}
+      {error && <Text style={{ color: 'red' }}>Error: {error.message}</Text>}
 
       {assets.map((a, i) => (
         <Image key={i} source={{ uri: a.uri }} style={{ width: 80, height: 80 }} />
@@ -169,13 +173,24 @@ function PhotoPicker() {
 }
 ```
 
+You can also override options per call:
+
+```ts
+// use hook defaults
+await pick()
+
+// override for this call only
+await pick({ maxCount: 1, crop: { enabled: true, ratioX: 16, ratioY: 9 } })
+await shoot({ mediaType: MediaType.VIDEO, maxVideoDuration: 15 })
+```
+
 #### Hook state
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `assets` | `MediaAsset[]` | Currently selected assets |
 | `loading` | `boolean` | `true` while the picker is open |
-| `error` | `PickerError \| null` | Last non-cancel error |
+| `error` | `PickerError \| null` | Last non-cancel error, `null` otherwise |
 
 #### Hook actions
 
@@ -183,105 +198,132 @@ function PhotoPicker() {
 |--------|-----------|-------------|
 | `pick` | `(options?) => Promise<MediaAsset[]>` | Open gallery picker |
 | `shoot` | `(options?) => Promise<MediaAsset[]>` | Open camera |
-| `clear` | `() => void` | Reset assets and error |
+| `clear` | `() => void` | Reset `assets` and `error` to initial state |
 
-> **Cancellation** — `CANCELLED` errors are swallowed by the hook. `pick()` and `shoot()` return `[]` on cancel instead of throwing.
+> **Cancellation** — `CANCELLED` errors are silently swallowed by the hook. `pick()` and `shoot()` return `[]` on cancel instead of throwing.
 
 ---
 
 ## Configuration (`PictureSelectorOptions`)
 
-All fields are optional.
+All fields are optional. Omitting an option uses the native library default.
+
+---
 
 ### Media type
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `mediaType` | `MediaType` | `IMAGE` | `IMAGE`, `VIDEO`, or `ALL` |
-| `maxCount` | `number` | `1` | Maximum selectable items |
-| `enableCamera` | `boolean` | `true` | Show camera button inside the gallery |
+| `maxCount` | `number` | `1` | Maximum selectable items (gallery picker only) |
+| `enableCamera` | `boolean` | `true` | Show camera shortcut inside gallery grid |
 
 ```ts
 import { MediaType } from 'react-native-picture-selector'
 
-// images only
+// Images only, single selection
 openPicker({ mediaType: MediaType.IMAGE })
 
-// videos only
-openPicker({ mediaType: MediaType.VIDEO })
+// Videos only, up to 3
+openPicker({ mediaType: MediaType.VIDEO, maxCount: 3 })
 
-// mixed, up to 9
+// Mixed photo + video, up to 9
 openPicker({ mediaType: MediaType.ALL, maxCount: 9 })
+
+// Gallery without in-picker camera button
+openPicker({ enableCamera: false })
 ```
 
 ---
 
 ### Cropping (`crop`)
 
-Crop applies only when `maxCount === 1`.
+Crop is applied automatically **after** the user selects a photo. It activates only when `maxCount === 1`.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `crop.enabled` | `boolean` | — | Enable crop after selection |
-| `crop.ratioX` | `number` | `1` | Width ratio |
-| `crop.ratioY` | `number` | `1` | Height ratio |
-| `crop.freeStyle` | `boolean` | `false` | Free-form crop (ignores ratio) |
+| `crop.enabled` | `boolean` | `false` | Enable the crop editor |
+| `crop.ratioX` | `number` | `1` | Crop width part of the ratio |
+| `crop.ratioY` | `number` | `1` | Crop height part of the ratio |
+| `crop.freeStyle` | `boolean` | `false` | Let the user freely resize the crop frame |
 | `crop.circular` | `boolean` | `false` | Circular crop mask **(iOS only)** |
 
 ```ts
-// Square crop
+// Square crop (avatar)
 openPicker({ crop: { enabled: true, ratioX: 1, ratioY: 1 } })
 
-// 16:9 crop
+// Widescreen banner 16:9
 openPicker({ crop: { enabled: true, ratioX: 16, ratioY: 9 } })
 
-// Free-style
+// Portrait 3:4
+openPicker({ crop: { enabled: true, ratioX: 3, ratioY: 4 } })
+
+// Free-form — user defines any size
 openPicker({ crop: { enabled: true, freeStyle: true } })
 
-// Circular (iOS)
+// Circular (iOS only — falls back to 1:1 on Android)
 openPicker({ crop: { enabled: true, circular: true } })
 ```
 
-> Android uses **uCrop**. iOS uses the built-in **HXPhotoPicker editor**.
+> **Android** uses the uCrop library for cropping.
+> **iOS** uses the built-in HXPhotoPicker photo editor.
+
+The cropped file path is available at `asset.editedUri`. The original (un-cropped) file is at `asset.uri`.
 
 ---
 
 ### Compression (`compress`)
 
+Compression runs **after** crop (if enabled). The original file is never modified — a new compressed copy is returned.
+
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `compress.enabled` | `boolean` | — | Enable compression |
-| `compress.quality` | `number` | `0.8` | JPEG quality `0.0`–`1.0` |
-| `compress.maxWidth` | `number` | `1920` | Max output width (px) |
-| `compress.maxHeight` | `number` | `1920` | Max output height (px) |
+| `compress.enabled` | `boolean` | `false` | Enable compression |
+| `compress.quality` | `number` | `0.8` | JPEG quality `0.0` (smallest) – `1.0` (lossless) |
+| `compress.maxWidth` | `number` | `1920` | Max output width in pixels (aspect preserved) |
+| `compress.maxHeight` | `number` | `1920` | Max output height in pixels (aspect preserved) |
 
 ```ts
+// Light compression for fast upload
 openPicker({
-  compress: {
-    enabled: true,
-    quality: 0.6,
-    maxWidth: 1280,
-    maxHeight: 1280,
-  },
+  compress: { enabled: true, quality: 0.8, maxWidth: 1920, maxHeight: 1920 },
+})
+
+// Heavy compression for thumbnails
+openPicker({
+  compress: { enabled: true, quality: 0.5, maxWidth: 640, maxHeight: 640 },
+})
+
+// Compress but keep original dimensions
+openPicker({
+  compress: { enabled: true, quality: 0.7 },
 })
 ```
 
-> Android uses **Luban**. iOS uses **HXPhotoPicker** native compression.
+> **Android** uses the Luban library. Files under 100 KB are passed through without compression.
+> **iOS** uses HXPhotoPicker's native compression pipeline.
 
 ---
 
 ### Video limits
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `maxVideoDuration` | `number` | Max video duration in **seconds** |
-| `minVideoDuration` | `number` | Min video duration in **seconds** |
+| Field | Type | Unit | Description |
+|-------|------|------|-------------|
+| `maxVideoDuration` | `number` | seconds | Reject (hide) videos longer than this |
+| `minVideoDuration` | `number` | seconds | Reject (hide) videos shorter than this |
 
 ```ts
+// Only show videos between 3 and 60 seconds
 openPicker({
   mediaType: MediaType.VIDEO,
-  maxVideoDuration: 60,
   minVideoDuration: 3,
+  maxVideoDuration: 60,
+})
+
+// Camera: stop recording automatically at 15 s
+openCamera({
+  mediaType: MediaType.VIDEO,
+  maxVideoDuration: 15,
 })
 ```
 
@@ -291,30 +333,49 @@ openPicker({
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `theme` | `PickerTheme` | Preset theme: `DEFAULT`, `WECHAT`, `WHITE`, `DARK` (Android) |
-| `themeColor` | `string` | Hex accent color, e.g. `"#007AFF"` (iOS: `themeColor`; Android: accent) |
+| `theme` | `PickerTheme` | Preset theme for the picker UI (Android only) |
+| `themeColor` | `string` | Hex accent color, e.g. `"#007AFF"` (both platforms) |
 
 ```ts
 import { PickerTheme } from 'react-native-picture-selector'
 
-// Android WeChat style
+// Android — WeChat-style dark green theme
 openPicker({ theme: PickerTheme.WECHAT })
 
-// Custom accent color (both platforms)
-openPicker({ themeColor: '#1DB954' })
+// Android — clean white theme
+openPicker({ theme: PickerTheme.WHITE })
+
+// Android — dark / night theme
+openPicker({ theme: PickerTheme.DARK })
+
+// Both platforms — custom accent colour
+openPicker({ themeColor: '#1DB954' })  // Spotify green
+openPicker({ themeColor: '#007AFF' })  // iOS blue
+openPicker({ themeColor: '#E91E63' })  // Pink
 ```
 
+> `theme` enum values (`WECHAT`, `WHITE`, `DARK`) are ignored on iOS. Use `themeColor` for cross-platform tinting.
+
 ---
 
 ### Pre-selected assets
 
-Pass `file://` URIs of previously selected files to restore the selection state:
+Pass `file://` URIs of previously selected files to pre-check them in the gallery grid.
 
 ```ts
-openPicker({
+// Store selection
+const [selectedAssets, setSelectedAssets] = useState<MediaAsset[]>([])
+
+// First open — nothing pre-selected
+const assets = await PictureSelector.openPicker({ maxCount: 9 })
+setSelectedAssets(assets)
+
+// Re-open — restore previous selection
+const updated = await PictureSelector.openPicker({
   maxCount: 9,
-  selectedAssets: previousAssets.map((a) => a.uri),
+  selectedAssets: selectedAssets.map((a) => a.uri),
 })
+setSelectedAssets(updated)
 ```
 
 ---
@@ -325,64 +386,101 @@ Every item in the returned array has this shape:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `uri` | `string` | `file://` URI of the final file |
-| `type` | `"image" \| "video"` | Media type |
+| `uri` | `string` | `file://` path of the final file (compressed / cropped if applicable) |
+| `type` | `"image" \| "video"` | Media kind |
 | `mimeType` | `string` | e.g. `"image/jpeg"`, `"video/mp4"` |
 | `width` | `number` | Width in pixels |
 | `height` | `number` | Height in pixels |
-| `duration` | `number` | Duration in **milliseconds** (0 for images) |
-| `fileName` | `string` | File name with extension |
-| `fileSize` | `number` | Size in bytes |
-| `editedUri?` | `string` | URI after crop/edit (when editing was applied) |
-| `isOriginal?` | `boolean` | iOS: user tapped the Original button |
-| `bucketName?` | `string` | Android: album/folder name |
+| `duration` | `number` | Duration in **milliseconds** (`0` for images) |
+| `fileName` | `string` | File name with extension, e.g. `"photo.jpg"` |
+| `fileSize` | `number` | Size in **bytes** |
+| `editedUri?` | `string` | Path of the edited file after crop (if crop was applied) |
+| `isOriginal?` | `boolean` | iOS only: `true` if the user tapped "Original" in the picker |
+| `bucketName?` | `string` | Android only: album / folder name the file came from |
 
 ```ts
 const [asset] = await PictureSelector.openPicker()
 
-console.log(asset.uri)       // "file:///data/user/0/.../image.jpg"
-console.log(asset.type)      // "image"
-console.log(asset.mimeType)  // "image/jpeg"
-console.log(asset.width)     // 4032
-console.log(asset.height)    // 3024
-console.log(asset.fileSize)  // 2457600  (bytes)
-console.log(asset.duration)  // 0        (image)
-console.log(asset.editedUri) // "file:///..." or undefined
+asset.uri       // "file:///data/user/0/com.myapp/cache/image.jpg"
+asset.type      // "image"
+asset.mimeType  // "image/jpeg"
+asset.width     // 4032
+asset.height    // 3024
+asset.fileSize  // 2457600  (bytes ≈ 2.4 MB)
+asset.duration  // 0        (image has no duration)
+asset.fileName  // "IMG_20240101_120000.jpg"
+asset.editedUri // "file:///...cropped.jpg" or undefined
+```
+
+Video example:
+
+```ts
+const [video] = await PictureSelector.openPicker({ mediaType: MediaType.VIDEO })
+
+video.type      // "video"
+video.mimeType  // "video/mp4"
+video.duration  // 12500  (12.5 seconds in ms)
+video.fileSize  // 8388608  (≈ 8 MB)
 ```
 
 ---
 
 ## Error handling
 
+Wrap picker calls in try/catch and use `toPickerError` to normalise any error into a typed `PickerError`:
+
 ```ts
-import { toPickerError } from 'react-native-picture-selector'
+import { PictureSelector, toPickerError } from 'react-native-picture-selector'
 import type { PickerError } from 'react-native-picture-selector'
 
-try {
-  const assets = await PictureSelector.openPicker()
-} catch (err) {
-  const e = toPickerError(err)
-
-  switch (e.code) {
-    case 'CANCELLED':
-      // user dismissed — treat as no-op
-      break
-    case 'PERMISSION_DENIED':
-      // show settings prompt
-      break
-    case 'UNKNOWN':
-      // unexpected error
-      console.error(e.message)
-      break
+async function pickPhoto() {
+  try {
+    const assets = await PictureSelector.openPicker()
+    return assets
+  } catch (err) {
+    const e = toPickerError(err)
+
+    switch (e.code) {
+      case 'CANCELLED':
+        // User dismissed — not an error, just return empty
+        return []
+
+      case 'PERMISSION_DENIED':
+        // Show a settings prompt
+        Alert.alert(
+          'Permission required',
+          'Please allow photo access in Settings.',
+          [{ text: 'Open Settings', onPress: () => Linking.openSettings() }]
+        )
+        return []
+
+      case 'UNKNOWN':
+      default:
+        console.error('[Picker]', e.message)
+        return []
+    }
   }
 }
 ```
 
+### Error codes
+
 | Code | When |
 |------|------|
-| `CANCELLED` | User tapped Back / Cancel |
-| `PERMISSION_DENIED` | Runtime permission not granted |
-| `UNKNOWN` | Any other native error |
+| `CANCELLED` | User tapped Back or Cancel without selecting |
+| `PERMISSION_DENIED` | Runtime permission was not granted |
+| `UNKNOWN` | Any unexpected native error |
+
+### `toPickerError(err)`
+
+Normalises an unknown thrown value into a `PickerError` object:
+
+```ts
+interface PickerError {
+  code: 'CANCELLED' | 'PERMISSION_DENIED' | 'UNKNOWN'
+  message: string
+}
+```
 
 ---
 
@@ -391,32 +489,41 @@ try {
 ```ts
 import { MediaType, PickerTheme } from 'react-native-picture-selector'
 
-MediaType.IMAGE   // 'image'
-MediaType.VIDEO   // 'video'
-MediaType.ALL     // 'all'
+// MediaType
+MediaType.IMAGE   // photos only
+MediaType.VIDEO   // videos only
+MediaType.ALL     // photos + videos
 
-PickerTheme.DEFAULT  // 'default'
-PickerTheme.WECHAT   // 'wechat'   (Android)
-PickerTheme.WHITE    // 'white'    (Android)
-PickerTheme.DARK     // 'dark'     (Android)
+// PickerTheme (Android only)
+PickerTheme.DEFAULT  // system default
+PickerTheme.WECHAT   // WeChat green style
+PickerTheme.WHITE    // light / white style
+PickerTheme.DARK     // dark / night style
 ```
 
 ---
 
 ## Common recipes
 
-### Avatar picker (square crop)
+### Avatar picker — square crop + resize
 
 ```ts
-const [avatar] = await PictureSelector.openPicker({
-  mediaType: MediaType.IMAGE,
-  maxCount: 1,
-  crop: { enabled: true, ratioX: 1, ratioY: 1 },
-  compress: { enabled: true, quality: 0.85, maxWidth: 512, maxHeight: 512 },
-})
+async function pickAvatar(): Promise<string | null> {
+  try {
+    const [asset] = await PictureSelector.openPicker({
+      mediaType: MediaType.IMAGE,
+      maxCount: 1,
+      crop: { enabled: true, ratioX: 1, ratioY: 1 },
+      compress: { enabled: true, quality: 0.85, maxWidth: 512, maxHeight: 512 },
+    })
+    return asset.uri
+  } catch {
+    return null
+  }
+}
 ```
 
-### Multi-photo with compression
+### Multi-photo for a post
 
 ```ts
 const photos = await PictureSelector.openPicker({
@@ -424,9 +531,10 @@ const photos = await PictureSelector.openPicker({
   maxCount: 9,
   compress: { enabled: true, quality: 0.7, maxWidth: 1920, maxHeight: 1920 },
 })
+// photos[0].uri … photos[8].uri
 ```
 
-### Short video clips
+### Short video clip picker
 
 ```ts
 const [clip] = await PictureSelector.openPicker({
@@ -435,123 +543,130 @@ const [clip] = await PictureSelector.openPicker({
   minVideoDuration: 1,
   maxVideoDuration: 30,
 })
+
+console.log(`${clip.duration / 1000}s, ${clip.fileSize} bytes`)
+```
+
+### Banner / cover image — 16:9 crop
+
+```ts
+const [banner] = await PictureSelector.openPicker({
+  mediaType: MediaType.IMAGE,
+  maxCount: 1,
+  crop: { enabled: true, ratioX: 16, ratioY: 9 },
+  compress: { enabled: true, quality: 0.8, maxWidth: 1280, maxHeight: 720 },
+})
 ```
 
-### Upload immediately after capture
+### Camera capture → instant upload
 
 ```ts
 async function captureAndUpload() {
   const [photo] = await PictureSelector.openCamera({
     mediaType: MediaType.IMAGE,
-    compress: { enabled: true, quality: 0.8 },
+    compress: { enabled: true, quality: 0.8, maxWidth: 1920, maxHeight: 1920 },
   })
 
-  const body = new FormData()
-  body.append('file', {
-    uri: photo.uri,
+  const form = new FormData()
+  form.append('file', {
+    uri:  photo.uri,
     type: photo.mimeType,
     name: photo.fileName,
   } as any)
 
-  await fetch('https://api.example.com/upload', { method: 'POST', body })
+  const res = await fetch('https://your-api.com/upload', {
+    method: 'POST',
+    body: form,
+  })
+
+  return res.json()
 }
 ```
 
-### Chat-style picker with hook
+### Chat input — hook version
 
 ```tsx
-function ChatInput() {
+import React from 'react'
+import { View, Pressable, Text, Image, ScrollView } from 'react-native'
+import { usePictureSelector, MediaType } from 'react-native-picture-selector'
+
+function ChatInput({ onSend }: { onSend: (uris: string[]) => void }) {
   const { assets, loading, pick, clear } = usePictureSelector({
     mediaType: MediaType.ALL,
     maxCount: 9,
+    compress: { enabled: true, quality: 0.7 },
   })
 
-  const send = async () => {
-    if (assets.length === 0) return
-    await uploadAll(assets)
+  const handleSend = () => {
+    onSend(assets.map((a) => a.uri))
     clear()
   }
 
   return (
     <View>
       <Pressable onPress={() => pick()} disabled={loading}>
-        <Text>📎 Attach</Text>
+        <Text>{loading ? 'Opening…' : '📎 Attach'}</Text>
       </Pressable>
 
       {assets.length > 0 && (
-        <Pressable onPress={send}>
-          <Text>Send ({assets.length})</Text>
-        </Pressable>
+        <>
+          <ScrollView horizontal>
+            {assets.map((a, i) => (
+              <Image
+                key={i}
+                source={{ uri: a.uri }}
+                style={{ width: 64, height: 64, marginRight: 4, borderRadius: 8 }}
+              />
+            ))}
+          </ScrollView>
+
+          <Pressable onPress={handleSend}>
+            <Text>Send {assets.length} file{assets.length > 1 ? 's' : ''}</Text>
+          </Pressable>
+
+          <Pressable onPress={clear}>
+            <Text>✕ Cancel</Text>
+          </Pressable>
+        </>
       )}
     </View>
   )
 }
-```
-
----
-
-## Architecture
 
+export default ChatInput
 ```
-JavaScript / TypeScript
-  PictureSelector.openPicker()
-  usePictureSelector()
-        │
-        │  JSI (zero serialization overhead)
-        │  react-native-nitro-modules
-        ▼
-  HybridPictureSelector
-  ┌──────────────────────┬───────────────────────┐
-  │ Android (Kotlin)     │ iOS (Swift 5.9)       │
-  │                      │                       │
-  │ PictureSelector v3   │ HXPhotoPicker v5      │
-  │  ├─ GlideEngine      │  ├─ PickerConfiguration│
-  │  ├─ UCropEngine      │  ├─ PhotoPickerController│
-  │  └─ LubanCompress    │  └─ async result map  │
-  └──────────────────────┴───────────────────────┘
-```
-
-Communication goes through a **statically compiled JSI binding** generated by `nitrogen`. There is no JSON serialization and no async bridge queue — results are returned via native Promises resolved directly on the JS thread.
-
----
-
-## Development workflow
-
-### Generate native bridge code
 
-After modifying `src/specs/PictureSelector.nitro.ts` run:
+### Profile settings — restore previous selection
 
-```sh
-npx nitrogen generate
-# or
-bun run generate
-```
-
-This populates `nitrogen/generated/` with:
-- `android/kotlin/com/nitro/pictureselector/` — Kotlin abstract spec classes
-- `ios/` — Swift protocol files and Objective-C++ bridge
-
-**Do not edit files inside `nitrogen/generated/` manually** — they are overwritten on each codegen run.
-
-### Build TypeScript
-
-```sh
-bun run build
-# or
-npx bob build
-```
-
-### Run example
+```tsx
+function ProfilePhotoScreen() {
+  const [photo, setPhoto] = useState<MediaAsset | null>(null)
+
+  const changePhoto = async () => {
+    try {
+      const [asset] = await PictureSelector.openPicker({
+        mediaType: MediaType.IMAGE,
+        maxCount: 1,
+        crop: { enabled: true, ratioX: 1, ratioY: 1 },
+        compress: { enabled: true, quality: 0.9, maxWidth: 512, maxHeight: 512 },
+        // restore the current photo if user re-opens
+        selectedAssets: photo ? [photo.uri] : [],
+      })
+      setPhoto(asset)
+    } catch {
+      // cancelled — do nothing
+    }
+  }
 
-```sh
-cd example
-npm install
-# iOS
-npx pod-install
-npx react-native run-ios
-
-# Android
-npx react-native run-android
+  return (
+    <Pressable onPress={changePhoto}>
+      {photo
+        ? <Image source={{ uri: photo.uri }} style={{ width: 100, height: 100, borderRadius: 50 }} />
+        : <Text>Tap to set photo</Text>
+      }
+    </Pressable>
+  )
+}
 ```
 
 ---
@@ -561,46 +676,46 @@ npx react-native run-android
 ### Android
 
 - Minimum SDK: **24** (Android 7.0)
-- PictureSelector v3 handles runtime permissions internally. On Android 13+ it requests `READ_MEDIA_IMAGES` / `READ_MEDIA_VIDEO`. On older versions it requests `READ_EXTERNAL_STORAGE`.
-- The `theme` option uses PictureSelector's built-in style presets. `PickerTheme.WECHAT` is the most polished.
+- PictureSelector v3 handles runtime permissions internally. On Android 13+ it requests `READ_MEDIA_IMAGES` / `READ_MEDIA_VIDEO`; on older versions it requests `READ_EXTERNAL_STORAGE`.
+- The `theme` option maps to PictureSelector's built-in style presets. `PickerTheme.WECHAT` is the most polished preset.
 - Video files captured by camera are placed in the app cache directory.
 - Glide is used for thumbnail rendering inside the gallery grid.
-- uCrop handles all cropping; circular crop uses uCrop's `setCircleDimmedLayer(true)`.
-- Luban handles compression; files under 100 KB are passed through unchanged.
+- uCrop handles all cropping; circular crop falls back to a 1:1 fixed-ratio crop.
+- Luban handles JPEG compression; files under 100 KB bypass compression unchanged.
 
 ### iOS
 
 - Minimum deployment target: **iOS 13.0**
 - Swift 5.9 is required for the C++ interop used by Nitro Modules.
-- HXPhotoPicker requests permissions automatically the first time the picker is opened. The `Info.plist` keys must be present or the app will crash.
-- The `circular` crop option is iOS-only; on Android it falls back to a 1:1 fixed ratio.
-- `isOriginal` in `MediaAsset` is only populated on iOS (when the user taps the "Original" button).
+- HXPhotoPicker requests permissions automatically the first time the picker is opened. The `Info.plist` keys **must** be present or the app will crash on first use.
+- The `circular` crop option is iOS-only; it renders a circular preview mask but saves a square file.
+- `isOriginal` in `MediaAsset` is only populated on iOS (when the user taps the "Original" toggle).
 - `bucketName` is only populated on Android.
-- `themeColor` sets HXPhotoPicker's global `themeColor` property.
-- The `theme` enum values `WECHAT`, `WHITE`, `DARK` have no effect on iOS (only `themeColor` is used).
+- `themeColor` sets HXPhotoPicker's global `themeColor` property (navigation bar, selection indicators).
+- `theme` enum values (`WECHAT`, `WHITE`, `DARK`) are ignored on iOS — use `themeColor` instead.
 
 ---
 
 ## Permissions summary
 
-### Android
+### Android — declared automatically
 
-| Permission | When requested |
-|-----------|----------------|
-| `CAMERA` | Camera capture |
-| `READ_EXTERNAL_STORAGE` | Android ≤ 12 |
-| `READ_MEDIA_IMAGES` | Android 13+ |
-| `READ_MEDIA_VIDEO` | Android 13+ |
-| `WRITE_EXTERNAL_STORAGE` | Android ≤ 9 only |
+| Permission | API level |
+|-----------|-----------|
+| `CAMERA` | All |
+| `READ_EXTERNAL_STORAGE` | ≤ API 32 (Android 12) |
+| `READ_MEDIA_IMAGES` | ≥ API 33 (Android 13) |
+| `READ_MEDIA_VIDEO` | ≥ API 33 (Android 13) |
+| `WRITE_EXTERNAL_STORAGE` | ≤ API 28 (Android 9) |
 
-### iOS (`Info.plist`)
+### iOS — `Info.plist` keys required
 
 | Key | Purpose |
 |-----|---------|
-| `NSPhotoLibraryUsageDescription` | Read photos/videos |
-| `NSPhotoLibraryAddUsageDescription` | Save to library |
-| `NSCameraUsageDescription` | Camera capture |
-| `NSMicrophoneUsageDescription` | Video with audio |
+| `NSPhotoLibraryUsageDescription` | Read photos and videos from the library |
+| `NSPhotoLibraryAddUsageDescription` | Save captured media to the library |
+| `NSCameraUsageDescription` | Access the camera for capture |
+| `NSMicrophoneUsageDescription` | Record audio with video |
 
 ---
 
@@ -610,18 +725,45 @@ npx react-native run-android
 |---------|--------|
 | Audio file selection | Not supported |
 | iCloud Photos (iOS) | Partial — depends on HXPhotoPicker internals |
-| LivePhoto | Not exposed |
+| Live Photos | Not exposed |
+| Animated GIF selection | Not exposed |
 | Background upload / processing | Out of scope |
 | Save to gallery | Out of scope |
-| Document picker | Out of scope |
+| Document picker (PDF, etc.) | Out of scope |
+
+---
+
+## Architecture
+
+```
+JavaScript / TypeScript
+  PictureSelector.openPicker()
+  PictureSelector.openCamera()
+  usePictureSelector()
+        │
+        │  JSI — zero serialization, zero bridge queue
+        │  react-native-nitro-modules
+        ▼
+  HybridPictureSelector
+  ┌──────────────────────┬────────────────────────┐
+  │ Android (Kotlin)     │ iOS (Swift 5.9)        │
+  │                      │                        │
+  │ PictureSelector v3   │ HXPhotoPicker v5       │
+  │  ├─ GlideEngine      │  ├─ PickerConfiguration│
+  │  ├─ UCropEngine      │  ├─ PhotoPickerController│
+  │  └─ LubanCompress    │  └─ async result map   │
+  └──────────────────────┴────────────────────────┘
+```
+
+Results travel from native to JavaScript through a **statically compiled JSI binding** — no JSON serialisation, no async bridge queue, no reflection. Native promises resolve directly on the JS thread.
 
 ---
 
 ## License
 
-MIT © react-native-picture-selector contributors
+MIT
 
-Native libraries:
-- [LuckSiege/PictureSelector](https://github.com/LuckSiege/PictureSelector) — Apache 2.0
-- [SilenceLove/HXPhotoPicker](https://github.com/SilenceLove/HXPhotoPicker) — MIT
-- [mrousavy/nitro](https://github.com/mrousavy/nitro) — MIT
+Native dependencies:
+- LuckSiege/PictureSelector — Apache 2.0
+- SilenceLove/HXPhotoPicker — MIT
+- mrousavy/nitro — MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-picture-selector",
-  "version": "1.0.1",
+  "version": "1.0.6",
   "description": "High-performance photo/video picker for React Native using Nitro Modules",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -33,10 +33,6 @@
     "camera",
     "gallery"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/yourorg/react-native-picture-selector.git"
-  },
   "license": "MIT",
   "peerDependencies": {
     "react": "*",