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

package/README.md

@@ -56,8 +56,11 @@ npx expo install @myazahq/kyc-sdk-react-native \
   react-native-safe-area-context react-native-svg
 ```
 
-Add the config plugins to `app.json`. The SDK's plugin adds the iOS camera usage
-string + Android `CAMERA`/`INTERNET` permissions; the VisionCamera plugin wires up
+Add the config plugins to `app.json`. The SDK's plugin adds the iOS camera and
+location usage strings + Android `CAMERA`/`INTERNET` and foreground location
+permissions (location backs the address-collection step's "Use my current
+location" and presence attestation; `["@myazahq/kyc-sdk-react-native",
+{ "location": false }]` opts out); the VisionCamera plugin wires up
 the camera + frame processors. Make sure the **New Architecture** is on (it is by
 default on Expo SDK 56):
 
@@ -67,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
@@ -82,8 +90,64 @@ npx expo run:ios                                  # iOS
 JAVA_HOME=/path/to/jdk-17 npx expo run:android    # Android — needs JDK 17
 ```
 
-> The SDK plugin accepts an optional custom camera prompt:
-> `["@myazahq/kyc-sdk-react-native", { "cameraPermission": "Your message…" }]`.
+> The SDK plugin accepts optional custom prompts:
+> `["@myazahq/kyc-sdk-react-native", { "cameraPermission": "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)
 
@@ -100,7 +164,8 @@ 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:
 cd ios && pod install && cd ..
@@ -113,11 +178,15 @@ prebuild):
   ```xml
   <key>NSCameraUsageDescription</key>
   <string>We use the camera to photograph your ID and capture a live selfie.</string>
+  <key>NSLocationWhenInUseUsageDescription</key>
+  <string>We use your location to confirm you are at the address you pin during verification.</string>
   ```
 - **Android** — add to `android/app/src/main/AndroidManifest.xml`:
   ```xml
   <uses-permission android:name="android.permission.CAMERA" />
   <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   ```
 - Ensure the **New Architecture** is enabled (`newArchEnabled=true` in
   `android/gradle.properties`; `RCT_NEW_ARCH_ENABLED=1` for the iOS Podfile install),
@@ -235,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'`.                                                             |
@@ -527,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
 
