@smileid/usesmileid_vision_face 12.0.0-beta01

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 12.0.0-beta01
+
+First public beta release. Apple Vision 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,50 @@
+# `@smileid/usesmileid_vision_face`
+
+UseSmileID v12 — Apple Vision face provider for React Native (Expo Modules).
+**iOS-only.** Thin shim around the existing Swift Package
+`UseSmileIDVisionFace`.
+
+## Architecture
+
+The native side runs the entire face-scan pipeline (analyzer +
+validator + transitioner + state machine). This package contributes a
+Swift Expo Module that constructs `UseSmileIDFaceSession(FaceDetectorAnalyzer())`
+and a TS wrapper that bridges the four contract methods (`configure /
+analyze / reset / close`) with Zod-validated wire payloads.
+
+No ML logic is reimplemented in this package — it's a pure passthrough.
+See `react-native-expo/docs/Architecture.md`.
+
+## Installation
+
+```sh
+pnpm add @smileid/usesmileid_vision_face
+```
+
+Run `npx pod-install` (or let Expo's prebuild handle it) so the iOS
+project picks up the SPM dependency declared in
+`UseSmileIDVisionFace.podspec`.
+
+## Usage
+
+```ts
+import { useSmileIDVisionFace } from "@smileid/usesmileid_vision_face";
+
+await useSmileIDVisionFace.configure({ selfieCaptureTimeoutMs: 60_000 });
+const result = await useSmileIDVisionFace.analyze(bytes, rotation);
+await useSmileIDVisionFace.close();
+```
+
+## Cross-platform peers
+
+| Platform         | Provider package                  | Native dep                   |
+| ---------------- | --------------------------------- | ---------------------------- |
+| iOS              | `@smileid/usesmileid_vision_face` | `UseSmileIDVisionFace` (SPM) |
+| Android          | `@smileid/usesmileid_mlkit_face`  | `com.usesmileid:mlkit-face`  |
+| Android (no GMS) | `@smileid/usesmileid_huawei_face` | `com.usesmileid:huawei-face` |
+
+## Testing
+
+```sh
+pnpm --filter @smileid/usesmileid_vision_face test
+```

package/app.plugin.js

@@ -0,0 +1,3 @@
+// Entry point Expo discovers when an app references this package in
+// `expo.plugins`. The compiled plugin lives at `plugin/build/index.js`.
+module.exports = require("./plugin/build");

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import type { FaceConfig, FaceScanResult } from "@smileid/usesmileid_bridge";
+/**
+ * Apple Vision face analyzer (iOS-only).
+ *
+ * Thin shim around the existing native session
+ * `UseSmileID.UseSmileIDFaceSession(FaceDetectorAnalyzer())` shipped in
+ * the `UseSmileIDVisionFace` Swift Package. The native side runs the
+ * entire pipeline (analyzer + validator + transitioner + state
+ * machine); this TS layer routes calls and validates wire payloads at
+ * the channel boundary.
+ *
+ * The canonical wiring lives in [useSmileIDAnalyzerExecutor] in
+ * `usesmileid_platform_interface`.
+ *
+ * Lifecycle: `configure()` → per-frame analysis via the native frame
+ * processor plugin → `reset()`? → `close()`. See
+ * `usesmileid_platform_interface` `FaceAnalyzer` for the canonical
+ * contract.
+ */
+/**
+ * Must match the Swift Expo Module's `Name("UseSmileIDVisionFace")` and its
+ * VisionCamera frame-processor-plugin registration — drift is a runtime
+ * "module/plugin not found" error, not a compile error.
+ */
+export declare const UseSmileIDVisionFaceIdentifiers: {
+    readonly nativeModuleName: "UseSmileIDVisionFace";
+    readonly frameProcessorPluginName: "UseSmileIDVisionFaceFrameProcessor";
+};
+export declare const useSmileIDVisionFace: 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;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;GAIG;AACH,eAAO,MAAM,+BAA+B;;;CAGlC,CAAC;AAEX,eAAO,MAAM,oBAAoB,+DAM/B,CAAC;AAEH,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,36 @@
+import { AnalyzerFactoryKey } from "@smileid/usesmileid_bridge";
+import { useSmileIDAnalyzerExecutor } from "@smileid/usesmileid_platform_interface";
+/**
+ * Apple Vision face analyzer (iOS-only).
+ *
+ * Thin shim around the existing native session
+ * `UseSmileID.UseSmileIDFaceSession(FaceDetectorAnalyzer())` shipped in
+ * the `UseSmileIDVisionFace` Swift Package. The native side runs the
+ * entire pipeline (analyzer + validator + transitioner + state
+ * machine); this TS layer routes calls and validates wire payloads at
+ * the channel boundary.
+ *
+ * The canonical wiring lives in [useSmileIDAnalyzerExecutor] in
+ * `usesmileid_platform_interface`.
+ *
+ * Lifecycle: `configure()` → per-frame analysis via the native frame
+ * processor plugin → `reset()`? → `close()`. See
+ * `usesmileid_platform_interface` `FaceAnalyzer` for the canonical
+ * contract.
+ */
+/**
+ * Must match the Swift Expo Module's `Name("UseSmileIDVisionFace")` and its
+ * VisionCamera frame-processor-plugin registration — drift is a runtime
+ * "module/plugin not found" error, not a compile error.
+ */
+export const UseSmileIDVisionFaceIdentifiers = {
+    nativeModuleName: "UseSmileIDVisionFace",
+    frameProcessorPluginName: "UseSmileIDVisionFaceFrameProcessor",
+};
+export const useSmileIDVisionFace = useSmileIDAnalyzerExecutor({
+    nativeModuleName: UseSmileIDVisionFaceIdentifiers.nativeModuleName,
+    frameProcessorPluginName: UseSmileIDVisionFaceIdentifiers.frameProcessorPluginName,
+    kind: "face",
+    key: AnalyzerFactoryKey.VisionFace,
+});
+//# 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;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,gBAAgB,EAAE,sBAAsB;IACxC,wBAAwB,EAAE,oCAAoC;CACtD,CAAC;AAEX,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;IAC7D,gBAAgB,EAAE,+BAA+B,CAAC,gBAAgB;IAClE,wBAAwB,EACtB,+BAA+B,CAAC,wBAAwB;IAC1D,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,kBAAkB,CAAC,UAAU;CACnC,CAAC,CAAC"}

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["apple"],
+  "apple": {
+    "modules": ["UseSmileIDVisionFaceModule"]
+  }
+}

