react-native-image-stitcher 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -14,6 +14,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > during 0.x are bumped to a new MINOR (e.g., 0.1 → 0.2), and the
 > upgrade path is documented in this CHANGELOG.
 
+## [0.16.1] — 2026-06-16
+
+### Changed — high-level `cv::Stitcher` is now the default pipeline
+
+The batch finalize now drives OpenCV's high-level `cv::Stitcher`
+(PANORAMA) on both platforms instead of the hand-rolled `cv::detail`
+("manual") path.  In testing it produced consistently better seams and
+lower, more stable peak memory.  This is a **behaviour change, not an
+API change** — the public surface (`<Camera>`, the hooks, the finalize
+options) is unchanged; only the stitched output and memory profile
+differ.
+
+The warper is chosen per-capture (pure function of the selected lens +
+pan direction), always `PANORAMA`:
+
+| Lens  | Mode A (vertical pan) | Mode B (horizontal pan) |
+| ----- | --------------------- | ----------------------- |
+| 1×    | plane                 | cylindrical             |
+| 0.5×  | spherical             | spherical               |
+
+The lens comes from the explicit `1x` / `0.5x` the user selected
+(plumbed through the finalize options); the previous FOV-from-intrinsics
+heuristic was unreliable on multi-camera devices and is gone, along with
+the now-redundant rotation-vs-translation (ex-SCANS) branch.
+
+### Added — production memory hardening on the high-level path
+
+The OOM guards that previously only covered the manual path were ported
+across, so the new default is memory-safe under pressure:
+
+- pre-stitch RSS headroom abort (also works on iOS now via the
+  `phys_footprint` probe, which revives the runtime-pressure router);
+- RAM-aware compositing resolution;
+- two-phase `estimateTransform` → project the warp canvas → abort if
+  degenerate, downscale or route to the bounded spherical warper if
+  over budget;
+- a full C++ catch ladder + a JNI backstop so an allocation failure can
+  no longer cross the C-ABI and abort the process;
+- a warper→spherical rescue (high-level) with the manual `PANORAMA` ↔
+  `SCANS` mode-fallback preserved for the iOS manual callers.
+
+### Fixed
+
+- The native allocator is purged after each stitch, and on Android the
+  OpenCV worker pool is pinned to one thread, eliminating the per-stitch
+  RSS creep observed on the manual path.
+
 ## [0.16.0] — 2026-06-15
 
 ### Added — first-time-user panorama capture GUIDANCE

package/README.md

@@ -353,21 +353,32 @@ omitted keys fall back to the English default. This covers the rotate prompt,
 the pan hint, the live "too fast" cue, the lateral-drift popups, the crop-editor
 buttons, the **capture-status banner**, and the **crop-editor warning banners**:
 
-| Key | Group | English default |
+Each default is the **exact, complete** source string — translate it verbatim
+(keep the `{included}` / `{requested}` / `{percent}` placeholders in
+`warnLowFrameUtilization`), or `import { DEFAULT_GUIDANCE_COPY }` to seed your
+catalogue programmatically.
+
+| Key | Where it appears | English default (translate verbatim) |
 | --- | --- | --- |
 | `rotateToLandscape` | rotate prompt | `Rotate to landscape` |
 | `rotateToPortrait` | rotate prompt | `Rotate to portrait` |
