react-native-image-stitcher 0.15.2 → 0.16.1

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

@@ -420,7 +420,7 @@ class IncrementalStitcher(
             // stalled scan still advances).  iOS parity:
             // IncrementalStitcher.swift maxKeyframeIntervalMs block.
             val maxKfIntervalMs = configOverrides
-                ?.getDoubleOrDefault("maxKeyframeIntervalMs", 2000.0) ?: 2000.0
+                ?.getDoubleOrDefault("maxKeyframeIntervalMs", 1500.0) ?: 1500.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
@@ -633,7 +633,8 @@ class IncrementalStitcher(
         val wasBatchKeyframe = batchKeyframeMode
         val keyframePathsSnapshot = batchKeyframePaths.toList()
         val captureOrientationSnapshot = batchCaptureOrientation
-        val warperTypeSnapshot = batchWarperType
+        // batchWarperType (settings) is superseded by the high-level warper tree
+        // (pickHighLevelWarper) below — kept as a field for back-compat, unused here.
         val blenderTypeSnapshot = batchBlenderType
         val seamFinderTypeSnapshot = batchSeamFinderType
         val useInscribedRectCropSnapshot = batchUseInscribedRectCrop
@@ -664,11 +665,31 @@ class IncrementalStitcher(
         // falls back to pose data only.  Always non-negative.
         val imuTranslationMetres = (options.getDoubleOrDefault("imuTranslationMetres", 0.0) ?: 0.0)
             .coerceAtLeast(0.0)
+        // Resolve once so the dev readout gets the SAME tMeters / ratio / rRadians
+        // that drove the decision — and gets them even when the mode was forced
+        // (informative: shows what auto WOULD have picked).
+        val autoResolution = resolveStitchModeAuto(firstPose, lastPose, imuTranslationMetres)
         val stitchModeResolved: String = when (batchStitchMode) {
             "panorama" -> "panorama"
             "scans"    -> "scans"
-            else -> resolveStitchModeAuto(firstPose, lastPose, imuTranslationMetres)
+            else -> autoResolution.mode
         }
+        // Surface the gyro rotation + translation + decision ratio for EVERY
+        // capture (the forced modes skip the auto decision, but the dev preview
+        // still reads these to tune the panorama-vs-SCANS threshold).
+        val rRadiansResolved: Double = autoResolution.rRadians
+        val tMetersResolved: Double = autoResolution.tMeters
+        val decisionRatioResolved: Double = autoResolution.ratio
+        // 2026-06-16 — HIGH-LEVEL ACROSS THE BOARD.  Pick the warper from the
+        // (motion, Mode A/B, zoom) tree and always run cv::Stitcher PANORAMA
+        // (useManualPipeline=false at the stitchSync call below).  stitchModeResolved
+        // is now only the MOTION classifier feeding the tree + the dev readout;
+        // the actual stitch mode is always panorama.  Zoom comes from the EXPLICIT
+        // lens label the user selected ('1x'|'0.5x') — the reliable signal (FOV
+        // from intrinsics was unreliable: multi-cam 0.5x doesn't change fx, and
+        // the non-AR path may supply fx=0 → FOV defaulted to 65° → never 0.5x).
+        val lensOpt = options.getString("lens") ?: "1x"
+        val highLevelWarper = pickHighLevelWarper(captureOrientationSnapshot, lensOpt)
         android.util.Log.i(
             "IncrementalStitcher",
             "finalize stitch-mode: configured=$batchStitchMode resolved=$stitchModeResolved " +
@@ -714,12 +735,13 @@ class IncrementalStitcher(
                         keyframePathsSnapshot.toTypedArray(),
                         outputPath,
                         quality,
-                        warperTypeSnapshot,
+                        highLevelWarper,                 // tree-chosen (was batchWarperType)
                         blenderTypeSnapshot,
                         seamFinderTypeSnapshot,
                         captureOrientationSnapshot,
                         useInscribedRectCropSnapshot,
-                        stitchMode = stitchModeResolved,
+                        stitchMode = "panorama",         // always high-level PANORAMA
+                        useManualPipeline = false,       // high level across the board
                     )
                     // 2026-05-15 (D) — dims layout from native JNI:
                     //   [0] width, [1] height, [2] framesRequested,
@@ -748,6 +770,35 @@ class IncrementalStitcher(
                     // resolved cv::Stitcher mode so JS can surface it
                     // on the output preview + debug toast.
                     map.putString("stitchModeResolved", stitchModeResolved)
+                    map.putDouble("rRadians", rRadiansResolved)
+                    // Dev tuning readout — translation magnitude + the auto
+                    // decision ratio that drove panorama-vs-SCANS.
+                    map.putDouble("tMeters", tMetersResolved)
+                    map.putDouble("decisionRatio", decisionRatioResolved)
+                    // 2026-06-15 (iOS parity) — the exact keyframe JPEG
+                    // paths used for this stitch, so JS can re-stitch
+                    // them ON DEMAND via refinePanorama (the high-level
+                    // preview tab) without enumerating the session dir.
+                    // Camera.tsx gates that tab on this array being
+                    // present, so without it the tab never appears on
+                    // Android (the bug this fixes).  Mirrors iOS'
+                    // FinalizePayload "batchKeyframePaths": payload.paths.
+                    val keyframePathsArray = Arguments.createArray()
+                    keyframePathsSnapshot.forEach { keyframePathsArray.pushString(it) }
+                    map.putArray("batchKeyframePaths", keyframePathsArray)
+                    // The orientation THIS stitch baked into the output.
+                    // The on-demand high-level re-stitch MUST pass the
+                    // same value back through refinePanorama or the
+                    // output comes out in raw sensor landscape (sideways)
+                    // — refinePanorama otherwise defaults to "portrait"
+                    // (no bake-rotation).  Mirrors iOS' FinalizePayload
+                    // "captureOrientation": payload.captureOrientation.
+                    map.putString("captureOrientation", captureOrientationSnapshot)
+                    // 2026-06-15 — DEV overlay parity with iOS: the stitcher's
+                    // runtime recipe (pipe/warp/route/seam/blend) so the Android
+                    // pill shows the same detail, not just mode/score/frames.
+                    val dbg = stitcher.lastDebugSummary
+                    if (dbg.isNotEmpty()) map.putString("debugSummary", dbg)
                 } else {
                     // The live engines (hybrid + firstwins/slit) and their
                     // auto-refine hook were archived in the 2026-06 batch-
@@ -851,36 +902,13 @@ class IncrementalStitcher(
         grayHeight: Int,
         grayStride: Int,
         onAccept: (targetPath: String) -> Boolean,
-        // 2026-05-21 (v0.3) — only required when batchKeyframeMode
-        // 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.  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: wrapped in `TransferredNV21` (audit #4A,
-        // v0.10.0).  The wrapper enforces single-use: the engine
-        // calls `.takeOnce()` on the producer thread before
-        // dispatching to `workScope`; subsequent attempts to extract
-        // the bytes throw.  Callers MUST construct a fresh
-        // `TransferredNV21` per frame and MUST NOT hand the same
-        // instance to two consumers (e.g., a sync gate-eval + an
-        // async workScope.launch).  The Frame Processor plugin and
-        // the AR camera view both allocate fresh NV21 arrays per
-        // frame; the wrapper is a defensive-programming guard.
-        nv21PixelData: TransferredNV21? = null,
-        nv21PixelWidth: Int = 0,
-        nv21PixelHeight: Int = 0,
+        // 2026-06-16 (audit #8/L3) — the live-engine ingest params
+        // (legacyJpegPath / nv21PixelData / nv21PixelWidth/Height) were
+        // removed here.  The live engines were archived in 2026-06, so the
+        // only remaining path is batch-keyframe (always on), which ingests via
+        // `grayData` + `onAccept`.  The TransferredNV21 ownership wrapper had no
+        // live consumer (takeOnce() called nowhere — verified by grep) and is
+        // deleted along with these params.
     ) {
         // ── V16 batch-keyframe: AR-driven path ─────────────────────
         //
@@ -1189,21 +1217,6 @@ 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`).
-            //
-            // v0.10.0 audit #4A — wrap in TransferredNV21 so the
-            // engine takes ownership exactly once on the producer
-            // thread (engine calls `.takeOnce()` before workScope).
-            // Misuse (handing this same instance to two consumers)
-            // throws at the second `.takeOnce()` site, not silently
-            // corrupting frames.
-            nv21PixelData = TransferredNV21(nv21Bytes),
-            nv21PixelWidth = width,
-            nv21PixelHeight = height,
             onAccept = { targetPath ->
                 // Synchronous JPEG encode via the existing
                 // YuvImageConverter (also used by RNSARCameraView's
@@ -1493,6 +1506,15 @@ class IncrementalStitcher(
             config?.getBooleanOrDefault("useInscribedRectCrop", false) ?: false
         val stitchMode = (config?.getString("stitchMode") ?: "auto")
             .let { if (it in setOf("auto", "panorama", "scans")) it else "auto" }
+        // 2026-06-15 — pipeline is caller-selectable (mirrors iOS'
+        // refinePanorama `refineManual`).  The on-demand HIGH-LEVEL
+        // preview tab (Camera.tsx requestHighLevelAlt) calls
+        // refinePanorama with useManualPipeline:false to re-stitch the
+        // captured keyframes via stock cv::Stitcher.  Default false
+        // (high-level) preserves the refine path's historical
+        // cv::Stitcher behaviour.
+        val useManualPipeline =
+            config?.getBooleanOrDefault("useManualPipeline", false) ?: false
         val jpegQuality = max(1, min(100,
             config?.getIntOrDefault("jpegQuality", 90) ?: 90))
 
@@ -1538,9 +1560,18 @@ class IncrementalStitcher(
                     warperType,
                     blenderType,
                     seamFinderType,
+                    // captureOrientation flows through so the high-level
+                    // re-stitch bakes the SAME rotation the capture used
+                    // — without it the output is sideways (raw sensor
+                    // landscape).  The high-level tab passes back the
+                    // orientation the finalize emitted.
                     captureOrientation,
                     useInscribedRectCrop,
                     stitchMode = effectiveMode,
+                    // false = stock high-level cv::Stitcher (the on-demand
+                    // HIGH-LEVEL preview tab); true would force the manual
+                    // pipeline.  Sourced from the JS config above.
+                    useManualPipeline = useManualPipeline,
                 )
                 // Stitch returned — BatchStitcher writes the JPEG
                 // synchronously, so "writing" reflects the final
@@ -1568,6 +1599,10 @@ class IncrementalStitcher(
                     putInt("framesIncluded", framesIncluded)
                     putInt("framesDropped", framesRequested - framesIncluded)
                     putDouble("finalConfidenceThresh", finalConfidenceThresh)
+                    // DEV overlay — the high-level re-stitch's recipe so the
+                    // pill shows pipe/warp/route/seam/blend on the high-level tab.
+                    val dbg = stitcher.lastDebugSummary
+                    if (dbg.isNotEmpty()) putString("debugSummary", dbg)
                 }
                 emitRefineProgress(
                     stage = "done",
@@ -1649,44 +1684,70 @@ class IncrementalStitcher(
      * via `task_info(TASK_VM_INFO)` — see
      * `IncrementalStitcherBridge.swift:231-259`).
      *
-     * Returns the **total PSS** (proportional set size) of this
-     * process in MB.  PSS is the metric Android's Low-Memory-Killer
-     * (`lmkd`) ranks against, so it's the right one-true-number for
-     * the on-screen memory pill: it's "how close are we to being
-     * killed by the system?".
+     * Returns the process **RSS** (resident set size) in MB, read from
+     * `/proc/self/statm` (resident-pages × page-size).  RSS is what the shared
+     * C++ `[memstat]` lines report (`rss_mb()` reads the same `/proc`), so the
+     * pill and the stitch logs show the SAME number — handy when correlating a
+     * spike with a logcat trace.
      *
-     * Total PSS = USS (private) + sum(shared / refcount).  Read via
-     * `ActivityManager.getProcessMemoryInfo()`, which is the same API
-     * Android Studio's profiler uses.  Granularity is 1 KB; we
-     * divide by 1024 to MB so the JS side displays a number directly
-     * comparable to the iOS phys_footprint value.
+     * Why not `ActivityManager.getProcessMemoryInfo().totalPss`?  It's
+     * RATE-LIMITED on Android 8+ (returns a cached value when polled often), so
+     * at the pill's 500 ms cadence it froze at the launch-time reading and never
+     * moved.  `/proc/self/statm` is a single unthrottled read.
      *
-     * Returns -1.0 on failure (very rare — `getProcessMemoryInfo()`
-     * is generally infallible since Android 5.0 because PSS is read
-     * from `/proc/self/smaps` synchronously on the calling thread).
+     * Returns -1.0 on failure (very rare — `/proc/self/statm` is always present
+     * and cheap to read on the calling thread).
      */
     @ReactMethod
     fun getMemoryFootprintMB(promise: Promise) {
         try {
-            val am = reactContext.getSystemService(ActivityManager::class.java)
-            if (am == null) {
-                promise.resolve(-1.0)
-                return
-            }
-            val pid = android.os.Process.myPid()
-            val infos = am.getProcessMemoryInfo(intArrayOf(pid))
-            if (infos == null || infos.isEmpty()) {
+            // Read RSS from /proc/self/statm (field[1] = resident pages).  This
+            // is UNTHROTTLED and matches the C++ [memstat] rss_mb() in logcat, so
+            // the pill tracks the same number I read from the stitch logs.
+            //
+            // 2026-06-15 — was ActivityManager.getProcessMemoryInfo().totalPss,
+            // which is RATE-LIMITED on Android 8+: polled frequently (the pill
+            // ticks every 500 ms) it returns a CACHED value, so the pill froze at
+            // its launch-time reading (~310 MB) and never showed the stitch spike.
+            val fields = java.io.File("/proc/self/statm")
+                .readText().trim().split(' ')
+            val residentPages = fields[1].toLong()
+            val pageSize =
+                android.system.Os.sysconf(android.system.OsConstants._SC_PAGESIZE)
+            val mb = residentPages.toDouble() * pageSize.toDouble() /
+                (1024.0 * 1024.0)
+            promise.resolve(mb)
+        } catch (t: Throwable) {
+            android.util.Log.w(
+                "IncrementalStitcher",
+                "getMemoryFootprintMB: failed: ${t.message}",
+            )
+            promise.resolve(-1.0)
+        }
+    }
+
+    /**
+     * Total physical RAM in MB.  Lets the DEV memory pill derive RAM-aware
+     * pressure bands instead of the iPhone-fixed 1500/2200 MB thresholds (which
+     * never trip on a 4 GB Android phone that jetsams ~1.3 GB — false comfort).
+     * Reads `_SC_PHYS_PAGES × _SC_PAGE_SIZE` (TOTAL + stable across runs, unlike
+     * the rate-limited ActivityManager path).  -1.0 on failure.
+     */
+    @ReactMethod
+    fun getDeviceTotalRamMB(promise: Promise) {
+        try {
+            val pages = android.system.Os.sysconf(android.system.OsConstants._SC_PHYS_PAGES)
+            val pageSize =
+                android.system.Os.sysconf(android.system.OsConstants._SC_PAGESIZE)
+            if (pages <= 0 || pageSize <= 0) {
                 promise.resolve(-1.0)
                 return
             }
-            // totalPss is in KB.  Divide by 1024 → MB.  Use Double so
-            // the JS overlay can render fractional MB if it wants.
-            val mb = infos[0].totalPss.toDouble() / 1024.0
-            promise.resolve(mb)
+            promise.resolve(pages.toDouble() * pageSize.toDouble() / (1024.0 * 1024.0))
         } catch (t: Throwable) {
             android.util.Log.w(
                 "IncrementalStitcher",
-                "getMemoryFootprintMB: failed: ${t.message}",
+                "getDeviceTotalRamMB: failed: ${t.message}",
             )
             promise.resolve(-1.0)
         }
@@ -1883,6 +1944,24 @@ class IncrementalStitcher(
      *
      * Returns "panorama" or "scans" — never "auto".
      */
+    /**
+     * Result of [resolveStitchModeAuto]: the chosen mode PLUS the gyro rotation
+     * magnitude that drove the decision.  rRadians is surfaced to JS (the dev
+     * 3-tab preview shows it) so the panorama-vs-SCANS rotation threshold can be
+     * tuned from real captures.  rRadians is 0.0 only on the no-pose fallbacks
+     * (non-AR with no pose data) — there is no gyro-derived rotation to report.
+     */
+    private data class StitchModeResolution(
+        val mode: String,
+        val rRadians: Double,
+        // tMeters = translation magnitude (m) that fed the ratio; ratio = the
+        // tScore/(tScore+rScore) decision value (>=0.55 → SCANS). Surfaced to the
+        // dev readout so the panorama-vs-SCANS threshold can be tuned from real
+        // captures, alongside rRadians.
+        val tMeters: Double,
+        val ratio: Double,
+    )
+
     private fun resolveStitchModeAuto(
         firstPose: DoubleArray?,
         lastPose: DoubleArray?,
@@ -1890,14 +1969,16 @@ class IncrementalStitcher(
         // translation in METRES.  Used as a fallback when pose-derived
         // translation is 0 (non-AR mode).
         imuTranslationMetres: Double = 0.0,
-    ): String {
+    ): StitchModeResolution {
         if (firstPose == null || lastPose == null) {
             // No pose data at all — fall back on the IMU signal.  IMU
             // > 5 cm hints SCANS; everything else hints PANORAMA.
-            return if (imuTranslationMetres > 0.05) "scans" else "panorama"
+            return StitchModeResolution(
+                if (imuTranslationMetres > 0.05) "scans" else "panorama", 0.0, 0.0, 0.0)
         }
         if (firstPose.size != 7 || lastPose.size != 7) {
-            return if (imuTranslationMetres > 0.05) "scans" else "panorama"
+            return StitchModeResolution(
+                if (imuTranslationMetres > 0.05) "scans" else "panorama", 0.0, 0.0, 0.0)
         }
 
         // Translation magnitude (Euclidean, in metres) — pose-derived.
@@ -1917,11 +1998,7 @@ class IncrementalStitcher(
         // conventions; rotated by the pose quaternion gives the world-
         // frame forward direction.  Angle between the first and last
         // camera-forward vectors is the total rotation around any axis.
-        val fwdFirst = qrotForward(firstPose[3], firstPose[4], firstPose[5], firstPose[6])
-        val fwdLast = qrotForward(lastPose[3], lastPose[4], lastPose[5], lastPose[6])
-        val dot = (fwdFirst[0] * fwdLast[0] + fwdFirst[1] * fwdLast[1] + fwdFirst[2] * fwdLast[2])
-            .coerceIn(-1.0, 1.0)
-        val rRadians = kotlin.math.acos(dot)
+        val rRadians = rotationRadians(firstPose, lastPose)
 
         // Normalisation: 10 cm of translation ≈ 1 rad of rotation as
         // "equivalent magnitude" for the ratio.  Empirically: shelf
@@ -1932,18 +2009,74 @@ class IncrementalStitcher(
         val tScore = tMeters / 0.10
         val rScore = rRadians / 1.00
         val denom = tScore + rScore
-        if (denom <= 1e-9) return "panorama"  // no motion either way
+        if (denom <= 1e-9) return StitchModeResolution("panorama", rRadians, tMeters, 0.0)  // no motion
         val ratio = tScore / denom
 
+        // 2026-06-15 — LOW-ROTATION GUARD.  The gyro rotation (rRadians) is
+        // trustworthy; the IMU translation (tMeters, in non-AR) is NOT — a
+        // continuous rotation leaks gravity into the double-integrated accel and
+        // inflates it, which can falsely push `ratio` over 0.55 → SCANS, whose
+        // affine warper can't represent the rotation.  So when the gyro shows a
+        // clear pan (> ~20°) with only modest translation, force PANORAMA
+        // regardless of the (possibly-inflated) translation.  Genuine shelf
+        // scans (low rotation, large real translation) skip this and still
+        // reach SCANS via the ratio.  (Conservative: keeps the tMeters cap so a
+        // genuine large-translation capture isn't forced to PANORAMA.)
+        val lowRotationGuard = rRadians > 0.35 && tMeters < 0.25
+        val mode = if (!lowRotationGuard && ratio >= 0.55) "scans" else "panorama"
         android.util.Log.i(
             "IncrementalStitcher",
             "stitch-mode auto: tPose=${"%.3f".format(tPose)}m " +
                 "tImu=${"%.3f".format(imuTranslationMetres)}m " +
                 "r=${"%.3f".format(rRadians)}rad " +
                 "ratio=${"%.3f".format(ratio)} " +
-                "→ ${if (ratio >= 0.55) "scans" else "panorama"}",
+                "rotGuard=$lowRotationGuard → $mode",
         )
-        return if (ratio >= 0.55) "scans" else "panorama"
+        return StitchModeResolution(mode, rRadians, tMeters, ratio)
+    }
+
+    /**
+     * 2026-06-16 — high-level warper decision tree (the pipeline is now ALWAYS
+     * high-level cv::Stitcher PANORAMA — useManualPipeline=false).  Warper is a
+     * pure function of (lens, pan direction); the rotation-vs-translation
+     * (ex-SCANS) distinction was DROPPED as redundant — at 1x the same
+     * direction-based warpers serve both, and 0.5x is always spherical.  Inputs:
+     *   orientation = capture hold ("landscape*" = Mode A vertical pan;
+     *                 "portrait*" = Mode B horizontal pan)
+     *   lens        = the EXPLICIT lens the user selected ("0.5x" ultra-wide |
+     *                 "1x" wide).  Reliable zoom signal (FOV-from-intrinsics was
+     *                 unreliable — multi-cam 0.5x reaches the ultra-wide by zoom
+     *                 without changing fx, and the non-AR path may supply fx=0).
+     *
+     *     0.5x ultra-wide          → spherical   (bounded both axes; any pan)
+     *     1x + Mode A (vertical)   → plane
+     *     1x + Mode B (horizontal) → cylindrical
+     *
+     * Quality-preferred warper; the C++ memory ladder force-falls to spherical
+     * (and downscales compositingResol) under pressure.
+     */
+    private fun pickHighLevelWarper(
+        orientation: String,
+        lens: String,
+    ): String {
+        if (lens == "0.5x") return "spherical"                // ultra-wide → always spherical
+        val verticalPanModeA = orientation.startsWith("landscape")
+        return if (verticalPanModeA) "plane" else "cylindrical"  // 1x: A→plane, B→cylindrical
+    }
+
+    /**
+     * Gyro rotation magnitude (radians) between two 7-element poses
+     * `[tx,ty,tz,qx,qy,qz,qw]` — the angle between the camera-forward vectors.
+     * Returns 0.0 if either pose is missing/malformed (non-AR with no pose).
+     * Shared by [resolveStitchModeAuto] and the finalize `rRadians` readout (DRY).
+     */
+    private fun rotationRadians(firstPose: DoubleArray?, lastPose: DoubleArray?): Double {
+        if (firstPose == null || lastPose == null) return 0.0
+        if (firstPose.size != 7 || lastPose.size != 7) return 0.0
+        val f = qrotForward(firstPose[3], firstPose[4], firstPose[5], firstPose[6])
+        val l = qrotForward(lastPose[3], lastPose[4], lastPose[5], lastPose[6])
+        val dot = (f[0] * l[0] + f[1] * l[1] + f[2] * l[2]).coerceIn(-1.0, 1.0)
+        return kotlin.math.acos(dot)
     }
 
     /**

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

@@ -151,7 +151,7 @@ internal class KeyframeGate : AutoCloseable {
     /// initializer below does NOT fire this setter, so the caller
     /// (IncrementalStitcher.kt) writes it explicitly at capture start
     /// to push the value into C++ (same contract as the iOS facade).
-    var maxKeyframeIntervalMs: Double = 2000.0
+    var maxKeyframeIntervalMs: Double = 1500.0
         set(value) {
             field = value
             nativeSetMaxKeyframeIntervalMs(nativeHandle, value)

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

@@ -612,26 +612,13 @@ class RNSARCameraView @JvmOverloads constructor(
         val rotationForEncode = if (lastDisplayRotation >= 0)
             lastDisplayRotation else android.view.Surface.ROTATION_0
 
-        // F8.6 (v0.6) — the eager JPEG encode for live-engine mode
-        // is gone.  Pass the already-packed NV21 directly via
-        // `nv21PixelData`; the engine's new `addFramePixelData`
-        // path builds the BGR cv::Mat in-process via cvtColor,
-        // skipping the JPEG decode round-trip downstream.  In
-        // batch-keyframe mode the engine ignores `nv21PixelData`
-        // (it uses `grayData` + `onAccept` lazily); no behaviour
-        // change there.
-        //
-        // (Was: eager JPEG encode for non-batch-keyframe modes,
-        //  written to `tmpJpegFile`, passed as `legacyJpegPath`.
-        //  See the v0.3 / F8.6 entries in CHANGELOG.md.)
-        //
-        // Synchronous engine ingest.  The ARCore Image ownership
-        // contract requires the engine to consume the TransferredNV21
-        // before ARCore recycles the Image, so this runs inline.  Only
-        // ingest when the host has actively engaged capture
-        // (`setIncrementalIngestionActive(true)`).  (The v0.8.0 worklet-
-        // runtime `runFirstParty` indirection + host-worklet fan-out
-        // were archived in the 2026-06 batch-keyframe cleanup.)
+        // Batch-keyframe ingest.  The gate reads the Y plane of the packed
+        // NV21 synchronously (grayData) and the lazy onAccept JPEG-encodes only
+        // accepted frames — no eager encode, no live-engine pixel-data path
+        // (the live engines + the TransferredNV21 ownership wrapper were removed
+        // in the 2026-06 cleanup; see audit #8).  Runs inline so the gate read
+        // completes before ARCore recycles the Image.  Only ingest when the host
+        // has actively engaged capture (`setIncrementalIngestionActive(true)`).
         if (ingestActive) {
         module.ingestFromARCameraView(
             tx = tArr[0].toDouble(),
@@ -654,22 +641,6 @@ class RNSARCameraView @JvmOverloads constructor(
             grayWidth = packed.width,
             grayHeight = packed.height,
             grayStride = packed.width,
-            legacyJpegPath = null,
-            // F8.6 — pixel-data path for live engines.  Batch-
-            // keyframe mode ignores these (bails earlier).
-            //
-            // v0.10.0 audit #4A — wrap `packed.nv21` in
-            // TransferredNV21 so ownership is enforced at runtime.
-            // The AR caller passes the SAME `packed.nv21` array as
-            // both `grayData` (sync, gate-eval read) and
-            // `nv21PixelData` (async, engine ingest).  Today no race
-            // because grayData is consumed inside evaluateWithFrame
-            // before workScope.launch fires; the wrapper makes a
-            // future refactor that reorders consumption fail loudly
-            // instead of silently corrupting frames.
-            nv21PixelData = TransferredNV21(packed.nv21),
-            nv21PixelWidth = packed.width,
-            nv21PixelHeight = packed.height,
             onAccept = { targetPath ->
                 // Lazy JPEG encode.  Runs ONLY if the C++ KeyframeGate
                 // accepted the frame.  Encodes from the pre-packed

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

@@ -860,21 +860,27 @@ class RNSARSession(reactContext: ReactApplicationContext)
             if (configs.isEmpty()) return
             fun aspect(s: android.util.Size): Float = s.width.toFloat() / s.height.toFloat()
 
-            val matched = configs.filter {
-                kotlin.math.abs(aspect(it.imageSize) - aspect(it.textureSize)) < 0.02f
-            }
-            val pool = if (matched.isNotEmpty()) matched else configs
-            val chosen = pool.sortedWith(
+            // Option B (max FOV + bounded memory): prefer the 4:3-aspect
+            // IMAGE for full vertical sensor FOV, regardless of texture aspect
+            // (the A35 only pairs its 4:3 image with a 16:9 texture, so an
+            // aspect-MATCH filter would force 16:9 and lose that FOV).  Among
+            // 4:3 images prefer the SMALLEST resolution — the keyframe is
+            // downscaled to AR_KEYFRAME_MAX_LONG_EDGE anyway, so smallest is
+            // closest to that budget + cheapest.  Device-agnostic: any
+            // device's 4:3 image is chosen, then normalised by the downscale
+            // guard in YuvImageConverter.  Trade-off: the 16:9 preview texture
+            // shows less than the 4:3 capture (accepted for max FOV).
+            val chosen = configs.sortedWith(
                 compareBy<CameraConfig> { kotlin.math.abs(aspect(it.imageSize) - 4f / 3f) }
-                    .thenByDescending { it.imageSize.width * it.imageSize.height },
+                    .thenBy { it.imageSize.width * it.imageSize.height },
             ).firstOrNull() ?: return
             session.setCameraConfig(chosen)
             Log.i(
                 TAG,
-                "selectMatchingCameraConfig: chose image=" +
+                "selectMatchingCameraConfig: chose 4:3-pref image=" +
                     "${chosen.imageSize.width}x${chosen.imageSize.height} texture=" +
                     "${chosen.textureSize.width}x${chosen.textureSize.height} " +
-                    "(from ${configs.size} configs, ${matched.size} aspect-matched)",
+                    "(from ${configs.size} configs)",
             )
         } catch (t: Throwable) {
             Log.w(TAG, "selectMatchingCameraConfig failed; keeping default config: ${t.message}")

package/android/src/main/java/io/imagestitcher/rn/ar/YuvImageConverter.kt

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 package io.imagestitcher.rn.ar
 
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
 import android.graphics.ImageFormat
 import android.graphics.Rect
 import android.graphics.YuvImage
@@ -10,6 +12,14 @@ import androidx.exifinterface.media.ExifInterface
 import java.io.ByteArrayOutputStream
 import java.io.File
 import java.io.FileOutputStream
+import kotlin.math.max
+import kotlin.math.roundToInt
+
+/** AR keyframe long-edge budget (px).  Every device's acquired AR frame is
+ *  downscaled to this before the keyframe JPEG is written, so the stitch
+ *  held-set (and thus memory) is consistent across devices regardless of
+ *  their ARCore 4:3 image resolution.  Matches the non-AR keyframe size. */
+private const val AR_KEYFRAME_MAX_LONG_EDGE = 640
 
 /**
  * Convert an ARCore `Image` (YUV_420_888) to a JPEG file on disk.
@@ -221,8 +231,36 @@ internal object YuvImageConverter {
             baos,
         )
         if (!ok) return null
+        // AR keyframe downscale guard — normalise the long edge to
+        // AR_KEYFRAME_MAX_LONG_EDGE so every device (whatever its ARCore 4:3
+        // image resolution) writes the same ~0.3 MP keyframe -> consistent
+        // stitch memory cross-device.  Only the SAVED keyframe is scaled; the
+        // C++ keyframe gate already ran on the full-res Y plane upstream.
+        var jpegBytes = baos.toByteArray()
+        if (max(packed.width, packed.height) > AR_KEYFRAME_MAX_LONG_EDGE) {
+            val src = BitmapFactory.decodeByteArray(jpegBytes, 0, jpegBytes.size)
+            if (src != null) {
+                val scale =
+                    AR_KEYFRAME_MAX_LONG_EDGE.toFloat() / max(src.width, src.height)
+                val dst = Bitmap.createScaledBitmap(
+                    src,
+                    (src.width * scale).roundToInt().coerceAtLeast(1),
+                    (src.height * scale).roundToInt().coerceAtLeast(1),
+                    true,
+                )
+                val baos2 = ByteArrayOutputStream()
+                dst.compress(
+                    Bitmap.CompressFormat.JPEG,
+                    jpegQuality.coerceIn(1, 100),
+                    baos2,
+                )
+                jpegBytes = baos2.toByteArray()
+                if (dst !== src) dst.recycle()
+                src.recycle()
+            }
+        }
         try {
-            FileOutputStream(File(outputPath)).use { it.write(baos.toByteArray()) }
+            FileOutputStream(File(outputPath)).use { it.write(jpegBytes) }
         } catch (e: Throwable) {
             return null
         }