react-native-image-stitcher 0.15.1 → 0.16.0

package/dist/stitching/cropQuad.d.ts

@@ -0,0 +1,78 @@
+/**
+ * cropQuad — item-7 perspective crop: rectify a user-dragged
+ * quadrilateral to an upright rectangle.
+ *
+ * The post-capture crop editor (`src/camera/RectCropPreview.tsx`) lets the
+ * user drag 4 independent corners over the stitched result.  When that
+ * quad isn't ~axis-aligned, the host calls THIS wrapper instead of the
+ * cheap `cropToRect`: it hands the 4 IMAGE-PIXEL corners to the native
+ * `BatchStitcher.cropToQuad`, which runs
+ * `cv::getPerspectiveTransform` + `cv::warpPerspective` to produce an
+ * upright rectangle (averaged opposite-edge dimensions) and overwrites the
+ * file in place.
+ *
+ * This is the typed twin of the `cropToRect` call in
+ * `example/InscribedRectDebug.tsx` — same native module (`BatchStitcher`),
+ * same in-place overwrite + `{ width, height }` result contract, same
+ * platform-availability fallback posture as
+ * `src/quality/normaliseOrientation.ts`.
+ *
+ * Corner-order contract: `quadImagePoints` MUST be in canonical
+ * [TL, TR, BR, BL] (clockwise from top-left) order — exactly what
+ * `cropGeometry.ts:orderQuadCorners` produces and `RectCropResult.quad`
+ * carries.  The native side rectifies into a rectangle whose corners map
+ * TL→(0,0), TR→(w,0), BR→(w,h), BL→(0,h); pass un-ordered points and the
+ * output is mirrored / rotated.
+ */
+import type { Quad } from '../camera/cropGeometry';
+/** Options for {@link cropQuad}. */
+export interface CropQuadOptions {
+    /**
+     * JPEG quality for the re-encoded output, 1–100.  Defaults to 90 (the
+     * native default, matching `cropToRect`).
+     */
+    quality?: number;
+}
+/** Resolved result of a successful {@link cropQuad}. */
+export interface CropQuadResult {
+    /**
+     * The file the rectified image was written to.  Equals the input
+     * `imagePath` (the native crop overwrites in place) — surfaced
+     * explicitly so callers don't have to assume the in-place contract.
+     */
+    outputPath: string;
+    /** Width of the rectified rectangle, in pixels. */
+    width: number;
+    /** Height of the rectified rectangle, in pixels. */
+    height: number;
+}
+/**
+ * Flatten the 4 ordered ([TL, TR, BR, BL]) image-pixel corners into the
+ * `[tlX, tlY, trX, trY, brX, brY, blX, blY]` array the native module
+ * expects.  Exported for unit tests + reuse.
+ */
+export declare function flattenQuad(quad: Quad): number[];
+/**
+ * Perspective-rectify `quadImagePoints` out of `imagePath` into an upright
+ * rectangle, overwriting the file in place, and resolve the output path +
+ * rectified dimensions.
+ *
+ * @param imagePath        file:// URI (or bare path) of the image to crop.
+ * @param quadImagePoints  the 4 corners in IMAGE-PIXEL space, canonically
+ *                         ordered [TL, TR, BR, BL] (use
+ *                         `orderQuadCorners`).  This is exactly
+ *                         `RectCropResult.quad`.
+ * @param outPath          where to write the result.  The native crop
+ *                         OVERWRITES IN PLACE, so this currently MUST equal
+ *                         `imagePath` (or be omitted — defaults to it).
+ *                         Passing a different path throws, surfacing the
+ *                         limitation rather than silently ignoring it; see
+ *                         the integrator note in the item-7 handoff.
+ * @param opts             optional `{ quality }`.
+ *
+ * @throws if the native module isn't registered, if `outPath` differs from
+ *         `imagePath`, or if the native crop rejects (degenerate quad,
+ *         canvas guard, write failure).
+ */
+export declare function cropQuad(imagePath: string, quadImagePoints: Quad, outPath?: string, opts?: CropQuadOptions): Promise<CropQuadResult>;
+//# sourceMappingURL=cropQuad.d.ts.map