-| `panHint` | pan how-to | `Pan slowly top to bottom` |
-| `tooFast` | speed cue | `Moving too fast — slow down` |
-| `lateralStopTitle` / `lateralStopBody` / `lateralStopDismiss` | lateral popup (stitched) | `Keep the pan straight` / … / `Got it` |
-| `lateralWrongDirectionTitle` / `lateralWrongDirectionBody` | lateral popup (too few frames) | `Follow the arrow` / … |
-| `cropConfirm` / `cropReset` / `cropUseOriginal` / `cropRetake` | crop buttons | `Crop` / `Reset` / `Use original` / `Retake` |
-| `previewConfirm` | preview-only accept button (`showPreview`) | `Confirm` |
+| `panHint` | pan how-to overlay | `Pan slowly top to bottom` |
+| `tooFast` | speed-cue pill | `Moving too fast — slow down` |
+| `lateralStopTitle` | lateral-drift popup (stitched) | `Keep the pan straight` |
+| `lateralStopBody` | lateral-drift popup (stitched) | `You moved sideways. Pan in one direction only — we stitched what you captured.` |
+| `lateralStopDismiss` | lateral-drift popup button | `Got it` |
+| `lateralWrongDirectionTitle` | lateral-drift popup (too few frames) | `Follow the arrow` |
+| `lateralWrongDirectionBody` | lateral-drift popup (too few frames) | `You moved the phone the wrong way. Pan slowly in the direction the arrow shows, in one straight line.` |
+| `cropConfirm` | crop-editor button | `Crop` |
+| `cropReset` | crop-editor button | `Reset` |
+| `cropUseOriginal` | crop-editor button | `Use original` |
+| `cropRetake` | crop-editor button | `Retake` |
+| `previewConfirm` | preview accept button (`showPreview`) | `Confirm` |
 | `statusRecording` | status banner | `Hold steady — pan slowly` |
 | `statusStitching` | status banner | `Stitching panorama…` |
-| `warnLowFrameUtilization` | crop warning **(template)** | `Only {included} of {requested} captured frames ({percent}%) could be used — …` |
-| `warnLateralDriftFinalize` | crop warning | `Capture stopped early because the phone drifted sideways — …` |
-| `warnHighPanSpeed` | crop warning | `The capture was taken faster than the recommended pace — …` |
+| `warnLowFrameUtilization` | crop warning **(template)** | `Only {included} of {requested} captured frames ({percent}%) could be used — the panorama may be incomplete. Pan more slowly and steadily next time.` |
+| `warnLateralDriftFinalize` | crop warning | `Capture stopped early because the phone drifted sideways — only the part captured before the drift was stitched.` |
+| `warnHighPanSpeed` | crop warning | `The capture was taken faster than the recommended pace — the result may not be the best. Pan more slowly next time.` |
 
 > **Templates:** `warnLowFrameUtilization` is interpolated at runtime — your
 > translation must keep the `{included}`, `{requested}` and `{percent}`
