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

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

@@ -0,0 +1,1419 @@
+package ai.sagepilot.reactnativecameraaddon;
+
+import android.Manifest;
+import android.app.Activity;
+import android.app.Dialog;
+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.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.view.Window;
+import android.view.WindowManager;
+import android.view.animation.DecelerateInterpolator;
+import android.widget.FrameLayout;
+import android.widget.ImageView;
+import android.widget.LinearLayout;
+import android.widget.TextView;
+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.core.resolutionselector.ResolutionSelector;
+import androidx.camera.core.resolutionselector.ResolutionStrategy;
+import androidx.camera.lifecycle.ProcessCameraProvider;
+import androidx.camera.view.PreviewView;
+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 androidx.lifecycle.LifecycleOwner;
+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;
+
+final class SagepilotInAppCameraOverlay {
+  private static final String TAG = "SagepilotInAppCamera";
+  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 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 Activity activity;
+  private final LifecycleOwner lifecycleOwner;
+  private final Listener listener;
+  private final int imageMaxDimension;
+  private final int imageQuality;
+  private final long imageMaxFileSizeBytes;
+  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 Dialog overlayDialog;
+  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 OnBackPressedCallback backCallback;
+  private int previousWindowFlags;
+  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 a CameraX overlay bound to the host Activity instead of a separate Activity. */
+  SagepilotInAppCameraOverlay(
+    Activity activity,
+    int imageMaxDimension,
+    int imageQuality,
+    long imageMaxFileSizeBytes,
+    Listener listener
+  ) {
+    if (!(activity instanceof LifecycleOwner)) {
+      throw new IllegalArgumentException("Host Activity must implement LifecycleOwner.");
+    }
+    this.activity = activity;
+    this.lifecycleOwner = (LifecycleOwner) activity;
+    this.imageMaxDimension = Math.max(1, imageMaxDimension);
+    this.imageQuality = Math.max(0, Math.min(100, imageQuality));
+    this.imageMaxFileSizeBytes = Math.max(0L, imageMaxFileSizeBytes);
+    this.listener = listener;
+  }
+
+  /** Attaches the camera overlay above the React Native host view and starts CameraX. */
+  void show() {
+    if (!hasCameraPermission()) {
+      throw new IllegalStateException("Camera permission is required before showing the overlay.");
+    }
+
+    mainExecutor = ContextCompat.getMainExecutor(activity);
+    cameraExecutor = Executors.newSingleThreadExecutor();
+    configureWindowChrome();
+    installBackHandler();
+    cleanupStaleCameraFiles();
+    createCameraLayout();
+    attachRootView();
+    startCameraProvider();
+  }
+
+  /** Tears down the overlay without resolving the customer-facing picker promise. */
+  void destroySilently() {
+    resultSettled.set(true);
+    closeOverlay(true);
+  }
+
+  /** Tears down the overlay from any native module thread by hopping to the host UI thread. */
+  void destroySilentlyOnUiThread() {
+    activity.runOnUiThread(this::destroySilently);
+  }
+
+  /** Checks whether this overlay has not yet settled a customer result. */
+  boolean isActive() {
+    return !resultSettled.get();
+  }
+
+  /** Checks the runtime camera permission before touching CameraX. */
+  private boolean hasCameraPermission() {
+    return ContextCompat.checkSelfPermission(activity, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED;
+  }
+
+  /** Configures window flags needed while the camera overlay is visible. */
+  private void configureWindowChrome() {
+    Window window = activity.getWindow();
+    if (window == null) {
+      return;
+    }
+    previousWindowFlags = window.getAttributes().flags;
+    window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+  }
+
+  /** Restores window flags that were changed for the camera overlay. */
+  private void restoreWindowChrome() {
+    Window window = activity.getWindow();
+    if (window == null) {
+      return;
+    }
+    if ((previousWindowFlags & WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON) == 0) {
+      window.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+    }
+  }
+
+  /** Installs AndroidX back handling so hardware back maps to picker cancellation. */
+  private void installBackHandler() {
+    if (!(activity instanceof ComponentActivity)) {
+      return;
+    }
+    backCallback = new OnBackPressedCallback(true) {
+      /** Cancels the in-process camera overlay when the customer presses back. */
+      @Override
+      public void handleOnBackPressed() {
+        finishWithCancel();
+      }
+    };
+    ((ComponentActivity) activity).getOnBackPressedDispatcher().addCallback(lifecycleOwner, backCallback);
+  }
+
+  /** Builds the full-screen preview and minimal capture controls. */
+  private void createCameraLayout() {
+    rootView = new FrameLayout(activity);
+    rootView.setBackgroundColor(Color.BLACK);
+    rootView.setClipToPadding(false);
+    rootView.setClickable(true);
+    rootView.setFocusable(true);
+
+    previewView = new PreviewView(activity);
+    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();
+    updateControlState(false);
+  }
+
+  /** Installs pinch-to-zoom handling on the live CameraX preview. */
+  private void installZoomGestureHandler() {
+    if (previewView == null) {
+      return;
+    }
+    logDebug("Overlay installing CameraX zoom gesture handler");
+    zoomGestureDetector = new ScaleGestureDetector(activity, 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("Overlay 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;
+    });
+  }
+
+  /** Attaches the overlay root in a top-level app dialog above React Native Modal windows. */
+  private void attachRootView() {
+    if (rootView == null) {
+      throw new IllegalStateException("Could not attach the camera overlay.");
+    }
+
+    overlayDialog = new Dialog(activity, android.R.style.Theme_Black_NoTitleBar_Fullscreen);
+    overlayDialog.setContentView(rootView);
+    overlayDialog.setCanceledOnTouchOutside(false);
+    overlayDialog.setOnCancelListener(dialog -> finishWithCancel());
+    Window window = overlayDialog.getWindow();
+    if (window != null) {
+      window.setBackgroundDrawableResource(android.R.color.black);
+      window.clearFlags(WindowManager.LayoutParams.FLAG_DIM_BEHIND);
+      window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+      WindowCompat.setDecorFitsSystemWindows(window, false);
+    }
+
+    overlayDialog.show();
+    Window shownWindow = overlayDialog.getWindow();
+    if (shownWindow != null) {
+      shownWindow.setLayout(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT);
+    }
+    ViewCompat.requestApplyInsets(rootView);
+    rootView.bringToFront();
+    rootView.requestFocus();
+    logDebug("Overlay dialog attached above host window");
+  }
+
+  /** Creates the dark top gradient that keeps controls legible over the preview. */
+  private View createTopScrim() {
+    View scrim = new View(activity);
+    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(activity);
+    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(activity);
+    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 overlay 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(activity);
+    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(activity);
+    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(activity);
+    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(activity);
+    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(activity);
+    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(activity);
+    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(activity);
+    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(activity);
+    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 capture feedback. */
+  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("Overlay requesting CameraX provider");
+    ListenableFuture<ProcessCameraProvider> providerFuture = ProcessCameraProvider.getInstance(activity);
+    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("Overlay CameraX provider ready");
+      selectAvailableLens();
+      bindCameraUseCases();
+    } catch (InterruptedException error) {
+      Thread.currentThread().interrupt();
+      logError("Overlay CameraX provider startup interrupted", error);
+      finishWithError(SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE, "Camera startup was interrupted.", error);
+    } catch (ExecutionException | CameraInfoUnavailableException | RuntimeException error) {
+      logError("Overlay CameraX provider startup failed", error);
+      finishWithError(SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE, "Could not start the in-app camera.", error);
+    }
+  }
+
+  /** Selects the restored lens when available, otherwise falls back to any available camera. */
+  private void selectAvailableLens() throws CameraInfoUnavailableException {
+    if (hasCameraWithLens(lensFacing)) {
+      logDebug("Overlay using requested lens: " + lensFacing);
+      return;
+    }
+    if (hasCameraWithLens(CameraSelector.LENS_FACING_BACK)) {
+      lensFacing = CameraSelector.LENS_FACING_BACK;
+      logDebug("Overlay falling back to back camera");
+      return;
+    }
+    if (hasCameraWithLens(CameraSelector.LENS_FACING_FRONT)) {
+      lensFacing = CameraSelector.LENS_FACING_FRONT;
+      logDebug("Overlay falling back to front camera");
+      return;
+    }
+    throw new CameraInfoUnavailableException("No available camera found.");
+  }
+
+  /** Binds Preview and ImageCapture to the host 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(lifecycleOwner, createCameraSelector(lensFacing), preview, nextImageCapture);
+      preview.setSurfaceProvider(previewView.getSurfaceProvider());
+      imageCapture = nextImageCapture;
+      applyZoomToBoundCamera();
+      logDebug("Overlay CameraX use cases bound: lensFacing=" + lensFacing + ", targetRotation=" + targetRotation);
+      updateControlState(true);
+    } catch (RuntimeException error) {
+      logError("Overlay could not bind CameraX use cases", error);
+      finishWithError(SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE, "Could not bind the in-app camera.", error);
+    }
+  }
+
+  /** 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("Overlay 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("Overlay CameraX zoom apply skipped: activeCamera=null");
+      return;
+    }
+    ZoomState zoomState = activeCamera.getCameraInfo().getZoomState().getValue();
+    if (!isUsableZoomState(zoomState)) {
+      logWarn("Overlay 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(
+      "Overlay 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(
+        "Overlay 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("Overlay CameraX zoom scale ignored: camera=" + activeCamera + ", scaleFactor=" + scaleFactor);
+      return false;
+    }
+
+    ZoomState zoomState = activeCamera.getCameraInfo().getZoomState().getValue();
+    if (!isUsableZoomState(zoomState)) {
+      logWarn("Overlay 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(
+      "Overlay 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("Overlay CameraX zoom gesture begin: unusable zoomState=" + zoomState + ", camera=" + camera);
+      return;
+    }
+    logDebug(
+      "Overlay 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("Overlay capturePhoto ignored: capture=" + capture + ", captureInProgress=" + captureInProgress.get());
+      return;
+    }
+
+    logDebug("Overlay capturePhoto started");
+    updateControlState(false);
+    playCaptureFeedback();
+    setProcessingOverlayVisible(true);
+    File photoFile;
+    try {
+      photoFile = createOutputFile();
+      pendingCapturePhotoFile = photoFile;
+      logDebug("Overlay capture output file created: " + photoFile.getAbsolutePath());
+    } catch (IOException error) {
+      logError("Overlay could not create capture output file", error);
+      pendingCapturePhotoFile = null;
+      captureInProgress.set(false);
+      finishWithError(SagepilotInAppCameraModule.ERROR_ENCODE_FAILED, "Could not create a temporary camera file.", error);
+      return;
+    }
+
+    capture.setTargetRotation(getTargetRotation());
+    ImageCapture.OutputFileOptions outputOptions = new ImageCapture.OutputFileOptions.Builder(photoFile)
+      .build();
+    capture.takePicture(outputOptions, cameraExecutor, new ImageCapture.OnImageSavedCallback() {
+      /** Handles a successful CameraX file save. */
+      @Override
+      public void onImageSaved(ImageCapture.OutputFileResults outputFileResults) {
+        logDebug("Overlay CameraX image saved: bytes=" + photoFile.length());
+        activity.runOnUiThread(() -> showCapturedPreview(photoFile));
+      }
+
+      /** Handles CameraX capture failures and removes the temporary file. */
+      @Override
+      public void onError(ImageCaptureException exception) {
+        logError("Overlay CameraX capture failed", exception);
+        deleteQuietly(photoFile);
+        pendingCapturePhotoFile = null;
+        captureInProgress.set(false);
+        activity.runOnUiThread(() -> finishWithError(
+          SagepilotInAppCameraModule.ERROR_CAMERA_UNAVAILABLE,
+          "Could not capture a photo.",
+          exception
+        ));
+      }
+    });
+  }
+
+  /** 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("Overlay 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("Overlay 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 shared image-processing pipeline. */
+  private void acceptPreviewPhoto() {
+    File photoFile = pendingPreviewPhotoFile;
+    if (!showingPreview || photoFile == null || resultSettled.get()) {
+      return;
+    }
+
+    logDebug("Overlay 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 overlay listener. */
+  private void handleImageSaved(File photoFile) {
+    File processedFile = null;
+    try {
+      logDebug("Overlay processing captured image: sourceBytes=" + photoFile.length());
+      processedFile = createProcessedOutputFile();
+      SagepilotInAppCameraImageProcessor.ProcessedImage processedImage =
+        new SagepilotInAppCameraImageProcessor(imageMaxDimension, imageQuality, imageMaxFileSizeBytes)
+          .process(photoFile, processedFile);
+      String fileName = createResultFileName();
+      logDebug(
+        "Overlay image processed: resultFileName=" + fileName +
+          ", processedBytes=" + processedImage.sizeBytes +
+          ", base64Length=" + processedImage.dataBase64.length()
+      );
+      activity.runOnUiThread(() -> finishWithSuccess(fileName, processedImage.sizeBytes, processedImage.dataBase64));
+    } catch (SagepilotInAppCameraImageProcessor.ImageTooLargeException error) {
+      logWarn("Overlay processed image exceeded size cap", error);
+      activity.runOnUiThread(() -> finishWithError(
+        SagepilotInAppCameraModule.ERROR_FILE_TOO_LARGE,
+        "Image is too large.",
+        error
+      ));
+    } catch (IOException | RuntimeException error) {
+      logError("Overlay image processing failed", error);
+      activity.runOnUiThread(() -> finishWithError(
+        SagepilotInAppCameraModule.ERROR_ENCODE_FAILED,
+        "The photo could not be processed.",
+        error
+      ));
+    } catch (OutOfMemoryError error) {
+      logError("Overlay image processing OOM", error);
+      activity.runOnUiThread(() -> finishWithError(
+        SagepilotInAppCameraModule.ERROR_ENCODE_FAILED,
+        "The photo is too large to process.",
+        error
+      ));
+    } 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 overlay 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)) {
+        deleteQuietly(file);
+      }
+    }
+  }
+
+  /** Returns the SDK camera cache directory. */
+  private File getCameraCacheDirectory() {
+    return new File(activity.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();
+    }
+  }
+
+  /** Resolves the overlay with the picked-file payload expected by the NativeModule. */
+  private void finishWithSuccess(String fileName, long size, String dataBase64) {
+    if (!resultSettled.compareAndSet(false, true)) {
+      return;
+    }
+    listener.onSuccess(fileName, IMAGE_MIME_TYPE, size, dataBase64);
+    closeOverlay(false);
+  }
+
+  /** Resolves the overlay as a customer cancellation. */
+  private void finishWithCancel() {
+    if (!resultSettled.compareAndSet(false, true)) {
+      return;
+    }
+    logDebug("Overlay finishing with cancel");
+    listener.onCancel();
+    closeOverlay(true);
+  }
+
+  /** Rejects the overlay with a stable SDK file-picker error code. */
+  private void finishWithError(String code, String message, Throwable error) {
+    if (!resultSettled.compareAndSet(false, true)) {
+      return;
+    }
+
+    logWarn("Overlay finishing with error: code=" + code + ", message=" + message, error);
+    listener.onError(code, message, error);
+    closeOverlay(true);
+  }
+
+  /** Releases CameraX, removes the overlay view, and cleans up pending files. */
+  private void closeOverlay(boolean discardPendingFiles) {
+    if (backCallback != null) {
+      backCallback.remove();
+      backCallback = null;
+    }
+    if (cameraProvider != null) {
+      cameraProvider.unbindAll();
+      cameraProvider = null;
+    }
+    camera = null;
+    imageCapture = null;
+    if (cameraExecutor != null) {
+      cameraExecutor.shutdownNow();
+      cameraExecutor = null;
+    }
+    if (discardPendingFiles) {
+      discardPendingCaptureFile();
+      discardPendingPreviewFile();
+    }
+    if (rootView != null && rootView.getParent() instanceof ViewGroup) {
+      ((ViewGroup) rootView.getParent()).removeView(rootView);
+    }
+    if (overlayDialog != null) {
+      overlayDialog.setOnCancelListener(null);
+      overlayDialog.dismiss();
+      overlayDialog = null;
+    }
+    rootView = null;
+    restoreWindowChrome();
+  }
+
+  /** 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 && activity.getDisplay() != null) {
+      return activity.getDisplay().getRotation();
+    }
+    return getLegacyDisplayRotation();
+  }
+
+  /** Reads display rotation on older Android releases. */
+  @SuppressWarnings("deprecation")
+  private int getLegacyDisplayRotation() {
+    if (activity.getWindowManager() != null && activity.getWindowManager().getDefaultDisplay() != null) {
+      return activity.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 * activity.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);
+  }
+
+  interface Listener {
+    /** Resolves a processed image produced by the in-process overlay. */
+    void onSuccess(String fileName, String mimeType, long sizeBytes, String dataBase64);
+
+    /** Resolves a user cancellation from the in-process overlay. */
+    void onCancel();
+
+    /** Rejects an in-process overlay failure. */
+    void onError(String code, String message, Throwable error);
+  }
+}