react-native-image-stitcher 0.15.2 → 0.16.1

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,50 @@ export interface IncrementalFinalizeResult {
      * on the just-completed capture.
      */
     stitchModeResolved?: 'panorama' | 'scans';
+    /**
+     * 2026-06-15 (DEV) — gyro rotation magnitude of the capture, in RADIANS
+     * (angle between the first and last accepted keyframe camera-forward vectors).
+     * Surfaced so a dev tool can display it and tune the panorama-vs-SCANS
+     * rotation threshold from real captures. `0` when there is no pose-derived
+     * rotation signal (non-AR with no poses) — not necessarily "no rotation".
+     */
+    rRadians?: number;
+    /**
+     * 2026-06-16 (DEV) — translation magnitude (metres) and the auto decision
+     * ratio (`tScore/(tScore+rScore)`, `>=0.55` → SCANS) that drove the
+     * panorama-vs-SCANS choice. Surfaced alongside `rRadians` so a dev tool can
+     * display the full decision inputs and tune the threshold from real captures.
+     * `0` when there is no motion signal (non-AR with no poses / no movement).
+     */
+    tMeters?: number;
+    decisionRatio?: number;
+    /**
+     * 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 +745,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 +773,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
@@ -799,6 +861,14 @@ interface NativeIncrementalModule {
          * are zero, matching legacy behaviour.
          */
         imuTranslationMetres?: number;
+        /**
+         * 2026-06-16 — the explicit lens the user selected (`'1x'` | `'0.5x'`).
+         * The reliable zoom signal for the high-level warper tree: `'0.5x'`
+         * (ultra-wide) → spherical warper.  Replaces deriving zoom from the
+         * intrinsics FOV (unreliable on multi-cam 0.5x / non-AR fx=0).  Omitted →
+         * treated as `'1x'`.
+         */
+        lens?: string;
     }): Promise<IncrementalFinalizeResult>;
     cancel(): Promise<{
         ok: true;
@@ -830,6 +900,10 @@ interface NativeIncrementalModule {
      *  one-true-number for "how close are we to OOM?".  Returns -1
      *  on task_info failure (very rare).  Resolves immediately. */
     getMemoryFootprintMB(): Promise<number>;
+    /** 2026-06-16 — total physical RAM in MB.  Lets the DEV memory pill derive
+     *  RAM-aware pressure bands instead of iPhone-fixed thresholds.  -1 on
+     *  failure.  Resolves immediately. */
+    getDeviceTotalRamMB?(): Promise<number>;
     /**
      * 2026-05-16 — realtime+batch fusion API foundation.  Run the
      * shared C++ `cv::Stitcher` pipeline over a caller-supplied list

package/dist/stitching/useIncrementalStitcher.d.ts

@@ -61,7 +61,13 @@ export interface UseIncrementalStitcherReturn {
      * (e.g. in AR mode the native side has its own pose-driven
      * translation magnitude and prefers that).
      */
-    imuTranslationMetres?: number) => Promise<IncrementalFinalizeResult>;
+    imuTranslationMetres?: number, 
+    /**
+     * 2026-06-16 — the EXPLICIT lens the user selected (`'1x'` | `'0.5x'`).
+     * The reliable zoom signal for the high-level warper tree (`'0.5x'`
+     * ultra-wide → spherical).  Omit ⇒ treated as `'1x'`.
+     */
+    lens?: string) => Promise<IncrementalFinalizeResult>;
     /** Abort the capture without producing output. */
     cancel: () => Promise<void>;
 }

package/dist/stitching/useIncrementalStitcher.js

@@ -110,7 +110,7 @@ function useIncrementalStitcher() {
         setState(null);
         lastHintRef.current = null;
     }, [native]);