@@ -553,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)**.
@@ -560,3 +693,140 @@ Full documentation, configuration options, and webhook setup: **[trust.myaza.co/
 ## License
 
 MIT © Flitstack Technologies Inc.
+
+## Presence reporting (Address Intelligence)
+
+When a workflow enables presence verification (`addressCollection.presence.enabled`),
+the SDK stores the confirmed pin on-device at capture. Call the reporter from your
+app on a natural moment (app open works well):
+
+```tsx
+import { reportAddressPresence, clearPresencePin } from '@myazahq/kyc-sdk-react-native';
+
+const result = await reportAddressPresence({
+  apiKey: 'pk_live_…',
+  externalUserId: 'user_42', // the same userId the KYC flow ran with
+});
+// result.reason: 'reported' | 'no_pin' | 'services_off' | 'no_fix' | 'outside_fence' | 'network_error'
+```
+
+It never throws and never blocks startup. The geofence is evaluated ON-DEVICE:
+only the derived record (calendar day + a night flag) is transmitted, never a
+coordinate. A fix outside the fence sends nothing (the server scores presence,
+never absence); a mock-location fix is reported flagged. `clearPresencePin`
+drops the stored pin (sign-out, or once the watch resolves).
+
+### Background monitoring (OS geofencing)
+
+The stronger tier: the OS wakes the SDK on fence crossings around the stored
+pin, app closed or not, so dwell and nights accrue with nobody in the loop.
+Entries stamp a timestamp; exits fold the dwell span into per-day aggregates
+and flush them. As with the foreground tier, only the derived day records
+ever leave the phone.
+
+Three opt-ins, each deliberate:
+
+1. Install the optional peer: `npx expo install expo-task-manager` (without
+   it the background tier simply does not exist — never a crash).
+2. Declare background location via the config plugin — this is what changes
+   your app's store review posture, so it is never a default:
+
+   ```json
+   ["@myazahq/kyc-sdk-react-native", { "location": "always" }]
+   ```
+
+3. Register the task at your app's ROOT module (before the component tree —
+   a task defined inside a component never fires headlessly), then enable:
+
+   ```tsx
+   // index.js
+   import { registerBackgroundPresence } from '@myazahq/kyc-sdk-react-native';
+   registerBackgroundPresence();
+
+   // later, after the KYC flow stored a pin:
+   const result = await enableBackgroundPresence({
+     apiKey: 'pk_live_…',
+     externalUserId: 'user_42',
+   });
+   // result.reason: 'enabled' | 'module_missing' | 'no_pin'
+   //              | 'foreground_denied' | 'background_denied' | 'start_failed'
+   ```
+
+`disableBackgroundPresence()` disarms the fence. A permission refusal leaves
+the foreground tier working exactly as before — the tiers degrade, never
+break.
+
+### The Android foreground service (reliability on OEM-managed phones)
+
+A geofence alone is not reliable on Android once a manufacturer's battery
+manager decides your app is idle: transitions are dropped, nothing says so,
+and the watch quietly lapses to inconclusive. The phones on that list (Tecno,
+Infinix, itel, Xiaomi, Oppo, Vivo) are the ones the market carries. A
+foreground service, with its persistent notification, is the one thing those
+managers leave alone — and OkHi's own integration guidance for the same
+markets is exactly this.
+
+Opt-in, Android only (iOS region monitoring is reliable on its own), on the
+same `location: "always"` plugin setting, which also declares the
+`FOREGROUND_SERVICE` and `FOREGROUND_SERVICE_LOCATION` permissions it needs.
+`registerBackgroundPresence()` at the root already defines its task; then:
+
+```tsx
+const result = await enableForegroundService({
+  apiKey: 'pk_live_…',
+  externalUserId: 'user_42',
+  notification: {
+    title: 'Address verification in progress', // shown in the status bar
+    body: 'Open the app to see your progress',
+    color: '#5645F5',
+  },
+});
+// result.reason: 'enabled' | 'unsupported_platform' | 'module_missing' | 'no_pin'
+//              | 'foreground_denied' | 'background_denied' | 'start_failed'
+```
+
+While it runs, a low-power fix every ten minutes (or hundred metres) is
+turned into the same enter/exit spans the geofence folds, on the same stored
+state, so the two never double-count a stay; the queue flushes while the
+process is alive; and a fence the OS dropped (a location toggle clears every
+registered fence) is re-armed. `disableForegroundService()` stops it and its
+notification. Word the notification honestly — it is on screen for days.
+
+### Which tier is running?
+
+Permissions get revoked in Settings and nothing tells the app. Ask:
+
+```tsx
+import { presenceStatus, openLocationSettings } from '@myazahq/kyc-sdk-react-native';
+
+const status = await presenceStatus('user_42');
+// status.tier: 'background' | 'foreground' | 'none'
+// plus pinStored, alwaysOn, locationServicesEnabled, both permission states,
+// geofenceArmed, foregroundServiceRunning
+if (!status.locationServicesEnabled) {
+  // The phone's location toggle is off: permission granted or not, no fix
+  // can be taken. Android deep-links to the toggle itself.
+  await openLocationSettings('services');
+} else if (status.tier === 'none' && status.pinStored) {
+  // The road back runs through Settings — no OS allows re-prompting in-app.
+  await openLocationSettings();
+}
+```
+
+### Showing the person where the check stands
+
+Somebody kept from a feature until their address is verified should be able
+to see the progress in your app, without a webhook relayed through your
+backend. The status endpoint is publishable-safe and enumeration-safe (an
+unknown user and a user with no watch answer the same `not_started` shape):
+
+```ts
+const res = await fetch(`${serverUrl}/api/kyc/address/presence/${externalUserId}`, {
+  headers: { Authorization: `Bearer pk_live_…` },
+});
+const { status, progress, tier } = await res.json();
+// status: 'not_started' | 'in_progress' | 'verified' | 'failed' | 'inconclusive' | 'expired' | 'revoked'
+// progress.score: 0..1 on WEIGHTED evidence (five foreground nights and three
+//                 geofence nights both read 1); nightsObserved/daysObserved beside it
+// tier: 'background' | 'foreground' | null — what is actually feeding it
+```

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,9 +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.google.android.gms.common.moduleinstall.ModuleInstallRequest
-import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit
@@ -45,64 +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) {
-            client.deferredInstall(
-              ModuleInstallRequest.newBuilder().addApi(detector).build(),
-            )
-          }
-          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 {
@@ -119,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()
       }
@@ -283,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())