@trustchex/react-native-sdk 1.267.0 → 1.354.0

package/src/Shared/Components/IdentityDocumentCamera.tsx

@@ -13,6 +13,7 @@ import {
   Image,
   ActivityIndicator,
 } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import {
   Camera,
   runAtTargetFps,
@@ -44,10 +45,11 @@ import {
   OpenCV,
   ThresholdTypes,
 } from 'react-native-fast-opencv';
-import { getAverageBrightness } from '../Libs/camera.utils';
+import { getAverageBrightness, getScanAreaCenterPoint, calculateExposureStep, isBlurry as checkBlurry } from '../Libs/camera.utils';
 import { useTranslation } from 'react-i18next';
 import LottieView from 'lottie-react-native';
 import StyledButton from './StyledButton';
+import { SafeAreaView } from 'react-native-safe-area-context';
 import { type Barcode, scanCodes } from '../VisionCameraPlugins/BarcodeScanner';
 import { speakWithDebounce } from '../Libs/tts.utils';
 import AppContext from '../Contexts/AppContext';
@@ -105,10 +107,10 @@ type ElementsData = [
 export type PhotoOptions = {
   uri: string;
   orientation?:
-    | 'landscapeRight'
-    | 'portrait'
-    | 'portraitUpsideDown'
-    | 'landscapeLeft';
+  | 'landscapeRight'
+  | 'portrait'
+  | 'portraitUpsideDown'
+  | 'landscapeLeft';
 };
 
 export interface IdentityDocumentCameraProps {
@@ -135,6 +137,7 @@ const IdentityDocumentCamera = ({
 }: IdentityDocumentCameraProps) => {
   useKeepAwake();
   const theme = useTheme();
+  const insets = useSafeAreaInsets();
   const appContext = React.useContext(AppContext);
   const cameraRef = React.useRef<Camera>(null);
   const cameraPermission = useCameraPermission();
@@ -174,6 +177,7 @@ const IdentityDocumentCamera = ({
     string | undefined
   >(undefined);
   const [isBrightnessLow, setIsBrightnessLow] = useState(false);
+  const [isFrameBlurry, setIsFrameBlurry] = useState(false);
   const [hasGuideShown, setHasGuideShown] = useState(false);
   const [status, setStatus] = useState<
     'SEARCHING' | 'SCANNING' | 'SCANNED' | 'INCORRECT'
@@ -181,10 +185,17 @@ const IdentityDocumentCamera = ({
   const [nextStep, setNextStep] = useState<
     'SCAN_ID_FRONT_OR_PASSPORT' | 'SCAN_ID_BACK' | 'SCAN_HOLOGRAM' | 'COMPLETED'
   >('SCAN_ID_FRONT_OR_PASSPORT');
+  const [completedStep, setCompletedStep] = useState<
+    'SCAN_ID_FRONT_OR_PASSPORT' | 'SCAN_ID_BACK' | 'SCAN_HOLOGRAM' | null
+  >(null);
+  const [detectedDocumentType, setDetectedDocumentType] = useState<
+    'ID_FRONT' | 'ID_BACK' | 'PASSPORT' | 'UNKNOWN'
+  >('UNKNOWN');
   const hologramDetectionCurrentRetryCount = useSharedValue(0);
   const secondaryFaceDetectionCurrentRetryCount = useSharedValue(0);
   const mrzDetectionCurrentRetryCount = useSharedValue(0);
   const faceDetectionErrorCount = useSharedValue(0);
+  const consecutiveBlurCount = useSharedValue(0);
   const [faceDetectionEnabled, setFaceDetectionEnabled] = useState(true);
   const { t } = useTranslation();
   // const [boundingBox, setBoundingBox] = useState<Bounds>({
@@ -262,17 +273,64 @@ const IdentityDocumentCamera = ({
 
   useEffect(() => {
     if (hasGuideShown) {
-      const message = isBrightnessLow
-        ? t('identityDocumentCamera.lowBrightness')
-        : nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
-          ? t('identityDocumentCamera.alignPhotoSide')
-          : nextStep === 'SCAN_HOLOGRAM'
-            ? t('identityDocumentCamera.alignHologram')
-            : nextStep === 'SCAN_ID_BACK'
-              ? t('identityDocumentCamera.alignIDBackSide')
-              : nextStep === 'COMPLETED'
-                ? t('identityDocumentCamera.scanCompleted')
-                : '';
+      let message = '';
+
+      // Priority: scanned > incorrect > blur during scanning > brightness > blur > step-specific
+      if (status === 'SCANNED') {
+        // Use step-specific completion messages
+        if (completedStep === 'SCAN_ID_FRONT_OR_PASSPORT') {
+          message = detectedDocumentType === 'PASSPORT'
+            ? t('identityDocumentCamera.passportScanned')
+            : t('identityDocumentCamera.frontSideScanned');
+        } else if (completedStep === 'SCAN_ID_BACK') {
+          message = t('identityDocumentCamera.backSideScanned');
+        } else if (completedStep === 'SCAN_HOLOGRAM') {
+          message = t('identityDocumentCamera.hologramVerified');
+        } else {
+          message = t('identityDocumentCamera.scanCompleted');
+        }
+      } else if (status === 'INCORRECT') {
+        // Wrong side detected - warn user
+        if (nextStep === 'SCAN_ID_FRONT_OR_PASSPORT') {
+          message = t('identityDocumentCamera.wrongSideFront');
+        } else if (nextStep === 'SCAN_ID_BACK') {
+          message = t('identityDocumentCamera.wrongSideBack');
+        }
+      } else if (isBrightnessLow) {
+        // Brightness warning takes priority over blur
+        message = t('identityDocumentCamera.lowBrightness');
+      } else if (isFrameBlurry) {
+        // Show blur warning only when brightness is sufficient
+        message = t('identityDocumentCamera.avoidBlur');
+      } else if (nextStep === 'SCAN_ID_FRONT_OR_PASSPORT') {
+        // Enhanced feedback based on detection status
+        if (status === 'SCANNING') {
+          if (currentFaceImage) {
+            // Document-specific detection message
+            if (detectedDocumentType === 'PASSPORT') {
+              message = t('identityDocumentCamera.passportDetected');
+            } else if (detectedDocumentType === 'ID_FRONT') {
+              message = t('identityDocumentCamera.idCardFrontDetected');
+            } else {
+              message = t('identityDocumentCamera.readingDocument');
+            }
+          } else {
+            message = t('identityDocumentCamera.readingDocument');
+          }
+        } else {
+          message = t('identityDocumentCamera.alignPhotoSide');
+        }
+      } else if (nextStep === 'SCAN_HOLOGRAM') {
+        message = t('identityDocumentCamera.alignHologram');
+      } else if (nextStep === 'SCAN_ID_BACK') {
+        if (status === 'SCANNING') {
+          message = t('identityDocumentCamera.readingDocument');
+        } else {
+          message = t('identityDocumentCamera.alignIDBackSide');
+        }
+      } else if (nextStep === 'COMPLETED') {
+        message = t('identityDocumentCamera.scanCompleted');
+      }
 
       if (
         appContext.currentWorkflowStep?.data?.voiceGuidanceActive &&
@@ -285,10 +343,58 @@ const IdentityDocumentCamera = ({
     appContext.currentWorkflowStep?.data?.voiceGuidanceActive,
     hasGuideShown,
     isBrightnessLow,
+    isFrameBlurry,
     nextStep,
+    status,
+    completedStep,
+    currentFaceImage,
+    detectedDocumentType,
     t,
   ]);
 
+  // Auto-reset INCORRECT status after showing warning briefly
+  useEffect(() => {
+    if (status === 'INCORRECT') {
+      const timeout = setTimeout(() => {
+        setStatus('SEARCHING');
+      }, 1500); // Show warning for 1.5 seconds
+      return () => clearTimeout(timeout);
+    }
+  }, [status]);
+
+  // Periodic autofocus - refocus on scan area center every 2.5 seconds
+  useEffect(() => {
+    if (!isActive || !device || !cameraRef.current || !device.supportsFocus) {
+      return;
+    }
+
+    // Only autofocus during searching and scanning states
+    if (status !== 'SEARCHING' && status !== 'SCANNING') {
+      return;
+    }
+
+    const autofocusInterval = setInterval(async () => {
+      try {
+        // Get camera dimensions (assuming format dimensions)
+        const width = format?.videoWidth ?? 1920;
+        const height = format?.videoHeight ?? 1080;
+
+        // Calculate center point of scan area
+        const centerPoint = getScanAreaCenterPoint(width, height);
+
+        // Focus on the center of the scan area
+        await cameraRef.current?.focus({
+          x: centerPoint.x,
+          y: centerPoint.y,
+        });
+      } catch (error) {
+        // Ignore autofocus errors
+      }
+    }, 2500); // Every 2.5 seconds
+
+    return () => clearInterval(autofocusInterval);
+  }, [isActive, device, format, status]);
+
   const detectDocumentType = (
     faces: Face[],
     ocrText: string,
@@ -411,6 +517,7 @@ const IdentityDocumentCamera = ({
     }
   };
 
+
   const detectHologram = (images: string[]) => {
     try {
       const lowerBound = OpenCV.createObject(ObjectType.Scalar, 40, 90, 90);
@@ -587,10 +694,26 @@ const IdentityDocumentCamera = ({
       | 'SCAN_ID_FRONT_OR_PASSPORT'
       | 'SCAN_ID_BACK'
       | 'SCAN_HOLOGRAM'
-      | 'COMPLETED'
+      | 'COMPLETED',
+    fromStep?:
+      | 'SCAN_ID_FRONT_OR_PASSPORT'
+      | 'SCAN_ID_BACK'
+      | 'SCAN_HOLOGRAM'
   ) => {
+    // Track which step was just completed for showing specific message
+    if (fromStep) {
+      setCompletedStep(fromStep);
+    }
     setNextStep(nextStepType);
     Vibration.vibrate(100);
+
+    // Reset status after delay to show success animation fully before next step
+    if (nextStepType !== 'COMPLETED') {
+      setTimeout(() => {
+        setStatus('SEARCHING');
+        setCompletedStep(null);
+      }, 2000); // Show success checkmark for 2 seconds before transitioning
+    }
   };
 
   const handleBrightness = useRunOnJS(
@@ -600,6 +723,13 @@ const IdentityDocumentCamera = ({
     [setIsBrightnessLow]
   );
 
+  const handleBlurStatus = useRunOnJS(
+    (blurry: boolean) => {
+      setIsFrameBlurry(blurry);
+    },
+    [setIsFrameBlurry]
+  );
+
   const handleFaceAndText = useRunOnJS(
     async (
       text: string,
@@ -614,7 +744,7 @@ const IdentityDocumentCamera = ({
         isTorchOn &&
         (currentHologramImage ||
           hologramDetectionCurrentRetryCount.value >=
-            HOLOGRAM_DETECTION_RETRY_COUNT)
+          HOLOGRAM_DETECTION_RETRY_COUNT)
       ) {
         setIsTorchOn(false);
       }
@@ -624,7 +754,18 @@ const IdentityDocumentCamera = ({
         return;
       }
 
+      // Early wrong side detection for SCAN_ID_BACK: if faces detected, it's the front side
+      if (nextStep === 'SCAN_ID_BACK' && faces.length > 0) {
+        console.log('[WRONG_SIDE] Back side expected but faces detected:', faces.length);
+        setStatus('INCORRECT');
+        return;
+      }
+
       if (!text || text.length < 10 || !image) {
+        // Log when searching to help debug
+        if (nextStep === 'SCAN_ID_BACK') {
+          console.log('[SCAN_ID_BACK] Searching... faces:', faces.length, 'text length:', text?.length || 0);
+        }
         setStatus('SEARCHING');
         return;
       }
@@ -652,16 +793,24 @@ const IdentityDocumentCamera = ({
       scannedData.faceImage = croppedFaces[0];
       setCurrentFaceImage(croppedFaces[0]);
 
-      if (!onlyMRZScan) {
-        if (
-          (nextStep === 'SCAN_ID_FRONT_OR_PASSPORT' &&
-            !(documentType === 'ID_FRONT' || documentType === 'PASSPORT')) ||
-          (nextStep === 'SCAN_ID_BACK' && documentType !== 'ID_BACK')
-        ) {
-          setStatus('INCORRECT');
-          return;
-        }
+      // Track detected document type for UI feedback
+      if (documentType !== 'UNKNOWN') {
+        setDetectedDocumentType(documentType);
+      }
+
+      // Detect wrong side based on document type or face presence (works for both normal and eID scan)
+      // For ID_BACK step: if faces are detected, it's likely the front side (wrong)
+      // For FRONT step: if ID_BACK is detected, it's the wrong side
+      const isWrongSide =
+        (nextStep === 'SCAN_ID_FRONT_OR_PASSPORT' && documentType === 'ID_BACK') ||
+        (nextStep === 'SCAN_ID_BACK' && (documentType === 'ID_FRONT' || documentType === 'PASSPORT' || croppedFaces.length > 0));
+
+      if (isWrongSide) {
+        setStatus('INCORRECT');
+        return;
+      }
 
+      if (!onlyMRZScan) {
         if (croppedFaces.length > 0 && croppedFaces[0]) {
           if (currentFaceImage) {
             scannedData.faceImage = currentFaceImage;
@@ -711,22 +860,22 @@ const IdentityDocumentCamera = ({
         if (nextStep === 'SCAN_ID_FRONT_OR_PASSPORT') {
           setStatus('SCANNED');
           if (onlyMRZScan) {
-            setNextStepAndVibrate('SCAN_ID_BACK');
+            setNextStepAndVibrate('SCAN_ID_BACK', 'SCAN_ID_FRONT_OR_PASSPORT');
             onIdentityDocumentScanned(scannedData);
           } else {
-            setNextStepAndVibrate('SCAN_HOLOGRAM');
+            setNextStepAndVibrate('SCAN_HOLOGRAM', 'SCAN_ID_FRONT_OR_PASSPORT');
           }
         } else if (
           nextStep === 'SCAN_HOLOGRAM' &&
           (!!scannedData.hologramImage ||
             hologramDetectionCurrentRetryCount.value >=
-              HOLOGRAM_DETECTION_RETRY_COUNT) &&
+            HOLOGRAM_DETECTION_RETRY_COUNT) &&
           (!!scannedData.secondaryFaceImage ||
             secondaryFaceDetectionCurrentRetryCount.value >=
-              SECOND_FACE_DETECTION_RETRY_COUNT)
+            SECOND_FACE_DETECTION_RETRY_COUNT)
         ) {
           setStatus('SCANNED');
-          setNextStepAndVibrate('SCAN_ID_BACK');
+          setNextStepAndVibrate('SCAN_ID_BACK', 'SCAN_HOLOGRAM');
           onIdentityDocumentScanned(scannedData);
         }
       } else if (documentType === 'PASSPORT') {
@@ -734,28 +883,41 @@ const IdentityDocumentCamera = ({
           nextStep === 'SCAN_ID_FRONT_OR_PASSPORT' &&
           !scannedData.hologramImage
         ) {
-          setStatus('SCANNED');
+          // For passport, require valid MRZ before proceeding
           if (onlyMRZScan) {
-            setNextStepAndVibrate('COMPLETED');
-            onIdentityDocumentScanned(scannedData);
+            // eID scan: require valid MRZ
+            if (
+              !!scannedData.mrzText &&
+              (parsedMRZData?.valid ||
+                mrzDetectionCurrentRetryCount.value >= MRZ_VALIDATION_RETRY_COUNT)
+            ) {
+              setStatus('SCANNED');
+              setNextStepAndVibrate('COMPLETED', 'SCAN_ID_FRONT_OR_PASSPORT');
+              onIdentityDocumentScanned(scannedData);
+            } else if (!parsedMRZData?.valid) {
+              mrzDetectionCurrentRetryCount.value++;
+              setStatus('SCANNING');
+            }
           } else {
-            setNextStepAndVibrate('SCAN_HOLOGRAM');
+            // Normal scan: proceed to hologram check (MRZ validated later)
+            setStatus('SCANNED');
+            setNextStepAndVibrate('SCAN_HOLOGRAM', 'SCAN_ID_FRONT_OR_PASSPORT');
           }
         } else if (
           ((nextStep === 'SCAN_HOLOGRAM' &&
             (!!scannedData.hologramImage ||
               hologramDetectionCurrentRetryCount.value >=
-                HOLOGRAM_DETECTION_RETRY_COUNT) &&
+              HOLOGRAM_DETECTION_RETRY_COUNT) &&
             (!!scannedData.secondaryFaceImage ||
               secondaryFaceDetectionCurrentRetryCount.value >=
-                SECOND_FACE_DETECTION_RETRY_COUNT)) ||
+              SECOND_FACE_DETECTION_RETRY_COUNT)) ||
             onlyMRZScan) &&
           !!scannedData.mrzText &&
           (parsedMRZData?.valid ||
             mrzDetectionCurrentRetryCount.value >= MRZ_VALIDATION_RETRY_COUNT)
         ) {
           setStatus('SCANNED');
-          setNextStepAndVibrate('COMPLETED');
+          setNextStepAndVibrate('COMPLETED', 'SCAN_HOLOGRAM');
           onIdentityDocumentScanned(scannedData);
         } else if (!parsedMRZData?.valid) {
           mrzDetectionCurrentRetryCount.value++;
@@ -764,7 +926,7 @@ const IdentityDocumentCamera = ({
         if (
           ((parsedMRZData?.fields?.issuingState === 'TUR' &&
             barcode?.value?.trim() ===
-              parsedMRZData?.fields?.optional1?.trim()) ||
+            parsedMRZData?.fields?.optional1?.trim()) ||
             parsedMRZData?.fields?.issuingState !== 'TUR' ||
             onlyMRZScan) &&
           nextStep === 'SCAN_ID_BACK' &&
@@ -774,7 +936,7 @@ const IdentityDocumentCamera = ({
         ) {
           scannedData.barcodeValue = barcode?.value ?? undefined;
           setStatus('SCANNED');
-          setNextStepAndVibrate('COMPLETED');
+          setNextStepAndVibrate('COMPLETED', 'SCAN_ID_BACK');
           onIdentityDocumentScanned(scannedData);
         } else if (!parsedMRZData?.valid) {
           mrzDetectionCurrentRetryCount.value++;
@@ -808,25 +970,63 @@ const IdentityDocumentCamera = ({
     [exposure]
   );
 
+  // Focus trigger for when blur is detected (called from worklet)
+  const triggerFocus = useRunOnJS(
+    async () => {
+      if (!cameraRef.current || !device?.supportsFocus) {
+        return;
+      }
+      try {
+        const width = format?.videoWidth ?? 1920;
+        const height = format?.videoHeight ?? 1080;
+        const centerPoint = getScanAreaCenterPoint(width, height);
+        await cameraRef.current.focus({
+          x: centerPoint.x,
+          y: centerPoint.y,
+        });
+      } catch (error) {
+        // Ignore focus errors
+      }
+    },
+    [device, format]
+  );
+
   const handleExposureAndBrightness = (frame: Frame) => {
     'worklet';
     const averageBrightness = getAverageBrightness(frame);
     const minExposure = device?.minExposure ?? 0;
     const maxExposure = device?.maxExposure ?? 0;
-    const lowerBrightnessBound = 40;
-    const upperBrightnessBound = 120;
+
+    // Dynamic thresholds based on scanning state using config values
+    // Face detection requires higher minimum brightness for reliable detection
+    const isFrontOrPassport = nextStep === 'SCAN_ID_FRONT_OR_PASSPORT';
+    const isBack = nextStep === 'SCAN_ID_BACK';
+
+    // Using config values: faceDetection { low: 50, high: 110, target: 85 }, mrzScanning { low: 45, high: 130, target: 80 }
+    const lowerBrightnessBound = isFrontOrPassport ? 50 : 40;
+    const upperBrightnessBound = isBack ? 130 : 120;
+    const targetBrightness = isFrontOrPassport ? 85 : 80;
+
+    // Smooth exposure adjustment with hysteresis to prevent oscillation
+    // Only adjust if brightness is significantly outside the acceptable range
+    const hysteresis = 5; // Dead zone to prevent jitter
 
     if (
-      averageBrightness < lowerBrightnessBound &&
+      averageBrightness < (lowerBrightnessBound - hysteresis) &&
       exposureValue.value < maxExposure
     ) {
-      exposureValue.value = exposureValue.value + 1;
+      // Increase exposure smoothly when too dark
+      const step = calculateExposureStep(averageBrightness, targetBrightness);
+      exposureValue.value = Math.min(maxExposure, exposureValue.value + step);
     } else if (
-      averageBrightness > upperBrightnessBound &&
+      averageBrightness > (upperBrightnessBound + hysteresis) &&
       exposureValue.value > minExposure
     ) {
-      exposureValue.value = exposureValue.value - 1;
+      // Decrease exposure smoothly when too bright
+      const step = calculateExposureStep(averageBrightness, targetBrightness);
+      exposureValue.value = Math.max(minExposure, exposureValue.value - step);
     }
+    // When within acceptable range (with hysteresis), don't adjust - prevents oscillation
 
     const isBright = averageBrightness > lowerBrightnessBound;
     handleExposureValue(exposureValue.value);
@@ -843,6 +1043,28 @@ const IdentityDocumentCamera = ({
         return;
       }
 
+
+
+      // Check for blur before processing - skip blurry frames
+      // Use different thresholds: 25 for front (face detection), 30 for back (MRZ/text)
+      // Higher thresholds with improved Laplacian algorithm using H+V gradients
+      const isFront = nextStep === 'SCAN_ID_FRONT_OR_PASSPORT';
+      const blurThreshold = isFront ? 25 : 30;
+      const blurry = checkBlurry(frame, blurThreshold);
+      handleBlurStatus(blurry);
+      if (blurry) {
+        consecutiveBlurCount.value++;
+        // Only trigger focus after 2 consecutive blurry frames (matching Flutter)
+        if (consecutiveBlurCount.value >= 2) {
+          triggerFocus();
+          consecutiveBlurCount.value = 0;
+        }
+        return;
+      }
+      // Reset blur count on sharp frame
+      consecutiveBlurCount.value = 0;
+
+
       // Validate frame dimensions before processing
       if (
         !frame.width ||
@@ -901,6 +1123,8 @@ const IdentityDocumentCamera = ({
       }
 
       // Text recognition with error handling
+      // Note: CLAHE enhancement is applied to captured images, not live frames
+      // ML Kit plugins work directly on Frame objects and don't support Mat input
       let scannedText: BlockText;
       try {
         scannedText = scanText(frame) as any as BlockText;
@@ -972,15 +1196,15 @@ const IdentityDocumentCamera = ({
 
   if (!permissionsRequested) {
     return (
-      <View style={styles.permissionContainer}>
+      <SafeAreaView style={styles.permissionContainer}>
         <ActivityIndicator size="large" color={theme.colors.primary} />
-      </View>
+      </SafeAreaView>
     );
   }
 
   if (!cameraPermission.hasPermission) {
     return (
-      <View style={styles.permissionContainer}>
+      <SafeAreaView style={styles.permissionContainer}>
         <Text style={styles.permissionText}>
           {t('general.noCameraPermissionGiven')}
         </Text>
@@ -992,17 +1216,17 @@ const IdentityDocumentCamera = ({
         >
           {t('general.openSettings')}
         </StyledButton>
-      </View>
+      </SafeAreaView>
     );
   }
 
   if (device == null) {
     return (
-      <View style={styles.permissionContainer}>
+      <SafeAreaView style={styles.permissionContainer}>
         <TextView style={styles.permissionText}>
           {t('general.noCameraDetected')}
         </TextView>
-      </View>
+      </SafeAreaView>
     );
   }
 
@@ -1023,7 +1247,7 @@ const IdentityDocumentCamera = ({
   return (
     <View style={StyleSheet.absoluteFill}>
       {!hasGuideShown ? (
-        <View style={styles.guide}>
+        <SafeAreaView style={styles.guide}>
           <LottieView
             source={require('../../Shared/Animations/id-or-passport.json')}
             style={styles.guideAnimation}
@@ -1055,7 +1279,7 @@ const IdentityDocumentCamera = ({
           >
             {t('general.letsGo')}
           </StyledButton>
-        </View>
+        </SafeAreaView>
       ) : (
         <>
           <Camera
@@ -1075,19 +1299,74 @@ const IdentityDocumentCamera = ({
               isCameraInitialized.value = true;
             }}
           />
-          <View style={styles.topZone}>
-            <TextView style={styles.topZoneText}>
-              {isBrightnessLow
-                ? t('identityDocumentCamera.lowBrightness')
-                : nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
-                  ? t('identityDocumentCamera.alignPhotoSide')
+          <View style={[styles.topZone, { paddingTop: insets.top }]}>
+            {/* Step Progress Indicator - show only after document type detected and not completed/scanned */}
+            {nextStep !== 'COMPLETED' && status !== 'SCANNED' && detectedDocumentType !== 'UNKNOWN' && (
+              <TextView style={styles.stepIndicator}>
+                {nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
+                  ? `${t('identityDocumentCamera.frontSide')} • ${t('identityDocumentCamera.stepProgress', {
+                    current: 1,
+                    total: onlyMRZScan
+                      ? (detectedDocumentType === 'PASSPORT' ? 1 : 2)
+                      : (detectedDocumentType === 'PASSPORT' ? 2 : 3)
+                  })}`
                   : nextStep === 'SCAN_HOLOGRAM'
-                    ? t('identityDocumentCamera.alignHologram')
+                    ? `${t('identityDocumentCamera.hologramCheck')} • ${t('identityDocumentCamera.stepProgress', {
+                      current: 2,
+                      total: detectedDocumentType === 'PASSPORT' ? 2 : 3
+                    })}`
                     : nextStep === 'SCAN_ID_BACK'
-                      ? t('identityDocumentCamera.alignIDBackSide')
-                      : nextStep === 'COMPLETED'
-                        ? t('identityDocumentCamera.scanCompleted')
-                        : ''}
+                      ? `${t('identityDocumentCamera.backSide')} • ${t('identityDocumentCamera.stepProgress', { current: 3, total: 3 })}`
+                      : ''}
+              </TextView>
+            )}
+            {/* Status-based guidance text */}
+            <TextView style={[
+              styles.topZoneText,
+              status === 'SCANNING' && styles.topZoneTextScanning,
+              status === 'SCANNED' && styles.topZoneTextSuccess,
+              status === 'INCORRECT' && styles.topZoneTextError,
+              (isBrightnessLow || isFrameBlurry) && styles.topZoneTextWarning,
+            ]}>
+              {status === 'SCANNED'
+                ? completedStep === 'SCAN_ID_FRONT_OR_PASSPORT'
+                  ? detectedDocumentType === 'PASSPORT'
+                    ? t('identityDocumentCamera.passportScanned')
+                    : t('identityDocumentCamera.frontSideScanned')
+                  : completedStep === 'SCAN_ID_BACK'
+                    ? t('identityDocumentCamera.backSideScanned')
+                    : completedStep === 'SCAN_HOLOGRAM'
+                      ? t('identityDocumentCamera.hologramVerified')
+                      : t('identityDocumentCamera.scanCompleted')
+                : status === 'INCORRECT'
+                  ? nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
+                    ? t('identityDocumentCamera.wrongSideFront')
+                    : nextStep === 'SCAN_ID_BACK'
+                      ? t('identityDocumentCamera.wrongSideBack')
+                      : t('identityDocumentCamera.alignPhotoSide')
+                  : isBrightnessLow
+                    ? t('identityDocumentCamera.lowBrightness')
+                    : isFrameBlurry
+                      ? t('identityDocumentCamera.avoidBlur')
+                      : nextStep === 'SCAN_ID_FRONT_OR_PASSPORT'
+                        ? status === 'SCANNING'
+                          ? currentFaceImage
+                            ? detectedDocumentType === 'PASSPORT'
+                              ? t('identityDocumentCamera.passportDetected')
+                              : detectedDocumentType === 'ID_FRONT'
+                                ? t('identityDocumentCamera.idCardFrontDetected')
+                                : t('identityDocumentCamera.readingDocument')
+                            : t('identityDocumentCamera.readingDocument')
+                          : t('identityDocumentCamera.alignPhotoSide')
+                        : nextStep === 'SCAN_HOLOGRAM'
+                          ? t('identityDocumentCamera.alignHologram')
+                          : nextStep === 'SCAN_ID_BACK'
+                            ? status === 'SCANNING'
+                              ? t('identityDocumentCamera.readingDocument')
+                              : t('identityDocumentCamera.alignIDBackSide')
+                            : nextStep === 'COMPLETED'
+                              ? t('identityDocumentCamera.scanCompleted')
+                              : ''}
             </TextView>
           </View>
           <View style={styles.leftZone} />
@@ -1154,19 +1433,16 @@ const IdentityDocumentCamera = ({
                   Status: {status}
                 </TextView>
                 <TextView style={styles.debugInfoText}>
-                  {`Face: ${currentFaceImage ? '✓' : '✗'} ${
-                    !faceDetectionEnabled ? '(DISABLED)' : ''
-                  }`}
+                  {`Face: ${currentFaceImage ? '✓' : '✗'} ${!faceDetectionEnabled ? '(DISABLED)' : ''
+                    }`}
                 </TextView>
                 <TextView style={styles.debugInfoText}>
-                  {`Hologram: ${currentHologramImage ? '✓' : '✗'} (${
-                    hologramDetectionCurrentRetryCount.value
-                  }/${HOLOGRAM_DETECTION_RETRY_COUNT})`}
+                  {`Hologram: ${currentHologramImage ? '✓' : '✗'} (${hologramDetectionCurrentRetryCount.value
+                    }/${HOLOGRAM_DETECTION_RETRY_COUNT})`}
                 </TextView>
                 <TextView style={styles.debugInfoText}>
-                  {`2nd Face: ${currentSecondaryFaceImage ? '✓' : '✗'} (${
-                    secondaryFaceDetectionCurrentRetryCount.value
-                  }/${SECOND_FACE_DETECTION_RETRY_COUNT})`}
+                  {`2nd Face: ${currentSecondaryFaceImage ? '✓' : '✗'} (${secondaryFaceDetectionCurrentRetryCount.value
+                    }/${SECOND_FACE_DETECTION_RETRY_COUNT})`}
                 </TextView>
               </View>
             )}
@@ -1177,51 +1453,54 @@ const IdentityDocumentCamera = ({
               {
                 borderColor:
                   status === 'SCANNED' || nextStep === 'COMPLETED'
-                    ? 'green'
+                    ? '#4CAF50' // Green - success
                     : status === 'INCORRECT'
-                      ? 'red'
-                      : 'white',
+                      ? '#f44336' // Red - error
+                      : status === 'SCANNING'
+                        ? '#2196F3' // Blue - processing
+                        : isBrightnessLow || isFrameBlurry
+                          ? '#FFC107' // Yellow - warning
+                          : 'white',
+                borderWidth: status === 'SCANNING' ? 3 : 2,
               },
             ]}
           >
-            {nextStep === 'SCAN_HOLOGRAM' && isTorchOn && !isBrightnessLow && (
+            {/* Only show ONE animation at a time - priority order: completed/scanned > brightness > hologram > scanning */}
+            {nextStep === 'COMPLETED' || status === 'SCANNED' ? (
               <LottieView
-                source={require('../../Shared/Animations/hologram-scan.json')}
+                source={require('../../Shared/Animations/success.json')}
                 style={styles.animation}
-                loop={true}
+                loop={false}
                 autoPlay
               />
-            )}
-            {nextStep !== 'COMPLETED' && isBrightnessLow && (
+            ) : isBrightnessLow ? (
               <LottieView
                 source={require('../../Shared/Animations/light.json')}
                 style={styles.animation}
                 loop={true}
                 autoPlay
               />
-            )}
-            {nextStep === 'COMPLETED' && (
+            ) : nextStep === 'SCAN_HOLOGRAM' && isTorchOn ? (
               <LottieView
-                source={require('../../Shared/Animations/success.json')}
+                source={require('../../Shared/Animations/hologram-scan.json')}
                 style={styles.animation}
-                loop={false}
+                loop={true}
                 autoPlay
               />
-            )}
+            ) : status === 'SCANNING' ? (
+              <LottieView
+                source={require('../../Shared/Animations/scanning.json')}
+                style={styles.animation}
+                loop={true}
+                autoPlay
+              />
+            ) : null}
           </View>
-          {/* <View
-            style={{
-              borderColor: 'red',
-              borderWidth: 1,
-              position: 'absolute',
-              top: boundingBox.y,
-              left: boundingBox.x,
-              width: boundingBox.width,
-              height: boundingBox.height,
-              zIndex: 3,
-            }}
-          /> */}
-          <TouchableOpacity onPress={handleFocus} style={styles.focusArea} />
+          <TouchableOpacity
+            onPress={handleFocus}
+            style={styles.focusArea}
+            activeOpacity={1}
+          />
         </>
       )}
     </View>
@@ -1281,6 +1560,13 @@ const styles = StyleSheet.create({
     justifyContent: 'flex-end',
     alignItems: 'center',
   },
+  stepIndicator: {
+    color: '#aaaaaa',
+    fontSize: 14,
+    textAlign: 'center',
+    fontWeight: '500',
+    marginBottom: 4,
+  },
   topZoneText: {
     color: 'white',
     fontSize: 20,
@@ -1288,6 +1574,18 @@ const styles = StyleSheet.create({
     fontWeight: 'bold',
     padding: 20,
   },
+  topZoneTextScanning: {
+    color: '#2196F3', // Blue when scanning
+  },
+  topZoneTextSuccess: {
+    color: '#4CAF50', // Green for success
+  },
+  topZoneTextWarning: {
+    color: '#FFC107', // Yellow for warnings
+  },
+  topZoneTextError: {
+    color: '#f44336', // Red for errors
+  },
   leftZone: {
     position: 'absolute',
     top: '36%',