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

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

@@ -0,0 +1,1549 @@
+package ai.sagepilot.reactnativecameraaddon;
+
+import android.Manifest;
+import android.app.Activity;
+import android.content.Intent;
+import android.content.pm.PackageManager;
+import android.content.res.ColorStateList;
+import android.graphics.Color;
+import android.graphics.Typeface;
+import android.graphics.drawable.GradientDrawable;
+import android.graphics.drawable.RippleDrawable;
+import android.net.Uri;
+import android.os.Build;
+import android.os.Bundle;
+import android.util.Log;
+import android.util.Size;
+import android.view.Gravity;
+import android.view.HapticFeedbackConstants;
+import android.view.MotionEvent;
+import android.view.ScaleGestureDetector;
+import android.view.Surface;
+import android.view.View;
+import android.view.ViewGroup;
+import android.widget.FrameLayout;
+import android.widget.ImageView;
+import android.widget.LinearLayout;
+import android.widget.TextView;
+import android.view.Window;
+import android.view.WindowManager;
+import android.view.animation.DecelerateInterpolator;
+import androidx.activity.ComponentActivity;
+import androidx.activity.OnBackPressedCallback;
+import androidx.camera.core.Camera;
+import androidx.camera.core.CameraInfoUnavailableException;
+import androidx.camera.core.CameraSelector;
+import androidx.camera.core.ImageCapture;
+import androidx.camera.core.ImageCaptureException;
+import androidx.camera.core.Preview;
+import androidx.camera.core.ZoomState;
+import androidx.camera.lifecycle.ProcessCameraProvider;
+import androidx.camera.core.resolutionselector.ResolutionSelector;
+import androidx.camera.core.resolutionselector.ResolutionStrategy;
+import androidx.camera.view.PreviewView;
+import androidx.core.app.ActivityCompat;
+import androidx.core.graphics.Insets;
+import androidx.core.content.ContextCompat;
+import androidx.core.view.ViewCompat;
+import androidx.core.view.WindowCompat;
+import androidx.core.view.WindowInsetsCompat;
+import com.google.common.util.concurrent.ListenableFuture;
+import java.io.File;
+import java.io.IOException;
+import java.util.Locale;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Executor;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+public class SagepilotInAppCameraActivity extends ComponentActivity {
+  private static final String TAG = "SagepilotInAppCamera";
+  private static final String STATE_LENS_FACING = "ai.sagepilot.reactnativecameraaddon.camera.STATE_LENS_FACING";
+  private static final String STATE_CAPTURE_IN_PROGRESS =
+    "ai.sagepilot.reactnativecameraaddon.camera.STATE_CAPTURE_IN_PROGRESS";
+  private static final String STATE_SHOWING_PREVIEW = "ai.sagepilot.reactnativecameraaddon.camera.STATE_SHOWING_PREVIEW";
+  private static final String STATE_PENDING_CAPTURE_PHOTO_PATH =
+    "ai.sagepilot.reactnativecameraaddon.camera.STATE_PENDING_CAPTURE_PHOTO_PATH";
+  private static final String STATE_PENDING_PREVIEW_PHOTO_PATH =
+    "ai.sagepilot.reactnativecameraaddon.camera.STATE_PENDING_PREVIEW_PHOTO_PATH";
+  private static final String STATE_ZOOM_RATIO = "ai.sagepilot.reactnativecameraaddon.camera.STATE_ZOOM_RATIO";
+  private static final String CAMERA_CACHE_DIRECTORY_NAME = "sagepilot-camera";
+  private static final String PHOTO_FILE_PREFIX = "sagepilot-camera-";
+  private static final String PROCESSED_PHOTO_FILE_PREFIX = "sagepilot-camera-processed-";
+  private static final String PHOTO_FILE_EXTENSION = ".jpg";
+  private static final String IMAGE_MIME_TYPE = "image/jpeg";
+  private static final int REQUEST_CODE_CAMERA_PERMISSION = 0x534A;
+
+  private static final int DEFAULT_IMAGE_MAX_DIMENSION = 1920;
+  private static final double DEFAULT_IMAGE_QUALITY = 0.8;
+  private static final int DEFAULT_IMAGE_QUALITY_PERCENT = 80;
+  private static final long DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES = 15L * 1024L * 1024L;
+  private static final int CONTROL_MARGIN_DP = 24;
+  private static final int TOP_CONTROL_WIDTH_DP = 44;
+  private static final int TOP_CONTROL_HEIGHT_DP = 44;
+  private static final int SHUTTER_SIZE_DP = 82;
+  private static final int SHUTTER_INNER_SIZE_DP = 62;
+  private static final int SHUTTER_BOTTOM_MARGIN_DP = 42;
+  private static final int TOP_SCRIM_HEIGHT_DP = 132;
+  private static final int BOTTOM_SCRIM_HEIGHT_DP = 196;
+  private static final int PROCESSING_PANEL_WIDTH_DP = 156;
+  private static final int PROCESSING_PANEL_HEIGHT_DP = 48;
+  private static final long SHUTTER_PRESS_ANIMATION_MS = 90L;
+  private static final long SHUTTER_RELEASE_ANIMATION_MS = 150L;
+  private static final long CAPTURE_FLASH_IN_MS = 55L;
+  private static final long CAPTURE_FLASH_OUT_MS = 170L;
+  private static final float DEFAULT_ZOOM_RATIO = 1.0f;
+  private static final float MIN_ZOOM_STEP_DELTA = 0.01f;
+  private static final int ZOOM_TOUCH_LOG_POINTER_COUNT = 2;
+
+  private final AtomicBoolean resultSettled = new AtomicBoolean(false);
+  private final AtomicBoolean captureInProgress = new AtomicBoolean(false);
+  private final DecelerateInterpolator controlInterpolator = new DecelerateInterpolator();
+
+  private FrameLayout rootView;
+  private PreviewView previewView;
+  private ImageView capturedPreviewView;
+  private View shutterButton;
+  private View shutterInnerButton;
+  private ImageView closeButton;
+  private ImageView switchButton;
+  private TextView cameraTitle;
+  private ImageView retakeButton;
+  private ImageView usePhotoButton;
+  private LinearLayout previewActionBar;
+  private View captureFlashView;
+  private View processingOverlay;
+  private FrameLayout.LayoutParams topScrimParams;
+  private FrameLayout.LayoutParams bottomScrimParams;
+  private FrameLayout.LayoutParams titleParams;
+  private FrameLayout.LayoutParams closeParams;
+  private FrameLayout.LayoutParams switchParams;
+  private FrameLayout.LayoutParams shutterParams;
+  private FrameLayout.LayoutParams previewActionParams;
+  private ProcessCameraProvider cameraProvider;
+  private Camera camera;
+  private ImageCapture imageCapture;
+  private ScaleGestureDetector zoomGestureDetector;
+  private Executor mainExecutor;
+  private ExecutorService cameraExecutor;
+  private int imageMaxDimension = DEFAULT_IMAGE_MAX_DIMENSION;
+  private int imageQuality = DEFAULT_IMAGE_QUALITY_PERCENT;
+  private long imageMaxFileSizeBytes = DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES;
+  private int lensFacing = CameraSelector.LENS_FACING_BACK;
+  private File pendingCapturePhotoFile;
+  private File pendingPreviewPhotoFile;
+  private int safeTopInsetPx;
+  private int safeBottomInsetPx;
+  private int safeLeftInsetPx;
+  private int safeRightInsetPx;
+  private float zoomRatio = DEFAULT_ZOOM_RATIO;
+  private boolean showingPreview;
+
+  /** Creates the SDK-owned in-app camera screen and starts CameraX preview binding. */
+  @Override
+  protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    logDebug("Activity onCreate");
+    configureWindowChrome();
+    mainExecutor = ContextCompat.getMainExecutor(this);
+    cameraExecutor = Executors.newSingleThreadExecutor();
+    installBackHandler();
+    readOptions(getIntent());
+    restoreState(savedInstanceState);
+
+    if (!hasCameraPermission()) {
+      requestCameraPermission();
+      return;
+    }
+
+    startCameraSession();
+  }
+
+  /** Starts the CameraX UI after permission and saved-state recovery are complete. */
+  private void startCameraSession() {
+    cleanupStaleCameraFiles();
+    createCameraLayout();
+    restoreCapturedPreviewIfNeeded();
+    startCameraProvider();
+  }
+
+  /** Stores camera UI and temp-file state so configuration recreation can resume safely. */
+  @Override
+  protected void onSaveInstanceState(Bundle outState) {
+    super.onSaveInstanceState(outState);
+    logDebug("Activity onSaveInstanceState: captureInProgress=" + captureInProgress.get());
+    outState.putInt(STATE_LENS_FACING, lensFacing);
+    outState.putBoolean(STATE_CAPTURE_IN_PROGRESS, captureInProgress.get() && !resultSettled.get());
+    outState.putBoolean(STATE_SHOWING_PREVIEW, showingPreview && pendingPreviewPhotoFile != null);
+    outState.putString(STATE_PENDING_CAPTURE_PHOTO_PATH, getFilePath(pendingCapturePhotoFile));
+    outState.putString(STATE_PENDING_PREVIEW_PHOTO_PATH, getFilePath(pendingPreviewPhotoFile));
+    outState.putFloat(STATE_ZOOM_RATIO, zoomRatio);
+  }
+
+  /** Continues camera startup after the Activity-side runtime permission request finishes. */
+  @Override
+  public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
+    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
+    if (requestCode != REQUEST_CODE_CAMERA_PERMISSION) {
+      return;
+    }
+    if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
+      logDebug("Activity camera permission granted");
+      startCameraSession();
+      return;
+    }
+    logWarn("Activity camera permission denied");
+    finishWithError(
+      SagepilotInAppCameraModule.ERROR_PERMISSION_DENIED,
+      "Camera permission is required to take a photo."
+    );
+  }
+
+  /** Releases CameraX and settles cancellation if Android destroys the screen before a result. */
+  @Override
+  protected void onDestroy() {
+    logDebug(
+      "Activity onDestroy: changingConfigurations=" + isChangingConfigurations() +
+        ", resultSettled=" + resultSettled.get()
+    );
+    if (cameraProvider != null) {
+      cameraProvider.unbindAll();
+    }
+    camera = null;
+    imageCapture = null;
+    if (cameraExecutor != null) {
+      cameraExecutor.shutdownNow();
+    }
+    if (!isChangingConfigurations()) {
+      discardPendingCaptureFile();
+      discardPendingPreviewFile();
+    }
+    if (!isChangingConfigurations() && resultSettled.compareAndSet(false, true)) {
+      setResult(Activity.RESULT_CANCELED);
+    }
+    super.onDestroy();
+  }
+
+  /** Installs AndroidX back handling so hardware back maps to picker cancellation. */
+  private void installBackHandler() {
+    getOnBackPressedDispatcher().addCallback(this, new OnBackPressedCallback(true) {
+      /** Cancels the SDK camera Activity when the customer presses back. */
+      @Override
+      public void handleOnBackPressed() {
+        finishWithCancel();
+      }
+    });
+  }
+
+  /** Configures the camera window for an immersive, wakeful capture surface. */
+  private void configureWindowChrome() {
+    Window window = getWindow();
+    if (window == null) {
+      return;
+    }
+
+    window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+    WindowCompat.setDecorFitsSystemWindows(window, false);
+    window.setStatusBarColor(Color.TRANSPARENT);
+    window.setNavigationBarColor(Color.BLACK);
+  }
+
+  /** Reads normalized processing options from the NativeModule launch intent. */
+  private void readOptions(Intent intent) {
+    if (intent == null) {
+      logDebug("Activity launched without options; using defaults");
+      return;
+    }
+    imageMaxDimension = Math.max(
+      1,
+      intent.getIntExtra(SagepilotInAppCameraModule.EXTRA_IMAGE_MAX_DIMENSION, DEFAULT_IMAGE_MAX_DIMENSION)
+    );
+    imageMaxFileSizeBytes = Math.max(
+      0L,
+      intent.getLongExtra(
+        SagepilotInAppCameraModule.EXTRA_IMAGE_MAX_FILE_SIZE_BYTES,
+        DEFAULT_IMAGE_MAX_FILE_SIZE_BYTES
+      )
+    );
+    imageQuality = qualityRatioToPercent(
+      intent.getDoubleExtra(SagepilotInAppCameraModule.EXTRA_IMAGE_QUALITY, DEFAULT_IMAGE_QUALITY)
+    );
+    logDebug(
+      "Camera options: maxDimension=" + imageMaxDimension +
+        ", jpegQuality=" + imageQuality +
+        ", maxFileSizeBytes=" + imageMaxFileSizeBytes
+    );
+  }
+
+  /** 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 DEFAULT_IMAGE_QUALITY_PERCENT;
+    }
+    double clampedQuality = Math.max(0.0, Math.min(1.0, qualityRatio));
+    return (int) Math.round(clampedQuality * 100.0);
+  }
+
+  /** Restores the selected camera lens and recoverable temp-file state after recreation. */
+  private void restoreState(Bundle savedInstanceState) {
+    if (savedInstanceState == null) {
+      return;
+    }
+    int restoredLensFacing = savedInstanceState.getInt(STATE_LENS_FACING, CameraSelector.LENS_FACING_BACK);
+    if (restoredLensFacing == CameraSelector.LENS_FACING_FRONT) {
+      lensFacing = CameraSelector.LENS_FACING_FRONT;
+    } else {
+      lensFacing = CameraSelector.LENS_FACING_BACK;
+    }
+    captureInProgress.set(savedInstanceState.getBoolean(STATE_CAPTURE_IN_PROGRESS, false));
+    pendingCapturePhotoFile = readRestoredCameraFile(savedInstanceState.getString(STATE_PENDING_CAPTURE_PHOTO_PATH));
+    pendingPreviewPhotoFile = readRestoredCameraFile(savedInstanceState.getString(STATE_PENDING_PREVIEW_PHOTO_PATH));
+    float restoredZoomRatio = savedInstanceState.getFloat(STATE_ZOOM_RATIO, DEFAULT_ZOOM_RATIO);
+    zoomRatio = Float.isNaN(restoredZoomRatio) || Float.isInfinite(restoredZoomRatio) || restoredZoomRatio <= 0.0f
+      ? DEFAULT_ZOOM_RATIO
+      : restoredZoomRatio;
+    showingPreview = savedInstanceState.getBoolean(STATE_SHOWING_PREVIEW, false) && pendingPreviewPhotoFile != null;
+
+    if (captureInProgress.get()) {
+      if (pendingCapturePhotoFile != null && pendingCapturePhotoFile.exists() && pendingCapturePhotoFile.length() > 0L) {
+        logWarn("Recovering captured file after Activity recreation");
+        pendingPreviewPhotoFile = pendingCapturePhotoFile;
+        pendingCapturePhotoFile = null;
+        showingPreview = true;
+      } else {
+        logWarn("Activity recreated mid-capture before file was durable; reopening camera instead of failing");
+        pendingCapturePhotoFile = null;
+      }
+      captureInProgress.set(false);
+    }
+    logDebug(
+      "Restored camera state: lensFacing=" + lensFacing +
+        ", captureInProgress=" + captureInProgress.get() +
+        ", showingPreview=" + showingPreview
+    );
+  }
+
+  /** Returns a restored SDK camera temp file when it still lives inside the SDK cache directory. */
+  private File readRestoredCameraFile(String path) {
+    if (path == null || path.length() == 0) {
+      return null;
+    }
+    File file = new File(path);
+    if (!isCameraCacheFile(file) || !file.exists() || !file.isFile()) {
+      return null;
+    }
+    return file;
+  }
+
+  /** Checks whether a file path belongs to this SDK camera cache directory. */
+  private boolean isCameraCacheFile(File file) {
+    String directoryPath = getCameraCacheDirectory().getAbsolutePath();
+    String filePath = file.getAbsolutePath();
+    return filePath.startsWith(directoryPath + File.separator);
+  }
+
+  /** Returns a nullable file path for saving Activity state. */
+  private String getFilePath(File file) {
+    return file == null ? null : file.getAbsolutePath();
+  }
+
+  /** Restores the captured-photo preview after layout recreation. */
+  private void restoreCapturedPreviewIfNeeded() {
+    File photoFile = pendingPreviewPhotoFile;
+    if (!showingPreview || photoFile == null || !photoFile.exists()) {
+      showingPreview = false;
+      pendingPreviewPhotoFile = null;
+      return;
+    }
+
+    logDebug("Restoring captured photo preview: " + photoFile.getAbsolutePath());
+    if (capturedPreviewView != null) {
+      capturedPreviewView.setImageURI(Uri.fromFile(photoFile));
+      capturedPreviewView.setVisibility(View.VISIBLE);
+      capturedPreviewView.setAlpha(1.0f);
+    }
+    if (previewView != null) {
+      previewView.setVisibility(View.INVISIBLE);
+    }
+    if (cameraTitle != null) {
+      cameraTitle.setText("Preview");
+    }
+    if (previewActionBar != null) {
+      previewActionBar.setVisibility(View.VISIBLE);
+      previewActionBar.setAlpha(1.0f);
+    }
+    updateControlState(true);
+  }
+
+  /** Checks the runtime camera permission before touching CameraX. */
+  private boolean hasCameraPermission() {
+    return ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED;
+  }
+
+  /** Requests CAMERA at the Activity boundary for direct launches that bypass JavaScript. */
+  private void requestCameraPermission() {
+    logWarn("Activity missing camera permission; requesting CAMERA");
+    ActivityCompat.requestPermissions(
+      this,
+      new String[] { Manifest.permission.CAMERA },
+      REQUEST_CODE_CAMERA_PERMISSION
+    );
+  }
+
+  /** Builds the full-screen preview and minimal capture controls. */
+  private void createCameraLayout() {
+    logDebug("Creating CameraX layout");
+    rootView = new FrameLayout(this);
+    rootView.setBackgroundColor(Color.BLACK);
+    rootView.setClipToPadding(false);
+
+    previewView = new PreviewView(this);
+    previewView.setImplementationMode(PreviewView.ImplementationMode.PERFORMANCE);
+    previewView.setScaleType(PreviewView.ScaleType.FILL_CENTER);
+    previewView.setClickable(true);
+    installZoomGestureHandler();
+    rootView.addView(previewView, new FrameLayout.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT,
+      ViewGroup.LayoutParams.MATCH_PARENT
+    ));
+
+    capturedPreviewView = createCapturedPreviewView();
+    rootView.addView(capturedPreviewView, new FrameLayout.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT,
+      ViewGroup.LayoutParams.MATCH_PARENT
+    ));
+
+    captureFlashView = createCaptureFlashView();
+    rootView.addView(captureFlashView, new FrameLayout.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT,
+      ViewGroup.LayoutParams.MATCH_PARENT
+    ));
+
+    topScrimParams = createTopScrimLayoutParams();
+    rootView.addView(createTopScrim(), topScrimParams);
+    bottomScrimParams = createBottomScrimLayoutParams();
+    rootView.addView(createBottomScrim(), bottomScrimParams);
+
+    cameraTitle = createCameraTitle();
+    titleParams = new FrameLayout.LayoutParams(
+      ViewGroup.LayoutParams.WRAP_CONTENT,
+      dp(TOP_CONTROL_HEIGHT_DP)
+    );
+    titleParams.gravity = Gravity.TOP | Gravity.CENTER_HORIZONTAL;
+    rootView.addView(cameraTitle, titleParams);
+
+    closeButton = createIconButton(R.drawable.sagepilot_ic_x, "Close camera");
+    closeParams = new FrameLayout.LayoutParams(
+      dp(TOP_CONTROL_HEIGHT_DP),
+      dp(TOP_CONTROL_HEIGHT_DP)
+    );
+    closeParams.gravity = Gravity.TOP | Gravity.START;
+    rootView.addView(closeButton, closeParams);
+
+    switchButton = createIconButton(R.drawable.sagepilot_ic_switch_camera, "Switch camera");
+    switchParams = new FrameLayout.LayoutParams(
+      dp(TOP_CONTROL_WIDTH_DP),
+      dp(TOP_CONTROL_HEIGHT_DP)
+    );
+    switchParams.gravity = Gravity.TOP | Gravity.END;
+    rootView.addView(switchButton, switchParams);
+
+    shutterButton = createShutterButton();
+    shutterParams = new FrameLayout.LayoutParams(dp(SHUTTER_SIZE_DP), dp(SHUTTER_SIZE_DP));
+    shutterParams.gravity = Gravity.BOTTOM | Gravity.CENTER_HORIZONTAL;
+    rootView.addView(shutterButton, shutterParams);
+
+    previewActionBar = createPreviewActionBar();
+    previewActionParams = new FrameLayout.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT,
+      dp(64)
+    );
+    previewActionParams.gravity = Gravity.BOTTOM;
+    rootView.addView(previewActionBar, previewActionParams);
+
+    processingOverlay = createProcessingOverlay();
+    FrameLayout.LayoutParams processingParams = new FrameLayout.LayoutParams(
+      dp(PROCESSING_PANEL_WIDTH_DP),
+      dp(PROCESSING_PANEL_HEIGHT_DP)
+    );
+    processingParams.gravity = Gravity.CENTER;
+    rootView.addView(processingOverlay, processingParams);
+
+    closeButton.setOnClickListener(view -> finishWithCancel());
+    switchButton.setOnClickListener(view -> switchCamera());
+    shutterButton.setOnTouchListener(createShutterTouchListener());
+    shutterButton.setOnClickListener(view -> {
+      view.performHapticFeedback(HapticFeedbackConstants.VIRTUAL_KEY);
+      capturePhoto();
+    });
+    retakeButton.setOnClickListener(view -> retakePhoto());
+    usePhotoButton.setOnClickListener(view -> acceptPreviewPhoto());
+    installSafeAreaInsets(rootView);
+    applySafeAreaInsetsToControls();
+    setContentView(rootView);
+    ViewCompat.requestApplyInsets(rootView);
+    updateControlState(false);
+  }
+
+  /** Installs pinch-to-zoom handling on the live CameraX preview. */
+  private void installZoomGestureHandler() {
+    if (previewView == null) {
+      return;
+    }
+    logDebug("Installing CameraX zoom gesture handler");
+    zoomGestureDetector = new ScaleGestureDetector(this, new ScaleGestureDetector.SimpleOnScaleGestureListener() {
+      /** Logs the active CameraX zoom range when a pinch starts. */
+      @Override
+      public boolean onScaleBegin(ScaleGestureDetector detector) {
+        logZoomGestureBegin();
+        return true;
+      }
+
+      /** Applies each pinch gesture step to CameraX zoom control. */
+      @Override
+      public boolean onScale(ScaleGestureDetector detector) {
+        return handleZoomScale(detector.getScaleFactor());
+      }
+
+      /** Logs the final zoom ratio when a pinch finishes. */
+      @Override
+      public void onScaleEnd(ScaleGestureDetector detector) {
+        logDebug("CameraX zoom gesture end: zoomRatio=" + zoomRatio);
+      }
+    });
+    previewView.setOnTouchListener((view, event) -> {
+      boolean canHandleZoom = canHandleZoomGesture();
+      logZoomTouchEvent(event, canHandleZoom);
+      if (!canHandleZoom) {
+        return false;
+      }
+      ScaleGestureDetector detector = zoomGestureDetector;
+      if (detector == null) {
+        return false;
+      }
+      detector.onTouchEvent(event);
+      return true;
+    });
+  }
+
+  /** Creates the dark top gradient that keeps controls legible over the preview. */
+  private View createTopScrim() {
+    View scrim = new View(this);
+    scrim.setBackground(createVerticalGradient(0xA6000000, 0x00000000, GradientDrawable.Orientation.TOP_BOTTOM));
+    return scrim;
+  }
+
+  /** Creates the dark bottom gradient that visually anchors the shutter control. */
+  private View createBottomScrim() {
+    View scrim = new View(this);
+    scrim.setBackground(createVerticalGradient(0x00000000, 0xCC000000, GradientDrawable.Orientation.TOP_BOTTOM));
+    return scrim;
+  }
+
+  /** Creates the full-screen still preview used after a photo is captured. */
+  private ImageView createCapturedPreviewView() {
+    ImageView imageView = new ImageView(this);
+    imageView.setBackgroundColor(Color.BLACK);
+    imageView.setScaleType(ImageView.ScaleType.FIT_CENTER);
+    imageView.setVisibility(View.GONE);
+    imageView.setAlpha(0.0f);
+    return imageView;
+  }
+
+  /** Returns layout params for the camera top gradient. */
+  private FrameLayout.LayoutParams createTopScrimLayoutParams() {
+    FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT,
+      dp(TOP_SCRIM_HEIGHT_DP)
+    );
+    params.gravity = Gravity.TOP;
+    return params;
+  }
+
+  /** Returns layout params for the camera bottom gradient. */
+  private FrameLayout.LayoutParams createBottomScrimLayoutParams() {
+    FrameLayout.LayoutParams params = new FrameLayout.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT,
+      dp(BOTTOM_SCRIM_HEIGHT_DP)
+    );
+    params.gravity = Gravity.BOTTOM;
+    return params;
+  }
+
+  /** Subscribes the full-screen Activity to system-bar and cutout inset changes. */
+  private void installSafeAreaInsets(FrameLayout root) {
+    ViewCompat.setOnApplyWindowInsetsListener(root, (view, windowInsets) -> {
+      Insets insets = windowInsets.getInsets(
+        WindowInsetsCompat.Type.systemBars() | WindowInsetsCompat.Type.displayCutout()
+      );
+      updateSafeAreaInsets(insets);
+      return windowInsets;
+    });
+    ViewCompat.requestApplyInsets(root);
+  }
+
+  /** Stores the latest safe-area insets and reapplies camera control margins. */
+  private void updateSafeAreaInsets(Insets insets) {
+    safeTopInsetPx = Math.max(0, insets.top);
+    safeBottomInsetPx = Math.max(0, insets.bottom);
+    safeLeftInsetPx = Math.max(0, insets.left);
+    safeRightInsetPx = Math.max(0, insets.right);
+    applySafeAreaInsetsToControls();
+  }
+
+  /** Offsets camera controls away from status bars, cutouts, and navigation bars. */
+  private void applySafeAreaInsetsToControls() {
+    int controlMargin = dp(CONTROL_MARGIN_DP);
+    if (topScrimParams != null) {
+      topScrimParams.height = dp(TOP_SCRIM_HEIGHT_DP) + safeTopInsetPx;
+    }
+    if (bottomScrimParams != null) {
+      bottomScrimParams.height = dp(BOTTOM_SCRIM_HEIGHT_DP) + safeBottomInsetPx;
+    }
+    if (titleParams != null) {
+      titleParams.setMargins(0, safeTopInsetPx + controlMargin, 0, 0);
+    }
+    if (closeParams != null) {
+      closeParams.setMargins(safeLeftInsetPx + controlMargin, safeTopInsetPx + controlMargin, 0, 0);
+    }
+    if (switchParams != null) {
+      switchParams.setMargins(0, safeTopInsetPx + controlMargin, safeRightInsetPx + controlMargin, 0);
+    }
+    if (shutterParams != null) {
+      shutterParams.setMargins(0, 0, 0, safeBottomInsetPx + dp(SHUTTER_BOTTOM_MARGIN_DP));
+    }
+    if (previewActionParams != null) {
+      previewActionParams.setMargins(
+        safeLeftInsetPx + controlMargin,
+        0,
+        safeRightInsetPx + controlMargin,
+        safeBottomInsetPx + dp(SHUTTER_BOTTOM_MARGIN_DP)
+      );
+    }
+    if (rootView != null) {
+      rootView.requestLayout();
+    }
+  }
+
+  /** Creates the centered camera title. */
+  private TextView createCameraTitle() {
+    TextView title = new TextView(this);
+    title.setText("Camera");
+    title.setTextColor(Color.WHITE);
+    title.setTextSize(16);
+    title.setTypeface(Typeface.DEFAULT_BOLD);
+    title.setGravity(Gravity.CENTER);
+    title.setIncludeFontPadding(false);
+    title.setAlpha(0.92f);
+    return title;
+  }
+
+  /** Creates a compact icon control for the top camera actions. */
+  private ImageView createIconButton(int iconResourceId, String contentDescription) {
+    ImageView button = new ImageView(this);
+    button.setImageResource(iconResourceId);
+    button.setColorFilter(Color.WHITE);
+    button.setContentDescription(contentDescription);
+    button.setScaleType(ImageView.ScaleType.CENTER);
+    button.setPadding(dp(10), dp(10), dp(10), dp(10));
+    button.setClickable(true);
+    button.setFocusable(true);
+    button.setBackground(createRoundedBackground(0x66000000, 0x44FFFFFF, 22, 1));
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+      button.setForeground(createRippleDrawable(0x33FFFFFF, 22));
+    }
+    button.setElevation(dp(3));
+    return button;
+  }
+
+  /** Creates the circular shutter control. */
+  private View createShutterButton() {
+    FrameLayout button = new FrameLayout(this);
+    button.setContentDescription("Take photo");
+    button.setClickable(true);
+    button.setFocusable(true);
+    button.setBackground(createOvalBackground(0x22FFFFFF, 0xFFFFFFFF, 4));
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+      button.setForeground(createOvalRippleDrawable(0x33FFFFFF));
+    }
+    button.setElevation(dp(8));
+
+    shutterInnerButton = new View(this);
+    shutterInnerButton.setBackground(createOvalBackground(Color.WHITE, 0x00000000, 0));
+    FrameLayout.LayoutParams innerParams = new FrameLayout.LayoutParams(
+      dp(SHUTTER_INNER_SIZE_DP),
+      dp(SHUTTER_INNER_SIZE_DP)
+    );
+    innerParams.gravity = Gravity.CENTER;
+    button.addView(shutterInnerButton, innerParams);
+    return button;
+  }
+
+  /** Creates the white flash layer shown immediately when capture starts. */
+  private View createCaptureFlashView() {
+    View flash = new View(this);
+    flash.setBackgroundColor(Color.WHITE);
+    flash.setAlpha(0.0f);
+    flash.setVisibility(View.GONE);
+    flash.setClickable(false);
+    return flash;
+  }
+
+  /** Creates the transient processing panel shown while CameraX saves and encodes. */
+  private View createProcessingOverlay() {
+    TextView overlay = new TextView(this);
+    overlay.setText("Processing...");
+    overlay.setTextColor(Color.WHITE);
+    overlay.setTextSize(14);
+    overlay.setTypeface(Typeface.DEFAULT_BOLD);
+    overlay.setGravity(Gravity.CENTER);
+    overlay.setIncludeFontPadding(false);
+    overlay.setBackground(createRoundedBackground(0xB3000000, 0x33FFFFFF, 24, 1));
+    overlay.setAlpha(0.0f);
+    overlay.setVisibility(View.GONE);
+    overlay.setElevation(dp(10));
+    return overlay;
+  }
+
+  /** Creates the preview action row shown after capture. */
+  private LinearLayout createPreviewActionBar() {
+    LinearLayout actionBar = new LinearLayout(this);
+    actionBar.setOrientation(LinearLayout.HORIZONTAL);
+    actionBar.setGravity(Gravity.CENTER);
+    actionBar.setVisibility(View.GONE);
+    actionBar.setAlpha(0.0f);
+
+    retakeButton = createPreviewActionButton(R.drawable.sagepilot_ic_rotate_ccw, "Retake photo", false);
+    usePhotoButton = createPreviewActionButton(R.drawable.sagepilot_ic_check, "Use photo", true);
+
+    LinearLayout.LayoutParams retakeParams = new LinearLayout.LayoutParams(dp(62), dp(62));
+    retakeParams.setMargins(0, 0, dp(18), 0);
+    actionBar.addView(retakeButton, retakeParams);
+
+    LinearLayout.LayoutParams useParams = new LinearLayout.LayoutParams(dp(62), dp(62));
+    useParams.setMargins(dp(18), 0, 0, 0);
+    actionBar.addView(usePhotoButton, useParams);
+    return actionBar;
+  }
+
+  /** Creates one icon-only action button for captured-photo preview decisions. */
+  private ImageView createPreviewActionButton(int iconResourceId, String contentDescription, boolean primary) {
+    ImageView button = new ImageView(this);
+    button.setImageResource(iconResourceId);
+    button.setColorFilter(primary ? Color.BLACK : Color.WHITE);
+    button.setContentDescription(contentDescription);
+    button.setScaleType(ImageView.ScaleType.CENTER);
+    button.setPadding(dp(17), dp(17), dp(17), dp(17));
+    button.setClickable(true);
+    button.setFocusable(true);
+    button.setBackground(createOvalBackground(primary ? Color.WHITE : 0x66000000, 0x44FFFFFF, primary ? 2 : 1));
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+      button.setForeground(createOvalRippleDrawable(primary ? 0x33000000 : 0x33FFFFFF));
+    }
+    button.setElevation(dp(primary ? 8 : 4));
+    return button;
+  }
+
+  /** Creates touch feedback for the shutter while preserving normal click dispatch. */
+  private View.OnTouchListener createShutterTouchListener() {
+    return (view, event) -> {
+      if (!view.isEnabled()) {
+        return false;
+      }
+
+      int action = event.getActionMasked();
+      if (action == MotionEvent.ACTION_DOWN) {
+        animateShutterPressed(true);
+      } else if (action == MotionEvent.ACTION_UP || action == MotionEvent.ACTION_CANCEL) {
+        animateShutterPressed(false);
+      }
+      return false;
+    };
+  }
+
+  /** Animates the shutter between resting and pressed states. */
+  private void animateShutterPressed(boolean pressed) {
+    if (shutterButton == null) {
+      return;
+    }
+
+    float buttonScale = pressed ? 0.90f : 1.0f;
+    float innerScale = pressed ? 0.82f : 1.0f;
+    long duration = pressed ? SHUTTER_PRESS_ANIMATION_MS : SHUTTER_RELEASE_ANIMATION_MS;
+
+    shutterButton.animate()
+      .scaleX(buttonScale)
+      .scaleY(buttonScale)
+      .setDuration(duration)
+      .setInterpolator(controlInterpolator)
+      .start();
+
+    if (shutterInnerButton != null) {
+      shutterInnerButton.animate()
+        .scaleX(innerScale)
+        .scaleY(innerScale)
+        .setDuration(duration)
+        .setInterpolator(controlInterpolator)
+        .start();
+    }
+  }
+
+  /** Plays immediate camera feedback before the slower file save/processing work. */
+  private void playCaptureFeedback() {
+    animateShutterPressed(false);
+    if (captureFlashView == null) {
+      return;
+    }
+
+    captureFlashView.animate().cancel();
+    captureFlashView.setAlpha(0.0f);
+    captureFlashView.setVisibility(View.VISIBLE);
+    captureFlashView.animate()
+      .alpha(0.36f)
+      .setDuration(CAPTURE_FLASH_IN_MS)
+      .setInterpolator(controlInterpolator)
+      .withEndAction(() -> captureFlashView.animate()
+        .alpha(0.0f)
+        .setDuration(CAPTURE_FLASH_OUT_MS)
+        .setInterpolator(controlInterpolator)
+        .withEndAction(() -> captureFlashView.setVisibility(View.GONE))
+        .start())
+      .start();
+  }
+
+  /** Shows or hides the processing state without blocking the Activity transition. */
+  private void setProcessingOverlayVisible(boolean visible) {
+    if (processingOverlay == null) {
+      return;
+    }
+
+    processingOverlay.animate().cancel();
+    if (visible) {
+      processingOverlay.setVisibility(View.VISIBLE);
+      processingOverlay.animate()
+        .alpha(1.0f)
+        .setDuration(120L)
+        .setInterpolator(controlInterpolator)
+        .start();
+      return;
+    }
+
+    processingOverlay.animate()
+      .alpha(0.0f)
+      .setDuration(120L)
+      .setInterpolator(controlInterpolator)
+      .withEndAction(() -> processingOverlay.setVisibility(View.GONE))
+      .start();
+  }
+
+  /** Creates a rounded drawable used by camera controls. */
+  private GradientDrawable createRoundedBackground(int fillColor, int strokeColor, int radiusDp, int strokeWidthDp) {
+    GradientDrawable drawable = new GradientDrawable();
+    drawable.setShape(GradientDrawable.RECTANGLE);
+    drawable.setColor(fillColor);
+    drawable.setCornerRadius(dp(radiusDp));
+    drawable.setStroke(dp(strokeWidthDp), strokeColor);
+    return drawable;
+  }
+
+  /** Creates a circular drawable used by the shutter control. */
+  private GradientDrawable createOvalBackground(int fillColor, int strokeColor, int strokeWidthDp) {
+    GradientDrawable drawable = new GradientDrawable();
+    drawable.setShape(GradientDrawable.OVAL);
+    drawable.setColor(fillColor);
+    if (strokeWidthDp > 0) {
+      drawable.setStroke(dp(strokeWidthDp), strokeColor);
+    }
+    return drawable;
+  }
+
+  /** Creates a vertical gradient drawable for camera chrome overlays. */
+  private GradientDrawable createVerticalGradient(
+    int startColor,
+    int endColor,
+    GradientDrawable.Orientation orientation
+  ) {
+    return new GradientDrawable(orientation, new int[] { startColor, endColor });
+  }
+
+  /** Creates a rounded ripple drawable for top controls on modern Android. */
+  private RippleDrawable createRippleDrawable(int rippleColor, int radiusDp) {
+    return new RippleDrawable(
+      ColorStateList.valueOf(rippleColor),
+      null,
+      createRoundedBackground(Color.WHITE, 0x00000000, radiusDp, 0)
+    );
+  }
+
+  /** Creates a circular ripple drawable for the shutter on modern Android. */
+  private RippleDrawable createOvalRippleDrawable(int rippleColor) {
+    return new RippleDrawable(
+      ColorStateList.valueOf(rippleColor),
+      null,
+      createOvalBackground(Color.WHITE, 0x00000000, 0)
+    );
+  }
+
+  /** Starts CameraX provider acquisition and binds preview when ready. */
+  private void startCameraProvider() {
+    logDebug("Requesting CameraX provider");
+    ListenableFuture<ProcessCameraProvider> providerFuture = ProcessCameraProvider.getInstance(this);
+    providerFuture.addListener(() -> handleCameraProviderReady(providerFuture), mainExecutor);
+  }
+
+  /** Handles the asynchronous CameraX provider result. */
+  private void handleCameraProviderReady(ListenableFuture<ProcessCameraProvider> providerFuture) {
+    if (resultSettled.get()) {
+      return;
+    }
+    try {
+      cameraProvider = providerFuture.get();
+      logDebug("CameraX provider ready");
+      selectAvailableLens();
+      bindCameraUseCases();
+    } catch (InterruptedException error) {
+      Thread.currentThread().interrupt();
+      logError("CameraX provider startup interrupted", error);
+      finishWithError(SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE, "Camera startup was interrupted.");
+    } catch (ExecutionException | CameraInfoUnavailableException | RuntimeException error) {
+      logError("CameraX provider startup failed", error);
+      finishWithError(SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE, "Could not start the in-app camera.");
+    }
+  }
+
+  /** Selects the restored lens when available, otherwise falls back to any available camera. */
+  private void selectAvailableLens() throws CameraInfoUnavailableException {
+    if (hasCameraWithLens(lensFacing)) {
+      logDebug("Using restored/requested lens: " + lensFacing);
+      return;
+    }
+    if (hasCameraWithLens(CameraSelector.LENS_FACING_BACK)) {
+      lensFacing = CameraSelector.LENS_FACING_BACK;
+      logDebug("Falling back to back camera");
+      return;
+    }
+    if (hasCameraWithLens(CameraSelector.LENS_FACING_FRONT)) {
+      lensFacing = CameraSelector.LENS_FACING_FRONT;
+      logDebug("Falling back to front camera");
+      return;
+    }
+    throw new CameraInfoUnavailableException("No available camera found.");
+  }
+
+  /** Binds Preview and ImageCapture to this Activity lifecycle. */
+  private void bindCameraUseCases() {
+    if (cameraProvider == null || previewView == null || resultSettled.get()) {
+      return;
+    }
+
+    try {
+      int targetRotation = getTargetRotation();
+      Preview preview = new Preview.Builder()
+        .setTargetRotation(targetRotation)
+        .build();
+      ImageCapture nextImageCapture = new ImageCapture.Builder()
+        .setCaptureMode(ImageCapture.CAPTURE_MODE_MINIMIZE_LATENCY)
+        .setResolutionSelector(createCaptureResolutionSelector())
+        .setTargetRotation(targetRotation)
+        .build();
+
+      cameraProvider.unbindAll();
+      camera = null;
+      imageCapture = null;
+      camera = cameraProvider.bindToLifecycle(this, createCameraSelector(lensFacing), preview, nextImageCapture);
+      preview.setSurfaceProvider(previewView.getSurfaceProvider());
+      imageCapture = nextImageCapture;
+      applyZoomToBoundCamera();
+      logDebug("CameraX use cases bound: lensFacing=" + lensFacing + ", targetRotation=" + targetRotation);
+      updateControlState(true);
+    } catch (RuntimeException error) {
+      logError("Could not bind CameraX use cases", error);
+      finishWithError(SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE, "Could not bind the in-app camera.");
+    }
+  }
+
+  /** Toggles between front and back cameras when both lenses are available. */
+  private void switchCamera() {
+    if (!canSwitchCamera() || captureInProgress.get()) {
+      return;
+    }
+    lensFacing = lensFacing == CameraSelector.LENS_FACING_BACK
+      ? CameraSelector.LENS_FACING_FRONT
+      : CameraSelector.LENS_FACING_BACK;
+    logDebug("Switching camera: nextLensFacing=" + lensFacing);
+    zoomRatio = DEFAULT_ZOOM_RATIO;
+    updateControlState(false);
+    bindCameraUseCases();
+  }
+
+  /** Applies the persisted zoom ratio after CameraX binds or rebinds a camera. */
+  private void applyZoomToBoundCamera() {
+    Camera activeCamera = camera;
+    if (activeCamera == null) {
+      logWarn("CameraX zoom apply skipped: activeCamera=null");
+      return;
+    }
+    ZoomState zoomState = activeCamera.getCameraInfo().getZoomState().getValue();
+    if (!isUsableZoomState(zoomState)) {
+      logWarn("CameraX zoom apply skipped: unusable zoomState=" + zoomState);
+      zoomRatio = DEFAULT_ZOOM_RATIO;
+      return;
+    }
+    float nextZoomRatio = clampZoomRatio(zoomRatio, zoomState.getMinZoomRatio(), zoomState.getMaxZoomRatio());
+    zoomRatio = nextZoomRatio;
+    activeCamera.getCameraControl().setZoomRatio(nextZoomRatio);
+    logDebug(
+      "CameraX zoom applied after bind: zoomRatio=" + nextZoomRatio +
+        ", min=" + zoomState.getMinZoomRatio() +
+        ", max=" + zoomState.getMaxZoomRatio()
+    );
+  }
+
+  /** Applies a pinch scale factor to the active CameraX zoom ratio. */
+  private boolean handleZoomScale(float scaleFactor) {
+    Camera activeCamera = camera;
+    if (!canHandleZoomGesture()) {
+      logWarn(
+        "CameraX zoom scale ignored: canHandle=false, camera=" + activeCamera +
+          ", showingPreview=" + showingPreview +
+          ", captureInProgress=" + captureInProgress.get() +
+          ", resultSettled=" + resultSettled.get()
+      );
+      return false;
+    }
+    if (activeCamera == null || scaleFactor <= 0.0f) {
+      logWarn("CameraX zoom scale ignored: camera=" + activeCamera + ", scaleFactor=" + scaleFactor);
+      return false;
+    }
+
+    ZoomState zoomState = activeCamera.getCameraInfo().getZoomState().getValue();
+    if (!isUsableZoomState(zoomState)) {
+      logWarn("CameraX zoom scale ignored: unusable zoomState=" + zoomState);
+      return false;
+    }
+
+    float currentZoomRatio = zoomState.getZoomRatio();
+    float nextZoomRatio = clampZoomRatio(
+      currentZoomRatio * scaleFactor,
+      zoomState.getMinZoomRatio(),
+      zoomState.getMaxZoomRatio()
+    );
+    if (Math.abs(nextZoomRatio - currentZoomRatio) < MIN_ZOOM_STEP_DELTA) {
+      return false;
+    }
+
+    zoomRatio = nextZoomRatio;
+    activeCamera.getCameraControl().setZoomRatio(nextZoomRatio);
+    return true;
+  }
+
+  /** Checks whether the live preview should consume touch events for zoom. */
+  private boolean canHandleZoomGesture() {
+    return !showingPreview && !captureInProgress.get() && !resultSettled.get();
+  }
+
+  /** Logs the first useful touch signals that should start a pinch gesture. */
+  private void logZoomTouchEvent(MotionEvent event, boolean canHandleZoom) {
+    if (event == null || event.getPointerCount() < ZOOM_TOUCH_LOG_POINTER_COUNT) {
+      return;
+    }
+    int action = event.getActionMasked();
+    if (action != MotionEvent.ACTION_POINTER_DOWN) {
+      return;
+    }
+    logDebug(
+      "CameraX zoom touch: action=" + motionActionToString(action) +
+        ", pointers=" + event.getPointerCount() +
+        ", canHandle=" + canHandleZoom +
+        ", detectorInProgress=" + (zoomGestureDetector != null && zoomGestureDetector.isInProgress())
+    );
+  }
+
+  /** Logs the current CameraX zoom range when a pinch gesture starts. */
+  private void logZoomGestureBegin() {
+    ZoomState zoomState = camera == null ? null : camera.getCameraInfo().getZoomState().getValue();
+    if (!isUsableZoomState(zoomState)) {
+      logWarn("CameraX zoom gesture begin: unusable zoomState=" + zoomState + ", camera=" + camera);
+      return;
+    }
+    logDebug(
+      "CameraX zoom gesture begin: current=" + zoomState.getZoomRatio() +
+        ", min=" + zoomState.getMinZoomRatio() +
+        ", max=" + zoomState.getMaxZoomRatio()
+    );
+  }
+
+  /** Converts MotionEvent action constants into readable debug labels. */
+  private String motionActionToString(int action) {
+    switch (action) {
+      case MotionEvent.ACTION_DOWN:
+        return "DOWN";
+      case MotionEvent.ACTION_POINTER_DOWN:
+        return "POINTER_DOWN";
+      case MotionEvent.ACTION_MOVE:
+        return "MOVE";
+      case MotionEvent.ACTION_POINTER_UP:
+        return "POINTER_UP";
+      case MotionEvent.ACTION_UP:
+        return "UP";
+      case MotionEvent.ACTION_CANCEL:
+        return "CANCEL";
+      default:
+        return String.valueOf(action);
+    }
+  }
+
+  /** Checks whether CameraX has reported a usable zoom range for this lens. */
+  private boolean isUsableZoomState(ZoomState zoomState) {
+    return zoomState != null &&
+      zoomState.getMinZoomRatio() > 0.0f &&
+      zoomState.getMaxZoomRatio() >= zoomState.getMinZoomRatio();
+  }
+
+  /** Clamps a zoom ratio to the active lens range reported by CameraX. */
+  private float clampZoomRatio(float value, float minZoomRatio, float maxZoomRatio) {
+    return Math.max(minZoomRatio, Math.min(maxZoomRatio, value));
+  }
+
+  /** Captures a single JPEG to SDK cache storage. */
+  private void capturePhoto() {
+    ImageCapture capture = imageCapture;
+    if (capture == null || !captureInProgress.compareAndSet(false, true)) {
+      logWarn("capturePhoto ignored: capture=" + capture + ", captureInProgress=" + captureInProgress.get());
+      return;
+    }
+
+    logDebug("capturePhoto started");
+    updateControlState(false);
+    playCaptureFeedback();
+    setProcessingOverlayVisible(true);
+    File photoFile;
+    try {
+      photoFile = createOutputFile();
+      pendingCapturePhotoFile = photoFile;
+      logDebug("Capture output file created: " + photoFile.getAbsolutePath());
+    } catch (IOException error) {
+      logError("Could not create capture output file", error);
+      captureInProgress.set(false);
+      pendingCapturePhotoFile = null;
+      finishWithError(SagepilotInAppCameraModule.ERROR_ENCODE_FAILED, "Could not create a temporary camera file.");
+      return;
+    }
+
+    capture.setTargetRotation(getTargetRotation());
+    ImageCapture.Metadata metadata = new ImageCapture.Metadata();
+    metadata.setReversedHorizontal(false);
+    metadata.setReversedVertical(false);
+    ImageCapture.OutputFileOptions outputOptions = new ImageCapture.OutputFileOptions.Builder(photoFile)
+      .setMetadata(metadata)
+      .build();
+    capture.takePicture(outputOptions, cameraExecutor, new ImageCapture.OnImageSavedCallback() {
+      /** Handles a successful CameraX file save. */
+      @Override
+      public void onImageSaved(ImageCapture.OutputFileResults outputFileResults) {
+        logDebug("CameraX image saved: bytes=" + photoFile.length());
+        runOnUiThread(() -> showCapturedPreview(photoFile));
+      }
+
+      /** Handles CameraX capture failures and removes the temporary file. */
+      @Override
+      public void onError(ImageCaptureException exception) {
+        logError("CameraX capture failed", exception);
+        deleteQuietly(photoFile);
+        pendingCapturePhotoFile = null;
+        captureInProgress.set(false);
+        runOnUiThread(() -> finishWithError(
+          SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE,
+          "Could not capture a photo."
+        ));
+      }
+    });
+  }
+
+  /** Shows the saved JPEG and waits for the customer to retake or confirm. */
+  private void showCapturedPreview(File photoFile) {
+    if (resultSettled.get()) {
+      deleteQuietly(photoFile);
+      return;
+    }
+
+    logDebug("Showing captured photo preview: " + photoFile.getAbsolutePath());
+    pendingCapturePhotoFile = null;
+    pendingPreviewPhotoFile = photoFile;
+    showingPreview = true;
+    captureInProgress.set(false);
+    setProcessingOverlayVisible(false);
+    if (capturedPreviewView != null) {
+      capturedPreviewView.setImageURI(Uri.fromFile(photoFile));
+      capturedPreviewView.setVisibility(View.VISIBLE);
+      capturedPreviewView.animate()
+        .alpha(1.0f)
+        .setDuration(140L)
+        .setInterpolator(controlInterpolator)
+        .start();
+    }
+    if (previewView != null) {
+      previewView.setVisibility(View.INVISIBLE);
+    }
+    if (cameraTitle != null) {
+      cameraTitle.setText("Preview");
+    }
+    animatePreviewActions(true);
+    updateControlState(true);
+  }
+
+  /** Discards the current preview and returns to the live camera. */
+  private void retakePhoto() {
+    if (!showingPreview || resultSettled.get()) {
+      return;
+    }
+
+    logDebug("Retaking captured photo");
+    discardPendingPreviewFile();
+    showingPreview = false;
+    if (capturedPreviewView != null) {
+      capturedPreviewView.animate()
+        .alpha(0.0f)
+        .setDuration(120L)
+        .setInterpolator(controlInterpolator)
+        .withEndAction(() -> {
+          capturedPreviewView.setImageDrawable(null);
+          capturedPreviewView.setVisibility(View.GONE);
+        })
+        .start();
+    }
+    if (previewView != null) {
+      previewView.setVisibility(View.VISIBLE);
+    }
+    if (cameraTitle != null) {
+      cameraTitle.setText("Camera");
+    }
+    animatePreviewActions(false);
+    updateControlState(true);
+  }
+
+  /** Confirms the previewed photo and runs the existing image-processing pipeline. */
+  private void acceptPreviewPhoto() {
+    File photoFile = pendingPreviewPhotoFile;
+    if (!showingPreview || photoFile == null || resultSettled.get()) {
+      return;
+    }
+
+    logDebug("Accepted captured photo preview");
+    showingPreview = false;
+    pendingPreviewPhotoFile = null;
+    animatePreviewActions(false);
+    updateControlState(false);
+    setProcessingOverlayVisible(true);
+    cameraExecutor.execute(() -> handleImageSaved(photoFile));
+  }
+
+  /** Deletes and clears the currently previewed photo file. */
+  private void discardPendingPreviewFile() {
+    File photoFile = pendingPreviewPhotoFile;
+    pendingPreviewPhotoFile = null;
+    if (photoFile != null) {
+      deleteQuietly(photoFile);
+    }
+  }
+
+  /** Deletes and clears the in-flight CameraX output file. */
+  private void discardPendingCaptureFile() {
+    File photoFile = pendingCapturePhotoFile;
+    pendingCapturePhotoFile = null;
+    if (photoFile != null) {
+      deleteQuietly(photoFile);
+    }
+  }
+
+  /** Fades the preview action row in or out. */
+  private void animatePreviewActions(boolean visible) {
+    if (previewActionBar == null) {
+      return;
+    }
+
+    previewActionBar.animate().cancel();
+    if (visible) {
+      previewActionBar.setVisibility(View.VISIBLE);
+      previewActionBar.animate()
+        .alpha(1.0f)
+        .setDuration(140L)
+        .setInterpolator(controlInterpolator)
+        .start();
+      return;
+    }
+
+    previewActionBar.animate()
+      .alpha(0.0f)
+      .setDuration(120L)
+      .setInterpolator(controlInterpolator)
+      .withEndAction(() -> previewActionBar.setVisibility(View.GONE))
+      .start();
+  }
+
+  /** Normalizes a captured JPEG and returns it through the NativeModule result contract. */
+  private void handleImageSaved(File photoFile) {
+    File processedFile = null;
+    try {
+      logDebug("Processing captured image: sourceBytes=" + photoFile.length());
+      processedFile = createProcessedOutputFile();
+      SagepilotInAppCameraImageProcessor.ProcessedImage processedImage =
+        new SagepilotInAppCameraImageProcessor(imageMaxDimension, imageQuality, imageMaxFileSizeBytes)
+          .process(photoFile, processedFile);
+      String fileName = createResultFileName();
+      logDebug(
+        "Image processed: resultFileName=" + fileName +
+          ", processedBytes=" + processedImage.sizeBytes +
+          ", base64Length=" + processedImage.dataBase64.length()
+      );
+      runOnUiThread(() -> finishWithSuccess(fileName, processedImage.sizeBytes, processedImage.dataBase64));
+    } catch (SagepilotInAppCameraImageProcessor.ImageTooLargeException error) {
+      logWarn("Processed image exceeded size cap", error);
+      runOnUiThread(() -> finishWithError(
+        SagepilotInAppCameraModule.ERROR_FILE_TOO_LARGE,
+        "Image is too large."
+      ));
+    } catch (IOException | RuntimeException error) {
+      logError("Image processing failed", error);
+      runOnUiThread(() -> finishWithError(
+        SagepilotInAppCameraModule.ERROR_ENCODE_FAILED,
+        "The photo could not be processed."
+      ));
+    } catch (OutOfMemoryError error) {
+      logError("Image processing OOM", error);
+      runOnUiThread(() -> finishWithError(
+        SagepilotInAppCameraModule.ERROR_ENCODE_FAILED,
+        "The photo is too large to process."
+      ));
+    } finally {
+      deleteQuietly(photoFile);
+      deleteQuietly(processedFile);
+      captureInProgress.set(false);
+    }
+  }
+
+  /** Creates a temporary app-cache file for CameraX output. */
+  private File createOutputFile() throws IOException {
+    File directory = getCameraCacheDirectory();
+    if (!directory.exists() && !directory.mkdirs()) {
+      throw new IOException("Could not create camera cache directory.");
+    }
+    return File.createTempFile(PHOTO_FILE_PREFIX, PHOTO_FILE_EXTENSION, directory);
+  }
+
+  /** Creates a temporary app-cache file for normalized JPEG output. */
+  private File createProcessedOutputFile() throws IOException {
+    File directory = getCameraCacheDirectory();
+    if (!directory.exists() && !directory.mkdirs()) {
+      throw new IOException("Could not create camera cache directory.");
+    }
+    return File.createTempFile(PROCESSED_PHOTO_FILE_PREFIX, PHOTO_FILE_EXTENSION, directory);
+  }
+
+  /** Creates a stable customer-facing file name for the captured image. */
+  private String createResultFileName() {
+    return String.format(Locale.US, "sagepilot-photo-%d.jpg", System.currentTimeMillis());
+  }
+
+  /** Deletes stale SDK camera cache files from prior interrupted captures. */
+  private void cleanupStaleCameraFiles() {
+    File directory = getCameraCacheDirectory();
+    File[] files = directory.listFiles();
+    if (files == null) {
+      return;
+    }
+    for (File file : files) {
+      if (file.isFile() && file.getName().startsWith(PHOTO_FILE_PREFIX) && !shouldKeepCameraFile(file)) {
+        deleteQuietly(file);
+      }
+    }
+  }
+
+  /** Checks whether cleanup should preserve a temp file restored from saved state. */
+  private boolean shouldKeepCameraFile(File file) {
+    return sameFile(file, pendingCapturePhotoFile) || sameFile(file, pendingPreviewPhotoFile);
+  }
+
+  /** Compares two files by absolute path without touching disk. */
+  private boolean sameFile(File first, File second) {
+    return first != null && second != null && first.getAbsolutePath().equals(second.getAbsolutePath());
+  }
+
+  /** Returns the SDK camera cache directory. */
+  private File getCameraCacheDirectory() {
+    return new File(getCacheDir(), CAMERA_CACHE_DIRECTORY_NAME);
+  }
+
+  /** Deletes a temporary file without surfacing cleanup failures to the customer. */
+  private void deleteQuietly(File file) {
+    if (file != null && file.exists()) {
+      file.delete();
+    }
+  }
+
+  /** Finishes the Activity with the picked-file payload expected by the NativeModule. */
+  private void finishWithSuccess(String fileName, long size, String dataBase64) {
+    if (!resultSettled.compareAndSet(false, true)) {
+      return;
+    }
+
+    String resultId = SagepilotInAppCameraResultStore.put(
+      this,
+      new SagepilotInAppCameraResultStore.PickedImage(fileName, IMAGE_MIME_TYPE, size, dataBase64)
+    );
+    logDebug(
+      "Finishing with success: resultId=" + resultId +
+        ", fileName=" + fileName +
+        ", size=" + size +
+        ", base64Length=" + dataBase64.length()
+    );
+    Intent data = new Intent();
+    data.putExtra(SagepilotInAppCameraModule.EXTRA_RESULT_ID, resultId);
+    data.putExtra(SagepilotInAppCameraModule.EXTRA_RESULT_FILE_NAME, fileName);
+    data.putExtra(SagepilotInAppCameraModule.EXTRA_RESULT_MIME_TYPE, IMAGE_MIME_TYPE);
+    data.putExtra(SagepilotInAppCameraModule.EXTRA_RESULT_SIZE, size);
+    setResult(Activity.RESULT_OK, data);
+    finish();
+  }
+
+  /** Finishes the Activity as a customer cancellation. */
+  private void finishWithCancel() {
+    if (!resultSettled.compareAndSet(false, true)) {
+      return;
+    }
+    logDebug("Finishing with cancel");
+    discardPendingCaptureFile();
+    discardPendingPreviewFile();
+    setResult(Activity.RESULT_CANCELED);
+    finish();
+  }
+
+  /** Finishes the Activity with a stable SDK file-picker error code. */
+  private void finishWithError(String code, String message) {
+    if (!resultSettled.compareAndSet(false, true)) {
+      return;
+    }
+
+    logWarn("Finishing with error: code=" + code + ", message=" + message);
+    discardPendingCaptureFile();
+    discardPendingPreviewFile();
+    Intent data = new Intent();
+    data.putExtra(SagepilotInAppCameraModule.EXTRA_ERROR_CODE, code);
+    data.putExtra(SagepilotInAppCameraModule.EXTRA_ERROR_MESSAGE, message);
+    setResult(SagepilotInAppCameraModule.RESULT_ERROR, data);
+    finish();
+  }
+
+  /** Updates enabled and visible states for capture controls. */
+  private void updateControlState(boolean cameraReady) {
+    boolean decisionAllowed = showingPreview && !captureInProgress.get() && !resultSettled.get();
+    boolean captureAllowed = cameraReady && !showingPreview && !captureInProgress.get() && !resultSettled.get();
+    boolean captureActive = captureInProgress.get() && !resultSettled.get();
+    if (shutterButton != null) {
+      shutterButton.setVisibility(showingPreview ? View.GONE : View.VISIBLE);
+      shutterButton.setEnabled(captureAllowed);
+      shutterButton.setAlpha(captureAllowed || captureActive ? 1.0f : 0.48f);
+    }
+    if (switchButton != null) {
+      boolean switchAllowed = captureAllowed && canSwitchCamera();
+      switchButton.setVisibility(!showingPreview && canSwitchCamera() ? View.VISIBLE : View.GONE);
+      switchButton.setEnabled(switchAllowed);
+      switchButton.setAlpha(switchAllowed ? 1.0f : 0.45f);
+    }
+    if (retakeButton != null) {
+      retakeButton.setEnabled(decisionAllowed);
+      retakeButton.setAlpha(decisionAllowed ? 1.0f : 0.55f);
+    }
+    if (usePhotoButton != null) {
+      usePhotoButton.setEnabled(decisionAllowed);
+      usePhotoButton.setAlpha(decisionAllowed ? 1.0f : 0.55f);
+    }
+    if (closeButton != null) {
+      closeButton.setEnabled(!resultSettled.get());
+    }
+  }
+
+  /** Checks whether both front and back cameras are available for switching. */
+  private boolean canSwitchCamera() {
+    try {
+      return cameraProvider != null &&
+        hasCameraWithLens(CameraSelector.LENS_FACING_BACK) &&
+        hasCameraWithLens(CameraSelector.LENS_FACING_FRONT);
+    } catch (CameraInfoUnavailableException error) {
+      return false;
+    }
+  }
+
+  /** Checks whether CameraX can provide a camera for a given lens facing value. */
+  private boolean hasCameraWithLens(int nextLensFacing) throws CameraInfoUnavailableException {
+    return cameraProvider != null && cameraProvider.hasCamera(createCameraSelector(nextLensFacing));
+  }
+
+  /** Creates a CameraX selector for a lens facing value. */
+  private CameraSelector createCameraSelector(int nextLensFacing) {
+    return new CameraSelector.Builder().requireLensFacing(nextLensFacing).build();
+  }
+
+  /** Creates a bounded capture selector so high-MP sensors do not emit full-sensor JPEGs. */
+  private ResolutionSelector createCaptureResolutionSelector() {
+    int boundWidth = Math.max(1, imageMaxDimension);
+    int boundHeight = Math.max(1, Math.round(boundWidth * 0.75f));
+    ResolutionStrategy resolutionStrategy = new ResolutionStrategy(
+      new Size(boundWidth, boundHeight),
+      ResolutionStrategy.FALLBACK_RULE_CLOSEST_LOWER_THEN_HIGHER
+    );
+    return new ResolutionSelector.Builder()
+      .setResolutionStrategy(resolutionStrategy)
+      .build();
+  }
+
+  /** Reads the current display rotation for Preview and ImageCapture. */
+  private int getTargetRotation() {
+    if (previewView != null && previewView.getDisplay() != null) {
+      return previewView.getDisplay().getRotation();
+    }
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R && getDisplay() != null) {
+      return getDisplay().getRotation();
+    }
+    return getLegacyDisplayRotation();
+  }
+
+  /** Reads display rotation on older Android releases. */
+  @SuppressWarnings("deprecation")
+  private int getLegacyDisplayRotation() {
+    if (getWindowManager() != null && getWindowManager().getDefaultDisplay() != null) {
+      return getWindowManager().getDefaultDisplay().getRotation();
+    }
+    return Surface.ROTATION_0;
+  }
+
+  /** Converts density-independent pixels to raw pixels for programmatic layout. */
+  private int dp(int value) {
+    return Math.round(value * getResources().getDisplayMetrics().density);
+  }
+
+  /** 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);
+  }
+}