@myazahq/kyc-sdk-react-native 2.6.0 → 3.0.0

package/README.md

@@ -70,13 +70,18 @@ default on Expo SDK 56):
   "expo": {
     "newArchEnabled": true,
     "plugins": [
-      ["react-native-vision-camera", { "enableMicrophonePermission": false }],
       "@myazahq/kyc-sdk-react-native"
     ]
   }
 }
 ```
 
+VisionCamera v5 ships **no config plugin** (v4 did), so it takes no `plugins`
+entry. Listing it makes `expo prebuild` load the package's main entry as a
+plugin and fail with `Cannot find module '.../lib/VisionCamera'`. The camera
+permission and usage strings come from this SDK's own plugin; pass
+`cameraPermission` to change the iOS wording.
+
 Then build a dev client (regenerates the native projects):
 
 ```sh
@@ -87,7 +92,62 @@ JAVA_HOME=/path/to/jdk-17 npx expo run:android    # Android — needs JDK 17
 
 > The SDK plugin accepts optional custom prompts:
 > `["@myazahq/kyc-sdk-react-native", { "cameraPermission": "Your message…",
-> "locationPermission": "Your message…" }]`.
+> "locationPermission": "Your message…", "nfcPermission": "Your message…" }]`.
+
+#### NFC is opt-in
+
+Reading the eMRTD chip in a passport or chip ID card needs platform permissions
+that most apps should not carry, so the SDK declares **none of them** unless you
+ask:
+
+```jsonc
+["@myazahq/kyc-sdk-react-native", { "nfc": true }]
+```
+
+With it on, the plugin writes the Android `NFC` permission plus a
+`uses-feature android:required="false"` declaration, and on iOS the
+`NFCReaderUsageDescription`, the reader-session entitlement and the eMRTD
+application identifier.
+
+Leave it off and none of that is added. The chip step already checks for a radio
+at runtime and skips itself when there is none, so an app built without NFC
+behaves exactly like a phone that has no NFC hardware — every other step is
+unaffected.
+
+Two reasons this is opt-in rather than on by default:
+
+- **iOS code signing.** The reader entitlement requires the App ID to carry the
+  "NFC Tag Reading" capability in the Apple Developer portal. Adding it
+  unconditionally breaks signing for every consumer who does not read chips and
+  has not enabled that capability.
+- **Play Store visibility.** `android.permission.NFC` makes Android infer that
+  the app *requires* an NFC radio, which hides it from every device without one.
+  That is why the permission and the `uses-feature` declaration are written
+  together and never separately.
+
+> **Changed in 3.0.0.** Earlier versions declared the Android NFC permission in
+> the library manifest, so it merged into every host app regardless of this
+> option — the opt-in only ever governed iOS. If you read chips on Android and
+> have not set `nfc: true`, set it now: without it the permission is no longer
+> declared and the chip step will find no radio. Apps that never read chips need
+> no change and lose a permission they never wanted.
+
+### Optional modules
+
+Four `expo-*` modules are **optional peers**. The SDK loads each one lazily and
+carries on without it, so nothing crashes if you skip them — but each one is
+missing a capability rather than a detail, so install them deliberately:
+
+| Module | What installing it buys | Without it |
+|--------|------------------------|-----------|
+| `expo-device` | Make, model, manufacturer and physical-vs-simulator in the device metadata | Those fields are omitted and the device class is guessed from the platform, so Device Intelligence has a weaker fingerprint and shared-device detection suffers |
+| `expo-application` | Your app's id, version and build number on the submission | The `app` block is omitted entirely, so a result cannot be traced to the build that produced it |
+| `expo-localization` | The device's region, explicitly | Country defaults and the reported locale fall back to the JS runtime's locale, which often carries no region at all (`en` rather than `en-NG`) |
+| `expo-document-picker` | "Choose a file" on the proof-of-address and KYB document steps | Those steps accept a camera capture only, so a PDF bank statement cannot be submitted at all |
+
+```sh
+npx expo install expo-device expo-application expo-localization expo-document-picker
+```
 
 ### Bare React Native app (no Expo prebuild)
 
@@ -104,7 +164,7 @@ npm install @myazahq/kyc-sdk-react-native \
   react-native-worklets react-native-nitro-modules react-native-nitro-image \
   react-native-safe-area-context react-native-svg \
   expo expo-image-manipulator expo-image-picker expo-speech expo-font \
-  expo-glass-effect expo-application expo-crypto expo-device expo-localization \
+  expo-glass-effect expo-crypto \
   expo-location
 
 # 3. iOS pods:
@@ -244,6 +304,7 @@ export default function VerifyScreen() {
 | `enableSelfie`          | `boolean`                                 | `true`              | Capture a selfie during liveness.                                                                                    |
 | `enableDocumentCapture` | `boolean`                                 | `true`              | Enable the document-scan step for document IDs.                                                                      |
 | `allowDocumentUpload`   | `boolean`                                 | `true`              | Allow picking a document photo from the gallery as an alternative to the camera. `false` hides every "upload instead" affordance (it's still offered on the camera-permission-denied screen as an escape hatch). |
+| `allowDocumentScan`     | `boolean`                                 | `true`              | Allow photographing the document with the live camera. `false` makes document capture upload-only: the SDK never asks for camera access and the applicant chooses a photo of each side from their device. At least one of `allowDocumentScan` and `allowDocumentUpload` must stay on; a config that switches both off keeps the camera on. |
 | `enableLiveness`        | `boolean`                                 | `true`              | Run the liveness challenge step. The server can still disable it per ID type.                                        |
 | `livenessMode`          | `'gestures' \| 'flash' \| 'both'`         | `'gestures'`        | How liveness is proven. See [Liveness](#liveness).                                                                   |
 | `flashSequenceLength`   | `number` (2–5)                            | `4`                 | Colours in the flash sequence, for `'flash'` / `'both'`.                                                             |
@@ -536,7 +597,9 @@ terminal `4xx` surface immediately. The UI shows a top toast while retrying, and
 If the user denies camera access, the SDK shows a clear "camera access needed"
 screen (with an **Open Settings** action) instead of hanging, and reports
 `camera_permission_denied` to `onError`. Document capture additionally offers a
-gallery-upload fallback unless `allowDocumentUpload` is `false`.
+gallery-upload fallback unless `allowDocumentUpload` is `false`. When
+`allowDocumentScan` is `false` the document step never requests the camera, so
+this screen cannot appear there: each side is a photo chosen from the device.
 
 ### Liveness quality guards
 
@@ -562,6 +625,67 @@ v5 Nitro frame processor: the camera frame never crosses the JS bridge. The self
 is **auto-captured** once challenges pass (anti-spoofing — never user-triggered),
 and a short liveness video is recorded and uploaded best-effort.
 
+## App size
+
+The SDK adds native machine learning to a host app, and that is where the weight
+sits. Two things decide what a user actually downloads, and the defaults are
+already the small ones — but the third and fourth are the host app's to set, and
+they are worth more than everything the SDK can do on its own.
+
+**On-device models are fetched, not bundled.** Face detection and text
+recognition both run on Google ML Kit on Android, and the SDK depends on the
+Play Services variants, which download their models on first use. Measured on a
+real integrator's release APK, the bundled pair cost **18.5 MB per device**
+(arm64: text 10.55 MB, face 7.95 MB) plus `.tflite` files in `assets/`, which
+ship to every device because assets are not split by ABI. Fetched, that is about
+0.4 MB of shims.
+
+The SDK primes both downloads the moment the flow opens, so they overlap the
+consent and ID-type screens. If a model has not arrived by the time it is needed,
+the step says so rather than failing silently — the liveness step waits and
+explains, and the MRZ scanner tells the user the code cannot be read and lets
+them continue without the chip.
+
+The trade is real: the Play Services variants need Google Play Services, so they
+do not work on Huawei or bare AOSP builds. If you ship to those devices, put this
+in your root `build.gradle` and you get fully-offline models back, at 18.5 MB per
+device:
+
+```gradle
+ext { myazaKycBundledMlKit = true }
+```
+
+**Ship an App Bundle, or filter your ABIs.** Native libraries dominate the rest
+of the download, and a universal APK carries every architecture at once. An `.aab`
+lets Play deliver only the one a device needs. If you must ship an APK, name the
+architectures your users actually have:
+
+```gradle
+android {
+  defaultConfig {
+    ndk { abiFilters 'arm64-v8a', 'armeabi-v7a' }
+  }
+}
+```
+
+**Turn on R8 and resource shrinking.** The SDK ships its own consumer rules
+(`consumer-rules.pro`), so you do not need to learn which of its classes Nitro
+constructs by name:
+
+```gradle
+android {
+  buildTypes {
+    release {
+      minifyEnabled true
+      shrinkResources true
+    }
+  }
+}
+```
+
+**Use Expo SDK 54 or newer.** Its default template builds smaller than earlier
+ones, and the SDK's peer range assumes it.
+
 ## Documentation
 
 Full documentation, configuration options, and webhook setup: **[trust.myaza.co/documentation/sdks](https://trust.myaza.co/documentation/sdks)**.

package/android/build.gradle

@@ -32,6 +32,11 @@ def safeExtGet(prop, fallback) {
   rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
 }
 
+// Resolved ONCE and used twice: it picks the ML Kit artifacts below AND is
+// compiled into BuildConfig so the native readiness checks can answer without
+// asking Play Services about a model that is sitting in the APK.
+def bundledMlKit = safeExtGet('myazaKycBundledMlKit', false).toString().toBoolean()
+
 android {
   namespace 'co.myazahq.kyc.rn'
   compileSdk safeExtGet('compileSdkVersion', 34)
@@ -41,6 +46,17 @@ android {
     minSdk safeExtGet('minSdkVersion', 24)
     targetSdk safeExtGet('targetSdkVersion', 34)
 
+    // Shipped to the host app's shrinker so an integrator can enable R8 without
+    // learning which of our classes Nitro constructs by name. See the file.
+    consumerProguardFiles 'consumer-rules.pro'
+
+    // Whether the ML Kit models ship inside the APK. Read by the face detector
+    // and the text recogniser to short-circuit their readiness checks: on a
+    // bundled build the model is already here, and asking Play Services whether
+    // it holds the OPTIONAL module would answer "no" and strand a build that
+    // works perfectly offline.
+    buildConfigField "boolean", "BUNDLED_ML_KIT", "${bundledMlKit}"
+
     externalNativeBuild {
       cmake {
         cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
@@ -125,24 +141,22 @@ dependencies {
   // GMS. An org shipping to those devices sets `myazaKycBundledMlKit = true` in
   // its root build.gradle ext and gets today's fully-offline behaviour back.
   //
-  // Availability is NOT inferred per frame — `isModelReady()` is checked once
-  // before the camera opens (see HybridMyazaFaceDetector.kt), because a missing
-  // model would otherwise be indistinguishable from "no face in frame".
-  if (safeExtGet('myazaKycBundledMlKit', false).toString().toBoolean()) {
+  // Availability is NOT inferred per frame. Both models carry the same
+  // `isModelReady()` / `prepareModel()` contract, checked once before the
+  // camera opens, because the failure they guard against is identical: an
+  // absent model is indistinguishable from an empty frame (no face found, no
+  // text found), so a fresh install would sit on "position your face" or never
+  // auto-capture, with nothing able to say why.
+  //
+  // The Kotlin and Swift sources are unchanged by the switch — the unbundled
+  // artifacts expose the same `com.google.mlkit.vision.*` API, and the
+  // OptionalModuleApi the readiness check needs comes from the shared
+  // play-services common artifact both variants depend on.
+  if (bundledMlKit) {
     implementation 'com.google.mlkit:face-detection:16.1.6'
+    implementation 'com.google.mlkit:text-recognition:16.0.1'
   } else {
     implementation 'com.google.android.gms:play-services-mlkit-face-detection:17.1.0'
+    implementation 'com.google.android.gms:play-services-mlkit-text-recognition:19.0.1'
   }
-
-  // Text recognition is STILL BUNDLED, deliberately, and it is the larger of the
-  // two (10.55 MB vs 7.95 MB on arm64) — so this is the bigger half of the win,
-  // deferred rather than abandoned.
-  //
-  // Unbundling it needs the same isModelReady()/prepareModel() contract the face
-  // detector just gained. Without that, a missing OCR model is indistinguishable
-  // from "no text in frame": document auto-capture would simply never fire and
-  // MRZ scanning would never produce a key for the chip read, with nothing shown
-  // to the user. Shipping the dependency swap ahead of the availability handling
-  // would trade 10 MB for a silent failure on every fresh install.
-  implementation 'com.google.mlkit:text-recognition:16.0.1'
 }

package/android/consumer-rules.pro

@@ -0,0 +1,22 @@
+# Consumer R8 / ProGuard rules for @myazahq/kyc-sdk-react-native.
+#
+# Merged into the host app's shrinker configuration automatically through
+# `consumerProguardFiles`, so an integrator who enables R8 (`minifyEnabled true`,
+# `shrinkResources true`) needs nothing on their side. Enabling R8 is the single
+# biggest thing an integrator can do for the Java half of the SDK's footprint:
+# the unminified dex the SDK pulls in (CameraX, Play Services shims, Expo, Kotlin
+# reflection) is mostly code no flow ever calls.
+#
+# Nitro constructs every hybrid implementation BY CLASS NAME from C++: the
+# generated OnLoad registers one JNI constructor per spec, which the shrinker
+# cannot see. A shrunk build without these rules removes exactly the classes the
+# registry then fails to find, and the failure is a crash at the first camera
+# frame rather than a build error.
+-keep class com.margelo.nitro.** { *; }
+-keep class co.myazahq.kyc.rn.** { *; }
+
+# JJ2000, the JPEG 2000 decoder for the chip portrait, predates the shrinker
+# era. Keeping it whole costs about 0.3 MB and takes a whole class of
+# shrink-time surprises out of a decode that runs once per chip read.
+-keep class jj2000.** { *; }
+-dontwarn jj2000.**

package/android/src/main/AndroidManifest.xml

@@ -1,12 +1,23 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   <!--
-    NFC, for reading a passport's eMRTD chip. `required="false"` on the feature
-    is deliberate: the rest of the SDK works without NFC, and marking it
-    required would hide the host app from every device that has no NFC radio.
-    The chip step checks availability at runtime and skips instead.
+    NFC is DELIBERATELY NOT DECLARED HERE.
+    ======================================
+    Reading a passport's eMRTD chip needs android.permission.NFC, but a library
+    manifest is MERGED into every host app, so declaring it here gave the
+    permission to every integrator — including the majority whose workflows
+    never touch a chip, and who had no way to remove it. That is the opposite
+    of opt-in, and it silently contradicted the config plugin's own `nfc`
+    option, which defaults to OFF.
+
+    The permission AND the feature are now written by app.plugin.js, and only
+    on `nfc: true`. They must travel TOGETHER — see ensureNfcFeatureOptional()
+    there for why the feature is not an optional extra: Android infers
+    `required="true"` from the permission alone, which hides the host app from
+    every device with no NFC radio.
+
+    The chip step still checks availability at runtime and auto-skips on a
+    device with no radio, so a host that opts out loses nothing else.
   -->
-  <uses-permission android:name="android.permission.NFC" />
-  <uses-feature android:name="android.hardware.nfc" android:required="false" />
 
   <application>
     <!--

package/android/src/main/java/com/margelo/nitro/myazakyc/HybridMyazaFaceDetector.kt

@@ -9,8 +9,6 @@ import com.google.mlkit.vision.face.Face
 import com.google.mlkit.vision.face.FaceDetection
 import com.google.mlkit.vision.face.FaceDetector
 import com.google.mlkit.vision.face.FaceDetectorOptions
-import com.google.android.gms.common.moduleinstall.ModuleInstall
-import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit
@@ -44,67 +42,13 @@ class HybridMyazaFaceDetector : HybridMyazaFaceDetectorSpec() {
 
   // ── Model availability ───────────────────────────────────────────────────
   //
-  // The default build fetches ML Kit's models through Play Services instead of
-  // bundling them (android/build.gradle), which is what keeps ~18.5 MB per
-  // device out of the APK. The cost is a window where detection cannot run:
-  // first launch before the download completes, or a device with no GMS at all.
-  //
-  // `detectFace` CANNOT report that. Its only channel is FaceResult, where a
-  // missing model and an empty frame are both `faceCount: 0` — so a user on a
-  // fresh install would watch "position your face" forever with nothing to
-  // explain it. Hence a separate, explicit contract, checked before the camera
-  // opens rather than inferred per frame.
-  //
-  // Cached rather than queried live: `areModulesAvailable` is asynchronous and
-  // `isModelReady` is a synchronous Nitro call, so blocking the worklet thread
-  // to answer it would be worse than the problem. The flag starts false and is
-  // set by prepareModel(), which the SDK primes at flow start.
-  @Volatile private var modelReady = false
+  // Shared with the text recogniser: the rule and the reasoning are identical,
+  // so they live once in MlKitModelReadiness.kt rather than twice here.
+  private val readiness = MlKitModelReadiness(detector)
 
-  override fun isModelReady(): Boolean = modelReady
+  override fun isModelReady(): Boolean = readiness.isReady()
 
-  override fun prepareModel(): Promise<Boolean> = Promise.async {
-    if (modelReady) return@async true
-
-    val ctx = NitroModules.applicationContext
-      ?: return@async false // No context — cannot ask Play Services anything.
-
-    val latch = CountDownLatch(1)
-    var ok = false
-    try {
-      val client = ModuleInstall.getClient(ctx)
-      // areModulesAvailable() answers "is it already here"; deferredInstall()
-      // asks Play Services to fetch it in the background if not. Requesting the
-      // install unconditionally is simpler AND correct — it is a no-op when the
-      // module is already present, and starting it early is the entire point.
-      client.areModulesAvailable(detector)
-        .addOnSuccessListener { response ->
-          ok = response.areModulesAvailable()
-          if (!ok) {
-            // `deferredInstall` takes the OptionalModuleApi itself, varargs.
-            // A ModuleInstallRequest belongs to `installModules`, which is the
-            // FOREGROUND install with its own progress listener — a different
-            // call, and the one this used to hand its request to, which is why
-            // the Android build stopped compiling.
-            client.deferredInstall(detector)
-          }
-          latch.countDown()
-        }
-        .addOnFailureListener {
-          // Thrown on devices without Google Play Services at all (Huawei, bare
-          // AOSP). Not an error to retry — it will never succeed on this device.
-          // Such orgs should build with `myazaKycBundledMlKit = true`.
-          ok = false
-          latch.countDown()
-        }
-      latch.await(MODEL_CHECK_TIMEOUT_MS, TimeUnit.MILLISECONDS)
-    } catch (_: Throwable) {
-      ok = false
-    }
-
-    modelReady = ok
-    ok
-  }
+  override fun prepareModel(): Promise<Boolean> = Promise.async { readiness.prepare() }
 
   @ExperimentalGetImage
   override fun detectFace(frame: HybridFrameSpec): FaceResult {
@@ -121,13 +65,34 @@ class HybridMyazaFaceDetector : HybridMyazaFaceDetectorSpec() {
     val rotation = proxy.imageInfo.rotationDegrees
     val input = InputImage.fromMediaImage(mediaImage, rotation)
 
+    // Read the frame's dimensions HERE, synchronously, and let the callback use
+    // these ints rather than the Image.
+    //
+    // The listener runs on the main Looper whenever ML Kit finishes, which is
+    // not necessarily before `latch.await` below gives up. Once detectFace has
+    // returned, VisionCamera recycles the frame and closes the underlying
+    // android.media.Image — so a late callback touching `mediaImage.width`
+    // threw `IllegalStateException: Image is already closed` and took the whole
+    // app down, every time a face was actually FOUND (the failure listener
+    // reads nothing, so only success crashed).
+    //
+    // Unbundling the models is what exposed it: play-services-mlkit dispatches
+    // through Play Services IPC and is slower than the in-process bundled
+    // artifact, so the callback overruns the 200 ms wait routinely on real
+    // mid-range hardware. Seen on a TECNO KM5 (Android 15).
+    //
+    // The text recogniser already reads its dimensions up front for the same
+    // reason; this makes the two agree.
+    val imageWidth = mediaImage.width
+    val imageHeight = mediaImage.height
+
     var result: FaceResult? = null
     val latch = CountDownLatch(1)
     detector.process(input)
       .addOnSuccessListener { faces ->
         val face = faces.maxByOrNull { it.boundingBox.width() * it.boundingBox.height() }
         result = face?.let {
-          toResult(it, mediaImage.width, mediaImage.height, rotation, faces.size, brightness, faceRgb)
+          toResult(it, imageWidth, imageHeight, rotation, faces.size, brightness, faceRgb)
         }
         latch.countDown()
       }
@@ -285,14 +250,4 @@ class HybridMyazaFaceDetector : HybridMyazaFaceDetectorSpec() {
     faceG = -1.0,
     faceB = -1.0,
   )
-
-  private companion object {
-    /**
-     * Bound on the availability query. It is a local Play Services call, not the
-     * model download — the download runs in the background afterwards. Generous
-     * enough for a cold Play Services process, short enough that a wedged one
-     * cannot stall flow start.
-     */
-    const val MODEL_CHECK_TIMEOUT_MS = 3_000L
-  }
 }

package/android/src/main/java/com/margelo/nitro/myazakyc/HybridMyazaTextRecognizer.kt

@@ -32,6 +32,20 @@ class HybridMyazaTextRecognizer : HybridMyazaTextRecognizerSpec() {
   private val recognizer: TextRecognizer =
     TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)
 
+  // ── Model availability ───────────────────────────────────────────────────
+  //
+  // Shared with the face detector, because the failure is the same one: the
+  // model is fetched through Play Services rather than bundled, and a missing
+  // one is indistinguishable from a frame with no text in it. Left to the
+  // per-frame result, document auto-capture would simply never fire and the MRZ
+  // would never produce a key for the chip read, with nothing shown to explain
+  // it. See MlKitModelReadiness.kt.
+  private val readiness = MlKitModelReadiness(recognizer)
+
+  override fun isModelReady(): Boolean = readiness.isReady()
+
+  override fun prepareModel(): Promise<Boolean> = Promise.async { readiness.prepare() }
+
   @ExperimentalGetImage
   override fun recognizeText(frame: HybridFrameSpec, bottomFraction: Double): TextResult {
     val proxy: ImageProxy = (frame as? NativeFrame)?.image ?: return TextResult(emptyArray())

package/android/src/main/java/com/margelo/nitro/myazakyc/MlKitModelReadiness.kt

@@ -0,0 +1,154 @@
+package com.margelo.nitro.myazakyc
+
+import co.myazahq.kyc.rn.BuildConfig
+import com.google.android.gms.common.api.OptionalModuleApi
+import com.google.android.gms.common.moduleinstall.InstallStatusListener
+import com.google.android.gms.common.moduleinstall.ModuleInstall
+import com.google.android.gms.common.moduleinstall.ModuleInstallClient
+import com.google.android.gms.common.moduleinstall.ModuleInstallRequest
+import com.google.android.gms.common.moduleinstall.ModuleInstallStatusUpdate
+import com.margelo.nitro.NitroModules
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+
+/**
+ * The readiness gate both ML Kit detectors share.
+ *
+ * The default build fetches ML Kit's models through Play Services instead of
+ * bundling them (android/build.gradle), which is what keeps ~18.5 MB per device
+ * out of the APK. The cost is a window where the detector cannot run: first
+ * launch before the download completes, or a device with no GMS at all.
+ *
+ * Neither detector can report that through its own result. A face detector
+ * answers in `FaceResult`, where a missing model and an empty frame are both
+ * `faceCount: 0`; a text recogniser answers in `TextResult`, where both are an
+ * empty `lines` array. So a user on a fresh install would watch "position your
+ * face" forever, or aim at a passport that never auto-captures, with nothing to
+ * explain it. Hence a separate, explicit contract, checked before the camera
+ * opens rather than inferred per frame.
+ *
+ * Two properties make it actually settle, and both were missing once:
+ *  - The install is URGENT (`installModules`). `deferredInstall` leaves the
+ *    timing to Play Services, which may wait for an idle, charging phone; right
+ *    for a model somebody might want next week, wrong for one a person is
+ *    waiting on now.
+ *  - The answer is REFRESHED. `isModelReady` is a synchronous Nitro call and
+ *    `areModulesAvailable` is asynchronous, so it returns the cached flag, but
+ *    while the flag is false each call also starts a background re-check. The
+ *    cache used to be set once at flow start and never again, so a download that
+ *    finished a few seconds later was never noticed and the step gave up.
+ */
+class MlKitModelReadiness(private val api: OptionalModuleApi) {
+  // A bundled build has the model in the APK, so there is nothing to wait for
+  // and nothing to ask. Asking anyway would be worse than useless: Play
+  // Services answers about its OWN optional modules, so it would report "not
+  // available" and strand a build that works perfectly offline — which is the
+  // exact scenario the bundled flag exists to serve.
+  @Volatile private var ready = BuildConfig.BUNDLED_ML_KIT
+  @Volatile private var checking = false
+  @Volatile private var installing = false
+
+  fun isReady(): Boolean {
+    if (!ready) refresh()
+    return ready
+  }
+
+  /**
+   * Ask Play Services for the model, returning true once it is usable, and
+   * request an urgent install when it is not.
+   *
+   * Safe to call repeatedly; returns immediately when already ready. Blocking
+   * — callers run it inside a Nitro `Promise.async`.
+   */
+  fun prepare(): Boolean {
+    if (ready) return true
+
+    val ctx = NitroModules.applicationContext
+      ?: return false // No context — cannot ask Play Services anything.
+
+    val latch = CountDownLatch(1)
+    try {
+      val client = ModuleInstall.getClient(ctx)
+      client.areModulesAvailable(api)
+        .addOnSuccessListener { response ->
+          if (response.areModulesAvailable()) ready = true else requestInstall(client)
+          latch.countDown()
+        }
+        .addOnFailureListener {
+          // Thrown on devices without Google Play Services at all (Huawei, bare
+          // AOSP). Not an error to retry — it will never succeed on this device.
+          // Such orgs should build with `myazaKycBundledMlKit = true`.
+          latch.countDown()
+        }
+      latch.await(MODEL_CHECK_TIMEOUT_MS, TimeUnit.MILLISECONDS)
+    } catch (_: Throwable) {
+      // Leave `ready` as it was; the shared gate's wait decides when to stop.
+    }
+    return ready
+  }
+
+  /** Re-asks Play Services in the background; at most one check at a time. */
+  private fun refresh() {
+    if (checking) return
+    val ctx = NitroModules.applicationContext ?: return
+    checking = true
+    try {
+      ModuleInstall.getClient(ctx).areModulesAvailable(api)
+        .addOnSuccessListener { response -> if (response.areModulesAvailable()) ready = true }
+        .addOnCompleteListener { checking = false }
+    } catch (_: Throwable) {
+      checking = false
+    }
+  }
+
+  private fun requestInstall(client: ModuleInstallClient) {
+    if (installing) return
+    installing = true
+
+    val listener = object : InstallStatusListener {
+      override fun onInstallStatusUpdated(update: ModuleInstallStatusUpdate) {
+        when (update.installState) {
+          ModuleInstallStatusUpdate.InstallState.STATE_COMPLETED -> {
+            ready = true
+            installing = false
+            client.unregisterListener(this)
+          }
+          ModuleInstallStatusUpdate.InstallState.STATE_FAILED,
+          ModuleInstallStatusUpdate.InstallState.STATE_CANCELED -> {
+            // Cleared so the next prepare() can ask again.
+            installing = false
+            client.unregisterListener(this)
+          }
+        }
+      }
+    }
+
+    // `installModules` takes a ModuleInstallRequest; `deferredInstall` takes the
+    // OptionalModuleApi itself. Handing a request to the wrong one is how this
+    // file once stopped compiling.
+    val request = ModuleInstallRequest.Builder().addApi(api).setListener(listener).build()
+    client.installModules(request)
+      .addOnSuccessListener { response ->
+        // The listener never fires for a module that was already there.
+        if (response.areModulesAlreadyInstalled()) {
+          ready = true
+          installing = false
+          client.unregisterListener(listener)
+        }
+      }
+      .addOnFailureListener {
+        installing = false
+        client.unregisterListener(listener)
+      }
+  }
+
+  private companion object {
+    /**
+     * Bound on the availability query. It is a local Play Services call, not the
+     * model download — the download runs in the background afterwards. Generous
+     * enough for a cold Play Services process, short enough that a wedged one
+     * cannot stall flow start.
+     */
+    const val MODEL_CHECK_TIMEOUT_MS = 3_000L
+  }
+}