react-native-rectangle-doc-scanner 3.29.0 → 3.31.0

package/dist/DocScanner.d.ts

@@ -20,6 +20,7 @@ export type DocScannerCapture = {
     rectangle: Rectangle | null;
     width: number;
     height: number;
+    origin: 'auto' | 'manual';
 };
 export interface DetectionConfig {
     processingWidth?: number;
@@ -43,6 +44,7 @@ interface Props {
     gridLineWidth?: number;
     detectionConfig?: DetectionConfig;
     onRectangleDetect?: (event: RectangleDetectEvent) => void;
+    showManualCaptureButton?: boolean;
 }
 export type DocScannerHandle = {
     capture: () => Promise<PictureEvent>;

package/dist/DocScanner.js

@@ -68,12 +68,13 @@ const normalizeRectangle = (rectangle) => {
     };
 };
 const DEFAULT_OVERLAY_COLOR = '#0b7ef4';
-exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAULT_OVERLAY_COLOR, autoCapture = true, minStableFrames = 8, enableTorch = false, quality = 90, useBase64 = false, children, showGrid = true, gridColor, gridLineWidth, detectionConfig, onRectangleDetect, }, ref) => {
+exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAULT_OVERLAY_COLOR, autoCapture = true, minStableFrames = 8, enableTorch = false, quality = 90, useBase64 = false, children, showGrid = true, gridColor, gridLineWidth, detectionConfig, onRectangleDetect, showManualCaptureButton = false, }, ref) => {
     const scannerRef = (0, react_1.useRef)(null);
     const captureResolvers = (0, react_1.useRef)(null);
     const [isAutoCapturing, setIsAutoCapturing] = (0, react_1.useState)(false);
     const [detectedRectangle, setDetectedRectangle] = (0, react_1.useState)(null);
     const lastRectangleRef = (0, react_1.useRef)(null);
+    const captureOriginRef = (0, react_1.useRef)('auto');
     (0, react_1.useEffect)(() => {
         if (!autoCapture) {
             setIsAutoCapturing(false);
@@ -90,6 +91,8 @@ exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAUL
         setIsAutoCapturing(false);
         const normalizedRectangle = normalizeRectangle(event.rectangleCoordinates ?? null) ?? lastRectangleRef.current;
         const quad = normalizedRectangle ? (0, coordinate_1.rectangleToQuad)(normalizedRectangle) : null;
+        const origin = captureOriginRef.current;
+        captureOriginRef.current = 'auto';
         const initialPath = event.initialImage ?? null;
         const croppedPath = event.croppedImage ?? null;
         const editablePath = initialPath ?? croppedPath;
@@ -102,6 +105,7 @@ exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAUL
                 rectangle: normalizedRectangle,
                 width: event.width ?? 0,
                 height: event.height ?? 0,
+                origin,
             });
         }
         setDetectedRectangle(null);
@@ -117,32 +121,50 @@ exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAUL
         }
     }, []);
     const capture = (0, react_1.useCallback)(() => {
+        captureOriginRef.current = 'manual';
         const instance = scannerRef.current;
         if (!instance || typeof instance.capture !== 'function') {
+            captureOriginRef.current = 'auto';
             return Promise.reject(new Error('DocumentScanner native instance is not ready'));
         }
         if (captureResolvers.current) {
+            captureOriginRef.current = 'auto';
             return Promise.reject(new Error('capture_in_progress'));
         }
-        const result = instance.capture();
+        let result;
+        try {
+            result = instance.capture();
+        }
+        catch (error) {
+            captureOriginRef.current = 'auto';
+            return Promise.reject(error);
+        }
         if (result && typeof result.then === 'function') {
-            return result.then((payload) => {
-                handlePictureTaken(payload);
-                return payload;
+            return result.catch((error) => {
+                captureOriginRef.current = 'auto';
+                throw error;
             });
         }
         return new Promise((resolve, reject) => {
-            captureResolvers.current = { resolve, reject };
+            captureResolvers.current = {
+                resolve: (value) => {
+                    captureOriginRef.current = 'auto';
+                    resolve(value);
+                },
+                reject: (reason) => {
+                    captureOriginRef.current = 'auto';
+                    reject(reason);
+                },
+            };
         });
-    }, [handlePictureTaken]);
+    }, []);
     const handleManualCapture = (0, react_1.useCallback)(() => {
-        if (autoCapture) {
-            return;
-        }
+        captureOriginRef.current = 'manual';
         capture().catch((error) => {
+            captureOriginRef.current = 'auto';
             console.warn('[DocScanner] manual capture failed', error);
         });
-    }, [autoCapture, capture]);
+    }, [capture]);
     const handleRectangleDetect = (0, react_1.useCallback)((event) => {
         const rectangleCoordinates = normalizeRectangle(event.rectangleCoordinates ?? null);
         const rectangleOnScreen = normalizeRectangle(event.rectangleOnScreen ?? null);
@@ -173,6 +195,7 @@ exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAUL
                 captureResolvers.current.reject(new Error('reset'));
                 captureResolvers.current = null;
             }
+            captureOriginRef.current = 'auto';
         },
     }), [capture]);
     const overlayPolygon = detectedRectangle?.rectangleOnScreen ?? detectedRectangle?.rectangleCoordinates ?? null;
