@trustchex/react-native-sdk 1.495.10 → 1.495.12

package/android/build.gradle

@@ -92,6 +92,16 @@ dependencies {
 
   // OpenCV for hologram detection and image processing
   implementation 'org.opencv:opencv:4.12.0'
+
+  // Pure-Java JPEG2000 decoder (jj2000, edu.ucar 5.2) — vendored as a local jar
+  // so it resolves fully offline with no Maven coordinate. Android's image
+  // pipeline cannot decode JPEG2000, but passport chip portraits (DG2) are
+  // frequently JP2; this lets ImageDecoderModule decode them to JPEG for display.
+  // No java.awt / javax.imageio usage, so it runs on Android.
+  implementation files("libs/jj2000-5.2.jar")
+
+  // Plain-JVM unit tests for the framework-free JP2 decode logic (Jp2PgxDecoder).
+  testImplementation "junit:junit:4.13.2"
 }
 
 react {

package/android/src/main/java/com/trustchex/reactnativesdk/ImageDecoderModule.kt

@@ -0,0 +1,88 @@
+package com.trustchex.reactnativesdk
+
+import android.graphics.Bitmap
+import android.util.Base64
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import java.io.ByteArrayOutputStream
+import java.io.File
+
+/**
+ * Decodes images that React Native's <Image> cannot render directly on Android.
+ *
+ * The driving case is the passport chip portrait (DG2), which is frequently
+ * stored as JPEG2000 (image/jp2). Android's Fresco/Skia image pipeline does NOT
+ * decode JPEG2000, so the chip photo showed as a blank/white placeholder. This
+ * module decodes the JP2 with the pure-Java jj2000 decoder (vendored jar, no
+ * NDK, no javax.imageio) and re-encodes it as JPEG so the JS <Image> can render
+ * it — mirroring the iOS ImageDecoderModule (which uses ImageIO).
+ *
+ * jj2000's [Decoder] is file-based and only writes raw PGX (one file per image
+ * component) headlessly — its PPM writer rejects many real codestreams. So we
+ * decode to "<base>-N.pgx" components and recombine: 3 components → RGB, 1 →
+ * grayscale. PGX samples may be >8-bit and big- or little-endian; we normalise
+ * to 8-bit. Handles both the JP2 container and a raw J2K codestream (DG2 ships
+ * as either).
+ */
+class ImageDecoderModule(reactContext: ReactApplicationContext) :
+  ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = NAME
+
+  /**
+   * Decode a base64 JPEG2000 image to a base64 JPEG. Resolves with the JPEG
+   * base64 string, or rejects on any failure (the JS caller falls back to the
+   * raw JP2, exactly as it does when the native module is unavailable).
+   */
+  @ReactMethod
+  fun decodeJp2ToJpeg(base64Jp2: String, promise: Promise) {
+    val cacheDir = reactApplicationContext.cacheDir
+    val token = System.nanoTime().toString()
+    val input = File(cacheDir, "jp2_decode_$token.jp2")
+    // jj2000 derives component filenames from this base ("<base>-1.pgx", …).
+    val outBase = File(cacheDir, "jp2_decode_$token.pgx")
+    try {
+      val jp2Bytes = Base64.decode(base64Jp2, Base64.DEFAULT)
+        ?: throw IllegalArgumentException("Could not base64-decode JP2 input")
+      input.writeBytes(jp2Bytes)
+
+      Jp2PgxDecoder.decodeToPgx(input, outBase)
+
+      val componentFiles = Jp2PgxDecoder.collectComponentFiles(outBase)
+      if (componentFiles.isEmpty()) {
+        throw IllegalStateException("jj2000 produced no component output")
+      }
+
+      val decoded = Jp2PgxDecoder.componentsToRgb(componentFiles.map { it.readBytes() })
+      val pixels = IntArray(decoded.rgb.size) { 0xFF000000.toInt() or decoded.rgb[it] }
+      val bitmap = Bitmap.createBitmap(
+        pixels,
+        decoded.width,
+        decoded.height,
+        Bitmap.Config.ARGB_8888
+      )
+      val jpeg = ByteArrayOutputStream().use { out ->
+        // Re-encode as baseline JPEG so the chip portrait is a format BOTH the
+        // on-screen <Image> AND the verification backend accept (the backend
+        // face-match expects JPEG/PNG, not raw JPEG2000).
+        bitmap.compress(Bitmap.CompressFormat.JPEG, 95, out)
+        out.toByteArray()
+      }
+      bitmap.recycle()
+
+      promise.resolve(Base64.encodeToString(jpeg, Base64.NO_WRAP))
+    } catch (e: Throwable) {
+      promise.reject("DECODE_FAILED", e.message, e)
+    } finally {
+      input.delete()
+      Jp2PgxDecoder.collectComponentFiles(outBase).forEach { it.delete() }
+      outBase.delete()
+    }
+  }
+
+  companion object {
+    const val NAME = "ImageDecoderModule"
+  }
+}