@@ -433,6 +444,10 @@ function CaptureScreen() {
 seed your translation catalogue from the source strings, and
 `RECOVERABLE_STITCH_GUIDANCE` exposes the built-in error copy for the same reason.
 
+> **Full worked example** — a Spanish `es.json` catalogue (both surfaces) plus a
+> host language-setting that switches the copy at runtime: see the
+> [Internationalization guide](https://bhargavkanda.github.io/react-native-image-stitcher/docs/i18n#worked-example-spanish-with-a-dynamic-language-setting).
+
 ### Migration from 0.13.x
 
 - **Removed:** the `panGuide` and `panoramaGuidance` props (the

package/android/src/main/cpp/image_stitcher_jni.cpp

@@ -97,7 +97,11 @@ double procRssMB() {
         * static_cast<double>(sysconf(_SC_PAGE_SIZE)) / (1024.0 * 1024.0);
 }
 
-void purgeNativeAllocator() {
+// Returns the POST-purge RSS in MB (the leak-plateau "floor"), or -1 when the
+// diagnostic reads are gated off.  The mallopt(M_PURGE) CALL is UNCONDITIONAL —
+// it's the leak fix; only its before/after READS + the log are gated (3A), so a
+// release build pays nothing while debug builds surface memFloor.
+double purgeNativeAllocator(bool profiling) {
     using MalloptFn = int (*)(int, int);
     // Resolve mallopt at runtime (API-26 symbol; minSdk 24).  Prefer an explicit
     // libc.so handle — RTLD_DEFAULT from a dlopen'd .so doesn't always reach
@@ -108,8 +112,9 @@ void purgeNativeAllocator() {
         if (s == nullptr) s = dlsym(RTLD_DEFAULT, "mallopt");
         return reinterpret_cast<MalloptFn>(s);
     }();
-    const double before = procRssMB();
-    if (fn != nullptr) fn(M_PURGE, 0);
+    const double before = profiling ? procRssMB() : -1.0;
+    if (fn != nullptr) fn(M_PURGE, 0);          // the fix — always runs
+    if (!profiling) return -1.0;
     const double after = procRssMB();
     // Diagnostic: shows whether mallopt resolved and how much RSS the purge
     // actually returned to the OS.  If mallopt=MISSING → dlsym failed; if
@@ -117,6 +122,7 @@ void purgeNativeAllocator() {
     // leak) and M_PURGE can't help.
     LOGI("[memstat] purge: mallopt=%s rss %.1f -> %.1f MB",
          (fn != nullptr) ? "ok" : "MISSING", before, after);
+    return after;  // memFloor — the post-purge plateau metric
 }
 
 }  // namespace
@@ -189,6 +195,9 @@ Java_io_imagestitcher_rn_BatchStitcher_nativeStitchFramePaths(
     // re-arms the manual pipeline's dynamic plane→spherical fallback/divergence
     // switch (they only fire when warperType != "spherical").
     cfg.useManualPipeline = (useManualPipeline == JNI_TRUE);
+    // 2026-06-16 — memory profiling (DEV).  Gated by the compile flag (debug-on,
+    // release-off); Android leaves memProbeFn null so rss_mb() uses /proc.
+    cfg.enableMemoryProfiling = (RNIS_MEMORY_PROFILING != 0);
     if (cfg.warperType.empty()) cfg.warperType = "spherical";
     if (cfg.registrationResolMP <= 0.0) {
         cfg.registrationResolMP = 0.6;
@@ -210,13 +219,49 @@ Java_io_imagestitcher_rn_BatchStitcher_nativeStitchFramePaths(
 
     const std::string outPath = jstring_to_string(env, outputPath);
 
-    retailens::StitchResult result = retailens::stitchFramePaths(
-        paths, outPath, cfg, &androidLogBridge);
+    // 2026-06-16 (review #1) — backstop try/catch at the JNI C-ABI boundary.
+    // stitchFramePaths now has its own catch ladders (high-level + manual), so
+    // this should never fire — but a C++ exception crossing into JNI is UB
+    // (std::terminate/SIGABRT), so we NEVER let one through: convert any escape
+    // into a Java exception the Kotlin layer can catch.
+    retailens::StitchResult result;
+    try {
+        result = retailens::stitchFramePaths(
+            paths, outPath, cfg, &androidLogBridge);
+    } catch (const std::exception& e) {
+        throw_runtime(env, std::string("native stitch crashed: ") + e.what());
+        return nullptr;
+    } catch (...) {
+        throw_runtime(env, "native stitch crashed (unknown exception)");
+        return nullptr;
+    }
 
     // Return the stitch's freed native memory to the OS so the native-heap RSS
     // baseline doesn't ratchet up ~10-15 MB per capture (see purgeNativeAllocator).
-    // Applies to BOTH pipelines (they share the OpenCV/bionic allocator).
-    purgeNativeAllocator();
+    // Applies to BOTH pipelines (they share the OpenCV/bionic allocator).  The
+    // post-purge RSS is the leak-plateau "floor" — append it to debugSummary so
+    // it rides the existing nativeLastDebugSummary() path to JS (no new bridge).
+    const double memFloor = purgeNativeAllocator(RNIS_MEMORY_PROFILING != 0);
+    if ((RNIS_MEMORY_PROFILING != 0) && memFloor >= 0.0) {
+        char fbuf[40];
+        std::snprintf(fbuf, sizeof(fbuf), ";memFloor=%.1f", memFloor);
+        if (!result.debugSummary.empty()) result.debugSummary += fbuf;
+        // 2026-06-16 — one authoritative per-stitch memory line to logcat (the
+        // sampler peak otherwise only rides debugSummary to the on-screen
+        // overlay).  pipe/warp/mode lets each line be attributed to a preview
+        // tab: pipe=manual warp=plane mode=panorama = "As captured" primary;
+        // pipe=highlevel warp=plane = HL·Plane; warp=spherical = HL·Sph;
+        // mode=scans = SCANS.  Grep `[memstat] record:` to harvest all of them.
+        LOGI("[memstat] record: pipe=%s warp=%s mode=%s before=%.1f peak=%.1f "
+             "after=%.1f floor=%.1f src=%s frames=%d/%d",
+             cfg.useManualPipeline ? "manual" : "highlevel",
+             cfg.warperType.c_str(),
+             (result.stitchModeUsed == retailens::StitchMode::Scans)
+                 ? "scans" : "panorama",
+             result.memBeforeMB, result.memPeakMB, result.memAfterMB, memFloor,
+             result.memSource.c_str(),
+             result.framesIncluded, result.framesRequested);
+    }
 
     if (!result.success) {
         const std::string msg = "Stitch failed: " + result.errorMessage +

package/android/src/main/cpp/keyframe_gate_jni.cpp

@@ -311,23 +311,30 @@ Java_io_imagestitcher_rn_KeyframeGate_nativeEvaluateWithFrame(
         }
     }
 
-    // Pin the byte[] for the duration of the gate evaluate.  Use
-    // GetPrimitiveArrayCritical (zero-copy, JVM pins the GC) over
-    // GetByteArrayElements (may copy on some VMs) because at 30-60
-    // Hz of 2 MB Y-planes, the copy cost adds up.  Evaluate is
-    // ~1-5 ms so the pin window is short.  Always paired with
-    // ReleasePrimitiveArrayCritical even on the error paths below.
+    // 2026-06-16 (audit #4) — pin the byte[] ONLY to INGEST it.
+    // GetPrimitiveArrayCritical is zero-copy (the JVM pins the GC) — preferred
+    // over GetByteArrayElements (which may copy a 2 MB Y-plane at 30-60 Hz) —
+    // but it blocks the GC for the pin's whole life.  So we keep that life to a
+    // single downscale: ingestWorkingFrame() reads the pinned bytes into an
+    // OWNED working frame, we Release IMMEDIATELY, then evaluateWithWorkingMat()
+    // runs the heavy OpenCV (goodFeaturesToTrack / optical flow) with the pin
+    // already gone — no longer stalling the GC or the frame-rate producer
+    // thread.  Always paired with ReleasePrimitiveArrayCritical, even on errors.
     retailens::KeyframeGateDecision d;
     if (grayBytes && grayWidth > 0 && grayHeight > 0 && grayStride >= grayWidth) {
         void* raw = env->GetPrimitiveArrayCritical(grayBytes, nullptr);
         if (raw) {
-            d = gate(handle)->evaluateWithFrame(
-                pose, planePtr,
+            gate(handle)->ingestWorkingFrame(
                 static_cast<const uint8_t*>(raw),
                 static_cast<int32_t>(grayWidth),
                 static_cast<int32_t>(grayHeight),
                 static_cast<int32_t>(grayStride));
             env->ReleasePrimitiveArrayCritical(grayBytes, raw, JNI_ABORT);
+            // Pin released — heavy OpenCV now runs outside the critical section.
+            d = gate(handle)->evaluateWithWorkingMat(
+                pose, planePtr,
+                static_cast<int32_t>(grayWidth),
+                static_cast<int32_t>(grayHeight));
         } else {
             // GetPrimitiveArrayCritical failed (rare, but defensive).
             // Fall back to pose-only path so we degrade gracefully

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

@@ -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,11 @@ 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
@@ -875,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 ─────────────────────
         //
@@ -1213,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
@@ -1737,6 +1726,33 @@ class IncrementalStitcher(
         }
     }
 
+    /**
+     * 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
+            }
+            promise.resolve(pages.toDouble() * pageSize.toDouble() / (1024.0 * 1024.0))
+        } catch (t: Throwable) {
+            android.util.Log.w(
+                "IncrementalStitcher",
+                "getDeviceTotalRamMB: failed: ${t.message}",
+            )
+            promise.resolve(-1.0)
+        }
+    }
+
     /**
      * Release the C++ KeyframeGate heap allocation when RN tears
      * down the bridge module (e.g. on a JS reload).  Without this,
@@ -1928,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?,
@@ -1935,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.
@@ -1962,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
@@ -1977,7 +2009,7 @@ 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
@@ -2000,7 +2032,51 @@ class IncrementalStitcher(
                 "ratio=${"%.3f".format(ratio)} " +
                 "rotGuard=$lowRotationGuard → $mode",
         )
-        return mode
+        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/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