package/ios/UseSmileIDVisionFaceExpo.podspec

@@ -0,0 +1,61 @@
+require 'json'
+
+# Reads the package's package.json so version stays in sync with the
+# JS-side package version. Mirrors the convention used by every Expo
+# Module in this workspace.
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  # Pod name is intentionally distinct from the SPM product
+  # `UseSmileIDVisionFace` (declared in `expo-module.config.json`)
+  # to avoid a name collision between the CocoaPods bridge target
+  # and the Swift Package product it imports.
+  s.name           = 'UseSmileIDVisionFaceExpo'
+  s.version        = package['version']
+  s.summary        = 'Apple Vision face provider for UseSmileID v12 (Expo Module bridge).'
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '15.0' }
+  s.swift_version  = '5.9'
+  s.source         = { git: 'https://github.com/usesmileid/react-native-expo.git', tag: "v#{s.version}" }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+  # VisionCamera provides the FrameProcessorPlugin base class and
+  # FrameProcessorPluginRegistry used by UseSmileIDVisionFaceFrameProcessorPlugin.
+  # Frame processors additionally require react-native-worklets-core in the
+  # consuming app (already declared as an SDK peer dependency).
+  s.dependency 'VisionCamera'
+
+  # The Smile ID native deps (`UseSmileIDVisionFace` / `UseSmileIDBridge`)
+  # are SPM-only — declared in `expo-module.config.json` under
+  # `apple.dependencies`. Expo Modules autolinking surfaces the SPM
+  # products to this target at compile time. Do NOT add a
+  # `s.dependency` for them here; that would require shipping a
+  # CocoaPods podspec for the binary, which we don't.
+
+  # Swift flags consistent with Expo Modules' Kotlin/Swift compiler-flag
+  # plumbing — toggled by the consuming app's Podfile when it runs in
+  # debug mode.
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule',
+    # Hardening — mirrors the native iOS frameworks' Release-config
+    # build settings. Dead code is stripped, install-path metadata is
+    # removed at link time, debug symbols (DWARF / line tables) are
+    # stripped via STRIP_STYLE = 'debugging', and Swift's field-name
+    # reflection metadata is dropped so class-dump / Hopper cannot
+    # recover Swift property names. STRIP_STYLE must stay 'debugging'
+    # (not 'all') — dynamic frameworks need their dyld-visible symbol
+    # table intact for consumers to link against. 'all' is for apps.
+    'DEAD_CODE_STRIPPING' => 'YES',
+    'DEPLOYMENT_POSTPROCESSING' => 'YES',
+    'STRIP_INSTALLED_PRODUCT' => 'YES',
+    'STRIP_STYLE' => 'debugging',
+    'SWIFT_REFLECTION_METADATA_LEVEL' => 'without-names'
+  }
+
+  s.source_files = 'UseSmileIDVisionFaceModule/**/*.{h,m,mm,swift,hpp,cpp}'
+end