package/android/src/main/java/com/trustchex/reactnativesdk/Jp2PgxDecoder.kt

@@ -0,0 +1,135 @@
+package com.trustchex.reactnativesdk
+
+import jj2000.j2k.decoder.Decoder
+import jj2000.j2k.util.ParameterList
+import java.io.File
+
+/**
+ * Pure (Android-free) half of the JPEG2000 decode: drive jj2000 to PGX
+ * components and turn those into a flat RGB pixel array. Kept separate from
+ * [ImageDecoderModule] so the parsing/recombination logic — the only novel,
+ * bug-prone part — is unit-testable on a plain JVM without Robolectric (no
+ * android.graphics.Bitmap / Color dependency here).
+ *
+ * jj2000's PGX output:
+ *  - colour (multi-component): "<base>-1.pgx", "<base>-2.pgx", "<base>-3.pgx"
+ *  - grayscale (single-component): "<base>.pgx" (no "-N" suffix)
+ *  - each PGX: ASCII header `PG <ML|LM> [<+|->] <depth> <w> <h>\n` then raw
+ *    big-/little-endian samples of `ceil(depth/8)` bytes each.
+ */
+object Jp2PgxDecoder {
+
+  /** A decoded image as packed 0xRRGGBB ints plus its dimensions. */
+  class DecodedImage(val width: Int, val height: Int, val rgb: IntArray)
+
+  /** Run jj2000's file-based decoder, writing per-component PGX next to [outBase]. */
+  fun decodeToPgx(input: File, outBase: File) {
+    val defaults = ParameterList()
+    for (param in Decoder.getAllParameters()) {
+      // i / o have no default (null); everything else seeds the defaults list.
+      if (param[3] != null) defaults.put(param[0], param[3])
+    }
+    val pl = ParameterList(defaults).apply {
+      put("i", input.absolutePath)
+      put("o", outBase.absolutePath)
+      put("debug", "off")
+      put("verbose", "off")
+    }
+    Decoder(pl).run()
+  }
+
+  /**
+   * The decoded component PGX files in component order. Colour → "<base>-N.pgx"
+   * sorted by N; grayscale → the base "<base>.pgx" itself.
+   */
+  fun collectComponentFiles(outBase: File): List<File> {
+    val dir = outBase.parentFile ?: return emptyList()
+    val stem = outBase.name.removeSuffix(".pgx")
+    val multi = (dir.listFiles() ?: emptyArray())
+      .filter { it.name.startsWith("$stem-") && it.name.endsWith(".pgx") }
+      .sortedBy {
+        it.name.removePrefix("$stem-").removeSuffix(".pgx").toIntOrNull() ?: 0
+      }
+    if (multi.isNotEmpty()) return multi
+    return if (outBase.exists() && outBase.length() > 0) listOf(outBase) else emptyList()
+  }
+
+  /** Recombine component PGX byte arrays into a packed-RGB image. */
+  fun componentsToRgb(components: List<ByteArray>): DecodedImage {
+    require(components.isNotEmpty()) { "No PGX components" }
+    val comps = components.map { parsePgx(it) }
+    val width = comps[0].width
+    val height = comps[0].height
+    require(width > 0 && height > 0) { "Invalid PGX dimensions ${width}x$height" }
+
+    val rgb = IntArray(width * height)
+    val n = comps.size
+    for (idx in 0 until width * height) {
+      val r: Int
+      val g: Int
+      val b: Int
+      if (n >= 3) {
+        r = comps[0].sampleAt(idx)
+        g = comps[1].sampleAt(idx)
+        b = comps[2].sampleAt(idx)
+      } else {
+        val v = comps[0].sampleAt(idx)
+        r = v; g = v; b = v
+      }
+      rgb[idx] = (r shl 16) or (g shl 8) or b
+    }
+    return DecodedImage(width, height, rgb)
+  }
+
+  internal class Pgx(
+    val width: Int,
+    val height: Int,
+    val depth: Int,
+    val bigEndian: Boolean,
+    val dataOffset: Int,
+    val bytes: ByteArray
+  ) {
+    /** One normalised 8-bit sample at pixel index [idx]. */
+    fun sampleAt(idx: Int): Int {
+      val bytesPer = (depth + 7) / 8
+      val p = dataOffset + idx * bytesPer
+      var v = if (bytesPer <= 1) {
+        bytes[p].toInt() and 0xFF
+      } else {
+        val a = bytes[p].toInt() and 0xFF
+        val b = bytes[p + 1].toInt() and 0xFF
+        if (bigEndian) (a shl 8) or b else (b shl 8) or a
+      }
+      if (depth > 8) v = v shr (depth - 8) else if (depth < 8) v = v shl (8 - depth)
+      return v and 0xFF
+    }
+  }
+
+  /**
+   * Parse a PGX header: "PG <ML|LM> [<+|->] <depth> <width> <height>\n" followed
+   * by raw samples. The sign and the leading '+'/'-' are optional and may be
+   * glued to the depth ("+16"); we tolerate both. "ML" = big-endian.
+   */
+  internal fun parsePgx(d: ByteArray): Pgx {
+    var i = 0
+    val sb = StringBuilder()
+    while (i < d.size && d[i].toInt().toChar() != '\n') {
+      sb.append((d[i].toInt() and 0xFF).toChar())
+      i++
+    }
+    val dataOffset = i + 1
+    val raw = sb.toString().trim().split(Regex("\\s+"))
+    val bigEndian = raw.getOrNull(1) == "ML"
+    val nums = ArrayList<Int>()
+    for (k in 2 until raw.size) {
+      var s = raw[k]
+      if (s == "+" || s == "-") continue
+      s = s.removePrefix("+").removePrefix("-")
+      s.toIntOrNull()?.let { nums.add(it) }
+    }
+    val depth = nums.getOrNull(0) ?: 8
+    val width = nums.getOrNull(1) ?: 0
+    val height = nums.getOrNull(2) ?: 0
+    return Pgx(width, height, depth, bigEndian, dataOffset, d)
+  }
+}

