@sagepilot-ai/react-native-camera-addon 0.3.0

package/android/src/main/java/ai/sagepilot/reactnativecameraaddon/SagepilotInAppCameraModule.java

@@ -0,0 +1,1012 @@
+package ai.sagepilot.reactnativecameraaddon;
+
+import android.Manifest;
+import android.app.Activity;
+import android.content.ActivityNotFoundException;
+import android.content.ClipData;
+import android.content.ContentResolver;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.database.Cursor;
+import android.net.Uri;
+import android.provider.OpenableColumns;
+import android.util.Base64;
+import android.util.Log;
+import androidx.activity.result.PickVisualMediaRequest;
+import androidx.activity.result.contract.ActivityResultContracts;
+import androidx.core.content.ContextCompat;
+import androidx.lifecycle.LifecycleOwner;
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.BaseActivityEventListener;
+import com.facebook.react.bridge.LifecycleEventListener;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.ReadableMap;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+public class SagepilotInAppCameraModule extends ReactContextBaseJavaModule implements LifecycleEventListener {
+  public static final String NAME = "SagepilotInAppCamera";
+  public static final String CAMERA_ACTIVITY_CLASS_NAME = "ai.sagepilot.reactnativecameraaddon.SagepilotInAppCameraActivity";
+  private static final String TAG = "SagepilotInAppCamera";
+
+  public static final int REQUEST_CODE_OPEN_CAMERA = 0x5347;
+  public static final int REQUEST_CODE_OPEN_IMAGE_LIBRARY = 0x5348;
+  public static final int REQUEST_CODE_OPEN_DOCUMENTS = 0x5349;
+  public static final int RESULT_ERROR = Activity.RESULT_FIRST_USER + 0x5347;
+  public static final int MODULE_CAPABILITIES_VERSION = 2;
+
+  public static final String EXTRA_IMAGE_MAX_DIMENSION =
+    "ai.sagepilot.reactnativecameraaddon.camera.IMAGE_MAX_DIMENSION";
+  public static final String EXTRA_IMAGE_QUALITY =
+    "ai.sagepilot.reactnativecameraaddon.camera.IMAGE_QUALITY";
+  public static final String EXTRA_IMAGE_MAX_FILE_SIZE_BYTES =
+    "ai.sagepilot.reactnativecameraaddon.camera.IMAGE_MAX_FILE_SIZE_BYTES";
+
+  public static final String EXTRA_RESULT_FILE_NAME =
+    "ai.sagepilot.reactnativecameraaddon.camera.RESULT_FILE_NAME";
+  public static final String EXTRA_RESULT_MIME_TYPE =
+    "ai.sagepilot.reactnativecameraaddon.camera.RESULT_MIME_TYPE";
+  public static final String EXTRA_RESULT_SIZE =
+    "ai.sagepilot.reactnativecameraaddon.camera.RESULT_SIZE";
+  public static final String EXTRA_RESULT_DATA_BASE64 =
+    "ai.sagepilot.reactnativecameraaddon.camera.RESULT_DATA_BASE64";
+  public static final String EXTRA_RESULT_ID =
+    "ai.sagepilot.reactnativecameraaddon.camera.RESULT_ID";
+
+  public static final String EXTRA_ERROR_CODE =
+    "ai.sagepilot.reactnativecameraaddon.camera.ERROR_CODE";
+  public static final String EXTRA_ERROR_MESSAGE =
+    "ai.sagepilot.reactnativecameraaddon.camera.ERROR_MESSAGE";
+
+  public static final String ERROR_PERMISSION_DENIED = "permission_denied";
+  public static final String ERROR_CAMERA_UNAVAILABLE = "camera_unavailable";
+  public static final String ERROR_ENCODE_FAILED = "encode_failed";
+  public static final String ERROR_FILE_TOO_LARGE = "file_too_large";
+  public static final String ERROR_READ_FAILED = "read_failed";
+
+  private static final int BASE64_BUFFER_SIZE = 8192;
+  private static final int DEFAULT_IMAGE_MAX_DIMENSION = 1920;
+  private static final double DEFAULT_IMAGE_QUALITY = 0.8;
+  private static final long DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES = 15L * 1024L * 1024L;
+  private static final long DEFAULT_DOCUMENT_MAX_FILE_SIZE_BYTES = 20L * 1024L * 1024L;
+  private static final String DEFAULT_IMAGE_MIME_TYPE = "image/jpeg";
+  private static final String DEFAULT_DOCUMENT_MIME_TYPE = "application/octet-stream";
+  private static final int PHOTO_PICKER_MAX_ITEMS = 20;
+  private static final String[] DOCUMENT_MIME_TYPES = new String[] { "*/*" };
+
+  private final ReactApplicationContext reactContext;
+  private final Object pendingLock = new Object();
+  private final BaseActivityEventListener activityEventListener = new BaseActivityEventListener() {
+    /** Handles the SDK camera Activity result for the pending JS promise. */
+    @Override
+    public void onActivityResult(Activity activity, int requestCode, int resultCode, Intent data) {
+      handleActivityResult(requestCode, resultCode, data);
+    }
+  };
+
+  private Promise pendingPromise;
+  private long pendingMaxFileSizeBytes;
+  private boolean pendingCameraCapture;
+  private final List<Promise> pendingCameraPromises = new ArrayList<>();
+  private boolean invalidated;
+  private SagepilotInAppCameraOverlay activeCameraOverlay;
+
+  /** Creates the in-app camera native module and attaches lifecycle listeners. */
+  public SagepilotInAppCameraModule(ReactApplicationContext reactContext) {
+    super(reactContext);
+    this.reactContext = reactContext;
+    reactContext.addActivityEventListener(activityEventListener);
+    reactContext.addLifecycleEventListener(this);
+    SagepilotInAppCameraDebugEvents.register(reactContext);
+  }
+
+  /** Returns the NativeModules registration name consumed by the JS wrapper. */
+  @Override
+  public String getName() {
+    return NAME;
+  }
+
+  /** Reports native picker capabilities so JavaScript can detect stale APKs. */
+  @Override
+  public Map<String, Object> getConstants() {
+    Map<String, Object> constants = new HashMap<>();
+    constants.put("moduleCapabilitiesVersion", MODULE_CAPABILITIES_VERSION);
+    constants.put("supportsInAppCamera", true);
+    constants.put("supportsImageLibrary", true);
+    constants.put("supportsDocumentPicker", true);
+    return constants;
+  }
+
+  /** Opens the SDK-owned camera Activity and resolves one picked file or null. */
+  @ReactMethod
+  public void openCamera(ReadableMap options, Promise promise) {
+    logDebug("openCamera requested");
+    if (invalidated) {
+      logWarn("openCamera rejected: module invalidated");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "The camera module is no longer available.");
+      return;
+    }
+
+    if (hasPendingPromise()) {
+      if (addPendingCameraPromise(promise)) {
+        logWarn("openCamera coalesced into pending capture");
+        return;
+      }
+      logWarn("openCamera rejected: pending capture exists");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "Another camera capture is already in progress.");
+      return;
+    }
+
+    Activity activity = reactContext.getCurrentActivity();
+    if (activity == null) {
+      logWarn("openCamera rejected: no current Activity");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "No active host activity is available to open the camera.");
+      return;
+    }
+
+    if (!hasCameraPermission()) {
+      logWarn("openCamera continuing without permission; camera surface will request CAMERA");
+    }
+
+    if (!hasCameraHardware()) {
+      logWarn("openCamera rejected: no camera hardware");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "This device does not have an available camera.");
+      return;
+    }
+
+    if (canUseCameraOverlay(activity)) {
+      openCameraOverlay(activity, options, promise);
+      return;
+    }
+
+    if (!hasCameraActivityClass()) {
+      logWarn("openCamera rejected: Activity class missing");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "The in-app camera screen is not available in this build.");
+      return;
+    }
+
+    startCameraActivity(activity, options, promise);
+  }
+
+  /** Starts the legacy Activity camera path used for permission fallback or unsupported host lifecycles. */
+  private void startCameraActivity(Activity activity, ReadableMap options, Promise promise) {
+    Intent intent = createCameraIntent(options);
+    setPendingCameraPromise(promise);
+
+    activity.runOnUiThread(() -> {
+      if (invalidated || !hasPendingPromise()) {
+        return;
+      }
+      try {
+        logDebug("starting CameraX Activity");
+        activity.startActivityForResult(intent, REQUEST_CODE_OPEN_CAMERA);
+      } catch (ActivityNotFoundException error) {
+        logError("CameraX Activity not registered", error);
+        rejectPendingPromise(ERROR_CAMERA_UNAVAILABLE, "The in-app camera screen is not registered.", error);
+      } catch (RuntimeException error) {
+        logError("Could not start CameraX Activity", error);
+        rejectPendingPromise(ERROR_CAMERA_UNAVAILABLE, "Could not open the in-app camera.", error);
+      }
+    });
+  }
+
+  /** Checks whether the host Activity can keep the camera in-process above the WebView. */
+  private boolean canUseCameraOverlay(Activity activity) {
+    return hasCameraPermission() && activity instanceof LifecycleOwner;
+  }
+
+  /** Opens CameraX as an in-process host-Activity overlay. */
+  private void openCameraOverlay(Activity activity, ReadableMap options, Promise promise) {
+    int imageMaxDimension = readIntOption(options, "imageMaxDimension", DEFAULT_IMAGE_MAX_DIMENSION);
+    int imageQuality = qualityRatioToPercent(readDoubleOption(options, "imageQuality", DEFAULT_IMAGE_QUALITY));
+    long imageMaxFileSizeBytes = readLongOption(
+      options,
+      "imageMaxFileSizeBytes",
+      DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES
+    );
+    setPendingCameraPromise(promise);
+
+    activity.runOnUiThread(() -> {
+      if (invalidated || !hasPendingPromise()) {
+        return;
+      }
+
+      try {
+        activeCameraOverlay = new SagepilotInAppCameraOverlay(
+          activity,
+          imageMaxDimension,
+          imageQuality,
+          imageMaxFileSizeBytes,
+          new SagepilotInAppCameraOverlay.Listener() {
+            /** Resolves the JS promise with a processed overlay capture. */
+            @Override
+            public void onSuccess(String fileName, String mimeType, long sizeBytes, String dataBase64) {
+              handleOverlaySuccess(fileName, mimeType, sizeBytes, dataBase64);
+            }
+
+            /** Resolves the JS promise with cancellation from the overlay. */
+            @Override
+            public void onCancel() {
+              handleOverlayCancel();
+            }
+
+            /** Rejects the JS promise with a stable overlay error. */
+            @Override
+            public void onError(String code, String message, Throwable error) {
+              handleOverlayError(code, message, error);
+            }
+          }
+        );
+        logDebug("showing in-process CameraX overlay");
+        activeCameraOverlay.show();
+      } catch (RuntimeException error) {
+        logError("Could not show in-process CameraX overlay", error);
+        destroyActiveCameraOverlay();
+        rejectPendingPromise(ERROR_CAMERA_UNAVAILABLE, "Could not open the in-app camera.", error);
+      }
+    });
+  }
+
+  /** Resolves the pending promise with an in-process overlay capture. */
+  private void handleOverlaySuccess(String fileName, String mimeType, long sizeBytes, String dataBase64) {
+    activeCameraOverlay = null;
+    List<Promise> promises = takePendingCameraPromises();
+    if (promises.isEmpty()) {
+      logWarn("overlay success ignored: no pending promise");
+      return;
+    }
+    for (Promise promise : promises) {
+      resolvePickedFile(promise, fileName, mimeType, sizeBytes, dataBase64);
+    }
+  }
+
+  /** Resolves the pending promise as a customer cancellation from the overlay. */
+  private void handleOverlayCancel() {
+    activeCameraOverlay = null;
+    List<Promise> promises = takePendingCameraPromises();
+    if (promises.isEmpty()) {
+      logWarn("overlay cancel ignored: no pending promise");
+      return;
+    }
+    for (Promise promise : promises) {
+      promise.resolve(null);
+    }
+  }
+
+  /** Rejects the pending promise with an overlay failure. */
+  private void handleOverlayError(String code, String message, Throwable error) {
+    activeCameraOverlay = null;
+    List<Promise> promises = takePendingCameraPromises();
+    if (promises.isEmpty()) {
+      logWarn("overlay error ignored: no pending promise");
+      return;
+    }
+    for (Promise promise : promises) {
+      rejectPromise(promise, code, message, error);
+    }
+  }
+
+  /** Destroys the active in-process overlay without settling the promise. */
+  private void destroyActiveCameraOverlay() {
+    SagepilotInAppCameraOverlay overlay = activeCameraOverlay;
+    activeCameraOverlay = null;
+    if (overlay != null && overlay.isActive()) {
+      overlay.destroySilentlyOnUiThread();
+    }
+  }
+
+  /** Opens the Android system image picker and resolves selected image files. */
+  @ReactMethod
+  public void openImageLibrary(ReadableMap options, Promise promise) {
+    openExternalPicker(
+      options,
+      promise,
+      REQUEST_CODE_OPEN_IMAGE_LIBRARY,
+      "image/*",
+      "image library",
+      "imageMaxFileSizeBytes",
+      DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES
+    );
+  }
+
+  /** Opens the Android system document picker and resolves selected document files. */
+  @ReactMethod
+  public void openDocumentPicker(ReadableMap options, Promise promise) {
+    openExternalPicker(
+      options,
+      promise,
+      REQUEST_CODE_OPEN_DOCUMENTS,
+      "*/*",
+      "document picker",
+      "documentMaxFileSizeBytes",
+      DEFAULT_DOCUMENT_MAX_FILE_SIZE_BYTES
+    );
+  }
+
+  /** Accepts JavaScript debug-event subscriptions required by NativeEventEmitter. */
+  @ReactMethod
+  public void addListener(String eventName) {
+    // Events are emitted through RCTDeviceEventEmitter; no per-event native setup is needed.
+  }
+
+  /** Accepts JavaScript debug-event unsubscriptions required by NativeEventEmitter. */
+  @ReactMethod
+  public void removeListeners(double count) {
+    // Events are emitted through RCTDeviceEventEmitter; no per-event native teardown is needed.
+  }
+
+  /** Keeps the pending capture alive while the SDK camera Activity is foregrounded. */
+  @Override
+  public void onHostPause() {
+    // Opening the SDK camera Activity pauses the React host Activity; this is not a cancellation.
+  }
+
+  /** Leaves pending capture ownership unchanged when the React host resumes. */
+  @Override
+  public void onHostResume() {
+    // Activity result delivery is the source of truth for capture completion.
+  }
+
+  /** Rejects a pending capture if the React host Activity is destroyed mid-capture. */
+  @Override
+  public void onHostDestroy() {
+    destroyActiveCameraOverlay();
+    rejectPendingPromise(
+      ERROR_CAMERA_UNAVAILABLE,
+      "Camera capture was cancelled because the host activity was destroyed.",
+      null
+    );
+  }
+
+  /** Removes listeners and rejects any pending capture when React invalidates the module. */
+  @Override
+  public void invalidate() {
+    invalidated = true;
+    destroyActiveCameraOverlay();
+    reactContext.removeActivityEventListener(activityEventListener);
+    reactContext.removeLifecycleEventListener(this);
+    SagepilotInAppCameraDebugEvents.unregister(reactContext);
+    rejectPendingPromise(
+      ERROR_CAMERA_UNAVAILABLE,
+      "Camera capture was cancelled because the React Native instance was invalidated.",
+      null
+    );
+    super.invalidate();
+  }
+
+  /** Builds the explicit Activity intent with normalized camera processing options. */
+  private Intent createCameraIntent(ReadableMap options) {
+    Intent intent = new Intent();
+    intent.setClassName(reactContext.getPackageName(), CAMERA_ACTIVITY_CLASS_NAME);
+    intent.putExtra(
+      EXTRA_IMAGE_MAX_DIMENSION,
+      readIntOption(options, "imageMaxDimension", DEFAULT_IMAGE_MAX_DIMENSION)
+    );
+    intent.putExtra(
+      EXTRA_IMAGE_QUALITY,
+      readDoubleOption(options, "imageQuality", DEFAULT_IMAGE_QUALITY)
+    );
+    intent.putExtra(
+      EXTRA_IMAGE_MAX_FILE_SIZE_BYTES,
+      readLongOption(options, "imageMaxFileSizeBytes", DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES)
+    );
+    return intent;
+  }
+
+  /** Resolves or rejects the pending JS promise from the camera Activity result. */
+  private void handleActivityResult(int requestCode, int resultCode, Intent data) {
+    if (
+      requestCode != REQUEST_CODE_OPEN_CAMERA &&
+      requestCode != REQUEST_CODE_OPEN_IMAGE_LIBRARY &&
+      requestCode != REQUEST_CODE_OPEN_DOCUMENTS
+    ) {
+      return;
+    }
+
+    if (requestCode == REQUEST_CODE_OPEN_IMAGE_LIBRARY || requestCode == REQUEST_CODE_OPEN_DOCUMENTS) {
+      handleExternalPickerResult(requestCode, resultCode, data);
+      return;
+    }
+
+    logDebug("camera Activity result received: resultCode=" + resultCode);
+    List<Promise> promises = takePendingCameraPromises();
+    if (promises.isEmpty()) {
+      logWarn("camera Activity result ignored: no pending promise");
+      return;
+    }
+
+    if (resultCode == Activity.RESULT_OK) {
+      resolvePickedFiles(promises, data);
+      return;
+    }
+
+    if (resultCode == Activity.RESULT_CANCELED) {
+      logDebug("camera Activity cancelled");
+      for (Promise promise : promises) {
+        promise.resolve(null);
+      }
+      return;
+    }
+
+    if (resultCode == RESULT_ERROR) {
+      String code = readStringExtra(data, EXTRA_ERROR_CODE, ERROR_CAMERA_UNAVAILABLE);
+      String message = readStringExtra(data, EXTRA_ERROR_MESSAGE, "Could not open the in-app camera.");
+      for (Promise promise : promises) {
+        rejectPromise(promise, code, message);
+      }
+      return;
+    }
+
+    for (Promise promise : promises) {
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "The in-app camera closed unexpectedly.");
+    }
+  }
+
+  /** Opens an Android system content picker and tracks the pending JS promise. */
+  private void openExternalPicker(
+    ReadableMap options,
+    Promise promise,
+    int requestCode,
+    String mimeType,
+    String pickerName,
+    String maxFileSizeOption,
+    long defaultMaxFileSizeBytes
+  ) {
+    logDebug("open " + pickerName + " requested");
+    if (invalidated) {
+      logWarn("open " + pickerName + " rejected: module invalidated");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "The file picker module is no longer available.");
+      return;
+    }
+
+    if (hasPendingPromise()) {
+      logWarn("open " + pickerName + " rejected: pending picker exists");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "Another file picker is already in progress.");
+      return;
+    }
+
+    Activity activity = reactContext.getCurrentActivity();
+    if (activity == null) {
+      logWarn("open " + pickerName + " rejected: no current Activity");
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "No active host activity is available to open the file picker.");
+      return;
+    }
+
+    boolean multiple = readBooleanOption(options, "multiple", true);
+    long maxFileSizeBytes = readLongOption(options, maxFileSizeOption, defaultMaxFileSizeBytes);
+    Intent intent = createExternalPickerIntent(requestCode, mimeType, multiple);
+    setPendingPromise(promise, maxFileSizeBytes);
+
+    try {
+      logDebug("starting " + pickerName + ": multiple=" + multiple + ", maxFileSizeBytes=" + maxFileSizeBytes);
+      activity.startActivityForResult(intent, requestCode);
+    } catch (ActivityNotFoundException error) {
+      logError("No Activity found for " + pickerName, error);
+      rejectPendingPromise(ERROR_CAMERA_UNAVAILABLE, "No file picker is available on this device.", error);
+    } catch (RuntimeException error) {
+      logError("Could not start " + pickerName, error);
+      rejectPendingPromise(ERROR_CAMERA_UNAVAILABLE, "Could not open the file picker.", error);
+    }
+  }
+
+  /** Creates the correct Android picker intent for image library or documents. */
+  private Intent createExternalPickerIntent(int requestCode, String mimeType, boolean multiple) {
+    if (requestCode == REQUEST_CODE_OPEN_IMAGE_LIBRARY) {
+      return createImageLibraryPickerIntent(multiple);
+    }
+    return createGetContentPickerIntent(mimeType, multiple, DOCUMENT_MIME_TYPES, "Choose file");
+  }
+
+  /** Creates an Android Photo Picker intent for media, falling back to GET_CONTENT on older devices. */
+  private Intent createImageLibraryPickerIntent(boolean multiple) {
+    if (ActivityResultContracts.PickVisualMedia.isPhotoPickerAvailable(reactContext)) {
+      PickVisualMediaRequest request = new PickVisualMediaRequest.Builder()
+        .setMediaType(ActivityResultContracts.PickVisualMedia.ImageOnly.INSTANCE)
+        .setMaxItems(multiple ? PHOTO_PICKER_MAX_ITEMS : 1)
+        .build();
+      if (multiple) {
+        return new ActivityResultContracts.PickMultipleVisualMedia(PHOTO_PICKER_MAX_ITEMS)
+          .createIntent(reactContext, request);
+      }
+      return new ActivityResultContracts.PickVisualMedia().createIntent(reactContext, request);
+    }
+
+    return createGetContentPickerIntent("image/*", multiple, null, "Choose image");
+  }
+
+  /** Creates a broad ACTION_GET_CONTENT chooser for providers such as Files and Drive. */
+  private Intent createGetContentPickerIntent(
+    String mimeType,
+    boolean multiple,
+    String[] mimeTypes,
+    String title
+  ) {
+    Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
+    intent.addCategory(Intent.CATEGORY_OPENABLE);
+    intent.setType(mimeType);
+    intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, multiple);
+    if (mimeTypes != null && mimeTypes.length > 0) {
+      intent.putExtra(Intent.EXTRA_MIME_TYPES, mimeTypes);
+    }
+    return Intent.createChooser(intent, title);
+  }
+
+  /** Resolves Android system picker results for gallery and document sources. */
+  private void handleExternalPickerResult(int requestCode, int resultCode, Intent data) {
+    String pickerName = requestCode == REQUEST_CODE_OPEN_IMAGE_LIBRARY ? "image library" : "document picker";
+    logDebug(pickerName + " Activity result received: resultCode=" + resultCode);
+    PendingPicker pendingPicker = takePendingPicker();
+    Promise promise = pendingPicker.promise;
+    if (promise == null) {
+      logWarn(pickerName + " Activity result ignored: no pending promise");
+      return;
+    }
+
+    if (resultCode == Activity.RESULT_CANCELED) {
+      logDebug(pickerName + " cancelled");
+      promise.resolve(Arguments.createArray());
+      return;
+    }
+
+    if (resultCode != Activity.RESULT_OK) {
+      rejectPromise(promise, ERROR_CAMERA_UNAVAILABLE, "The file picker closed unexpectedly.");
+      return;
+    }
+
+    try {
+      WritableArray files = createPickedFilesArray(
+        collectResultUris(data),
+        requestCode == REQUEST_CODE_OPEN_IMAGE_LIBRARY ? DEFAULT_IMAGE_MIME_TYPE : DEFAULT_DOCUMENT_MIME_TYPE,
+        pendingPicker.maxFileSizeBytes
+      );
+      logDebug(pickerName + " resolved files");
+      promise.resolve(files);
+    } catch (PickerFileTooLargeException error) {
+      logWarn(pickerName + " file too large", error);
+      rejectPromise(promise, ERROR_FILE_TOO_LARGE, error.getMessage(), error);
+    } catch (IOException | RuntimeException error) {
+      logError(pickerName + " read failed", error);
+      rejectPromise(promise, ERROR_READ_FAILED, "Could not read the selected file.", error);
+    }
+  }
+
+  /** Collects all content URIs returned by Android's picker result. */
+  private List<Uri> collectResultUris(Intent data) {
+    List<Uri> uris = new ArrayList<>();
+    if (data == null) {
+      return uris;
+    }
+
+    ClipData clipData = data.getClipData();
+    if (clipData != null) {
+      for (int index = 0; index < clipData.getItemCount(); index += 1) {
+        Uri uri = clipData.getItemAt(index).getUri();
+        if (uri != null) {
+          uris.add(uri);
+        }
+      }
+    }
+
+    Uri uri = data.getData();
+    if (uri != null && !uris.contains(uri)) {
+      uris.add(uri);
+    }
+    return uris;
+  }
+
+  /** Converts selected content URIs into bridge-ready picked-file payloads. */
+  private WritableArray createPickedFilesArray(
+    List<Uri> uris,
+    String fallbackMimeType,
+    long maxFileSizeBytes
+  ) throws IOException, PickerFileTooLargeException {
+    WritableArray files = Arguments.createArray();
+    for (int index = 0; index < uris.size(); index += 1) {
+      Uri uri = uris.get(index);
+      PickedContentMetadata metadata = readPickedContentMetadata(uri, fallbackMimeType, index);
+      if (maxFileSizeBytes > 0L && metadata.sizeBytes > maxFileSizeBytes) {
+        throw new PickerFileTooLargeException(metadata.fileName, metadata.sizeBytes, maxFileSizeBytes);
+      }
+      String dataBase64 = readUriAsBase64(uri, maxFileSizeBytes, metadata.fileName);
+      long sizeBytes = metadata.sizeBytes >= 0L ? metadata.sizeBytes : estimateBase64ByteSize(dataBase64);
+
+      WritableMap file = Arguments.createMap();
+      file.putString("file_name", metadata.fileName);
+      file.putString("mime_type", metadata.mimeType);
+      file.putDouble("size", Math.max(0L, sizeBytes));
+      file.putString("data_base64", dataBase64);
+      files.pushMap(file);
+      logDebug(
+        "picked content fileName=" + metadata.fileName +
+          ", mimeType=" + metadata.mimeType +
+          ", size=" + sizeBytes +
+          ", base64Length=" + dataBase64.length()
+      );
+    }
+    return files;
+  }
+
+  /** Reads display name, MIME type, and byte size for one content URI. */
+  private PickedContentMetadata readPickedContentMetadata(
+    Uri uri,
+    String fallbackMimeType,
+    int index
+  ) {
+    String fileName = null;
+    long sizeBytes = -1L;
+    ContentResolver contentResolver = reactContext.getContentResolver();
+
+    try (Cursor cursor = contentResolver.query(uri, null, null, null, null)) {
+      if (cursor != null && cursor.moveToFirst()) {
+        int displayNameIndex = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME);
+        if (displayNameIndex >= 0 && !cursor.isNull(displayNameIndex)) {
+          fileName = cursor.getString(displayNameIndex);
+        }
+        int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE);
+        if (sizeIndex >= 0 && !cursor.isNull(sizeIndex)) {
+          sizeBytes = cursor.getLong(sizeIndex);
+        }
+      }
+    } catch (RuntimeException error) {
+      logWarn("Could not read picker metadata for uri=" + uri, error);
+    }
+
+    String mimeType = contentResolver.getType(uri);
+    return new PickedContentMetadata(
+      fileName == null || fileName.length() == 0 ? "attachment-" + (index + 1) : fileName,
+      mimeType == null || mimeType.length() == 0 ? fallbackMimeType : mimeType,
+      sizeBytes
+    );
+  }
+
+  /** Reads a selected content URI into a bounded base64 payload. */
+  private String readUriAsBase64(
+    Uri uri,
+    long maxFileSizeBytes,
+    String fileName
+  ) throws IOException, PickerFileTooLargeException {
+    ContentResolver contentResolver = reactContext.getContentResolver();
+    try (InputStream inputStream = contentResolver.openInputStream(uri);
+         ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
+      if (inputStream == null) {
+        throw new IOException("Could not open selected file.");
+      }
+
+      byte[] buffer = new byte[BASE64_BUFFER_SIZE];
+      int bytesRead;
+      long totalBytes = 0L;
+      while ((bytesRead = inputStream.read(buffer)) != -1) {
+        totalBytes += bytesRead;
+        if (maxFileSizeBytes > 0L && totalBytes > maxFileSizeBytes) {
+          throw new PickerFileTooLargeException(fileName, totalBytes, maxFileSizeBytes);
+        }
+        outputStream.write(buffer, 0, bytesRead);
+      }
+
+      return Base64.encodeToString(outputStream.toByteArray(), Base64.NO_WRAP);
+    }
+  }
+
+  /** Converts successful Activity result extras into the JS picked-file payload for all coalesced callers. */
+  private void resolvePickedFiles(List<Promise> promises, Intent data) {
+    String resultId = readStringExtra(data, EXTRA_RESULT_ID, null);
+    String fileName = readStringExtra(data, EXTRA_RESULT_FILE_NAME, null);
+    String mimeType = readStringExtra(data, EXTRA_RESULT_MIME_TYPE, DEFAULT_IMAGE_MIME_TYPE);
+    String dataBase64 = readStringExtra(data, EXTRA_RESULT_DATA_BASE64, null);
+    long size = readLongExtra(data, EXTRA_RESULT_SIZE, dataBase64 == null ? 0L : estimateBase64ByteSize(dataBase64));
+    SagepilotInAppCameraResultStore.PickedImage storedImage =
+      SagepilotInAppCameraResultStore.take(reactContext, resultId, fileName, mimeType, size);
+
+    if (storedImage != null) {
+      logDebug(
+        "resolving stored camera payload: fileName=" + storedImage.fileName +
+          ", size=" + storedImage.sizeBytes +
+          ", base64Length=" + storedImage.dataBase64.length()
+      );
+      for (Promise promise : promises) {
+        resolvePickedFile(
+          promise,
+          storedImage.fileName,
+          storedImage.mimeType,
+          storedImage.sizeBytes,
+          storedImage.dataBase64
+        );
+      }
+      return;
+    }
+
+    if (resultId != null) {
+      logWarn("stored camera payload missing for resultId=" + resultId);
+    }
+
+    for (Promise promise : promises) {
+      resolvePickedFile(promise, fileName, mimeType, size, dataBase64);
+    }
+  }
+
+  /** Resolves a successful camera payload into the JS picked-file shape. */
+  private void resolvePickedFile(
+    Promise promise,
+    String fileName,
+    String mimeType,
+    long size,
+    String dataBase64
+  ) {
+    if (fileName == null || fileName.length() == 0 || dataBase64 == null || dataBase64.length() == 0) {
+      logWarn("camera payload missing fileName or base64 data");
+      rejectPromise(promise, ERROR_ENCODE_FAILED, "The photo could not be processed.");
+      return;
+    }
+
+    WritableMap file = Arguments.createMap();
+    file.putString("file_name", fileName);
+    file.putString("mime_type", mimeType);
+    file.putDouble("size", Math.max(0L, size));
+    file.putString("data_base64", dataBase64);
+    promise.resolve(file);
+  }
+
+  /** Checks the current Android runtime camera permission before direct native launch. */
+  private boolean hasCameraPermission() {
+    return ContextCompat.checkSelfPermission(reactContext, Manifest.permission.CAMERA)
+      == PackageManager.PERMISSION_GRANTED;
+  }
+
+  /** Checks whether the host device advertises at least one camera. */
+  private boolean hasCameraHardware() {
+    return reactContext.getPackageManager().hasSystemFeature(PackageManager.FEATURE_CAMERA_ANY);
+  }
+
+  /** Checks whether the SDK camera Activity class is packaged in the host app. */
+  private boolean hasCameraActivityClass() {
+    try {
+      Class.forName(CAMERA_ACTIVITY_CLASS_NAME);
+      return true;
+    } catch (ClassNotFoundException error) {
+      return false;
+    }
+  }
+
+  /** Reads an integer option from the JS options map with a native fallback. */
+  private int readIntOption(ReadableMap options, String key, int fallback) {
+    if (options == null || !options.hasKey(key) || options.isNull(key)) {
+      return fallback;
+    }
+    return Math.max(1, (int) Math.round(options.getDouble(key)));
+  }
+
+  /** Reads a double option from the JS options map with a native fallback. */
+  private double readDoubleOption(ReadableMap options, String key, double fallback) {
+    if (options == null || !options.hasKey(key) || options.isNull(key)) {
+      return fallback;
+    }
+    return Math.max(0.0, Math.min(1.0, options.getDouble(key)));
+  }
+
+  /** Converts a JS quality ratio into Android's 0-100 JPEG quality range. */
+  private int qualityRatioToPercent(double qualityRatio) {
+    if (Double.isNaN(qualityRatio) || Double.isInfinite(qualityRatio)) {
+      return (int) Math.round(DEFAULT_IMAGE_QUALITY * 100.0);
+    }
+    double clampedQuality = Math.max(0.0, Math.min(1.0, qualityRatio));
+    return (int) Math.round(clampedQuality * 100.0);
+  }
+
+  /** Reads a long option from the JS options map with a native fallback. */
+  private long readLongOption(ReadableMap options, String key, long fallback) {
+    if (options == null || !options.hasKey(key) || options.isNull(key)) {
+      return fallback;
+    }
+    return Math.max(0L, Math.round(options.getDouble(key)));
+  }
+
+  /** Reads a boolean option from the JS options map with a native fallback. */
+  private boolean readBooleanOption(ReadableMap options, String key, boolean fallback) {
+    if (options == null || !options.hasKey(key) || options.isNull(key)) {
+      return fallback;
+    }
+    try {
+      return options.getBoolean(key);
+    } catch (RuntimeException error) {
+      return fallback;
+    }
+  }
+
+  /** Reads a string extra from an Activity result with a fallback. */
+  private String readStringExtra(Intent data, String key, String fallback) {
+    if (data == null || !data.hasExtra(key)) {
+      return fallback;
+    }
+    String value = data.getStringExtra(key);
+    return value == null ? fallback : value;
+  }
+
+  /** Reads a long extra from an Activity result with a fallback. */
+  private long readLongExtra(Intent data, String key, long fallback) {
+    if (data == null || !data.hasExtra(key)) {
+      return fallback;
+    }
+    return data.getLongExtra(key, fallback);
+  }
+
+  /** Estimates byte size for a base64 payload when native size metadata is absent. */
+  private long estimateBase64ByteSize(String dataBase64) {
+    return (dataBase64.length() * 3L) / 4L;
+  }
+
+  /** Checks if a JS promise is already waiting for a camera result. */
+  private boolean hasPendingPromise() {
+    synchronized (pendingLock) {
+      return pendingPromise != null;
+    }
+  }
+
+  /** Stores the JS promise that will receive the next camera result. */
+  private void setPendingPromise(Promise promise) {
+    setPendingPromise(promise, 0L);
+  }
+
+  /** Stores the JS promise and file-size cap that will receive the next picker result. */
+  private void setPendingPromise(Promise promise, long maxFileSizeBytes) {
+    synchronized (pendingLock) {
+      pendingPromise = promise;
+      pendingMaxFileSizeBytes = maxFileSizeBytes;
+      pendingCameraCapture = false;
+      pendingCameraPromises.clear();
+    }
+  }
+
+  /** Stores the primary JS promise for a camera capture and starts a coalescing list. */
+  private void setPendingCameraPromise(Promise promise) {
+    synchronized (pendingLock) {
+      pendingPromise = promise;
+      pendingMaxFileSizeBytes = 0L;
+      pendingCameraCapture = true;
+      pendingCameraPromises.clear();
+      pendingCameraPromises.add(promise);
+    }
+  }
+
+  /** Adds a duplicate camera open request to the active capture instead of rejecting it. */
+  private boolean addPendingCameraPromise(Promise promise) {
+    synchronized (pendingLock) {
+      if (!pendingCameraCapture || pendingPromise == null) {
+        return false;
+      }
+      pendingCameraPromises.add(promise);
+      return true;
+    }
+  }
+
+  /** Takes and clears every promise waiting for the active camera capture. */
+  private List<Promise> takePendingCameraPromises() {
+    synchronized (pendingLock) {
+      if (!pendingCameraCapture) {
+        return new ArrayList<>();
+      }
+      List<Promise> promises = new ArrayList<>(pendingCameraPromises);
+      pendingPromise = null;
+      pendingMaxFileSizeBytes = 0L;
+      pendingCameraCapture = false;
+      pendingCameraPromises.clear();
+      return promises;
+    }
+  }
+
+  /** Takes and clears the pending promise so it can be settled exactly once. */
+  private Promise takePendingPromise() {
+    return takePendingPicker().promise;
+  }
+
+  /** Takes and clears the pending picker state so it can be settled exactly once. */
+  private PendingPicker takePendingPicker() {
+    synchronized (pendingLock) {
+      Promise promise = pendingPromise;
+      long maxFileSizeBytes = pendingMaxFileSizeBytes;
+      pendingPromise = null;
+      pendingMaxFileSizeBytes = 0L;
+      pendingCameraCapture = false;
+      pendingCameraPromises.clear();
+      return new PendingPicker(promise, maxFileSizeBytes);
+    }
+  }
+
+  /** Rejects and clears the pending promise when native ownership ends early. */
+  private void rejectPendingPromise(String code, String message, Throwable error) {
+    List<Promise> cameraPromises = takePendingCameraPromises();
+    if (!cameraPromises.isEmpty()) {
+      for (Promise promise : cameraPromises) {
+        rejectPromise(promise, code, message, error);
+      }
+      return;
+    }
+
+    Promise promise = takePendingPromise();
+    if (promise == null) {
+      return;
+    }
+    rejectPromise(promise, code, message, error);
+  }
+
+  /** Rejects a JS promise with a stable code and optional native cause. */
+  private void rejectPromise(Promise promise, String code, String message, Throwable error) {
+    logWarn("rejecting camera promise: code=" + code + ", message=" + message, error);
+    if (error == null) {
+      promise.reject(code, message);
+      return;
+    }
+    promise.reject(code, message, error);
+  }
+
+  /** Rejects a JS promise with a stable code. */
+  private void rejectPromise(Promise promise, String code, String message) {
+    rejectPromise(promise, code, message, null);
+  }
+
+  /** Writes a native debug log and mirrors it into the React Native console. */
+  private void logDebug(String message) {
+    Log.d(TAG, message);
+    SagepilotInAppCameraDebugEvents.debug(message);
+  }
+
+  /** Writes a native warning log and mirrors it into the React Native console. */
+  private void logWarn(String message) {
+    Log.w(TAG, message);
+    SagepilotInAppCameraDebugEvents.warn(message);
+  }
+
+  /** Writes a native warning log with a cause and mirrors it into the React Native console. */
+  private void logWarn(String message, Throwable error) {
+    Log.w(TAG, message, error);
+    SagepilotInAppCameraDebugEvents.warn(message);
+  }
+
+  /** Writes a native error log and mirrors it into the React Native console. */
+  private void logError(String message, Throwable error) {
+    Log.e(TAG, message, error);
+    SagepilotInAppCameraDebugEvents.error(message, error);
+  }
+
+  private static final class PendingPicker {
+    final Promise promise;
+    final long maxFileSizeBytes;
+
+    /** Holds pending picker state captured before clearing the shared pending slot. */
+    PendingPicker(Promise promise, long maxFileSizeBytes) {
+      this.promise = promise;
+      this.maxFileSizeBytes = maxFileSizeBytes;
+    }
+  }
+
+  private static final class PickedContentMetadata {
+    final String fileName;
+    final String mimeType;
+    final long sizeBytes;
+
+    /** Holds Android content metadata used to build a picked-file payload. */
+    PickedContentMetadata(String fileName, String mimeType, long sizeBytes) {
+      this.fileName = fileName;
+      this.mimeType = mimeType;
+      this.sizeBytes = sizeBytes;
+    }
+  }
+
+  private static final class PickerFileTooLargeException extends Exception {
+    private static final long serialVersionUID = 1L;
+
+    /** Creates a picker size-cap failure with file name and byte counts. */
+    PickerFileTooLargeException(String fileName, long actualSizeBytes, long maxSizeBytes) {
+      super("\"" + fileName + "\" is too large: " + actualSizeBytes + " > " + maxSizeBytes);
+    }
+  }
+}