@capgo/camera-preview 8.4.2 → 8.4.4

package/android/src/main/java/app/capgo/capacitor/camera/preview/CameraPreview.java

@@ -6,7 +6,11 @@ import static android.Manifest.permission.RECORD_AUDIO;
 import android.Manifest;
 import android.annotation.SuppressLint;
 import android.app.Activity;
+import android.app.KeyguardManager;
+import android.content.BroadcastReceiver;
+import android.content.Context;
 import android.content.Intent;
+import android.content.IntentFilter;
 import android.content.pm.ActivityInfo;
 import android.content.pm.PackageManager;
 import android.content.res.Configuration;
@@ -69,12 +73,19 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
 
     private final String pluginVersion = "";
 
+    @Override
+    public void load() {
+        registerScreenLockReceiver();
+    }
+
     @Override
     protected void handleOnPause() {
         super.handleOnPause();
+        activityPaused = true;
         if (cameraXView != null && cameraXView.isRunning()) {
             // Store the current configuration before stopping
             lastSessionConfig = cameraXView.getSessionConfig();
+            requestBarcodeScannerRestartAfterCameraResume();
             cameraXView.stopSession();
         }
     }
@@ -82,22 +93,25 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
     @Override
     protected void handleOnResume() {
         super.handleOnResume();
+        registerScreenLockReceiver();
+        activityPaused = false;
         if (lastSessionConfig != null) {
-            // Set to black to avoid flicker, transparent set later
-            if (lastSessionConfig.isToBack()) {
-                try {
-                    getBridge()
-                        .getActivity()
-                        .getWindow()
-                        .setBackgroundDrawable(new android.graphics.drawable.ColorDrawable(android.graphics.Color.BLACK));
-                    getBridge().getWebView().setBackgroundColor(android.graphics.Color.BLACK);
-                } catch (Exception ignored) {}
-            }
             // Recreate camera with last known configuration
-            if (cameraXView == null) {
+            if (cameraXView == null || !cameraXView.isRunning() || cameraXView.isStopping()) {
                 cameraXView = new CameraXView(getContext(), getBridge().getWebView());
                 cameraXView.setListener(this);
             }
+            if (lastSessionConfig.isToBack()) {
+                if (usesFullStackTransparentBackgroundWorkaround()) {
+                    activateTransparentBackgroundsForToBack(cameraXView);
+                } else {
+                    prepareTransparentBackgroundsForToBack(cameraXView);
+                }
+            } else {
+                toBackVisualStateActive = false;
+            }
+            requestBarcodeScannerRestartAfterCameraResume();
+            cameraRestartAfterResumeInProgress = true;
             cameraXView.startSession(lastSessionConfig);
         }
     }
@@ -110,12 +124,18 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
             cameraXView = null;
         }
         lastSessionConfig = null;
+        clearActiveBarcodeScanner();
+        toBackVisualStateActive = false;
+        restoreOriginalWindowBackground(getBridge().getActivity());
+        restoreWebViewVisualState();
         restoreSystemUiForToBackMode(getBridge().getActivity());
+        unregisterScreenLockReceiver();
     }
 
     private CameraSessionConfiguration lastSessionConfig;
 
     private static final String TAG = "CameraPreview CameraXView";
+    private static final int DEFAULT_WEB_VIEW_BACKGROUND = Color.WHITE;
 
     static final String CAMERA_WITH_AUDIO_PERMISSION_ALIAS = "cameraWithAudio";
     static final String CAMERA_ONLY_PERMISSION_ALIAS = "cameraOnly";
@@ -138,15 +158,40 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
     private boolean lastDisableAudio = true;
     private boolean lastIncludeSafeAreaInsets = false;
     private Drawable originalWindowBackground;
+    private boolean originalWindowBackgroundCaptured = false;
+    private Drawable originalWebViewBackground;
+    private boolean originalWebViewBackgroundCaptured = false;
     private Float originalWebViewAlpha;
     private Drawable originalWebViewParentBackground;
+    private boolean originalWebViewParentBackgroundCaptured = false;
     private Integer originalStatusBarColor;
     private Integer originalNavigationBarColor;
     private Boolean originalNavigationBarContrastEnforced;
+    private volatile boolean toBackVisualStateActive = false;
     private boolean isCameraPermissionDialogShowing = false;
     private boolean pendingStartBarcodeScanner = false;
     private List<String> pendingStartBarcodeFormats = new ArrayList<>();
     private int pendingStartBarcodeDetectionInterval = 500;