package/android/src/main/java/com/trustchex/reactnativesdk/TrustchexSDKPackage.kt

@@ -18,6 +18,7 @@ class TrustchexSDKPackage : BaseReactPackage() {
       "DeviceBrightness" -> DeviceBrightnessModule(reactContext)
       "MLKitModule" -> MLKitModule(reactContext)
       "OpenCVModule" -> OpenCVModule(reactContext)
+      ImageDecoderModule.NAME -> ImageDecoderModule(reactContext)
       else -> null
     }
   }
@@ -74,6 +75,17 @@ class TrustchexSDKPackage : BaseReactPackage() {
                       false // isTurboModule
               )
 
+      // JPEG2000 image decoder module (passport DG2 portrait → JPEG)
+      moduleInfos[ImageDecoderModule.NAME] =
+              ReactModuleInfo(
+                      ImageDecoderModule.NAME,
+                      ImageDecoderModule.NAME,
+                      false, // canOverrideExistingModule
+                      false, // needsEagerInit
+                      false, // isCxxModule
+                      false // isTurboModule
+              )
+
       moduleInfos
     }
   }

package/android/src/test/java/com/trustchex/reactnativesdk/Jp2PgxDecoderTest.kt

@@ -0,0 +1,143 @@
+package com.trustchex.reactnativesdk
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.io.File
+import java.nio.file.Files
+
+/**
+ * Plain-JVM tests for the JPEG2000 → RGB decode logic that backs the Android
+ * ImageDecoderModule (the fix for the "white face" on German passports).
+ *
+ * Runs the real vendored jj2000 decoder against committed JP2 fixtures and
+ * verifies the recombined pixels, plus the PGX header parsing edge cases. No
+ * android.graphics dependency, so no Robolectric is needed.
+ *
+ * Fixtures (android/src/test/resources/jp2):
+ *  - solid_color.jp2 : 64×64, every pixel rgb(200,40,60)  [JP2 container, colour]
+ *  - solid_color.j2k : same image as a raw J2K codestream (DG2 ships as either)
+ *  - gray.jp2        : 64×64 black→white horizontal gradient [single-component]
+ */
+class Jp2PgxDecoderTest {
+
+  private fun fixture(name: String): File {
+    val url = javaClass.classLoader!!.getResource("jp2/$name")
+      ?: error("Missing test fixture jp2/$name")
+    return File(url.toURI())
+  }
+
+  /** Decode a fixture end-to-end through the production code path. */
+  private fun decode(fixtureName: String): Jp2PgxDecoder.DecodedImage {
+    val tmpDir = Files.createTempDirectory("jp2test").toFile()
+    try {
+      val input = File(tmpDir, "in.jp2").apply { writeBytes(fixture(fixtureName).readBytes()) }
+      val outBase = File(tmpDir, "out.pgx")
+      Jp2PgxDecoder.decodeToPgx(input, outBase)
+      val comps = Jp2PgxDecoder.collectComponentFiles(outBase)
+      assertTrue("expected at least one component for $fixtureName", comps.isNotEmpty())
+      return Jp2PgxDecoder.componentsToRgb(comps.map { it.readBytes() })
+    } finally {
+      tmpDir.deleteRecursively()
+    }
+  }
+
+  private fun Jp2PgxDecoder.DecodedImage.pixelAt(x: Int, y: Int) = rgb[y * width + x]
+  private fun r(p: Int) = (p shr 16) and 0xFF
+  private fun g(p: Int) = (p shr 8) and 0xFF
+  private fun b(p: Int) = p and 0xFF
+
+  @Test
+  fun decodesColorJp2ContainerToCorrectRgb() {
+    val img = decode("solid_color.jp2")
+    assertEquals(64, img.width)
+    assertEquals(64, img.height)
+    // Every pixel is the same solid colour; check a few spread-out ones. JP2 is
+    // lossy so allow a small tolerance.
+    for ((x, y) in listOf(0 to 0, 63 to 0, 0 to 63, 63 to 63, 32 to 32)) {
+      val p = img.pixelAt(x, y)
+      assertClose("R@($x,$y)", 200, r(p))
+      assertClose("G@($x,$y)", 40, g(p))
+      assertClose("B@($x,$y)", 60, b(p))
+    }
+  }
+
+  @Test
+  fun decodesRawJ2kCodestreamSameAsContainer() {
+    // DG2 may be a bare codestream rather than a .jp2 box; must decode identically.
+    val img = decode("solid_color.j2k")
+    assertEquals(64, img.width)
+    val p = img.pixelAt(10, 10)
+    assertClose("R", 200, r(p))
+    assertClose("G", 40, g(p))
+    assertClose("B", 60, b(p))
+  }
+
+  @Test
+  fun decodesGrayscaleJp2AsSingleComponentToGray() {
+    // Single-component output is written as "<base>.pgx" with no "-N" suffix; the
+    // collector must still find it, and grayscale must expand to R==G==B.
+    val img = decode("gray.jp2")
+    assertEquals(64, img.width)
+    // ImageMagick `gradient:black-white` is a VERTICAL ramp (top dark → bottom
+    // bright), constant across each row. Check top vs bottom, and that every
+    // channel is equal (true grayscale expansion).
+    val top = img.pixelAt(32, 1)
+    val bottom = img.pixelAt(32, 62)
+    assertEquals("top should be gray", r(top), g(top))
+    assertEquals("top should be gray", g(top), b(top))
+    assertEquals("bottom should be gray", r(bottom), g(bottom))
+    assertTrue("gradient should brighten top→bottom", r(bottom) > r(top))
+  }
+
+  @Test
+  fun parsesBigEndian16BitPgxAndScalesTo8Bit() {
+    // "PG ML + 16 2 1\n" then one 16-bit big-endian sample 0xFF00 (=65280) and
+    // one 0x0100 (=256). depth 16 → >>8 → 255 and 1.
+    val header = "PG ML + 16 2 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(0xFF.toByte(), 0x00, 0x01, 0x00)
+    val pgx = Jp2PgxDecoder.parsePgx(header + body)
+    assertEquals(2, pgx.width)
+    assertEquals(1, pgx.height)
+    assertEquals(255, pgx.sampleAt(0))
+    assertEquals(1, pgx.sampleAt(1))
+  }
+
+  @Test
+  fun parsesLittleEndian8BitPgx() {
+    // "PG LM + 8 3 1\n" then bytes 10, 20, 30 — 8-bit, no scaling.
+    val header = "PG LM + 8 3 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(10, 20, 30)
+    val pgx = Jp2PgxDecoder.parsePgx(header + body)
+    assertEquals(10, pgx.sampleAt(0))
+    assertEquals(20, pgx.sampleAt(1))
+    assertEquals(30, pgx.sampleAt(2))
+  }
+
+  @Test
+  fun parsesHeaderWithSignGluedToDepth() {
+    // Some writers emit "+16" with no space; the parser must still read depth 16.
+    val header = "PG ML +16 1 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(0x80.toByte(), 0x00) // 0x8000 >> 8 = 128
+    val pgx = Jp2PgxDecoder.parsePgx(header + body)
+    assertEquals(128, pgx.sampleAt(0))
+  }
+
+  @Test
+  fun grayscaleComponentExpandsToEqualRgbChannels() {
+    val header = "PG ML + 8 1 1\n".toByteArray(Charsets.US_ASCII)
+    val body = byteArrayOf(123)
+    val img = Jp2PgxDecoder.componentsToRgb(listOf(header + body))
+    val p = img.rgb[0]
+    assertEquals(123, r(p))
+    assertEquals(123, g(p))
+    assertEquals(123, b(p))
+  }
+
+  private fun assertClose(label: String, expected: Int, actual: Int, tol: Int = 12) {
+    assertTrue(
+      "$label expected ~$expected (±$tol) but was $actual",
+      kotlin.math.abs(expected - actual) <= tol
+    )
+  }
+}

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

