petrus-react-native 0.1.0

package/android/src/main/java/com/petrusreactnative/PetrusReactNativeModule.kt

@@ -0,0 +1,253 @@
+package com.petrusreactnative
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import android.util.Base64
+import androidx.core.content.ContextCompat
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.modules.core.PermissionAwareActivity
+import com.facebook.react.bridge.WritableMap
+import com.petrus.core.PetrusCore
+import com.petrus.vision.ocr.OCRProcessor
+import com.petrus.vision.pdf417.PDF417Decoder
+import com.petrus.vision.pdf417.PDF417Scanner
+import com.petrus.vision.sa.SouthAfricanIDParser
+import com.petrus.vision.pdf417.SouthAfricanDriversLicenseParser
+import com.petrus.vision.mrz.PassportParser
+import com.petrus.vision.vehicle.VehicleRegistrationParser
+import com.petrusreactnative.mrz.toWritableMap
+import com.petrusreactnative.ocr.toWritableMap
+import com.petrusreactnative.pdf417.toWritableMap
+import com.petrusreactnative.sa.toWritableMap
+import com.petrusreactnative.vehicle.toWritableMap
+import androidx.camera.core.ExperimentalGetImage
+import java.io.File
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+
+class PetrusReactNativeModule(reactContext: ReactApplicationContext) :
+  NativePetrusReactNativeSpec(reactContext) {
+
+  private val ocrProcessor = OCRProcessor()
+  private val pdf417Scanner = PDF417Scanner()
+  private val moduleScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+
+  // Phase 0 placeholder: proves the JS <-> TurboModule <-> petrus-core wiring
+  // works end to end. Replaced by the real capture/detect/OCR/parse API surface
+  // in later phases.
+  override fun getPipelineVersion(): String {
+    return "petrus-core@${PetrusCore.VERSION}"
+  }
+
+  override fun recognizeText(imagePath: String, promise: Promise) {
+    moduleScope.launch {
+      try {
+        val result = ocrProcessor.process(reactApplicationContext, imagePath)
+        promise.resolve(result.toWritableMap())
+      } catch (e: Exception) {
+        promise.reject("OCR_FAILED", e.message ?: "Text recognition failed", e)
+      }
+    }
+  }
+
+  override fun invalidate() {
+    ocrProcessor.close()
+    moduleScope.cancel()
+    super.invalidate()
+  }
+
+  // Synchronous -- pure CPU work (regex + arithmetic on a short string), no I/O,
+  // no coroutine needed. Same reasoning as getPipelineVersion.
+  override fun parseSouthAfricanID(text: String): WritableMap {
+    return SouthAfricanIDParser.parse(text).toWritableMap()
+  }
+
+  override fun scanPDF417(imagePath: String, promise: Promise) {
+    moduleScope.launch {
+      try {
+        val bitmap = loadBitmap(imagePath)
+        if (bitmap == null) {
+          promise.reject("PDF417_IMAGE_LOAD_FAILED", "Could not load image at $imagePath")
+          return@launch
+        }
+        val result =
+          try {
+            pdf417Scanner.scan(bitmap)
+          } finally {
+            bitmap.recycle()
+          }
+        if (result == null) {
+          promise.reject("PDF417_NOT_FOUND", "No PDF417 barcode found in the image")
+        } else {
+          promise.resolve(result.toWritableMap())
+        }
+      } catch (e: Exception) {
+        promise.reject("PDF417_SCAN_FAILED", e.message ?: "PDF417 scan failed", e)
+      }
+    }
+  }
+
+  // Synchronous -- pure CPU work (RSA modPow over a few hundred bytes + nibble
+  // parsing), no I/O. Throws (rather than returning a null/empty result) when
+  // rawDataBase64 doesn't decode to a recognized SA driver's licence format -- see
+  // NativePetrusReactNative.ts for why this differs from parseSouthAfricanID.
+  override fun parseSouthAfricanDriversLicense(rawDataBase64: String): WritableMap {
+    val bytes = Base64.decode(rawDataBase64, Base64.DEFAULT)
+    val decoded =
+      PDF417Decoder.decode(bytes)
+        ?: throw IllegalArgumentException(
+          "Data does not decode to a recognized SA driver's licence barcode format"
+        )
+    return SouthAfricanDriversLicenseParser.parse(decoded).toWritableMap()
+  }
+
+  override fun scanSouthAfricanDriversLicense(promise: Promise) {
+    PDF417ScanSession(reactApplicationContext).start(timeoutMs = SCAN_TIMEOUT_MS) { result ->
+      if (result == null) {
+        promise.reject("PDF417_SCAN_TIMEOUT", "No PDF417 barcode found within the scan window")
+        return@start
+      }
+      val decoded = PDF417Decoder.decode(result.rawBytes)
+      if (decoded == null) {
+        promise.reject(
+          "PDF417_DECODE_FAILED",
+          "Scanned barcode did not decode to a recognized SA driver's licence format",
+        )
+        return@start
+      }
+      promise.resolve(SouthAfricanDriversLicenseParser.parse(decoded).toWritableMap())
+    }
+  }
+
+  // Synchronous -- pure CPU work (regex-based field extraction over a short OCR
+  // string), no I/O, same reasoning as parseSouthAfricanID.
+  override fun parseVehicleRegistration(text: String): WritableMap {
+    return VehicleRegistrationParser.parse(text).toWritableMap()
+  }
+
+  // Constructing VehicleRegistrationScanSession touches ImageProxy.getImage()
+  // (via OCRProcessor.processFrame), which CameraX marks @ExperimentalGetImage --
+  // opted into here rather than propagated, since this is the leaf call site.
+  @OptIn(ExperimentalGetImage::class)
+  override fun scanVehicleRegistration(promise: Promise) {
+    VehicleRegistrationScanSession(reactApplicationContext).start(timeoutMs = SCAN_TIMEOUT_MS) { result ->
+      if (result == null) {
+        promise.reject("VEHICLE_REGISTRATION_SCAN_TIMEOUT", "No registration number or VIN found within the scan window")
+        return@start
+      }
+      promise.resolve(result.toWritableMap())
+    }
+  }
+
+  // Synchronous -- pure CPU work (regex + checksum arithmetic over two
+  // 44-character lines), same reasoning as parseSouthAfricanID. Never throws --
+  // PassportParser.parse never returns null (see its doc comment).
+  override fun parseMRZ(text: String): WritableMap {
+    return PassportParser.parse(text).toWritableMap()
+  }
+
+  // Unlike scanVehicleRegistration, no @ExperimentalGetImage opt-in is needed --
+  // PassportScanSession never touches ImageProxy.getImage() (MRZDetector uses
+  // the non-experimental ImageProxy.toBitmap(), and DocumentDetector uses
+  // ImageProxy.planes directly).
+  override fun scanPassport(promise: Promise) {
+    PassportScanSession(reactApplicationContext).start(timeoutMs = SCAN_TIMEOUT_MS) { result ->
+      if (result == null) {
+        promise.reject("PASSPORT_SCAN_TIMEOUT", "No passport MRZ found within the scan window")
+        return@start
+      }
+      promise.resolve(result.toWritableMap())
+    }
+  }
+
+  /** [imagePath] may be a bare filesystem path or a URI (file://, content://, ...). */
+  private fun loadBitmap(imagePath: String): Bitmap? {
+    val uri = if (imagePath.contains("://")) Uri.parse(imagePath) else Uri.fromFile(File(imagePath))
+    return reactApplicationContext.contentResolver.openInputStream(uri)?.use { stream ->
+      BitmapFactory.decodeStream(stream)
+    }
+  }
+
+  override fun checkPermission(promise: Promise) {
+    promise.resolve(currentPermissionStatus())
+  }
+
+  override fun requestPermission(promise: Promise) {
+    val activity = reactApplicationContext.currentActivity
+    if (activity !is PermissionAwareActivity) {
+      promise.reject("NO_ACTIVITY", "No activity available to request camera permission")
+      return
+    }
+
+    if (isGranted()) {
+      promise.resolve("granted")
+      return
+    }
+
+    markHasRequestedBefore()
+    activity.requestPermissions(
+      arrayOf(Manifest.permission.CAMERA),
+      CAMERA_PERMISSION_REQUEST_CODE,
+    ) { requestCode, _, grantResults ->
+      if (requestCode != CAMERA_PERMISSION_REQUEST_CODE) {
+        return@requestPermissions false
+      }
+      val granted = grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED
+      promise.resolve(if (granted) "granted" else currentPermissionStatus())
+      true
+    }
+  }
+
+  private fun isGranted(): Boolean =
+    ContextCompat.checkSelfPermission(
+      reactApplicationContext,
+      Manifest.permission.CAMERA,
+    ) == PackageManager.PERMISSION_GRANTED
+
+  /**
+   * Android has no direct "permanently blocked" signal. The standard heuristic (used by
+   * most permission libraries): if the permission isn't granted, rationale can no longer
+   * be shown, AND we know we've asked before, the user must have picked "don't ask
+   * again" -- otherwise it's just "not asked/denied yet, can still ask."
+   */
+  private fun currentPermissionStatus(): String {
+    if (isGranted()) return "granted"
+
+    val activity = reactApplicationContext.currentActivity
+    val canAskAgain =
+      activity is PermissionAwareActivity &&
+        activity.shouldShowRequestPermissionRationale(Manifest.permission.CAMERA)
+
+    return when {
+      canAskAgain -> "denied"
+      hasRequestedBefore() -> "blocked"
+      else -> "denied"
+    }
+  }
+
+  private fun hasRequestedBefore(): Boolean =
+    prefs().getBoolean(KEY_HAS_REQUESTED, false)
+
+  private fun markHasRequestedBefore() {
+    prefs().edit().putBoolean(KEY_HAS_REQUESTED, true).apply()
+  }
+
+  private fun prefs() =
+    reactApplicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+
+  companion object {
+    const val NAME = NativePetrusReactNativeSpec.NAME
+    private const val PREFS_NAME = "petrus_camera_permission"
+    private const val KEY_HAS_REQUESTED = "has_requested_camera_permission"
+    private const val CAMERA_PERMISSION_REQUEST_CODE = 5417
+    private const val SCAN_TIMEOUT_MS = 20_000L
+  }
+}