@@ -180,7 +203,7 @@ exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAUL
     return (react_1.default.createElement(react_native_1.View, { style: styles.container },
         react_1.default.createElement(react_native_document_scanner_1.default, { ref: scannerRef, style: styles.scanner, detectionCountBeforeCapture: minStableFrames, overlayColor: overlayColor, enableTorch: enableTorch, quality: normalizedQuality, useBase64: useBase64, manualOnly: !autoCapture, detectionConfig: detectionConfig, onPictureTaken: handlePictureTaken, onError: handleError, onRectangleDetect: handleRectangleDetect }),
         showGrid && overlayPolygon && (react_1.default.createElement(overlay_1.ScannerOverlay, { active: overlayIsActive, color: gridColor ?? overlayColor, lineWidth: gridLineWidth, polygon: overlayPolygon })),
-        !autoCapture && react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.button, onPress: handleManualCapture }),
+        (showManualCaptureButton || !autoCapture) && (react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.button, onPress: handleManualCapture })),
         children));
 });
 const styles = react_native_1.StyleSheet.create({

package/dist/FullDocScanner.js

@@ -41,6 +41,27 @@ const CropEditor_1 = require("./CropEditor");
 const coordinate_1 = require("./utils/coordinate");
 const stripFileUri = (value) => value.replace(/^file:\/\//, '');
 const ensureFileUri = (value) => (value.startsWith('file://') ? value : `file://${value}`);
+const createFullImageRectangle = (width, height) => ({
+    topLeft: { x: 0, y: 0 },
+    topRight: { x: width, y: 0 },
+    bottomRight: { x: width, y: height },
+    bottomLeft: { x: 0, y: height },
+});
+const resolveImageSize = (path, fallbackWidth, fallbackHeight) => new Promise((resolve) => {
+    react_native_1.Image.getSize(ensureFileUri(path), (width, height) => resolve({ width, height }), () => resolve({
+        width: fallbackWidth > 0 ? fallbackWidth : 0,
+        height: fallbackHeight > 0 ? fallbackHeight : 0,
+    }));
+});
+const normalizeCapturedDocument = (document) => {
+    const normalizedPath = stripFileUri(document.initialPath ?? document.path);
+    return {
+        ...document,
+        path: normalizedPath,
+        initialPath: document.initialPath ? stripFileUri(document.initialPath) : normalizedPath,
+        croppedPath: document.croppedPath ? stripFileUri(document.croppedPath) : null,
+    };
+};
 const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3170f3', gridColor, gridLineWidth, showGrid, overlayStrokeColor = '#3170f3', handlerColor = '#3170f3', strings, manualCapture = false, minStableFrames, onError, }) => {
     const [screen, setScreen] = (0, react_1.useState)('scanner');
     const [capturedDoc, setCapturedDoc] = (0, react_1.useState)(null);
@@ -48,6 +69,10 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
     const [imageSize, setImageSize] = (0, react_1.useState)(null);
     const [processing, setProcessing] = (0, react_1.useState)(false);
     const resolvedGridColor = gridColor ?? overlayColor;
+    const docScannerRef = (0, react_1.useRef)(null);
+    const manualCapturePending = (0, react_1.useRef)(false);
+    const processingCaptureRef = (0, react_1.useRef)(false);
+    const cropInitializedRef = (0, react_1.useRef)(false);
     const mergedStrings = (0, react_1.useMemo)(() => ({
         captureHint: strings?.captureHint ?? 'Align the document within the frame.',
         manualHint: strings?.manualHint ?? 'Tap the button below to capture.',
@@ -64,7 +89,7 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
         react_native_1.Image.getSize(ensureFileUri(capturedDoc.path), (width, height) => setImageSize({ width, height }), () => setImageSize({ width: capturedDoc.width, height: capturedDoc.height }));
     }, [capturedDoc]);
     (0, react_1.useEffect)(() => {
-        if (!capturedDoc || !imageSize || cropRectangle) {
+        if (!capturedDoc || !imageSize || cropInitializedRef.current) {
             return;
         }
         const baseWidth = capturedDoc.width > 0 ? capturedDoc.width : imageSize.width;
@@ -80,36 +105,19 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
             }
         }
         if (initialRectangle) {
+            cropInitializedRef.current = true;
             setCropRectangle(initialRectangle);
         }
-    }, [capturedDoc, imageSize, cropRectangle]);
+    }, [capturedDoc, imageSize]);
     const resetState = (0, react_1.useCallback)(() => {
         setScreen('scanner');
         setCapturedDoc(null);
         setCropRectangle(null);
         setImageSize(null);
         setProcessing(false);
-    }, []);
-    const handleCapture = (0, react_1.useCallback)((document) => {
-        const normalizedPath = stripFileUri(document.path);
-        const nextQuad = document.quad && document.quad.length === 4 ? document.quad : null;
-        const quadRectangle = nextQuad ? (0, coordinate_1.quadToRectangle)(nextQuad) : null;
-        const nextRectangle = document.rectangle ?? quadRectangle ?? null;
-        const normalizedInitial = document.initialPath != null ? stripFileUri(document.initialPath) : normalizedPath;
-        const normalizedCropped = document.croppedPath != null ? stripFileUri(document.croppedPath) : null;
-        setCapturedDoc({
-            ...document,
-            path: normalizedPath,
-            initialPath: normalizedInitial,
-            croppedPath: normalizedCropped,
-            quad: nextQuad,
-            rectangle: nextRectangle,
-        });
-        setCropRectangle(null);
-        setScreen('crop');
-    }, []);
-    const handleCropChange = (0, react_1.useCallback)((rectangle) => {
-        setCropRectangle(rectangle);
+        manualCapturePending.current = false;
+        processingCaptureRef.current = false;
+        cropInitializedRef.current = false;
     }, []);
     const emitError = (0, react_1.useCallback)((error, fallbackMessage) => {
         console.error('[FullDocScanner] error', error);
@@ -118,6 +126,104 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
             react_native_1.Alert.alert('Document Scanner', fallbackMessage);
         }
     }, [onError]);