package/dist/stitching/cropQuad.js

@@ -0,0 +1,116 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * cropQuad — item-7 perspective crop: rectify a user-dragged
+ * quadrilateral to an upright rectangle.
+ *
+ * The post-capture crop editor (`src/camera/RectCropPreview.tsx`) lets the
+ * user drag 4 independent corners over the stitched result.  When that
+ * quad isn't ~axis-aligned, the host calls THIS wrapper instead of the
+ * cheap `cropToRect`: it hands the 4 IMAGE-PIXEL corners to the native
+ * `BatchStitcher.cropToQuad`, which runs
+ * `cv::getPerspectiveTransform` + `cv::warpPerspective` to produce an
+ * upright rectangle (averaged opposite-edge dimensions) and overwrites the
+ * file in place.
+ *
+ * This is the typed twin of the `cropToRect` call in
+ * `example/InscribedRectDebug.tsx` — same native module (`BatchStitcher`),
+ * same in-place overwrite + `{ width, height }` result contract, same
+ * platform-availability fallback posture as
+ * `src/quality/normaliseOrientation.ts`.
+ *
+ * Corner-order contract: `quadImagePoints` MUST be in canonical
+ * [TL, TR, BR, BL] (clockwise from top-left) order — exactly what
+ * `cropGeometry.ts:orderQuadCorners` produces and `RectCropResult.quad`
+ * carries.  The native side rectifies into a rectangle whose corners map
+ * TL→(0,0), TR→(w,0), BR→(w,h), BL→(0,h); pass un-ordered points and the
+ * output is mirrored / rotated.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flattenQuad = flattenQuad;
+exports.cropQuad = cropQuad;
+const react_native_1 = require("react-native");
+/**
+ * Resolve the native `cropToQuad` function off `NativeModules.BatchStitcher`,
+ * or `null` when the module / method isn't registered (e.g. an older native
+ * build).  Same defensive lookup as `normaliseOrientation`.
+ */
+function resolveCropToQuad() {
+    const native = react_native_1.NativeModules['BatchStitcher'];
+    if (native
+        && typeof native === 'object'
+        && typeof native.cropToQuad === 'function') {
+        return native.cropToQuad;
+    }
+    return null;
+}
+/**
+ * Flatten the 4 ordered ([TL, TR, BR, BL]) image-pixel corners into the
+ * `[tlX, tlY, trX, trY, brX, brY, blX, blY]` array the native module
+ * expects.  Exported for unit tests + reuse.
+ */
+function flattenQuad(quad) {
+    const out = [];
+    for (const p of quad) {
+        out.push(p.x, p.y);
+    }
+    return out;
+}
+/**
+ * Perspective-rectify `quadImagePoints` out of `imagePath` into an upright
+ * rectangle, overwriting the file in place, and resolve the output path +
+ * rectified dimensions.
+ *
+ * @param imagePath        file:// URI (or bare path) of the image to crop.
+ * @param quadImagePoints  the 4 corners in IMAGE-PIXEL space, canonically
+ *                         ordered [TL, TR, BR, BL] (use
+ *                         `orderQuadCorners`).  This is exactly
+ *                         `RectCropResult.quad`.
+ * @param outPath          where to write the result.  The native crop
+ *                         OVERWRITES IN PLACE, so this currently MUST equal
+ *                         `imagePath` (or be omitted — defaults to it).
+ *                         Passing a different path throws, surfacing the
+ *                         limitation rather than silently ignoring it; see
+ *                         the integrator note in the item-7 handoff.
+ * @param opts             optional `{ quality }`.
+ *
+ * @throws if the native module isn't registered, if `outPath` differs from
+ *         `imagePath`, or if the native crop rejects (degenerate quad,
+ *         canvas guard, write failure).
+ */
+async function cropQuad(imagePath, quadImagePoints, outPath, opts) {
+    if (outPath !== undefined && outPath !== imagePath) {
+        // The native cropToQuad (like cropToRect) only overwrites in place.
+        // Fail loudly rather than silently writing to imagePath and returning
+        // a path the file isn't at.
+        throw new Error('[capture-sdk] cropQuad: native crop overwrites in place; '
+            + 'outPath must equal imagePath (or be omitted).');
+    }
+    const fn = resolveCropToQuad();
+    if (!fn) {
+        throw new Error(`[capture-sdk] cropQuad: native module BatchStitcher.cropToQuad not `
+            + `available on ${react_native_1.Platform.OS}.  Ensure the native module is registered.`);
+    }
+    const quality = clampQuality(opts?.quality);
+    const dims = await fn({
+        imagePath,
+        quad: flattenQuad(quadImagePoints),
+        quality,
+    });
+    return {
+        outputPath: imagePath,
+        width: dims.width,
+        height: dims.height,
+    };
+}
+/** Clamp the requested JPEG quality into [1, 100]; default 90. */
+function clampQuality(quality) {
+    if (quality === undefined || Number.isNaN(quality))
+        return 90;
+    if (quality < 1)
+        return 1;
+    if (quality > 100)
+        return 100;
+    return Math.round(quality);
+}
+//# sourceMappingURL=cropQuad.js.map

