react-native-image-stitcher 0.2.1 → 0.3.0

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

@@ -62,6 +62,24 @@ internal class KeyframeGate : AutoCloseable {
         get() = nativeIsEnabled(nativeHandle)
         set(value) = nativeSetEnabled(nativeHandle, value)
 
+    /// 2026-05-22 (audit F6) — Gate strategy.  Matches the C++ enum
+    /// retailens::GateStrategy (0 = Pose, 1 = Flow).  Pose strategy
+    /// uses plane-projection / angular novelty; Flow strategy uses
+    /// sparse optical-flow KLT.  iOS parity: Swift facade's
+    /// `keyframeGate.strategy = .flow / .pose`.  Default `Pose`
+    /// (matches C++ default).  Write-only; the C++ side has a getter
+    /// but the Kotlin facade caches locally to avoid JNI round-trip.
+    enum class Strategy(val nativeValue: Int) {
+        Pose(0),
+        Flow(1);
+    }
+
+    var strategy: Strategy = Strategy.Pose
+        set(value) {
+            field = value
+            nativeSetStrategy(nativeHandle, value.nativeValue)
+        }
+
     /// Required new-content fraction (0…1).  Default 0.4.  No getter
     /// — the C++ side has no read accessor (Swift side never needed
     /// to read this back either).  Stored locally for diagnostic
@@ -122,6 +140,47 @@ internal class KeyframeGate : AutoCloseable {
             nativeSetFlowMaxTranslationM(nativeHandle, value)
         }
 
+    /// 2026-05-22 (audit F5) — Flow strategy: Shi-Tomasi max corners
+    /// to track per frame.  Same knob iOS exposes via setFlowMaxCorners.
+    /// C++ clamps to ≥ 30.  Higher = more sensitive to fine detail but
+    /// CPU-quadratic in the KLT step.  Default 150 (matches iOS).
+    var flowMaxCorners: Int = 150
+        set(value) {
+            field = value
+            nativeSetFlowMaxCorners(nativeHandle, value)
+        }
+
+    /// 2026-05-22 (audit F5) — Flow strategy: Shi-Tomasi minimum
+    /// eigenvalue threshold (0, 1].  C++ default 0.01.  Lower lets
+    /// weaker corners in (more candidate points, more KLT noise);
+    /// higher demands stronger corners (fewer points, more robust).
+    var flowQualityLevel: Double = 0.01
+        set(value) {
+            field = value
+            nativeSetFlowQualityLevel(nativeHandle, value)
+        }
+
+    /// 2026-05-22 (audit F5) — Flow strategy: Shi-Tomasi minimum
+    /// distance between accepted corners, in working-resolution
+    /// pixels.  C++ clamps to ≥ 1.0.  Default 10.0 (matches iOS).
+    var flowMinDistance: Double = 10.0
+        set(value) {
+            field = value
+            nativeSetFlowMinDistance(nativeHandle, value)
+        }
+
+    /// 2026-05-22 (audit F5) — Eval cadence: caller-side throttle so
+    /// the Flow strategy runs every Nth frame instead of every frame.
+    /// iOS parity with `IncrementalStitcher.swift:2459-2471` —
+    /// the GATE doesn't enforce the throttle itself; it just stores
+    /// the value here.  The caller (`IncrementalStitcher.kt`) reads
+    /// this and decides per-frame whether to evaluate.  Default 1
+    /// (no throttle).  Caller is responsible for clamping to [1, 10].
+    var flowEvalEveryNFrames: Int = 1
+        set(value) {
+            field = value.coerceAtLeast(1)
+        }
+
     // ── Read-only state ─────────────────────────────────────────
 
     val acceptedCount: Int get() = nativeGetAcceptedCount(nativeHandle)
@@ -175,6 +234,56 @@ internal class KeyframeGate : AutoCloseable {
         )
     }
 