+    const processAutoCapture = (0, react_1.useCallback)(async (document) => {
+        manualCapturePending.current = false;
+        const normalizedDoc = normalizeCapturedDocument(document);
+        const cropManager = react_native_1.NativeModules.CustomCropManager;
+        if (!cropManager?.crop) {
+            emitError(new Error('CustomCropManager.crop is not available'));
+            return;
+        }
+        setProcessing(true);
+        try {
+            const size = await resolveImageSize(normalizedDoc.path, normalizedDoc.width, normalizedDoc.height);
+            const targetWidthRaw = size.width > 0 ? size.width : normalizedDoc.width;
+            const targetHeightRaw = size.height > 0 ? size.height : normalizedDoc.height;
+            const baseWidth = normalizedDoc.width > 0 ? normalizedDoc.width : targetWidthRaw;
+            const baseHeight = normalizedDoc.height > 0 ? normalizedDoc.height : targetHeightRaw;
+            const targetWidth = targetWidthRaw > 0 ? targetWidthRaw : baseWidth || 1;
+            const targetHeight = targetHeightRaw > 0 ? targetHeightRaw : baseHeight || 1;
+            let rectangleBase = normalizedDoc.rectangle ?? null;
+            if (!rectangleBase && normalizedDoc.quad && normalizedDoc.quad.length === 4) {
+                rectangleBase = (0, coordinate_1.quadToRectangle)(normalizedDoc.quad);
+            }
+            const scaledRectangle = rectangleBase
+                ? (0, coordinate_1.scaleRectangle)(rectangleBase, baseWidth || targetWidth, baseHeight || targetHeight, targetWidth, targetHeight)
+                : null;
+            const rectangleToUse = scaledRectangle ?? createFullImageRectangle(targetWidth, targetHeight);
+            const base64 = await new Promise((resolve, reject) => {
+                cropManager.crop({
+                    topLeft: rectangleToUse.topLeft,
+                    topRight: rectangleToUse.topRight,
+                    bottomRight: rectangleToUse.bottomRight,
+                    bottomLeft: rectangleToUse.bottomLeft,
+                    width: targetWidth,
+                    height: targetHeight,
+                }, ensureFileUri(normalizedDoc.path), (error, result) => {
+                    if (error) {
+                        reject(error instanceof Error ? error : new Error('Crop failed'));
+                        return;
+                    }
+                    resolve(result.image);
+                });
+            });
+            const finalDoc = {
+                ...normalizedDoc,
+                rectangle: rectangleToUse,
+            };
+            onResult({
+                original: finalDoc,
+                rectangle: rectangleToUse,
+                base64,
+            });
+            resetState();
+        }
+        catch (error) {
+            setProcessing(false);
+            emitError(error instanceof Error ? error : new Error(String(error)), 'Failed to process document.');
+        }
+        finally {
+            processingCaptureRef.current = false;
+        }
+    }, [emitError, onResult, resetState]);
+    const handleCapture = (0, react_1.useCallback)((document) => {
+        if (processingCaptureRef.current) {
+            return;
+        }
+        const isManualCapture = manualCapture || manualCapturePending.current || document.origin === 'manual';
+        const normalizedDoc = normalizeCapturedDocument(document);
+        if (isManualCapture) {
+            manualCapturePending.current = false;
+            processingCaptureRef.current = false;
+            cropInitializedRef.current = false;
+            setCapturedDoc(normalizedDoc);
+            setImageSize(null);
+            setCropRectangle(null);
+            setScreen('crop');
+            return;
+        }
+        processingCaptureRef.current = true;
+        processAutoCapture(document);
+    }, [manualCapture, processAutoCapture]);
+    const handleCropChange = (0, react_1.useCallback)((rectangle) => {
+        setCropRectangle(rectangle);
+    }, []);
+    const triggerManualCapture = (0, react_1.useCallback)(() => {
+        if (processingCaptureRef.current) {
+            return;
+        }
+        manualCapturePending.current = true;
+        const capturePromise = docScannerRef.current?.capture();
+        if (capturePromise && typeof capturePromise.catch === 'function') {
+            capturePromise.catch((error) => {
+                manualCapturePending.current = false;
+                console.warn('[FullDocScanner] manual capture failed', error);
+            });
+        }
+        else if (!capturePromise) {
+            manualCapturePending.current = false;
+        }
+    }, []);
     const performCrop = (0, react_1.useCallback)(async () => {
         if (!capturedDoc) {
             throw new Error('No captured document to crop');
@@ -129,25 +235,27 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
         }
         const baseWidth = capturedDoc.width > 0 ? capturedDoc.width : size.width;
         const baseHeight = capturedDoc.height > 0 ? capturedDoc.height : size.height;
-        const rectangleFromDetection = capturedDoc.rectangle
-            ? (0, coordinate_1.scaleRectangle)(capturedDoc.rectangle, baseWidth, baseHeight, size.width, size.height)
-            : null;
-        let fallbackRectangle = rectangleFromDetection;
-        if (!fallbackRectangle && capturedDoc.quad && capturedDoc.quad.length === 4) {
+        const targetWidth = size.width > 0 ? size.width : baseWidth || 1;
+        const targetHeight = size.height > 0 ? size.height : baseHeight || 1;
+        let fallbackRectangle = null;
+        if (capturedDoc.rectangle) {
+            fallbackRectangle = (0, coordinate_1.scaleRectangle)(capturedDoc.rectangle, baseWidth || targetWidth, baseHeight || targetHeight, targetWidth, targetHeight);
+        }
+        else if (capturedDoc.quad && capturedDoc.quad.length === 4) {
             const quadRectangle = (0, coordinate_1.quadToRectangle)(capturedDoc.quad);
             if (quadRectangle) {
-                fallbackRectangle = (0, coordinate_1.scaleRectangle)(quadRectangle, baseWidth, baseHeight, size.width, size.height);
+                fallbackRectangle = (0, coordinate_1.scaleRectangle)(quadRectangle, baseWidth || targetWidth, baseHeight || targetHeight, targetWidth, targetHeight);
             }
         }
-        const rectangle = cropRectangle ?? fallbackRectangle;
+        const rectangleToUse = cropRectangle ?? fallbackRectangle ?? createFullImageRectangle(targetWidth, targetHeight);
         const base64 = await new Promise((resolve, reject) => {
             cropManager.crop({
-                topLeft: rectangle?.topLeft ?? { x: 0, y: 0 },
-                topRight: rectangle?.topRight ?? { x: size.width, y: 0 },
-                bottomRight: rectangle?.bottomRight ?? { x: size.width, y: size.height },
-                bottomLeft: rectangle?.bottomLeft ?? { x: 0, y: size.height },
-                width: size.width,
-                height: size.height,
+                topLeft: rectangleToUse.topLeft,
+                topRight: rectangleToUse.topRight,
+                bottomRight: rectangleToUse.bottomRight,
+                bottomLeft: rectangleToUse.bottomLeft,
+                width: targetWidth,
+                height: targetHeight,
             }, ensureFileUri(capturedDoc.path), (error, result) => {
                 if (error) {
                     reject(error instanceof Error ? error : new Error('Crop failed'));
@@ -156,7 +264,7 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
                 resolve(result.image);
             });
         });
-        return base64;
+        return { base64, rectangle: rectangleToUse };
     }, [capturedDoc, cropRectangle, imageSize]);
     const handleConfirm = (0, react_1.useCallback)(async () => {
         if (!capturedDoc) {
@@ -164,11 +272,15 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
         }
         try {
             setProcessing(true);
-            const base64 = await performCrop();
+            const { base64, rectangle } = await performCrop();
             setProcessing(false);
+            const finalDoc = {
+                ...capturedDoc,
+                rectangle,
+            };
             onResult({
-                original: capturedDoc,
-                rectangle: cropRectangle,
+                original: finalDoc,
+                rectangle,
                 base64,
             });
             resetState();
@@ -177,7 +289,7 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
             setProcessing(false);
             emitError(error instanceof Error ? error : new Error(String(error)), 'Failed to process document.');
         }
-    }, [capturedDoc, cropRectangle, emitError, onResult, performCrop, resetState]);
+    }, [capturedDoc, emitError, onResult, performCrop, resetState]);
     const handleRetake = (0, react_1.useCallback)(() => {
         resetState();
     }, [resetState]);
