@smileid/usesmileid_mlkit_face 12.2.0 → 12.3.0

package/CHANGELOG.md

@@ -1,10 +1,14 @@
 Full release notes: [Smile ID docs](https://docs.usesmileid.com/developer-resources/sdks/mobile/release-notes/react-native-expo).
 
+## 12.3.0
+
+See the repository CHANGELOG for the 12.3.0 release notes.
+
+
 ## 12.2.0
 
 See the repository CHANGELOG for the 12.2.0 release notes.
 
-
 ## 12.1.1
 
 See the repository CHANGELOG for the 12.1.1 release notes.

package/android/build.gradle

@@ -17,7 +17,7 @@ plugins {
 }
 
 group = 'com.usesmileid.mlkit.face'
-version = '12.2.0'
+version = '12.3.0'
 
 android {
   namespace 'com.usesmileid.mlkit.face'
@@ -29,7 +29,7 @@ android {
   // android/build.gradle and the rest of the @expo/* modules.
   defaultConfig {
     versionCode 1
-    versionName '12.2.0'
+    versionName '12.3.0'
     // R8 keep-rules to bundle into partner apps that depend on this
     // module. Without these, R8 may rename the Expo module entry
     // point and the JS-bridged member functions, breaking autolinking.
@@ -41,14 +41,33 @@ dependencies {
   // kamera native core: the analyzer executor takes analysis frames from
   // kamera's KameraFrameHub so pixels never cross the JS bridge. Resolves from
   // Maven Central; a local publishToMavenLocal build wins (see kamera.md).
-  implementation 'com.usesmileid:kamera:1.1.0'
+  implementation 'com.usesmileid:kamera:1.2.0'
+
+  // The analyzer executor and frame storage every provider module shares, from the bridge module.
+  implementation project(':smileid-usesmileid_bridge')
 
   // Existing Smile ID native AAR — the entire ML pipeline lives here.
   // This Expo Module is a thin Kotlin shim that constructs the
   // session and bridges its four methods to JS via Expo Modules.
-  implementation 'com.usesmileid:mlkit-face:12.2.0'
+  implementation 'com.usesmileid:mlkit-face:12.3.0'
+  // The bridge build the bridge module ships. The provider's SDK artifact names its bridge too, and a
+  // snapshot names the moving x.y.z-SNAPSHOT, so this keeps the provider compiling against the build
+  // the app runs.
+  implementation 'com.usesmileid:bridge:12.3.0'
+
+
+}
 
 
+// The provider compiles against the executor the bridge module ships, so the two must be one release:
+// a mixed install would build this provider against a bridge that lacks what it needs.
+def smileIdPackageVersion = { File packageDir -> new groovy.json.JsonSlurper().parse(new File(packageDir, 'package.json')).version }
+def bridgeVersion = smileIdPackageVersion(project(':smileid-usesmileid_bridge').projectDir.parentFile)
+def providerVersion = smileIdPackageVersion(projectDir.parentFile)
+if (bridgeVersion != providerVersion) {
+  throw new GradleException(
+    "@smileid/usesmileid_bridge is $bridgeVersion but ${project.name} is $providerVersion: install every @smileid package at one version."
+  )
 }
 
 // kamera resolves from Maven Central. mavenLocal stays injected — content-filtered to

package/android/consumer-rules.pro

@@ -17,10 +17,3 @@
     public static **[] values();
     public static ** valueOf(java.lang.String);
 }
-
-# ─── Shared RN analyzer-executor namespace ──────────────────────────────────
-# RN providers reach into `com.usesmileid.rn.analyzer.<provider>` for their
-# local `UseSmileIDAnalyzerExecutor` subclass (the pattern this workspace
-# uses before the Flutter executor was de-duplicated). Keep that namespace
-# intact so JS-bridged calls resolve.
--keep class com.usesmileid.rn.analyzer.mlkitface.** { *; }

package/android/src/main/java/com/usesmileid/mlkit/face/UseSmileIDMlkitFaceKameraAnalysisTick.kt

@@ -1,42 +1,44 @@
 package com.usesmileid.mlkit.face
 
-import com.usesmileid.bridge.model.YuvFrame as NativeYuvFrame
+import com.usesmileid.kamera.frame.KameraFrame
 import com.usesmileid.kamera.integration.KameraFrameHub
-import com.usesmileid.rn.analyzer.mlkitface.toNativeYuvFrame
 import kotlin.coroutines.cancellation.CancellationException
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withContext
 
 /**
  * Scans the latest [KameraFrameHub] frame natively; no pending frame returns the `no_frame` wire error.
- * The frame's rotationDegrees already uprights the buffer to the locked interface axis.
+ * The frame's rotationDegrees already uprights the buffer to the locked interface axis; the frame
+ * stays open until its scan returns.
  */
-internal fun analyzeKameraFrameTick(arguments: Map<String, Any?>?): Any {
-    val frame = KameraFrameHub.take() ?: return mapOf("error" to "no_frame")
-    val yuvFrame = try {
-        frame.toNativeYuvFrame()
-    } finally {
-        // Closing releases the frame to the pipeline; the converted copy owns its own bytes.
-        frame.close()
-    }
+internal fun analyzeKameraFrameTick(
+    arguments: Map<String, Any?>?,
+    takeFrame: () -> KameraFrame? = KameraFrameHub::take,
+): Any {
+    val frame = takeFrame() ?: return mapOf("error" to "no_frame")
+    // The session reads the live frame in place, as the native capture screens do; closing it once
+    // the tick ends, on every path, releases it to the pipeline for the next one.
+    try {
+        // Device-tilt context (0 = upright portrait) for the validators.
+        val jsRotation = (arguments?.get("rotation") as? Number)?.toInt() ?: 0
 
-    // Device-tilt context (0 = upright portrait) for the validators.
-    val jsRotation = (arguments?.get("rotation") as? Number)?.toInt() ?: 0
+        return runBlocking {
+            withContext(UseSmileIDMlkitFaceSessionHolder.sessionDispatcher) {
+                val activeSession = UseSmileIDMlkitFaceSessionHolder.session
+                    ?: return@withContext mapOf("error" to "session_not_configured")
 
-    return runBlocking {
-        withContext(UseSmileIDMlkitFaceSessionHolder.sessionDispatcher) {
-            val activeSession = UseSmileIDMlkitFaceSessionHolder.session
-                ?: return@withContext mapOf("error" to "session_not_configured")
-
-            try {
-                val scanResult = activeSession.scan(yuvFrame, jsRotation)
-                val events = activeSession.drainCaptureReadyEvents()
-                UseSmileIDMlkitFaceModule.buildWireResult(scanResult, events)
-            } catch (cancellation: CancellationException) {
-                throw cancellation
-            } catch (e: Exception) {
-                mapOf("error" to ("scan_failed: " + (e.message ?: e.javaClass.simpleName)))
+                try {
+                    val scanResult = activeSession.scan(frame, jsRotation)
+                    val events = activeSession.drainCaptureReadyEvents()
+                    UseSmileIDMlkitFaceModule.buildWireResult(scanResult, events)
+                } catch (cancellation: CancellationException) {
+                    throw cancellation
+                } catch (e: Exception) {
+                    mapOf("error" to ("scan_failed: " + (e.message ?: e.javaClass.simpleName)))
+                }
             }
         }
+    } finally {
+        frame.close()
     }
 }

package/android/src/main/java/com/usesmileid/mlkit/face/UseSmileIDMlkitFaceModule.kt

@@ -9,15 +9,18 @@ import com.usesmileid.bridge.model.HeadPoseResult
 import com.usesmileid.bridge.model.YuvFrame as NativeYuvFrame
 import com.usesmileid.bridge.registry.FaceAnalyzerFactoryRegistry
 import com.usesmileid.bridge.session.FaceScanConfig
+import com.usesmileid.bridge.session.UseSmileIDCaptureStep
 import com.usesmileid.bridge.session.UseSmileIDFaceScanResult
 import com.usesmileid.bridge.session.UseSmileIDFaceSession
 import com.usesmileid.bridge.session.UseSmileIDScanState
 import com.usesmileid.bridge.session.UseSmileIDScanStateType
 import com.usesmileid.bridge.storage.FrameStorage
-import com.usesmileid.rn.analyzer.mlkitface.UseSmileIDAnalyzerExecutor
+import com.usesmileid.bridge.model.CaptureType
+import com.usesmileid.rn.analyzer.UseSmileIDAnalyzerExecutor
 import expo.modules.kotlin.Promise
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
+import com.usesmileid.bridge.config.ThresholdConfig
 
 /**
  * Expo Module bridging the existing native session
@@ -44,6 +47,9 @@ class UseSmileIDMlkitFaceModule : Module() {
         UseSmileIDFaceScanResult,
         >() {
 
+        override val storageCaptureType: CaptureType = CaptureType.SELFIE
+
+
         override fun createSession(
             config: Map<String, Any?>,
             frameStorage: FrameStorage,
@@ -177,12 +183,10 @@ private fun Map<String, Any?>.toFaceScanConfig(): FaceScanConfig {
     // overlay any explicitly-set threshold field on top.
     val base = FaceDetectorMode.fromToken(this["faceDetectorMode"] as? String).config
     return FaceScanConfig(
-        selfieCaptureTimeout = (this["selfieCaptureTimeout"] as? Number)?.toInt() ?: 100_000,
-        // Default yields 1 selfie + 7 liveness frames — the server requires
-        // `liveness_images >= 6`, so anything below 7 causes submission rejection.
-        numSamples = (this["numSamples"] as? Number)?.toInt() ?: 8,
-        sampleInterval = (this["sampleInterval"] as? Number)?.toInt() ?: 350,
-        stayInFoundDuration = (this["stayInFoundDuration"] as? Number)?.toInt() ?: 3_000,
+        numSamples = (this["numSamples"] as? Number)?.toInt() ?: ThresholdConfig.FaceCapture.NUM_SAMPLES,
+        sampleInterval = (this["sampleInterval"] as? Number)?.toInt() ?: ThresholdConfig.FaceCapture.SAMPLE_INTERVAL_MS,
+        stayInFoundDuration = (this["stayInFoundDuration"] as? Number)?.toInt()
+            ?: ThresholdConfig.FaceCapture.DEFAULT_STAY_IN_FOUND_DURATION_MS,
         minFillThreshold = (this["minFillThreshold"] as? Number)?.toFloat() ?: base.minFillThreshold,
         maxFillThreshold = (this["maxFillThreshold"] as? Number)?.toFloat() ?: base.maxFillThreshold,
         faceDetectorMinScore = (this["faceDetectorMinScore"] as? Number)?.toFloat() ?: base.faceDetectorMinScore,
@@ -255,10 +259,16 @@ private fun UseSmileIDScanState.toWireMap(): Map<String, Any?> = buildMap {
     // Head-turn direction for Enhanced Smart Selfie guidance.
     currentDirection?.let { put("currentDirection", it.name.lowercase()) }
     captureProgress?.let { put("captureProgress", it.toDouble()) }
-    // Latched pose-match flag for the ESS head turn — drives the grey→green
-    // direction arrow. Emit only while matched (omit ⇒ false on the JS side),
+    // Latched pose-match flag for the ESS head turn — keeps the direction arrow
+    // green through a hold at the threshold. Emit only while matched (omit ⇒ false on the JS side),
     // matching the optional-field omission convention above.
     if (poseMatched) put("poseMatched", true)
+    when (captureStep) {
+        UseSmileIDCaptureStep.HOLD_STILL -> put("captureStep", "holdStill")
+        UseSmileIDCaptureStep.SMILE -> put("captureStep", "smile")
+        null -> Unit
+    }
+    turnProgress?.let { put("turnProgress", it.toDouble()) }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smileid/usesmileid_mlkit_face",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "description": "Android MLKit face detection implementation for the UseSmileID React Native (Expo) SDK.",
   "homepage": "https://usesmileid.com",
   "repository": {
@@ -47,8 +47,8 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@smileid/usesmileid_bridge": "12.2.0",
-    "@smileid/usesmileid_platform_interface": "12.2.0"
+    "@smileid/usesmileid_platform_interface": "12.3.0",
+    "@smileid/usesmileid_bridge": "12.3.0"
   },
   "peerDependencies": {
     "expo": ">=56.0.0",
@@ -56,9 +56,9 @@
     "react-native": ">=0.83.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.2",
-    "expo": "~57.0.25",
-    "expo-modules-core": "^57.0.19",
+    "@types/node": "^26.6.4",
+    "expo": "~57.0.26",
+    "expo-modules-core": "^57.0.21",
     "react-native": "^0.86.3",
     "typescript": "^6.0.3"
   },

package/android/src/main/java/com/usesmileid/rn/analyzer/mlkitface/ResizingFrameStorage.kt

@@ -1,329 +0,0 @@
-// MIRRORED FILE — duplicated into all four RN Expo Android analyzer modules
-// (mlkitface / mlkitdoc / huaweiface / huaweidoc). The per-module sub-package
-// is required so a partner shipping multiple backends doesn't get a dex-merge
-// FQN collision. Only the `package` declaration differs across copies; any
-// edit here MUST be applied to the other three locations in the same commit.
-
-package com.usesmileid.rn.analyzer.mlkitface
-
-import com.usesmileid.bridge.model.BoundingBox as NativeBoundingBox
-import com.usesmileid.bridge.model.CaptureType
-import com.usesmileid.bridge.model.ViewportCropRegion as NativeViewportCropRegion
-import com.usesmileid.bridge.model.YuvFrame
-import com.usesmileid.bridge.storage.DocumentSide
-import com.usesmileid.bridge.storage.FrameKind
-import com.usesmileid.bridge.storage.FrameStorage
-import com.usesmileid.bridge.storage.writeJpegToFileExact
-import com.usesmileid.bridge.util.toArgbBitmap
-import java.io.File
-import java.io.IOException
-import java.util.concurrent.ConcurrentHashMap
-import java.util.concurrent.ConcurrentLinkedDeque
-import java.util.concurrent.atomic.AtomicReference
-import kotlin.coroutines.cancellation.CancellationException
-import kotlin.math.roundToInt
-import kotlinx.coroutines.CoroutineExceptionHandler
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.Job
-import kotlinx.coroutines.SupervisorJob
-import kotlinx.coroutines.launch
-import kotlinx.coroutines.withContext
-
-/**
- * [FrameStorage] implementation that center-crops and scales every selfie and
- * liveness JPEG to the configured target dimensions before writing.
- *
- * Target dimensions are resolved at configure-time from the token
- * `sdk_config` claim; the executor falls back to 480 × 640 when the token
- * carries no override, so the on-disk pixel size always matches the
- * `image_width` / `image_height` values reported in job metadata.
- *
- * Document frames are decoded upright, then cropped to the guide rectangle when
- * a crop region has been published via [setCropRegion] (the on-screen frame the
- * user aligned the document into) so the uploaded image matches the capture
- * preview. The crop runs at full resolution first; the resulting crop is then
- * downscaled so its longest edge is bounded at [DOCUMENT_MAX_DIMENSION] (1600
- * px), preserving aspect ratio and never upscaling, before JPEG-encoding at the
- * specified [documentQuality]. Cropping before the downscale keeps maximum
- * detail in the document region — the bound applies to the crop, not the whole
- * frame, so a tightly framed card fills the saved pixels. Document dimensions
- * are not part of the token `sdk_config` contract.
- *
- * Resize and encode run on a private `Dispatchers.IO` scope; [persist] is
- * fire-and-forget so the analyzer keeps running at frame rate. [flush] awaits
- * all in-flight writes before upload proceeds.
- */
-internal class ResizingFrameStorage(
-    private val sessionDirectory: File,
-    private val captureType: CaptureType,
-    private val documentSide: DocumentSide = DocumentSide.Front,
-    private val selfieTargetWidth: Int = 480,
-    private val selfieTargetHeight: Int = 640,
-    private val livenessTargetWidth: Int = 480,
-    private val livenessTargetHeight: Int = 640,
-    private val selfieQuality: Int = 95,
-    private val livenessQuality: Int = 80,
-    private val documentQuality: Int = 85,
-) : FrameStorage {
-
-    companion object {
-        /**
-         * Longest-edge bound, in pixels, for the saved document JPEG. The
-         * guide-rect crop is downscaled so its larger dimension never exceeds
-         * this value, preserving aspect ratio and never upscaling.
-         */
-        private const val DOCUMENT_MAX_DIMENSION = 1600
-
-        /**
-         * The hidden border kept around the guide rect: this fraction of the
-         * saved image's short side on every edge, the rule of the native
-         * bridges' `DocumentCropGeometry.DOCUMENT_BORDER_FRACTION` and the
-         * selfie's interior crop. The border is where presentation-attack cues
-         * live; the backend reads it, and the preview shows only the interior.
-         */
-        internal const val DOCUMENT_BORDER_FRACTION = 0.15f
-
-        /**
-         * The uniform border, in pixels, to grow a [left], [top], [right],
-         * [bottom] guide by: the b that is [DOCUMENT_BORDER_FRACTION] of the
-         * grown rect's own short side, b = f × s / (1 − 2f) for the guide's
-         * short side s. Shrinks to the most every edge of a [width] × [height]
-         * image can hold; 0 for an empty guide or one touching an edge.
-         * Mirrors the native bridges' `DocumentCropGeometry.borderAround`.
-         */
-        internal fun borderAround(left: Float, top: Float, right: Float, bottom: Float, width: Int, height: Int): Float {
-            val shortSide = minOf(right - left, bottom - top)
-            if (shortSide <= 0f) return 0f
-            val wanted = DOCUMENT_BORDER_FRACTION * shortSide / (1f - 2f * DOCUMENT_BORDER_FRACTION)
-            val room = minOf(left, top, width - right, height - bottom)
-            return minOf(wanted, room).coerceAtLeast(0f)
-        }
-
-        /**
-         * A [border] of pixels around a [width] × [height] crop as a fraction of the
-         * crop's short side, held to [DOCUMENT_BORDER_FRACTION] so the crop's pixel
-         * rounding never reports more border than was kept; 0 for an empty crop.
-         */
-        internal fun borderFraction(border: Float, width: Int, height: Int): Float {
-            val shortSide = minOf(width, height)
-            if (shortSide <= 0) return 0f
-            return (border / shortSide).coerceIn(0f, DOCUMENT_BORDER_FRACTION)
-        }
-    }
-
-    /** A backstop for anything that escapes the write's own catch; [flush] still surfaces it. */
-    private val scope = CoroutineScope(
-        SupervisorJob() + Dispatchers.IO + CoroutineExceptionHandler { _, e -> firstError.compareAndSet(null, e) },
-    )
-    private val pending = ConcurrentLinkedDeque<Job>()
-    private val firstError = AtomicReference<Throwable?>(null)
-
-    /** Read back as [FrameStorage.cropRegion], which the document transitioner judges the detected document against. */
-    @Volatile
-    override var cropRegion: NativeViewportCropRegion? = null
-        private set
-
-    /**
-     * The hidden border of each document this storage saved with one, by absolute
-     * path, as a fraction of the document's short side. Written on the encode scope
-     * once the file is written, read after [flush].
-     */
-    private val savedBorderFractions = ConcurrentHashMap<String, Float>()
-
-    /**
-     * The hidden border the document at [file] was saved with, as a fraction of its
-     * short side on every edge: [DOCUMENT_BORDER_FRACTION] when the frame had room for
-     * all of it, less where it did not, and 0 for a document saved without a guide
-     * crop or a file this storage did not write. The screens that show the document
-     * hide exactly this much.
-     */
-    fun borderFractionOf(file: File): Float = savedBorderFractions[file.absolutePath] ?: 0f
-
-    private fun recordBorder(file: File, borderFraction: Float) {
-        if (borderFraction > 0f) {
-            savedBorderFractions[file.absolutePath] = borderFraction
-        } else {
-            savedBorderFractions.remove(file.absolutePath)
-        }
-    }
-
-    override fun setCropRegion(region: NativeViewportCropRegion?) {
-        cropRegion = region
-    }
-
-    override fun fileFor(kind: FrameKind, captureIndex: Int): File = File(
-        sessionDirectory,
-        when (kind) {
-            FrameKind.Selfie -> "selfie.jpg"
-            FrameKind.Liveness -> "liveness_$captureIndex.jpg"
-            FrameKind.Document -> when (documentSide) {
-                DocumentSide.Front -> "document_front.jpg"
-                DocumentSide.Back -> "document_back.jpg"
-                DocumentSide.Visa -> "document_visa.jpg"
-            }
-        },
-    )
-
-    override fun persist(frame: YuvFrame, file: File) {
-        launchEncode(frame, file, documentCropRegion = null)
-    }
-
-    override fun persistDocument(frame: YuvFrame, file: File, liveBoundingBox: NativeBoundingBox?) {
-        // Snapshot the crop region at dispatch time so a concurrent
-        // setCropRegion(null) between here and the coroutine body can't tear
-        // the state. liveBoundingBox is unused: the guide rectangle the user
-        // framed (cropRegion) takes precedence over the live detector box.
-        launchEncode(frame, file, documentCropRegion = cropRegion)
-    }
-
-    private fun launchEncode(frame: YuvFrame, file: File, documentCropRegion: NativeViewportCropRegion?) {
-        val job = scope.launch {
-            try {
-                encodeAndWrite(frame, file, documentCropRegion)
-            } catch (e: CancellationException) {
-                runCatching { file.delete() }
-                recordBorder(file, 0f)
-                throw e
-            } catch (e: Throwable) {
-                runCatching { file.delete() }
-                recordBorder(file, 0f)
-                // Surfaced by flush; a rethrow here would reach the host's uncaught handler.
-                firstError.compareAndSet(null, e)
-            }
-        }
-        // Add synchronously so flush() cannot race past an in-flight job.
-        pending.add(job)
-    }
-
-    override suspend fun flush() {
-        val jobs = mutableListOf<Job>()
-        while (true) jobs.add(pending.poll() ?: break)
-        jobs.forEach { it.join() }
-        firstError.getAndSet(null)?.let { throw it }
-    }
-
-    override fun clear() {
-        // Selfie and document captures share one session directory; delete
-        // only this role's own frames.
-        sessionDirectory.listFiles()?.forEach { file ->
-            if (ownsForClear(file)) {
-                file.delete()
-                recordBorder(file, 0f)
-            }
-        }
-    }
-
-    private fun ownsForClear(file: File): Boolean = when (captureType) {
-        CaptureType.SELFIE -> {
-            val kind = frameKindOf(file)
-            kind == FrameKind.Selfie || kind == FrameKind.Liveness
-        }
-        CaptureType.DOCUMENT -> file.name == fileFor(FrameKind.Document, captureIndex = 0).name
-    }
-
-    private fun frameKindOf(file: File): FrameKind? = when {
-        file.name.startsWith("selfie") -> FrameKind.Selfie
-        file.name.startsWith("liveness") -> FrameKind.Liveness
-        file.name.startsWith("document") -> FrameKind.Document
-        else -> null
-    }
-
-    private suspend fun encodeAndWrite(
-        frame: YuvFrame,
-        file: File,
-        documentCropRegion: NativeViewportCropRegion?,
-    ) {
-        withContext(Dispatchers.IO) {
-            file.parentFile?.mkdirs()
-            val name = file.name
-            when {
-                name.startsWith("selfie") -> {
-                    val bitmap = frame.toArgbBitmap(jpegQuality = selfieQuality)
-                        ?: throw IOException("toArgbBitmap returned null for ${file.name}")
-                    try {
-                        bitmap.writeJpegToFileExact(file, selfieTargetWidth, selfieTargetHeight, selfieQuality)
-                    } finally {
-                        bitmap.recycle()
-                    }
-                }
-                name.startsWith("liveness") -> {
-                    val bitmap = frame.toArgbBitmap(jpegQuality = livenessQuality)
-                        ?: throw IOException("toArgbBitmap returned null for ${file.name}")
-                    try {
-                        bitmap.writeJpegToFileExact(file, livenessTargetWidth, livenessTargetHeight, livenessQuality)
-                    } finally {
-                        bitmap.recycle()
-                    }
-                }
-                else -> {
-                    // Document frames: decode to the upright bitmap, crop to the guide
-                    // rectangle (if a crop region is set) at full resolution, then
-                    // downscale the crop so its longest edge is bounded at
-                    // DOCUMENT_MAX_DIMENSION. Cropping before the downscale keeps maximum
-                    // detail in the document region — the bound applies to the crop, not
-                    // the whole frame, so a tightly framed card fills the saved pixels.
-                    // toFrameBoundingBox returns a normalized 0–1 box in the upright
-                    // frame's coordinate space, mapped to pixels by the bitmap dimensions.
-                    // The box grows by the hidden border (DOCUMENT_BORDER_FRACTION of the
-                    // saved image's short side, uniform on every edge), which the preview
-                    // never shows, so it shows what the user framed.
-                    val source = frame.toArgbBitmap(jpegQuality = documentQuality)
-                        ?: throw IOException("toArgbBitmap returned null for ${file.name}")
-                    val (cropped, borderFraction) = if (documentCropRegion != null) {
-                        val box = documentCropRegion.toFrameBoundingBox(source.width, source.height)
-                        val border = borderAround(
-                            box.left * source.width,
-                            box.top * source.height,
-                            (box.left + box.width) * source.width,
-                            (box.top + box.height) * source.height,
-                            source.width,
-                            source.height,
-                        )
-                        val padX = border / source.width
-                        val padY = border / source.height
-                        // Clamp left/top to leave room for at least one pixel and derive
-                        // right/bottom from the clamped left/top so the crop never runs past
-                        // the bitmap edge. Bitmap.createBitmap throws IllegalArgumentException
-                        // when x + width exceeds the source width, which is reachable if the
-                        // padded box lands fully off an edge and both bounds collapse onto the
-                        // same coordinate.
-                        val pixelLeft = ((box.left - padX) * source.width).roundToInt().coerceIn(0, source.width - 1)
-                        val pixelTop = ((box.top - padY) * source.height).roundToInt().coerceIn(0, source.height - 1)
-                        val pixelRight = ((box.left + box.width + padX) * source.width).roundToInt().coerceIn(pixelLeft + 1, source.width)
-                        val pixelBottom = ((box.top + box.height + padY) * source.height).roundToInt().coerceIn(pixelTop + 1, source.height)
-                        val cropWidth = (pixelRight - pixelLeft).coerceAtLeast(1)
-                        val cropHeight = (pixelBottom - pixelTop).coerceAtLeast(1)
-                        android.graphics.Bitmap.createBitmap(source, pixelLeft, pixelTop, cropWidth, cropHeight) to
-                            borderFraction(border, cropWidth, cropHeight)
-                    } else {
-                        source to 0f
-                    }
-                    // Downscale the crop so its longest edge is at most
-                    // DOCUMENT_MAX_DIMENSION, preserving aspect ratio. Skip when the crop
-                    // already fits so a small document is never upscaled.
-                    val longest = maxOf(cropped.width, cropped.height)
-                    val scaled = if (longest > DOCUMENT_MAX_DIMENSION) {
-                        val scale = DOCUMENT_MAX_DIMENSION.toFloat() / longest
-                        val scaledWidth = (cropped.width * scale).roundToInt().coerceAtLeast(1)
-                        val scaledHeight = (cropped.height * scale).roundToInt().coerceAtLeast(1)
-                        android.graphics.Bitmap.createScaledBitmap(cropped, scaledWidth, scaledHeight, true)
-                    } else {
-                        cropped
-                    }
-                    try {
-                        val success = file.outputStream().use {
-                            scaled.compress(android.graphics.Bitmap.CompressFormat.JPEG, documentQuality, it)
-                        }
-                        if (!success) throw IOException("Bitmap.compress(JPEG) failed for ${file.absolutePath}")
-                        recordBorder(file, borderFraction)
-                    } finally {
-                        if (scaled !== cropped) scaled.recycle()
-                        if (cropped !== source) cropped.recycle()
-                        source.recycle()
-                    }
-                }
-            }
-        }
-    }
-}

package/android/src/main/java/com/usesmileid/rn/analyzer/mlkitface/UseSmileIDAnalyzerExecutor.kt

@@ -1,336 +0,0 @@
-// MIRRORED FILE — duplicated into all four RN Expo Android analyzer modules
-// (mlkitface / mlkitdoc / huaweiface / huaweidoc). The per-module sub-package
-// suffix is required so a partner shipping multiple backends doesn't get a
-// dex-merge FQN collision. Only the `package` declaration differs across copies;
-// any edit here MUST be applied to the other three locations in the same commit.
-
-package com.usesmileid.rn.analyzer.mlkitface
-
-import android.content.Context
-import com.usesmileid.bridge.model.CaptureReadyEvent as NativeCaptureReadyEvent
-import com.usesmileid.bridge.model.CaptureType
-import com.usesmileid.bridge.model.YuvFrame as NativeYuvFrame
-import com.usesmileid.bridge.storage.DocumentSide
-import com.usesmileid.bridge.storage.FrameStorage
-import com.usesmileid.kamera.frame.KameraFrame
-import com.usesmileid.kamera.integration.KameraFrameHub
-import java.io.File
-import kotlinx.coroutines.CoroutineDispatcher
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.SupervisorJob
-import kotlinx.coroutines.cancel
-import kotlinx.coroutines.launch
-import kotlinx.coroutines.runBlocking
-import kotlinx.coroutines.withContext
-
-/**
- * Generic base for the four RN Expo analyzer modules. Concrete
- * subclasses extend this base with their session construction (face vs
- * document, mlkit vs huawei) and result-to-wire conversion. The Expo
- * Module class owns one instance of a subclass and forwards its async
- * functions through it.
- *
- * Type parameters:
- * - [PConfig]: the JS-side config map (always `Map<String, Any?>` after
- *   Expo bridge marshalling).
- * - [PResult]: the JS-side wire result (always `Map<String, Any?>`
- *   after Expo bridge marshalling).
- * - [Session]: the native SDK session class
- *   (`UseSmileIDFaceSession` / `UseSmileIDDocumentSession`).
- * - [ScanResult]: the native SDK scan-result type
- *   (`UseSmileIDFaceScanResult` / `UseSmileIDDocumentScanResult`).
- *
- * The base owns the coroutine scope, the on-disk session-frame storage
- * root, and the current `session` reference. Subclasses must not
- * redeclare these — they would diverge from the lifecycle this base
- * manages.
- */
-abstract class UseSmileIDAnalyzerExecutor<
-    PConfig : Any,
-    PResult : Any,
-    Session,
-    ScanResult,
-    > {
-
-    protected var session: Session? = null
-    private var storageRoot: File? = null
-
-    /**
-     * The latest session's storage, read by [handleDocumentBorderFraction] after `flush`. Written by
-     * `configure` on the executor's IO scope and read on the module's async-function thread.
-     */
-    @Volatile
-    private var storage: ResizingFrameStorage? = null
-
-    /**
-     * Scope used for all `analyze` / `flush` work. Bound to `Dispatchers.IO`
-     * + a `SupervisorJob` so a single failed frame analysis doesn't poison
-     * the rest of the session. Cancelled on module destroy.
-     */
-    protected val scope: CoroutineScope = CoroutineScope(Dispatchers.IO + SupervisorJob())
-
-    // Subclass hooks --------------------------------------------------------
-
-    /**
-     * Build a native session from the JS-side config map. The
-     * implementation receives the prepared on-disk `frameStorage` so each
-     * `configure` starts with a fresh session directory.
-     *
-     * Subclasses are responsible for any registry interaction (face
-     * modules resolve the analyzer through `FaceAnalyzerFactoryRegistry`;
-     * document modules instantiate their analyzer directly).
-     */
-    protected abstract fun createSession(config: PConfig, frameStorage: FrameStorage): Session
-
-    /**
-     * The document side this session's [ResizingFrameStorage] writes, selecting
-     * the `document_front.jpg` vs `document_back.jpg` filename. Face modules
-     * keep the default ([DocumentSide.Front]); document modules override to
-     * read the side from their wire config so two-sided captures don't
-     * overwrite the front image with the back.
-     */
-    protected open fun storageDocumentSide(config: PConfig): DocumentSide = DocumentSide.Front
-
-    /** Run one frame through the native session. */
-    protected abstract suspend fun scan(
-        session: Session,
-        frame: NativeYuvFrame,
-        rotation: Int,
-    ): ScanResult
-
-    /** Drain pending capture-ready events from the session. */
-    protected abstract fun drainEvents(session: Session): List<NativeCaptureReadyEvent>
-
-    /** Flush the session (suspend — writes pending JPEGs to disk). */
-    protected abstract suspend fun flushSession(session: Session)
-
-    /** Reset the session state machine without tearing down the analyzer. */
-    protected abstract fun resetSession(session: Session)
-
-    /** Close the session and release any underlying analyzer resources. */
-    protected abstract fun closeSession(session: Session)
-
-    /**
-     * Convert the native scan result + drained events into the JS-side
-     * wire result type (always a `Map<String, Any?>` for Expo). The map
-     * keys must match the JS-side schemas declared in `@usesmileid/ml`.
-     */
-    protected abstract fun buildResult(
-        scanResult: ScanResult,
-        events: List<NativeCaptureReadyEvent>,
-    ): PResult
-
-    // Lifecycle (driven by the Expo Module's OnCreate / OnDestroy) -------
-
-    /**
-     * Called from the Expo Module's `OnCreate` block. Subclasses can
-     * override to register backend-specific analyzer factories with the
-     * shared process-wide registry. Default no-op.
-     */
-    open fun onAttach(context: Context) {
-        val root = File(context.filesDir, "UseSmileID")
-        root.mkdirs()
-        File(root, ".nomedia").takeIf { !it.exists() }?.createNewFile()
-        storageRoot = root
-    }
-
-    /**
-     * Called from the Expo Module's `OnDestroy` block. Cancels the
-     * coroutine scope, closes any live session, then invokes
-     * [onDetached] for subclass-specific teardown.
-     */
-    fun onDetach() {
-        scope.cancel()
-        session?.let {
-            onSessionClosed()
-            closeSession(it)
-        }
-        session = null
-        onDetached()
-    }
-
-    /**
-     * Subclass hook invoked from [onDetach] after the session is closed
-     * and the scope is cancelled. Default no-op. Face modules use this
-     * to unregister their analyzer factory.
-     */
-    protected open fun onDetached() {}
-
-    // Session lifecycle notifications (driven by holder publishing) ------
-
-    /** Called after a new session is created; subclasses publish it to the holder. Default no-op. */
-    protected open fun onSessionCreated(session: Session) {}
-
-    /**
-     * Called BEFORE [closeSession] when the session is about to be torn down.
-     * Subclasses null the process-wide holder here so any concurrent scan
-     * queued on the session dispatcher sees null instead of a closing session.
-     * Default no-op.
-     */
-    protected open fun onSessionClosed() {}
-
-    /**
-     * The single-thread [CoroutineDispatcher] that serialises all session
-     * operations for this module's holder, preventing concurrent state-machine
-     * mutations between the frame-processor thread and the Expo module thread.
-     * Returning `null` (default) runs inline on the calling thread.
-     */
-    protected open fun holderSessionDispatcher(): CoroutineDispatcher? = null
-
-    // Shared implementation behind the Expo Module's async functions -----
-
-
-    /**
-     * Implementation behind `configure`. Closes any prior session,
-     * allocates a fresh on-disk session directory, and delegates session
-     * construction to the subclass.
-     */
-    fun handleConfigure(config: PConfig) {
-        session?.let {
-            // Null the holder before closing so a queued scan sees null,
-            // not a mid-close session.
-            onSessionClosed()
-            closeSession(it)
-        }
-        // Each `configure` starts a fresh session directory so retries
-        // after `close` / re-`configure` don't collide with the previous
-        // session's JPGs. Old directories are left in place; partner
-        // clean-up policies can prune them.
-        val sessionDir = freshSessionDirectory()
-        val storage = buildResizingFrameStorage(sessionDir, storageDocumentSide(config), config as? Map<*, *>)
-        this.storage = storage
-        val newSession = createSession(config, storage)
-        session = newSession
-        onSessionCreated(newSession)
-    }
-
-    /**
-     * Implementation behind `documentBorderFraction`: the hidden border the document at [url], a
-     * `file://` URL or a path, was saved with, as a fraction of its short side; 0 for a file the
-     * latest session's storage did not write with one.
-     */
-    fun handleDocumentBorderFraction(url: String): Double {
-        val file = try {
-            if (url.startsWith("file:")) File(java.net.URI(url)) else File(url)
-        } catch (e: java.net.URISyntaxException) {
-            return 0.0
-        } catch (e: IllegalArgumentException) {
-            // Not a hierarchical file: URL.
-            return 0.0
-        }
-        return storage?.borderFractionOf(file)?.toDouble() ?: 0.0
-    }
-
-    /**
-     * Implementation behind `flush`. Same dispatcher hopping discipline;
-     * a missing session is treated as a successful
-     * no-op (matches the prior per-module behaviour).
-     */
-    fun handleFlush(callback: (Result<Unit>) -> Unit) {
-        scope.launch {
-            val result = runCatching { session?.let { flushSession(it) } ?: Unit }
-            withContext(Dispatchers.Main) { callback(result) }
-        }
-    }
-
-    /**
-     * Implementation behind `reset`. Serialized through [holderSessionDispatcher]
-     * so it cannot interleave with a concurrent frame-processor scan.
-     */
-    fun handleReset() {
-        val dispatcher = holderSessionDispatcher()
-        if (dispatcher != null) {
-            runBlocking {
-                withContext(dispatcher) {
-                    session?.let { resetSession(it) }
-                }
-            }
-        } else {
-            session?.let { resetSession(it) }
-        }
-    }
-
-    /**
-     * Implementation behind `close`. Nulls the holder BEFORE closing the
-     * session (see [onSessionClosed]), serialized through [holderSessionDispatcher].
-     */
-    fun handleClose() {
-        val dispatcher = holderSessionDispatcher()
-        if (dispatcher != null) {
-            runBlocking {
-                withContext(dispatcher) {
-                    session?.let {
-                        onSessionClosed()
-                        closeSession(it)
-                    }
-                    session = null
-                }
-            }
-        } else {
-            session?.let {
-                onSessionClosed()
-                closeSession(it)
-            }
-            session = null
-        }
-    }
-
-    // Helpers ---------------------------------------------------------------
-
-    /**
-     * Build a [ResizingFrameStorage] from the wire config map, applying
-     * token-resolved dimensions and JPEG quality when present. All values
-     * fall back to SDK defaults when absent or not a [Number].
-     */
-    private fun buildResizingFrameStorage(
-        sessionDir: File,
-        documentSide: DocumentSide,
-        config: Map<*, *>?,
-    ): ResizingFrameStorage = ResizingFrameStorage(
-        sessionDirectory = sessionDir,
-        captureType = CaptureType.SELFIE,
-        documentSide = documentSide,
-        selfieTargetWidth = (config?.get("selfieImageWidth") as? Number)?.toInt() ?: 480,
-        selfieTargetHeight = (config?.get("selfieImageHeight") as? Number)?.toInt() ?: 640,
-        livenessTargetWidth = (config?.get("livenessImageWidth") as? Number)?.toInt() ?: 480,
-        livenessTargetHeight = (config?.get("livenessImageHeight") as? Number)?.toInt() ?: 640,
-        selfieQuality = (config?.get("selfieJpegQuality") as? Number)?.toInt() ?: 95,
-        livenessQuality = (config?.get("livenessJpegQuality") as? Number)?.toInt() ?: 80,
-        documentQuality = (config?.get("documentJpegQuality") as? Number)?.toInt() ?: 85,
-    )
-
-    private fun freshSessionDirectory(): File {
-        val root = checkNotNull(storageRoot) {
-            "Executor not attached — call onAttach(context) from the Expo Module's OnCreate block first"
-        }
-        val dir = File(root, System.currentTimeMillis().toString())
-        dir.mkdirs()
-        return dir
-    }
-}
-
-/** Copies the YUV planes so the frame can close at once; rotation stays metadata for the detector. */
-internal fun KameraFrame.toNativeYuvFrame(): NativeYuvFrame {
-    val yPlane = planes[0]
-    val uPlane = planes[1]
-    val vPlane = planes[2]
-    fun copyBytes(buffer: java.nio.ByteBuffer): ByteArray {
-        val source = buffer.duplicate()
-        source.rewind()
-        return ByteArray(source.remaining()).also { source.get(it) }
-    }
-    return NativeYuvFrame(
-        planeY = copyBytes(yPlane.buffer),
-        planeU = copyBytes(uPlane.buffer),
-        planeV = copyBytes(vPlane.buffer),
-        yRowStride = yPlane.rowStride,
-        uRowStride = uPlane.rowStride,
-        vRowStride = vPlane.rowStride,
-        uPixelStride = uPlane.pixelStride,
-        vPixelStride = vPlane.pixelStride,
-        width = width,
-        height = height,
-        rotation = rotationDegrees,
-    )
-}