package/android/src/main/java/com/petrusreactnative/PetrusReactNativePackage.kt

@@ -0,0 +1,38 @@
+package com.petrusreactnative
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+import java.util.HashMap
+
+class PetrusReactNativePackage : BaseReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == PetrusReactNativeModule.NAME) {
+      PetrusReactNativeModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun createViewManagers(
+    reactContext: ReactApplicationContext
+  ): List<ViewManager<*, *>> {
+    return listOf(PetrusCameraViewManager())
+  }
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
+    mapOf(
+      PetrusReactNativeModule.NAME to ReactModuleInfo(
+        name = PetrusReactNativeModule.NAME,
+        className = PetrusReactNativeModule.NAME,
+        canOverrideExistingModule = false,
+        needsEagerInit = false,
+        isCxxModule = false,
+        isTurboModule = true
+      )
+    )
+  }
+}

package/android/src/main/java/com/petrusreactnative/VehicleRegistrationScanSession.kt

@@ -0,0 +1,119 @@
+package com.petrusreactnative
+
+import android.os.Handler
+import android.os.Looper
+import androidx.camera.core.CameraSelector
+import androidx.camera.core.ExperimentalGetImage
+import androidx.camera.core.ImageAnalysis
+import androidx.camera.lifecycle.ProcessCameraProvider
+import androidx.core.content.ContextCompat
+import androidx.lifecycle.LifecycleOwner
+import com.facebook.react.bridge.ReactApplicationContext
+import com.petrus.vision.ocr.OCRProcessor
+import com.petrus.vision.vehicle.VehicleRegistrationParser
+import com.petrus.vision.vehicle.VehicleRegistrationResult
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
+import java.util.concurrent.Executors
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * One-shot headless vehicle-registration scan: binds just an `ImageAnalysis` use
+ * case (no `Preview`/`PreviewView`) to the current Activity's lifecycle, runs OCR
+ * on frames via [OCRProcessor.processFrame] (petrus-core -- keeps ML Kit's
+ * `InputImage`/`Text` types out of this module entirely) and parses each result
+ * with [VehicleRegistrationParser], stopping once a frame yields a registration
+ * number or VIN, or [start]'s timeout elapses. Structurally mirrors
+ * `PDF417ScanSession`; needs `Activity`/`LifecycleOwner` access, same reasoning as
+ * why that class (and not petrus-core's `CameraController`) owns this plumbing.
+ *
+ * Unlike PDF417 decoding, OCR always returns *some* text even from an irrelevant
+ * frame, so "OCR succeeded" can't be the stopping condition. Stops once
+ * `registrationNumber` or `vin` is non-null -- the two most identifying,
+ * structurally-checkable fields -- rather than requiring full
+ * `validation.isValid`, which would be too strict for a single handheld-camera
+ * frame. Analysis frames are typically downscaled for performance, so OCR accuracy
+ * here is lower than a full-resolution still photo; adding a real `ImageCapture`
+ * use case for a higher-quality final frame is out of scope here, same boundary
+ * `PDF417ScanSession` draws for barcode scanning.
+ */
+@ExperimentalGetImage
+class VehicleRegistrationScanSession(private val reactContext: ReactApplicationContext) {
+
+  private val ocrProcessor = OCRProcessor()
+  private val executor = Executors.newSingleThreadExecutor()
+  private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+  private val finished = AtomicBoolean(false)
+  private var cameraProvider: ProcessCameraProvider? = null
+
+  fun start(timeoutMs: Long, onResult: (VehicleRegistrationResult?) -> Unit) {
+    val lifecycleOwner = reactContext.currentActivity as? LifecycleOwner
+    if (lifecycleOwner == null) {
+      onResult(null)
+      return
+    }
+
+    val timeoutHandler = Handler(Looper.getMainLooper())
+
+    fun finish(result: VehicleRegistrationResult?) {
+      if (!finished.compareAndSet(false, true)) return
+      timeoutHandler.removeCallbacksAndMessages(null)
+      cameraProvider?.unbindAll()
+      ocrProcessor.close()
+      scope.cancel()
+      executor.shutdown()
+      onResult(result)
+    }
+
+    timeoutHandler.postDelayed({ finish(null) }, timeoutMs)
+
+    val providerFuture = ProcessCameraProvider.getInstance(reactContext)
+    providerFuture.addListener(
+      {
+        if (finished.get()) return@addListener
+
+        val provider = providerFuture.get()
+        cameraProvider = provider
+
+        val analysis =
+          ImageAnalysis.Builder()
+            .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
+            .build()
+            .also {
+              it.setAnalyzer(executor) { image ->
+                if (finished.get()) {
+                  image.close()
+                  return@setAnalyzer
+                }
+                scope.launch {
+                  try {
+                    val ocrResult = ocrProcessor.processFrame(image)
+                    if (!finished.get()) {
+                      val parsed = VehicleRegistrationParser.parse(ocrResult.fullText)
+                      if (parsed.registrationNumber != null || parsed.vin != null) {
+                        finish(parsed)
+                      }
+                    }
+                  } catch (e: Exception) {
+                    // Swallow -- a single failed frame shouldn't end the scan session.
+                  } finally {
+                    image.close()
+                  }
+                }
+              }
+            }
+
+        try {
+          provider.unbindAll()
+          provider.bindToLifecycle(lifecycleOwner, CameraSelector.DEFAULT_BACK_CAMERA, analysis)
+        } catch (e: Exception) {
+          finish(null)
+        }
+      },
+      ContextCompat.getMainExecutor(reactContext),
+    )
+  }
+}

package/android/src/main/java/com/petrusreactnative/events/CapturedEvent.kt

@@ -0,0 +1,30 @@
+package com.petrusreactnative.events
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+import com.petrus.core.detection.DocumentCorners
+import com.petrusreactnative.events.DocumentDetectedEvent.Companion.toWritableMap
+
+/**
+ * Fires once when AutoCaptureManager's threshold (confidence > 0.9, stable 750ms) is
+ * crossed. Signal only -- carries the corners/confidence at the moment of capture, not
+ * a photo. Full-resolution capture is a later phase (see README).
+ */
+internal class CapturedEvent(
+  surfaceId: Int,
+  viewId: Int,
+  private val corners: DocumentCorners,
+  private val confidence: Float,
+  private val timestampMs: Long,
+) : Event<CapturedEvent>(surfaceId, viewId) {
+
+  override fun getEventName(): String = "topCaptured"
+
+  override fun getEventData(): WritableMap =
+    Arguments.createMap().apply {
+      putMap("corners", corners.toWritableMap())
+      putDouble("confidence", confidence.toDouble())
+      putDouble("timestamp", timestampMs.toDouble())
+    }
+}

package/android/src/main/java/com/petrusreactnative/events/DocumentDetectedEvent.kt

@@ -0,0 +1,49 @@
+package com.petrusreactnative.events
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+import com.petrus.core.detection.DetectionUpdate
+import com.petrus.core.detection.DocumentCorners
+import com.petrus.core.detection.Point2D
+
+/** Fabric event carrying a document detection update to JS. Already throttled by the caller. */
+internal class DocumentDetectedEvent(
+  surfaceId: Int,
+  viewId: Int,
+  private val update: DetectionUpdate,
+) : Event<DocumentDetectedEvent>(surfaceId, viewId) {
+
+  override fun getEventName(): String = "topDocumentDetected"
+
+  override fun getEventData(): WritableMap =
+    Arguments.createMap().apply {
+      putBoolean("detected", update.corners != null)
+      putBoolean("isStable", update.isStable)
+      putDouble("stableDurationMs", update.stableDurationMs.toDouble())
+      putDouble("confidence", update.confidence.toDouble())
+      // Always a well-formed object (zeroed when nothing's detected) rather than
+      // null/omitted -- keeps the codegen'd event schema a plain nested object, no
+      // optional/nullable object type. `detected` is the authoritative signal.
+      putMap("corners", (update.corners ?: DocumentCorners.EMPTY).toWritableMap())
+    }
+
+  companion object {
+    fun DocumentCorners.toWritableMap(): WritableMap =
+      Arguments.createMap().apply {
+        putMap("topLeft", topLeft.toWritableMap())
+        putMap("topRight", topRight.toWritableMap())
+        putMap("bottomRight", bottomRight.toWritableMap())
+        putMap("bottomLeft", bottomLeft.toWritableMap())
+        putInt("frameWidth", frameWidth)
+        putInt("frameHeight", frameHeight)
+        putInt("rotationDegrees", rotationDegrees)
+      }
+
+    fun Point2D.toWritableMap(): WritableMap =
+      Arguments.createMap().apply {
+        putDouble("x", x.toDouble())
+        putDouble("y", y.toDouble())
+      }
+  }
+}

package/android/src/main/java/com/petrusreactnative/events/FrameMetadataEvent.kt

@@ -0,0 +1,24 @@
+package com.petrusreactnative.events
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+import com.petrus.core.camera.FrameMetadata
+
+/** Fabric event carrying frame metadata to JS. Already throttled by the time this fires. */
+internal class FrameMetadataEvent(
+  surfaceId: Int,
+  viewId: Int,
+  private val metadata: FrameMetadata,
+) : Event<FrameMetadataEvent>(surfaceId, viewId) {
+
+  override fun getEventName(): String = "topFrameMetadata"
+
+  override fun getEventData(): WritableMap =
+    Arguments.createMap().apply {
+      putInt("width", metadata.width)
+      putInt("height", metadata.height)
+      putInt("rotation", metadata.rotationDegrees)
+      putDouble("timestamp", metadata.timestampMs.toDouble())
+    }
+}

package/android/src/main/java/com/petrusreactnative/mrz/PassportResultMapping.kt

@@ -0,0 +1,54 @@
+package com.petrusreactnative.mrz
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.petrus.vision.mrz.MRZDate
+import com.petrus.vision.mrz.MRZSex
+import com.petrus.vision.mrz.MRZValidator
+import com.petrus.vision.mrz.PassportResult
+
+/** Converts petrus-core's plain-Kotlin MRZ/passport model into RN bridge (WritableMap) types. */
+
+fun PassportResult.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putString("documentCode", documentCode)
+    putString("issuingCountry", issuingCountry)
+    putString("surname", surname)
+    putString("givenNames", givenNames)
+    putString("passportNumber", passportNumber)
+    putString("nationality", nationality)
+    if (dateOfBirth != null) putMap("dateOfBirth", dateOfBirth.toWritableMap()) else putNull("dateOfBirth")
+    putString("sex", sex.toWireValue())
+    if (dateOfExpiry != null) putMap("dateOfExpiry", dateOfExpiry.toWritableMap()) else putNull("dateOfExpiry")
+    if (personalNumber != null) putString("personalNumber", personalNumber) else putNull("personalNumber")
+    putMap("validation", validation.toWritableMap())
+    putArray("parseWarnings", parseWarnings.toWritableStringArray())
+  }
+
+private fun MRZDate.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putInt("year", year)
+    putInt("month", month)
+    putInt("day", day)
+    putInt("twoDigitYear", twoDigitYear)
+  }
+
+private fun MRZSex.toWireValue(): String =
+  when (this) {
+    MRZSex.MALE -> "male"
+    MRZSex.FEMALE -> "female"
+    MRZSex.UNSPECIFIED -> "unspecified"
+  }
+
+private fun MRZValidator.ValidationResult.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putBoolean("isValid", isValid)
+    putBoolean("passportNumberCheckValid", passportNumberCheckValid)
+    putBoolean("dateOfBirthCheckValid", dateOfBirthCheckValid)
+    putBoolean("expiryDateCheckValid", expiryDateCheckValid)
+    putBoolean("personalNumberCheckValid", personalNumberCheckValid)
+    putBoolean("compositeCheckValid", compositeCheckValid)
+  }
+
+private fun List<String>.toWritableStringArray() =
+  Arguments.createArray().apply { forEach { pushString(it) } }