package/ios/UseSmileIDVisionFaceModule/ResizingFrameStorage.swift

@@ -0,0 +1,181 @@
+// MIRRORED FILE — duplicated into both RN Expo iOS vision modules
+// (usesmileid_vision_face / usesmileid_vision_document). The per-module
+// CocoaPods bridge target sources cannot share files without a new pod.
+// Canonical location:
+//   usesmileid_vision_face/ios/UseSmileIDVisionFaceModule/ResizingFrameStorage.swift
+// Mirror location:
+//   usesmileid_vision_document/ios/UseSmileIDVisionDocumentModule/ResizingFrameStorage.swift
+//
+// Any edit here MUST be applied to the other location in the same commit.
+
+import Foundation
+import UIKit
+import UseSmileIDBridge
+
+/// `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.
+///
+/// Encode and write run on background tasks; `persist` is fire-and-forget so
+/// the analyzer keeps running at frame rate. `flush()` awaits all in-flight
+/// writes before upload proceeds.
+final class ResizingFrameStorage: FrameStorage {
+  private let sessionDirectory: URL
+  private let documentSide: DocumentSide
+  private let selfieTargetWidth: Int
+  private let selfieTargetHeight: Int
+  private let livenessTargetWidth: Int
+  private let livenessTargetHeight: Int
+  private let selfieQuality: CGFloat
+  private let livenessQuality: CGFloat
+  private let documentQuality: CGFloat
+  private let writer: Writer
+
+  init(
+    sessionDirectory: URL,
+    documentSide: DocumentSide = .front,
+    selfieTargetWidth: Int = 480,
+    selfieTargetHeight: Int = 640,
+    livenessTargetWidth: Int = 480,
+    livenessTargetHeight: Int = 640,
+    selfieQuality: CGFloat = 0.95,
+    livenessQuality: CGFloat = 0.80,
+    documentQuality: CGFloat = 0.85
+  ) {
+    self.sessionDirectory = sessionDirectory
+    self.documentSide = documentSide
+    self.selfieTargetWidth = selfieTargetWidth
+    self.selfieTargetHeight = selfieTargetHeight
+    self.livenessTargetWidth = livenessTargetWidth
+    self.livenessTargetHeight = livenessTargetHeight
+    self.selfieQuality = selfieQuality
+    self.livenessQuality = livenessQuality
+    self.documentQuality = documentQuality
+    self.writer = Writer()
+  }
+
+  func url(for kind: FrameKind, captureIndex: Int) -> URL {
+    let name: String
+    switch kind {
+    case .selfie:
+      name = "selfie.jpg"
+    case .liveness:
+      // Use the capture index so each liveness frame has a stable,
+      // deterministic name. Retries after `.unsatisfied` reuse the same
+      // URL, keeping the emitted CaptureReadyEvent and the on-disk file
+      // in sync per the FrameStorage contract.
+      name = "liveness_\(captureIndex).jpg"
+    case .document:
+      name = documentSide == .front ? "document_front.jpg" : "document_back.jpg"
+    @unknown default:
+      name = "frame_\(captureIndex).jpg"
+    }
+    return sessionDirectory.appendingPathComponent(name)
+  }
+
+  func persist(image: UIImage, to url: URL) {
+    let name = url.lastPathComponent
+    let resize: (Int, Int)?
+    let quality: CGFloat
+    if name.hasPrefix("selfie") {
+      resize = (selfieTargetWidth, selfieTargetHeight)
+      quality = selfieQuality
+    } else if name.hasPrefix("liveness") {
+      resize = (livenessTargetWidth, livenessTargetHeight)
+      quality = livenessQuality
+    } else {
+      // Document frames: encode at the analyzer's native resolution.
+      resize = nil
+      quality = documentQuality
+    }
+    Task {
+      await writer.enqueue(image: image, to: url, resize: resize, quality: quality)
+    }
+  }
+
+  func flush() async throws {
+    try await writer.flush()
+  }
+
+  func clear() {
+    let fileManager = FileManager.default
+    let contents = (try? fileManager.contentsOfDirectory(
+      at: sessionDirectory,
+      includingPropertiesForKeys: nil
+    )) ?? []
+    for fileURL in contents {
+      try? fileManager.removeItem(at: fileURL)
+    }
+  }
+
+  /// Serialises writes through an actor so concurrent `persist` calls for
+  /// the same URL don't race and `flush()` can join every outstanding task
+  /// without external synchronisation.
+  private actor Writer {
+    private var inFlight: [Task<Void, Error>] = []
+
+    func enqueue(image: UIImage, to url: URL, resize: (Int, Int)?, quality: CGFloat) {
+      let task = Task<Void, Error>.detached(priority: .utility) {
+        try Self.encodeAndWrite(image: image, to: url, resize: resize, quality: quality)
+      }
+      inFlight.append(task)
+    }
+
+    func flush() async throws {
+      let pending = inFlight
+      inFlight.removeAll()
+      var firstError: Error?
+      for task in pending {
+        do {
+          try await task.value
+        } catch {
+          firstError = firstError ?? error
+        }
+      }
+      if let firstError {
+        throw firstError
+      }
+    }
+
+    private static func encodeAndWrite(
+      image: UIImage,
+      to url: URL,
+      resize: (Int, Int)?,
+      quality: CGFloat
+    ) throws {
+      try FileManager.default.createDirectory(
+        at: url.deletingLastPathComponent(),
+        withIntermediateDirectories: true
+      )
+      // Bake any non-`.up` orientation into the pixel buffer before
+      // encoding. `UIImage.jpegData(...)` only writes the EXIF
+      // Orientation tag — viewers that ignore EXIF would otherwise
+      // render the file sideways.
+      let upright = image.normalizingOrientation()
+      let data: Data?
+      if let (width, height) = resize, let cgImage = upright.cgImage {
+        // Center-crop and scale to the token-resolved target size.
+        let cropped = cgImage.centerCroppedExact(width: width, height: height)
+        data = cropped.flatMap { UIImage(cgImage: $0).jpegData(compressionQuality: quality) }
+      } else {
+        data = upright.jpegData(compressionQuality: quality)
+      }
+      guard let data else {
+        throw ResizingFrameStorageError.encodeFailed(url: url)
+      }
+      try data.write(to: url, options: .atomic)
+    }
+  }
+}
+
+enum ResizingFrameStorageError: Error, Sendable {
+  case encodeFailed(url: URL)
+}

