@smileid/usesmileid_mlkit_face 12.0.0-beta01

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 12.0.0-beta01
+
+First public beta release. Android ML Kit face detection for the Smile ID React Native (Expo) SDK v12.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Smile ID
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# `@smileid/usesmileid_mlkit_face`
+
+UseSmileID v12 — Google ML Kit face provider for React Native (Expo Modules).
+**Android-only.** Thin shim around the existing native AAR
+`com.usesmileid:mlkit-face`.
+
+## Architecture
+
+The native side runs the entire face-scan pipeline (analyzer + validator
+
+- transitioner + state machine). This package contributes:
+
+* A Kotlin Expo Module that constructs `UseSmileIDFaceSession(FaceDetectorAnalyzer())`
+  from the existing native session.
+* A TypeScript wrapper that bridges the four contract methods
+  (`configure / analyze / reset / close`) and validates the wire payloads
+  at the channel boundary via Zod.
+
+No ML logic is reimplemented in this package — it's a pure passthrough.
+See `improvements.md` and `react-native-expo/docs/Architecture.md` for
+the design rationale.
+
+## Installation
+
+```sh
+pnpm add @smileid/usesmileid_mlkit_face
+```
+
+Expo's autolinking picks up `expo-module.config.json` at app build time;
+no manual native registration required.
+
+## Usage
+
+```ts
+import { useSmileIDMlkitFace } from "@smileid/usesmileid_mlkit_face";
+
+await useSmileIDMlkitFace.configure({
+  selfieCaptureTimeoutMs: 60_000,
+});
+
+const result = await useSmileIDMlkitFace.analyze(bytes, rotation);
+// result.state.type === 'found' | 'satisfied' | 'unsatisfied' | …
+// result.output.faces[0].score === 0.9
+
+await useSmileIDMlkitFace.close();
+```
+
+## Cross-platform peers
+
+| Platform         | Provider package                  | Native dep                   |
+| ---------------- | --------------------------------- | ---------------------------- |
+| Android          | `@smileid/usesmileid_mlkit_face`  | `com.usesmileid:mlkit-face`  |
+| Android (no GMS) | `@smileid/usesmileid_huawei_face` | `com.usesmileid:huawei-face` |
+| iOS              | `@smileid/usesmileid_vision_face` | `UseSmileIDVisionFace` (SPM) |
+
+## Testing
+
+```sh
+pnpm --filter @smileid/usesmileid_mlkit_face test
+```
+
+JS-side tests mock `requireNativeModule` and verify the wrapper's
+contract: method shape, boundary validation, error propagation,
+idempotency. Native-side tests live under
+`android/src/test/kotlin/...` (TODO when the Kotlin module is wired
+to the real AAR).

package/android/build.gradle

@@ -0,0 +1,58 @@
+// Expo Module — ML Kit face analyzer (GMS-backed). Uses the
+// canonical Expo Module Groovy template so the script-compilation
+// classpath inherits AGP from the host app's pluginManagement, the
+// same way every other Expo module on the workspace's autolinking
+// graph does (see node_modules/expo-camera/android/build.gradle for
+// the upstream reference).
+//
+// `id 'expo-module-gradle-plugin'` provides:
+//   • compileSdk / minSdk / Java + Kotlin target levels (from the host)
+//   • Standard Expo Module dependency wiring + publishing config
+// So we only declare what's specific to THIS module: namespace +
+// the native AAR that ships the actual ML pipeline.
+
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'com.usesmileid.mlkit.face'
+version = '12.0.0'
+
+android {
+  namespace 'com.usesmileid.mlkit.face'
+
+  // `expo-module-gradle-plugin` requires versionName + versionCode on
+  // the library's defaultConfig — concrete failure without these:
+  // "android.defaultConfig.versionName is not defined" at autolinking
+  // time. Matches the canonical pattern in node_modules/expo-camera/
+  // android/build.gradle and the rest of the @expo/* modules.
+  defaultConfig {
+    versionCode 1
+    versionName '12.0.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.
+    consumerProguardFiles 'consumer-rules.pro'
+  }
+}
+
+dependencies {
+  // 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.0.0-beta01'
+
+  // VisionCamera frame-processor plugin classes. The host app provides
+  // this dependency via RN autolinking — react-native-vision-camera >= 4.7.3
+  // must be present in the partner app's package.json.
+  implementation project(':react-native-vision-camera')
+
+  // CameraX types (`ImageProxy`, `ExperimentalGetImage`) referenced by the
+  // frame processor plugin. VisionCamera declares camera-core as
+  // `implementation`, so it is NOT on this module's compile classpath
+  // transitively — compileOnly pins the compile-time API while the host
+  // app's VisionCamera provides the runtime classes (its camera-core is
+  // 1.5.0-alpha03; the `ImageProxy` surface used here is stable since 1.0).
+  compileOnly 'androidx.camera:camera-core:1.5.0-alpha03'
+}