package/dist/stitching/incremental.d.ts

@@ -639,6 +639,33 @@ export interface IncrementalFinalizeResult {
      * on the just-completed capture.
      */
     stitchModeResolved?: 'panorama' | 'scans';
+    /**
+     * 2026-06-14 (DEV overlay) — a semicolon-separated `key=value` trace of the
+     * stitcher's RUNTIME choices for this output, e.g.
+     * `"pipe=manual;warp=spherical;route=batch;seam=graphcut;blend=multiband"`.
+     *   pipe:  `manual` (cv::detail) | `highlevel` (cv::Stitcher)
+     *   warp:  `plane` | `cylindrical` | `spherical`
+     *   route: `batch` (warp-all + seam) | `stream` (low-memory per-frame)
+     *   seam:  `graphcut` | `none`
+     *   blend: `multiband` | `feather`
+     * Intended for a __DEV__-only overlay so the operator can see HOW the
+     * panorama was built (which warper, whether the low-memory stream/feather
+     * fallback kicked in, etc.).  iOS only for now; undefined elsewhere.
+     */
+    debugSummary?: string;
+    /**
+     * 2026-06-15 (iOS) — the exact keyframe JPEG paths used for this stitch.
+     * Lets the host re-stitch the SAME frames on demand via `refinePanorama`
+     * (e.g. the high-level preview tab) without re-running the capture or
+     * enumerating the session directory.  iOS only; undefined elsewhere.
+     */
+    batchKeyframePaths?: string[];
+    /**
+     * 2026-06-15 (iOS) — the capture orientation this stitch baked into the
+     * output.  An on-demand re-stitch (refinePanorama) MUST pass this back or the
+     * result comes out in the raw sensor landscape (sideways).  iOS only.
+     */
+    captureOrientation?: string;
 }
 /**
  * 2026-05-16 — input to `refinePanorama`.  Mirrors the subset of
@@ -701,6 +728,15 @@ export interface IncrementalRefineOptions {
     stitchMode?: 'auto' | 'panorama' | 'scans';
     /** JPEG quality 1..100, default 90. */
     jpegQuality?: number;
+    /**
+     * 2026-06-15 (iOS) — which stitch pipeline to run.  `true` = the manual
+     * `cv::detail` pipeline (the default batch-capture output); `false` = stock
+     * high-level `cv::Stitcher`.  Default `false` on the refine path.  This is
+     * how the on-demand "high-level" preview tab re-stitches the captured
+     * keyframes via cv::Stitcher without re-running the whole capture.  iOS only
+     * (Android refine is always cv::Stitcher).
+     */
+    useManualPipeline?: boolean;
 }
 /**
  * 2026-05-16 — result of an explicit `refinePanorama` call.  Mirrors
@@ -720,6 +756,15 @@ export interface IncrementalRefineResult {
     framesDropped: number;
     /** The confidence threshold that succeeded.  -1 when not applicable. */
     finalConfidenceThresh: number;