@@ -187,13 +299,15 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
     }, [onClose, resetState]);
     return (react_1.default.createElement(react_native_1.View, { style: styles.container },
         screen === 'scanner' && (react_1.default.createElement(react_native_1.View, { style: styles.flex },
-            react_1.default.createElement(DocScanner_1.DocScanner, { autoCapture: !manualCapture, overlayColor: overlayColor, showGrid: showGrid, gridColor: resolvedGridColor, gridLineWidth: gridLineWidth, minStableFrames: minStableFrames ?? 6, detectionConfig: detectionConfig, onCapture: handleCapture },
+            react_1.default.createElement(DocScanner_1.DocScanner, { ref: docScannerRef, autoCapture: !manualCapture, overlayColor: overlayColor, showGrid: showGrid, gridColor: resolvedGridColor, gridLineWidth: gridLineWidth, minStableFrames: minStableFrames ?? 6, detectionConfig: detectionConfig, onCapture: handleCapture },
                 react_1.default.createElement(react_native_1.View, { style: styles.overlay, pointerEvents: "box-none" },
                     react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.closeButton, onPress: handleClose, accessibilityLabel: mergedStrings.cancel, accessibilityRole: "button" },
                         react_1.default.createElement(react_native_1.Text, { style: styles.closeButtonLabel }, "\u00D7")),
                     react_1.default.createElement(react_native_1.View, { style: styles.instructions, pointerEvents: "none" },
                         react_1.default.createElement(react_native_1.Text, { style: styles.captureText }, mergedStrings.captureHint),
-                        manualCapture && react_1.default.createElement(react_native_1.Text, { style: styles.captureText }, mergedStrings.manualHint)))))),
+                        react_1.default.createElement(react_native_1.Text, { style: styles.captureText }, mergedStrings.manualHint)),
+                    react_1.default.createElement(react_native_1.TouchableOpacity, { style: [styles.shutterButton, processing && styles.shutterButtonDisabled], onPress: triggerManualCapture, disabled: processing, accessibilityLabel: mergedStrings.manualHint, accessibilityRole: "button" },
+                        react_1.default.createElement(react_native_1.View, { style: styles.shutterInner })))))),
         screen === 'crop' && capturedDoc && (react_1.default.createElement(react_native_1.View, { style: styles.flex },
             react_1.default.createElement(CropEditor_1.CropEditor, { document: capturedDoc, overlayColor: "rgba(0,0,0,0.6)", overlayStrokeColor: overlayStrokeColor, handlerColor: handlerColor, onCropChange: handleCropChange }),
             react_1.default.createElement(react_native_1.View, { style: styles.cropFooter },
@@ -248,6 +362,26 @@ const styles = react_native_1.StyleSheet.create({
         fontSize: 15,
         textAlign: 'center',
     },
+    shutterButton: {
+        alignSelf: 'center',
+        width: 80,
+        height: 80,
+        borderRadius: 40,
+        borderWidth: 4,
+        borderColor: '#fff',
+        justifyContent: 'center',
+        alignItems: 'center',
+        backgroundColor: 'rgba(255,255,255,0.1)',
+    },
+    shutterButtonDisabled: {
+        opacity: 0.4,
+    },
+    shutterInner: {
+        width: 60,
+        height: 60,
+        borderRadius: 30,
+        backgroundColor: '#fff',
+    },
     cropFooter: {
         position: 'absolute',
         bottom: 40,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-rectangle-doc-scanner",
-  "version": "3.29.0",
+  "version": "3.31.0",
   "description": "Native-backed document scanner for React Native with customizable overlays.",
   "license": "MIT",
   "main": "dist/index.js",

package/src/DocScanner.tsx

@@ -36,6 +36,7 @@ export type DocScannerCapture = {
   rectangle: Rectangle | null;
   width: number;
   height: number;
+  origin: 'auto' | 'manual';
 };
 
 const isFiniteNumber = (value: unknown): value is number =>
@@ -93,6 +94,7 @@ interface Props {
   gridLineWidth?: number;
   detectionConfig?: DetectionConfig;
   onRectangleDetect?: (event: RectangleDetectEvent) => void;
+  showManualCaptureButton?: boolean;
 }
 
 export type DocScannerHandle = {
@@ -118,6 +120,7 @@ export const DocScanner = forwardRef<DocScannerHandle, Props>(
       gridLineWidth,
       detectionConfig,
       onRectangleDetect,
+      showManualCaptureButton = false,
     },
     ref,
   ) => {
@@ -129,6 +132,7 @@ export const DocScanner = forwardRef<DocScannerHandle, Props>(
     const [isAutoCapturing, setIsAutoCapturing] = useState(false);
     const [detectedRectangle, setDetectedRectangle] = useState<RectangleDetectEvent | null>(null);
     const lastRectangleRef = useRef<Rectangle | null>(null);
+    const captureOriginRef = useRef<'auto' | 'manual'>('auto');
 
     useEffect(() => {
       if (!autoCapture) {
@@ -151,6 +155,8 @@ export const DocScanner = forwardRef<DocScannerHandle, Props>(
         const normalizedRectangle =
           normalizeRectangle(event.rectangleCoordinates ?? null) ?? lastRectangleRef.current;
         const quad = normalizedRectangle ? rectangleToQuad(normalizedRectangle) : null;
+        const origin = captureOriginRef.current;
+        captureOriginRef.current = 'auto';
 
         const initialPath = event.initialImage ?? null;
         const croppedPath = event.croppedImage ?? null;
@@ -165,6 +171,7 @@ export const DocScanner = forwardRef<DocScannerHandle, Props>(
             rectangle: normalizedRectangle,
             width: event.width ?? 0,
             height: event.height ?? 0,
+            origin,
           });
         }
 
@@ -186,35 +193,52 @@ export const DocScanner = forwardRef<DocScannerHandle, Props>(
     }, []);
 
     const capture = useCallback((): Promise<PictureEvent> => {
+      captureOriginRef.current = 'manual';
       const instance = scannerRef.current;
       if (!instance || typeof instance.capture !== 'function') {
+        captureOriginRef.current = 'auto';
         return Promise.reject(new Error('DocumentScanner native instance is not ready'));
       }
       if (captureResolvers.current) {
+        captureOriginRef.current = 'auto';
         return Promise.reject(new Error('capture_in_progress'));
       }
 
-      const result = instance.capture();
+      let result: any;
+      try {
+        result = instance.capture();
+      } catch (error) {
+        captureOriginRef.current = 'auto';
+        return Promise.reject(error);
+      }
       if (result && typeof result.then === 'function') {
-        return result.then((payload: PictureEvent) => {
-          handlePictureTaken(payload);
-          return payload;
+        return result.catch((error: unknown) => {
+          captureOriginRef.current = 'auto';
+          throw error;
         });
       }
 
       return new Promise<PictureEvent>((resolve, reject) => {
-        captureResolvers.current = { resolve, reject };
+        captureResolvers.current = {
+          resolve: (value) => {
+            captureOriginRef.current = 'auto';
+            resolve(value);
+          },
+          reject: (reason) => {
+            captureOriginRef.current = 'auto';
+            reject(reason);
+          },
+        };
       });
-    }, [handlePictureTaken]);
+    }, []);
 
     const handleManualCapture = useCallback(() => {
-      if (autoCapture) {
-        return;
-      }
+      captureOriginRef.current = 'manual';
       capture().catch((error) => {
+        captureOriginRef.current = 'auto';
         console.warn('[DocScanner] manual capture failed', error);
       });
-    }, [autoCapture, capture]);
+    }, [capture]);
 
     const handleRectangleDetect = useCallback(
       (event: RectangleEventPayload) => {
@@ -255,6 +279,7 @@ export const DocScanner = forwardRef<DocScannerHandle, Props>(
             captureResolvers.current.reject(new Error('reset'));
             captureResolvers.current = null;
           }
+          captureOriginRef.current = 'auto';
         },
       }),
       [capture],
@@ -287,7 +312,9 @@ export const DocScanner = forwardRef<DocScannerHandle, Props>(
             polygon={overlayPolygon}
           />
         )}
-        {!autoCapture && <TouchableOpacity style={styles.button} onPress={handleManualCapture} />}
+        {(showManualCaptureButton || !autoCapture) && (
+          <TouchableOpacity style={styles.button} onPress={handleManualCapture} />
+        )}
         {children}
       </View>
     );

package/src/FullDocScanner.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
   ActivityIndicator,
   Alert,
@@ -12,7 +12,7 @@ import {
 import { DocScanner } from './DocScanner';
 import { CropEditor } from './CropEditor';
 import type { CapturedDocument, Point, Quad, Rectangle } from './types';
-import type { DetectionConfig } from './DocScanner';
+import type { DetectionConfig, DocScannerHandle, DocScannerCapture } from './DocScanner';
 import { quadToRectangle, scaleRectangle } from './utils/coordinate';
 
 type CustomCropManagerType = {
@@ -34,6 +34,39 @@ const stripFileUri = (value: string) => value.replace(/^file:\/\//, '');
 
 const ensureFileUri = (value: string) => (value.startsWith('file://') ? value : `file://${value}`);
 
+const createFullImageRectangle = (width: number, height: number): Rectangle => ({
+  topLeft: { x: 0, y: 0 },
+  topRight: { x: width, y: 0 },
+  bottomRight: { x: width, y: height },
+  bottomLeft: { x: 0, y: height },
+});
+
+const resolveImageSize = (
+  path: string,
+  fallbackWidth: number,
+  fallbackHeight: number,
+): Promise<{ width: number; height: number }> =>
+  new Promise((resolve) => {
+    Image.getSize(
+      ensureFileUri(path),
+      (width, height) => resolve({ width, height }),
+      () => resolve({
+        width: fallbackWidth > 0 ? fallbackWidth : 0,
+        height: fallbackHeight > 0 ? fallbackHeight : 0,
+      }),
+    );
+  });
+
+const normalizeCapturedDocument = (document: DocScannerCapture): CapturedDocument => {
+  const normalizedPath = stripFileUri(document.initialPath ?? document.path);
+  return {
+    ...document,
+    path: normalizedPath,
+    initialPath: document.initialPath ? stripFileUri(document.initialPath) : normalizedPath,
+    croppedPath: document.croppedPath ? stripFileUri(document.croppedPath) : null,
+  };
+};
+
 export interface FullDocScannerResult {
   original: CapturedDocument;
   rectangle: Rectangle | null;
@@ -90,6 +123,10 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
   const [imageSize, setImageSize] = useState<{ width: number; height: number } | null>(null);
   const [processing, setProcessing] = useState(false);
   const resolvedGridColor = gridColor ?? overlayColor;
+  const docScannerRef = useRef<DocScannerHandle | null>(null);
+  const manualCapturePending = useRef(false);
+  const processingCaptureRef = useRef(false);
+  const cropInitializedRef = useRef(false);
 
   const mergedStrings = useMemo<Required<FullDocScannerStrings>>(
     () => ({
@@ -117,7 +154,7 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
   }, [capturedDoc]);
 
   useEffect(() => {
-    if (!capturedDoc || !imageSize || cropRectangle) {
+    if (!capturedDoc || !imageSize || cropInitializedRef.current) {
       return;
     }
 
@@ -148,9 +185,10 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
     }
 
     if (initialRectangle) {
+      cropInitializedRef.current = true;
       setCropRectangle(initialRectangle);
     }
-  }, [capturedDoc, imageSize, cropRectangle]);
+  }, [capturedDoc, imageSize]);
 
   const resetState = useCallback(() => {
     setScreen('scanner');
@@ -158,35 +196,9 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
     setCropRectangle(null);
     setImageSize(null);
     setProcessing(false);
-  }, []);
-
-  const handleCapture = useCallback(
-    (document: CapturedDocument) => {
-      const normalizedPath = stripFileUri(document.path);
-      const nextQuad = document.quad && document.quad.length === 4 ? (document.quad as Quad) : null;
-      const quadRectangle = nextQuad ? quadToRectangle(nextQuad) : null;
-      const nextRectangle = document.rectangle ?? quadRectangle ?? null;
-      const normalizedInitial =
-        document.initialPath != null ? stripFileUri(document.initialPath) : normalizedPath;
-      const normalizedCropped =
-        document.croppedPath != null ? stripFileUri(document.croppedPath) : null;
-
-      setCapturedDoc({
-        ...document,
-        path: normalizedPath,
-        initialPath: normalizedInitial,
-        croppedPath: normalizedCropped,
-        quad: nextQuad,
-        rectangle: nextRectangle,
-      });
-      setCropRectangle(null);
-      setScreen('crop');
-    },
-    [],
-  );
-
-  const handleCropChange = useCallback((rectangle: Rectangle) => {
-    setCropRectangle(rectangle);
+    manualCapturePending.current = false;
+    processingCaptureRef.current = false;
+    cropInitializedRef.current = false;
   }, []);
 
   const emitError = useCallback(
@@ -200,7 +212,142 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
     [onError],
   );
 
-  const performCrop = useCallback(async (): Promise<string> => {
+  const processAutoCapture = useCallback(
+    async (document: DocScannerCapture) => {
+      manualCapturePending.current = false;
+      const normalizedDoc = normalizeCapturedDocument(document);
+      const cropManager = NativeModules.CustomCropManager as CustomCropManagerType | undefined;
+
+      if (!cropManager?.crop) {
+        emitError(new Error('CustomCropManager.crop is not available'));
+        return;
+      }
+
+      setProcessing(true);
+
+      try {
+        const size = await resolveImageSize(
+          normalizedDoc.path,
+          normalizedDoc.width,
+          normalizedDoc.height,
+        );
+
+        const targetWidthRaw = size.width > 0 ? size.width : normalizedDoc.width;
+        const targetHeightRaw = size.height > 0 ? size.height : normalizedDoc.height;
+        const baseWidth = normalizedDoc.width > 0 ? normalizedDoc.width : targetWidthRaw;
+        const baseHeight = normalizedDoc.height > 0 ? normalizedDoc.height : targetHeightRaw;
+        const targetWidth = targetWidthRaw > 0 ? targetWidthRaw : baseWidth || 1;
+        const targetHeight = targetHeightRaw > 0 ? targetHeightRaw : baseHeight || 1;
+
+        let rectangleBase: Rectangle | null = normalizedDoc.rectangle ?? null;
+        if (!rectangleBase && normalizedDoc.quad && normalizedDoc.quad.length === 4) {
+          rectangleBase = quadToRectangle(normalizedDoc.quad as Quad);
+        }
+
+        const scaledRectangle = rectangleBase
+          ? scaleRectangle(
+              rectangleBase,
+              baseWidth || targetWidth,
+              baseHeight || targetHeight,
+              targetWidth,
+              targetHeight,
+            )
+          : null;
+
+        const rectangleToUse = scaledRectangle ?? createFullImageRectangle(targetWidth, targetHeight);
+
+        const base64 = await new Promise<string>((resolve, reject) => {
+          cropManager.crop(
+            {
+              topLeft: rectangleToUse.topLeft,
+              topRight: rectangleToUse.topRight,
+              bottomRight: rectangleToUse.bottomRight,
+              bottomLeft: rectangleToUse.bottomLeft,
+              width: targetWidth,
+              height: targetHeight,
+            },
+            ensureFileUri(normalizedDoc.path),
+            (error: unknown, result: { image: string }) => {
+              if (error) {
+                reject(error instanceof Error ? error : new Error('Crop failed'));
+                return;
+              }
+              resolve(result.image);
+            },
+          );
+        });
+
+        const finalDoc: CapturedDocument = {
+          ...normalizedDoc,
+          rectangle: rectangleToUse,
+        };
+
+        onResult({
+          original: finalDoc,
+          rectangle: rectangleToUse,
+          base64,
+        });
+
+        resetState();
+      } catch (error) {
+        setProcessing(false);
+        emitError(error instanceof Error ? error : new Error(String(error)), 'Failed to process document.');
+      } finally {
+        processingCaptureRef.current = false;
+      }
+    },
+    [emitError, onResult, resetState],
+  );
+
+  const handleCapture = useCallback(
+    (document: DocScannerCapture) => {
+      if (processingCaptureRef.current) {
+        return;
+      }
+
+      const isManualCapture =
+        manualCapture || manualCapturePending.current || document.origin === 'manual';
+
+      const normalizedDoc = normalizeCapturedDocument(document);
+
+      if (isManualCapture) {
+        manualCapturePending.current = false;
+        processingCaptureRef.current = false;
+        cropInitializedRef.current = false;
+        setCapturedDoc(normalizedDoc);
+        setImageSize(null);
+        setCropRectangle(null);
+        setScreen('crop');
+        return;
+      }
+
+      processingCaptureRef.current = true;
+      processAutoCapture(document);
+    },
+    [manualCapture, processAutoCapture],
+  );
+
+  const handleCropChange = useCallback((rectangle: Rectangle) => {
+    setCropRectangle(rectangle);
+  }, []);
+
+  const triggerManualCapture = useCallback(() => {
+    if (processingCaptureRef.current) {
+      return;
+    }
+    manualCapturePending.current = true;
+    const capturePromise = docScannerRef.current?.capture();
+    if (capturePromise && typeof capturePromise.catch === 'function') {
+      capturePromise.catch((error: unknown) => {
+        manualCapturePending.current = false;
+        console.warn('[FullDocScanner] manual capture failed', error);
+      });
+    } else if (!capturePromise) {
+      manualCapturePending.current = false;
+    }
+  }, []);
+
+  const performCrop = useCallback(async (): Promise<{ base64: string; rectangle: Rectangle }> => {
     if (!capturedDoc) {
       throw new Error('No captured document to crop');
     }
@@ -214,43 +361,43 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
 
     const baseWidth = capturedDoc.width > 0 ? capturedDoc.width : size.width;
     const baseHeight = capturedDoc.height > 0 ? capturedDoc.height : size.height;
+    const targetWidth = size.width > 0 ? size.width : baseWidth || 1;
+    const targetHeight = size.height > 0 ? size.height : baseHeight || 1;
 
-    const rectangleFromDetection = capturedDoc.rectangle
-      ? scaleRectangle(
-          capturedDoc.rectangle,
-          baseWidth,
-          baseHeight,
-          size.width,
-          size.height,
-        )
-      : null;
-
-    let fallbackRectangle: Rectangle | null = rectangleFromDetection;
+    let fallbackRectangle: Rectangle | null = null;
 
-    if (!fallbackRectangle && capturedDoc.quad && capturedDoc.quad.length === 4) {
+    if (capturedDoc.rectangle) {
+      fallbackRectangle = scaleRectangle(
+        capturedDoc.rectangle,
+        baseWidth || targetWidth,
+        baseHeight || targetHeight,
+        targetWidth,
+        targetHeight,
+      );
+    } else if (capturedDoc.quad && capturedDoc.quad.length === 4) {
       const quadRectangle = quadToRectangle(capturedDoc.quad as Quad);
       if (quadRectangle) {
         fallbackRectangle = scaleRectangle(
           quadRectangle,
-          baseWidth,
-          baseHeight,
-          size.width,
-          size.height,
+          baseWidth || targetWidth,
+          baseHeight || targetHeight,
+          targetWidth,
+          targetHeight,
         );
       }
     }
 
-    const rectangle = cropRectangle ?? fallbackRectangle;
+    const rectangleToUse = cropRectangle ?? fallbackRectangle ?? createFullImageRectangle(targetWidth, targetHeight);
 
     const base64 = await new Promise<string>((resolve, reject) => {
       cropManager.crop(
         {
-          topLeft: rectangle?.topLeft ?? { x: 0, y: 0 },
-          topRight: rectangle?.topRight ?? { x: size.width, y: 0 },
-          bottomRight: rectangle?.bottomRight ?? { x: size.width, y: size.height },
-          bottomLeft: rectangle?.bottomLeft ?? { x: 0, y: size.height },
-          width: size.width,
-          height: size.height,
+          topLeft: rectangleToUse.topLeft,
+          topRight: rectangleToUse.topRight,
+          bottomRight: rectangleToUse.bottomRight,
+          bottomLeft: rectangleToUse.bottomLeft,
+          width: targetWidth,
+          height: targetHeight,
         },
         ensureFileUri(capturedDoc.path),
         (error: unknown, result: { image: string }) => {
@@ -264,7 +411,7 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
       );
     });
 
-    return base64;
+    return { base64, rectangle: rectangleToUse };
   }, [capturedDoc, cropRectangle, imageSize]);
 
   const handleConfirm = useCallback(async () => {
@@ -274,11 +421,15 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
 
     try {
       setProcessing(true);
-      const base64 = await performCrop();
+      const { base64, rectangle } = await performCrop();
       setProcessing(false);
+      const finalDoc: CapturedDocument = {
+        ...capturedDoc,
+        rectangle,
+      };
       onResult({
-        original: capturedDoc,
-        rectangle: cropRectangle,
+        original: finalDoc,
+        rectangle,
         base64,
       });
       resetState();
@@ -286,7 +437,7 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
       setProcessing(false);
       emitError(error instanceof Error ? error : new Error(String(error)), 'Failed to process document.');
     }
-  }, [capturedDoc, cropRectangle, emitError, onResult, performCrop, resetState]);
+  }, [capturedDoc, emitError, onResult, performCrop, resetState]);
 
   const handleRetake = useCallback(() => {
     resetState();
@@ -302,6 +453,7 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
       {screen === 'scanner' && (
         <View style={styles.flex}>
           <DocScanner
+            ref={docScannerRef}
             autoCapture={!manualCapture}
             overlayColor={overlayColor}
             showGrid={showGrid}
@@ -322,8 +474,17 @@ export const FullDocScanner: React.FC<FullDocScannerProps> = ({
               </TouchableOpacity>
               <View style={styles.instructions} pointerEvents="none">
                 <Text style={styles.captureText}>{mergedStrings.captureHint}</Text>
-                {manualCapture && <Text style={styles.captureText}>{mergedStrings.manualHint}</Text>}
+                <Text style={styles.captureText}>{mergedStrings.manualHint}</Text>
               </View>
+              <TouchableOpacity
+                style={[styles.shutterButton, processing && styles.shutterButtonDisabled]}
+                onPress={triggerManualCapture}
+                disabled={processing}
+                accessibilityLabel={mergedStrings.manualHint}
+                accessibilityRole="button"
+              >
+                <View style={styles.shutterInner} />
+              </TouchableOpacity>
             </View>
           </DocScanner>
         </View>
@@ -401,6 +562,26 @@ const styles = StyleSheet.create({
     fontSize: 15,
     textAlign: 'center',
   },
+  shutterButton: {
+    alignSelf: 'center',
+    width: 80,
+    height: 80,
+    borderRadius: 40,
+    borderWidth: 4,
+    borderColor: '#fff',
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: 'rgba(255,255,255,0.1)',
+  },
+  shutterButtonDisabled: {
+    opacity: 0.4,
+  },
+  shutterInner: {
+    width: 60,
+    height: 60,
+    borderRadius: 30,
+    backgroundColor: '#fff',
+  },
   cropFooter: {
     position: 'absolute',
     bottom: 40,