package/android/consumer-rules.pro

@@ -0,0 +1,26 @@
+# ═════════════════════════════════════════════════════════════════════════════
+# R8 consumer rules — usesmileid_mlkit_face (React Native / Expo module)
+#
+# Bundled into partner apps that depend on this Expo module. Tells R8 what
+# NOT to rename / strip during the partner's release build.
+# ═════════════════════════════════════════════════════════════════════════════
+
+# ─── Expo Module entry-point + bridge surface ───────────────────────────────
+# Expo's module registry instantiates `UseSmileIDMlkitFaceModule` by FQN at
+# app launch — renaming breaks autolinking. The same package hosts the
+# `ModuleDefinition` function names referenced by JS via string keys, plus
+# the shared `UseSmileIDAnalyzerExecutor` subclass; both must survive R8.
+-keep class com.usesmileid.mlkit.face.** { *; }
+
+# ─── Enums (kotlinx-serialization / JS bridge valueOf reflection) ───────────
+-keepclassmembers enum com.usesmileid.mlkit.face.** {
+    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/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

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

@@ -0,0 +1,79 @@
+package com.usesmileid.mlkit.face
+
+import androidx.camera.core.ExperimentalGetImage
+import com.mrousavy.camera.core.FrameInvalidError
+import com.mrousavy.camera.frameprocessors.Frame
+import com.mrousavy.camera.frameprocessors.FrameProcessorPlugin
+import com.usesmileid.bridge.model.YuvFrame as NativeYuvFrame
+import kotlin.coroutines.cancellation.CancellationException
+import kotlinx.coroutines.runBlocking
+import kotlinx.coroutines.withContext
+
+/**
+ * VisionCamera Frame Processor Plugin for the ML Kit face backend.
+ * Registered under [UseSmileIDMlkitFaceModule.FRAME_PROCESSOR_PLUGIN_NAME].
+ * Reads raw [ImageProxy] planes directly (no JPEG encoding) and runs the
+ * native session pipeline. Blocks the FP thread via [runBlocking] —
+ * VisionCamera drops frames that arrive while a scan is in flight.
+ */
+@OptIn(ExperimentalGetImage::class)
+internal class UseSmileIDMlkitFaceFrameProcessorPlugin : FrameProcessorPlugin() {
+
+    override fun callback(frame: Frame, arguments: Map<String, Any>?): Any? {
+        val imageProxy = try {
+            frame.imageProxy
+        } catch (e: FrameInvalidError) {
+            return mapOf("error" to "frame_conversion_failed")
+        }
+
+        val image = imageProxy.image
+            ?: return mapOf("error" to "frame_conversion_failed")
+
+        // Pixel-orientation for ML Kit — always from ImageProxy metadata, never from JS.
+        val sensorRotation = imageProxy.imageInfo.rotationDegrees
+
+        // Device-tilt context (0 = upright portrait) for head-pose math.
+        // Must not fall back to sensorRotation — sensor angle != device tilt.
+        val jsRotation = (arguments?.get("rotation") as? Number)?.toInt() ?: 0
+
+        val planes = image.planes
+        if (planes.size < 3) return mapOf("error" to "frame_conversion_failed")
+
+        fun extractPlane(index: Int): ByteArray {
+            val buffer = planes[index].buffer
+            buffer.rewind()
+            return ByteArray(buffer.remaining()).also { buffer.get(it) }
+        }
+
+        val yuvFrame = NativeYuvFrame(
+            planeY = extractPlane(0),
+            planeU = extractPlane(1),
+            planeV = extractPlane(2),
+            yRowStride = planes[0].rowStride,
+            uRowStride = planes[1].rowStride,
+            vRowStride = planes[2].rowStride,
+            uPixelStride = planes[1].pixelStride,
+            vPixelStride = planes[2].pixelStride,
+            width = image.width,
+            height = image.height,
+            rotation = sensorRotation,
+        )
+
+        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)))
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,309 @@
+package com.usesmileid.mlkit.face
+
+import com.usesmileid.bridge.dsl.builder.FaceDetectorMode
+import com.usesmileid.bridge.mlkit.face.FaceDetectorAnalyzer
+import com.usesmileid.bridge.model.BoundingBox as NativeBoundingBox
+import com.usesmileid.bridge.model.CaptureReadyEvent as NativeCaptureReadyEvent
+import com.usesmileid.bridge.model.FaceDetectorOutput as NativeFaceOutput
+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.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.mrousavy.camera.frameprocessors.FrameProcessorPluginRegistry
+import com.usesmileid.rn.analyzer.mlkitface.UseSmileIDAnalyzerExecutor
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * Expo Module bridging the existing native session
+ * `UseSmileIDFaceSession(FaceDetectorAnalyzer())` (shipped in the
+ * `com.smileidentity:mlkit-face` AAR) to the JS side.
+ *
+ * No ML logic lives here — the native session owns the entire
+ * pipeline. The configure / flush / reset / close plumbing
+ * lives in [UseSmileIDAnalyzerExecutor]; this module supplies the
+ * subclass hooks (session construction, wire conversion) and forwards
+ * the async functions through it.
+ *
+ * Per-frame work is handled by [UseSmileIDMlkitFaceFrameProcessorPlugin],
+ * which is registered with VisionCamera's frame-processor runtime in
+ * [OnCreate]. Partners call `VisionCameraProxy.initFrameProcessorPlugin`
+ * from their JS worklet instead of the old `AsyncFunction("analyze")`.
+ *
+ * Lifecycle: Expo instantiates exactly one `Module` per app process;
+ * the executor is owned for the module's lifetime.
+ */
+class UseSmileIDMlkitFaceModule : Module() {
+
+    private val executor = object : UseSmileIDAnalyzerExecutor<
+        Map<String, Any?>,
+        Map<String, Any?>,
+        UseSmileIDFaceSession,
+        UseSmileIDFaceScanResult,
+        >() {
+
+        override fun createSession(
+            config: Map<String, Any?>,
+            frameStorage: FrameStorage,
+        ): UseSmileIDFaceSession {
+            val key = (config["analyzerFactoryKey"] as? String) ?: KEY
+            val analyzer = FaceAnalyzerFactoryRegistry.newAnalyzer(key)
+            return UseSmileIDFaceSession(
+                analyzer = analyzer,
+                config = config.toFaceScanConfig(),
+                frameStorage = frameStorage,
+            )
+        }
+
+        override suspend fun scan(
+            session: UseSmileIDFaceSession,
+            frame: NativeYuvFrame,
+            rotation: Int,
+        ): UseSmileIDFaceScanResult = session.scan(frame, rotation)
+
+        override fun drainEvents(session: UseSmileIDFaceSession): List<NativeCaptureReadyEvent> =
+            session.drainCaptureReadyEvents()
+
+        override suspend fun flushSession(session: UseSmileIDFaceSession) {
+            session.flush()
+        }
+
+        override fun resetSession(session: UseSmileIDFaceSession) {
+            session.reset()
+        }
+
+        override fun closeSession(session: UseSmileIDFaceSession) {
+            session.close()
+        }
+
+        override fun buildResult(
+            scanResult: UseSmileIDFaceScanResult,
+            events: List<NativeCaptureReadyEvent>,
+        ): Map<String, Any?> = buildWireResult(scanResult, events)
+
+        override fun onDetached() {
+            FaceAnalyzerFactoryRegistry.unregister(KEY)
+        }
+
+        override fun onSessionCreated(session: UseSmileIDFaceSession) {
+            UseSmileIDMlkitFaceSessionHolder.session = session
+        }
+
+        override fun onSessionClosed() {
+            UseSmileIDMlkitFaceSessionHolder.session = null
+        }
+
+        override fun holderSessionDispatcher() = UseSmileIDMlkitFaceSessionHolder.sessionDispatcher
+    }
+
+    override fun definition() = ModuleDefinition {
+        // Must match the JS-side `requireNativeModule('UseSmileIDMlkitFace')`
+        // call in `src/index.ts`. Drift here = "Cannot find native
+        // module" runtime error in partner apps.
+        Name("UseSmileIDMlkitFace")
+
+        OnCreate {
+            // Register this backend's factory with the shared process-wide
+            // registry so partners who ship multiple backends (e.g.
+            // mlkit-face + huawei-face) can select among them at runtime via
+            // the `analyzerFactoryKey` DSL field.
+            FaceAnalyzerFactoryRegistry.register(KEY) { FaceDetectorAnalyzer() }
+            val ctx = appContext.reactContext
+                ?: throw IllegalStateException("Module not attached to a React context")
+            executor.onAttach(ctx)
+
+            // Guard against duplicate registration on dev-client hot reloads
+            // where OnCreate can fire more than once in the same process.
+            if (!pluginRegistered) {
+                pluginRegistered = true
+                FrameProcessorPluginRegistry.addFrameProcessorPlugin(
+                    FRAME_PROCESSOR_PLUGIN_NAME,
+                ) { _, _ -> UseSmileIDMlkitFaceFrameProcessorPlugin() }
+            }
+        }
+
+        AsyncFunction("configure") { config: Map<String, Any?> ->
+            executor.handleConfigure(config)
+        }
+
+        AsyncFunction("reset") {
+            executor.handleReset()
+        }
+
+        AsyncFunction("flush") { promise: Promise ->
+            executor.handleFlush { result ->
+                result.fold(
+                    onSuccess = { promise.resolve(null) },
+                    onFailure = { promise.reject("FLUSH_FAILED", it.message, it) },
+                )
+            }
+        }
+
+        AsyncFunction("close") {
+            executor.handleClose()
+        }
+
+        OnDestroy {
+            executor.onDetach()
+        }
+    }
+
+    companion object {
+        /** Wire-format key partners pass via `FaceConfig.analyzerFactoryKey`. */
+        const val KEY: String = "mlkit-face"
+
+        /**
+         * Must match the JS worklet's `VisionCameraProxy.initFrameProcessorPlugin(...)`
+         * call exactly — drift is a runtime "plugin not found" error.
+         */
+        const val FRAME_PROCESSOR_PLUGIN_NAME: String = "UseSmileIDMlkitFaceFrameProcessor"
+
+        /**
+         * [FrameProcessorPluginRegistry.addFrameProcessorPlugin] asserts uniqueness
+         * and crashes on duplicate registration; this guard prevents that on dev-client
+         * hot reloads where [OnCreate] fires more than once per process.
+         */
+        @Volatile
+        private var pluginRegistered: Boolean = false
+
+        /** Wire-result builder shared with [UseSmileIDMlkitFaceFrameProcessorPlugin]. */
+        internal fun buildWireResult(
+            scanResult: UseSmileIDFaceScanResult,
+            events: List<NativeCaptureReadyEvent>,
+        ): Map<String, Any?> = mapOf(
+            "output" to (
+                (scanResult.output as? NativeFaceOutput)?.toWireMap()
+                    ?: mapOf("faces" to emptyList<Any>(), "brightness" to 0.0)
+            ),
+            "state" to scanResult.state.toWireMap(),
+            "capturedEvents" to events.map { it.toWireMap() },
+        )
+    }
+}
+
+/**
+ * Adapt the partner-supplied JS object (a `Map<String, Any?>` after
+ * Expo Modules' bridge marshalling) into the strongly-typed
+ * `FaceScanConfig` the native session expects. Every field is
+ * nullable on the wire; the fallbacks below are the production
+ * defaults.
+ */
+private fun Map<String, Any?>.toFaceScanConfig(): FaceScanConfig {
+    // Resolve the preset token to this backend's engine-calibrated base, then
+    // 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,
+        minFillThreshold = (this["minFillThreshold"] as? Number)?.toFloat() ?: base.minFillThreshold,
+        maxFillThreshold = (this["maxFillThreshold"] as? Number)?.toFloat() ?: base.maxFillThreshold,
+        faceDetectorMinScore = (this["faceDetectorMinScore"] as? Number)?.toFloat() ?: base.faceDetectorMinScore,
+        centerToleranceX = (this["centerToleranceX"] as? Number)?.toFloat() ?: base.centerToleranceX,
+        centerToleranceY = (this["centerToleranceY"] as? Number)?.toFloat() ?: base.centerToleranceY,
+        motionBlurMinIou = (this["motionBlurMinIou"] as? Number)?.toFloat() ?: base.motionBlurMinIou,
+        motionBlurMinDuration = (this["motionBlurMinDuration"] as? Number)?.toLong() ?: base.motionBlurMinDuration,
+        minTopPadding = (this["minTopPadding"] as? Number)?.toFloat() ?: base.minTopPadding,
+        minFaceBoundsThreshold = (this["minFaceBoundsThreshold"] as? Number)?.toFloat() ?: base.minFaceBoundsThreshold,
+        maxFaceBoundsThreshold = (this["maxFaceBoundsThreshold"] as? Number)?.toFloat() ?: base.maxFaceBoundsThreshold,
+        minSmileProbability = (this["minSmileProbability"] as? Number)?.toFloat() ?: base.minSmileProbability,
+        enableEnhancedLiveness = (this["enableEnhancedLiveness"] as? Boolean) ?: false,
+    )
+}
+
+/**
+ * Convert the native session's typed result into the JS-side wire
+ * shape declared in `@usesmileid/ml`. Keys must match
+ * `faceDetectorOutputSchema` field-for-field — the JS-side
+ * `parseFaceScanResult` parse fails loud on any drift.
+ */
+private fun NativeFaceOutput.toWireMap(): Map<String, Any?> {
+    val primaryFace = faces.maxByOrNull { it.boundingBox.area }
+    return buildMap {
+        put("faces", faces.map { it.boundingBox.toWireMap() })
+        // Omit absent optional fields; never put null (Zod .optional() rejects explicit null).
+        primaryFace?.headPose?.let { put("headPose", it.toWireMap()) }
+        primaryFace?.smilingProbability?.let { put("smilingProbability", it.toDouble()) }
+        put("brightness", (primaryFace?.brightness ?: 0f).toDouble())
+    }
+}
+
+private fun NativeBoundingBox.toWireMap(): Map<String, Any?> = mapOf(
+    "left" to left.toDouble(),
+    "top" to top.toDouble(),
+    "width" to width.toDouble(),
+    "height" to height.toDouble(),
+    "score" to score.toDouble(),
+)
+
+private fun HeadPoseResult.toWireMap(): Map<String, Any?> = mapOf(
+    "yaw" to yaw.toDouble(),
+    "pitch" to pitch.toDouble(),
+    "roll" to roll.toDouble(),
+)
+
+/**
+ * Map the native state-machine type into the wire-string the JS-side
+ * `scanStateTypeSchema` enum accepts. Keep in lock-step with the
+ * `ScanStateType` enum order so cross-platform analytics/dashboards
+ * see consistent values.
+ */
+private fun UseSmileIDScanState.toWireMap(): Map<String, Any?> = buildMap {
+    put(
+        "type",
+        when (type) {
+            UseSmileIDScanStateType.INITIAL -> "initial"
+            UseSmileIDScanStateType.FOUND -> "found"
+            UseSmileIDScanStateType.SATISFIED -> "satisfied"
+            UseSmileIDScanStateType.UNSATISFIED -> "unsatisfied"
+            UseSmileIDScanStateType.FINISHED -> "finished"
+            UseSmileIDScanStateType.TIMEOUT -> "timeout"
+            UseSmileIDScanStateType.HEAD_TURN -> "headTurn"
+        },
+    )
+    // Absent optional fields are OMITTED, never set to null:
+    // Zod .optional() rejects explicit null; the bridge maps Kotlin null → JS null.
+    feedbackName?.let { put("feedback", it) }
+    unsatisfiedReason?.let { put("reason", it) }
+    // 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),
+    // matching the optional-field omission convention above.
+    if (poseMatched) put("poseMatched", true)
+}
+
+/**
+ * Wire-shape for [CaptureReadyEvent] — keys match the JS-side
+ * `captureReadyEventSchema` field-for-field. The native event carries a
+ * `java.io.File`; we serialise as a `file://` URL so the JS partner can
+ * hand the string straight to `Image` / upload pipelines without further
+ * processing.
+ */
+private fun NativeCaptureReadyEvent.toWireMap(): Map<String, Any?> = when (this) {
+    is NativeCaptureReadyEvent.SelfieFrame -> mapOf(
+        "kind" to "selfie",
+        "captureIndex" to captureIndex,
+        "url" to file.toURI().toString(),
+    )
+    is NativeCaptureReadyEvent.LivenessFrame -> mapOf(
+        "kind" to "liveness",
+        "captureIndex" to captureIndex,
+        "url" to file.toURI().toString(),
+    )
+    is NativeCaptureReadyEvent.DocumentFrame -> mapOf(
+        "kind" to "document",
+        "captureIndex" to captureIndex,
+        "url" to file.toURI().toString(),
+    )
+}

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