+    /**
+     * Pixel-aware evaluate.  Hands the gate the frame's grayscale
+     * plane so the C++ Flow strategy (sparse optical-flow novelty)
+     * actually runs — without grayData, the gate silently falls back
+     * to the Pose strategy (angular-delta).  iOS parity: see
+     * `KeyframeGateBridge.mm::evaluateWithPixelBuffer:...`.
+     *
+     * 2026-05-21 (v0.3) added.  Two call-site categories:
+     *
+     *  - AR mode (`RNSARCameraView.forwardToIncremental`): extracts
+     *    the Y plane from the ARCore camera image (YUV_420_888) and
+     *    hands it through.  Zero-copy on the way in (the byte[] is
+     *    pinned via GetPrimitiveArrayCritical in the JNI).
+     *  - Non-AR mode (`IncrementalStitcher.processFrameAtPath`): the
+     *    JS-driver path supplies a JPEG path; the caller decodes the
+     *    JPEG to grayscale before calling this method.
+     *
+     * @param grayData    The grayscale plane bytes.  Length must be
+     *                    at least `grayStride * grayHeight`.
+     * @param grayWidth   Image width in pixels (≤ grayStride).
+     * @param grayHeight  Image height in pixels.
+     * @param grayStride  Bytes per row.  May exceed `grayWidth` when
+     *                    the plane has padding (ARCore can pad).
+     */
+    fun evaluateWithFrame(
+        pose: RNSARFramePose,
+        latchedPlaneMatrix: FloatArray?,
+        grayData: ByteArray,
+        grayWidth: Int,
+        grayHeight: Int,
+        grayStride: Int,
+    ): KeyframeGateDecision {
+        val result = nativeEvaluateWithFrame(
+            nativeHandle,
+            pose.tx.toFloat(), pose.ty.toFloat(), pose.tz.toFloat(),
+            pose.qx.toFloat(), pose.qy.toFloat(), pose.qz.toFloat(), pose.qw.toFloat(),
+            pose.fx.toFloat(), pose.fy.toFloat(), pose.cx.toFloat(), pose.cy.toFloat(),
+            pose.imageWidth, pose.imageHeight,
+            latchedPlaneMatrix,
+            grayData, grayWidth, grayHeight, grayStride,
+        )
+        return KeyframeGateDecision(
+            accept = result[0] >= 0.5,
+            reason = reasonFromCode(result[1].toInt()),
+            newContentFraction = result[2],
+            acceptedCount = result[3].toInt(),
+            maxCount = result[4].toInt(),
+        )
+    }
+
     // ── JNI thunks ──────────────────────────────────────────────
 
     private external fun nativeCreate(): Long