-    const finalize = (0, react_1.useCallback)(async (outputPath, quality = 90, captureOrientation, imuTranslationMetres) => {
+    const finalize = (0, react_1.useCallback)(async (outputPath, quality = 90, captureOrientation, imuTranslationMetres, lens) => {
         if (!native) {
             throw new Error('useIncrementalStitcher: native module unavailable');
         }
@@ -128,6 +128,12 @@ function useIncrementalStitcher() {
             // doesn't carry tx/ty/tz, so pose-derived translation is 0).
             // Native side treats it as a magnitude (always ≥ 0).
             imuTranslationMetres: Math.max(0, imuTranslationMetres ?? 0),
+            // 2026-06-16 — the EXPLICIT lens the user selected ('1x' | '0.5x').
+            // This is the reliable zoom signal for the high-level warper tree
+            // (0.5x ultra-wide → spherical); deriving zoom from intrinsics FOV was
+            // unreliable (multi-cam 0.5x reaches the ultra-wide by zoom without
+            // changing the reported fx, and the non-AR path may supply fx=0).
+            lens,
         });
         setIsRunning(false);
         // Clear React state on finalize so the next start doesn't

package/ios/Sources/RNImageStitcher/IncrementalStitcher.swift

@@ -223,6 +223,15 @@ struct FinalizePayload {
     /// resolved upstream by `resolveStitchModeAuto` before this snapshot
     /// is captured; this field never carries 'auto'.
     let batchStitchModeResolved: String
+    /// Gyro rotation magnitude (radians) of the capture — surfaced to JS for the
+    /// dev 3-tab preview's rRadians readout (threshold tuning).  0.0 when there
+    /// is no pose-derived rotation signal (non-AR with no poses).
+    let rRadians: Double
+    /// Translation magnitude (metres) + the auto decision ratio
+    /// (tScore/(tScore+rScore), >=0.55 → SCANS) that drove the panorama-vs-SCANS
+    /// choice — surfaced to JS for the dev tuning readout alongside rRadians.
+    let tMeters: Double
+    let decisionRatio: Double
     let keyframeExifOrientation: Int
     /// AR-STITCHING-TWO-MODES (memory/ar-stitching-two-modes.md):
     /// capture-time hold orientation for the bake-rotation pass.
@@ -430,6 +439,10 @@ public final class IncrementalStitcher: NSObject {
     /// AR mode (where pose-derived tx/ty/tz is always 0).  Set to 0
     /// at start() and overwritten at finalize() entry.
     private var batchImuTranslationMetres: Double = 0.0
+    /// 2026-06-16 — the explicit lens the user selected ('1x' | '0.5x'), set at
+    /// finalize() entry from JS.  The zoom signal for the high-level warper tree
+    /// (0.5x ultra-wide → spherical).  Defaults to '1x'.
+    private var batchLens: String = "1x"
     /// AR-STITCHING-TWO-MODES — see memory/ar-stitching-two-modes.md
     ///
     /// Physical phone orientation at start() time, sourced from the
@@ -492,6 +505,14 @@ public final class IncrementalStitcher: NSObject {
         stateLock.unlock()
     }
 
+    /// 2026-06-16 — store the explicit lens ('1x' | '0.5x') JS supplies at
+    /// finalize() entry; the high-level warper tree reads it (0.5x → spherical).
+    @objc public func updateLens(_ lens: String) {
+        stateLock.lock()
+        self.batchLens = lens
+        stateLock.unlock()
+    }
+
     /// 2026-05-18 (Iss 3) — return the current capture's keyframe
     /// session directory, or nil if no capture is in flight / engine
     /// isn't using a per-session keyframe collector.
@@ -829,6 +850,7 @@ public final class IncrementalStitcher: NSObject {
             // too.  Updated at finalize() entry from JS-supplied
             // option value.
             self.batchImuTranslationMetres = 0.0
+            self.batchLens = "1x"  // overwritten at finalize() from JS (updateLens)
             self.batchKeyframeMode = true
             os_log(.fault, log: Self.diagLog,
                    "[V16-batch-keyframe] start mode=batch-keyframe rotation=0 (was %d, forced to 0 to match pose intrinsics) sessionDir=%{public}@",
@@ -943,7 +965,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
@@ -1147,20 +1169,33 @@ public final class IncrementalStitcher: NSObject {
         // translation/rotation magnitude ratio between first + last
         // accepted keyframe poses → SCANS (translation-heavy) or
         // PANORAMA (rotation-heavy).  Non-auto values pass through.
+        // Resolve once so the dev readout gets the SAME tMeters / ratio / rRadians
+        // that drove the decision — and gets them even when the mode is forced
+        // (informative: shows what auto WOULD have picked).  Captured into the
+        // payload here so the C2-invariant finalize closure can read them via
+        // payload (no self/ivar access inside the closure).
+        let autoResolution = resolveStitchModeAuto(
+            first: batchFirstAcceptedPose,
+            last:  batchLastAcceptedPose,
+            imuTranslationMetres: batchImuTranslationMetres)
         let stitchModeResolved: String
         switch batchStitchMode {
         case "panorama": stitchModeResolved = "panorama"
         case "scans":    stitchModeResolved = "scans"
-        default:         stitchModeResolved = resolveStitchModeAuto(
-                            first: batchFirstAcceptedPose,
-                            last:  batchLastAcceptedPose,
-                            imuTranslationMetres: batchImuTranslationMetres
-                         )
+        default:         stitchModeResolved = autoResolution.mode
         }
+        let rRadiansResolved = autoResolution.rRadians
+        // 2026-06-16 — HIGH-LEVEL ACROSS THE BOARD (mirrors Android).  Pick the
+        // warper from the (motion, Mode A/B, lens) tree; the dispatch below now
+        // forces useManualPipeline=false + stitchMode="panorama".  batchWarperType
+        // (settings) is superseded by the tree.
+        let highLevelWarper = pickHighLevelWarper(
+            orientation: captureOrientation,
+            lens: batchLens)
         os_log(.fault, log: Self.diagLog,
-               "[V16-batch-keyframe.stitchMode] configured=%{public}@ resolved=%{public}@ paths=%d imuT=%.3fm",
-               batchStitchMode, stitchModeResolved, Int32(paths.count),
-               batchImuTranslationMetres)
+               "[V16-batch-keyframe.stitchMode] configured=%{public}@ resolved=%{public}@ warper=%{public}@ lens=%{public}@ paths=%d imuT=%.3fm",
+               batchStitchMode, stitchModeResolved, highLevelWarper, batchLens,
+               Int32(paths.count), batchImuTranslationMetres)
 
         let payload = FinalizePayload(
             cleaned: cleaned,
@@ -1168,11 +1203,14 @@ public final class IncrementalStitcher: NSObject {
             inBatchKeyframeMode: inBatchKeyframeMode,
             collector: collector,
             paths: paths,
-            batchWarperType: batchWarperType,
+            batchWarperType: highLevelWarper,
             batchBlenderType: batchBlenderType,
             batchSeamFinderType: batchSeamFinderType,
             batchEnableInscribedRectCrop: batchEnableInscribedRectCrop,
             batchStitchModeResolved: stitchModeResolved,
+            rRadians: rRadiansResolved,
+            tMeters: autoResolution.tMeters,
+            decisionRatio: autoResolution.ratio,
             keyframeExifOrientation: keyframeExifOrientation,
             captureOrientation: captureOrientation,
             drops: drops,
@@ -1438,7 +1476,15 @@ public final class IncrementalStitcher: NSObject {
                             seamFinderType: payload.batchSeamFinderType,
                             captureOrientation: payload.captureOrientation,
                             useInscribedRectCrop: payload.batchEnableInscribedRectCrop,
-                            stitchMode: payload.batchStitchModeResolved
+                            // 2026-06-16 — HIGH-LEVEL ACROSS THE BOARD (mirrors
+                            // Android): always cv::Stitcher PANORAMA with the
+                            // tree-chosen warper (payload.batchWarperType is now
+                            // highLevelWarper).  The manual path's OOM hardening
+                            // was ported to high-level (catch ladder + two-phase
+                            // canvas guard + RAM-aware compositingResol + spherical
+                            // rescue), so this is now memory-safe.
+                            stitchMode: "panorama",
+                            useManualPipeline: false
                         )
                         // V16 fix-attempt 9 (verified on device,
                         // 2026-05-13) — sentinel-result detection.
@@ -1501,6 +1547,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 +1580,17 @@ public final class IncrementalStitcher: NSObject {
                         // helps the operator understand why the
                         // panorama looks the way it does.
                         batchDict["stitchModeResolved"] = payload.batchStitchModeResolved
+                        batchDict["rRadians"] = payload.rRadians
+                        // Dev tuning readout — translation magnitude + the auto
+                        // decision ratio that drove panorama-vs-SCANS.
+                        batchDict["tMeters"] = payload.tMeters
+                        batchDict["decisionRatio"] = payload.decisionRatio
+                        // 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 +1709,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 +1752,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 +1791,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 +1805,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",
@@ -2413,13 +2497,13 @@ public final class IncrementalStitcher: NSObject {
         first: [Double]?,
         last:  [Double]?,
         imuTranslationMetres: Double
-    ) -> String {
+    ) -> (mode: String, rRadians: Double, tMeters: Double, ratio: Double) {
         guard let firstPose = first, firstPose.count == 7,
               let lastPose  = last,  lastPose.count == 7  else {
             // No pose data at all — fall back on whichever signal we
             // do have.  imuTranslationMetres > 0 hints "scans"; 0
-            // hints "panorama".
-            return imuTranslationMetres > 0.05 ? "scans" : "panorama"
+            // hints "panorama".  rRadians 0.0 — no gyro signal.
+            return (imuTranslationMetres > 0.05 ? "scans" : "panorama", 0.0, 0.0, 0.0)
         }
         // Translation magnitude (Euclidean, in metres).
         let dtx = lastPose[0] - firstPose[0]
@@ -2431,14 +2515,7 @@ public final class IncrementalStitcher: NSObject {
         // the only signal we have.
         let tMeters = max(tPose, imuTranslationMetres)
         // Rotation magnitude — angle between camera-forward vectors.
-        // Camera-forward in body frame is (0, 0, -1) for ARKit/ARCore.
-        let fwdFirst = qrotForwardZneg(
-            firstPose[3], firstPose[4], firstPose[5], firstPose[6])
-        let fwdLast = qrotForwardZneg(
-            lastPose[3], lastPose[4], lastPose[5], lastPose[6])
-        let dot = max(-1.0, min(1.0,
-            fwdFirst.0 * fwdLast.0 + fwdFirst.1 * fwdLast.1 + fwdFirst.2 * fwdLast.2))
-        let rRadians = acos(dot)
+        let rRadians = rotationRadians(first: firstPose, last: lastPose)
         // Normalisation: 10 cm of translation ≈ 1 rad of rotation as
         // "equivalent magnitude" for the ratio.  Shelf scans cover
         // ~30 cm translation with ~10° (0.17 rad) rotation:
@@ -2448,13 +2525,61 @@ public final class IncrementalStitcher: NSObject {
         let tScore = tMeters / 0.10
         let rScore = rRadians / 1.00
         let denom = tScore + rScore
-        if denom <= 1e-9 { return "panorama" }  // no motion either way
+        if denom <= 1e-9 { return ("panorama", rRadians, tMeters, 0.0) }  // 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, rRadians, tMeters, ratio)
+    }
+
+    /// 2026-06-16 — high-level warper decision tree (mirrors Android's
+    /// pickHighLevelWarper).  The pipeline is now ALWAYS high-level cv::Stitcher
+    /// PANORAMA.  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.  orientation = capture hold ("landscape*" = Mode A vertical
+    /// pan; else Mode B horizontal); lens = the EXPLICIT lens ("0.5x" | "1x").
+    ///
+    ///     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 func pickHighLevelWarper(
+        orientation: String,
+        lens: String
+    ) -> String {
+        if lens == "0.5x" { return "spherical" }           // ultra-wide → always spherical
+        let verticalPanModeA = orientation.hasPrefix("landscape")
+        return verticalPanModeA ? "plane" : "cylindrical"  // 1x: A→plane, B→cylindrical
+    }
+
+    /// Gyro rotation magnitude (radians) between two 7-element poses
+    /// `[tx,ty,tz,qx,qy,qz,qw]` — angle between camera-forward vectors.
+    /// Returns 0.0 if either pose is missing/malformed (non-AR, no pose).
+    /// Shared by `resolveStitchModeAuto` + the finalize `rRadians` readout (DRY).
+    private func rotationRadians(first: [Double]?, last: [Double]?) -> Double {
+        guard let f = first, f.count == 7, let l = last, l.count == 7 else { return 0.0 }
+        let fwdFirst = qrotForwardZneg(f[3], f[4], f[5], f[6])
+        let fwdLast  = qrotForwardZneg(l[3], l[4], l[5], l[6])
+        let dot = max(-1.0, min(1.0,
+            fwdFirst.0 * fwdLast.0 + fwdFirst.1 * fwdLast.1 + fwdFirst.2 * fwdLast.2))
+        return acos(dot)
     }
 
     /// Closed-form q · (0,0,-1) · q⁻¹ — rotates the camera-forward