@trustchex/react-native-sdk 1.497.0 → 1.500.2

package/lib/module/Screens/Static/ResultScreen.js

@@ -1,7 +1,7 @@
 "use strict";
 
 import React, { useCallback, useContext, useEffect, useMemo, useState } from 'react';
-import { Alert, Image, Platform, SafeAreaView, ScrollView, StyleSheet, Text, View } from 'react-native';
+import { Image, Platform, SafeAreaView, ScrollView, StyleSheet, Text, View } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import AppContext from "../../Shared/Contexts/AppContext.js";
 import httpClient, { getSessionToken } from "../../Shared/Libs/http-client.js";
@@ -48,13 +48,27 @@ const collectDiagnosticImages = doc => {
 import { trackError, trackFunnelStep, useScreenTracking } from "../../Shared/Libs/analytics.utils.js";
 import { analyticsService } from "../../Shared/Services/AnalyticsService.js";
 import { AnalyticsEventName, AnalyticsEventCategory } from "../../Shared/Types/analytics.types.js";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const ResultScreen = () => {
   const appContext = useContext(AppContext);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [progress, setProgress] = useState(0);
+  // Set when submit() fails — drives a recoverable error UI with a "Retry"
+  // button instead of wiping the whole flow back to the start (which forced a
+  // full re-scan + re-liveness on any transient final-step failure).
+  const [submitFailed, setSubmitFailed] = useState(false);
   const navigationManagerRef = React.useRef(null);
   const hasSubmittedRef = React.useRef(false);
+  // Tracks which submit steps already succeeded so a retry RESUMES from the
+  // failed step instead of re-running earlier ones. submit() is a chain of
+  // non-idempotent POSTs (consent/document/media/videos), so a naive full
+  // retry after a partial success could create duplicate server-side records.
+  const completedSteps = React.useRef({
+    consent: false,
+    document: false,
+    media: false,
+    verbalConsentVideos: false
+  });
   const [shouldShowDemoData, setShouldShowDemoData] = useState(false);
   const [deviceIdentifier, setDeviceIdentifier] = useState('');
   const {
@@ -383,29 +397,48 @@ const ResultScreen = () => {
   const submit = useCallback(async identificationInfo => {
     try {
       setIsSubmitting(true);
+      setSubmitFailed(false);
       const identificationId = identificationInfo.identificationId;
       if (!identificationId) {
         throw new Error('IdentificationId not found');
       }
       const alreadyUploaded = !!identificationInfo.mediaUploadedDuringVideoCall;
       const sessionKey = await runWithRetry(() => getSessionKey(apiUrl, appContext.identificationInfo.sessionId));
+
+      // createIdentification is effectively idempotent (creates/verifies the
+      // record), so it's safe to re-run on retry without a guard.
       if (!alreadyUploaded) {
         await runWithRetry(() => createIdentification(identificationId));
       }
       setProgress(20);
-      await runWithRetry(() => submitIdentificationConsent(identificationId, sessionKey));
+
+      // Each POST below is guarded by completedSteps so a retry skips work
+      // that already committed server-side (avoiding duplicate records).
+      if (!completedSteps.current.consent) {
+        await runWithRetry(() => submitIdentificationConsent(identificationId, sessionKey));
+        completedSteps.current.consent = true;
+      }
       setProgress(30);
       if (!alreadyUploaded) {
         const scannedIdentityDocument = identificationInfo.scannedDocument;
-        if (scannedIdentityDocument && scannedIdentityDocument.documentType !== 'UNKNOWN') {
+        if (!completedSteps.current.document && scannedIdentityDocument && scannedIdentityDocument.documentType !== 'UNKNOWN') {
           await runWithRetry(() => submitIdentificationDocument(identificationId, scannedIdentityDocument, sessionKey));
+          completedSteps.current.document = true;
         }
         setProgress(40);
-        const livenessDetection = identificationInfo.livenessDetection;
-        await runWithRetry(() => uploadIdentificationMedia(identificationId, scannedIdentityDocument, livenessDetection, false));
+        if (!completedSteps.current.media) {
+          const livenessDetection = identificationInfo.livenessDetection;
+          await runWithRetry(() => uploadIdentificationMedia(identificationId, scannedIdentityDocument, livenessDetection, false));
+          completedSteps.current.media = true;
+        }
+      }
+      if (!completedSteps.current.verbalConsentVideos) {
+        await runWithRetry(() => uploadVerbalConsentVideos(identificationId, identificationInfo.verbalConsentVideos));
+        completedSteps.current.verbalConsentVideos = true;
       }
-      await runWithRetry(() => uploadVerbalConsentVideos(identificationId, identificationInfo.verbalConsentVideos));
       setProgress(90);
+
+      // finishIdentification is a PUT (idempotent) — always safe to re-run.
       await runWithRetry(() => finishIdentification(identificationId, sessionKey));
       setProgress(100);
       setIsSubmitting(false);
@@ -422,16 +455,21 @@ const ResultScreen = () => {
       // Track verification failure
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
       trackError('VERIFICATION_SUBMISSION_FAILED', errorMessage, 'result_screen', 'critical', {
-        recoverable: false,
+        recoverable: true,
         userAction: 'submit_verification'
       }).catch(() => {});
       analyticsService.trackEvent(AnalyticsEventName.VERIFICATION_FAILED, AnalyticsEventCategory.VERIFICATION, {
         sessionId: appContext.identificationInfo.sessionId || '',
         errorMessage
       }).catch(() => {});
-      Alert.alert(t('general.error'), t('resultScreen.submissionFailed'));
+
+      // Show a recoverable error UI with a Retry button instead of resetting
+      // the whole flow. The collected data is still intact in AppContext, and
+      // completedSteps ensures a retry resumes from the failed step. We notify
+      // the host via onError but do NOT tear the flow down — the user can
+      // retry without re-scanning their document or redoing liveness.
       appContext.onError?.(t('resultScreen.submissionFailed'));
-      navigationManagerRef.current?.reset();
+      setSubmitFailed(true);
     }
   }, [createIdentification, apiUrl, uploadIdentificationMedia, uploadVerbalConsentVideos, finishIdentification, submitIdentificationDocument, submitIdentificationConsent, t, appContext]);
   useEffect(() => {
@@ -464,7 +502,35 @@ const ResultScreen = () => {
     style: styles.container,
     children: /*#__PURE__*/_jsxs(View, {
       style: styles.container,
-      children: [isSubmitting ? /*#__PURE__*/_jsxs(_Fragment, {
+      children: [submitFailed && !isSubmitting ? /*#__PURE__*/_jsxs(View, {
+        style: styles.submitErrorContainer,
+        children: [/*#__PURE__*/_jsx(Text, {
+          style: styles.submitErrorTitle,
+          children: t('resultScreen.submissionFailedTitle')
+        }), /*#__PURE__*/_jsx(Text, {
+          style: styles.submitErrorMessage,
+          children: t('resultScreen.submissionFailedRetryHint')
+        }), /*#__PURE__*/_jsx(StyledButton, {
+          mode: "contained",
+          onPress: () => submit(appContext.identificationInfo),
+          style: styles.submitRetryButton,
+          children: t('resultScreen.retrySubmission')
+        }), /*#__PURE__*/_jsx(View, {
+          style: styles.submitReportButton,
+          children: /*#__PURE__*/_jsx(DiagnosticReportButton, {
+            baseUrl: appContext.baseUrl,
+            sessionId: appContext.identificationInfo?.sessionId,
+            scan: {
+              documentType: appContext.identificationInfo?.scannedDocument?.documentType,
+              dataSource: appContext.identificationInfo?.scannedDocument?.dataSource,
+              mrzText: appContext.identificationInfo?.scannedDocument?.mrzText,
+              mrzFields: appContext.identificationInfo?.scannedDocument?.mrzFields,
+              barcodeValue: appContext.identificationInfo?.scannedDocument?.barcodeValue
+            },
+            images: collectDiagnosticImages(appContext.identificationInfo?.scannedDocument)
+          })
+        })]
+      }) : isSubmitting ? /*#__PURE__*/_jsxs(_Fragment, {
         children: [/*#__PURE__*/_jsx(Text, {
           style: styles.sectionHeader,
           children: t('resultScreen.submitting')
@@ -819,6 +885,33 @@ const styles = StyleSheet.create({
     textAlign: 'center',
     textTransform: 'capitalize'
   },
+  submitErrorContainer: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    paddingHorizontal: 24
+  },
+  submitErrorTitle: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    color: 'black',
+    textAlign: 'center',
+    marginBottom: 12
+  },
+  submitErrorMessage: {
+    fontSize: 16,
+    color: '#666',
+    textAlign: 'center',
+    lineHeight: 22,
+    marginBottom: 28
+  },
+  submitRetryButton: {
+    minWidth: 220
+  },
+  submitReportButton: {
+    marginTop: 16,
+    minWidth: 220
+  },
   sectionText: {
     fontSize: 18,
     color: 'black',

package/lib/module/Shared/Components/EIDScanner.js

@@ -15,6 +15,7 @@ import { normalizeFromMRZInfo } from "../Libs/documentDataNormalizer.js";
 import { useTranslation } from 'react-i18next';
 import AppContext from "../Contexts/AppContext.js";
 import StyledButton from "./StyledButton.js";
+import DiagnosticReportButton from "./DiagnosticReportButton.js";
 import LottieView from 'lottie-react-native';
 import { getLocalizedCountryName } from "../Libs/country-display.utils.js";
 import { useKeepAwake } from "../Libs/native-keep-awake.utils.js";
@@ -87,6 +88,10 @@ const EIDScanner = ({
     }
   }, []);
   const [isScanned, setIsScanned] = React.useState(false);
+  // Set when an NFC read fails — surfaces a "report issue" support channel next
+  // to the retry button (a failed chip read is the most common point a user
+  // genuinely needs help). Cleared when a new read starts.
+  const [hasScanFailed, setHasScanFailed] = React.useState(false);
   const [hasGuideShown, setHasGuideShown] = React.useState(false);
   const {
     t,
@@ -144,6 +149,7 @@ const EIDScanner = ({
     setAttemptNumber(currentAttempt);
     setIsScanning(true);
     setIsScanned(false);
+    setHasScanFailed(false);
     setProgress(0);
     setProgressStage('');
     resetLastMessage();
@@ -260,6 +266,9 @@ const EIDScanner = ({
             setDocumentName(builtName);
             setIsScanned(true);
           }
+          // Defensive: clear any prior-failure flag on a successful read so the
+          // report affordance can't linger if the UI returns to this state.
+          setHasScanFailed(false);
           await trackEIDScanComplete(docType, scanDuration, currentAttempt).catch(() => {});
         } else {
           // eidReader resolved without throwing but produced no data. Without
@@ -279,6 +288,7 @@ const EIDScanner = ({
         Alert.alert(t('general.error'), t('eidScannerScreen.invalidMRZFields'));
       }
     } catch (error) {
+      setHasScanFailed(true);
       const scanDuration = Date.now() - startTime;
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
 
@@ -593,13 +603,25 @@ const EIDScanner = ({
       })), hasNfc && isEnabled && isScanning && progress === 0 && /*#__PURE__*/_jsx(Text, {
         style: styles.keepStillHint,
         children: t('eidScannerScreen.keepStill')
-      }), hasNfc && isEnabled && !isScanning && !isScanned && /*#__PURE__*/_jsx(View, {
+      }), hasNfc && isEnabled && !isScanning && !isScanned && /*#__PURE__*/_jsxs(View, {
         style: styles.buttonsContainer,
-        children: /*#__PURE__*/_jsx(StyledButton, {
+        children: [/*#__PURE__*/_jsx(StyledButton, {
           mode: "contained",
           onPress: readNFC,
           children: t('eidScannerScreen.startScanning')
-        })
+        }), hasScanFailed && /*#__PURE__*/_jsx(View, {
+          style: styles.reportButtonWrapper,
+          children: /*#__PURE__*/_jsx(DiagnosticReportButton, {
+            baseUrl: appContext.baseUrl,
+            sessionId: appContext.identificationInfo?.sessionId,
+            scan: {
+              documentType: appContext.identificationInfo?.scannedDocument?.documentType,
+              dataSource: appContext.identificationInfo?.scannedDocument?.dataSource,
+              mrzText: appContext.identificationInfo?.scannedDocument?.mrzText,
+              mrzFields: appContext.identificationInfo?.scannedDocument?.mrzFields
+            }
+          })
+        })]
       }), hasNfc && isEnabled && isScanned && !documentMRZInfo && /*#__PURE__*/_jsx(View, {
         style: styles.buttonsContainer,
         children: /*#__PURE__*/_jsx(StyledButton, {
@@ -679,6 +701,9 @@ const styles = StyleSheet.create({
     flexDirection: 'column',
     gap: 10
   },
+  reportButtonWrapper: {
+    marginTop: 4
+  },
   mainText: {
     fontSize: 20,
     fontWeight: 'bold',

package/lib/module/Shared/Components/ErrorBoundary.js

@@ -0,0 +1,144 @@
+"use strict";
+
+import React, { useContext } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { useTranslation } from 'react-i18next';
+import { useTheme } from "../Contexts/ThemeContext.js";
+import AppContext from "../Contexts/AppContext.js";
+import StyledButton from "./StyledButton.js";
+import { trackError } from "../Libs/analytics.utils.js";
+import { logError } from "../Libs/debug.utils.js";
+
+/**
+ * Themed fallback UI for an unrecoverable render error. A functional child so it
+ * can use the theme + translation hooks (the boundary itself must be a class).
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function ErrorFallback({
+  onRetry
+}) {
+  const {
+    colors
+  } = useTheme();
+  const {
+    t
+  } = useTranslation();
+  return /*#__PURE__*/_jsx(View, {
+    style: [styles.container, {
+      backgroundColor: colors.background
+    }],
+    children: /*#__PURE__*/_jsxs(View, {
+      style: styles.content,
+      children: [/*#__PURE__*/_jsx(Text, {
+        style: [styles.title, {
+          color: colors.text
+        }],
+        children: t('errorBoundary.title')
+      }), /*#__PURE__*/_jsx(Text, {
+        style: [styles.message, {
+          color: colors.textSecondary
+        }],
+        children: t('errorBoundary.message')
+      }), /*#__PURE__*/_jsx(StyledButton, {
+        mode: "contained",
+        onPress: onRetry,
+        style: styles.button,
+        children: t('errorBoundary.tryAgain')
+      })]
+    })
+  });
+}
+class ErrorBoundaryInner extends React.Component {
+  state = {
+    hasError: false,
+    resetKey: 0
+  };
+  static getDerivedStateFromError() {
+    return {
+      hasError: true
+    };
+  }
+  componentDidCatch(error, info) {
+    logError('ErrorBoundary', 'Caught render error', error);
+    // Telemetry — best-effort, never let reporting throw.
+    trackError('SDK_RENDER_ERROR', error.message, 'error_boundary', 'critical', {
+      error,
+      component: 'error_boundary',
+      recoverable: true,
+      additionalData: {
+        componentStack: info.componentStack ?? ''
+      }
+    }).catch(() => {});
+    // Notify the host integration that the SDK hit an unrecoverable error.
+    this.props.onError?.(error.message);
+  }
+  handleRetry = () => {
+    // Bump resetKey so the children below re-mount with a fresh key — a real
+    // recovery, not just a re-render of the same (possibly still-broken) tree.
+    this.setState(prev => ({
+      hasError: false,
+      resetKey: prev.resetKey + 1
+    }));
+  };
+  render() {
+    if (this.state.hasError) {
+      return /*#__PURE__*/_jsx(ErrorFallback, {
+        onRetry: this.handleRetry
+      });
+    }
+    return /*#__PURE__*/_jsx(React.Fragment, {
+      children: this.props.children
+    }, this.state.resetKey);
+  }
+}
+
+/**
+ * Catches unexpected render/runtime errors anywhere in the SDK's screen tree so
+ * an unhandled throw shows a recoverable fallback instead of unmounting to a
+ * white screen / crashing the host app. The SDK was otherwise entirely
+ * functional with no crash protection.
+ *
+ * Placed inside ThemeProvider + AppContext.Provider so the fallback can theme
+ * itself and notify the host via `onError`. This thin functional wrapper reads
+ * `onError` from context (a hook, which the class can't use) and passes it to
+ * the class as a prop. "Try Again" re-mounts the subtree (the navigator returns
+ * to its initial route).
+ */
+export default function ErrorBoundary({
+  children
+}) {
+  const {
+    onError
+  } = useContext(AppContext);
+  return /*#__PURE__*/_jsx(ErrorBoundaryInner, {
+    onError: onError,
+    children: children
+  });
+}
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    padding: 24
+  },
+  content: {
+    alignItems: 'center',
+    maxWidth: 360
+  },
+  title: {
+    fontSize: 22,
+    fontWeight: 'bold',
+    textAlign: 'center',
+    marginBottom: 12
+  },
+  message: {
+    fontSize: 16,
+    textAlign: 'center',
+    lineHeight: 22,
+    marginBottom: 28
+  },
+  button: {
+    minWidth: 200
+  }
+});

package/lib/module/Shared/Components/IdentityDocumentCamera.constants.js

@@ -14,6 +14,11 @@ export const MIN_MLI_FACE_SIZE_PERCENT = 0.01; // MLI (Multi Layer Image): min 1
 
 export const REQUIRED_CONSISTENT_MRZ_READS = 2;
 export const REQUIRED_CONSISTENT_DOCTYPE_DETECTIONS = 3;
+
+// After this long on a single scan step without completing it, surface the
+// "Having trouble?" prompt so the user isn't stranded on a live camera with no
+// timeout, retry, or help. Per-step (re-armed on each step transition).
+export const HELP_PROMPT_DELAY_MS = 25000;
 export const SIGNATURE_REGEX = /s[gi]g?n[au]?t[u]?r|imz[a]s?/i;
 export const SIGNATURE_TEXT_REGEX = /signature|imza|İmza/i;
 export const MRZ_BLOCK_PATTERN = /[A-Z0-9<]{8,}.*</i;

package/lib/module/Shared/Components/IdentityDocumentCamera.js

@@ -2,7 +2,7 @@
 
 /* eslint-disable react-native/no-inline-styles */
 import React, { useEffect, useState, useRef, useCallback } from 'react';
-import { View, StyleSheet, Text as TextView, Platform, StatusBar, Vibration, Linking, ActivityIndicator, Animated } from 'react-native';
+import { View, StyleSheet, Text as TextView, Platform, StatusBar, Vibration, Linking, ActivityIndicator, Animated, TouchableOpacity } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { TrustchexCamera } from "./TrustchexCamera.js";
 import { NativeModules } from 'react-native';
@@ -16,6 +16,7 @@ import { debugLog, logError, isDebugEnabled } from "../Libs/debug.utils.js";
 import { diagnostics } from "../Libs/diagnostics.js";
 import LottieView from 'lottie-react-native';
 import StyledButton from "./StyledButton.js";
+import DiagnosticReportButton from "./DiagnosticReportButton.js";
 import { SafeAreaView } from 'react-native-safe-area-context';
 import { speak, resetLastMessage } from "../Libs/tts.utils.js";
 import AppContext from "../Contexts/AppContext.js";
@@ -23,7 +24,7 @@ import { useTheme } from "../Contexts/ThemeContext.js";
 import DebugOverlay, { TestModePanel } from "./DebugOverlay.js";
 import { getStatusMessage, getFrameToScreenTransform, transformBoundsToScreen, getScanAreaBounds, angleBetweenPoints, detectDocumentType, determineDocumentTypeToSet, areMRZFieldsEqual, hasRequiredMRZFields, validateFacePosition, isPassportDocumentCode } from "./IdentityDocumentCamera.utils.js";
 import { handlePassportFlow, handleIDFrontFlow, handleIDBackFlow, getNextStepAfterHologram } from "./IdentityDocumentCamera.flows.js";
-import { HOLOGRAM_IMAGE_COUNT, HOLOGRAM_DETECTION_THRESHOLD, HOLOGRAM_DETECTION_RETRY_COUNT, HOLOGRAM_CAPTURE_INTERVAL, HOLOGRAM_MAX_FRAMES_WITHOUT_FACE, MIN_BRIGHTNESS_THRESHOLD, MAX_BRIGHTNESS_THRESHOLD, FACE_EDGE_MARGIN_PERCENT, MAX_CONSECUTIVE_QUALITY_FAILURES, REQUIRED_CONSISTENT_DOCTYPE_DETECTIONS, SIGNATURE_TEXT_REGEX, MRZ_BLOCK_PATTERN, MIN_CARD_FACE_SIZE_PERCENT } from "./IdentityDocumentCamera.constants.js";
+import { HOLOGRAM_IMAGE_COUNT, HOLOGRAM_DETECTION_THRESHOLD, HOLOGRAM_DETECTION_RETRY_COUNT, HOLOGRAM_CAPTURE_INTERVAL, HOLOGRAM_MAX_FRAMES_WITHOUT_FACE, MIN_BRIGHTNESS_THRESHOLD, MAX_BRIGHTNESS_THRESHOLD, FACE_EDGE_MARGIN_PERCENT, MAX_CONSECUTIVE_QUALITY_FAILURES, REQUIRED_CONSISTENT_DOCTYPE_DETECTIONS, HELP_PROMPT_DELAY_MS, SIGNATURE_TEXT_REGEX, MRZ_BLOCK_PATTERN, MIN_CARD_FACE_SIZE_PERCENT } from "./IdentityDocumentCamera.constants.js";
 
 // Re-export types for backward compatibility
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
@@ -77,6 +78,13 @@ const IdentityDocumentCamera = ({
   // cleared when a frame passes the brightness check (a fresh, glare-free frame).
   const [isGlareDetected, setIsGlareDetected] = useState(false);
   const [hasGuideShown, setHasGuideShown] = useState(false);
+  // "Having trouble?" escape: if a scan step doesn't complete within
+  // HELP_PROMPT_DELAY_MS the user is otherwise stuck on a live camera forever
+  // (no timeout/retry/help). We surface an unobtrusive prompt, then an opt-in
+  // help sheet with tips / retry / torch.
+  const [showHelpPrompt, setShowHelpPrompt] = useState(false);
+  const [helpSheetVisible, setHelpSheetVisible] = useState(false);
+  const stepStartedAt = useRef(Date.now());
   const [status, setStatus] = useState('SEARCHING');
   // True once the multi-frame voted MRZ consensus is STABLE + valid (the same
   // reading matched across `stabilityTarget` consecutive frames, with a clear
@@ -285,6 +293,25 @@ const IdentityDocumentCamera = ({
     }
   }, [status]);
 
+  // "Having trouble?" stuck-detection. The scan is frame-driven with no
+  // wall-clock timeout, so a document that never reads leaves the user stranded.
+  // Re-arm per step (keyed on nextStep) and per scan-start (hasGuideShown); show
+  // the prompt once the current step has been open longer than the threshold.
+  // Never arm on the terminal COMPLETED step.
+  useEffect(() => {
+    setShowHelpPrompt(false);
+    stepStartedAt.current = Date.now();
+    if (!hasGuideShown || nextStep === 'COMPLETED') {
+      return;
+    }
+    const interval = setInterval(() => {
+      if (Date.now() - stepStartedAt.current >= HELP_PROMPT_DELAY_MS) {
+        setShowHelpPrompt(true);
+      }
+    }, 1000);
+    return () => clearInterval(interval);
+  }, [nextStep, hasGuideShown]);
+
   // Disable face detection when scanning back side (no face expected, avoids false positives)
   useEffect(() => {
     if (nextStep === 'SCAN_ID_BACK') {
@@ -1852,9 +1879,16 @@ const IdentityDocumentCamera = ({
         style: [styles.topZone, {
           paddingTop: insets.top
         }],
-        children: [nextStep !== 'COMPLETED' && status !== 'SCANNED' && detectedDocumentType !== 'UNKNOWN' && /*#__PURE__*/_jsx(TextView, {
+        children: [nextStep !== 'COMPLETED' && status !== 'SCANNED' && /*#__PURE__*/_jsx(TextView, {
           style: styles.stepIndicator,
-          children: nextStep === 'SCAN_ID_FRONT_OR_PASSPORT' ? `${t('identityDocumentCamera.frontSide')} • ${t('identityDocumentCamera.stepProgress', {
+          children: nextStep === 'SCAN_ID_FRONT_OR_PASSPORT' ?
+          // Show "Front side • 1/N" from the START — even before the
+          // document type is recognized — so the user immediately knows
+          // to present the photo side and how many steps remain. Until
+          // the type is known we assume the ID-card path (the common
+          // case); the total corrects to the passport count once a
+          // passport is detected.
+          `${t('identityDocumentCamera.frontSide')} • ${t('identityDocumentCamera.stepProgress', {
             current: 1,
             total: onlyMRZScan ? detectedDocumentType === 'PASSPORT' ? 1 : 2 : detectedDocumentType === 'PASSPORT' ? 2 : 3
           })}` : nextStep === 'SCAN_HOLOGRAM' ? `${t('identityDocumentCamera.hologramCheck')} • ${t('identityDocumentCamera.stepProgress', {
@@ -1864,6 +1898,12 @@ const IdentityDocumentCamera = ({
             current: 3,
             total: 3
           })}` : ''
+        }), nextStep === 'SCAN_HOLOGRAM' && status !== 'SCANNED' && /*#__PURE__*/_jsx(TextView, {
+          style: styles.hologramProgress,
+          children: t('identityDocumentCamera.hologramProgress', {
+            current: hologramImageCount,
+            total: HOLOGRAM_IMAGE_COUNT
+          })
         }), /*#__PURE__*/_jsx(AnimatedText, {
           style: [styles.topZoneText,
           // Priority order for coloring (later styles override earlier ones)
@@ -1935,6 +1975,68 @@ const IdentityDocumentCamera = ({
         elementsOutsideScanArea: elementsOutsideScanArea
       }), testMode && testModeData && /*#__PURE__*/_jsx(TestModePanel, {
         mrzText: testModeData.mrzText
+      }), showHelpPrompt && !helpSheetVisible && nextStep !== 'COMPLETED' && /*#__PURE__*/_jsx(TouchableOpacity, {
+        style: styles.helpPrompt,
+        accessibilityRole: "button",
+        onPress: () => setHelpSheetVisible(true),
+        children: /*#__PURE__*/_jsx(TextView, {
+          style: styles.helpPromptText,
+          children: t('identityDocumentCamera.havingTrouble')
+        })
+      }), helpSheetVisible && /*#__PURE__*/_jsx(View, {
+        style: styles.helpBackdrop,
+        children: /*#__PURE__*/_jsxs(View, {
+          style: styles.helpCard,
+          children: [/*#__PURE__*/_jsx(TextView, {
+            style: styles.helpTitle,
+            children: t('identityDocumentCamera.troubleTitle')
+          }), /*#__PURE__*/_jsx(TextView, {
+            style: styles.helpTip,
+            children: `• ${t('identityDocumentCamera.guidePoint1')}`
+          }), /*#__PURE__*/_jsx(TextView, {
+            style: styles.helpTip,
+            children: `• ${t('identityDocumentCamera.guidePoint2')}`
+          }), /*#__PURE__*/_jsx(TextView, {
+            style: styles.helpTip,
+            children: `• ${t('identityDocumentCamera.guidePoint3')}`
+          }), isBrightnessLow && nextStep !== 'SCAN_HOLOGRAM' && /*#__PURE__*/_jsx(StyledButton, {
+            mode: "outlined",
+            onPress: () => {
+              setIsTorchOn(!isTorchOnRef.current);
+            },
+            style: styles.helpButton,
+            children: isTorchOn ? t('identityDocumentCamera.turnOffTorch') : t('identityDocumentCamera.turnOnTorch')
+          }), /*#__PURE__*/_jsx(StyledButton, {
+            mode: "contained",
+            onPress: () => {
+              // Full restart: send the flow back to the first step (so a
+              // stuck back/hologram step truly restarts, matching the label)
+              // and re-show the guide, which deactivates + resets scan state
+              // via the focus effect.
+              setHelpSheetVisible(false);
+              setShowHelpPrompt(false);
+              setNextStep('SCAN_ID_FRONT_OR_PASSPORT');
+              setDetectedDocumentType('UNKNOWN');
+              setHasGuideShown(false);
+            },
+            style: styles.helpButton,
+            children: t('identityDocumentCamera.troubleRetry')
+          }), /*#__PURE__*/_jsx(View, {
+            style: styles.helpButton,
+            children: /*#__PURE__*/_jsx(DiagnosticReportButton, {
+              baseUrl: appContext.baseUrl,
+              sessionId: appContext.identificationInfo?.sessionId,
+              scan: {
+                documentType: detectedDocumentType
+              }
+            })
+          }), /*#__PURE__*/_jsx(StyledButton, {
+            mode: "text",
+            onPress: () => setHelpSheetVisible(false),
+            style: styles.helpButton,
+            children: t('identityDocumentCamera.troubleDismiss')
+          })]
+        })
       })]
     })]
   });
@@ -1988,6 +2090,13 @@ const styles = StyleSheet.create({
     fontWeight: '500',
     marginBottom: 4
   },
+  hologramProgress: {
+    color: '#4CAF50',
+    fontSize: 14,
+    textAlign: 'center',
+    fontWeight: '600',
+    marginBottom: 4
+  },
   topZoneText: {
     color: 'white',
     fontSize: 20,
@@ -2023,6 +2132,56 @@ const styles = StyleSheet.create({
     bottom: '36%',
     backgroundColor: '#00000099'
   },
+  helpPrompt: {
+    position: 'absolute',
+    bottom: 40,
+    alignSelf: 'center',
+    backgroundColor: 'rgba(0,0,0,0.65)',
+    paddingVertical: 10,
+    paddingHorizontal: 20,
+    borderRadius: 22
+  },
+  helpPromptText: {
+    color: 'white',
+    fontSize: 15,
+    fontWeight: '600'
+  },
+  helpBackdrop: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    backgroundColor: 'rgba(0,0,0,0.55)',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24,
+    zIndex: 10
+  },
+  helpCard: {
+    width: '100%',
+    maxWidth: 340,
+    backgroundColor: 'white',
+    borderRadius: 16,
+    paddingVertical: 24,
+    paddingHorizontal: 20
+  },
+  helpTitle: {
+    fontSize: 18,
+    fontWeight: 'bold',
+    color: '#111827',
+    textAlign: 'center',
+    marginBottom: 16
+  },
+  helpTip: {
+    fontSize: 15,
+    color: '#374151',
+    lineHeight: 22,
+    marginBottom: 8
+  },
+  helpButton: {
+    marginTop: 12
+  },
   bottomZone: {
     position: 'absolute',
     top: '64%',