react-native-image-stitcher 0.3.0 → 0.4.1

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

@@ -14,6 +14,25 @@ import java.io.FileOutputStream
 /**
  * Convert an ARCore `Image` (YUV_420_888) to a JPEG file on disk.
  *
+ * 2026-05-22 (audit follow-up #19) — split into two phases so callers
+ * can release the underlying ARCore `Image` ASAP:
+ *
+ *   1. `packNV21(image)`  — reads the Y/U/V planes into a contiguous
+ *      JVM-side `ByteArray` (NV21 layout).  Fast (~3 ms for 1920×1080).
+ *      The caller can close the `Image` IMMEDIATELY after this returns,
+ *      freeing the ARCore Camera2 ImageReader buffer.
+ *
+ *   2. `encodeJpegFromNV21(packed, …)` — does the slow YUV→JPEG
+ *      conversion (~10-25 ms) on the already-extracted bytes, NOT on
+ *      the Image.  Safe to run after the Image has been closed.
+ *
+ * The pre-#19 single-call `encodeToJpeg(image, …)` API is preserved as
+ * a thin wrapper for callers that don't care about Image hold time
+ * (e.g., one-shot photo capture).  Performance-critical paths
+ * (`RNSARCameraView.forwardToIncremental`, called at ~60 Hz on the
+ * GL render thread) should use the two-step API to keep Image hold
+ * times bounded by the ~3 ms pack step instead of the ~25 ms encode.
+ *
  * Why JPEG → file → re-decode by OpenCV (slightly wasteful)?
  *   The incremental engine's existing API (matching iOS') consumes
  *   image PATHS, not raw planes.  Threading raw YUV through the
@@ -22,56 +41,182 @@ import java.io.FileOutputStream
  *   next to the ~40 ms per-frame engine work — keeping the surface
  *   uniform across iOS / Android paths is worth the few-ms cost.
  *
- * `Image` ownership: caller MUST `image.close()` after this returns.
- * We don't close inside because the caller may want to inspect more
- * fields (timestamp, format) before releasing.
+ * `Image` ownership: the two-step API (`packNV21` + `encodeJpegFromNV21`)
+ * returns control to the caller after the pack step so the caller can
+ * close the Image at the right moment.  The legacy single-call
+ * `encodeToJpeg(image, …)` does NOT close the Image — caller is
+ * responsible for that.
  */
 internal object YuvImageConverter {
 
-    /// Convert + write JPEG.  Returns the path (no file:// prefix)
-    /// or null on any encode/write error (caller-decides whether to
-    /// log + drop the frame).
-    ///
-    /// 2026-05-15 (B3) — `displayRotation` parameter writes the
-    /// appropriate EXIF orientation tag so RN's Image loader (and
-    /// any other consumer that respects EXIF) displays the JPEG
-    /// upright regardless of how the device was held at capture.
-    ///
-    /// Without this, Android's image loaders display the raw sensor
-    /// pixels (typically landscape) as-is — so a portrait-held
-    /// capture's thumbnail appears sideways.  iOS's image loader
-    /// auto-respects EXIF orientation; Android's doesn't always
-    /// (depends on the loader path).  Setting the tag covers both.
-    ///
-    /// `displayRotation` should be the value returned from
-    /// `WindowManager.defaultDisplay.rotation` at capture time
-    /// (Surface.ROTATION_0/_90/_180/_270).  We assume a typical
-    /// back-camera sensor orientation of 90° — true for all
-    /// devices we ship to (Galaxy A35 verified).  Wire through
-    /// CameraCharacteristics.SENSOR_ORIENTATION in a follow-up
-    /// if we ever encounter a device that differs.
-    ///
-    /// Default `displayRotation = Surface.ROTATION_0` (portrait)
-    /// preserves the previous behaviour for legacy callsites that
-    /// haven't been updated yet.
-    fun encodeToJpeg(
-        image: Image,
+    /**
+     * Packed NV21 pixel data extracted from an ARCore `Image`.
+     * Once you hold one of these, the source `Image` can be closed —
+     * all subsequent operations work on the JVM-side byte array.
+     *
+     * NV21 layout (single contiguous byte array):
+     *   bytes [0 .. width*height)              = Y plane (luminance),
+     *                                            densely packed,
+     *                                            row stride = width
+     *   bytes [width*height .. width*height*3/2) = interleaved V-U pairs
+     *                                              at half resolution
+     *
+     * The Y plane portion can be passed directly to the C++
+     * `keyframe_gate` as grayscale pixels with `stride = width`.
+     */
+    data class PackedYuv(
+        val nv21: ByteArray,
+        val width: Int,
+        val height: Int,
+    ) {
+        /** Length of the Y plane portion (bytes [0 .. ySize)). */
+        val ySize: Int get() = width * height
+
+        // equals + hashCode override required because `nv21` is a
+        // mutable array; default `data class` equality uses reference
+        // identity for arrays, which is rarely what callers want.
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is PackedYuv) return false
+            return width == other.width
+                && height == other.height
+                && nv21.contentEquals(other.nv21)
+        }
+        override fun hashCode(): Int {
+            var result = nv21.contentHashCode()
+            result = 31 * result + width
+            result = 31 * result + height
+            return result
+        }
+    }
+
+
+    /**
+     * Pack the Y, U, V planes of a YUV_420_888 `Image` into a
+     * contiguous JVM-side NV21 byte array.  Returns null if the
+     * `Image`'s format isn't YUV_420_888 or doesn't expose 3 planes.
+     *
+     * Performance: ~3 ms for 1920×1080 on a Galaxy A35.  Dominated
+     * by the row-by-row copy through the direct ByteBuffers backing
+     * the camera planes.
+     *
+     * The Y plane is densely repacked (the source rowStride may be
+     * padded, but we discard padding on the way in so the result has
+     * `rowStride = width`).  This is what callers want — `cv::Mat`
+     * wrap on the C++ side prefers tight strides, and downstream
+     * `YuvImage.compressToJpeg` requires densely-packed input.
+     */
+    fun packNV21(image: Image): PackedYuv? {
+        if (image.format != ImageFormat.YUV_420_888) return null
+        val planes = image.planes
+        if (planes.size < 3) return null
+
+        val w = image.width
+        val h = image.height
+        val ySize = w * h
+        val uvSize = w * h / 2
+        val nv21 = ByteArray(ySize + uvSize)
+
+        // ── Y plane (luminance) ─────────────────────────────────
+        val yPlane = planes[0]
+        val yBuf = yPlane.buffer
+        val yRowStride = yPlane.rowStride
+        if (yRowStride == w) {
+            // Source already densely packed — single block copy.
+            // Use duplicate() so we don't mutate the original buffer's
+            // position state (defensive — ARCore may have other readers
+            // of the same underlying buffer, though in practice it
+            // shouldn't).
+            yBuf.duplicate().apply { rewind() }.get(nv21, 0, ySize)
+        } else {
+            // Row-by-row copy when stride > width (padded rows).
+            val dup = yBuf.duplicate()
+            var dstOffset = 0
+            var srcOffset = 0
+            for (row in 0 until h) {
+                dup.position(srcOffset)
+                dup.get(nv21, dstOffset, w)
+                dstOffset += w
+                srcOffset += yRowStride
+            }
+        }
+
+        // ── U + V planes (chroma) ───────────────────────────────
+        // YUV_420_888 has them subsampled 2:1 so each plane physically
+        // covers (w/2) × (h/2).  Pixel stride is 1 (planar) or 2
+        // (semi-planar interleaved).  NV21 expects interleaved V-U.
+        val uPlane = planes[1]
+        val vPlane = planes[2]
+        val uBuf = uPlane.buffer
+        val vBuf = vPlane.buffer
+        val uRowStride = uPlane.rowStride
+        val uPixelStride = uPlane.pixelStride
+        val vRowStride = vPlane.rowStride
+        val vPixelStride = vPlane.pixelStride
+
+        // Fast path — most Android camera2 / ARCore producers emit
+        // semi-planar interleaved data with pixelStride=2.  In that
+        // case the V plane's underlying bytes physically interleave
+        // V-U-V-U... and copying the V plane's full byte range
+        // produces NV21 layout directly.
+        if (uPixelStride == 2 && vPixelStride == 2 &&
+            uRowStride == vRowStride && uRowStride == w) {
+            val vBytes = vBuf.remaining().coerceAtMost(uvSize)
+            // Defensive duplicate() again — same reasoning as Y plane.
+            vBuf.duplicate().apply { rewind() }.get(nv21, ySize, vBytes)
+            return PackedYuv(nv21, w, h)
+        }
+
+        // Slow path — manual interleave for planar (pixelStride=1) or
+        // non-tight semi-planar layouts.
+        var pos = ySize
+        val rowsUv = h / 2
+        val colsUv = w / 2
+        for (row in 0 until rowsUv) {
+            for (col in 0 until colsUv) {
+                val vIdx = row * vRowStride + col * vPixelStride
+                val uIdx = row * uRowStride + col * uPixelStride
+                nv21[pos++] = vBuf.get(vIdx)
+                nv21[pos++] = uBuf.get(uIdx)
+            }
+        }
+        return PackedYuv(nv21, w, h)
+    }
+
+
+    /**
+     * Encode an already-packed NV21 buffer to a JPEG file on disk.
+     *
+     * Returns the output path on success, or null on any encode/write
+     * error (caller decides whether to log + drop the frame).
+     *
+     * `displayRotation` writes the appropriate EXIF orientation tag
+     * so consumers that respect EXIF (RN's Image loader, etc.)
+     * display the JPEG upright regardless of how the device was held
+     * at capture.  Should be the value from
+     * `WindowManager.defaultDisplay.rotation` at capture time
+     * (Surface.ROTATION_0 / _90 / _180 / _270).
+     *
+     * Sensor orientation 90° assumed (back camera) — verified on
+     * Galaxy A35.  Wire `CameraCharacteristics.SENSOR_ORIENTATION`
+     * through in a follow-up if we hit a device that differs.
+     */
+    fun encodeJpegFromNV21(
+        packed: PackedYuv,
         outputPath: String,
         jpegQuality: Int = 70,
         displayRotation: Int = Surface.ROTATION_0,
     ): String? {
-        if (image.format != ImageFormat.YUV_420_888) return null
-        val nv21 = yuv420toNV21(image) ?: return null
         val yuvImage = YuvImage(
-            nv21,
+            packed.nv21,
             ImageFormat.NV21,
-            image.width,
-            image.height,
+            packed.width,
+            packed.height,
             null,
         )
         val baos = ByteArrayOutputStream()
         val ok = yuvImage.compressToJpeg(
-            Rect(0, 0, image.width, image.height),
+            Rect(0, 0, packed.width, packed.height),
             jpegQuality.coerceIn(1, 100),
             baos,
         )
@@ -81,8 +226,9 @@ internal object YuvImageConverter {
         } catch (e: Throwable) {
             return null
         }
+
         // Write EXIF orientation tag based on display rotation.
-        // Sensor orientation 90° assumed (back camera).  The math:
+        // The math:
         //   ROTATION_0  (portrait, sensor 90° CW from screen-up)
         //     → JPEG needs 90° CW to display upright → ROTATE_90 (6)
         //   ROTATION_90 (landscape-left, sensor aligned with screen)
@@ -93,11 +239,11 @@ internal object YuvImageConverter {
         //     → 180° → ROTATE_180 (3)
         //
         // EXIF tag set EVEN when the orientation is normal — keeps
-        // every output JPEG self-describing for downstream
-        // consumers (cv::Stitcher does NOT auto-honour EXIF, see
-        // BatchStitcher.applyExifOrientation; this metadata
-        // exists primarily for the live thumbnail strip + future
-        // RN Image renderers).
+        // every output JPEG self-describing for downstream consumers.
+        // cv::Stitcher does NOT auto-honour EXIF (see
+        // BatchStitcher.applyExifOrientation); this metadata exists
+        // primarily for the live thumbnail strip + future RN Image
+        // renderers.
         val exifOrientation = when (displayRotation) {
             Surface.ROTATION_0   -> ExifInterface.ORIENTATION_ROTATE_90
             Surface.ROTATION_90  -> ExifInterface.ORIENTATION_NORMAL
@@ -114,88 +260,35 @@ internal object YuvImageConverter {
             exif.saveAttributes()
         } catch (e: Throwable) {
             // EXIF write failed — JPEG itself is still valid; just
-            // missing the orientation hint.  Caller doesn't need to
-            // know — non-fatal.
+            // missing the orientation hint.  Non-fatal; caller doesn't
+            // need to know.
         }
         return outputPath
     }
 
+
     /**
-     * Pack a YUV_420_888 `Image` into a contiguous NV21 byte array.
+     * Single-call convenience wrapper: pack the `Image` and encode
+     * to JPEG in one step.  Keeps the `Image` open through the entire
+     * ~25 ms encode — fine for one-shot photo capture, NOT
+     * recommended for the ~60 Hz `forwardToIncremental` path.  See the
+     * file-level docs for the two-step alternative.
      *
-     * The Image API exposes Y, U, V as three planes, each with its
-     * own row stride and pixel stride.  NV21 expects a single
-     * contiguous buffer with Y plane first, then interleaved VU bytes
-     * after.  The repacking handles row + pixel strides that don't
-     * match the dense layout.
+     * Caller still owns the `Image` and MUST close it afterwards;
+     * this function does not.
      */
-    private fun yuv420toNV21(image: Image): ByteArray? {
-        val w = image.width
-        val h = image.height
-        val ySize = w * h
-        val uvSize = w * h / 2
-
-        val nv21 = ByteArray(ySize + uvSize)
-        val planes = image.planes
-        if (planes.size < 3) return null
-
-        // Y plane.
-        val yPlane = planes[0]
-        val yBuf = yPlane.buffer
-        val yRowStride = yPlane.rowStride
-        if (yRowStride == w) {
-            yBuf.get(nv21, 0, ySize)
-        } else {
-            // Row-by-row copy when stride != width.
-            var dstOffset = 0
-            var srcOffset = 0
-            for (row in 0 until h) {
-                yBuf.position(srcOffset)
-                yBuf.get(nv21, dstOffset, w)
-                dstOffset += w
-                srcOffset += yRowStride
-            }
-        }
-
-        // U + V planes.  YUV_420_888 has them subsampled 2:1 so each
-        // covers (w/2) × (h/2).  Pixel stride is 1 (planar) or 2
-        // (semi-planar interleaved).  NV21 requires interleaved VU.
-        val uPlane = planes[1]
-        val vPlane = planes[2]
-        val uBuf = uPlane.buffer
-        val vBuf = vPlane.buffer
-        val uRowStride = uPlane.rowStride
-        val uPixelStride = uPlane.pixelStride
-        val vRowStride = vPlane.rowStride
-        val vPixelStride = vPlane.pixelStride
-
-        // Most camera2 / ARCore implementations on Android already
-        // produce semi-planar interleaved data with pixelStride=2.
-        // In that case Y plane + V plane (offset by 1) form NV21
-        // directly with a single block copy.  Detect + fast-path it.
-        if (uPixelStride == 2 && vPixelStride == 2 &&
-            uRowStride == vRowStride && uRowStride == w) {
-            // The V plane in NV21 layout starts at vBuf's first byte.
-            // Copy the entire V plane (which physically interleaves
-            // with U bytes since pixelStride=2 means consecutive
-            // bytes are V-U-V-U...).
-            val vBytes = vBuf.remaining().coerceAtMost(uvSize)
-            vBuf.get(nv21, ySize, vBytes)
-            return nv21
-        }
-
-        // Slow path — manual interleave.
-        var pos = ySize
-        val rowsUv = h / 2
-        val colsUv = w / 2
-        for (row in 0 until rowsUv) {
-            for (col in 0 until colsUv) {
-                val vIdx = row * vRowStride + col * vPixelStride
-                val uIdx = row * uRowStride + col * uPixelStride
-                nv21[pos++] = vBuf.get(vIdx)
-                nv21[pos++] = uBuf.get(uIdx)
-            }
-        }
-        return nv21
+    fun encodeToJpeg(
+        image: Image,
+        outputPath: String,
+        jpegQuality: Int = 70,
+        displayRotation: Int = Surface.ROTATION_0,
+    ): String? {
+        val packed = packNV21(image) ?: return null
+        return encodeJpegFromNV21(
+            packed,
+            outputPath,
+            jpegQuality = jpegQuality,
+            displayRotation = displayRotation,
+        )
     }
 }

package/dist/camera/Camera.js

@@ -90,7 +90,10 @@ const CaptureKeyframePill_1 = require("./CaptureKeyframePill");
 const CaptureOrientationPill_1 = require("./CaptureOrientationPill");
 const CaptureStitchStatsToast_1 = require("./CaptureStitchStatsToast");
 const PanoramaBandOverlay_1 = require("./PanoramaBandOverlay");
+const PanoramaSettingsBridge_1 = require("./PanoramaSettingsBridge");
 const PanoramaSettingsModal_1 = require("./PanoramaSettingsModal");
+const buildPanoramaInitialSettings_1 = require("./buildPanoramaInitialSettings");
+const lowMemDevice_1 = require("./lowMemDevice");
 const useCapture_1 = require("./useCapture");
 const useDeviceOrientation_1 = require("./useDeviceOrientation");
 const incremental_1 = require("../stitching/incremental");
@@ -228,32 +231,31 @@ function deriveEffectiveCaptureSource(arPreference, lens, isARSupportedOnDevice)
     return arPreference ? 'ar' : 'non-ar';
 }
 /**
- * Apply per-prop defaults to build the initial settings snapshot.
- * The settings live in component state from there; the prop values
- * never re-flow.
+ * Pluck the props that influence the initial PanoramaSettings tree.
+ * Kept inline (vs. a wide structural type) so future Camera prop
+ * additions don't accidentally widen the settings-translation
+ * surface — the pure builder in `./buildPanoramaInitialSettings.ts`
+ * has the canonical interface; this just forwards the relevant
+ * fields.
  *
- * Note: the `default*ResolMP` props don't have a home on PanoramaSettings
- * yet — they're accepted on the prop interface for forward compatibility
- * but ignored here.  Wiring is a follow-up once PanoramaSettings is
- * extended.
+ * The `default*ResolMP` props on `CameraProps` are documented as
+ * forward-looking no-ops; the new PanoramaSettings tree has no home
+ * for them yet (the v0.3 audit found cv::Stitcher's resol knobs
+ * aren't reached by either platform's bridge).  They're accepted on
+ * the prop interface for API stability and ignored here.
  */
-function buildInitialSettings(props) {
+function extractPanoramaOverrides(props) {
     return {
-        ...PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS,
-        stitchMode: props.defaultStitchMode ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.stitchMode,
-        blenderType: props.defaultBlender ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.blenderType,
-        seamFinderType: props.defaultSeamFinder ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.seamFinderType,
-        warperType: props.defaultWarper ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.warperType,
-        flowNoveltyPercentile: props.defaultFlowNoveltyPercentile ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowNoveltyPercentile,
-        flowEvalEveryNFrames: props.defaultFlowEvalEveryNFrames ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowEvalEveryNFrames,
-        flowMaxTranslationCm: props.defaultFlowMaxTranslationCm ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowMaxTranslationCm,
-        keyframeMaxCount: props.defaultKeyframeMaxCount ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.keyframeMaxCount,
-        keyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.keyframeOverlapThreshold,
+        defaultCaptureSource: props.defaultCaptureSource,
+        defaultStitchMode: props.defaultStitchMode,
+        defaultBlender: props.defaultBlender,
+        defaultSeamFinder: props.defaultSeamFinder,
+        defaultWarper: props.defaultWarper,
+        defaultFlowNoveltyPercentile: props.defaultFlowNoveltyPercentile,
+        defaultFlowEvalEveryNFrames: props.defaultFlowEvalEveryNFrames,
+        defaultFlowMaxTranslationCm: props.defaultFlowMaxTranslationCm,
+        defaultKeyframeMaxCount: props.defaultKeyframeMaxCount,
+        defaultKeyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold,
     };
 }
 // `toFileUri` (used to be an inline `toFileUri` here) lives in
@@ -273,7 +275,7 @@ function Camera(props) {
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
     const [lens, setLens] = (0, react_1.useState)(defaultLens);
-    const [settings, setSettings] = (0, react_1.useState)(() => buildInitialSettings(props));
+    const [settings, setSettings] = (0, react_1.useState)(() => (0, buildPanoramaInitialSettings_1.buildPanoramaInitialSettings)(extractPanoramaOverrides(props), (0, lowMemDevice_1.isLowMemDevice)()));
     const [settingsModalVisible, setSettingsModalVisible] = (0, react_1.useState)(false);
     const [statusPhase, setStatusPhase] = (0, react_1.useState)('idle');
     const [recordingStartedAt, setRecordingStartedAt] = (0, react_1.useState)(null);
@@ -399,11 +401,16 @@ function Camera(props) {
     // |residual|` — which undercounted any time a non-IMU accept
     // (flow novelty, force-last) reset the integrator before the
     // budget threshold was reached.
+    // The translation budget lives at `frameSelection.flow.maxTranslationCm`
+    // in the new hierarchical settings shape.  When `flow` is undefined
+    // (the consumer opted out of the flow strategy entirely), the gate
+    // stays disabled — same observable behaviour as v0.3's `0` default.
+    const flowMaxTranslationCm = settings.frameSelection.flow?.maxTranslationCm ?? 0;
     const imuGate = (0, useIMUTranslationGate_1.useIMUTranslationGate)({
         enabled: isNonAR
             && statusPhase === 'recording'
-            && settings.flowMaxTranslationCm > 0,
-        budgetMeters: Math.max(0.001, settings.flowMaxTranslationCm / 100.0),
+            && flowMaxTranslationCm > 0,
+        budgetMeters: Math.max(0.001, flowMaxTranslationCm / 100.0),
         onBudgetExceeded: () => {
             const mod = (0, incremental_1.getIncrementalNativeModule)();
             mod?.markNextFrameAsLastKeyframe?.().catch(() => undefined);
@@ -578,6 +585,25 @@ function Camera(props) {
             const orientationRotation = deviceOrientation === 'portrait' ? 90
                 : deviceOrientation === 'portrait-upside-down' ? 270
                     : 0;
+            // v0.4 — the inline-flat config dict that v0.3 maintained here
+            // moved into `panoramaSettingsToNativeConfig` (see
+            // PanoramaSettingsBridge.ts).  That adapter is the single source
+            // of truth for the JS→native wire format; both this call site
+            // AND the modal's reset-to-defaults preview agree on the same
+            // mapping.  Audit fixes F1 / F4 / F6 from v0.3 are now properties
+            // of the bridge (verified by the unit tests in
+            // src/camera/__tests__/PanoramaSettingsBridge.test.ts).
+            //
+            // 2026-05-23 — override `captureSource` with the runtime-derived
+            // `effectiveCaptureSource` (from `arPreference + lens +
+            // AR-device-support`).  Pre-this change the camera-screen AR
+            // toggle wrote ONLY to local `arPreference` state while the
+            // bridge read `settings.captureSource` — so native could think
+            // the capture was AR while the operator had toggled it off (or
+            // vice-versa).  Single source of truth now: whatever camera the
+            // operator can see is what native is told it is.  The settings
+            // modal's `captureSource` control has been removed for the same
+            // reason — see PanoramaSettingsModal.tsx for the rationale.
             await incremental.start({
                 snapshotJpegQuality: 75,
                 snapshotEveryNAccepts: 1,
@@ -589,37 +615,10 @@ function Camera(props) {
                 canvasWidth: 5000,
                 canvasHeight: 5000,
                 engine: 'batch-keyframe',
-                config: {
-                    // ── cv::Stitcher (batch finalize) ─────────────────────────
-                    stitchMode: settings.stitchMode,
-                    warperType: settings.warperType,
-                    blenderType: settings.blenderType,
-                    seamFinderType: settings.seamFinderType,
-                    enableMaxInscribedRectCrop: settings.enableMaxInscribedRectCrop,
-                    // ── KeyframeGate (per-frame selection) ────────────────────
-                    // F6 audit fix: pass settings.frameSelectionMode through
-                    // instead of hardcoding 'flow-based' (which silently made the
-                    // time-based / pose-based modal options no-ops).
-                    frameSelectionMode: settings.frameSelectionMode,
-                    keyframeMaxCount: settings.keyframeMaxCount,
-                    keyframeOverlapThreshold: settings.keyframeOverlapThreshold,
-                    // ── Flow-strategy tunables ────────────────────────────────
-                    // F4 audit fix: previously omitted, which made the modal
-                    // sliders for these three a complete no-op (only iOS native
-                    // even read them, and only when JS sent them).
-                    flowNoveltyPercentile: settings.flowNoveltyPercentile,
-                    flowEvalEveryNFrames: settings.flowEvalEveryNFrames,
-                    flowMaxTranslationCm: settings.flowMaxTranslationCm,
-                    flowMaxCorners: settings.flowMaxCorners,
-                    flowQualityLevel: settings.flowQualityLevel,
-                    flowMinDistance: settings.flowMinDistance,
-                    // ── Engine-routing flags consumed by native ───────────────
-                    // F1 audit fix: Android keyframe gate's disableAngularFallback
-                    // opt-out reads this to decide whether to skip the angular
-                    // fallback (gyro pose is too noisy for the FoV-overlap calc
-                    // in non-AR mode, causing degenerate cv::Stitcher params).
-                    captureSource: settings.captureSource,
-                },
+                config: (0, PanoramaSettingsBridge_1.panoramaSettingsToNativeConfig)({
+                    ...settings,
+                    captureSource: effectiveCaptureSource,
+                }),
             });
             imuGate.resetAnchor();
             // Start pumping vision-camera snapshots into the engine for
@@ -642,6 +641,7 @@ function Camera(props) {
         isNonAR,
         deviceOrientation,
         settings,
+        effectiveCaptureSource,
         imuGate,
         jsDriver,
         onError,
@@ -723,6 +723,18 @@ function Camera(props) {
         onError,
         recordingStartedAt,
         jsDriver,
+        // F10 Phase 2 review N1 — these four were missing pre-fix.  The
+        // callback reads `settings.debug` (to gate the stitchToast),
+        // `isNonAR` (to decide whether to read IMU totalAbs translation),
+        // `imuGate` (the read itself), and `stitchToast` (the toast hook
+        // object).  If any of those identities change between the user
+        // pressing-and-holding the shutter and the release, the stale-
+        // closure read could disagree with the actual current state.
+        // Pre-existing v0.3 bug; v0.4 was the natural time to address it.
+        settings,
+        isNonAR,
+        imuGate,
+        stitchToast,
     ]);
     // ── Lens / AR-toggle handlers ───────────────────────────────────
     const handleLensChange = (0, react_1.useCallback)((next) => {
@@ -749,7 +761,7 @@ function Camera(props) {
             react_1.default.createElement(CaptureOrientationPill_1.CaptureOrientationPill, { orientation: deviceOrientation, topInset: insets.top }),
             react_1.default.createElement(CaptureKeyframePill_1.CaptureKeyframePill, { state: incrementalState, topInset: insets.top }),
             react_1.default.createElement(CaptureMemoryPill_1.CaptureMemoryPill, { topInset: insets.top }),
-            react_1.default.createElement(CaptureDebugOverlay_1.CaptureDebugOverlay, { incrementalState: incrementalState, imuTranslationMetres: isNonAR ? imuGate.getTranslationMetres() : null, captureSource: effectiveCaptureSource, frameSelectionMode: settings.frameSelectionMode, stitchMode: settings.stitchMode }))),
+            react_1.default.createElement(CaptureDebugOverlay_1.CaptureDebugOverlay, { incrementalState: incrementalState, imuTranslationMetres: isNonAR ? imuGate.getTranslationMetres() : null, captureSource: effectiveCaptureSource, frameSelectionMode: settings.frameSelection.mode, stitchMode: settings.stitcher.stitchMode }))),
         react_1.default.createElement(CaptureStitchStatsToast_1.CaptureStitchStatsToast, { message: stitchToast.message, topInset: insets.top }),
         showSettingsButton && (react_1.default.createElement(SettingsButton, { topInset: insets.top, onPress: () => setSettingsModalVisible(true) })),
         react_1.default.createElement(react_native_1.View, { pointerEvents: "box-none", style: [styles.bottomArea, { paddingBottom: insets.bottom + 12 }] },