@@ -193,6 +302,15 @@ internal class KeyframeGate : AutoCloseable {
     private external fun nativeSetDisableAngularFallback(handle: Long, disabled: Boolean)
     private external fun nativeSetFlowNoveltyPercentile(handle: Long, percentile: Double)
     private external fun nativeSetFlowMaxTranslationM(handle: Long, metres: Double)
+    // 2026-05-22 (audit F5) — flow-strategy tunables that were
+    // previously iOS-only.  Add Android JNI parity so the Settings UI
+    // sliders work on both platforms.
+    private external fun nativeSetFlowMaxCorners(handle: Long, maxCorners: Int)
+    private external fun nativeSetFlowQualityLevel(handle: Long, quality: Double)
+    private external fun nativeSetFlowMinDistance(handle: Long, minDistance: Double)
+    // 2026-05-22 (audit F6) — gate-strategy selector.  Maps to C++
+    // retailens::GateStrategy (Pose=0, Flow=1).
+    private external fun nativeSetStrategy(handle: Long, strategy: Int)
     private external fun nativeEvaluate(
         handle: Long,
         tx: Float, ty: Float, tz: Float,
@@ -201,6 +319,16 @@ internal class KeyframeGate : AutoCloseable {
         imageWidth: Int, imageHeight: Int,
         plane16: FloatArray?,
     ): DoubleArray
+    private external fun nativeEvaluateWithFrame(
+        handle: Long,
+        tx: Float, ty: Float, tz: Float,
+        qx: Float, qy: Float, qz: Float, qw: Float,
+        fx: Float, fy: Float, cx: Float, cy: Float,
+        imageWidth: Int, imageHeight: Int,
+        plane16: FloatArray?,
+        grayData: ByteArray,
+        grayWidth: Int, grayHeight: Int, grayStride: Int,
+    ): DoubleArray
 
     companion object {
         init {

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

@@ -196,6 +196,15 @@ class RNSARCameraView @JvmOverloads constructor(
         // to work for hosts that prefer explicit control — the
         // refs/state are shared.
         RNSARSession.instance?.stopForView()
+        // 2026-05-23 (crash fix) — drop our local Session reference
+        // too.  stopForView() above pause+close'd the session and
+        // nulled the singleton's ref, but our own sessionRef still
+        // pointed at the closed Session.  If the view ever got
+        // re-used (re-attach without recreating), the next
+        // session.resume() / forwardToIncremental call would
+        // dereference a closed Session → SEGV in libarcore_c.so's
+        // internal cleanup, exactly the tombstone we saw.
+        sessionRef.set(null)
     }
 
     /// Called by IncrementalStitcher.start/stop.  When true,
@@ -420,22 +429,38 @@ class RNSARCameraView @JvmOverloads constructor(
             return
         }
         try {
-            val written = YuvImageConverter.encodeToJpeg(
-                image,
-                tmpJpegFile.absolutePath,
-                jpegQuality = 70,
-                // 2026-05-15 (B3) — pass current display rotation so
-                // the encoded JPEG gets an EXIF orientation tag.
-                // Without this, the live thumbnail strip shows
-                // sideways pictures when the device is held in
-                // portrait (sensor pixels are landscape by default).
-                // lastDisplayRotation is updated by the
-                // updateDisplayRotation() helper called from
-                // didMoveToWindow / the ARCore Session.setDisplayGeometry
-                // hook (see line ~410).
-                displayRotation = if (lastDisplayRotation >= 0)
-                    lastDisplayRotation else android.view.Surface.ROTATION_0,
-            ) ?: return
+            // 2026-05-21 (v0.3) — pixel-data path.  Pre-0.3 this code
+            // unconditionally encoded the YUV camera image to JPEG and
+            // wrote it to disk for EVERY ARCore frame at ~60 Hz (~25 ms
+            // per frame of JPEG encode + disk I/O on the GL render
+            // thread), regardless of whether the C++ KeyframeGate would
+            // accept it.  Now we extract the Y plane bytes (cheap
+            // memcpy from a DirectByteBuffer), feed them to the gate
+            // for proper Flow-strategy evaluation, and defer the JPEG
+            // encode + disk write to the `onAccept` lambda so it only
+            // runs on the rare frames the gate actually keeps
+            // (typically ~6 per capture).
+            //
+            // Y-plane extraction for ARCore's YUV_420_888 format:
+            // plane[0] is the luminance channel at full resolution,
+            // pixelStride=1, rowStride may equal width OR be padded.
+            // We pass rowStride as the C++ side's `stride` so the gate
+            // skips padding correctly.
+            val yPlane = image.planes[0]
+            val yBuffer = yPlane.buffer
+            val yStride = yPlane.rowStride
+            val yWidth = image.width
+            val yHeight = image.height
+            // Copy Y bytes into a JVM-side ByteArray.  Using
+            // duplicate() so we don't mutate the original buffer's
+            // position state (ARCore may have other readers).
+            // For 1920×1080 Y plane that's ~2 MB; on Galaxy A35 the
+            // memcpy itself is < 1 ms.  JNI side pins via
+            // GetPrimitiveArrayCritical so the byte[] stays a single
+            // copy through the entire frame's lifecycle.
+            val ySize = yStride * yHeight
+            val yBytes = ByteArray(ySize)
+            yBuffer.duplicate().apply { rewind() }.get(yBytes, 0, ySize)
 
             // Compute yaw + pitch from the ARCore quaternion using
             // the same convention the iOS Swift side uses (camera-
@@ -469,8 +494,32 @@ class RNSARCameraView @JvmOverloads constructor(
             val tArr = camera.pose.translation
 
             val trackingPoor = camera.trackingState != TrackingState.TRACKING
-            postFrameToEngine(
-                path = written,
+            val module = IncrementalStitcher.bridgeInstance ?: return
+            // 2026-05-15 (B3) — pass current display rotation so the
+            // encoded JPEG gets an EXIF orientation tag.  Captured into
+            // a local val so the lambda below closes over a primitive
+            // (avoids re-reading lastDisplayRotation if it shifts
+            // between gate-evaluate and lambda invocation).
+            val rotationForEncode = if (lastDisplayRotation >= 0)
+                lastDisplayRotation else android.view.Surface.ROTATION_0
+            // 2026-05-21 (v0.3) — eager JPEG encode is only needed when
+            // the engine is in the legacy hybrid/firstwins live-engine
+            // mode (which feeds JPEG paths into addFrameAtPath every
+            // frame).  In batch-keyframe mode (the production Camera
+            // component's path), the JPEG is encoded LAZILY inside
+            // the onAccept lambda below — only on the ~6 frames per
+            // capture that the C++ KeyframeGate actually keeps.
+            val legacyJpegPath: String? = if (module.isBatchKeyframeMode) {
+                null
+            } else {
+                YuvImageConverter.encodeToJpeg(
+                    image,
+                    tmpJpegFile.absolutePath,
+                    jpegQuality = 70,
+                    displayRotation = rotationForEncode,
+                )
+            }
+            module.ingestFromARCameraView(
                 tx = tArr[0].toDouble(),
                 ty = tArr[1].toDouble(),
                 tz = tArr[2].toDouble(),
@@ -482,39 +531,32 @@ class RNSARCameraView @JvmOverloads constructor(
                 yaw = yaw, pitch = pitch,
                 fovHorizDegrees = fovHDeg, fovVertDegrees = fovVDeg,
                 trackingPoor = trackingPoor,
+                grayData = yBytes,
+                grayWidth = yWidth,
+                grayHeight = yHeight,
+                grayStride = yStride,
+                legacyJpegPath = legacyJpegPath,
+                onAccept = { targetPath ->
+                    // Lazy JPEG encode.  Runs ONLY if the C++ KeyframeGate
+                    // accepted the frame.  The ARCore Image is still open
+                    // at this point (we haven't reached `image.close()`
+                    // in the surrounding `finally` block yet), so the
+                    // encode reads raw camera pixels directly into a
+                    // JPEG at the final persistent path — no tmp file,
+                    // no second copy.
+                    YuvImageConverter.encodeToJpeg(
+                        image,
+                        targetPath,
+                        jpegQuality = 70,
+                        displayRotation = rotationForEncode,
+                    ) != null
+                },
             )
         } finally {
             image.close()
         }
     }
 
-    private fun postFrameToEngine(
-        path: String,
-        tx: Double, ty: Double, tz: Double,
-        qx: Double, qy: Double, qz: Double, qw: Double,
-        fx: Double, fy: Double, cx: Double, cy: Double,
-        imageWidth: Int, imageHeight: Int,
-        yaw: Double,
-        pitch: Double,
-        fovHorizDegrees: Double,
-        fovVertDegrees: Double,
-        trackingPoor: Boolean,
-    ) {
-        val module = IncrementalStitcher.bridgeInstance ?: return
-        module.ingestFromARCameraView(
-            path = path,
-            tx = tx, ty = ty, tz = tz,
-            qx = qx, qy = qy, qz = qz, qw = qw,
-            fx = fx, fy = fy, cx = cx, cy = cy,
-            imageWidth = imageWidth, imageHeight = imageHeight,
-            yaw = yaw,
-            pitch = pitch,
-            fovHorizDegrees = fovHorizDegrees,
-            fovVertDegrees = fovVertDegrees,
-            trackingPoor = trackingPoor,
-        )
-    }
-
     private fun applyDisplayGeometry() {
         val session = sessionRef.get() ?: return
         val rotation = (context.getSystemService(Context.WINDOW_SERVICE) as? WindowManager)

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

@@ -148,7 +148,34 @@ class RNSARSession(reactContext: ReactApplicationContext)
     @ReactMethod
     fun stop(promise: Promise) {
         try {
-            sessionRef.getAndSet(null)?.pause()
+            // 2026-05-23 (crash fix) — Session.pause() stops frame
+            // production but keeps the native session ALIVE: its
+            // internal worker threads (tango_pool_lp4, etc.) keep
+            // running.  Once the session reference is nulled here,
+            // those threads become orphaned — still alive, but with
+            // no owner to clean them up.  Under later memory
+            // pressure scudo unmaps freed pages and an in-flight
+            // tango_pool_lp4 memcpy SEGVs on an unmapped destination
+            // (the crash we diagnosed from tombstone_03, with
+            // libarcore_c.so internal `ImageBlockData` frames).
+            //
+            // Session.close() shuts down those threads AND releases
+            // native resources, which is what we actually want for
+            // an explicit "AR off" toggle.  Pause+close together is
+            // ARCore's documented full-teardown sequence.  The next
+            // start() recreates the Session from scratch (see
+            // line 105's `sessionRef.get() ?: Session(...)` path).
+            val prev = sessionRef.getAndSet(null)
+            try {
+                prev?.pause()
+            } catch (t: Throwable) {
+                Log.w(TAG, "stop: pause failed (ignoring): ${t.message}")
+            }
+            try {
+                prev?.close()
+            } catch (t: Throwable) {
+                Log.w(TAG, "stop: close failed (ignoring): ${t.message}")
+            }
             trackingStateRef.set(TRACKING_NOT_AVAILABLE)
             clearPoseLogInternal()
             promise.resolve(null)
@@ -291,11 +318,26 @@ class RNSARSession(reactContext: ReactApplicationContext)
                 // Common on first-attach failures (no Activity, etc.).
                 return
             }
-            prev.pause()
+            // 2026-05-23 (crash fix) — pause + close, not just pause.
+            // See the matching fix in `stop()` above for the full
+            // rationale.  Short version: pause() leaves ARCore's
+            // internal worker threads alive but orphaned; close()
+            // tears them down.  Required for the AR-off toggle path
+            // (ARCameraView unmount → onDetachedFromWindow → here).
+            try {
+                prev.pause()
+            } catch (t: Throwable) {
+                Log.w(TAG, "stopForView: pause failed (ignoring): ${t.message}")
+            }
+            try {
+                prev.close()
+            } catch (t: Throwable) {
+                Log.w(TAG, "stopForView: close failed (ignoring): ${t.message}")
+            }
             trackingStateRef.set(TRACKING_NOT_AVAILABLE)
-            Log.i(TAG, "stopForView: AR session paused")
+            Log.i(TAG, "stopForView: AR session paused + closed")
         } catch (t: Throwable) {
-            Log.w(TAG, "stopForView: pause failed: ${t.message}", t)
+            Log.w(TAG, "stopForView: teardown failed: ${t.message}", t)
         }
     }
 

package/cpp/stitcher.cpp

@@ -244,11 +244,97 @@ cv::Rect maxInscribedRectFromMask(const cv::Mat& mask) {
 }  // namespace
 
 
+// Forward declaration — body is the renamed inner entry point further
+// down.  The public `stitchFramePaths` wraps this with the
+// mode-fallback retry logic added in the 2026-05-22 audit.
+static StitchResult stitchFramePathsImpl_(
+    const std::vector<std::string>& framePaths,
+    const std::string&              outputPath,
+    const StitchConfig&             config,
+    LogFn                           logFn);
+
+
 StitchResult stitchFramePaths(
     const std::vector<std::string>& framePaths,
     const std::string&              outputPath,
     const StitchConfig&             config,
     LogFn                           logFn)
+{
+    // 2026-05-22 (audit follow-up) — mode-fallback retry.  When the
+    // configured stitchMode produces degenerate camera params (the
+    // "warpRoi too large" crash users hit on translation-heavy
+    // captures stitched as PANORAMA, or low-texture inputs stitched
+    // as SCANS), automatically retry once with the OPPOSITE mode
+    // before giving up.  Symmetric: PANORAMA-then-SCANS or
+    // SCANS-then-PANORAMA depending on configured mode.
+    //
+    // Why this is safe to enable unconditionally:
+    //   - The retry only fires on a failed attempt (no perf hit on
+    //     happy paths).
+    //   - Both modes share the load-images and write-output stages,
+    //     so the per-frame I/O cost isn't duplicated — only the
+    //     estimator/BA/warp middle is re-run.
+    //   - Result reflects whichever mode succeeded (returned via
+    //     StitchResult.stitchModeUsed, populated below).
+    auto runOnce = [&](StitchMode modeOverride) -> StitchResult {
+        StitchConfig cfg = config;
+        cfg.stitchMode = modeOverride;
+        return stitchFramePathsImpl_(framePaths, outputPath, cfg, logFn);
+    };
+    StitchResult firstAttempt = runOnce(config.stitchMode);
+    if (firstAttempt.errorCode == StitchErrorCode::Ok) {
+        firstAttempt.stitchModeUsed = config.stitchMode;
+        return firstAttempt;
+    }
+    // First attempt failed.  Try the opposite mode unless the error
+    // is something the opposite mode wouldn't fix (e.g. invalid
+    // argument count, file-read failure, OOM).
+    bool worthRetrying =
+        firstAttempt.errorCode == StitchErrorCode::UnknownCvException
+        || firstAttempt.errorCode == StitchErrorCode::HomographyEstimationFailed
+        || firstAttempt.errorCode == StitchErrorCode::CameraParamsAdjustFailed
+        || firstAttempt.errorCode == StitchErrorCode::WarpFailed
+        || firstAttempt.errorCode == StitchErrorCode::EmptyPanorama;
+    if (!worthRetrying) {
+        firstAttempt.stitchModeUsed = config.stitchMode;
+        return firstAttempt;
+    }
+    StitchMode fallbackMode =
+        (config.stitchMode == StitchMode::Panorama) ? StitchMode::Scans
+                                                    : StitchMode::Panorama;
+    log_info(logFn, "[stitch-fallback]",
+             "primary mode (%s) failed with code=%d msg=%s — retrying with %s",
+             config.stitchMode == StitchMode::Scans ? "scans" : "panorama",
+             static_cast<int>(firstAttempt.errorCode),
+             firstAttempt.errorMessage.c_str(),
+             fallbackMode == StitchMode::Scans ? "scans" : "panorama");
+    StitchResult secondAttempt = runOnce(fallbackMode);
+    if (secondAttempt.errorCode == StitchErrorCode::Ok) {
+        secondAttempt.stitchModeUsed = fallbackMode;
+        log_info(logFn, "[stitch-fallback]",
+                 "fallback mode (%s) succeeded",
+                 fallbackMode == StitchMode::Scans ? "scans" : "panorama");
+        return secondAttempt;
+    }
+    // Both attempts failed.  Return the FIRST attempt's error (it's
+    // what the operator's chosen mode produced — more useful for
+    // diagnosis than the fallback's failure).
+    log_info(logFn, "[stitch-fallback]",
+             "fallback mode (%s) also failed with code=%d — returning primary error",
+             fallbackMode == StitchMode::Scans ? "scans" : "panorama",
+             static_cast<int>(secondAttempt.errorCode));
+    firstAttempt.stitchModeUsed = config.stitchMode;
+    return firstAttempt;
+}
+
+// 2026-05-22 (audit follow-up) — renamed inner entry point so the
+// public `stitchFramePaths` wrapper above can layer the mode-fallback
+// retry on top.  This used to be the public function.
+static StitchResult stitchFramePathsImpl_(
+    const std::vector<std::string>& framePaths,
+    const std::string&              outputPath,
+    const StitchConfig&             config,
+    LogFn                           logFn)
 {
     // V2 routing — when caller opts in, hand off to the manual
     // cv::detail::* pipeline.  See stitcher.hpp::StitchConfig::
@@ -1572,13 +1658,27 @@ StitchResult stitchFramePathsManual(
                                   i, roi.width, roi.height,
                                   (long long)roiPixels,
                                   (long long)kMaxWarpPixels);
+                        // 2026-05-22 (audit follow-up) — include
+                        // stitchMode + frame index in the error message
+                        // so the JS host can correlate the failure with
+                        // operator behaviour.  Pre-fix the error said
+                        // nothing about which pipeline diverged.  The
+                        // value tells you: PANORAMA usually fails on
+                        // translation-heavy input (homography + BA-Ray
+                        // assume pure rotation); SCANS usually fails on
+                        // low-texture or low-overlap input (affine needs
+                        // enough matches).
+                        const char* modeStr =
+                            (config.stitchMode == StitchMode::Scans) ? "scans" : "panorama";
                         throw cv::Exception(
                             cv::Error::StsOutOfRange,
                             std::string("warpRoi too large (")
                                 + std::to_string(roi.width) + "x"
                                 + std::to_string(roi.height)
                                 + ") — estimator produced degenerate "
-                                + "camera params on this frame",
+                                + "camera params on this frame (stitchMode="
+                                + modeStr + ", frameIdx="
+                                + std::to_string(i) + ")",
                             "stitchFramePathsManual",
                             __FILE__, __LINE__);
                     }

package/cpp/stitcher.hpp

@@ -217,6 +217,14 @@ struct StitchResult {
     double   finalConfidenceThresh   = -1.0;  // The threshold value that succeeded; -1 if not relevant.
 
     int64_t  durationMs              = 0;
+
+    // 2026-05-22 (audit follow-up) — the stitchMode that actually
+    // produced the output, after the auto-fallback in `stitchFramePaths`
+    // (which retries with the opposite mode when the configured one
+    // fails with degenerate camera params).  May differ from
+    // StitchConfig::stitchMode iff the fallback ran.  Defaults to
+    // Panorama for back-compat in code paths that don't set it.
+    StitchMode stitchModeUsed         = StitchMode::Panorama;
 };
 
 

package/dist/camera/Camera.d.ts

@@ -74,6 +74,15 @@ export type CameraCaptureResult = {
     framesDropped: number;
     finalConfidenceThresh: number;
     durationMs: number;
+    /**
+     * 2026-05-22 (audit F2g) — which cv::Stitcher pipeline the
+     * batch finalize ran (after auto-resolution if applicable).
+     * Useful for displaying a "Stitched as: scans" pill on the
+     * output preview.  Undefined when the engine wasn't
+     * batch-keyframe (hybrid / slit-scan don't go through
+     * cv::Stitcher at finalize).
+     */
+    stitchModeResolved?: 'panorama' | 'scans';
 };
 /**
  * Errors surfaced via `onError`.  Classified codes so consumers can