react-native-image-stitcher 0.14.1 → 0.15.0

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

@@ -96,15 +96,6 @@ class IncrementalStitcher(
     @ReactMethod
     fun removeListeners(count: Int) { /* no-op */ }
 
-    /// V7 hybrid engine — selected for engineMode == 'hybrid'.
-    private var engine: IncrementalEngine? = null
-    /// V12.7 firstwins engine — selected for any engineMode starting
-    /// with 'firstwins' (firstwins, firstwins-zoomed, firstwins-rectilinear).
-    /// Native engine is identical for firstwins and firstwins-zoomed
-    /// (the difference is JS-side viewport zoom only).  useRectilinear
-    /// is set for 'firstwins-rectilinear'.
-    private var firstwinsEngine: IncrementalFirstwinsEngine? = null
-
     // ── V16 batch-keyframe mode (Android parity with iOS' V16 Phase 1) ─
     //
     // Selected for engineMode == 'batch-keyframe'.  No live engine
@@ -112,15 +103,11 @@ class IncrementalStitcher(
     // and at finalize() time we hand them all to the JNI shim
     // (libimage_stitcher.so) for one-shot cv::Stitcher processing.
     //
-    // 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 `ingestFromARCameraView` calls.  For now,
-    // every N-th frame is good enough to validate end-to-end
-    // stitching parity.
+    // Accepted frames are selected by the shared C++ KeyframeGate
+    // (pose / flow / time strategies, configured in start()); the
+    // collected paths are handed to the JNI shim at finalize().
     private var batchKeyframeMode: Boolean = false
     private val batchKeyframePaths: MutableList<String> = mutableListOf()
-    private var batchKeyframeFrameCounter: Int = 0
     /// V16 Phase 2 (Android Fix-1) — per-capture-session subdirectory
     /// under `cacheDir` where this capture's batch-keyframe JPEGs are
     /// written.  Created on each batch-keyframe `start()` with a fresh
@@ -155,10 +142,6 @@ class IncrementalStitcher(
     /// Parity: matches iOS `OpenCVKeyframeCollector.sessionDir`
     /// (created with `Library/AppSupport/Captures/{NSUUID}/`).
     private var captureSessionDir: java.io.File? = null
-    /// Accept every Nth frame.  10 is the iOS default capture cadence
-    /// (5-6 keyframes over a ~2-3 second pan = roughly one every 10
-    /// frames at 30fps).
-    private var batchKeyframeAcceptStride: Int = 10
     /// Hard cap on keyframes to match iOS' default (V16 Phase 1's
     /// keyframeMaxCount=6).  Going higher inflates cv::Stitcher's
     /// MultiBandBlender memory; iOS hit OOM at 7+ on some scenes.
@@ -342,211 +325,164 @@ class IncrementalStitcher(
             // Critic #29: clamp snapshotEveryNAccepts to >= 1 so a
             // value of 0 doesn't mean "snapshot every frame forever".
             val snapN    = max(1, options.getIntOrDefault("snapshotEveryNAccepts", 1))
-            // V12.7 — engineMode now distinguishes 4 variants.  See
-            // src/stitching/incremental.ts for the full description.
-            // V16 added 'batch-keyframe' as a fifth variant: no live
-            // engine, frames are saved as JPEGs and handed to
-            // cv::Stitcher (via the JNI shim) at finalize.
-            val engineMode = options.getString("engine") ?: "hybrid"
-            // 2026-05-15 — Route 'slitscan*' engineModes to the same
-            // IncrementalFirstwinsEngine that handles 'firstwins*'.
-            // Per IncrementalFirstwinsEngine's docstring (lines 260,
-            // 431, 436, 672, 957): "Mirrors iOS' OpenCVSlitScanStitcher.mm
-            // exactly".  Before this change, 'slitscan' / 'slitscan-rotate'
-            // / 'slitscan-both' engineModes fell through to IncrementalEngine
-            // (the hybrid engine), producing identical output to picking
-            // 'hybrid' — silent platform divergence vs iOS.
-            //
-            // iOS-parity reference: IncrementalStitcher.swift:556
-            // computes `useFirstwinsClass = normalisedMode.hasPrefix("slitscan")`
-            // which routes BOTH 'slitscan-rotate' AND 'slitscan-both' AND
-            // the deprecated aliases to OpenCVFirstWinsCylindricalStitcher.
-            // We mirror that logic here so Android Settings → Engine
-            // dropdown actually toggles the underlying engine.
-            val isFirstwinsClass =
-                engineMode.startsWith("firstwins") ||
-                engineMode.startsWith("slitscan")
-            val isFirstwins = isFirstwinsClass    // legacy name kept
-                                                  // for the remainder of
-                                                  // start() — refactor to
-                                                  // isFirstwinsClass when
-                                                  // the engineMode taxonomy
-                                                  // is rationalised.
-            val useRectilinear =
-                engineMode == "firstwins-rectilinear" ||
-                engineMode == "slitscan-rotate"
-            val isBatchKeyframe = engineMode == "batch-keyframe"
+            // Engine selection.  The live engines (hybrid `IncrementalEngine`,
+            // firstwins / slitscan `IncrementalFirstwinsEngine`) were archived
+            // in the 2026-06 batch-keyframe cleanup -- the SDK now ships only
+            // 'batch-keyframe': no live engine; frames are saved as JPEGs and
+            // handed to cv::Stitcher (via the JNI shim) at finalize.  Any other
+            // engineMode is still accepted for backward compatibility but falls
+            // back to batch-keyframe with a deprecation log (mirrors iOS'
+            // IncrementalStitcher.start()).
+            val engineMode = options.getString("engine") ?: "batch-keyframe"
+            if (engineMode != "batch-keyframe") {
+                android.util.Log.w(
+                    "IncrementalStitcher",
+                    "[bridge] DEPRECATED engine '$engineMode' -- live engines " +
+                        "archived, using batch-keyframe",
+                )
+            }
 
             val configOverrides: ReadableMap? =
                 if (options.hasKey("config")) options.getMap("config") else null
 
-            if (isBatchKeyframe) {
-                // No live engine runs.  Reset the keyframe collector
-                // state.  Read knobs from `config` per the V16 Phase
-                // 1 plumbing pattern.
-                engine = null
-                firstwinsEngine = null
-                batchKeyframeMode = true
-                batchKeyframePaths.clear()
-                batchKeyframeFrameCounter = 0
-                // V16 Phase 2 (Android Fix-1) — fresh per-session subdir
-                // for this capture's keyframe JPEGs.  Replaces the
-                // V16-Phase-1 "rlis-keyframe-{N}.jpg in cacheDir"
-                // scheme that caused thumbnails from a previous capture
-                // to leak into the next one via RN's bitmap cache (see
-                // `captureSessionDir` declaration above for the full
-                // RCA).  Matches iOS' OpenCVKeyframeCollector behaviour.
-                captureSessionDir = java.io.File(
-                    reactContext.cacheDir,
-                    "rlis-capture-${java.util.UUID.randomUUID()}",
-                ).also { it.mkdirs() }
-                batchKeyframeMaxCount = configOverrides
-                    ?.getIntOrDefault("keyframeMaxCount", 6) ?: 6
-                batchWarperType = configOverrides?.getString("warperType")
-                    ?: "plane"
-                batchBlenderType = configOverrides?.getString("blenderType")
-                    ?: "multiband"
-                batchSeamFinderType = configOverrides?.getString("seamFinderType")
-                    ?: "graphcut"
-                batchUseInscribedRectCrop = configOverrides
-                    ?.getBooleanOrDefault("enableMaxInscribedRectCrop", false)
-                    ?: false
-                // 2026-05-14 — stitch-mode picker from JS Settings.
-                // Default 'auto'.  Validated against the closed set
-                // {auto, panorama, scans}; unknown values fall back
-                // to 'auto'.  Reset accumulated-pose state for the
-                // new capture so finalize() picks a fresh mode.
-                batchStitchMode = (configOverrides?.getString("stitchMode") ?: "auto")
-                    .let { if (it in setOf("auto", "panorama", "scans")) it else "auto" }
-                batchFirstAcceptedPose = null
-                batchLastAcceptedPose = null
-                // captureOrientation is JS-supplied here (Android
-                // doesn't yet have a native ARCore classifier
-                // equivalent to iOS' nativeCaptureOrientation; the
-                // JS hook is stale but at least it's directional).
-                batchCaptureOrientation = options.getString("captureOrientation")
-                    ?: "portrait"
-                // P3-F — configure the shared-C++ KeyframeGate for
-                // this capture.  Same knob set + defaults as iOS:
-                //   overlapThreshold default 0.4 (40% new content)
-                //   maxCount         default 6
-                // Both clamped to safe ranges that iOS also uses (see
-                // IncrementalStitcher.swift:608-615).
-                val threshold = configOverrides
-                    ?.getDoubleOrDefault("keyframeOverlapThreshold", 0.4) ?: 0.4
-                keyframeGate.overlapThreshold = threshold.coerceIn(0.10, 0.80)
-                keyframeGate.maxCount = batchKeyframeMaxCount.coerceIn(3, 10)
-
-                // 2026-05-14 — thread flow-strategy tunables through to the
-                // shared C++ gate.  Before this commit the Android JNI was
-                // missing setFlowNoveltyPercentile + setFlowMaxTranslationM
-                // bindings (iOS-only via KeyframeGateBridge), which meant
-                // operators flipping these in Settings only affected iOS
-                // captures.  Now both platforms honour them.
-                val pctile = configOverrides
-                    ?.getDoubleOrDefault("flowNoveltyPercentile", 0.85) ?: 0.85
-                keyframeGate.flowNoveltyPercentile = pctile.coerceIn(0.50, 0.99)
-                // Settings UI exposes flowMaxTranslationCm in CENTIMETRES;
-                // C++ API is in METRES.  Convert.  0 = disabled.
-                val txBudgetCm = configOverrides
-                    ?.getDoubleOrDefault("flowMaxTranslationCm", 0.0) ?: 0.0
-                keyframeGate.flowMaxTranslationM = (txBudgetCm / 100.0).coerceAtLeast(0.0)
-                // 2026-05-22 (audit F5) — flow-strategy Shi-Tomasi
-                // tunables.  Pre-audit, Android had no JNI for these
-                // (iOS-only via KeyframeGateBridge); JS Settings sliders
-                // were silent no-ops.  Now both platforms honour them.
-                // Clamp ranges match iOS (IncrementalStitcher.swift:907-924).
-                val maxCorners = configOverrides
-                    ?.getIntOrDefault("flowMaxCorners", 150) ?: 150
-                keyframeGate.flowMaxCorners = maxCorners.coerceIn(50, 300)
-                val quality = configOverrides
-                    ?.getDoubleOrDefault("flowQualityLevel", 0.01) ?: 0.01
-                keyframeGate.flowQualityLevel = quality.coerceIn(0.005, 0.05)
-                val minDist = configOverrides
-                    ?.getDoubleOrDefault("flowMinDistance", 10.0) ?: 10.0
-                keyframeGate.flowMinDistance = minDist.coerceIn(1.0, 50.0)
-                // Eval throttle: caller (this class) applies the cadence
-                // at the per-frame call sites.  iOS parity at
-                // IncrementalStitcher.swift:2459-2471.
-                val evalCadence = configOverrides
-                    ?.getIntOrDefault("flowEvalEveryNFrames", 1) ?: 1
-                keyframeGate.flowEvalEveryNFrames = evalCadence.coerceIn(1, 10)
-
-                // 2026-05-22 — non-AR mode opt-out for angular fallback.
-                // captureSource = 'non-ar' means the host is using
-                // vision-camera (no ARKit/ARCore pose).  Disable the gate's
-                // angular fallback so it doesn't compute on garbage pose
-                // (gyro drift accumulating into the integrated angle was
-                // making the gate accept near-identical frames → degenerate
-                // cv::Stitcher params → "warpRoi too large" crash).
-                //
-                // Audit fix: pre-v0.3 the check tested the legacy
-                // 'wide'/'ultrawide' enum (replaced 2026-05-14 by 'ar'/'non-ar').
-                // The string mismatch silently nullified this opt-out for the
-                // entire Android non-AR path.  See PanoramaSettings audit
-                // table row `captureSource`.
-                val captureSource = configOverrides?.getString("captureSource") ?: "ar"
-                val isNonAR = (captureSource == "non-ar")
-                keyframeGate.disableAngularFallback = isNonAR
-
-                // 2026-05-22 (audit F6) — honour frameSelectionMode.
-                // Pre-audit Android force-enabled the gate with the C++
-                // default (Pose) strategy regardless of the JS setting,
-                // making `frameSelectionMode = 'flow-based'` silently
-                // ineffective on Android (the Flow KLT path was never
-                // taken — only on iOS).  Match iOS' mapping:
-                //   'time-based' → gate disabled (passthrough)
-                //   'pose-based' → gate enabled, Pose strategy
-                //   'flow-based' → gate enabled, Flow strategy
-                val frameMode = configOverrides?.getString("frameSelectionMode")
-                    ?: "flow-based"
-                keyframeGate.enabled =
-                    (frameMode == "pose-based" || frameMode == "flow-based")
-                keyframeGate.strategy = if (frameMode == "flow-based") {
-                    KeyframeGate.Strategy.Flow
-                } else {
-                    KeyframeGate.Strategy.Pose
-                }
-                keyframeGate.reset()
-                // 2026-05-22 (audit F5) — reset the eval-throttle frame
-                // counter so the first frame of every capture is
-                // ALWAYS evaluated regardless of evalCadence.
-                consumeFrameCounter = 0L
-            } else if (isFirstwins) {
-                batchKeyframeMode = false
-                batchKeyframePaths.clear()
-                keyframeGate.enabled = false   // gate is batch-only; off for live engines
-                firstwinsEngine = IncrementalFirstwinsEngine(
-                    composeWidth = composeW,
-                    composeHeight = composeH,
-                    canvasWidth = canvasW,
-                    canvasHeight = canvasH,
-                    snapshotJpegQuality = snapQ,
-                    snapshotEveryNAccepts = snapN,
-                    frameRotationDegrees = rotation,
-                    useRectilinear = useRectilinear,
-                    // Critic #27 fix: writable app-sandbox dir for
-                    // live-snapshot JPEGs.  java.io.tmpdir resolves to
-                    // /data/local/tmp on Android (rooted-only).
-                    snapshotCacheDir = reactContext.cacheDir.absolutePath,
-                )
-                engine = null
+            // No live engine runs.  Reset the keyframe collector state.
+            // Read knobs from `config` per the V16 Phase 1 plumbing pattern.
+            batchKeyframeMode = true
+            batchKeyframePaths.clear()
+            // V16 Phase 2 (Android Fix-1) — fresh per-session subdir
+            // for this capture's keyframe JPEGs.  Replaces the
+            // V16-Phase-1 "rlis-keyframe-{N}.jpg in cacheDir"
+            // scheme that caused thumbnails from a previous capture
+            // to leak into the next one via RN's bitmap cache (see
+            // `captureSessionDir` declaration above for the full
+            // RCA).  Matches iOS' OpenCVKeyframeCollector behaviour.
+            captureSessionDir = java.io.File(
+                reactContext.cacheDir,
+                "rlis-capture-${java.util.UUID.randomUUID()}",
+            ).also { it.mkdirs() }
+            batchKeyframeMaxCount = configOverrides
+                ?.getIntOrDefault("keyframeMaxCount", 6) ?: 6
+            batchWarperType = configOverrides?.getString("warperType")
+                ?: "plane"
+            batchBlenderType = configOverrides?.getString("blenderType")
+                ?: "multiband"
+            batchSeamFinderType = configOverrides?.getString("seamFinderType")
+                ?: "graphcut"
+            batchUseInscribedRectCrop = configOverrides
+                ?.getBooleanOrDefault("enableMaxInscribedRectCrop", false)
+                ?: false
+            // 2026-05-14 — stitch-mode picker from JS Settings.
+            // Default 'auto'.  Validated against the closed set
+            // {auto, panorama, scans}; unknown values fall back
+            // to 'auto'.  Reset accumulated-pose state for the
+            // new capture so finalize() picks a fresh mode.
+            batchStitchMode = (configOverrides?.getString("stitchMode") ?: "auto")
+                .let { if (it in setOf("auto", "panorama", "scans")) it else "auto" }
+            batchFirstAcceptedPose = null
+            batchLastAcceptedPose = null
+            // captureOrientation is JS-supplied here (Android
+            // doesn't yet have a native ARCore classifier
+            // equivalent to iOS' nativeCaptureOrientation; the
+            // JS hook is stale but at least it's directional).
+            batchCaptureOrientation = options.getString("captureOrientation")
+                ?: "portrait"
+            // P3-F — configure the shared-C++ KeyframeGate for
+            // this capture.  Same knob set + defaults as iOS:
+            //   overlapThreshold default 0.4 (40% new content)
+            //   maxCount         default 6
+            // Both clamped to safe ranges that iOS also uses (see
+            // IncrementalStitcher.swift:608-615).
+            val threshold = configOverrides
+                ?.getDoubleOrDefault("keyframeOverlapThreshold", 0.4) ?: 0.4
+            keyframeGate.overlapThreshold = threshold.coerceIn(0.10, 0.80)
+            keyframeGate.maxCount = batchKeyframeMaxCount.coerceIn(3, 10)
+
+            // 2026-05-14 — thread flow-strategy tunables through to the
+            // shared C++ gate.  Before this commit the Android JNI was
+            // missing setFlowNoveltyPercentile + setFlowMaxTranslationM
+            // bindings (iOS-only via KeyframeGateBridge), which meant
+            // operators flipping these in Settings only affected iOS
+            // captures.  Now both platforms honour them.
+            val pctile = configOverrides
+                ?.getDoubleOrDefault("flowNoveltyPercentile", 0.85) ?: 0.85
+            keyframeGate.flowNoveltyPercentile = pctile.coerceIn(0.50, 0.99)
+            // Settings UI exposes flowMaxTranslationCm in CENTIMETRES;
+            // C++ API is in METRES.  Convert.  0 = disabled.
+            val txBudgetCm = configOverrides
+                ?.getDoubleOrDefault("flowMaxTranslationCm", 0.0) ?: 0.0
+            keyframeGate.flowMaxTranslationM = (txBudgetCm / 100.0).coerceAtLeast(0.0)
+            // Wall-clock keyframe-interval budget, in MILLISECONDS.
+            // Force-accept once this much time has elapsed since the last
+            // accepted keyframe (applies to BOTH Pose and Flow strategies).
+            // Passed straight through — the JS value is already in ms (no
+            // cm→m style conversion).  Clamp to ≥ 0.  Default 2000 ms when
+            // absent (NOT 0 — time-budget acceptance is on by default so a
+            // stalled scan still advances).  iOS parity:
+            // IncrementalStitcher.swift maxKeyframeIntervalMs block.
+            val maxKfIntervalMs = configOverrides
+                ?.getDoubleOrDefault("maxKeyframeIntervalMs", 2000.0) ?: 2000.0
+            keyframeGate.maxKeyframeIntervalMs = maxKfIntervalMs.coerceAtLeast(0.0)
+            // 2026-05-22 (audit F5) — flow-strategy Shi-Tomasi
+            // tunables.  Pre-audit, Android had no JNI for these
+            // (iOS-only via KeyframeGateBridge); JS Settings sliders
+            // were silent no-ops.  Now both platforms honour them.
+            // Clamp ranges match iOS (IncrementalStitcher.swift:907-924).
+            val maxCorners = configOverrides
+                ?.getIntOrDefault("flowMaxCorners", 150) ?: 150
+            keyframeGate.flowMaxCorners = maxCorners.coerceIn(50, 300)
+            val quality = configOverrides
+                ?.getDoubleOrDefault("flowQualityLevel", 0.01) ?: 0.01
+            keyframeGate.flowQualityLevel = quality.coerceIn(0.005, 0.05)
+            val minDist = configOverrides
+                ?.getDoubleOrDefault("flowMinDistance", 10.0) ?: 10.0
+            keyframeGate.flowMinDistance = minDist.coerceIn(1.0, 50.0)
+            // Eval throttle: caller (this class) applies the cadence
+            // at the per-frame call sites.  iOS parity at
+            // IncrementalStitcher.swift:2459-2471.
+            val evalCadence = configOverrides
+                ?.getIntOrDefault("flowEvalEveryNFrames", 1) ?: 1
+            keyframeGate.flowEvalEveryNFrames = evalCadence.coerceIn(1, 10)
+
+            // 2026-05-22 — non-AR mode opt-out for angular fallback.
+            // captureSource = 'non-ar' means the host is using
+            // vision-camera (no ARKit/ARCore pose).  Disable the gate's
+            // angular fallback so it doesn't compute on garbage pose
+            // (gyro drift accumulating into the integrated angle was
+            // making the gate accept near-identical frames → degenerate
+            // cv::Stitcher params → "warpRoi too large" crash).
+            //
+            // Audit fix: pre-v0.3 the check tested the legacy
+            // 'wide'/'ultrawide' enum (replaced 2026-05-14 by 'ar'/'non-ar').
+            // The string mismatch silently nullified this opt-out for the
+            // entire Android non-AR path.  See PanoramaSettings audit
+            // table row `captureSource`.
+            val captureSource = configOverrides?.getString("captureSource") ?: "ar"
+            val isNonAR = (captureSource == "non-ar")
+            keyframeGate.disableAngularFallback = isNonAR
+
+            // 2026-05-22 (audit F6) — honour frameSelectionMode.
+            // Pre-audit Android force-enabled the gate with the C++
+            // default (Pose) strategy regardless of the JS setting,
+            // making `frameSelectionMode = 'flow-based'` silently
+            // ineffective on Android (the Flow KLT path was never
+            // taken — only on iOS).  Match iOS' mapping:
+            //   'time-based' → gate disabled (passthrough)
+            //   'pose-based' → gate enabled, Pose strategy
+            //   'flow-based' → gate enabled, Flow strategy
+            val frameMode = configOverrides?.getString("frameSelectionMode")
+                ?: "flow-based"
+            keyframeGate.enabled =
+                (frameMode == "pose-based" || frameMode == "flow-based")
+            keyframeGate.strategy = if (frameMode == "flow-based") {
+                KeyframeGate.Strategy.Flow
             } else {
-                batchKeyframeMode = false
-                batchKeyframePaths.clear()
-                keyframeGate.enabled = false   // gate is batch-only; off for hybrid engine
-                engine = IncrementalEngine(
-                    composeWidth  = composeW,
-                    composeHeight = composeH,
-                    canvasWidth   = canvasW,
-                    canvasHeight  = canvasH,
-                    featherPx     = featherP,
-                    snapshotJpegQuality = snapQ,
-                    snapshotEveryNAccepts = snapN,
-                    frameRotationDegrees = rotation,
-                )
-                firstwinsEngine = null
+                KeyframeGate.Strategy.Pose
             }
+            keyframeGate.reset()
+            // 2026-05-22 (audit F5) — reset the eval-throttle frame
+            // counter so the first frame of every capture is
+            // ALWAYS evaluated regardless of evalCadence.
+            consumeFrameCounter = 0L
             // Engage the ARCameraView's per-frame ingestion path if a
             // view is mounted — this is what gives Android parity
             // with iOS' ARSession-driven path.  No-op when the view
@@ -641,20 +577,11 @@ class IncrementalStitcher(
     // iOS has used since the V16 ship.  See
     // `private val keyframeGate = KeyframeGate()` above for the
     // instance + lifetime.
-    //
-    // `batchKeyframeAcceptStride` is no longer consulted (the proper
-    // gate uses pose-driven overlap, not a frame-counter stride);
-    // the field is kept around for now because removing it would
-    // touch unrelated init/serialization paths.  Wire it back in if
-    // we ever add a "force every Nth frame regardless of overlap"
-    // override.
 
 
     @ReactMethod
     fun finalize(options: ReadableMap, promise: Promise) {
-        val hybrid = this.engine
-        val firstwins = this.firstwinsEngine
-        if (hybrid == null && firstwins == null && !batchKeyframeMode) {
+        if (!batchKeyframeMode) {
             return promise.reject(
                 "incremental-not-running",
                 "No active capture — call start() first.",
@@ -750,16 +677,9 @@ class IncrementalStitcher(
         )
         batchKeyframeMode = false
         batchKeyframePaths.clear()
-        batchKeyframeFrameCounter = 0
         batchFirstAcceptedPose = null
         batchLastAcceptedPose = null
 
-        // Null the bridge refs synchronously NOW so any worker that's
-        // about to run sees them as gone (V12.1 pattern).  We keep
-        // local refs to do the actual finalize.
-        engine = null
-        firstwinsEngine = null
-
         workScope.launch {
             try {
                 val map = Arguments.createMap()
@@ -828,62 +748,18 @@ class IncrementalStitcher(
                     // resolved cv::Stitcher mode so JS can surface it
                     // on the output preview + debug toast.
                     map.putString("stitchModeResolved", stitchModeResolved)
-                } else if (firstwins != null) {
-                    val snap = firstwins.finalize(outputPath, quality)
-                        ?: throw IllegalStateException("firstwins.finalize returned null")
-                    map.putString("panoramaPath", snap.panoramaPath)
-                    map.putInt("width", snap.width)
-                    map.putInt("height", snap.height)
-                    map.putInt("acceptedCount", snap.acceptedCount)
-                    // Critic #22 fix: explicit native-buffer release.
-                    firstwins.release()
                 } else {
-                    val snap = hybrid!!.finalize(outputPath, quality)
-                    map.putString("panoramaPath", snap.panoramaPath)
-                    map.putInt("width", snap.width)
-                    map.putInt("height", snap.height)
-                    map.putInt("acceptedCount", snap.acceptedCount)
-                    hybrid.release()
-                    // 2026-05-16 — realtime+batch fusion (Option A
-                    // "Replace on completion") hook.  The live
-                    // panorama has been written to outputPath; now
-                    // fire-and-forget an async refinement on the
-                    // engine's accepted keyframes via the shared C++
-                    // stitcher.
-                    //
-                    // Today's `IncrementalEngine` (the hybrid live
-                    // engine) does NOT retain per-frame JPEGs — it
-                    // paints into a single persistent canvas Mat
-                    // that's torn down by `release()` above.  So the
-                    // keyframe-paths list passed to runHybridAutoRefine
-                    // is empty for the hybrid branch, which means
-                    // the auto-trigger detects "< 2 keyframes on
-                    // disk" and emits `isRefining=false` without
-                    // running cv::Stitcher.  Per the prompt's
-                    // "no-op when no keyframes on disk" constraint.
-                    //
-                    // When a future change wires the hybrid engine
-                    // to a keyframe collector (parallel to iOS'
-                    // OpenCVKeyframeCollector), the same hook will
-                    // light up automatically — just pass the
-                    // populated list here.
-                    val keyframePathsForHybrid: List<String> = emptyList()
-                    val refinedOutputPath = refinedPathFromLive(outputPath)
-                    runHybridAutoRefine(
-                        framePaths = keyframePathsForHybrid,
-                        refinedOutputPath = refinedOutputPath,
-                        captureOrientation = captureOrientationSnapshot,
-                        warperType = warperTypeSnapshot,
-                        blenderType = blenderTypeSnapshot,
-                        seamFinderType = seamFinderTypeSnapshot,
-                        useInscribedRectCrop = useInscribedRectCropSnapshot,
+                    // The live engines (hybrid + firstwins/slit) and their
+                    // auto-refine hook were archived in the 2026-06 batch-
+                    // keyframe cleanup; batchKeyframeMode is always true now.
+                    throw IllegalStateException(
+                        "finalize: live engines were archived; " +
+                            "expected batchKeyframeMode.",
                     )
                 }
                 map.putInt("droppedBackpressure", 0)
                 promise.resolve(map)
             } catch (t: Throwable) {
-                firstwins?.release()
-                hybrid?.release()
                 promise.reject("incremental-finalize-failed", t.message, t)
             }
         }
@@ -891,17 +767,12 @@ class IncrementalStitcher(
 
     @ReactMethod
     fun cancel(promise: Promise) {
-        // Critic #4 fix: synchronously flip isRunning + null engine
-        // refs BEFORE releasing.  Any in-flight worker bails at the
-        // re-check before touching the now-null engine.  Matches
-        // iOS V12.1 cancel path.
+        // Critic #4 fix: synchronously flip isRunning BEFORE the work
+        // queue runs.  Any in-flight worker bails at the re-check.
+        // Matches iOS V12.1 cancel path.
         arCameraViewRef?.setIncrementalIngestionActive(false)
         isRunning.set(false)
         frameProcessorIngestEnabled.set(false)  // F8.4 — cut producer-thread ingest at cancel
-        val hybrid = engine
-        val firstwins = firstwinsEngine
-        engine = null
-        firstwinsEngine = null
         // V16 Phase 2 (Android Fix-1) — clean up the per-session
         // batch-keyframe subdir.  iOS-parity: cancel removes the
         // session's saved JPEGs because the operator explicitly
@@ -912,14 +783,10 @@ class IncrementalStitcher(
         captureSessionDir = null
         batchKeyframeMode = false
         batchKeyframePaths.clear()
-        batchKeyframeFrameCounter = 0
-        // Defer engine release + session-dir cleanup onto the work
-        // queue so we don't race with an ingest that already passed
-        // the null-check and is mid-execution on a captured local
-        // reference.
+        // Defer the session-dir cleanup onto the work queue so we don't
+        // race with an ingest that already passed the null-check and is
+        // mid-execution on a captured local reference.
         workScope.launch {
-            hybrid?.release()
-            firstwins?.reset()
             sessionDirToCleanup?.deleteRecursively()
         }
         val map = Arguments.createMap()
@@ -1017,9 +884,9 @@ class IncrementalStitcher(
     ) {
         // ── V16 batch-keyframe: AR-driven path ─────────────────────
         //
-        // Batch-keyframe mode runs WITHOUT a live engine (engine ==
-        // firstwinsEngine == null) — frames accumulate as keyframe
-        // paths and the cv::Stitcher pipeline runs at finalize time.
+        // Batch-keyframe mode runs WITHOUT a live engine (they were
+        // archived in the 2026-06 cleanup) — frames accumulate as
+        // keyframe paths and the cv::Stitcher pipeline runs at finalize.
         //
         // P3-F: this branch now calls into the shared-C++
         // KeyframeGate (cpp/keyframe_gate.{hpp,cpp}, same algorithm
@@ -1190,101 +1057,6 @@ class IncrementalStitcher(
             return
         }
 
-        val hybrid = this.engine
-        val firstwins = this.firstwinsEngine
-        if (hybrid == null && firstwins == null) return
-        // 2026-05-21 (v0.3) — legacy live-engine path requires a JPEG
-        // path (hybrid/firstwins addFrameAtPath feeds the cv::Mat
-        // pipeline).  The batch-keyframe path above lazily encodes
-        // only on accept and reaches `return` before this point, so
-        // 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.
-        // 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 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
-        }
-        // v0.10.0 audit #4A — extract the wrapped bytes ONCE on the
-        // producer thread before dispatching to workScope.  This
-        // makes the transfer-of-ownership explicit + caught early:
-        // if a caller accidentally passes the same TransferredNV21
-        // instance to a sync consumer earlier, takeOnce() would
-        // have already thrown there.  Capturing `pixelBytes` by
-        // value inside the coroutine sidesteps any chance of the
-        // wrapper being read from two threads.
-        val pixelBytes: ByteArray? = if (hasPixelData) nv21PixelData!!.takeOnce() else null
-        workScope.launch {
-            val state: WritableMap? = if (firstwins != null) {
-                val tele = if (hasPixelData) {
-                    firstwins.addFramePixelData(
-                        nv21 = pixelBytes!!,
-                        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 = if (hasPixelData) {
-                    hybrid!!.addFramePixelData(
-                        nv21 = pixelBytes!!,
-                        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)
-        }
     }
 
     // ─── F8.4 — Frame Processor entry point ──────────────────────
@@ -1479,12 +1251,12 @@ class IncrementalStitcher(
 
     @ReactMethod
     fun getState(promise: Promise) {
-        val state = firstwinsEngine?.lastState ?: engine?.lastState
-        if (state == null) {
-            promise.resolve(null)
-            return
-        }
-        promise.resolve(state)
+        // The live engines exposed a cached `lastState` snapshot; the
+        // batch-keyframe path (the only engine now) drives state purely
+        // through emitted IncrementalStateUpdate events, so there is no
+        // poll-able snapshot to return.  (Batch-keyframe captures already
+        // returned null here — engine/firstwinsEngine were both null.)
+        promise.resolve(null)
     }
 
     // ── V15.0e — AR plane detection bridge (iOS-parity) ──────────────
@@ -1816,124 +1588,6 @@ class IncrementalStitcher(
         }
     }
 
-    /**
-     * 2026-05-16 — realtime+batch fusion auto-trigger called from
-     * the hybrid-engine branch of `finalize()`.  Fire-and-forget;
-     * the finalize() promise has ALREADY resolved with the live
-     * panorama before this is invoked.
-     *
-     *   1. Emits a state event with `isRefining = true` so the
-     *      host renders a "Refining…" pill.
-     *   2. Runs `BatchStitcher.stitchSync(...)` on the supplied
-     *      keyframe paths.
-     *   3. On success: emits a state event with `isRefining = false`
-     *      AND `refinedPanoramaPath = <path>`.
-     *   4. On failure: emits a state event with `isRefining = false`
-     *      and no refined path.  Host keeps showing the live
-     *      panorama; failure does not affect audit save.
-     *
-     * NO-OP when `framePaths.size < 2` or any path is missing on
-     * disk — matches the design doc's "if keyframes are NOT on
-     * disk, auto-trigger is a no-op" contract.  Today's hybrid
-     * engine retains no per-frame JPEGs so this is the
-     * always-no-op path; the hook is wired in advance of a future
-     * keyframe-collector enhancement.
-     */
-    internal fun runHybridAutoRefine(
-        framePaths: List<String>,
-        refinedOutputPath: String,
-        captureOrientation: String,
-        warperType: String,
-        blenderType: String,
-        seamFinderType: String,
-        useInscribedRectCrop: Boolean,
-    ) {
-        if (framePaths.size < 2) {
-            android.util.Log.i(
-                "IncrementalStitcher",
-                "[refine.auto] skipped: framePaths.size=${framePaths.size} " +
-                    "(hybrid engine retains no per-frame JPEGs)",
-            )
-            emitRefinementState(isRefining = false, refinedPanoramaPath = null)
-            return
-        }
-        for (p in framePaths) {
-            if (!File(p).exists()) {
-                android.util.Log.i(
-                    "IncrementalStitcher",
-                    "[refine.auto] skipped: missing keyframe $p",
-                )
-                emitRefinementState(isRefining = false, refinedPanoramaPath = null)
-                return
-            }
-        }
-        emitRefinementState(isRefining = true, refinedPanoramaPath = null)
-        refineScope.launch {
-            try {
-                val stitcher = BatchStitcher.bridgeInstance
-                    ?: throw IllegalStateException(
-                        "BatchStitcher.bridgeInstance is null at auto-refine time",
-                    )
-                stitcher.stitchSync(
-                    framePaths.toTypedArray(),
-                    refinedOutputPath,
-                    90,
-                    warperType,
-                    blenderType,
-                    seamFinderType,
-                    captureOrientation,
-                    useInscribedRectCrop,
-                    stitchMode = "scans",
-                )
-                android.util.Log.i(
-                    "IncrementalStitcher",
-                    "[refine.auto] success path=$refinedOutputPath",
-                )
-                emitRefinementState(
-                    isRefining = false,
-                    refinedPanoramaPath = refinedOutputPath,
-                )
-            } catch (t: Throwable) {
-                android.util.Log.w(
-                    "IncrementalStitcher",
-                    "[refine.auto] refinement failed (live output kept): ${t.message}",
-                )
-                emitRefinementState(isRefining = false, refinedPanoramaPath = null)
-            }
-        }
-    }
-
-    /**
-     * 2026-05-16 — emit a refinement-related state event.  Reuses
-     * the same IncrementalStateUpdate channel the live
-     * engines emit on; JS reads `isRefining` and `refinedPanoramaPath`
-     * directly from the event payload (no schema change required on
-     * the JS dispatch side).
-     */
-    private fun emitRefinementState(
-        isRefining: Boolean,
-        refinedPanoramaPath: String?,
-    ) {
-        val state = Arguments.createMap().apply {
-            putNull("panoramaPath")
-            putInt("width", 0)
-            putInt("height", 0)
-            putInt("acceptedCount", 0)
-            putInt("outcome", 0)              // AcceptedHigh
-            putDouble("confidence", 1.0)
-            putDouble("overlapPercent", -1.0)
-            putInt("processingMs", 0)
-            putBoolean("isLandscape", false)
-            putInt("paintedExtent", 0)
-            putInt("panExtent", 0)
-            putInt("keyframeMax", 0)
-            putBoolean("isRefining", isRefining)
-            if (refinedPanoramaPath != null) {
-                putString("refinedPanoramaPath", refinedPanoramaPath)
-            }
-        }
-        emitState(state)
-    }
 
     /**
      * v0.10.0 #15A — emit a refine-pipeline phase update on the same
@@ -1988,24 +1642,6 @@ class IncrementalStitcher(
         emitState(state)
     }
 
-    /**
-     * 2026-05-16 — given the live panorama path, derive a sibling
-     * path for the refined output.  Same algorithm iOS uses:
-     *   /…/<base>.jpg → /…/<base>-refined.jpg
-     */
-    private fun refinedPathFromLive(livePath: String): String {
-        val cleaned = stripFileScheme(livePath)
-        val file = File(cleaned)
-        val parent = file.parentFile ?: File(reactContext.cacheDir, "panoramas")
-        val name = file.name
-        val dot = name.lastIndexOf('.')
-        val refinedName = if (dot >= 0) {
-            "${name.substring(0, dot)}-refined${name.substring(dot)}"
-        } else {
-            "$name-refined"
-        }
-        return File(parent, refinedName).absolutePath
-    }
 
     /**
      * Poll the process' memory footprint in MB.  Android parity for
@@ -2180,10 +1816,8 @@ class IncrementalStitcher(
         state.putInt("width", 0)
         state.putInt("height", 0)
         state.putInt("acceptedCount", keyframeCount)
-        // Outcome 0 = AcceptedHigh — matches the FrameOutcome enum
-        // ordinal that the live engines emit.  Keeps the iOS
-        // IncrementalOutcome contract: batch-keyframe
-        // accepts all carry outcome=acceptedHigh.
+        // Outcome 0 = AcceptedHigh.  Keeps the iOS IncrementalOutcome
+        // contract: batch-keyframe accepts all carry outcome=acceptedHigh.
         state.putInt("outcome", 0)
         state.putDouble("confidence", 1.0)
         val overlapPercent = if (newContentFraction >= 0.0) {
@@ -2378,628 +2012,12 @@ private fun ReadableMap.getBooleanOrDefault(key: String, default: Boolean): Bool
     if (hasKey(key) && !isNull(key)) getBoolean(key) else default
 
 
-// ── Frame outcome — mirrors iOS RLISFrameOutcome ────────────────────
-
-internal enum class FrameOutcome {
-    AcceptedHigh,
-    AcceptedMedium,
-    SkippedTooClose,
-    RejectedTooFar,
-    RejectedSceneUniform,
-    RejectedAlignmentLost,
-    SkippedTrackingPoor,
-    /** V12.11 Step D — operator panned BACKWARDS past the running
-     *  max along the pan axis.  Engine has SKIPPED the paste; host
-     *  should auto-finalize.  Rectilinear-only. */
-    RejectedReverseDirection,
-}
-
-
-internal data class FrameTelemetry(
-    val outcome: FrameOutcome,
-    val overlapPercent: Double,
-    val matchCount: Int,
-    val inlierRatio: Double,
-    val confidence: Double,
-    val processingMs: Double,
-    /** V12.12 — engine-detected orientation.  Mirrors iOS'
-     *  `RLISFrameTelemetry.isLandscape`.  TRUE for landscape capture
-     *  (vertical pan), FALSE for portrait (horizontal pan).  Stays
-     *  at the FIRST-FRAME determination thereafter. */
-    val isLandscape: Boolean = false,
-)
-
-
-internal data class StitcherSnapshot(
-    val panoramaPath: String,
-    val width: Int,
-    val height: Int,
-    val acceptedCount: Int,
-)
-
-
-/**
- * Pure-OpenCV implementation of the incremental algorithm.  No RN
- * dependency — this class can be unit-tested with synthetic Mat
- * inputs.  Exact algorithmic mirror of iOS' OpenCVIncrementalStitcher.mm.
- */
-internal class IncrementalEngine(
-    val composeWidth: Int,
-    val composeHeight: Int,
-    val canvasWidth: Int,
-    val canvasHeight: Int,
-    val featherPx: Int,
-    val snapshotJpegQuality: Int,
-    val snapshotEveryNAccepts: Int,
-    /// 0/90/180/270 — rotation applied to each ingested frame before
-    /// any other processing.  See iOS' equivalent for the full
-    /// rationale.  JS computes from device orientation.
-    val frameRotationDegrees: Int,
-) {
-    private val canvas: Mat = Mat.zeros(canvasHeight, canvasWidth, CvType.CV_8UC3)
-    private val canvasMask: Mat = Mat.zeros(canvasHeight, canvasWidth, CvType.CV_8UC1)
-
-    /// V7 pose-driven state — sensor-native compute path.  Mirrors iOS.
-    private var firstRotationArkit: Mat = Mat()
-    private var kCompose: Mat = Mat()
-    private var tCanvas: Mat = Mat.eye(3, 3, CvType.CV_64F)
-    private val mArkitToCv: Mat = Mat(3, 3, CvType.CV_64F).apply {
-        // diag(1, -1, -1) — ARKit/ARCore (Y-up, -Z forward) → OpenCV.
-        setTo(Scalar(0.0))
-        put(0, 0, 1.0); put(1, 1, -1.0); put(2, 2, -1.0)
-    }
-
-    private var lastAcceptedYaw: Double = 0.0
-    private var lastAcceptedPitch: Double = 0.0
-    private var hasFirstFrame: Boolean = false
-    private var acceptsSinceSnapshot: Int = 0
-    var acceptedCount: Int = 0
-        private set
-    private var snapshotSeq: Int = 0
-    var lastState: WritableMap? = null
-        private set
-
-    /**
-     * Read the JPEG at `path`, downscale to compose-resolution, run
-     * the same algorithm as the iOS engine.
-     */
-    fun addFrameAtPath(
-        path: String,
-        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),
-            )
-        }
-
-        val cleaned = stripFileScheme(path)
-        val srcRaw = Imgcodecs.imread(cleaned, Imgcodecs.IMREAD_COLOR)
-        if (srcRaw.empty()) {
-            return FrameTelemetry(
-                FrameOutcome.SkippedTrackingPoor, -1.0, 0, 0.0, 0.0,
-                msSince(t0),
-            )
-        }
-        // V7: NO input rotation.  ARCore (and the JS gyro fallback)
-        // deliver sensor-native landscape frames; we keep them in
-        // that frame through the entire compute pipeline.  Output
-        // rotation for display happens at snapshot/finalize time.
-        // 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)
-
-        if (!hasFirstFrame) {
-            firstRotationArkit = rNew.clone()
-            // V7: K is in COMPOSE pixel coordinates.  Sensor intrinsics
-            // get scaled by the same uniform factor we used to downsample
-            // the frame, so K · ray → pixel produces the right pixel
-            // in compose space directly.  No rotation chain needed.
-            val sx = frame.cols().toDouble() / maxOf(1, imageWidth)
-            val sy = frame.rows().toDouble() / maxOf(1, imageHeight)
-            val s = 0.5 * (sx + sy)
-            kCompose = Mat(3, 3, CvType.CV_64F).apply {
-                setTo(Scalar(0.0))
-                put(0, 0, fx * s); put(0, 2, cx * s)
-                put(1, 1, fy * s); put(1, 2, cy * s)
-                put(2, 2, 1.0)
-            }
-
-            // Place first frame at canvas centre.
-            val ox = (canvas.cols() - frame.cols()) / 2
-            val oy = (canvas.rows() - frame.rows()) / 2
-            val roi = Rect(ox, oy, frame.cols(), frame.rows())
-            frame.copyTo(canvas.submat(roi))
-            canvasMask.submat(roi).setTo(Scalar(255.0))
-            tCanvas = Mat.eye(3, 3, CvType.CV_64F)
-            tCanvas.put(0, 2, ox.toDouble())
-            tCanvas.put(1, 2, oy.toDouble())
-
-            lastAcceptedYaw = yaw
-            lastAcceptedPitch = pitch
-            hasFirstFrame = true
-            acceptedCount = 1
-            frame.release()
-            return FrameTelemetry(
-                FrameOutcome.AcceptedHigh, 0.0, 0, 0.0, 1.0, msSince(t0),
-            )
-        }
-
-        val overlap = computeOverlapPct(
-            yaw - lastAcceptedYaw, pitch - lastAcceptedPitch,
-            fovHorizDegrees, fovVertDegrees,
-        )
-        if (overlap > MAX_OVERLAP_PCT) {
-            frame.release()
-            return FrameTelemetry(
-                FrameOutcome.SkippedTooClose, overlap, 0, 0.0, 0.0, msSince(t0),
-            )
-        }
-        if (overlap < MIN_OVERLAP_PCT) {
-            frame.release()
-            return FrameTelemetry(
-                FrameOutcome.RejectedTooFar, overlap, 0, 0.0, 0.0, msSince(t0),
-            )
-        }
-
-        // V7 pose-driven homography (sensor-native compose space):
-        //   R_rel_cv = M · R_first⁻¹ · R_new · M
-        //   H_compose = K_compose · R_rel_cv · K_compose⁻¹
-        //   H_canvas = T_canvas · H_compose
-        // No R2S/S chain — the v6 bug was applying input rotation
-        // and undoing it via the chain; v7 keeps everything in
-        // sensor-native compose space and rotates only at output.
-        val firstInv = Mat()
-        Core.transpose(firstRotationArkit, firstInv)
-        val tmp1 = Mat(); Core.gemm(mArkitToCv, firstInv, 1.0, Mat(), 0.0, tmp1)
-        val tmp2 = Mat(); Core.gemm(tmp1, rNew, 1.0, Mat(), 0.0, tmp2)
-        val rRelCv = Mat(); Core.gemm(tmp2, mArkitToCv, 1.0, Mat(), 0.0, rRelCv)
-        firstInv.release(); tmp1.release(); tmp2.release()
-
-        val kInv = kCompose.inv()
-        val hcTmp = Mat(); Core.gemm(kCompose, rRelCv, 1.0, Mat(), 0.0, hcTmp)
-        val hCompose = Mat(); Core.gemm(hcTmp, kInv, 1.0, Mat(), 0.0, hCompose)
-        kInv.release(); hcTmp.release(); rRelCv.release(); rNew.release()
-
-        val hCanvas = Mat(); Core.gemm(tCanvas, hCompose, 1.0, Mat(), 0.0, hCanvas)
-        hCompose.release()
-
-        warpAndBlend(frame, hCanvas)
-        hCanvas.release()
-        frame.release()
-
-        lastAcceptedYaw = yaw
-        lastAcceptedPitch = pitch
-        acceptedCount++
-
-        // Confidence as in iOS — function of how centred the overlap
-        // is in the [10, 75]% acceptance window.
-        val midOverlap = 0.5 * (MIN_OVERLAP_PCT + MAX_OVERLAP_PCT)
-        val overlapDistance = kotlin.math.abs(overlap - midOverlap) /
-            (MAX_OVERLAP_PCT - midOverlap)
-        val confidence = maxOf(0.0, 1.0 - overlapDistance)
-        val outcome = if (confidence >= 0.6) FrameOutcome.AcceptedHigh
-                      else FrameOutcome.AcceptedMedium
-
-        return FrameTelemetry(
-            outcome, overlap, -1, -1.0, confidence, msSince(t0),
-        )
-    }
-
-    /** Write a JPEG snapshot if accept-counter has hit the configured cadence. */
-    fun snapshotIfDue(tele: FrameTelemetry): WritableMap? {
-        val isAccept = tele.outcome == FrameOutcome.AcceptedHigh
-                    || tele.outcome == FrameOutcome.AcceptedMedium
-        var snapshotPath: String? = null
-        var snapW = 0
-        var snapH = 0
-        if (isAccept) {
-            acceptsSinceSnapshot++
-            if (acceptsSinceSnapshot >= snapshotEveryNAccepts) {
-                acceptsSinceSnapshot = 0
-                snapshotSeq++
-                val slot = snapshotSeq % 4
-                val tmpPath = "${System.getProperty("java.io.tmpdir") ?: "/data/local/tmp"}" +
-                              "/rlis-live-$slot.jpg"
-                // tightCrop = true for live snapshots: the canvas is
-                // 4800x2200, but most of it is empty until the pan
-                // covers it.  Without a tight crop, every snapshot
-                // was a ~24 MB JPEG that RN's <Image> couldn't keep
-                // up with.  Tight-cropped snapshots are 50–500 KB.
-                val snap = writeJpeg(tmpPath, snapshotJpegQuality, tightCrop = true)
-                if (snap != null) {
-                    snapshotPath = snap.panoramaPath
-                    snapW = snap.width
-                    snapH = snap.height
-                }
-            }
-        }
-
-        val map = Arguments.createMap().apply {
-            putInt("width", snapW)
-            putInt("height", snapH)
-            putInt("acceptedCount", acceptedCount)
-            putInt("outcome", tele.outcome.ordinal)
-            putDouble("confidence", tele.confidence)
-            putDouble("overlapPercent", tele.overlapPercent)
-            putDouble("processingMs", tele.processingMs)
-            if (snapshotPath != null) putString("panoramaPath", snapshotPath)
-        }
-        lastState = map
-        return map
-    }
-
-    fun finalize(outputPath: String, quality: Int): StitcherSnapshot {
-        val cleaned = stripFileScheme(outputPath)
-        val snap = writeJpeg(cleaned, quality, tightCrop = true)
-            ?: throw IllegalStateException(
-                "No frames have been accepted yet, or write failed: $cleaned",
-            )
-        release()
-        return snap
-    }
-
-    fun release() {
-        canvas.release()
-        canvasMask.release()
-        firstRotationArkit.release()
-        kCompose.release()
-        tCanvas.release()
-        mArkitToCv.release()
-    }
-
-    // ── internal helpers ────────────────────────────────────────────
-
-    private fun downsampleToCompose(src: Mat): Mat {
-        // Uniform scale that fits inside the compose-dim budget — the
-        // smaller of the two ratios wins so neither axis distorts.
-        val sw = src.cols().toDouble()
-        val sh = src.rows().toDouble()
-        var scale = minOf(composeWidth.toDouble() / sw, composeHeight.toDouble() / sh)
-        if (scale > 1.0) scale = 1.0  // never upscale
-        val outW = maxOf(1, (sw * scale).toInt())
-        val outH = maxOf(1, (sh * scale).toInt())
-        if (src.cols() == outW && src.rows() == outH) return src
-        val out = Mat()
-        Imgproc.resize(src, out, Size(outW.toDouble(), outH.toDouble()), 0.0, 0.0, Imgproc.INTER_AREA)
-        return out
-    }
-
-    // `placeFirstFrame` was dropped in v6 — the first-frame logic is
-    // now inlined in `addFrameAtPath` so the engine can capture the
-    // reference pose + intrinsics in the same place it positions the
-    // frame on the canvas.
-
-    private fun warpAndBlend(frame: Mat, worldH: Mat) {
-        val canvasSize = Size(canvasWidth.toDouble(), canvasHeight.toDouble())
-
-        val warped = Mat()
-        Imgproc.warpPerspective(
-            frame, warped, worldH, canvasSize,
-            Imgproc.INTER_LINEAR, Core.BORDER_CONSTANT, Scalar(0.0, 0.0, 0.0),
-        )
-
-        val frameOnesMask = Mat(frame.rows(), frame.cols(), CvType.CV_8UC1, Scalar(255.0))
-        val warpedMask = Mat()
-        Imgproc.warpPerspective(
-            frameOnesMask, warpedMask, worldH, canvasSize,
-            Imgproc.INTER_NEAREST, Core.BORDER_CONSTANT, Scalar(0.0),
-        )
-        frameOnesMask.release()
-
-        // Hard midline seam (replaces v4 ratio-feather).  Same fix
-        // as iOS v5: each output pixel comes from exactly one frame,
-        // so misalignment between frames can't produce ghosts.  The
-        // seam is placed where each pixel is equidistant from both
-        // frames' outer edges (the "middle" of the overlap), then
-        // softened with a small Gaussian to hide the pixel-perfect
-        // cut.
-        val distNew = Mat()
-        Imgproc.distanceTransform(warpedMask, distNew, Imgproc.DIST_L2, 3)
-        val distCanvas = Mat()
-        Imgproc.distanceTransform(canvasMask, distCanvas, Imgproc.DIST_L2, 3)
-
-        // alpha8: 255 where new is deeper, 0 where canvas is deeper.
-        val alpha8 = Mat()
-        Core.compare(distNew, distCanvas, alpha8, Core.CMP_GE)
-
-        // First-touch regions need new frame to write unconditionally.
-        val noPriorMask = Mat()
-        Core.compare(canvasMask, Scalar(0.0), noPriorMask, Core.CMP_EQ)
-        alpha8.setTo(Scalar(255.0), noPriorMask)
-        noPriorMask.release()
-
-        val alpha = Mat()
-        alpha8.convertTo(alpha, CvType.CV_32F, 1.0 / 255.0)
-        alpha8.release()
-        Imgproc.GaussianBlur(alpha, alpha, Size(7.0, 7.0), 0.0)
-        distNew.release(); distCanvas.release()
-
-        val alphaChannels = mutableListOf(alpha, alpha, alpha)
-        val alpha3 = Mat()
-        Core.merge(alphaChannels, alpha3)
-        val invAlpha3 = Mat()
-        Core.subtract(Mat.ones(alpha3.size(), alpha3.type()).apply {
-            setTo(Scalar(1.0, 1.0, 1.0))
-        }, alpha3, invAlpha3)
-
-        val warpedF = Mat(); warped.convertTo(warpedF, CvType.CV_32FC3)
-        val canvasF = Mat(); canvas.convertTo(canvasF, CvType.CV_32FC3)
-        val blendedF = Mat()
-        Core.multiply(warpedF, alpha3, warpedF)
-        Core.multiply(canvasF, invAlpha3, canvasF)
-        Core.add(warpedF, canvasF, blendedF)
-        warpedF.release(); canvasF.release()
-        alpha.release(); alpha3.release(); invAlpha3.release()
-
-        val blended8 = Mat()
-        blendedF.convertTo(blended8, CvType.CV_8UC3)
-        blendedF.release()
-        // Only write where warpedMask is set; rest of canvas is unchanged.
-        blended8.copyTo(canvas, warpedMask)
-        blended8.release()
-
-        Core.bitwise_or(canvasMask, warpedMask, canvasMask)
-        warpedMask.release()
-        warped.release()
-    }
-
-    private fun writeJpeg(
-        outputPath: String,
-        quality: Int,
-        tightCrop: Boolean,
-    ): StitcherSnapshot? {
-        if (acceptedCount == 0) return null
-        var crop = Rect(0, 0, canvas.cols(), canvas.rows())
-        if (tightCrop) {
-            val nonZero = MatOfPoint2f()
-            // boundingRect on the mask matrix gives us the tight crop;
-            // OpenCV Java's API takes a Mat of points, but for an
-            // image mask we use Imgproc.boundingRect on a contour.
-            // Cheaper path: walk the mask once.
-            val contoured = Imgproc.boundingRect(MaskNonZeroContour(canvasMask))
-            if (contoured.width > 0 && contoured.height > 0) {
-                crop = contoured
-            }
-            nonZero.release()
-        }
-        val cropped = Mat(canvas, crop)
-        // V7.1 GRAVITY-DERIVED OUTPUT ROTATION.  Mirrors iOS — see
-        // OpenCVIncrementalStitcher.mm for the full derivation.  The
-        // rotation comes from the AR pose (which knows gravity) so
-        // we don't need a device-orientation hook (which was the
-        // source of the v7 "sideways for landscape" bug).
-        var rotationDeg = 0
-        if (hasFirstFrame && !firstRotationArkit.empty()) {
-            val gravWorld = Mat(3, 1, CvType.CV_64F).apply {
-                put(0, 0, 0.0); put(1, 0, -1.0); put(2, 0, 0.0)
-            }
-            val firstT = Mat()
-            Core.transpose(firstRotationArkit, firstT)
-            val gravArkit = Mat(); Core.gemm(firstT, gravWorld, 1.0, Mat(), 0.0, gravArkit)
-            val gravCv = Mat(); Core.gemm(mArkitToCv, gravArkit, 1.0, Mat(), 0.0, gravCv)
-            val gx = gravCv.get(0, 0)[0]
-            val gy = gravCv.get(1, 0)[0]
-            val angle = kotlin.math.atan2(gx, gy) * 180.0 / Math.PI
-            rotationDeg = (kotlin.math.round(angle / 90.0).toInt()) * 90
-            rotationDeg = ((rotationDeg % 360) + 360) % 360
-            gravWorld.release(); firstT.release(); gravArkit.release(); gravCv.release()
-        }
-        val out = when (rotationDeg) {
-            90  -> Mat().also { Core.rotate(cropped, it, Core.ROTATE_90_CLOCKWISE) }
-            180 -> Mat().also { Core.rotate(cropped, it, Core.ROTATE_180) }
-            270 -> Mat().also { Core.rotate(cropped, it, Core.ROTATE_90_COUNTERCLOCKWISE) }
-            else -> cropped
-        }
-        val outW = out.cols()
-        val outH = out.rows()
-        val params = MatOfInt(Imgcodecs.IMWRITE_JPEG_QUALITY, quality)
-        val ok = Imgcodecs.imwrite(outputPath, out, params)
-        if (out !== cropped) out.release()
-        cropped.release()
-        if (!ok) return null
-        return StitcherSnapshot(
-            panoramaPath = outputPath,
-            width = outW,
-            height = outH,
-            acceptedCount = acceptedCount,
-        )
-    }
-
-    private fun msSince(t0Nanos: Long): Double =
-        (System.nanoTime() - t0Nanos) / 1_000_000.0
-
-    companion object {
-        // v3 thresholds — relaxed match-count + inlier minimums for
-        // light-texture shelf scenes; tighter det range because the
-        // affine fit produces a much narrower legitimate scale band.
-        private const val MIN_OVERLAP_PCT = 10.0
-        private const val MAX_OVERLAP_PCT = 75.0
-        private const val MIN_MATCHES_ACCEPT = 10
-        private const val MIN_INLIER_RATIO_ACCEPT = 0.18
-        private const val HIGH_CONF_MATCHES = 60
-        private const val HIGH_CONF_INLIER_RATIO = 0.55
-        private const val ORB_MAX_FEATURES = 1000
-        private const val ORB_SCALE_FACTOR = 1.2f
-        private const val ORB_LEVELS = 8
-        private const val ORB_EDGE_THRESHOLD = 31
-        private const val LOWE_RATIO = 0.75f
-        private const val RANSAC_REPROJ_THRESH = 5.0
-        private const val HOM_DET_MIN = 0.7
-        private const val HOM_DET_MAX = 1.4
-    }
-}
-
-
-/// Helper for OpenCV's odd boundingRect signature on a binary mask.
-/// Wraps the mask's non-zero pixel coords as a MatOfPoint that
-/// `Imgproc.boundingRect` will accept.
-private fun MaskNonZeroContour(mask: Mat): org.opencv.core.MatOfPoint {
-    val locations = Mat()
-    Core.findNonZero(mask, locations)
-    if (locations.empty()) {
-        locations.release()
-        return org.opencv.core.MatOfPoint()
-    }
-    val pts = mutableListOf<Point>()
-    // findNonZero returns CV_32SC2 with N rows, 1 col.  Each entry is
-    // a (col, row) pair; build a point list for boundingRect.
-    val n = locations.rows()
-    val buf = IntArray(2)
-    for (i in 0 until n) {
-        locations.get(i, 0, buf)
-        pts.add(Point(buf[0].toDouble(), buf[1].toDouble()))
-    }
-    locations.release()
-    val out = org.opencv.core.MatOfPoint()
-    out.fromList(pts)
-    return out
-}
-
-
-// computeOverlapPct, stripFileScheme — same code as iOS's static helpers,
-// transcribed to Kotlin.
-
-internal fun computeOverlapPct(
-    deltaYaw: Double,
-    deltaPitch: Double,
-    fovHorizDegrees: Double,
-    fovVertDegrees: Double,
-): Double {
-    val absYaw = kotlin.math.abs(deltaYaw)
-    val absPitch = kotlin.math.abs(deltaPitch)
-    var fovH = fovHorizDegrees * Math.PI / 180.0
-    var fovV = fovVertDegrees * Math.PI / 180.0
-    if (fovH <= 1e-6) fovH = 65.0 * Math.PI / 180.0
-    if (fovV <= 1e-6) fovV = 50.0 * Math.PI / 180.0
-    val overlap = if (absYaw >= absPitch) {
-        1.0 - absYaw / fovH
-    } else {
-        1.0 - absPitch / fovV
-    }
-    return overlap.coerceIn(0.0, 1.0) * 100.0
-}
+// stripFileScheme — same code as iOS's static helper, transcribed to Kotlin.
 
 
 internal fun stripFileScheme(path: String): String =
     if (path.startsWith("file://")) path.removePrefix("file://") else path
 
 
-/// Quaternion → 3x3 rotation matrix, mirroring iOS `quaternionToRotationMat`.
-internal fun quaternionToRotationMat(qx0: Double, qy0: Double, qz0: Double, qw0: Double): Mat {
-    var qx = qx0; var qy = qy0; var qz = qz0; var qw = qw0
-    val n = kotlin.math.sqrt(qx*qx + qy*qy + qz*qz + qw*qw)
-    if (n > 1e-9) { qx /= n; qy /= n; qz /= n; qw /= n }
-    val r = Mat(3, 3, CvType.CV_64F)
-    r.put(0, 0, 1 - 2*(qy*qy + qz*qz)); r.put(0, 1, 2*(qx*qy - qw*qz));     r.put(0, 2, 2*(qx*qz + qw*qy))
-    r.put(1, 0, 2*(qx*qy + qw*qz));     r.put(1, 1, 1 - 2*(qx*qx + qz*qz)); r.put(1, 2, 2*(qy*qz - qw*qx))
-    r.put(2, 0, 2*(qx*qz - qw*qy));     r.put(2, 1, 2*(qy*qz + qw*qx));     r.put(2, 2, 1 - 2*(qx*qx + qy*qy))
-    return r
-}
-
-
 // `sensorRotationMatrix` was removed in V7 — the rotation chain it
 // powered is no longer in the homography path.  See iOS' equivalent.