@@ -458,11 +458,14 @@ const EIDScanner = ({
               style: styles.idCardPhotoContainer,
               children: /*#__PURE__*/_jsx(View, {
                 style: styles.idCardPhotoFrame,
-                children: documentFaceImage && (documentFaceImageMimeType === 'image/jpeg' || documentFaceImageMimeType === 'image/png' ||
-                // Android's <Image> decodes a raw JP2 data URI; on iOS
-                // the chip JP2 is converted to JPEG before this point
-                // (native ImageIO), so iOS never reaches here as jp2.
-                documentFaceImageMimeType === 'image/jp2') ? /*#__PURE__*/_jsx(Image, {
+                children: documentFaceImage && (
+                // The chip portrait (DG2) is JPEG2000, which RN's <Image>
+                // can't render on either platform — the native decoder
+                // (iOS ImageIO / Android jj2000) converts it to JPEG (or
+                // the small-image JS fallback to PNG) before this point.
+                // A raw image/jp2 would render as a blank box, so we only
+                // accept the decoded formats and otherwise show '?'.
+                documentFaceImageMimeType === 'image/jpeg' || documentFaceImageMimeType === 'image/png') ? /*#__PURE__*/_jsx(Image, {
                   source: {
                     uri: `data:${documentFaceImageMimeType};base64,${documentFaceImage}`
                   },

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

@@ -17,6 +17,15 @@ export const REQUIRED_CONSISTENT_DOCTYPE_DETECTIONS = 3;
 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;
+// A DENSE MRZ run — a contiguous block of MRZ characters that contains a chevron
+// FILLER pair (`<<`). Real machine-readable zones are padded with `<<…`; a card
+// FACE (ID front) has no MRZ, and the occasional stray single `<` OCR'd from a
+// guilloche/chevron glyph will NOT contain a `<<` filler run. Used to decide
+// "is a real MRZ visible on this front?" without the false positives of
+// MRZ_BLOCK_PATTERN (whose `.*<` lets a lone detached `<` anywhere in the frame
+// match) — that looseness could otherwise wedge a legitimate ID front that
+// happens to OCR a stray `<`.
+export const MRZ_DENSE_PATTERN = /[A-Z0-9<]{6,}<<[A-Z0-9<]*/i;
 // Matches the line-1 start of ANY ICAO TD3 passport MRZ, so the camera routes
 // every passport variant into the passport flow (not the ID-card back-side
 // flow). Per ICAO 9303 Part 4: `P` + a type char (filler `<` or a subtype

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

@@ -30,8 +30,8 @@
  *   - No face, has MRZ with code 'I'
  */
 
-import { PASSPORT_MRZ_PATTERN } from "./IdentityDocumentCamera.constants.js";
-import { isIDCardDocumentCode } from "./IdentityDocumentCamera.utils.js";
+import { PASSPORT_MRZ_PATTERN, MRZ_DENSE_PATTERN } from "./IdentityDocumentCamera.constants.js";
+import { isIDCardDocumentCode, isPassportDocumentCode, documentHasBackSide } from "./IdentityDocumentCamera.utils.js";
 
 /**
  * After this many retry attempts for ID_FRONT flow, proceed with face detection alone
@@ -142,8 +142,15 @@ export function handleIDFrontFlow(faces, text, mrzText, mrzFields, retryCount) {
       nextAction: 'REJECT_AS_PASSPORT'
     };
   }
-  if (mrzText && PASSPORT_MRZ_PATTERN.test(mrzText)) {
-    // Passport MRZ pattern visible even if not fully parsed
+
+  // Passport MRZ pattern visible even if not fully parsed. Check BOTH the
+  // parsed `mrzText` (null until the MRZ validates) AND the raw OCR `text` — a
+  // passport's MRZ is dense and frequently OCRs a few frames after its face +
+  // signature, so on the accepting frame `mrzText` is often still null while the
+  // raw `P<XXX...` run is already visible. Testing only `mrzText` (the old bug)
+  // let such a passport pass as an ID front and get routed to a back side that
+  // does not exist.
+  if (mrzText && PASSPORT_MRZ_PATTERN.test(mrzText) || PASSPORT_MRZ_PATTERN.test(text)) {
     return {
       shouldProceed: false,
       reason: 'Passport MRZ pattern visible - not an ID card',
@@ -163,6 +170,34 @@ export function handleIDFrontFlow(faces, text, mrzText, mrzFields, retryCount) {
     };
   }
 
+  // ============================================================================
+  // STEP 2b: An ID-card FRONT has NO MRZ (the MRZ is on the back). So if a real
+  // MRZ is currently visible on this "front", it is almost certainly a passport
+  // data page whose 'P' code we just haven't parsed yet — do NOT accept it as an
+  // ID front; wait for the MRZ to resolve (→ a 'P' code routes it to the
+  // passport flow). This is the guard that stops a passport (face + signature +
+  // not-yet-parsed MRZ) being accepted as ID_FRONT and then getting stuck at
+  // SCAN_ID_BACK, which rejects the passport's photo page because it has a face.
+  //
+  // We use MRZ_DENSE_PATTERN (requires a `<<` filler run), NOT the loose
+  // MRZ_BLOCK_PATTERN — a card face has no MRZ, but a stray single `<` OCR'd
+  // from a guilloche could match the loose pattern and wedge a real ID front.
+  // We ALSO honor the signature retry threshold: a real ID front genuinely has
+  // no MRZ, so if a "dense MRZ" keeps matching frame after frame past the
+  // threshold it is OCR noise, not a passport — fall through and let STEP 3's
+  // face-only acceptance proceed rather than waiting forever.
+  const mrzVisibleOnFront = !!mrzText || MRZ_DENSE_PATTERN.test(text);
+  const stillWaitingForMrz = retryCount <= SIGNATURE_RETRY_THRESHOLD;
+  if (mrzVisibleOnFront && stillWaitingForMrz && !isIDCardDocumentCode(mrzFields?.documentCode)) {
+    // An ID-card MRZ code (I/A/C) is allowed to proceed (handled in STEP 4); any
+    // other visible MRZ → keep waiting for it to parse and reveal a 'P' code.
+    return {
+      shouldProceed: false,
+      reason: 'MRZ block visible on front - waiting to confirm it is not a passport',
+      nextAction: 'WAIT_FOR_MRZ'
+    };
+  }
+
   // ============================================================================
   // STEP 3: Check for signature (optional front side confirmation)
   // ============================================================================
@@ -283,20 +318,23 @@ export function handleIDBackFlow(mrzText, mrzFields, mrzValid, mrzStableAndValid
  * self-corrects: SCAN_ID_BACK simply won't find an ID-back MRZ/barcode and the
  * user can cancel, which is far better than skipping the back of every real ID.
  */
-export function getNextStepAfterHologram(detectedDocumentType, currentFrameDocType, mrzDocCode) {
-  // Any positive passport signal → done (no back side).
-  const isPassport = detectedDocumentType === 'PASSPORT' || currentFrameDocType === 'PASSPORT' || mrzDocCode === 'P';
-  if (isPassport) {
-    return 'COMPLETED';
-  }
-
-  // Positive ID-card evidence → scan the back. Either a non-'P' MRZ code, or a
-  // front classified as ID_FRONT (an ID front legitimately has no MRZ, so the
-  // classification is the only signal we get).
-  const hasIdCardMrzCode = !!mrzDocCode && mrzDocCode !== 'P';
+export function getNextStepAfterHologram(detectedDocumentType, currentFrameDocType, mrzDocCode,
+// True if a passport MRZ pattern / 'P' code was seen in ANY front frame this
+// session — not just the accepting one. The passport MRZ is dense and often
+// OCRs a few frames AFTER the face + signature, so a passport can get locked
+// as ID_FRONT before its MRZ is read. Latching the signal across frames is
+// what stops that passport from being wrongly routed to SCAN_ID_BACK here.
+sawPassportSignal = false) {
+  // Resolve to a single document type, passport-biased: any positive passport
+  // signal wins (a passport must never wait for a back that does not exist),
+  // then positive ID-card evidence (a non-'P' MRZ code, or an ID_FRONT
+  // classification — an ID front legitimately has no MRZ, so the classification
+  // is the only signal we get), else UNKNOWN.
+  const isPassport = sawPassportSignal || detectedDocumentType === 'PASSPORT' || currentFrameDocType === 'PASSPORT' || isPassportDocumentCode(mrzDocCode);
+  const hasIdCardMrzCode = !!mrzDocCode && !isPassportDocumentCode(mrzDocCode);
   const isIdFront = detectedDocumentType === 'ID_FRONT' || currentFrameDocType === 'ID_FRONT';
-  if (hasIdCardMrzCode || isIdFront) {
-    return 'SCAN_ID_BACK';
-  }
-  return 'COMPLETED';
+  const resolved = isPassport ? 'PASSPORT' : hasIdCardMrzCode || isIdFront ? 'ID_FRONT' : 'UNKNOWN';
+
+  // Single source of truth for "is there a back side left to scan?".
+  return documentHasBackSide(resolved) ? 'SCAN_ID_BACK' : 'COMPLETED';
 }