@@ -0,0 +1,27 @@
+package com.usesmileid.mlkit.face
+
+import com.usesmileid.bridge.session.UseSmileIDFaceSession
+import java.util.concurrent.Executors
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.asCoroutineDispatcher
+
+/**
+ * Process-wide holder for the active [UseSmileIDFaceSession] (ML Kit face backend).
+ *
+ * The session's state machine is not thread-safe; all operations —
+ * scan+drain as one atomic unit, flush, reset, close — are serialized
+ * through [sessionDispatcher] (a single-thread executor). The FP plugin
+ * blocks its thread via [runBlocking]; VisionCamera drops frames that
+ * arrive while a scan is in flight rather than queuing them.
+ */
+internal object UseSmileIDMlkitFaceSessionHolder {
+
+    /** Single-thread dispatcher; serializes all session operations without explicit locking. */
+    val sessionDispatcher: CoroutineDispatcher =
+        Executors.newSingleThreadExecutor { runnable ->
+            Thread(runnable, "usesmileid-mlkit-face-session")
+        }.asCoroutineDispatcher()
+
+    @Volatile
+    var session: UseSmileIDFaceSession? = null
+}

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

@@ -0,0 +1,134 @@
+// 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.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.ConcurrentLinkedDeque
+import java.util.concurrent.atomic.AtomicReference
+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 not resized — they are written at the analyzer's native
+ * frame resolution using the specified [documentQuality]. 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 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 {
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    private val pending = ConcurrentLinkedDeque<Job>()
+    private val firstError = AtomicReference<Throwable?>(null)
+
+    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"
+            }
+        },
+    )
+
+    override fun persist(frame: YuvFrame, file: File) {
+        val job = scope.launch {
+            try {
+                encodeAndWrite(frame, file)
+            } catch (throwable: Throwable) {
+                firstError.compareAndSet(null, throwable)
+                throw throwable
+            }
+        }
+        // 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() {
+        sessionDirectory.listFiles()?.forEach { it.delete() }
+    }
+
+    private suspend fun encodeAndWrite(frame: YuvFrame, file: File) {
+        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: encode at native resolution, quality only.
+                    val bitmap = frame.toArgbBitmap(jpegQuality = documentQuality)
+                        ?: throw IOException("toArgbBitmap returned null for ${file.name}")
+                    try {
+                        val success = file.outputStream().use {
+                            bitmap.compress(android.graphics.Bitmap.CompressFormat.JPEG, documentQuality, it)
+                        }
+                        if (!success) throw IOException("Bitmap.compress(JPEG) failed for ${file.absolutePath}")
+                    } finally {
+                        bitmap.recycle()
+                    }
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,281 @@
+// 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.YuvFrame as NativeYuvFrame
+import com.usesmileid.bridge.storage.DocumentSide
+import com.usesmileid.bridge.storage.FrameStorage
+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
+
+    /**
+     * 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 [JpegFrameStorage] 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<*, *>)
+        val newSession = createSession(config, storage)
+        session = newSession
+        onSessionCreated(newSession)
+    }
+
+    /**
+     * 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,
+        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
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { FaceConfig, FaceScanResult } from "@smileid/usesmileid_bridge";
+/**
+ * Google ML Kit face analyzer (Android-only).
+ *
+ * Thin shim around the existing native session
+ * `com.usesmileid.bridge.session.UseSmileIDFaceSession(FaceDetectorAnalyzer())`
+ * shipped in the `com.smileidentity:mlkit-face` AAR. The native side
+ * runs the entire pipeline (analyzer + validator + transitioner +
+ * state machine); this TS layer only routes calls and validates wire
+ * payloads at the channel boundary.
+ *
+ * The canonical wiring lives in [useSmileIDAnalyzerExecutor] in
+ * `usesmileid_platform_interface`. This file only supplies the
+ * provider-specific identity so all six provider modules share one set
+ * of correctness properties by construction.
+ *
+ * Lifecycle: `configure()` → per-frame analysis via the native frame
+ * processor plugin → `reset()`? → `close()`. Calling
+ * `close()` twice is idempotent. See `usesmileid_platform_interface`
+ * `FaceAnalyzer` for the canonical contract.
+ */
+/**
+ * Must match the Kotlin Expo Module's `Name("UseSmileIDMlkitFace")` and its
+ * VisionCamera frame-processor-plugin registration — drift is a runtime
+ * "module/plugin not found" error, not a compile error.
+ */
+export declare const UseSmileIDMlkitFaceIdentifiers: {
+    readonly nativeModuleName: "UseSmileIDMlkitFace";
+    readonly frameProcessorPluginName: "UseSmileIDMlkitFaceFrameProcessor";
+};
+export declare const useSmileIDMlkitFace: import("@smileid/usesmileid_platform_interface").FaceAnalyzer;
+export type { FaceConfig, FaceScanResult };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG7E;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;CAGjC,CAAC;AAEX,eAAO,MAAM,mBAAmB,+DAM9B,CAAC;AAKH,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,38 @@
+import { AnalyzerFactoryKey } from "@smileid/usesmileid_bridge";
+import { useSmileIDAnalyzerExecutor } from "@smileid/usesmileid_platform_interface";
+/**
+ * Google ML Kit face analyzer (Android-only).
+ *
+ * Thin shim around the existing native session
+ * `com.usesmileid.bridge.session.UseSmileIDFaceSession(FaceDetectorAnalyzer())`
+ * shipped in the `com.smileidentity:mlkit-face` AAR. The native side
+ * runs the entire pipeline (analyzer + validator + transitioner +
+ * state machine); this TS layer only routes calls and validates wire
+ * payloads at the channel boundary.
+ *
+ * The canonical wiring lives in [useSmileIDAnalyzerExecutor] in
+ * `usesmileid_platform_interface`. This file only supplies the
+ * provider-specific identity so all six provider modules share one set
+ * of correctness properties by construction.
+ *
+ * Lifecycle: `configure()` → per-frame analysis via the native frame
+ * processor plugin → `reset()`? → `close()`. Calling
+ * `close()` twice is idempotent. See `usesmileid_platform_interface`
+ * `FaceAnalyzer` for the canonical contract.
+ */
+/**
+ * Must match the Kotlin Expo Module's `Name("UseSmileIDMlkitFace")` and its
+ * VisionCamera frame-processor-plugin registration — drift is a runtime
+ * "module/plugin not found" error, not a compile error.
+ */
+export const UseSmileIDMlkitFaceIdentifiers = {
+    nativeModuleName: "UseSmileIDMlkitFace",
+    frameProcessorPluginName: "UseSmileIDMlkitFaceFrameProcessor",
+};
+export const useSmileIDMlkitFace = useSmileIDAnalyzerExecutor({
+    nativeModuleName: UseSmileIDMlkitFaceIdentifiers.nativeModuleName,
+    frameProcessorPluginName: UseSmileIDMlkitFaceIdentifiers.frameProcessorPluginName,
+    kind: "face",
+    key: AnalyzerFactoryKey.MLKitFace,
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,gBAAgB,EAAE,qBAAqB;IACvC,wBAAwB,EAAE,mCAAmC;CACrD,CAAC;AAEX,MAAM,CAAC,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;IAC5D,gBAAgB,EAAE,8BAA8B,CAAC,gBAAgB;IACjE,wBAAwB,EACtB,8BAA8B,CAAC,wBAAwB;IACzD,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,kBAAkB,CAAC,SAAS;CAClC,CAAC,CAAC"}

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": ["com.usesmileid.mlkit.face.UseSmileIDMlkitFaceModule"]
+  }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@smileid/usesmileid_mlkit_face",
+  "version": "12.0.0-beta01",
+  "description": "UseSmileID v12 — Google ML Kit face provider (Android-only). Thin Expo Module shim around the existing native AAR `com.smileidentity:mlkit-face`.",
+  "homepage": "https://usesmileid.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smileidentity/react-native-expo.git",
+    "directory": "usesmileid_mlkit_face"
+  },
+  "bugs": {
+    "url": "https://github.com/smileidentity/react-native-expo/issues"
+  },
+  "license": "MIT",
+  "author": "Smile Identity <hello@usesmileid.com>",
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-module",
+    "biometric",
+    "kyc",
+    "identity-verification",
+    "face-detection",
+    "document-capture",
+    "smile-id"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "android",
+    "expo-module.config.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@smileid/usesmileid_bridge": "12.0.0-beta01",
+    "@smileid/usesmileid_platform_interface": "12.0.0-beta01"
+  },
+  "peerDependencies": {
+    "expo": ">=56.0.0",
+    "expo-modules-core": ">=56.0.0",
+    "react-native": ">=0.83.0"
+  },
+  "devDependencies": {
+    "expo-modules-core": "^56.0.15",
+    "react-native": "^0.85.3",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo coverage"
+  }
+}