package/android/src/main/java/com/petrusreactnative/ocr/OCRResultMapping.kt

@@ -0,0 +1,52 @@
+package com.petrusreactnative.ocr
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import com.petrus.vision.ocr.OCRBlock
+import com.petrus.vision.ocr.OCRBoundingBox
+import com.petrus.vision.ocr.OCRLine
+import com.petrus.vision.ocr.OCRResult
+import com.petrus.vision.ocr.OCRWord
+
+/** Converts petrus-core's plain-Kotlin OCR model into RN bridge (WritableMap) types. */
+
+fun OCRResult.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putString("fullText", fullText)
+    putDouble("confidence", confidence.toDouble())
+    putArray("blocks", blocks.toWritableArray { it.toWritableMap() })
+  }
+
+private fun OCRBlock.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putString("text", text)
+    putMap("boundingBox", boundingBox.toWritableMap())
+    putArray("lines", lines.toWritableArray { it.toWritableMap() })
+  }
+
+private fun OCRLine.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putString("text", text)
+    putMap("boundingBox", boundingBox.toWritableMap())
+    putDouble("confidence", confidence.toDouble())
+    putArray("words", words.toWritableArray { it.toWritableMap() })
+  }
+
+private fun OCRWord.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putString("text", text)
+    putMap("boundingBox", boundingBox.toWritableMap())
+    putDouble("confidence", confidence.toDouble())
+  }
+
+private fun OCRBoundingBox.toWritableMap(): WritableMap =
+  Arguments.createMap().apply {
+    putInt("left", left)
+    putInt("top", top)
+    putInt("right", right)
+    putInt("bottom", bottom)
+  }
+
+private inline fun <T> List<T>.toWritableArray(transform: (T) -> WritableMap): WritableArray =
+  Arguments.createArray().apply { forEach { pushMap(transform(it)) } }