package/ios/UseSmileIDVisionFaceModule/UseSmileIDAnalyzerExecutor.swift

@@ -0,0 +1,119 @@
+// MIRRORED FILE — this file is duplicated byte-identical across the two
+// RN Expo iOS bridge modules. Canonical location:
+//   usesmileid_vision_face/ios/UseSmileIDVisionFaceModule/
+//     UseSmileIDAnalyzerExecutor.swift
+// Mirror location:
+//   usesmileid_vision_document/ios/UseSmileIDVisionDocumentModule/
+//     UseSmileIDAnalyzerExecutor.swift
+//
+// Each RN module is its own CocoaPods bridge target with its own
+// `source_files` glob; source cannot be shared across them without
+// inventing a new pod. The helper is duplicated verbatim into both
+// vision modules. Any edit here MUST be copied to the other location in
+// the same commit.
+//
+// Purpose: collapse the analyze / flush plumbing of the two RN Expo
+// vision modules into a single generic executor whose Task closures
+// capture only @Sendable values (closures + locals) — no module-class
+// state, no implicit `self`. This forces both modules to share one set
+// of Sendable correctness properties by construction: if one compiles
+// cleanly under strict concurrency, the other must too.
+//
+// RN-specific differences from the Flutter twin:
+//   • RN modules receive pre-decoded JPEG/PNG bytes (`UIImage(data:)`),
+//     so the executor accepts `UIImage` directly rather than Pigeon's
+//     `YuvImage` and an associated decoder. JPEG decoding happens in
+//     the per-module wrapper before the executor is invoked.
+//   • The completion signature is `(Result<PigeonResult, Error>) -> Void`
+//     identical to Flutter — the per-module wrapper translates that
+//     into Expo's `Promise.resolve`/`reject`. Keeping the executor's
+//     public surface a `Result` consumer means both bridges share the
+//     same Task discipline.
+
+import ExpoModulesCore
+import UIKit
+import UseSmileIDBridge
+
+/// Bridges an Expo Modules @escaping completion handler into Swift 6
+/// Task captures. Expo's `Promise` is itself reference-typed but not
+/// `Sendable`; the executor never captures a `Promise` — it captures a
+/// `Result` consumer closure that the per-module wrapper translates
+/// into `resolve`/`reject`. This box mirrors the Flutter PigeonCompletion
+/// pattern.
+final class ExecutorCompletion<T>: @unchecked Sendable {
+    let call: (T) -> Void
+    init(_ fn: @escaping (T) -> Void) { self.call = fn }
+}
+
+/// Generic helper that owns the analyze / flush bridging between the
+/// RN Expo Module's completion-based API and the native session's async
+/// API.
+///
+/// The class itself is `@unchecked Sendable` because it stores only
+/// `@Sendable` closures (which are themselves Sendable). The downstream
+/// `Task.detached` bodies capture those closures — never an instance of a
+/// concrete module class — so the compiler can prove the Task body is
+/// Sendable-by-construction.
+///
+/// `NativeOutput` is the concrete native analyzer output type (e.g.
+/// `FaceDetectorOutput`, `DocumentDetectorOutput`); `Wire` is the
+/// JS-side wire dictionary the module returns to JS (typed as
+/// `[String: Any?]` after Expo bridge marshalling).
+final class UseSmileIDAnalyzerExecutor<NativeOutput: AnalyzerOutput, Wire>: @unchecked Sendable {
+
+    private let scan: @Sendable (UIImage, Int) async -> (NativeOutput?, UseSmileIDScanState)
+    private let drainEvents: @Sendable () -> [UseSmileIDBridge.CaptureReadyEvent]
+    private let flushFn: @Sendable () async throws -> Void
+    private let buildResult: @Sendable (NativeOutput?, UseSmileIDScanState, [UseSmileIDBridge.CaptureReadyEvent]) -> Wire
+
+    init(
+        scan: @escaping @Sendable (UIImage, Int) async -> (NativeOutput?, UseSmileIDScanState),
+        drainEvents: @escaping @Sendable () -> [UseSmileIDBridge.CaptureReadyEvent],
+        flush: @escaping @Sendable () async throws -> Void,
+        buildResult: @escaping @Sendable (NativeOutput?, UseSmileIDScanState, [UseSmileIDBridge.CaptureReadyEvent]) -> Wire
+    ) {
+        self.scan = scan
+        self.drainEvents = drainEvents
+        self.flushFn = flush
+        self.buildResult = buildResult
+    }
+
+    /// Hands the already-decoded `UIImage` to the captured `scan` closure
+    /// on a detached task. The Task's capture list explicitly lists every
+    /// value it consumes so the compiler can verify the closure is
+    /// Sendable without falling back on implicit `self` capture.
+    ///
+    /// The `completion` consumer is a `Result<Wire, Error>` — the
+    /// per-module wrapper translates that into `Promise.resolve` /
+    /// `Promise.reject`.
+    func analyze(
+        image: UIImage,
+        rotation: Int,
+        completion: @escaping (Result<Wire, Error>) -> Void
+    ) {
+        let scan = self.scan
+        let drainEvents = self.drainEvents
+        let buildResult = self.buildResult
+        let completionBox = ExecutorCompletion(completion)
+        Task.detached(priority: .userInitiated) {
+            let (output, state) = await scan(image, rotation)
+            let events = drainEvents()
+            completionBox.call(.success(buildResult(output, state, events)))
+        }
+    }
+
+    /// Awaits the captured `flushFn` on a detached task. Mirrors `analyze`'s
+    /// capture discipline — no `self`, no class state.
+    func flush(completion: @escaping (Result<Void, Error>) -> Void) {
+        let flushFn = self.flushFn
+        let completionBox = ExecutorCompletion(completion)
+        Task.detached(priority: .userInitiated) {
+            do {
+                try await flushFn()
+                completionBox.call(.success(()))
+            } catch {
+                completionBox.call(.failure(error))
+            }
+        }
+    }
+}