+    /**
+     * 2026-06-15 (DEV overlay A/B-aware) — the stitcher's own semicolon-separated
+     * `key=value` runtime recipe for THIS refined output, e.g.
+     * `"pipe=highlevel;warp=spherical;route=batch;seam=graphcut;blend=multiband"`.
+     * Mirrors `IncrementalFinalizeResult.debugSummary`.  Lets the on-demand
+     * high-level preview tab show its OWN recipe in the __DEV__ overlay pill
+     * instead of the manual primary's recipe.  iOS only; undefined elsewhere.
+     */
+    debugSummary?: string;
 }
 /**
  * V15.0e — ARKit plane detection state, polled by the capture screen

package/ios/Sources/RNImageStitcher/IncrementalStitcher.swift

@@ -943,7 +943,7 @@ public final class IncrementalStitcher: NSObject {
         } else if let v = configOverrides["maxKeyframeIntervalMs"] as? Int {
             self.keyframeGate.maxKeyframeIntervalMs = max(0.0, Double(v))
         } else {
-            self.keyframeGate.maxKeyframeIntervalMs = 2000.0
+            self.keyframeGate.maxKeyframeIntervalMs = 1500.0
         }
         // V16 — novelty aggregation percentile.  Clamp at start to
         // [0.5, 0.99]; the bridge re-clamps but matching it here
@@ -1438,7 +1438,10 @@ public final class IncrementalStitcher: NSObject {
                             seamFinderType: payload.batchSeamFinderType,
                             captureOrientation: payload.captureOrientation,
                             useInscribedRectCrop: payload.batchEnableInscribedRectCrop,
-                            stitchMode: payload.batchStitchModeResolved
+                            stitchMode: payload.batchStitchModeResolved,
+                            // Batch capture = the default output = MANUAL pipeline
+                            // (graphcut + multiband + the full memory-guard set).
+                            useManualPipeline: true
                         )
                         // V16 fix-attempt 9 (verified on device,
                         // 2026-05-13) — sentinel-result detection.
@@ -1501,6 +1504,17 @@ public final class IncrementalStitcher: NSObject {
                             "batchKeyframeSessionDir":
                                 payload.collector?.sessionDir ?? "",
                             "batchKeyframeCount": payload.paths.count,
+                            // 2026-06-15 — the exact keyframe JPEG paths used for
+                            // this stitch, so JS can re-stitch them ON DEMAND via
+                            // refinePanorama (the high-level tab) without listing
+                            // the session dir itself.
+                            "batchKeyframePaths": payload.paths,
+                            // The orientation this stitch baked into the output.
+                            // The on-demand high-level re-stitch MUST pass the
+                            // same value or it comes out in the raw sensor
+                            // landscape (sideways) — refinePanorama otherwise
+                            // defaults to "portrait" (no bake-rotation).
+                            "captureOrientation": payload.captureOrientation,
                         ]
                         if r.framesRequested >= 0 {
                             batchDict["framesRequested"] = Int(r.framesRequested)
@@ -1523,6 +1537,12 @@ public final class IncrementalStitcher: NSObject {
                         // helps the operator understand why the
                         // panorama looks the way it does.
                         batchDict["stitchModeResolved"] = payload.batchStitchModeResolved
+                        // 2026-06-14 (DEV overlay) — the stitcher's runtime
+                        // choices (pipeline/warper/route/seam/blend) for this
+                        // output, shown on the preview in __DEV__.
+                        if !r.debugSummary.isEmpty {
+                            batchDict["debugSummary"] = r.debugSummary
+                        }
                         completion(batchDict, nil)
                     } catch let stitchErr as NSError {
                         completion(nil, stitchErr)
@@ -1641,6 +1661,11 @@ public final class IncrementalStitcher: NSObject {
         // at line 738 of src/stitching/incremental.ts).  JS callers
         // can override by passing config["stitchMode"].
         let refineStitchMode = (config["stitchMode"] as? String) ?? "scans"
+        // 2026-06-15 — pipeline is caller-selectable.  The on-demand high-level
+        // tab 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.
+        let refineManual = (config["useManualPipeline"] as? Bool) ?? false
         let quality     = max(1, min(100, (config["jpegQuality"] as? Int) ?? 90))
         let cleanedOutput = outputPath.hasPrefix("file://")
             ? String(outputPath.dropFirst(7))
@@ -1679,7 +1704,8 @@ public final class IncrementalStitcher: NSObject {
                     seamFinderType: seam,
                     captureOrientation: orientation,
                     useInscribedRectCrop: useInscribed,
-                    stitchMode: refineStitchMode
+                    stitchMode: refineStitchMode,
+                    useManualPipeline: refineManual
                 )
                 // fix-9 sentinel detection — see the finalize() path
                 // for the full rationale.  A 0×0 result means
@@ -1717,7 +1743,13 @@ public final class IncrementalStitcher: NSObject {
                     frames: frameCount,
                     errorMessage: nil
                 )
-                completion([
+                // 2026-06-15 (DEV overlay A/B-aware) — carry the stitcher's
+                // own runtime recipe up to JS so the preview's DEV pill shows
+                // the HIGH-LEVEL recipe (pipe=highlevel;warp=spherical;…) while
+                // the user views the high-level tab, instead of the manual
+                // primary's recipe.  Mirrors the batch finalize's batchDict
+                // (guard empty — empty string means unavailable).
+                var refineDict: [String: Any] = [
                     "panoramaPath": r.outputPath,
                     "width": Int(r.width),
                     "height": Int(r.height),
@@ -1725,7 +1757,11 @@ public final class IncrementalStitcher: NSObject {
                     "framesIncluded": frameCount,
                     "framesDropped": 0,
                     "finalConfidenceThresh": -1.0,
-                ], nil)
+                ]
+                if !r.debugSummary.isEmpty {
+                    refineDict["debugSummary"] = r.debugSummary
+                }
+                completion(refineDict, nil)
             } catch let err as NSError {
                 self?.emitRefineProgress(
                     stage: "error",
@@ -2450,11 +2486,23 @@ public final class IncrementalStitcher: NSObject {
         let denom = tScore + rScore
         if denom <= 1e-9 { return "panorama" }  // no motion either way
         let 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.  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.
+        let lowRotationGuard = rRadians > 0.35 && tMeters < 0.25
+        let mode = (!lowRotationGuard && ratio >= 0.55) ? "scans" : "panorama"
         os_log(.fault, log: Self.diagLog,
-               "[stitchMode.auto] tPose=%.3fm tImu=%.3fm r=%.3frad ratio=%.3f → %{public}@",
+               "[stitchMode.auto] tPose=%.3fm tImu=%.3fm r=%.3frad ratio=%.3f rotGuard=%d → %{public}@",
                tPose, imuTranslationMetres, rRadians, ratio,
-               ratio >= 0.55 ? "scans" : "panorama")
-        return ratio >= 0.55 ? "scans" : "panorama"
+               lowRotationGuard ? 1 : 0, mode)
+        return mode
     }
 
     /// Closed-form q · (0,0,-1) · q⁻¹ — rotates the camera-forward

package/ios/Sources/RNImageStitcher/KeyframeGate.swift

@@ -151,9 +151,9 @@ final class KeyframeGate {
     /// overlapThreshold.  Unlike `flowMaxTranslationCm` this applies to
     /// BOTH the Pose and Flow strategies, and is passed STRAIGHT
     /// THROUGH to the bridge (the unit is already what C++ expects — no
-    /// cm→m style conversion).  Default 2000 ms; 0 = disabled.  The C++
+    /// cm→m style conversion).  Default 1500 ms; 0 = disabled.  The C++
     /// setter clamps to ≥ 0.
-    var maxKeyframeIntervalMs: Double = 2000.0 {
+    var maxKeyframeIntervalMs: Double = 1500.0 {
         didSet {
             bridge.setMaxKeyframeIntervalMs(maxKeyframeIntervalMs)
         }

package/ios/Sources/RNImageStitcher/OpenCVKeyframeCollector.mm

@@ -12,6 +12,16 @@
 #include <opencv2/imgcodecs.hpp>
 #pragma pop_macro("NO")
 
+// v0.16 — keyframe long-edge clamp (px) applied before the JPEG is written.
+// The stitcher composites at ~1 MP (COMPOSE_MP) and `compose_scale` never
+// upscales, so a keyframe larger than ~1.2 MP only inflates the held-set RAM
+// (N × decoded frame) without sharpening the panorama — the 0.5× ultra-wide
+// otherwise lands ~8 MP/frame here.  1280 px sits just above the compose
+// target, so it reclaims ~6× of that RAM with zero quality loss.  (Android's
+// equivalent clamp is 640 px — a tighter low-RAM budget for A35-class
+// devices; iOS can afford the full compose resolution.)
+static const int kKeyframeMaxLongEdge = 1280;
+
 // V16 Phase 1.fix2 — write a JPEG with an EXIF Orientation tag so
 // iOS image renderers display the saved frame correctly while
 // cv::imread (with IMREAD_IGNORE_ORIENTATION) gets raw landscape
@@ -119,17 +129,26 @@ static BOOL WriteJPEGWithEXIF(const cv::Mat &bgr,
 
 - (nullable instancetype)initWithError:(NSError **)error {
   if ((self = [super init])) {
-    NSURL *appSupport = [[NSFileManager defaultManager]
-        URLForDirectory:NSApplicationSupportDirectory
+    // DEBUG builds write keyframes under Documents so they are inspectable in
+    // the Files app (gated by the example's Info.plist UIFileSharingEnabled +
+    // LSSupportsOpeningDocumentsInPlace).  RELEASE keeps them in the private,
+    // auto-cleaned ApplicationSupport dir.  See `cleanup` (retains in DEBUG).
+#if DEBUG
+    NSSearchPathDirectory baseDirType = NSDocumentDirectory;
+#else
+    NSSearchPathDirectory baseDirType = NSApplicationSupportDirectory;
+#endif
+    NSURL *baseDir = [[NSFileManager defaultManager]
+        URLForDirectory:baseDirType
                inDomain:NSUserDomainMask
       appropriateForURL:nil
                  create:YES
                   error:error];
-    if (!appSupport) return nil;
+    if (!baseDir) return nil;
     NSString *captureUUID = [[NSUUID UUID] UUIDString];
     NSString *sessionPath =
-        [[appSupport.path stringByAppendingPathComponent:@"Captures"]
-                          stringByAppendingPathComponent:captureUUID];
+        [[baseDir.path stringByAppendingPathComponent:@"Captures"]
+                       stringByAppendingPathComponent:captureUUID];
     BOOL ok = [[NSFileManager defaultManager]
                 createDirectoryAtPath:sessionPath
           withIntermediateDirectories:YES
@@ -190,6 +209,22 @@ static BOOL WriteJPEGWithEXIF(const cv::Mat &bgr,
     rotated = bgr;
   }
 
+  // Clamp the keyframe's long edge (see kKeyframeMaxLongEdge).  Uniform
+  // downscale — same factor on both axes — so it preserves aspect ratio AND
+  // orientation (no transpose/flip); the rotate above and the EXIF tag below
+  // are unaffected, only the pixel count shrinks.  INTER_AREA is the correct
+  // filter for downsampling.
+  {
+    const int longEdge =
+        rotated.cols > rotated.rows ? rotated.cols : rotated.rows;
+    if (longEdge > kKeyframeMaxLongEdge) {
+      const double s = (double)kKeyframeMaxLongEdge / (double)longEdge;
+      cv::Mat scaled;
+      cv::resize(rotated, scaled, cv::Size(), s, s, cv::INTER_AREA);
+      rotated = scaled;
+    }
+  }
+
   NSInteger idx = self.acceptedCount;
   NSString *filename =
       [NSString stringWithFormat:@"keyframe-%03ld.jpg", (long)idx];
@@ -230,8 +265,16 @@ static BOOL WriteJPEGWithEXIF(const cv::Mat &bgr,
 
 - (void)cleanup {
   if (self.sessionDir.length == 0) return;
+#if DEBUG
+  // DEBUG: keep the session's keyframes on disk so they can be inspected in
+  // the Files app (Documents/Captures/<uuid>/keyframe-NNN.jpg).  Each capture
+  // is a fresh UUID folder; delete old ones via Files when done.
+  NSLog(@"[KeyframeCollector] DEBUG — retaining keyframes for inspection: %@",
+        self.sessionDir);
+#else
   [[NSFileManager defaultManager] removeItemAtPath:self.sessionDir
                                              error:nil];
+#endif
 }
 
 // ── CVPixelBuffer → cv::Mat (BGR) ──────────────────────────────────

package/ios/Sources/RNImageStitcher/OpenCVStitcher.h

@@ -44,6 +44,10 @@ extern NSString *const RNImageStitcherErrorDomain;
 @property (nonatomic, assign, readonly) NSInteger framesRequested;
 @property (nonatomic, assign, readonly) NSInteger framesIncluded;
 @property (nonatomic, assign, readonly) double finalConfidenceThresh;
+/// 2026-06-14 (DEV overlay) — semicolon-separated `key=value` trace of the
+/// stitcher's runtime choices for this output (pipeline/warper/route/seam/
+/// blend), surfaced on the preview in __DEV__.  Empty string when unavailable.
+@property (nonatomic, copy, readonly) NSString *debugSummary;
 - (instancetype)initWithOutputPath:(NSString *)outputPath
                              width:(NSInteger)width
                             height:(NSInteger)height
@@ -108,6 +112,10 @@ extern NSString *const RNImageStitcherErrorDomain;
 ///     them.  With `useInscribedRectCrop:YES` we find the largest
 ///     axis-aligned rectangle entirely inside the non-zero region
 ///     and crop to that — clean output with no black corners.
+/// `useManualPipeline`: YES → the manual cv::detail pipeline (graphcut +
+///   multiband, with the full memory-guard machinery); NO → stock high-level
+///   cv::Stitcher.  The batch capture passes YES (the default output); the
+///   on-demand high-level tab re-stitches the same keyframes with NO.
 + (nullable RNStitchResult *)stitchFramePaths:(NSArray<NSString *> *)framePaths
                                           outputPath:(NSString *)outputPath
                                          jpegQuality:(NSInteger)quality
@@ -117,6 +125,7 @@ extern NSString *const RNImageStitcherErrorDomain;
                                   captureOrientation:(nullable NSString *)captureOrientation
                                 useInscribedRectCrop:(BOOL)useInscribedRectCrop
                                           stitchMode:(nullable NSString *)stitchMode
+                                   useManualPipeline:(BOOL)useManualPipeline
                                                error:(NSError **)error;
 
 /// Extract `maxFrames` evenly-spaced frames from the video at
@@ -194,6 +203,24 @@ extern NSString *const RNImageStitcherErrorDomain;
                                                            quality:(NSInteger)quality
                                                              error:(NSError **)error;
 
+/// item-7 — free-quad perspective crop.  Takes 4 IMAGE-PIXEL corners
+/// (ordered TL, TR, BR, BL) and rectifies the enclosed quadrilateral to
+/// an upright rectangle (cv::getPerspectiveTransform + warpPerspective),
+/// re-encodes at `quality`, overwrites in place.  Returns the rectified
+/// `{ width, height }`.  Rejects a degenerate / non-convex / out-of-bounds
+/// quad, and guards the output canvas with the shared canvasExceedsGuard.
++ (nullable NSDictionary<NSString *, NSNumber *> *)cropToQuadAtPath:(NSString *)imagePath
+                                                               tlX:(double)tlX
+                                                               tlY:(double)tlY
+                                                               trX:(double)trX
+                                                               trY:(double)trY
+                                                               brX:(double)brX
+                                                               brY:(double)brY
+                                                               blX:(double)blX
+                                                               blY:(double)blY
+                                                           quality:(NSInteger)quality
+                                                             error:(NSError **)error;
+
 /// v0.15 debug — write a red-tinted overlay JPEG (excluded / sub-threshold
 /// pixels rendered red) next to `imagePath` (suffix ".mask.jpg") so the
 /// harness can show WHY the inscribed rect lands where it does. Returns