package/src/__tests__/use_smile_id_mlkit_face.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi, beforeEach, type Mock } from "vitest";
+
+// Hoist the mock so `requireNativeModule` resolves to a stub before
+// the index module's top-level `requireNativeModule(...)` call runs.
+// Without `vi.hoisted(...)`, Vitest evaluates the import statement
+// before the mock is in scope and the wrapper grabs the real native
+// module — which doesn't exist in a Node test environment.
+const native = vi.hoisted(() => ({
+  configure: vi.fn(),
+  reset: vi.fn(),
+  close: vi.fn(),
+}));
+
+vi.mock("expo-modules-core", () => ({
+  requireNativeModule: vi.fn(() => native),
+}));
+
+// Imports happen *after* the mock is registered.
+import { requireNativeModule } from "expo-modules-core";
+import { useSmileIDMlkitFace, UseSmileIDMlkitFaceIdentifiers } from "../index";
+
+describe("useSmileIDMlkitFace — TS wrapper", () => {
+  beforeEach(() => {
+    Object.values(native).forEach((m) => (m as Mock).mockReset());
+  });
+
+  it("looks up the native module under the contract-stable name", () => {
+    // The Kotlin Expo Module declares `Name("UseSmileIDMlkitFace")`.
+    // If the JS wrapper passes a different string, partner apps fail
+    // at runtime with "Cannot find native module 'X'".
+    expect(requireNativeModule).toHaveBeenCalledWith("UseSmileIDMlkitFace");
+  });
+
+  it("exposes the lifecycle surface — no per-frame analyze method", () => {
+    expect(typeof useSmileIDMlkitFace.configure).toBe("function");
+    expect(typeof useSmileIDMlkitFace.reset).toBe("function");
+    expect(typeof useSmileIDMlkitFace.close).toBe("function");
+    // Per-frame analysis lives in the native VisionCamera frame
+    // processor plugin — raw pixels never cross the JS bridge.
+    expect("analyze" in useSmileIDMlkitFace).toBe(false);
+  });
+
+  it("exposes the kind discriminator and frame processor plugin name", () => {
+    expect(useSmileIDMlkitFace.kind).toBe("face");
+    expect(useSmileIDMlkitFace.frameProcessorPluginName).toBe(
+      UseSmileIDMlkitFaceIdentifiers.frameProcessorPluginName,
+    );
+  });
+
+  describe("configure", () => {
+    it("passes the validated config through to native", async () => {
+      native.configure.mockResolvedValueOnce(undefined);
+      await useSmileIDMlkitFace.configure({ selfieCaptureTimeout: 60_000 });
+      expect(native.configure).toHaveBeenCalledTimes(1);
+      expect(native.configure).toHaveBeenCalledWith({
+        selfieCaptureTimeout: 60_000,
+      });
+    });
+
+    it("rejects malformed config at the JS boundary before crossing the bridge", async () => {
+      // Concrete scenario: a partner builds a config from float math
+      // and passes `selfieCaptureTimeout: 60_000.5`. Without the
+      // boundary parse, the value would marshal to a Kotlin `Int`
+      // with silent truncation. With it, the JS layer throws here
+      // and `native.configure` is never called.
+      await expect(
+        useSmileIDMlkitFace.configure({
+          // @ts-expect-error — deliberately wrong: int field with float value
+          selfieCaptureTimeout: 60_000.5,
+        }),
+      ).rejects.toThrow();
+      expect(native.configure).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("reset", () => {
+    it("routes to native reset", async () => {
+      native.reset.mockResolvedValueOnce(undefined);
+      await useSmileIDMlkitFace.reset();
+      expect(native.reset).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("close", () => {
+    it("routes to native close", async () => {
+      native.close.mockResolvedValueOnce(undefined);
+      await useSmileIDMlkitFace.close();
+      expect(native.close).toHaveBeenCalledTimes(1);
+    });
+
+    it("is idempotent — partner can call it twice safely", async () => {
+      // Idempotency contract from FaceAnalyzer doc-comment. The native
+      // side handles the second close as a no-op; the wrapper just
+      // needs to not throw on re-entry.
+      native.close.mockResolvedValue(undefined);
+      await useSmileIDMlkitFace.close();
+      await useSmileIDMlkitFace.close();
+      expect(native.close).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,46 @@
+import { AnalyzerFactoryKey } from "@smileid/usesmileid_bridge";
+import type { FaceConfig, FaceScanResult } from "@smileid/usesmileid_bridge";
+import { useSmileIDAnalyzerExecutor } from "@smileid/usesmileid_platform_interface";
+
+/**
+ * Google ML Kit face analyzer (Android-only).
+ *
+ * Thin shim around the existing native session
+ * `com.usesmileid.bridge.session.UseSmileIDFaceSession(FaceDetectorAnalyzer())`
+ * shipped in the `com.smileidentity:mlkit-face` AAR. The native side
+ * runs the entire pipeline (analyzer + validator + transitioner +
+ * state machine); this TS layer only routes calls and validates wire
+ * payloads at the channel boundary.
+ *
+ * The canonical wiring lives in [useSmileIDAnalyzerExecutor] in
+ * `usesmileid_platform_interface`. This file only supplies the
+ * provider-specific identity so all six provider modules share one set
+ * of correctness properties by construction.
+ *
+ * Lifecycle: `configure()` → per-frame analysis via the native frame
+ * processor plugin → `reset()`? → `close()`. Calling
+ * `close()` twice is idempotent. See `usesmileid_platform_interface`
+ * `FaceAnalyzer` for the canonical contract.
+ */
+/**
+ * Must match the Kotlin Expo Module's `Name("UseSmileIDMlkitFace")` and its
+ * VisionCamera frame-processor-plugin registration — drift is a runtime
+ * "module/plugin not found" error, not a compile error.
+ */
+export const UseSmileIDMlkitFaceIdentifiers = {
+  nativeModuleName: "UseSmileIDMlkitFace",
+  frameProcessorPluginName: "UseSmileIDMlkitFaceFrameProcessor",
+} as const;
+
+export const useSmileIDMlkitFace = useSmileIDAnalyzerExecutor({
+  nativeModuleName: UseSmileIDMlkitFaceIdentifiers.nativeModuleName,
+  frameProcessorPluginName:
+    UseSmileIDMlkitFaceIdentifiers.frameProcessorPluginName,
+  kind: "face",
+  key: AnalyzerFactoryKey.MLKitFace,
+});
+
+// Re-export the contract types so consumers don't need a separate
+// import line for `FaceConfig` / `FaceScanResult` when they're using
+// this provider.
+export type { FaceConfig, FaceScanResult };