package/ios/UseSmileIDVisionFaceModule/UseSmileIDVisionFaceFrameProcessorPlugin.swift

@@ -0,0 +1,96 @@
+import CoreMedia
+import CoreImage
+import UIKit
+import VisionCamera
+
+/// VisionCamera frame processor plugin that feeds camera frames directly
+/// into the active `UseSmileIDFaceSession` without crossing the JS thread.
+///
+/// Registered programmatically via `FrameProcessorPluginRegistry` (avoids ObjC bridging-header
+/// constraint); the `OnCreate` guard prevents double-registration on fast-refresh reloads.
+/// All session ops are serialised through `UseSmileIDVisionFaceSessionHolder.operationQueue`.
+/// `CIContext` is created once per instance — per-frame creation causes GPU pipeline re-compilation.
+@objc(UseSmileIDVisionFaceFrameProcessorPlugin)
+public class UseSmileIDVisionFaceFrameProcessorPlugin: FrameProcessorPlugin {
+
+  /// GPU-backed context reused across frames (CPU fallback if Metal unavailable).
+  private let ciContext = CIContext(options: [.useSoftwareRenderer: false])
+
+  @objc public override init(proxy: VisionCameraProxyHolder, options: [AnyHashable: Any]? = nil) {
+    super.init(proxy: proxy, options: options)
+  }
+
+  public override func callback(_ frame: Frame, withArguments arguments: [AnyHashable: Any]?) -> Any? {
+    guard frame.isValid else {
+      return ["error": "frame_conversion_failed"]
+    }
+
+    guard let pixelBuffer = CMSampleBufferGetImageBuffer(frame.buffer) else {
+      return ["error": "frame_conversion_failed"]
+    }
+
+    // Bake rotation physically into pixels (CIImage.oriented) rather than
+    // tagging UIImage with an orientation flag: some consumers honour the flag
+    // (UIKit draw) but others ignore it (raw CGImage ops), so physical pixels are safer.
+    // The front camera's mirror is preserved — the analyzer's head-pose
+    // convention is calibrated on mirrored pixels; un-mirroring flips
+    // Vision's yaw sign and inverts the ESS head-turn gates.
+    let orientationFlag = frame.isMirrored
+      ? frame.orientation.oppositeRotationPreservingMirror()
+      : frame.orientation
+    let orientedImage = CIImage(cvPixelBuffer: pixelBuffer)
+      .oriented(CGImagePropertyOrientation(orientationFlag))
+
+    guard let cgImage = ciContext.createCGImage(orientedImage, from: orientedImage.extent) else {
+      return ["error": "frame_conversion_failed"]
+    }
+
+    let rotation = (arguments?["rotation"] as? NSNumber)?.intValue ?? 0
+    let uiImage = UIImage(cgImage: cgImage)
+
+    guard let result = UseSmileIDVisionFaceSessionHolder.shared.scanAndDrain(
+      image: uiImage,
+      rotation: rotation
+    ) else {
+      return ["error": "session_not_configured"]
+    }
+
+    return result
+  }
+}
+
+
+private extension UIImage.Orientation {
+  /// Rotation-only flag that uprights a MIRRORED buffer while keeping its
+  /// mirror — flipH ∘ transpose is the opposite 90°, so quarter-turns swap.
+  /// Device-verified: `.right` ⇒ upright mirrored; raw `.left` ⇒ upside down.
+  func oppositeRotationPreservingMirror() -> UIImage.Orientation {
+    switch self {
+    case .left: return .right
+    case .right: return .left
+    case .leftMirrored: return .rightMirrored
+    case .rightMirrored: return .leftMirrored
+    default: return self
+    }
+  }
+}
+
+
+private extension CGImagePropertyOrientation {
+  /// Case-for-case translation from `UIImage.Orientation` — the two
+  /// enums share semantics but not raw values, so a direct cast would
+  /// silently produce the wrong transform.
+  init(_ uiOrientation: UIImage.Orientation) {
+    switch uiOrientation {
+    case .up: self = .up
+    case .upMirrored: self = .upMirrored
+    case .down: self = .down
+    case .downMirrored: self = .downMirrored
+    case .left: self = .left
+    case .leftMirrored: self = .leftMirrored
+    case .right: self = .right
+    case .rightMirrored: self = .rightMirrored
+    @unknown default: self = .up
+    }
+  }
+}