react-native-image-stitcher 0.5.0 → 0.6.0

package/android/src/main/java/io/imagestitcher/rn/IncrementalStitcher.kt

@@ -58,20 +58,20 @@ import java.util.concurrent.atomic.AtomicBoolean
  *
  * What the bridge exposes to JS:
  *   - start(options)        — spin up the engine
- *   - processFrameAtPath()  — feed a JPEG path + pose; engine returns
- *                             the same outcome enum iOS emits as events
  *   - finalize(options)     — write the final panorama and reset
  *   - cancel()              — abort without producing output
  *   - getState()            — pull the latest state on demand
- *   - Event "IncrementalStateUpdate" emitted on every
- *     processFrameAtPath call
+ *   - refinePanorama()      — re-run the C++ stitcher over saved keyframes
+ *   - cleanupKeyframes()    — GC stale per-capture keyframe directories
+ *   - Event "IncrementalStateUpdate" emitted on every accepted frame
  *
- * What's missing for true live capture on Android:
- *   ARCore-backed live frame delivery.  The engine itself doesn't
- *   care where frames come from; today the only Android caller is
- *   the `processFrameAtPath` bridge method.  A follow-up will plumb
- *   ARCore's per-frame `Frame.acquireCameraImage()` directly into
- *   the engine the same way iOS uses ARSession.
+ * How frames reach the engine (no JS-driven path post-v0.6):
+ *   - AR mode: `RNSARCameraView` calls `ingestFromARCameraView(...)`
+ *     once per ARCore Frame from its scene-update listener.
+ *   - Non-AR mode: the vision-camera Frame Processor plugin
+ *     (`CvFlowGateFrameProcessor`) calls `consumeFrameFromPlugin(...)`
+ *     on the producer thread, gated by `frameProcessorIngestEnabled`.
+ *   The pre-v0.6 `processFrameAtPath` JS-driver entry point is gone.
  */
 class IncrementalStitcher(
     private val reactContext: ReactApplicationContext,
@@ -115,9 +115,9 @@ class IncrementalStitcher(
     // The MVP gate is frame-count-based ("accept every Nth frame
     // until cap").  iOS uses a pose-based gate (overlap < threshold)
     // — adding that here is a follow-up that needs ARCore-pose
-    // accumulation across processFrameAtPath calls.  For now, every
-    // N-th frame is good enough to validate end-to-end stitching
-    // parity.
+    // accumulation across `ingestFromARCameraView` calls.  For now,
+    // every N-th frame is good enough to validate end-to-end
+    // stitching parity.
     private var batchKeyframeMode: Boolean = false
     private val batchKeyframePaths: MutableList<String> = mutableListOf()
     private var batchKeyframeFrameCounter: Int = 0
@@ -217,9 +217,10 @@ class IncrementalStitcher(
 
     /// 2026-05-22 (audit F5) — Frame counter for the flowEvalEveryNFrames
     /// throttle.  Incremented on every per-frame entry point
-    /// (ingestFromARCameraView for AR, processFrameAtPath for non-AR);
-    /// gate evaluation only runs when (counter - 1) % evalCadence == 0
-    /// so frame #1 always evaluates regardless of cadence.  iOS parity:
+    /// (`ingestFromARCameraView` for AR mode, `consumeFrameFromPlugin`
+    /// for non-AR Frame Processor mode); gate evaluation only runs when
+    /// (counter - 1) % evalCadence == 0 so frame #1 always evaluates
+    /// regardless of cadence.  iOS parity:
     /// IncrementalStitcher.swift:2459-2471 (`consumeFrameCounter`).
     /// Reset to 0 on each `start()` call.
     private var consumeFrameCounter: Long = 0L
@@ -229,22 +230,23 @@ class IncrementalStitcher(
     /// F8.4 — gate for `consumeFrameFromPlugin` (the vision-camera
     /// Frame Processor producer-thread entry point on Android).
     /// TRUE only when the current capture was started with
-    /// `frameSourceMode == "frameProcessor"`.  In other modes
-    /// (especially the legacy `"jsDriver"` path that feeds via
-    /// `processFrameAtPath`), the plugin would double-feed the
-    /// engine — bytes from the producer thread + JPEG paths from
-    /// the JS interval, racing on the same workScope serial
-    /// dispatcher — so we drop the producer-thread call.
+    /// `frameSourceMode == "frameProcessor"`.  In AR mode
+    /// (`frameSourceMode == "arSession"`) the plugin would double-feed
+    /// the engine alongside `ingestFromARCameraView` — bytes from the
+    /// producer thread + bytes from the ARCore Frame listener, racing
+    /// on the same workScope serial dispatcher — so we drop the
+    /// producer-thread call.
     ///
     /// AtomicBoolean: producer thread reads lock-free, JS thread
     /// (start/cancel/finalize) writes via `set()`/`compareAndSet()`.
     /// Mirror of iOS' `frameProcessorIngestEnabled` ivar.
     private val frameProcessorIngestEnabled = AtomicBoolean(false)
-    /// Critic #5 fix: serial dispatcher so concurrent
-    /// processFrameAtPath() calls can't race on the engine's canvas.
-    /// `limitedParallelism(1)` guarantees one-at-a-time execution
-    /// while still backing onto the Default pool — matches iOS'
-    /// `workQueue` (DispatchQueue.serial).
+    /// Critic #5 fix: serial dispatcher so concurrent per-frame
+    /// ingest calls (today: `ingestFromARCameraView` in AR mode,
+    /// `consumeFrameFromPlugin` in frame-processor mode) can't race
+    /// on the engine's canvas.  `limitedParallelism(1)` guarantees
+    /// one-at-a-time execution while still backing onto the Default
+    /// pool — matches iOS' `workQueue` (DispatchQueue.serial).
     @OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)
     private val workScope = CoroutineScope(Dispatchers.Default.limitedParallelism(1))
 
@@ -275,17 +277,6 @@ class IncrementalStitcher(
     /// on start/stop so the view feeds frames only during a capture.
     @Volatile private var arCameraViewRef: RNSARCameraView? = null
 
-    /// 2026-05-21 (v0.3) — public-to-the-view-file getter so
-    /// `RNSARCameraView.forwardToIncremental` can ask whether the
-    /// currently-running engine is the batch-keyframe path (v0.3
-    /// Y-plane pixel-data flow) or the legacy hybrid/firstwins live
-    /// engine (which still needs a per-frame JPEG path).  Used to
-    /// elide the eager JPEG encode for batchKeyframe mode (the
-    /// production Camera component's path); the legacy live engine
-    /// still pays the per-frame JPEG cost.
-    internal val isBatchKeyframeMode: Boolean
-        get() = batchKeyframeMode
-
     init {
         // Static back-pointer so `RNSARCameraView` can call into
         // the singleton-style bridge module without a DI dance.  RN
@@ -327,11 +318,16 @@ class IncrementalStitcher(
             // F8.4 — frameSourceMode honoured on Android.  Pre-F8.4,
             // Android ignored this option (only iOS interpreted it).
             // Now `"frameProcessor"` unlocks `consumeFrameFromPlugin`'s
-            // producer-thread ingest path; everything else (the
-            // implicit default + the legacy `"jsDriver"`) keeps the
-            // ingest path dormant so the existing `processFrameAtPath`
-            // / ARCore paths run unmodified.
-            val frameSourceMode = options.getString("frameSourceMode") ?: "jsDriver"
+            // producer-thread ingest path; `"arSession"` (the default)
+            // keeps it dormant so the ARCore-driven
+            // `ingestFromARCameraView` path runs unmodified.
+            // Default to "arSession" for parity with iOS — pre-v0.6 this
+            // defaulted to "jsDriver", but that mode (the JS-driver
+            // processFrameAtPath path) was removed in v0.6.  Raw
+            // NativeModules callers that omit `frameSourceMode` get the
+            // AR-mode behaviour (the production <Camera> always sets
+            // 'arSession' explicitly for AR captures anyway).
+            val frameSourceMode = options.getString("frameSourceMode") ?: "arSession"
             frameProcessorIngestEnabled.set(frameSourceMode == "frameProcessor")
             val rotation = options.getIntOrDefault("frameRotationDegrees", 90)
             val composeW = options.getIntOrDefault("composeWidth",  960)
@@ -585,14 +581,6 @@ class IncrementalStitcher(
         }
     }
 
-    /**
-     * Feed one frame at a JPEG path into the engine.  Pose inputs
-     * drive the same FoV-overlap gate as iOS.  When a pose source
-     * isn't available pass yaw=0, pitch=0, fovHorizDegrees=0 — the
-     * engine treats fov<=0 as a sentinel for "no intrinsics" and
-     * substitutes a 65° default, so frames will still be processed,
-     * just less gated.
-     */
     /**
      * Copy a (non-persistent) source JPEG to a persistent per-keyframe
      * path under the React context's cache dir.  The ARCameraView's
@@ -614,67 +602,6 @@ class IncrementalStitcher(
      * for a Phase 3 follow-up; this MVP is just enough to make
      * batch-keyframe work end-to-end on Android.
      */
-    /**
-     * 2026-05-21 (v0.3) — JPEG-to-grayscale decode for the JS-driver
-     * (non-AR) keyframe-gate path.  Used by the batch-keyframe branch
-     * of processFrameAtPath to feed the C++ KeyframeGate with real
-     * pixel data so its Flow strategy actually runs (pre-0.3 the
-     * non-AR call was `evaluate(pose, null)` which silently fell back
-     * to the Pose strategy because no pixel data was supplied).
-     *
-     * Uses OpenCV's Imgcodecs.imread with IMREAD_GRAYSCALE, which
-     * decodes the JPEG straight into a single-channel CV_8UC1 Mat —
-     * faster than BitmapFactory + manual luma loop (~10-20 ms here
-     * vs ~100+ ms in interpreted Kotlin for a 1920×1080 image).
-     *
-     * The non-AR snapshot cadence is ~4 FPS so the per-call cost is
-     * well under the inter-snapshot interval.  v0.4 will replace
-     * this code path entirely by moving non-AR capture to
-     * vision-camera's Frame Processor API (which delivers raw
-     * pixels directly with no JPEG roundtrip).  Tracked at issue #11.
-     *
-     * Returns null when the decode fails (corrupt JPEG, OOM, etc.);
-     * caller is expected to fall back to the pose-only evaluate
-     * path so the capture doesn't lock up.
-     */
-    private data class GrayscaleFrame(
-        val bytes: ByteArray,
-        val width: Int,
-        val height: Int,
-        val stride: Int,
-    )
-
-    private fun decodeJpegToGrayscale(path: String): GrayscaleFrame? {
-        val mat = Imgcodecs.imread(path, Imgcodecs.IMREAD_GRAYSCALE)
-        if (mat.empty()) {
-            android.util.Log.w(
-                "IncrementalStitcher",
-                "decodeJpegToGrayscale: imread returned empty Mat for $path"
-            )
-            return null
-        }
-        return try {
-            val width = mat.cols()
-            val height = mat.rows()
-            // step1() returns bytes-per-row for a CV_8UC1 Mat.  For a
-            // continuous Mat from imread (no ROI) stride == width.
-            val stride = mat.step1().toInt()
-            val size = stride * height
-            val bytes = ByteArray(size)
-            mat.get(0, 0, bytes)
-            GrayscaleFrame(bytes, width, height, stride)
-        } catch (e: Exception) {
-            android.util.Log.w(
-                "IncrementalStitcher",
-                "decodeJpegToGrayscale: failed to copy Mat bytes for $path: ${e.message}",
-                e,
-            )
-            null
-        } finally {
-            mat.release()
-        }
-    }
-
     private fun copyKeyframeToStore(srcPath: String): String? {
         // V16 Phase 2 (Android Fix-1) — write into the per-session
         // subdir created by start().  If start() didn't run (defensive
@@ -708,8 +635,8 @@ class IncrementalStitcher(
     // ── V16 Phase 1 → P3-F migration note ────────────────────────
     // The frame-counter placeholder gate `handleBatchKeyframeFrame`
     // that lived here has been REMOVED.  Both the AR-driven path
-    // (ingestFromARCameraView) and the vision-camera fallback path
-    // (processFrameAtPath) now route through the shared-C++
+    // (`ingestFromARCameraView`) and the Frame Processor path
+    // (`consumeFrameFromPlugin`) now route through the shared-C++
     // `KeyframeGate` (cpp/keyframe_gate.{hpp,cpp}) — same algorithm
     // iOS has used since the V16 ship.  See
     // `private val keyframeGate = KeyframeGate()` above for the
@@ -722,204 +649,6 @@ class IncrementalStitcher(
     // we ever add a "force every Nth frame regardless of overlap"
     // override.
 
-    @ReactMethod
-    fun processFrameAtPath(options: ReadableMap, promise: Promise) {
-        val hybrid = this.engine
-        val firstwins = this.firstwinsEngine
-        // batch-keyframe mode runs without a live engine — handle it
-        // up-front before the null-check rejects.
-        //
-        // P3-F: this path uses the same shared-C++ KeyframeGate as
-        // the AR view path, but with translation = 0 (gyro-derived
-        // poses have only rotation, not position).  The gate's
-        // internal logic detects the missing plane and uses the
-        // camera-forward angular-delta fallback automatically.
-        if (batchKeyframeMode) {
-            val path = options.getString("path")
-                ?: return promise.reject("invalid-options", "path required")
-            val pose = RNSARFramePose(
-                tx = options.getDoubleOrDefault("tx", 0.0) ?: 0.0,
-                ty = options.getDoubleOrDefault("ty", 0.0) ?: 0.0,
-                tz = options.getDoubleOrDefault("tz", 0.0) ?: 0.0,
-                qx = options.getDoubleOrDefault("qx", 0.0) ?: 0.0,
-                qy = options.getDoubleOrDefault("qy", 0.0) ?: 0.0,
-                qz = options.getDoubleOrDefault("qz", 0.0) ?: 0.0,
-                qw = options.getDoubleOrDefault("qw", 1.0) ?: 1.0,
-                fx = options.getDoubleOrDefault("fx", 1000.0) ?: 1000.0,
-                fy = options.getDoubleOrDefault("fy", 1000.0) ?: 1000.0,
-                cx = options.getDoubleOrDefault("cx", 540.0) ?: 540.0,
-                cy = options.getDoubleOrDefault("cy", 960.0) ?: 960.0,
-                imageWidth = options.getIntOrDefault("imageWidth", 1080),
-                imageHeight = options.getIntOrDefault("imageHeight", 1920),
-                timestampMs = 0.0,
-                trackingState = RNSARSession.TRACKING_TRACKING,
-            )
-            // Vision-camera path: no plane available (gyro can't fit
-            // planes).  Pass null → C++ skips the plane-overlap math.
-            //
-            // 2026-05-21 (v0.3) — pixel-aware Flow-strategy evaluation.
-            // The JS driver hands us a JPEG file path; we decode it to
-            // grayscale here so the C++ gate actually runs sparse-flow
-            // novelty (pre-0.3 the call was `evaluate(pose, null)` and
-            // the C++ side silently fell back to Pose strategy because
-            // no pixel data was supplied — same bug as Android AR
-            // mode, both fixed in v0.3).  BitmapFactory + manual luma
-            // is fine here — non-AR snapshot cadence is ~4 FPS, the
-            // ~15-30 ms JPEG-decode-to-grayscale per call is well
-            // under the inter-snapshot interval.  (v0.4 will move
-            // non-AR to vision-camera's Frame Processor API, at which
-            // point the JPEG step goes away entirely.  Tracked at
-            // https://github.com/bhargavkanda/react-native-image-stitcher/issues/11)
-            val gray = decodeJpegToGrayscale(path)
-            val decision = if (gray != null) {
-                keyframeGate.evaluateWithFrame(
-                    pose, null,
-                    gray.bytes, gray.width, gray.height, gray.stride,
-                )
-            } else {
-                // JPEG decode failed (corrupt file? OOM?).  Fall back
-                // to pose-only path so the capture doesn't lock up;
-                // this matches the C++ side's own defensive fallback
-                // for null grayData.
-                keyframeGate.evaluate(pose, null)
-            }
-            val result = Arguments.createMap()
-            // Outcome mapping for iOS-parity JS contract:
-            //   1 = accepted, 2 = rejected (gate), 3 = rejected (cap).
-            // C++ enum → outcome int:
-            val outcome = when {
-                decision.accept -> 1
-                decision.reason == "max-reached" -> 3
-                else -> 2
-            }
-            result.putInt("outcome", outcome)
-            if (!decision.accept) {
-                // 2026-05-22 (audit follow-up) — emit reject-state on
-                // the non-AR JS-driver path too so the debug overlay
-                // sees overlap % update on every snapshot (~4 Hz).
-                // Same rationale as the AR path's reject emission
-                // above; iOS parity.
-                emitBatchKeyframeRejectState(
-                    decision = decision,
-                    keyframeCount = batchKeyframePaths.size,
-                    keyframeMax = keyframeGate.maxCount,
-                    isLandscape = pose.imageWidth >= pose.imageHeight,
-                )
-            }
-            if (decision.accept) {
-                batchKeyframePaths.add(path)  // vision-camera path
-                                              // gives us a unique
-                                              // per-snapshot file
-                                              // already (no copy
-                                              // needed).
-                // Emit the same state event the AR path emits so
-                // the JS LiveFrameStrip + "Keyframes n/max" pill
-                // work identically on the vision-camera fallback
-                // path.
-                emitBatchKeyframeAcceptedState(
-                    thumbnailPath = path,
-                    keyframeIndex = batchKeyframePaths.size - 1,
-                    keyframeCount = batchKeyframePaths.size,
-                    keyframeMax = keyframeGate.maxCount,
-                    isLandscape = pose.imageWidth >= pose.imageHeight,
-                    newContentFraction = decision.newContentFraction,
-                )
-            }
-            result.putInt("acceptedCount", batchKeyframePaths.size)
-            promise.resolve(result)
-            return
-        }
-        if (hybrid == null && firstwins == null) {
-            return promise.reject(
-                "incremental-not-running",
-                "Call start() before processFrameAtPath().",
-            )
-        }
-        val path = options.getString("path")
-            ?: return promise.reject("invalid-options", "path required")
-        val yaw = options.getDoubleOrDefault("yaw", 0.0)
-        val pitch = options.getDoubleOrDefault("pitch", 0.0)
-        val fovH = options.getDoubleOrDefault("fovHorizDegrees", 65.0)
-        val fovV = options.getDoubleOrDefault("fovVertDegrees", 50.0)
-        // V6 pose-driven params.  Defaults removed per critic finding
-        // #3: previously qw=1.0 default meant frames without explicit
-        // quaternion produced an identity rotation, and EVERY
-        // subsequent frame had R_rel = R_first^T (constant), so
-        // strip placement never advanced and `acceptedCount` froze
-        // at 1 after the first frame.  Now every quaternion field is
-        // required; missing → reject as RejectedAlignmentLost so the
-        // gyro driver upstream notices instantly.
-        if (!options.hasKey("qx") || !options.hasKey("qy")
-            || !options.hasKey("qz") || !options.hasKey("qw")) {
-            return promise.reject(
-                "invalid-options",
-                "qx/qy/qz/qw all required (no identity-quaternion fallback)",
-            )
-        }
-        val qx = options.getDouble("qx")
-        val qy = options.getDouble("qy")
-        val qz = options.getDouble("qz")
-        val qw = options.getDouble("qw")
-        val fx = options.getDoubleOrDefault("fx", 0.0)
-        val fy = options.getDoubleOrDefault("fy", 0.0)
-        val cx = options.getDoubleOrDefault("cx", 0.0)
-        val cy = options.getDoubleOrDefault("cy", 0.0)
-        val imageWidth = options.getIntOrDefault("imageWidth", 0)
-        val imageHeight = options.getIntOrDefault("imageHeight", 0)
-        val trackingPoor = options.getBooleanOrDefault("trackingPoor", false)
-
-        workScope.launch {
-            // Critic #4 fix: re-check isRunning synchronously here in
-            // case finalize/cancel ran on the JS thread between the
-            // null-check above and this dispatch landing.  Skip the
-            // ingest if we're no longer running — matches iOS' V12.1
-            // pattern (synchronous-stop + worker re-check).
-            if (!isRunning.get()) {
-                promise.resolve(Arguments.createMap().apply { putInt("outcome", -1) })
-                return@launch
-            }
-            try {
-                val telemetry: FrameTelemetry
-                val state: WritableMap?
-                val accepted: Int
-                if (firstwins != null) {
-                    telemetry = firstwins.addFrameAtPath(
-                        path = path,
-                        qx = qx, qy = qy, qz = qz, qw = qw,
-                        fx = fx, fy = fy, cx = cx, cy = cy,
-                        imageWidth = imageWidth, imageHeight = imageHeight,
-                        yaw = yaw, pitch = pitch,
-                        fovHorizDegrees = fovH, fovVertDegrees = fovV,
-                        trackingPoor = trackingPoor,
-                    )
-                    state = firstwins.snapshotIfDue(telemetry)
-                    accepted = firstwins.acceptedCount
-                } else {
-                    telemetry = hybrid!!.addFrameAtPath(
-                        path = path,
-                        qx = qx, qy = qy, qz = qz, qw = qw,
-                        fx = fx, fy = fy, cx = cx, cy = cy,
-                        imageWidth = imageWidth, imageHeight = imageHeight,
-                        yaw = yaw, pitch = pitch,
-                        fovHorizDegrees = fovH, fovVertDegrees = fovV,
-                        trackingPoor = trackingPoor,
-                    )
-                    state = hybrid.snapshotIfDue(telemetry)
-                    accepted = hybrid.acceptedCount
-                }
-                emitState(state)
-                val result = Arguments.createMap()
-                result.putInt("outcome", telemetry.outcome.ordinal)
-                result.putDouble("confidence", telemetry.confidence)
-                result.putDouble("overlapPercent", telemetry.overlapPercent)
-                result.putDouble("processingMs", telemetry.processingMs)
-                result.putInt("acceptedCount", accepted)
-                promise.resolve(result)
-            } catch (t: Throwable) {
-                promise.reject("incremental-process-failed", t.message, t)
-            }
-        }
-    }
 
     @ReactMethod
     fun finalize(options: ReadableMap, promise: Promise) {
@@ -963,9 +692,10 @@ class IncrementalStitcher(
         // frames slip into the engine while we serialize the canvas.
         arCameraViewRef?.setIncrementalIngestionActive(false)
         // Critic #4 fix: synchronously flip isRunning=false BEFORE
-        // dispatching the finalize body, so any in-flight
-        // processFrameAtPath workers that are about to launch will
-        // bail at the re-check (see processFrameAtPath above).
+        // dispatching the finalize body, so any in-flight per-frame
+        // ingest workers about to launch on workScope (today:
+        // `ingestFromARCameraView` or `consumeFrameFromPlugin`) bail
+        // at the re-check inside their workScope.launch blocks.
         // Matches iOS V12.1 fix.
         isRunning.set(false)
         frameProcessorIngestEnabled.set(false)  // F8.4 — cut producer-thread ingest at finalize
@@ -1258,10 +988,29 @@ class IncrementalStitcher(
         // is false (the legacy hybrid/firstwins live-engine path,
         // which feeds JPEG paths into addFrameAtPath for each ARCore
         // frame).  Pass null when batchKeyframeMode is true; the
-        // batch path uses `grayData` + `onAccept` instead.  Callers
-        // can check `isBatchKeyframeMode` to elide the per-frame
-        // JPEG encode for the batch path.
+        // batch path uses `grayData` + `onAccept` instead.  Modern
+        // callers prefer `nv21PixelData` below — `legacyJpegPath` is
+        // kept only as a defensive fallback for older call sites
+        // that have not yet been migrated.
         legacyJpegPath: String? = null,
+        // F8.6 — pixel-data path for live engines.  When supplied
+        // (and `batchKeyframeMode == false`), takes precedence over
+        // `legacyJpegPath`: the live engine ingests via
+        // `addFramePixelData` (NV21 → BGR Mat in-process) instead of
+        // `addFrameAtPath` (JPEG decode round-trip).  Saves ~30-50 ms
+        // per accepted frame on a mid-tier device.  Pass null to use
+        // the legacy JPEG path.
+        //
+        // OWNERSHIP: the engine retains a reference to `nv21PixelData`
+        // until `workScope`'s coroutine consumes it (~50 ms later).
+        // Callers MUST treat the array as transferred — do not
+        // mutate it or return it to a buffer pool after calling
+        // this method.  If a caller needs to recycle the buffer,
+        // pass `.copyOf()` (currently no caller does — the F8.4
+        // Frame Processor plugin allocates a fresh array per frame).
+        nv21PixelData: ByteArray? = null,
+        nv21PixelWidth: Int = 0,
+        nv21PixelHeight: Int = 0,
     ) {
         // ── V16 batch-keyframe: AR-driven path ─────────────────────
         //
@@ -1439,40 +1188,78 @@ class IncrementalStitcher(
         // we only get here when batchKeyframeMode == false.  Caller
         // (RNSARCameraView) was expected to supply legacyJpegPath in
         // that case — defensively drop the frame if it didn't.
-        val path = legacyJpegPath ?: run {
+        // F8.6 — prefer the pixel-data path when the caller supplied
+        // NV21 bytes (Frame Processor / refactored ARCore path),
+        // otherwise fall back to legacyJpegPath (un-migrated ARCore
+        // path).  At least one of them must be present; drop the
+        // frame defensively otherwise.
+        val hasPixelData = nv21PixelData != null
+            && nv21PixelWidth > 0
+            && nv21PixelHeight > 0
+        val path = if (hasPixelData) null else legacyJpegPath ?: run {
             android.util.Log.w(
                 "IncrementalStitcher",
                 "ingestFromARCameraView legacy: batchKeyframeMode=false " +
-                    "but legacyJpegPath is null — dropping frame.  " +
-                    "Caller should have encoded a JPEG when " +
-                    "isBatchKeyframeMode == false.",
+                    "but both legacyJpegPath and nv21PixelData are null — " +
+                    "dropping frame.  Caller must supply NV21 pixel data " +
+                    "(preferred) or a JPEG path for the live engine path.",
             )
             return
         }
         workScope.launch {
             val state: WritableMap? = if (firstwins != null) {
-                val tele = firstwins.addFrameAtPath(
-                    path = path,
-                    qx = qx, qy = qy, qz = qz, qw = qw,
-                    fx = fx, fy = fy, cx = cx, cy = cy,
-                    imageWidth = imageWidth, imageHeight = imageHeight,
-                    yaw = yaw, pitch = pitch,
-                    fovHorizDegrees = fovHorizDegrees,
-                    fovVertDegrees = fovVertDegrees,
-                    trackingPoor = trackingPoor,
-                )
+                val tele = if (hasPixelData) {
+                    firstwins.addFramePixelData(
+                        nv21 = nv21PixelData!!,
+                        nv21Width = nv21PixelWidth,
+                        nv21Height = nv21PixelHeight,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                } else {
+                    firstwins.addFrameAtPath(
+                        path = path!!,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                }
                 firstwins.snapshotIfDue(tele)
             } else {
-                val tele = hybrid!!.addFrameAtPath(
-                    path = path,
-                    qx = qx, qy = qy, qz = qz, qw = qw,
-                    fx = fx, fy = fy, cx = cx, cy = cy,
-                    imageWidth = imageWidth, imageHeight = imageHeight,
-                    yaw = yaw, pitch = pitch,
-                    fovHorizDegrees = fovHorizDegrees,
-                    fovVertDegrees = fovVertDegrees,
-                    trackingPoor = trackingPoor,
-                )
+                val tele = if (hasPixelData) {
+                    hybrid!!.addFramePixelData(
+                        nv21 = nv21PixelData!!,
+                        nv21Width = nv21PixelWidth,
+                        nv21Height = nv21PixelHeight,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                } else {
+                    hybrid!!.addFrameAtPath(
+                        path = path!!,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                }
                 hybrid.snapshotIfDue(tele)
             }
             emitState(state)
@@ -1534,23 +1321,36 @@ class IncrementalStitcher(
     ) {
         // F8.4 — drop the call unless this capture was started in
         // frameProcessor mode.  Otherwise the plugin would double-
-        // feed the engine alongside the legacy jsDriver /
-        // processFrameAtPath path.  See the flag's declaration
+        // feed the engine alongside the AR-mode
+        // `ingestFromARCameraView` path.  See the flag's declaration
         // for the full reasoning.  Mirrors iOS H1.
         if (!frameProcessorIngestEnabled.get()) return
 
-        val width = image.width
-        val height = image.height
-        val yPlane = image.planes[0]
-        val yRowStride = yPlane.rowStride
-
-        // Read Y plane bytes.  ByteBuffer.get() advances position;
-        // copy into our own ByteArray so the engine's downstream
-        // workScope can safely outlive this method (the Image
-        // closes after callback returns, but we've already copied).
-        val yBuffer = yPlane.buffer
-        val yBytes = ByteArray(yBuffer.remaining())
-        yBuffer.get(yBytes)
+        // F8.6 — pack the full NV21 (Y + interleaved VU) once,
+        // then reuse it for BOTH the gate's Y-plane read AND the
+        // live engine's pixel-data ingest.  Previously the plugin
+        // only extracted Y; the live engine then had to JPEG-decode
+        // a separately-encoded path to recover BGR colour.  Now we
+        // skip both round-trips: the packed NV21 → BGR cvtColor
+        // inside `addFramePixelData` produces the BGR Mat directly.
+        //
+        // YuvImageConverter.packNV21 is stride-aware and densely
+        // repacks Y (so the gate's `grayStride = grayWidth = width`
+        // works), then interleaves VU per the standard NV21 layout
+        // [Y...][VU...].  Returns null only on degenerate Images
+        // (closed mid-callback or non-YUV format).
+        val packed = io.imagestitcher.rn.ar.YuvImageConverter.packNV21(image)
+            ?: return
+        val width = packed.width
+        val height = packed.height
+        val nv21Bytes = packed.nv21
+        // The gate reads `grayHeight` rows of `grayWidth` pixels
+        // at stride=width starting from offset 0.  That's exactly
+        // the Y plane region of nv21Bytes — the gate naturally
+        // stops before the UV bytes start.  No need to slice into
+        // a separate ByteArray.
+        val yBytes = nv21Bytes
+        val yRowStride = width
 
         // Compute derived params expected by the existing ingest
         // API.  Quaternion-to-yaw/pitch follows the same convention
@@ -1596,13 +1396,22 @@ class IncrementalStitcher(
             grayWidth = width,
             grayHeight = height,
             grayStride = yRowStride,
+            // F8.6 — pass the already-packed NV21 so the live
+            // engine branch (hybrid / firstwins) can ingest via
+            // `addFramePixelData` instead of JPEG-decoding a
+            // separately-written path.  Batch-keyframe mode
+            // ignores these (it uses `grayData` + `onAccept`).
+            nv21PixelData = nv21Bytes,
+            nv21PixelWidth = width,
+            nv21PixelHeight = height,
             onAccept = { targetPath ->
                 // Synchronous JPEG encode via the existing
                 // YuvImageConverter (also used by RNSARCameraView's
-                // ARCore path).  Handles both the NV21 conversion
-                // (stride / pixelStride aware) and the EXIF
-                // Orientation tag write so the JPEG displays upright
-                // in the UI thumbnail strip + any RN Image consumer.
+                // ARCore path).  Reuses the NV21 already packed at
+                // the top of `consumeFrameFromPlugin` — F8.6 saves
+                // a duplicate packNV21 call here (the previous
+                // version repacked the live `image` inside the
+                // lambda).
                 //
                 // EXIF rotation is BAKED-AS-METADATA, not pixel-
                 // rotated.  cv::imread in the stitcher ignores EXIF
@@ -1614,32 +1423,20 @@ class IncrementalStitcher(
                 // Returning `true` tells the engine the keyframe was
                 // persisted; `false` tells it to drop the accept.
                 try {
-                    val packed = YuvImageConverter.packNV21(image)
-                        ?: run {
-                            android.util.Log.w(
-                                "IncrementalStitcher",
-                                "consumeFrameFromPlugin: packNV21 returned null for $targetPath",
-                            )
-                            return@run null
-                        }
-                    if (packed == null) {
-                        false
-                    } else {
-                        val displayRotation = when (sensorRotationDegrees) {
-                            0   -> android.view.Surface.ROTATION_90
-                            90  -> android.view.Surface.ROTATION_0
-                            180 -> android.view.Surface.ROTATION_270
-                            270 -> android.view.Surface.ROTATION_180
-                            else -> android.view.Surface.ROTATION_0
-                        }
-                        val outPath = YuvImageConverter.encodeJpegFromNV21(
-                            packed,
-                            targetPath,
-                            jpegQuality = 80,
-                            displayRotation = displayRotation,
-                        )
-                        outPath != null
+                    val displayRotation = when (sensorRotationDegrees) {
+                        0   -> android.view.Surface.ROTATION_90
+                        90  -> android.view.Surface.ROTATION_0
+                        180 -> android.view.Surface.ROTATION_270
+                        270 -> android.view.Surface.ROTATION_180
+                        else -> android.view.Surface.ROTATION_0
                     }
+                    val outPath = YuvImageConverter.encodeJpegFromNV21(
+                        packed,
+                        targetPath,
+                        jpegQuality = 80,
+                        displayRotation = displayRotation,
+                    )
+                    outPath != null
                 } catch (e: Throwable) {
                     android.util.Log.w(
                         "IncrementalStitcher",
@@ -2548,7 +2345,91 @@ internal class IncrementalEngine(
         // See iOS' equivalent fix for the architectural rationale.
         val frame = downsampleToCompose(srcRaw)
         if (frame !== srcRaw) srcRaw.release()
+        return addFrameMat(
+            frame,
+            qx, qy, qz, qw,
+            fx, fy, cx, cy,
+            imageWidth, imageHeight,
+            yaw, pitch,
+            fovHorizDegrees, fovVertDegrees,
+            t0,
+        )
+    }
 
+    /**
+     * F8.6 — pixel-data twin of [addFrameAtPath].  Accepts the
+     * camera frame as an NV21 byte buffer instead of a JPEG file
+     * path; skips the JPEG decode round-trip.  See
+     * `IncrementalFirstwinsEngine.addFramePixelData` for the
+     * sibling implementation rationale.
+     */
+    fun addFramePixelData(
+        nv21: ByteArray,
+        nv21Width: Int,
+        nv21Height: Int,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        yaw: Double, pitch: Double,
+        fovHorizDegrees: Double, fovVertDegrees: Double,
+        trackingPoor: Boolean,
+    ): FrameTelemetry {
+        val t0 = System.nanoTime()
+        if (trackingPoor) {
+            return FrameTelemetry(
+                FrameOutcome.SkippedTrackingPoor, -1.0, 0, 0.0, 0.0,
+                msSince(t0),
+            )
+        }
+        // F8.6 IS-1 — length guard; see
+        // `IncrementalFirstwinsEngine.addFramePixelData` for the
+        // failure-mode rationale.
+        val expectedBytes = nv21Width * nv21Height * 3 / 2
+        require(nv21.size >= expectedBytes) {
+            "addFramePixelData: nv21 buffer too small " +
+                "(${nv21.size} bytes < $expectedBytes for " +
+                "${nv21Width}x${nv21Height})"
+        }
+        val yuv = Mat(nv21Height + nv21Height / 2, nv21Width, CvType.CV_8UC1)
+        yuv.put(0, 0, nv21)
+        val srcRaw = Mat()
+        Imgproc.cvtColor(yuv, srcRaw, Imgproc.COLOR_YUV2BGR_NV21)
+        yuv.release()
+        if (srcRaw.empty()) {
+            return FrameTelemetry(
+                FrameOutcome.SkippedTrackingPoor, -1.0, 0, 0.0, 0.0,
+                msSince(t0),
+            )
+        }
+        val frame = downsampleToCompose(srcRaw)
+        if (frame !== srcRaw) srcRaw.release()
+        return addFrameMat(
+            frame,
+            qx, qy, qz, qw,
+            fx, fy, cx, cy,
+            imageWidth, imageHeight,
+            yaw, pitch,
+            fovHorizDegrees, fovVertDegrees,
+            t0,
+        )
+    }
+
+    /**
+     * F8.6 — the body extracted from [addFrameAtPath].  Takes a
+     * BGR `Mat` (already downsampled to compose dims) and runs the
+     * pose-driven homography paste pipeline.  Behaviour is
+     * identical to the pre-F8.6 `addFrameAtPath` — the body is a
+     * verbatim move.
+     */
+    private fun addFrameMat(
+        frame: Mat,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        yaw: Double, pitch: Double,
+        fovHorizDegrees: Double, fovVertDegrees: Double,
+        t0: Long,
+    ): FrameTelemetry {
         // Build R_new from quaternion.
         val rNew = quaternionToRotationMat(qx, qy, qz, qw)