+    private final Object activeBarcodeScannerLock = new Object();
+    private boolean activeBarcodeScanner = false;
+    private List<String> activeBarcodeFormats = new ArrayList<>();
+    private int activeBarcodeDetectionInterval = 500;
+    private boolean restartBarcodeScannerAfterCameraResume = false;
+    private boolean screenLocked = false;
+    private boolean activityPaused = false;
+    private boolean cameraRestartAfterResumeInProgress = false;
+    private BroadcastReceiver screenLockReceiver;
+
+    private static final class BarcodeScannerRequest {
+
+        private final List<String> formats;
+        private final int detectionInterval;
+
+        private BarcodeScannerRequest(List<String> formats, int detectionInterval) {
+            this.formats = formats;
+            this.detectionInterval = detectionInterval;
+        }
+    }
 
     @PluginMethod
     public void getExposureModes(PluginCall call) {
@@ -418,6 +463,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
             new CameraXView.BarcodeScannerStartCallback() {
                 @Override
                 public void onStarted() {
+                    markActiveBarcodeScanner(formats, detectionInterval != null ? detectionInterval : 500);
                     call.resolve();
                 }
 
@@ -431,6 +477,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
 
     @PluginMethod
     public void stopBarcodeScanner(PluginCall call) {
+        clearActiveBarcodeScanner();
         if (cameraXView != null) {
             cameraXView.stopBarcodeScanner();
         }
@@ -492,6 +539,176 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         pendingStartBarcodeDetectionInterval = 500;
     }
 
+    private void markActiveBarcodeScanner(List<String> formats, int detectionInterval) {
+        synchronized (activeBarcodeScannerLock) {
+            activeBarcodeScanner = true;
+            activeBarcodeFormats = new ArrayList<>(formats);
+            activeBarcodeDetectionInterval = detectionInterval;
+        }
+    }
+
+    private void clearActiveBarcodeScanner() {
+        synchronized (activeBarcodeScannerLock) {
+            activeBarcodeScanner = false;
+            activeBarcodeFormats = new ArrayList<>();
+            activeBarcodeDetectionInterval = 500;
+            restartBarcodeScannerAfterCameraResume = false;
+        }
+    }
+
+    private void requestBarcodeScannerRestartAfterCameraResume() {
+        synchronized (activeBarcodeScannerLock) {
+            if (activeBarcodeScanner) {
+                restartBarcodeScannerAfterCameraResume = true;
+            }
+        }
+    }
+
+    private BarcodeScannerRequest consumeBarcodeScannerRestartRequest() {
+        synchronized (activeBarcodeScannerLock) {
+            if (!activeBarcodeScanner || !restartBarcodeScannerAfterCameraResume) {
+                return null;
+            }
+            restartBarcodeScannerAfterCameraResume = false;
+            return new BarcodeScannerRequest(new ArrayList<>(activeBarcodeFormats), activeBarcodeDetectionInterval);
+        }
+    }
+
+    private void restoreBarcodeScannerRestartRequest(BarcodeScannerRequest request) {
+        if (request == null) {
+            return;
+        }
+        synchronized (activeBarcodeScannerLock) {
+            if (activeBarcodeScanner) {
+                restartBarcodeScannerAfterCameraResume = true;
+            }
+        }
+    }
+
+    private void restartBarcodeScannerAfterCameraResumeIfNeeded() {
+        if (screenLocked || isDeviceLocked()) {
+            return;
+        }
+
+        if (cameraXView == null || !cameraXView.isRunning()) {
+            return;
+        }
+
+        BarcodeScannerRequest request = consumeBarcodeScannerRestartRequest();
+        if (request == null) {
+            return;
+        }
+
+        cameraXView.startBarcodeScanner(
+            request.formats,
+            request.detectionInterval,
+            new CameraXView.BarcodeScannerStartCallback() {
+                @Override
+                public void onStarted() {
+                    markActiveBarcodeScanner(request.formats, request.detectionInterval);
+                }
+
+                @Override
+                public void onError(String message) {
+                    restoreBarcodeScannerRestartRequest(request);
+                    onBarcodeScanError("Failed to restart barcode scanner after unlock: " + message);
+                }
+            }
+        );
+    }
+
+    private void registerScreenLockReceiver() {
+        if (screenLockReceiver != null) {
+            return;
+        }
+
+        screenLockReceiver = new BroadcastReceiver() {
+            @Override
+            public void onReceive(Context context, Intent intent) {
+                String action = intent != null ? intent.getAction() : null;
+                if (Intent.ACTION_SCREEN_OFF.equals(action)) {
+                    handleScreenOff();
+                } else if (Intent.ACTION_SCREEN_ON.equals(action)) {
+                    handleScreenOn();
+                } else if (Intent.ACTION_USER_PRESENT.equals(action)) {
+                    handleScreenUnlocked();
+                }
+            }
+        };
+
+        IntentFilter filter = new IntentFilter();
+        filter.addAction(Intent.ACTION_SCREEN_OFF);
+        filter.addAction(Intent.ACTION_SCREEN_ON);
+        filter.addAction(Intent.ACTION_USER_PRESENT);
+
+        Context context = getContext();
+        if (context == null) {
+            screenLockReceiver = null;
+            return;
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            context.registerReceiver(screenLockReceiver, filter, Context.RECEIVER_NOT_EXPORTED);
+        } else {
+            context.registerReceiver(screenLockReceiver, filter);
+        }
+    }
+
+    private void unregisterScreenLockReceiver() {
+        if (screenLockReceiver == null) {
+            return;
+        }
+        try {
+            Context context = getContext();
+            if (context != null) {
+                context.unregisterReceiver(screenLockReceiver);
+            }
+        } catch (IllegalArgumentException ignored) {
+            // Receiver may already be unregistered by the host activity.
+        } finally {
+            screenLockReceiver = null;
+        }
+    }
+
+    private boolean isDeviceLocked() {
+        Context context = getContext();
+        KeyguardManager keyguardManager = context != null ? (KeyguardManager) context.getSystemService(Context.KEYGUARD_SERVICE) : null;
+        return keyguardManager != null && keyguardManager.isKeyguardLocked();
+    }
+
+    private void handleScreenOff() {
+        screenLocked = true;
+        requestBarcodeScannerRestartAfterCameraResume();
+        if (cameraXView != null && cameraXView.isRunning() && !cameraXView.isStopping()) {
+            lastSessionConfig = cameraXView.getSessionConfig();
+            cameraXView.stopSession();
+        }
+    }
+
+    private void handleScreenOn() {
+        screenLocked = isDeviceLocked();
+        if (!screenLocked) {
+            restartBarcodeScannerAfterCameraResumeIfNeeded();
+        }
+    }
+
+    private void handleScreenUnlocked() {
+        screenLocked = false;
+        if (
+            !activityPaused &&
+            !cameraRestartAfterResumeInProgress &&
+            lastSessionConfig != null &&
+            (cameraXView == null || cameraXView.isStopping())
+        ) {
+            cameraXView = new CameraXView(getContext(), getBridge().getWebView());
+            cameraXView.setListener(this);
+            requestBarcodeScannerRestartAfterCameraResume();
+            cameraRestartAfterResumeInProgress = true;
+            cameraXView.startSession(lastSessionConfig);
+            return;
+        }
+        restartBarcodeScannerAfterCameraResumeIfNeeded();
+    }
+
     @PluginMethod
     public void stop(final PluginCall call) {
         boolean force = Boolean.TRUE.equals(call.getBoolean("force", false));
@@ -524,13 +741,9 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
                 }
                 // Manual stops should not trigger automatic resume with stale config
                 lastSessionConfig = null;
-                // Restore original window background if modified earlier
-                if (originalWindowBackground != null) {
-                    try {
-                        getBridge().getActivity().getWindow().setBackgroundDrawable(originalWindowBackground);
-                    } catch (Exception ignored) {}
-                    originalWindowBackground = null;
-                }
+                clearActiveBarcodeScanner();
+                toBackVisualStateActive = false;
+                restoreOriginalWindowBackground(getBridge().getActivity());
                 restoreWebViewVisualState();
                 restoreSystemUiForToBackMode(getBridge().getActivity());
                 call.resolve();
@@ -1051,16 +1264,14 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
             .getActivity()
             .runOnUiThread(() -> {
                 lockSystemUiForToBackMode(getBridge().getActivity(), toBack);
-                // Ensure transparent background when preview is behind the WebView (Android 10 fix)
                 if (toBack) {
-                    try {
-                        if (originalWindowBackground == null) {
-                            originalWindowBackground = getBridge().getActivity().getWindow().getDecorView().getBackground();
-                        }
-                        // Set to solid black first to prevent flickering during transition
-                        // This provides a stable base before camera preview is ready
-                        getBridge().getActivity().getWindow().setBackgroundDrawable(new ColorDrawable(Color.BLACK));
-                    } catch (Exception ignored) {}
+                    if (usesFullStackTransparentBackgroundWorkaround()) {
+                        activateTransparentBackgroundsForToBack(cameraXView);
+                    } else {
+                        prepareTransparentBackgroundsForToBack(cameraXView);
+                    }
+                } else {
+                    toBackVisualStateActive = false;
                 }
                 DisplayMetrics metrics = getBridge().getActivity().getResources().getDisplayMetrics();
                 if (lockOrientation) {
@@ -1337,7 +1548,11 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
                 config.setTargetZoom(finalTargetZoom);
                 config.setCentered(isCentered);
                 config.setEnablePhysicalDeviceSelection(enablePhysicalDeviceSelection);
+                config.setBarcodeScannerEnabled(barcodeScannerOptions != null);
                 setPendingStartBarcodeScanner(barcodeScannerOptions);
+                if (barcodeScannerOptions == null) {
+                    clearActiveBarcodeScanner();
+                }
 
                 bridge.saveCall(call);
                 cameraStartCallbackId = call.getCallbackId();
@@ -1625,11 +1840,14 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
             Log.d(TAG, "onCameraStopped: ignoring callback from stale instance");
             return;
         }
+        cameraRestartAfterResumeInProgress = false;
         // Ensure reference is cleared once the originating CameraXView has fully stopped
-        if (cameraXView == source) {
+        if (source != null && cameraXView == source) {
             cameraXView = null;
         }
-        restoreWebViewVisualState();
+        if (!toBackVisualStateActive) {
+            restoreWebViewVisualState();
+        }
 
         PluginCall queuedCall = null;
         synchronized (pendingStartLock) {
@@ -1676,6 +1894,72 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         return manufacturer.contains("xiaomi") || brand.contains("xiaomi") || brand.contains("redmi") || brand.contains("poco");
     }
 
+    private boolean usesFullStackTransparentBackgroundWorkaround() {
+        String manufacturer = Build.MANUFACTURER != null ? Build.MANUFACTURER.toLowerCase(Locale.US) : "";
+        String brand = Build.BRAND != null ? Build.BRAND.toLowerCase(Locale.US) : "";
+        return (
+            isMiuiDevice() ||
+            manufacturer.contains("huawei") ||
+            manufacturer.contains("honor") ||
+            brand.contains("huawei") ||
+            brand.contains("honor")
+        );
+    }
+
+    private void captureOriginalWindowBackground(Activity activity) {
+        if (activity == null) {
+            return;
+        }
+        synchronized (this) {
+            if (!originalWindowBackgroundCaptured) {
+                originalWindowBackground = activity.getWindow().getDecorView().getBackground();
+                originalWindowBackgroundCaptured = true;
+            }
+        }
+    }
+
+    private void captureOriginalWebViewVisualState(WebView webView, ViewGroup webViewParent) {
+        if (webView == null) {
+            return;
+        }
+        synchronized (this) {
+            if (!originalWebViewBackgroundCaptured) {
+                originalWebViewBackground = webView.getBackground();
+                originalWebViewBackgroundCaptured = true;
+            }
+            if (originalWebViewAlpha == null) {
+                originalWebViewAlpha = webView.getAlpha();
+            }
+            if (webViewParent != null && !originalWebViewParentBackgroundCaptured) {
+                originalWebViewParentBackground = webViewParent.getBackground();
+                originalWebViewParentBackgroundCaptured = true;
+            }
+        }
+    }
+
+    private void restoreOriginalWindowBackground(Activity activity) {
+        final Drawable backgroundToRestore;
+        final boolean captured;
+        synchronized (this) {
+            backgroundToRestore = originalWindowBackground;
+            captured = originalWindowBackgroundCaptured;
+            originalWindowBackground = null;
+            originalWindowBackgroundCaptured = false;
+        }
+
+        if (!captured || activity == null) {
+            return;
+        }
+
+        activity.runOnUiThread(() -> {
+            try {
+                activity.getWindow().setBackgroundDrawable(backgroundToRestore);
+            } catch (Exception e) {
+                Log.w(TAG, "Failed to restore window background", e);
+            }
+        });
+    }
+
     private int toOpaqueColor(int color) {
         return Color.argb(255, Color.red(color), Color.green(color), Color.blue(color));
     }
@@ -1741,35 +2025,46 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         });
     }
 
-    private void applyTransparentBackgroundsForToBack() {
-        if (!isToBackMode()) {
-            return;
-        }
+    private void prepareTransparentBackgroundsForToBack(CameraXView visualStateOwner) {
         Activity activity = getActivity();
         WebView webView = getBridge().getWebView();
         if (activity == null || webView == null) {
             return;
         }
 
-        if (originalWebViewAlpha == null) {
-            originalWebViewAlpha = webView.getAlpha();
+        toBackVisualStateActive = true;
+        final ViewGroup webViewParent = (ViewGroup) webView.getParent();
+        captureOriginalWindowBackground(activity);
+        captureOriginalWebViewVisualState(webView, webViewParent);
+    }
+
+    private void activateTransparentBackgroundsForToBack(CameraXView visualStateOwner) {
+        prepareTransparentBackgroundsForToBack(visualStateOwner);
+        Activity activity = getActivity();
+        WebView webView = getBridge().getWebView();
+        if (activity == null || webView == null) {
+            return;
         }
 
         final ViewGroup webViewParent = (ViewGroup) webView.getParent();
-        if (webViewParent != null && originalWebViewParentBackground == null) {
-            originalWebViewParentBackground = webViewParent.getBackground();
-        }
 
         Runnable apply = () -> {
             try {
-                activity.getWindow().setBackgroundDrawable(new ColorDrawable(Color.TRANSPARENT));
-                if (webViewParent != null) {
+                if (!toBackVisualStateActive || visualStateOwner == null || cameraXView != visualStateOwner) {
+                    return;
+                }
+                boolean fullStackWorkaround = usesFullStackTransparentBackgroundWorkaround();
+                if (fullStackWorkaround) {
+                    activity.getWindow().setBackgroundDrawable(new ColorDrawable(Color.TRANSPARENT));
+                }
+                if (webViewParent != null && fullStackWorkaround) {
                     webViewParent.setBackgroundColor(Color.TRANSPARENT);
                 }
-                // Keep a tiny alpha on MIUI/Xiaomi devices to avoid compositor bugs that treat
-                // fully transparent layers as black.
-                webView.setBackgroundColor(Color.argb(1, 255, 255, 255));
+                webView.setBackgroundColor(isMiuiDevice() ? Color.argb(1, 255, 255, 255) : Color.TRANSPARENT);
                 webView.setAlpha(isMiuiDevice() ? 0.99f : (originalWebViewAlpha != null ? originalWebViewAlpha : 1f));
+                if (webViewParent != null) {
+                    webViewParent.requestTransparentRegion(webView);
+                }
             } catch (Exception e) {
                 Log.w(TAG, "Failed to set backgrounds to transparent", e);
             }
@@ -1784,13 +2079,41 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
         });
     }
 
+    private void applyTransparentBackgroundsForToBack() {
+        if (!isToBackMode()) {
+            return;
+        }
+        activateTransparentBackgroundsForToBack(cameraXView);
+    }
+
     private void restoreWebViewVisualState() {
+        if (toBackVisualStateActive) {
+            return;
+        }
+
         Activity activity = getActivity();
         WebView webView = getBridge().getWebView();
-        final Float alphaToRestore = originalWebViewAlpha;
-        final Drawable parentBackground = originalWebViewParentBackground;
-        originalWebViewAlpha = null;
-        originalWebViewParentBackground = null;
+        final Float alphaToRestore;
+        final Drawable webViewBackground;
+        final boolean webViewBackgroundCaptured;
+        final Drawable parentBackground;
+        final boolean parentBackgroundCaptured;
+        synchronized (this) {
+            alphaToRestore = originalWebViewAlpha;
+            webViewBackground = originalWebViewBackground;
+            webViewBackgroundCaptured = originalWebViewBackgroundCaptured;
+            parentBackground = originalWebViewParentBackground;
+            parentBackgroundCaptured = originalWebViewParentBackgroundCaptured;
+            originalWebViewAlpha = null;
+            originalWebViewBackground = null;
+            originalWebViewBackgroundCaptured = false;
+            originalWebViewParentBackground = null;
+            originalWebViewParentBackgroundCaptured = false;
+        }
+
+        if (alphaToRestore == null && !webViewBackgroundCaptured && !parentBackgroundCaptured) {
+            return;
+        }
 
         if (activity == null || webView == null) {
             return;
@@ -1802,7 +2125,12 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
                 if (alphaToRestore != null) {
                     webView.setAlpha(alphaToRestore);
                 }
-                if (webViewParent != null && parentBackground != null) {
+                if (webViewBackgroundCaptured) {
+                    webView.setBackground(webViewBackground);
+                } else {
+                    webView.setBackgroundColor(DEFAULT_WEB_VIEW_BACKGROUND);
+                }
+                if (webViewParent != null && parentBackgroundCaptured) {
                     webViewParent.setBackground(parentBackground);
                 }
             } catch (Exception ignored) {}
@@ -1811,6 +2139,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
 
     @Override
     public void onCameraStarted(int width, int height, int x, int y) {
+        cameraRestartAfterResumeInProgress = false;
         // Always transition window and WebView backgrounds to transparent when the camera starts,
         // regardless of whether there is a pending JS call. This is critical for the
         // background/foreground resume cycle: on resume, handleOnResume() sets backgrounds to
@@ -1971,6 +2300,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
                     new CameraXView.BarcodeScannerStartCallback() {
                         @Override
                         public void onStarted() {
+                            markActiveBarcodeScanner(formats, detectionInterval);
                             resolveCameraStartCall(call, result);
                         }
 
@@ -1985,6 +2315,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
 
             resolveCameraStartCall(call, result);
         }
+        restartBarcodeScannerAfterCameraResumeIfNeeded();
     }
 
     private void resolveCameraStartCall(PluginCall call, JSObject result) {
@@ -2042,7 +2373,23 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
     }
 
     @Override
-    public void onCameraStartError(String message) {
+    public void onCameraStartError(CameraXView source, String message) {
+        if (cameraXView != null && cameraXView != source) {
+            Log.d(TAG, "onCameraStartError: ignoring callback from stale instance");
+            return;
+        }
+        cameraRestartAfterResumeInProgress = false;
+        toBackVisualStateActive = false;
+        if (cameraXView == source) {
+            try {
+                // Keep the reference until onCameraStopped clears it after native cleanup.
+                source.stopSession();
+            } catch (Exception e) {
+                Log.w(TAG, "onCameraStartError: failed to stop failed camera session", e);
+                cameraXView = null;
+            }
+        }
+
         PluginCall call = bridge.getSavedCall(cameraStartCallbackId);
         if (call != null) {
             call.reject(message);
@@ -2051,24 +2398,7 @@ public class CameraPreview extends Plugin implements CameraXView.CameraXViewList
             resetPendingStartBarcodeScanner();
         }
 
-        // Restore original window background on error to prevent black screen
-        // Use synchronized block to ensure only one thread captures and clears the background.
-        // Even if multiple errors occur, only the first will have a non-null background to restore.
-        synchronized (this) {
-            final Drawable backgroundToRestore = originalWindowBackground;
-            if (backgroundToRestore != null) {
-                originalWindowBackground = null; // Clear immediately so other threads won't restore
-                getBridge()
-                    .getActivity()
-                    .runOnUiThread(() -> {
-                        try {
-                            getBridge().getActivity().getWindow().setBackgroundDrawable(backgroundToRestore);
-                        } catch (Exception e) {
-                            Log.w(TAG, "Failed to restore window background on error", e);
-                        }
-                    });
-            }
-        }
+        restoreOriginalWindowBackground(getBridge().getActivity());
         restoreWebViewVisualState();
         restoreSystemUiForToBackMode(getBridge().getActivity());
     }

package/android/src/main/java/app/capgo/capacitor/camera/preview/CameraXView.java

@@ -129,7 +129,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
         void onBarcodesScanned(JSONArray barcodes);
         void onBarcodeScanError(String message);
         void onCameraStarted(int width, int height, int x, int y);
-        void onCameraStartError(String message);
+        void onCameraStartError(CameraXView source, String message);
         void onCameraStopped(CameraXView source);
     }
 
@@ -191,6 +191,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
     private volatile boolean isBarcodeFrameProcessing = false;
     private volatile long lastBarcodeFrameAtMs = 0L;
     private volatile long barcodeDetectionIntervalMs = 500L;
+    private boolean cameraStartedCallbackSent = false;
 
     // Operation coordination (acts like a semaphore to prevent stop during active ops)
     private final Object operationLock = new Object();
@@ -481,13 +482,13 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
             // runnable is still queued — never transition backward from DESTROYED.
             if (lifecycleRegistry.getCurrentState() == Lifecycle.State.DESTROYED) {
                 if (listener != null) {
-                    listener.onCameraStartError("Camera start aborted: lifecycle destroyed");
+                    listener.onCameraStartError(this, "Camera start aborted: lifecycle destroyed");
                 }
                 return;
             }
             if (stopRequested) {
                 if (listener != null) {
-                    listener.onCameraStartError("Camera start aborted: stop requested");
+                    listener.onCameraStartError(this, "Camera start aborted: stop requested");
                 }
                 return;
             }
@@ -496,44 +497,45 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                 lifecycleRegistry.setCurrentState(Lifecycle.State.CREATED);
                 if (lifecycleRegistry.getCurrentState() == Lifecycle.State.DESTROYED) {
                     if (listener != null) {
-                        listener.onCameraStartError("Camera start aborted: lifecycle destroyed");
+                        listener.onCameraStartError(this, "Camera start aborted: lifecycle destroyed");
                     }
                     return;
                 }
                 if (stopRequested) {
                     if (listener != null) {
-                        listener.onCameraStartError("Camera start aborted: stop requested");
+                        listener.onCameraStartError(this, "Camera start aborted: stop requested");
                     }
                     return;
                 }
             }
             if (lifecycleRegistry.getCurrentState() == Lifecycle.State.DESTROYED) {
                 if (listener != null) {
-                    listener.onCameraStartError("Camera start aborted: lifecycle destroyed");
+                    listener.onCameraStartError(this, "Camera start aborted: lifecycle destroyed");
                 }
                 return;
             }
             if (stopRequested) {
                 if (listener != null) {
-                    listener.onCameraStartError("Camera start aborted: stop requested");
+                    listener.onCameraStartError(this, "Camera start aborted: stop requested");
                 }
                 return;
             }
             lifecycleRegistry.setCurrentState(Lifecycle.State.STARTED);
             if (lifecycleRegistry.getCurrentState() == Lifecycle.State.DESTROYED) {
                 if (listener != null) {
-                    listener.onCameraStartError("Camera start aborted: lifecycle destroyed");
+                    listener.onCameraStartError(this, "Camera start aborted: lifecycle destroyed");
                 }
                 return;
             }
             if (stopRequested) {
                 if (listener != null) {
-                    listener.onCameraStartError("Camera start aborted: stop requested");
+                    listener.onCameraStartError(this, "Camera start aborted: stop requested");
                 }
                 return;
             }
 
             this.sessionConfig = config;
+            cameraStartedCallbackSent = false;
             cameraExecutor = Executors.newSingleThreadExecutor();
             requestEnumeratedDeviceCacheRefresh();
 
@@ -629,6 +631,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                 if (cameraProvider != null) {
                     cameraProvider.unbindAll();
                 }
+                barcodeAnalysis = null;
                 if (cameraExecutor != null) {
                     cameraExecutor.shutdown();
                 }
@@ -654,7 +657,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
     private void restoreWebViewBackground() {
         // Capture sessionConfig reference once to avoid race conditions
         CameraSessionConfiguration config = sessionConfig;
-        boolean shouldRestore = config != null && config.isToBack();
+        boolean shouldRestore = config == null || !config.isToBack();
         if (shouldRestore) {
             // Capture background color before posting to UI thread
             final int backgroundColorToRestore = originalWebViewBackground;
@@ -674,26 +677,26 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                 try {
                     if (lifecycleRegistry.getCurrentState() == Lifecycle.State.DESTROYED) {
                         if (listener != null) {
-                            listener.onCameraStartError("Camera binding cancelled: lifecycle destroyed (before provider)");
+                            listener.onCameraStartError(this, "Camera binding cancelled: lifecycle destroyed (before provider)");
                         }
                         return;
                     }
                     if (stopRequested) {
                         if (listener != null) {
-                            listener.onCameraStartError("Camera binding cancelled: stop requested (before provider)");
+                            listener.onCameraStartError(this, "Camera binding cancelled: stop requested (before provider)");
                         }
                         return;
                     }
                     cameraProvider = cameraProviderFuture.get();
                     if (lifecycleRegistry.getCurrentState() == Lifecycle.State.DESTROYED) {
                         if (listener != null) {
-                            listener.onCameraStartError("Camera binding cancelled: lifecycle destroyed (after provider)");
+                            listener.onCameraStartError(this, "Camera binding cancelled: lifecycle destroyed (after provider)");
                         }
                         return;
                     }
                     if (stopRequested) {
                         if (listener != null) {
-                            listener.onCameraStartError("Camera binding cancelled: stop requested (after provider)");
+                            listener.onCameraStartError(this, "Camera binding cancelled: stop requested (after provider)");
                         }
                         return;
                     }
@@ -703,7 +706,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                     // Restore webView background on error
                     restoreWebViewBackground();
                     if (listener != null) {
-                        listener.onCameraStartError("Error initializing camera: " + e.getMessage());
+                        listener.onCameraStartError(this, "Error initializing camera: " + e.getMessage());
                     }
                 }
             },
@@ -715,13 +718,11 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
         if (previewView != null) {
             removePreviewView();
         }
-        if (sessionConfig.isToBack()) {
-            // Set to black initially to prevent flickering, will be transparent after camera starts
-            webView.setBackgroundColor(android.graphics.Color.BLACK);
-        }
-
         // Create a container to hold both the preview and grid overlay
         previewContainer = new FrameLayout(context);
+        if (sessionConfig != null && sessionConfig.isToBack()) {
+            previewContainer.setBackgroundColor(Color.TRANSPARENT);
+        }
         // Ensure container can receive touch events
         previewContainer.setClickable(true);
         previewContainer.setFocusable(true);
@@ -735,9 +736,11 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
 
         // Create and setup the preview view
         previewView = new PreviewView(context);
-        // Use TextureView-backed implementation for broader device compatibility when overlaying with WebView
-        // This avoids SurfaceView z-order issues seen on some MIUI/EMUI devices.
-        previewView.setImplementationMode(PreviewView.ImplementationMode.COMPATIBLE);
+        if (sessionConfig != null && sessionConfig.isToBack()) {
+            previewView.setBackgroundColor(Color.TRANSPARENT);
+        }
+        PreviewView.ImplementationMode implementationMode = choosePreviewImplementationMode();
+        previewView.setImplementationMode(implementationMode);
         // Set scale type based on aspectMode: 'contain' uses FIT, 'cover' uses FILL
         String aspectMode = sessionConfig != null ? sessionConfig.getAspectMode() : "contain";
         previewView.setScaleType("cover".equals(aspectMode) ? PreviewView.ScaleType.FILL_CENTER : PreviewView.ScaleType.FIT_CENTER);
@@ -753,6 +756,14 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
             new FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT)
         );
 
+        previewView
+            .getPreviewStreamState()
+            .observe(this, (streamState) -> {
+                if (sessionConfig != null && sessionConfig.isToBack() && streamState == PreviewView.StreamState.STREAMING) {
+                    notifyCameraStartedIfNeeded("streaming");
+                }
+            });
+
         // Create and setup the grid overlay
         gridOverlayView = new GridOverlayView(context);
         // Make grid overlay not intercept touch events
@@ -781,7 +792,17 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
         if (parent != null) {
             FrameLayout.LayoutParams layoutParams = calculatePreviewLayoutParams();
             parent.addView(previewContainer, layoutParams);
-            if (sessionConfig.isToBack()) webView.bringToFront();
+            if (sessionConfig.isToBack()) {
+                webView.bringToFront();
+                parent.requestTransparentRegion(webView);
+                webView.post(() -> {
+                    webView.bringToFront();
+                    ViewGroup currentParent = (ViewGroup) webView.getParent();
+                    if (currentParent != null) {
+                        currentParent.requestTransparentRegion(webView);
+                    }
+                });
+            }
 
             // Log the actual position after layout
             previewContainer.post(() -> {
@@ -811,6 +832,10 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
         }
     }
 
+    private PreviewView.ImplementationMode choosePreviewImplementationMode() {
+        return PreviewView.ImplementationMode.COMPATIBLE;
+    }
+
     /**
      * Compute layout parameters for the camera preview container based on the current session configuration,
      * device screen size, WebView/parent geometry, and optional aspect-ratio centering.
@@ -1000,7 +1025,9 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
         if (focusIndicatorView != null) {
             focusIndicatorView = null;
         }
-        webView.setBackgroundColor(originalWebViewBackground);
+        if (sessionConfig == null || !sessionConfig.isToBack()) {
+            webView.setBackgroundColor(originalWebViewBackground);
+        }
     }
 
     @OptIn(markerClass = ExperimentalCamera2Interop.class)
@@ -1050,6 +1077,14 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                     .setTargetRotation(rotation)
                     .build();
                 sampleImageCapture = imageCapture;
+                barcodeAnalysis = null;
+
+                if (!sessionConfig.isVideoModeEnabled() && sessionConfig.isBarcodeScannerEnabled()) {
+                    barcodeAnalysis = createBarcodeAnalysisUseCase();
+                    if (isBarcodeScannerActive && barcodeScanner != null && cameraExecutor != null) {
+                        barcodeAnalysis.setAnalyzer(cameraExecutor, this::analyzeBarcodeImage);
+                    }
+                }
 
                 // Only setup VideoCapture if enableVideoMode is true
                 if (sessionConfig.isVideoModeEnabled()) {
@@ -1214,6 +1249,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                         if (initialZoom < minZoom || initialZoom > maxZoom) {
                             if (listener != null) {
                                 listener.onCameraStartError(
+                                    this,
                                     "Initial zoom level " +
                                         initialZoom +
                                         " is not available. " +
@@ -1233,43 +1269,78 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                 isRunning = true;
                 Log.d(TAG, "bindCameraUseCases: Camera bound successfully");
                 if (listener != null) {
-                    // Post the callback to ensure layout is complete
-                    previewContainer.post(() -> {
-                        // Return actual preview container dimensions instead of requested dimensions
-                        // Get the actual camera dimensions and position
-                        int actualWidth = getPreviewWidth();
-                        int actualHeight = getPreviewHeight();
-                        int actualX = getPreviewX();
-                        int actualY = getPreviewY();
-
-                        Log.d(
-                            TAG,
-                            "onCameraStarted callback - actualX=" +
-                                actualX +
-                                ", actualY=" +
-                                actualY +
-                                ", actualWidth=" +
-                                actualWidth +
-                                ", actualHeight=" +
-                                actualHeight
-                        );
-
-                        // Update grid overlay bounds after camera is started
-                        updateGridOverlayBounds();
-
-                        // Notify listener that camera is started
-                        // The listener (CameraPreview) will handle setting both window and webview to transparent
-                        listener.onCameraStarted(actualWidth, actualHeight, actualX, actualY);
-                    });
+                    if (sessionConfig != null && sessionConfig.isToBack()) {
+                        PreviewView.StreamState streamState = previewView != null ? previewView.getPreviewStreamState().getValue() : null;
+                        if (streamState == PreviewView.StreamState.STREAMING) {
+                            notifyCameraStartedIfNeeded("already-streaming");
+                        } else if (previewContainer != null) {
+                            previewContainer.postDelayed(
+                                () -> {
+                                    PreviewView.StreamState latestState = previewView != null
+                                        ? previewView.getPreviewStreamState().getValue()
+                                        : null;
+                                    if (latestState == PreviewView.StreamState.STREAMING) {
+                                        notifyCameraStartedIfNeeded("watchdog-streaming");
+                                    }
+                                },
+                                300
+                            );
+                            previewContainer.postDelayed(
+                                () -> {
+                                    PreviewView.StreamState latestState = previewView != null
+                                        ? previewView.getPreviewStreamState().getValue()
+                                        : null;
+                                    if (!cameraStartedCallbackSent && latestState == PreviewView.StreamState.STREAMING) {
+                                        notifyCameraStartedIfNeeded("fallback-streaming");
+                                    }
+                                },
+                                1500
+                            );
+                        }
+                    } else {
+                        notifyCameraStartedIfNeeded("bound");
+                    }
                 }
             } catch (Exception e) {
                 // Restore webView background on error
                 restoreWebViewBackground();
-                if (listener != null) listener.onCameraStartError("Error binding camera: " + e.getMessage());
+                if (listener != null) listener.onCameraStartError(this, "Error binding camera: " + e.getMessage());
             }
         });
     }
 
+    private void notifyCameraStartedIfNeeded(String reason) {
+        if (cameraStartedCallbackSent || listener == null || previewContainer == null) {
+            return;
+        }
+        cameraStartedCallbackSent = true;
+        previewContainer.post(() -> {
+            if (listener == null || previewContainer == null) {
+                return;
+            }
+
+            int actualWidth = getPreviewWidth();
+            int actualHeight = getPreviewHeight();
+            int actualX = getPreviewX();
+            int actualY = getPreviewY();
+
+            Log.d(
+                TAG,
+                "onCameraStarted callback - actualX=" +
+                    actualX +
+                    ", actualY=" +
+                    actualY +
+                    ", actualWidth=" +
+                    actualWidth +
+                    ", actualHeight=" +
+                    actualHeight
+            );
+
+            updateGridOverlayBounds();
+            listener.onCameraStarted(actualWidth, actualHeight, actualX, actualY);
+        });
+    }
+
     @OptIn(markerClass = ExperimentalCamera2Interop.class)
     private CameraSelector buildCameraSelector() {
         return buildCameraBindingPlan(sessionConfig).selector;
@@ -1523,6 +1594,8 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
     private void bindConfiguredUseCases(CameraBindingPlan bindingPlan, Preview preview) {
         if (sessionConfig.isVideoModeEnabled() && videoCapture != null) {
             camera = cameraProvider.bindToLifecycle(this, bindingPlan.selector, preview, imageCapture, videoCapture);
+        } else if (barcodeAnalysis != null) {
+            camera = cameraProvider.bindToLifecycle(this, bindingPlan.selector, preview, imageCapture, barcodeAnalysis);
         } else {
             camera = cameraProvider.bindToLifecycle(this, bindingPlan.selector, preview, imageCapture);
         }
@@ -1551,26 +1624,20 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
 
         mainExecutor.execute(() -> {
             try {
-                stopBarcodeScannerInternal(true);
+                stopBarcodeScannerInternal(false);
                 barcodeScanner = createBarcodeScanner(formats);
                 barcodeDetectionIntervalMs = Math.max(100L, detectionIntervalMs);
                 lastBarcodeFrameAtMs = 0L;
                 isBarcodeFrameProcessing = false;
                 isBarcodeScannerActive = true;
 
-                ResolutionSelector barcodeResolutionSelector = new ResolutionSelector.Builder()
-                    .setResolutionStrategy(
-                        new ResolutionStrategy(new Size(1280, 720), ResolutionStrategy.FALLBACK_RULE_CLOSEST_LOWER_THEN_HIGHER)
-                    )
-                    .build();
-
-                barcodeAnalysis = new ImageAnalysis.Builder()
-                    .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
-                    .setResolutionSelector(barcodeResolutionSelector)
-                    .build();
-                barcodeAnalysis.setAnalyzer(cameraExecutor, this::analyzeBarcodeImage);
-
-                cameraProvider.bindToLifecycle(this, currentCameraSelector, barcodeAnalysis);
+                if (barcodeAnalysis == null) {
+                    barcodeAnalysis = createBarcodeAnalysisUseCase();
+                    barcodeAnalysis.setAnalyzer(cameraExecutor, this::analyzeBarcodeImage);
+                    cameraProvider.bindToLifecycle(this, currentCameraSelector, barcodeAnalysis);
+                } else {
+                    barcodeAnalysis.setAnalyzer(cameraExecutor, this::analyzeBarcodeImage);
+                }
                 callback.onStarted();
             } catch (Exception e) {
                 stopBarcodeScannerInternal(true);
@@ -1583,6 +1650,17 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
         mainExecutor.execute(() -> stopBarcodeScannerInternal(true));
     }
 
+    private ImageAnalysis createBarcodeAnalysisUseCase() {
+        ResolutionSelector barcodeResolutionSelector = new ResolutionSelector.Builder()
+            .setResolutionStrategy(new ResolutionStrategy(new Size(1280, 720), ResolutionStrategy.FALLBACK_RULE_CLOSEST_LOWER_THEN_HIGHER))
+            .build();
+
+        return new ImageAnalysis.Builder()
+            .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
+            .setResolutionSelector(barcodeResolutionSelector)
+            .build();
+    }
+
     private void stopBarcodeScannerInternal(boolean unbindAnalysis) {
         isBarcodeScannerActive = false;
         isBarcodeFrameProcessing = false;
@@ -1595,9 +1673,10 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
                     cameraProvider.unbind(barcodeAnalysis);
                 } catch (Exception e) {
                     Log.w(TAG, "stopBarcodeScannerInternal: failed to unbind barcode analysis", e);
+                } finally {
+                    barcodeAnalysis = null;
                 }
             }
-            barcodeAnalysis = null;
         }
 
         if (barcodeScanner != null) {
@@ -1803,6 +1882,7 @@ public class CameraXView implements LifecycleOwner, LifecycleObserver {
         target.setCentered(source.isCentered());
         target.setTargetZoom(source.getTargetZoom());
         target.setEnablePhysicalDeviceSelection(source.isPhysicalDeviceSelectionEnabled());
+        target.setBarcodeScannerEnabled(source.isBarcodeScannerEnabled());
     }
 
     private void requestEnumeratedDeviceCacheRefresh() {

package/android/src/main/java/app/capgo/capacitor/camera/preview/model/CameraSessionConfiguration.java

@@ -27,6 +27,7 @@ public class CameraSessionConfiguration {
     private boolean isCentered = false;
     private final String videoQuality;
     private boolean enablePhysicalDeviceSelection = false;
+    private boolean barcodeScannerEnabled = false;
 
     public CameraSessionConfiguration(
         String deviceId,
@@ -158,6 +159,14 @@ public class CameraSessionConfiguration {
         this.enablePhysicalDeviceSelection = enablePhysicalDeviceSelection;
     }
 
+    public boolean isBarcodeScannerEnabled() {
+        return barcodeScannerEnabled;
+    }
+
+    public void setBarcodeScannerEnabled(boolean barcodeScannerEnabled) {
+        this.barcodeScannerEnabled = barcodeScannerEnabled;
+    }
+
     // Additional getters with "get" prefix for compatibility
     public boolean getToBack() {
         return toBack;

package/ios/Sources/CapgoCameraPreviewPlugin/Plugin.swift

@@ -35,7 +35,7 @@ extension UIWindow {
  */
 @objc(CameraPreview)
 public class CameraPreview: CAPPlugin, CAPBridgedPlugin, CLLocationManagerDelegate {
-    private let pluginVersion: String = "8.4.2"
+    private let pluginVersion: String = "8.4.4"
     public let identifier = "CameraPreviewPlugin"
     public let jsName = "CameraPreview"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/camera-preview",
-  "version": "8.4.2",
+  "version": "8.4.4",
   "description": "Camera preview",
   "license": "MPL-2.0",
   "repository": {