@smileid/usesmileid_vision_document 12.1.1 → 12.2.1-SNAPSHOT.44

package/CHANGELOG.md

@@ -1,15 +1,17 @@
 Full release notes: [Smile ID docs](https://docs.usesmileid.com/developer-resources/sdks/mobile/release-notes/react-native-expo).
 
+## 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.
 
-
 ## 12.1.0
 
 See the repository CHANGELOG for the 12.1.0 release notes.
 
-
 ## 12.0.2
 
 See the repository CHANGELOG for the 12.0.2 release notes.

package/README.md

@@ -62,7 +62,7 @@ your own and other vendors'.
 ```ts
 import { useSmileIDVisionDocument } from "@smileid/usesmileid_vision_document";
 
-await useSmileIDVisionDocument.configure({ timeoutMs: 15_000 });
+await useSmileIDVisionDocument.configure({ timeRequired: 500 });
 const result = await useSmileIDVisionDocument.analyze(bytes, rotation);
 await useSmileIDVisionDocument.close();
 ```

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { DocumentConfig, DocumentScanResult } from "@smileid/usesmileid_bridge";
+import { type DocumentConfig, type DocumentScanResult } from "@smileid/usesmileid_bridge";
 /**
  * Apple Vision document analyzer (iOS-only).
  *

package/dist/index.js

@@ -1 +1 @@
-"use strict";import{useSmileIDAnalyzerExecutor as e}from"@smileid/usesmileid_platform_interface";export const UseSmileIDVisionDocumentIdentifiers={nativeModuleName:"UseSmileIDVisionDocument",frameProcessorPluginName:"UseSmileIDVisionDocumentFrameProcessor"},useSmileIDVisionDocument=e({nativeModuleName:UseSmileIDVisionDocumentIdentifiers.nativeModuleName,frameProcessorPluginName:UseSmileIDVisionDocumentIdentifiers.frameProcessorPluginName,kind:"document"});
+"use strict";import{DocumentAnalyzerKey as e}from"@smileid/usesmileid_bridge";import{useSmileIDAnalyzerExecutor as o}from"@smileid/usesmileid_platform_interface";export const UseSmileIDVisionDocumentIdentifiers={nativeModuleName:"UseSmileIDVisionDocument",frameProcessorPluginName:"UseSmileIDVisionDocumentFrameProcessor"},useSmileIDVisionDocument=o({nativeModuleName:UseSmileIDVisionDocumentIdentifiers.nativeModuleName,frameProcessorPluginName:UseSmileIDVisionDocumentIdentifiers.frameProcessorPluginName,kind:"document",key:e.VisionDocument});

package/ios/UseSmileIDVisionDocumentModule/ResizingFrameStorage.swift

@@ -1,6 +1,8 @@
 // MIRRORED FILE — duplicated in both RN Expo iOS vision modules
-// (usesmileid_vision_face / usesmileid_vision_document); the per-module pod
-// targets can't share sources. Apply any edit to BOTH copies in the same commit.
+// (usesmileid_vision_face / usesmileid_vision_document). The per-module pod
+// targets can't share sources, and the bridge pod that both depend on doesn't
+// link the native UseSmileIDBridge package this conforms to. Apply any edit to
+// BOTH copies in the same commit.
 
 import Foundation
 import UIKit
@@ -17,11 +19,34 @@ import UseSmileIDBridge
 final class ResizingFrameStorage: FrameStorage {
   /// Longest-edge pixel bound applied to document frames before encoding.
   private static let documentMaxDimension = 1600
-  /// Outward padding fraction applied to the guide-rect crop on each side
-  /// before cropping. Fifteen percent of the box's own width/height keeps the
-  /// document's corners and edges from being clipped when the card is framed
-  /// tight against the on-screen guide.
-  private static let documentCropPaddingFraction: CGFloat = 0.15
+  /// 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.documentBorderFraction` 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.
+  static let documentBorderFraction: CGFloat = 0.15
+
+  /// The uniform border, in pixels, to grow `guide` by: the b that is
+  /// `documentBorderFraction` 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 an `imageSize` image can hold; 0 for an empty guide or one
+  /// touching an edge. Mirrors the native bridges' `DocumentCropGeometry.borderAround`.
+  static func borderAround(_ guide: CGRect, imageSize: CGSize) -> CGFloat {
+    let shortSide = min(guide.width, guide.height)
+    guard shortSide > 0 else { return 0 }
+    let wanted = documentBorderFraction * shortSide / (1 - 2 * documentBorderFraction)
+    let room = min(guide.minX, guide.minY, imageSize.width - guide.maxX, imageSize.height - guide.maxY)
+    return max(min(wanted, room), 0)
+  }
+
+  /// A `border` around a crop of `size` as a fraction of the crop's short side,
+  /// held to `documentBorderFraction` so the crop's pixel rounding never reports
+  /// more border than was kept; 0 for an empty crop.
+  static func borderFraction(_ border: CGFloat, of size: CGSize) -> CGFloat {
+    let shortSide = min(size.width, size.height)
+    guard shortSide > 0 else { return 0 }
+    return min(max(border / shortSide, 0), documentBorderFraction)
+  }
 
   private let sessionDirectory: URL
   private let captureType: CaptureType
@@ -34,12 +59,18 @@ final class ResizingFrameStorage: FrameStorage {
   private let livenessQuality: CGFloat
   private let documentQuality: CGFloat
   private let writer: Writer
+  /// The hidden border each document this storage saved kept, recorded by the
+  /// write tasks once their file is on disk and read after `flush()`.
+  private let savedBorders = SavedDocumentBorders()
   // The analysis tick calls `setCropRegion` on the module's async-function
   // thread; `persist` reads the value on that same serialised scan path before
   // handing it (by value) to the background encode task. The Swift value is a
   // `Sendable` struct captured by value into `Writer.enqueue`, so no background
   // task ever observes a torn read of this property.
-  nonisolated(unsafe) private var cropRegion: ViewportCropRegion?
+  //
+  // Read back as `FrameStorage.cropRegion`, which the document transitioner judges the detected
+  // document against, so auto-capture waits for the document inside the outline (ios-v12 #370).
+  nonisolated(unsafe) private(set) var cropRegion: ViewportCropRegion?
 
   init(
     sessionDirectory: URL,
@@ -124,7 +155,8 @@ final class ResizingFrameStorage: FrameStorage {
         resize: resize,
         maxDimension: maxDimension,
         quality: quality,
-        documentCropRegion: documentCropRegion
+        documentCropRegion: documentCropRegion,
+        savedBorders: savedBorders
       )
     }
   }
@@ -133,6 +165,16 @@ final class ResizingFrameStorage: FrameStorage {
     try await writer.flush()
   }
 
+  /// The hidden border the document at `url` was saved with, as a fraction of its
+  /// short side on every edge, once `flush()` has returned:
+  /// `documentBorderFraction` 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.
+  func documentBorderFraction(at url: URL) -> CGFloat {
+    savedBorders.fraction(for: url)
+  }
+
   func clear() {
     // Selfie and document captures share one session directory; delete
     // only this role's own frames.
@@ -143,6 +185,7 @@ final class ResizingFrameStorage: FrameStorage {
     )) ?? []
     for fileURL in contents where ownsForClear(fileURL) {
       try? fileManager.removeItem(at: fileURL)
+      savedBorders.record(0, for: fileURL)
     }
   }
 
@@ -170,17 +213,24 @@ final class ResizingFrameStorage: FrameStorage {
       resize: (Int, Int)?,
       maxDimension: Int?,
       quality: CGFloat,
-      documentCropRegion: ViewportCropRegion?
+      documentCropRegion: ViewportCropRegion?,
+      savedBorders: SavedDocumentBorders
     ) {
       let task = Task<Void, Error>.detached(priority: .utility) {
-        try Self.encodeAndWrite(
-          image: image,
-          to: url,
-          resize: resize,
-          maxDimension: maxDimension,
-          quality: quality,
-          documentCropRegion: documentCropRegion
-        )
+        do {
+          let borderFraction = try Self.encodeAndWrite(
+            image: image,
+            to: url,
+            resize: resize,
+            maxDimension: maxDimension,
+            quality: quality,
+            documentCropRegion: documentCropRegion
+          )
+          savedBorders.record(borderFraction, for: url)
+        } catch {
+          savedBorders.record(0, for: url)
+          throw error
+        }
       }
       inFlight.append(task)
     }
@@ -208,7 +258,7 @@ final class ResizingFrameStorage: FrameStorage {
       maxDimension: Int?,
       quality: CGFloat,
       documentCropRegion: ViewportCropRegion?
-    ) throws {
+    ) throws -> CGFloat {
       try FileManager.default.createDirectory(
         at: url.deletingLastPathComponent(),
         withIntermediateDirectories: true
@@ -219,6 +269,8 @@ final class ResizingFrameStorage: FrameStorage {
       // render the file sideways.
       let upright = image.normalizingOrientation()
       let data: Data?
+      // The border the saved document kept, as a fraction of its short side.
+      var borderFraction: CGFloat = 0
       if let (width, height) = resize, let cgImage = upright.cgImage {
         // Center-crop and scale to the token-resolved target size
         // (selfie / liveness path).
@@ -236,20 +288,25 @@ final class ResizingFrameStorage: FrameStorage {
           let pixelWidth = cgImage.width
           let pixelHeight = cgImage.height
           let box = region.toFrameBoundingBox(frameWidth: pixelWidth, frameHeight: pixelHeight)
-          // Pad the guide rect outward by documentCropPaddingFraction of its
-          // own size on each side so the document's corners and edges keep
-          // breathing room and are never clipped when framed tight. Intersect
-          // with the image bounds so a padded edge never runs off-frame.
-          let padX = CGFloat(box.width) * ResizingFrameStorage.documentCropPaddingFraction
-          let padY = CGFloat(box.height) * ResizingFrameStorage.documentCropPaddingFraction
-          let cropRect = CGRect(
-            x: (CGFloat(box.left) - padX) * CGFloat(pixelWidth),
-            y: (CGFloat(box.top) - padY) * CGFloat(pixelHeight),
-            width: (CGFloat(box.width) + padX * 2) * CGFloat(pixelWidth),
-            height: (CGFloat(box.height) + padY * 2) * CGFloat(pixelHeight)
-          ).intersection(CGRect(x: 0, y: 0, width: pixelWidth, height: pixelHeight))
+          // Grow the guide rect by the hidden border (documentBorderFraction of
+          // the saved image's short side, uniform on every edge), which the
+          // preview never shows; clamp to the image bounds.
+          let imageSize = CGSize(width: pixelWidth, height: pixelHeight)
+          let guide = CGRect(
+            x: CGFloat(box.left) * imageSize.width,
+            y: CGFloat(box.top) * imageSize.height,
+            width: CGFloat(box.width) * imageSize.width,
+            height: CGFloat(box.height) * imageSize.height
+          )
+          let border = ResizingFrameStorage.borderAround(guide, imageSize: imageSize)
+          let cropRect = guide.insetBy(dx: -border, dy: -border)
+            .intersection(CGRect(origin: .zero, size: imageSize))
           if let cropped = cgImage.cropping(to: cropRect) {
             cgImage = cropped
+            borderFraction = ResizingFrameStorage.borderFraction(
+              border,
+              of: CGSize(width: cropped.width, height: cropped.height)
+            )
           }
         }
         let pixelWidth = cgImage.width
@@ -277,10 +334,27 @@ final class ResizingFrameStorage: FrameStorage {
         throw ResizingFrameStorageError.encodeFailed(url: url)
       }
       try data.write(to: url, options: .atomic)
+      return borderFraction
     }
   }
 }
 
+/// The hidden border each document a `ResizingFrameStorage` saved kept, as a
+/// fraction of its short side, by file. Shared with the detached write tasks, so it
+/// is lock-guarded.
+final class SavedDocumentBorders: @unchecked Sendable {
+  private let lock = NSLock()
+  private var fractions: [URL: CGFloat] = [:]
+
+  func record(_ fraction: CGFloat, for url: URL) {
+    lock.withLock { fractions[url.standardizedFileURL] = fraction > 0 ? fraction : nil }
+  }
+
+  func fraction(for url: URL) -> CGFloat {
+    lock.withLock { fractions[url.standardizedFileURL] ?? 0 }
+  }
+}
+
 enum ResizingFrameStorageError: Error, Sendable {
   case encodeFailed(url: URL)
 }

package/ios/UseSmileIDVisionDocumentModule/UseSmileIDVisionDocumentKameraAnalysisTick.swift

@@ -1,70 +1,56 @@
-import CoreMedia
 import Kamera
-import CoreImage
 import UIKit
 import UseSmileIDBridge
 
-
-private extension CGImagePropertyOrientation {
-  /// Kamera rotation + mirror metadata → the preview's view of the frame. The rotation already
-  /// follows the locked interface axis, so no further fold onto the viewport is needed.
-  init(rotationDegrees: Int, isMirrored: Bool) {
-    let normalised = ((rotationDegrees % 360) + 360) % 360
-    switch (normalised, isMirrored) {
-    case (90, false): self = .right
-    case (90, true): self = .leftMirrored
-    case (180, false): self = .down
-    case (180, true): self = .downMirrored
-    case (270, false): self = .left
-    case (270, true): self = .rightMirrored
-    case (_, true): self = .upMirrored
-    default: self = .up
-    }
-  }
-}
-
 /// Scans the latest `KameraFrameHub` frame; no pending frame returns the `no_frame` wire error.
 enum UseSmileIDVisionDocumentKameraTick {
-  /// Reused across ticks — per-tick creation recompiles the GPU pipeline.
-  private static let ciContext = CIContext(options: [.useSoftwareRenderer: false])
-
   static func analyze(arguments: [String: Any?]?) -> Any {
     guard let frame = KameraFrameHub.take() else {
       return ["error": "no_frame"]
     }
-    guard let concrete = frame as? CVPixelBufferKameraFrame else {
-      frame.close()
-      return ["error": "frame_conversion_failed"]
-    }
-
-    let orientedImage = CIImage(cvPixelBuffer: concrete.pixelBuffer)
-      .oriented(CGImagePropertyOrientation(
-        rotationDegrees: frame.rotationDegrees,
-        isMirrored: frame.isMirrored
-      ))
-    let cgImage = ciContext.createCGImage(orientedImage, from: orientedImage.extent)
-    frame.close()
-    guard let cgImage else {
+    // The session reads the live frame's readings as the scan runs; closing it afterwards releases
+    // it to the pipeline for the next one.
+    defer { frame.close() }
+    guard frame is CVPixelBufferKameraFrame else {
       return ["error": "frame_conversion_failed"]
     }
 
     let rotation = (arguments?["rotation"] as? NSNumber)?.intValue ?? 0
 
     // Crop the saved capture to the guide rectangle the user framed.
-    UseSmileIDVisionDocumentSessionHolder.shared.setCropRegion(kameraCropRegionFrom(arguments))
+    let cropRegion = kameraCropRegionFrom(arguments)
+    UseSmileIDVisionDocumentSessionHolder.shared.setCropRegion(cropRegion)
+    // The guide follows the overlay's crop and the upright frame's size, for the camera's
+    // close-focus floor.
+    let guideTracker = UseSmileIDVisionDocumentSessionHolder.shared.guideTracker
+    guideTracker?.setCropRegion(cropRegion)
+    // The frame is sensor-native; its rotation turns it upright.
+    let turned = frame.rotationDegrees % 180 != 0
+    guideTracker?.setUprightFrameSize(
+      width: turned ? frame.height : frame.width,
+      height: turned ? frame.width : frame.height
+    )
 
-    guard let result = UseSmileIDVisionDocumentSessionHolder.shared.scanAndDrain(
-      image: UIImage(cgImage: cgImage),
+    guard var result = UseSmileIDVisionDocumentSessionHolder.shared.scanAndDrain(
+      frame: frame,
       rotation: rotation
     ) else {
       return ["error": "session_not_configured"]
     }
+    if let guide = guideTracker?.guide {
+      result["documentGuide"] = documentGuideWire(guide)
+    }
     return result
   }
 }
 
+/// A guide as the JS `documentGuideSchema` reads it.
+func documentGuideWire(_ guide: DocumentGuide) -> [String: Any] {
+  ["widthMm": guide.widthMm, "frameWidthFraction": guide.frameWidthFraction]
+}
+
 /// Crop region from the flat crop args; nil when `cropWidth <= 0` means no region.
-private func kameraCropRegionFrom(_ arguments: [String: Any?]?) -> ViewportCropRegion? {
+func kameraCropRegionFrom(_ arguments: [String: Any?]?) -> ViewportCropRegion? {
   guard let width = (arguments?["cropWidth"] as? NSNumber)?.floatValue, width > 0 else {
     return nil
   }

package/ios/UseSmileIDVisionDocumentModule/UseSmileIDVisionDocumentModule.swift

@@ -12,6 +12,9 @@ public class UseSmileIDVisionDocumentModule: Module {
 
 
   private var session: UseSmileIDDocumentSession?
+  /// The latest session's storage, kept past `close` so `documentBorderFraction` can read the
+  /// border of a document saved before the flow moved on.
+  private var storage: ResizingFrameStorage?
 
   public func definition() -> ModuleDefinition {
     Name("UseSmileIDVisionDocument")
@@ -20,6 +23,7 @@ public class UseSmileIDVisionDocumentModule: Module {
     }
 
     AsyncFunction("configure") { (config: [String: Any?]) in
+      UseSmileIDVisionDocumentSessionHolder.shared.configureGuide(config)
       // The active side selects the `document_front.jpg` /
       // `document_back.jpg` filename; two-sided flows re-`configure` with
       // `back` so the back image doesn't overwrite the front.
@@ -43,6 +47,7 @@ public class UseSmileIDVisionDocumentModule: Module {
         frameStorage: storage
       )
       self.session = newSession
+      self.storage = storage
       // Publish the session through the holder's operation queue so the
       // write is serialised with any concurrent scan on the FP thread.
       UseSmileIDVisionDocumentSessionHolder.shared.setSession(newSession)
@@ -56,6 +61,17 @@ public class UseSmileIDVisionDocumentModule: Module {
       UseSmileIDVisionDocumentKameraTick.analyze(arguments: arguments)
     }
 
+    // The overlay's guide rectangle, as soon as it lays out: crops the saved capture to it and
+    // resolves what it frames. The tracker measures against the session's frame size until the first
+    // frame, so the camera gets its zoom before it starts.
+    AsyncFunction("setCropRegion") { (arguments: [String: Any?]?) -> [String: Any]? in
+      let region = kameraCropRegionFrom(arguments)
+      UseSmileIDVisionDocumentSessionHolder.shared.setCropRegion(region)
+      guard let tracker = UseSmileIDVisionDocumentSessionHolder.shared.guideTracker else { return nil }
+      tracker.setCropRegion(region)
+      return tracker.guide.map(documentGuideWire)
+    }
+
     AsyncFunction("reset") {
       UseSmileIDVisionDocumentSessionHolder.shared.reset()
     }
@@ -73,6 +89,14 @@ public class UseSmileIDVisionDocumentModule: Module {
       }
     }
 
+    // The hidden border the document at `url` was saved with, as a fraction of its short side,
+    // once `flush` has returned; 0 for a document saved without one.
+    AsyncFunction("documentBorderFraction") { (url: String) -> Double in
+      let fileURL = url.hasPrefix("file:") ? URL(string: url) : URL(fileURLWithPath: url)
+      guard let fileURL, let storage = self.storage else { return 0 }
+      return Double(storage.documentBorderFraction(at: fileURL))
+    }
+
     AsyncFunction("close") {
       UseSmileIDVisionDocumentSessionHolder.shared.setSession(nil)
       UseSmileIDVisionDocumentSessionHolder.shared.setStorage(nil)
@@ -107,20 +131,28 @@ public class UseSmileIDVisionDocumentModule: Module {
 private extension Dictionary where Key == String, Value == Any? {
   // JS numbers cross the Expo bridge as `NSNumber`; direct `Int`/`Double` casts
   // silently fail when the bit pattern doesn't match — funnel through `NSNumber`.
+  // Unset fields take the native capture screen's defaults (DocumentDetectorConfig), so the document is
+  // held as long and judged as the iOS SDK does. Its coverage floor sits at 0.12 because coverage is measured
+  // against the full analysis frame, which is wider than the preview shows.
   func toDocumentScanConfig() -> DocumentScanConfig {
-    DocumentScanConfig(
+    let screen = DocumentDetectorConfig()
+    let expectedAspectRatio = DocumentKind.expectedAspectRatio(
+      wireToken: self["documentKind"] as? String,
+      knownAspectRatio: (self["knownAspectRatio"] as? NSNumber)?.floatValue
+    )
+    return DocumentScanConfig(
       documentDetectorConfig: DocumentDetectorConfig(
-        timeout: (self["timeout"] as? NSNumber)?.intValue ?? 15_000,
-        iouThreshold: (self["iouThreshold"] as? NSNumber)?.floatValue ?? 0.85,
-        timeRequired: (self["timeRequired"] as? NSNumber)?.intValue ?? 1_000,
-        // Coverage is measured against the full analysis frame, which is wider than the preview;
-        // a guide-filling document covers only ~0.2 of it, so the floor must sit below that.
-          minCoverageThreshold: (self["minCoverageThreshold"] as? NSNumber)?.floatValue ?? 0.12,
-        maxCoverageThreshold: (self["maxCoverageThreshold"] as? NSNumber)?.floatValue ?? 0.78,
-        centerToleranceX: (self["centerToleranceX"] as? NSNumber)?.floatValue ?? 0.05,
-        centerToleranceY: (self["centerToleranceY"] as? NSNumber)?.floatValue ?? 0.05
+        iouThreshold: (self["iouThreshold"] as? NSNumber)?.floatValue ?? screen.iouThreshold,
+        timeRequired: (self["timeRequired"] as? NSNumber)?.intValue ?? screen.timeRequired,
+        minCoverageThreshold: (self["minCoverageThreshold"] as? NSNumber)?.floatValue ?? screen.minCoverageThreshold,
+        maxCoverageThreshold: (self["maxCoverageThreshold"] as? NSNumber)?.floatValue ?? screen.maxCoverageThreshold,
+        centerToleranceX: (self["centerToleranceX"] as? NSNumber)?.floatValue ?? screen.centerToleranceX,
+        centerToleranceY: (self["centerToleranceY"] as? NSNumber)?.floatValue ?? screen.centerToleranceY,
+        aspectRatioTolerance: screen.aspectRatioTolerance,
+        // The shape gate judges the document's own shape, by the bridge's rule for its kind.
+        expectedAspectRatio: expectedAspectRatio
       ),
-      stayInFoundDuration: (self["stayInFoundDuration"] as? NSNumber)?.intValue ?? 1_000
+      stayInFoundDuration: (self["stayInFoundDuration"] as? NSNumber)?.intValue ?? DocumentScanConfig().stayInFoundDuration
     )
   }
 }

package/ios/UseSmileIDVisionDocumentModule/UseSmileIDVisionDocumentSessionHolder.swift

@@ -1,4 +1,5 @@
 import Foundation
+import Kamera
 import UIKit
 import UseSmileIDBridge
 import UseSmileIDVisionDocument
@@ -27,6 +28,28 @@ final class UseSmileIDVisionDocumentSessionHolder {
 
   private init() {}
 
+  private let guideLock = NSLock()
+  private var currentGuideTracker: DocumentGuideTracker?
+
+  /// Keeps what the document guide frames, for the camera's close-focus floor; built at configure
+  /// from the document's kind and the session's analysis size, and nil without them.
+  var guideTracker: DocumentGuideTracker? {
+    guideLock.withLock { currentGuideTracker }
+  }
+
+  /// Builds `guideTracker` for the document kind and session size `config` carries.
+  func configureGuide(_ config: [String: Any?]) {
+    let next = DocumentKind.fromWireToken(config["documentKind"] as? String).flatMap { kind in
+      DocumentGuideTracker(
+        kind: kind,
+        sessionFrameWidth: (config["sessionFrameWidth"] as? NSNumber)?.intValue ?? 0,
+        sessionFrameHeight: (config["sessionFrameHeight"] as? NSNumber)?.intValue ?? 0,
+        onGuideChanged: { _ in }
+      )
+    }
+    guideLock.withLock { currentGuideTracker = next }
+  }
+
   /// Replace or clear the active session. Called from the Expo module's
   /// `configure`, `close`, and `OnDestroy` paths.
   func setSession(_ newSession: UseSmileIDDocumentSession?) {
@@ -90,7 +113,11 @@ final class UseSmileIDVisionDocumentSessionHolder {
 
   /// Run `session.scan` + `drainCaptureReadyEvents` as one atomic unit, blocking the
   /// caller. Returns `nil` when no session is configured; never throws.
-  func scanAndDrain(image: UIImage, rotation: Int) -> [String: Any]? {
+  ///
+  /// The session analyses the kamera `frame`'s pixel buffer as the native capture screens do, with
+  /// the readings kamera took on it (device motion, tracked face, live-frame quality), and draws an
+  /// image only for a frame a capture keeps. The caller keeps `frame` open until this returns.
+  func scanAndDrain(frame: any KameraFrame, rotation: Int) -> [String: Any]? {
     var result: [String: Any]?
     operationQueue.sync {
       guard let currentSession = session else {
@@ -98,8 +125,14 @@ final class UseSmileIDVisionDocumentSessionHolder {
       }
       let resultBox = ScanResultBox()
       let semaphore = DispatchSemaphore(value: 0)
+      let frameBox = KameraFrameBox(frame)
       Task.detached(priority: .userInitiated) {
-        let scanResult = await currentSession.scan(image: image, rotation: rotation)
+        guard let scanResult = await currentSession.scan(kameraFrame: frameBox.frame, rotation: rotation) else {
+          // A frame with no pixel buffer; the tick only hands over pixel-buffer frames.
+          resultBox.value = ["error": "frame_conversion_failed"]
+          semaphore.signal()
+          return
+        }
         let nativeOutput = scanResult.output as? UseSmileIDBridge.DocumentDetectorOutput
         let state = scanResult.state
         let events = currentSession.drainCaptureReadyEvents()
@@ -117,6 +150,16 @@ final class UseSmileIDVisionDocumentSessionHolder {
   }
 }
 
+/// Carries the kamera frame into the scan Task. Kamera frames guard their planes with their own
+/// lock, and the caller blocks on the Task while it reads the frame.
+private final class KameraFrameBox: @unchecked Sendable {
+  let frame: any KameraFrame
+
+  init(_ frame: any KameraFrame) {
+    self.frame = frame
+  }
+}
+
 /// Shuttles a scan result from the cooperative-pool Task to the semaphore-blocked caller.
 private final class ScanResultBox: @unchecked Sendable {
   var value: [String: Any] = [:]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smileid/usesmileid_vision_document",
-  "version": "12.1.1",
+  "version": "12.2.1-SNAPSHOT.44",
   "description": "Apple Vision document detection implementation for the UseSmileID React Native (Expo) SDK.",
   "homepage": "https://usesmileid.com",
   "repository": {
@@ -46,8 +46,8 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@smileid/usesmileid_bridge": "12.1.1",
-    "@smileid/usesmileid_platform_interface": "12.1.1"
+    "@smileid/usesmileid_bridge": "12.2.1-SNAPSHOT.44",
+    "@smileid/usesmileid_platform_interface": "12.2.1-SNAPSHOT.44"
   },
   "peerDependencies": {
     "expo": ">=56.0.0",
@@ -55,9 +55,9 @@
     "react-native": ">=0.83.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
-    "expo": "~57.0.20",
-    "expo-modules-core": "^57.0.16",
+    "@types/node": "^26.6.4",
+    "expo": "~57.0.26",
+    "expo-modules-core": "^57.0.20",
     "react-native": "^0.86.3",
     "typescript": "^6.0.3",
     "xcode": "^3.0.1"

package/plugin/build/index.js

@@ -1 +1 @@
-"use strict";var __createBinding=this&&this.__createBinding||(Object.create?(function(i,r,t,e){e===void 0&&(e=t);var o=Object.getOwnPropertyDescriptor(r,t);(!o||("get"in o?!r.__esModule:o.writable||o.configurable))&&(o={enumerable:!0,get:function(){return r[t]}}),Object.defineProperty(i,e,o)}):(function(i,r,t,e){e===void 0&&(e=t),i[e]=r[t]})),__setModuleDefault=this&&this.__setModuleDefault||(Object.create?(function(i,r){Object.defineProperty(i,"default",{enumerable:!0,value:r})}):function(i,r){i.default=r}),__importStar=this&&this.__importStar||(function(){var i=function(r){return i=Object.getOwnPropertyNames||function(t){var e=[];for(var o in t)Object.prototype.hasOwnProperty.call(t,o)&&(e[e.length]=o);return e},i(r)};return function(r){if(r&&r.__esModule)return r;var t={};if(r!=null)for(var e=i(r),o=0;o<e.length;o++)e[o]!=="default"&&__createBinding(t,r,e[o]);return __setModuleDefault(t,r),t}})();Object.defineProperty(exports,"__esModule",{value:!0}),exports.SPM_PRODUCTS=void 0;const config_plugins_1=require("expo/config-plugins"),fs=__importStar(require("fs")),path=__importStar(require("path")),deployment_target_1=require("./lib/deployment_target"),podfile_1=require("./lib/podfile"),signature_dedup_1=require("./lib/signature_dedup"),spm_1=require("./lib/spm"),IOS_DEPLOYMENT_TARGET="16.4",SMILE_ID_PACKAGE={url:"https://github.com/smileidentity/ios-spm",requirement:{kind:"exactVersion",version:"12.1.1"}},POD_TARGET="UseSmileIDVisionDocumentExpo";exports.SPM_PRODUCTS=["UseSmileIDVisionDocument"];const PODFILE_MARKER="usesmileid_vision_document",BRIDGE_POD_TARGET="UseSmileIDBridgeExpo",BRIDGE_SPM_PRODUCTS=["UseSmileIDBridge"],BRIDGE_PODFILE_MARKER="usesmileid_bridge",withVisionDocumentSpm=(i,r)=>(i=(0,deployment_target_1.withIosDeploymentTargetFloor)(i,IOS_DEPLOYMENT_TARGET),i=(0,config_plugins_1.withXcodeProject)(i,t=>{const e=t.modRequest.projectName;if(!e)throw new Error("[usesmileid_vision_document] Unable to resolve host app native target name from Expo config.");return(0,spm_1.linkSpmPackage)(t.modResults,SMILE_ID_PACKAGE,{targetName:e,products:[...exports.SPM_PRODUCTS]}),r?.iosSignatureAggregation==="disabled"?(0,signature_dedup_1.disableSignatureAggregation)(t.modResults,e):(0,signature_dedup_1.ensureSignatureDedupPhase)(t.modResults,e),t}),i=(0,config_plugins_1.withDangerousMod)(i,["ios",t=>{const e=path.join(t.modRequest.platformProjectRoot,"Podfile"),o=fs.readFileSync(e,"utf-8");let n=(0,podfile_1.injectPodfileSpmBlock)(o,{marker:PODFILE_MARKER,package:SMILE_ID_PACKAGE,podTarget:POD_TARGET,products:[...exports.SPM_PRODUCTS]});return n=(0,podfile_1.injectPodfileSpmBlock)(n,{marker:BRIDGE_PODFILE_MARKER,package:SMILE_ID_PACKAGE,podTarget:BRIDGE_POD_TARGET,products:[...BRIDGE_SPM_PRODUCTS],required:!0}),n=(0,podfile_1.injectPodfileKameraLinkBlock)(n),n=(0,podfile_1.injectPodfileSignatureDedupBlock)(n),n!==o&&fs.writeFileSync(e,n),t}]),i);exports.default=withVisionDocumentSpm;
+"use strict";var __createBinding=this&&this.__createBinding||(Object.create?(function(i,r,t,e){e===void 0&&(e=t);var o=Object.getOwnPropertyDescriptor(r,t);(!o||("get"in o?!r.__esModule:o.writable||o.configurable))&&(o={enumerable:!0,get:function(){return r[t]}}),Object.defineProperty(i,e,o)}):(function(i,r,t,e){e===void 0&&(e=t),i[e]=r[t]})),__setModuleDefault=this&&this.__setModuleDefault||(Object.create?(function(i,r){Object.defineProperty(i,"default",{enumerable:!0,value:r})}):function(i,r){i.default=r}),__importStar=this&&this.__importStar||(function(){var i=function(r){return i=Object.getOwnPropertyNames||function(t){var e=[];for(var o in t)Object.prototype.hasOwnProperty.call(t,o)&&(e[e.length]=o);return e},i(r)};return function(r){if(r&&r.__esModule)return r;var t={};if(r!=null)for(var e=i(r),o=0;o<e.length;o++)e[o]!=="default"&&__createBinding(t,r,e[o]);return __setModuleDefault(t,r),t}})();Object.defineProperty(exports,"__esModule",{value:!0}),exports.SPM_PRODUCTS=void 0;const config_plugins_1=require("expo/config-plugins"),fs=__importStar(require("fs")),path=__importStar(require("path")),deployment_target_1=require("./lib/deployment_target"),podfile_1=require("./lib/podfile"),signature_dedup_1=require("./lib/signature_dedup"),spm_1=require("./lib/spm"),IOS_DEPLOYMENT_TARGET="16.4",SMILE_ID_PACKAGE={url:"https://github.com/smileidentity/ios-spm",requirement:{kind:"exactVersion",version:"12.2.0-SNAPSHOT.20261011230808.38182841286"}},POD_TARGET="UseSmileIDVisionDocumentExpo";exports.SPM_PRODUCTS=["UseSmileIDVisionDocument"];const PODFILE_MARKER="usesmileid_vision_document",BRIDGE_POD_TARGET="UseSmileIDBridgeExpo",BRIDGE_SPM_PRODUCTS=["UseSmileIDBridge"],BRIDGE_PODFILE_MARKER="usesmileid_bridge",withVisionDocumentSpm=(i,r)=>(i=(0,deployment_target_1.withIosDeploymentTargetFloor)(i,IOS_DEPLOYMENT_TARGET),i=(0,config_plugins_1.withXcodeProject)(i,t=>{const e=t.modRequest.projectName;if(!e)throw new Error("[usesmileid_vision_document] Unable to resolve host app native target name from Expo config.");return(0,spm_1.linkSpmPackage)(t.modResults,SMILE_ID_PACKAGE,{targetName:e,products:[...exports.SPM_PRODUCTS]}),r?.iosSignatureAggregation==="disabled"?(0,signature_dedup_1.disableSignatureAggregation)(t.modResults,e):(0,signature_dedup_1.ensureSignatureDedupPhase)(t.modResults,e),t}),i=(0,config_plugins_1.withDangerousMod)(i,["ios",t=>{const e=path.join(t.modRequest.platformProjectRoot,"Podfile"),o=fs.readFileSync(e,"utf-8");let n=(0,podfile_1.injectPodfileSpmBlock)(o,{marker:PODFILE_MARKER,package:SMILE_ID_PACKAGE,podTarget:POD_TARGET,products:[...exports.SPM_PRODUCTS]});return n=(0,podfile_1.injectPodfileSpmBlock)(n,{marker:BRIDGE_PODFILE_MARKER,package:SMILE_ID_PACKAGE,podTarget:BRIDGE_POD_TARGET,products:[...BRIDGE_SPM_PRODUCTS],required:!0}),n=(0,podfile_1.injectPodfileKameraLinkBlock)(n),n=(0,podfile_1.injectPodfileSignatureDedupBlock)(n),n!==o&&fs.writeFileSync(e,n),t}]),i);exports.default=withVisionDocumentSpm;

package/plugin/build/lib/podfile.js

@@ -145,7 +145,7 @@ begin
     #    @rpath/Kamera.framework/Kamera"). Xcode embeds a binary product only for an app
     #    target that depends on it, so the app target takes both products directly.
     kamera_spm_url = 'https://github.com/smileidentity/kamera-spm'
-    kamera_spm_version = JSON.parse(File.read(kamera_package_json))['version'].sub(/-SNAPSHOT.*$/, '')
+    kamera_spm_version = JSON.parse(File.read(kamera_package_json))['version'].sub(/-SNAPSHOT$/, '')
     kamera_spm_app_products = %w[Kamera KameraVision]
     # A reference an app added by hand may spell the same repository differently (.git suffix,
     # trailing slash, case); a second reference to one repository fails Xcode's resolution.

package/ios/UseSmileIDVisionDocumentModule/UseSmileIDAnalyzerExecutor.swift

@@ -1,119 +0,0 @@
-// 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))
-            }
-        }
-    }
-}