react-native-image-stitcher 0.16.0 → 0.16.2

package/dist/camera/RectCropPreview.js

@@ -109,56 +109,8 @@ function seedImageQuad(imageWidth, imageHeight, initialRect) {
     ];
 }
 function RectCropPreview(props) {
-    const { imageUri, imageWidth, imageHeight, altImageUri, visible, onConfirm, onUseOriginal, onRetake, warnings, showCropControls = true, initialRect, copy, topInset = 0, bottomInset = 0, debugInfo, onRequestAlt, showMemoryPill, } = props;
+    const { imageUri, imageWidth, imageHeight, visible, onConfirm, onUseOriginal, onRetake, warnings, showCropControls = true, initialRect, copy, topInset = 0, bottomInset = 0, debugInfo, showMemoryPill, } = props;
     const resolvedCopy = (0, react_1.useMemo)(() => (0, cameraGuidanceCopy_1.mergeGuidanceCopy)(copy), [copy]);
-    // ── A/B comparison — the PRIMARY (imageUri) is the MANUAL pipeline (the
-    // default output).  The alt is HIGH-LEVEL cv::Stitcher, produced either
-    // EAGERLY (`altImageUri`, legacy) or ON DEMAND (`onRequestAlt`, re-stitched
-    // the first time the user opens the high-level tab).  `altSize` is fetched
-    // once the alt uri exists; when the alt is showing we use its dims for the
-    // contain-fit and hide the crop quad.
-    const [showingAlt, setShowingAlt] = (0, react_1.useState)(false);
-    const [lazyAltUri, setLazyAltUri] = (0, react_1.useState)(null);
-    // The high-level (alt) stitch's OWN DEV-overlay recipe, resolved alongside
-    // its uri from `onRequestAlt`.  Shown in the params pill in place of the
-    // manual primary's `debugInfo` while the high-level tab is being viewed.
-    const [lazyAltDebugInfo, setLazyAltDebugInfo] = (0, react_1.useState)(null);
-    const [altLoading, setAltLoading] = (0, react_1.useState)(false);
-    const [altFailed, setAltFailed] = (0, react_1.useState)(false);
-    const altUri = altImageUri ?? lazyAltUri ?? null;
-    const altOffered = !!altImageUri || !!onRequestAlt;
-    const [altSize, setAltSize] = (0, react_1.useState)(null);
-    react_1.default.useEffect(() => {
-        if (!altUri) {
-            setAltSize(null);
-            return;
-        }
-        react_native_1.Image.getSize(altUri, (w, h) => setAltSize({ w, h }), () => setAltSize(null));
-    }, [altUri]);
-    // Switch to the high-level (alt) view; compute it lazily on first request.
-    const showHighLevel = react_1.default.useCallback(() => {
-        setShowingAlt(true);
-        if (altUri || altLoading || !onRequestAlt)
-            return;
-        setAltFailed(false);
-        setAltLoading(true);
-        onRequestAlt()
-            .then((result) => {
-            if (result) {
-                setLazyAltUri(result.uri);
-                setLazyAltDebugInfo(result.debugInfo);
-            }
-            else {
-                setAltFailed(true);
-            }
-        })
-            .catch(() => setAltFailed(true))
-            .finally(() => setAltLoading(false));
-    }, [altUri, altLoading, onRequestAlt]);
-    const showAlt = showingAlt && !!altUri && !!altSize;
-    const activeUri = showAlt ? altUri : imageUri;
-    const activeW = showAlt ? altSize.w : imageWidth;
-    const activeH = showAlt ? altSize.h : imageHeight;
     // The 4 corners live in IMAGE-PIXEL space (the source of truth) so they
     // survive layout-box changes (rotation, keyboard) without drift.  We map
     // to screen for rendering and back on every drag via cropGeometry.
@@ -244,19 +196,18 @@ function RectCropPreview(props) {
     let imageBox = null;
     let screenCorners = null;
     if (box) {
-        const fit = (0, cropGeometry_1.containFit)(box, activeW, activeH);
+        const fit = (0, cropGeometry_1.containFit)(box, imageWidth, imageHeight);
         if (fit) {
             imageBox = {
                 left: fit.offX,
                 top: fit.offY,
-                width: activeW * fit.scale,
-                height: activeH * fit.scale,
+                width: imageWidth * fit.scale,
+                height: imageHeight * fit.scale,
             };
-            // Quad corners only apply to the primary (croppable) image — hidden
-            // while the alt (manual) output is shown for comparison.
-            screenCorners = showAlt
-                ? null
-                : imageQuad.map((p) => (0, cropGeometry_1.imageToScreen)(p, box, imageWidth, imageHeight));
+            // Quad corners only apply in crop mode.
+            screenCorners = showCropControls
+                ? imageQuad.map((p) => (0, cropGeometry_1.imageToScreen)(p, box, imageWidth, imageHeight))
+                : null;
         }
     }
     // Outline path (a <View> per edge — RN core has no <Polygon>; this
@@ -282,32 +233,16 @@ function RectCropPreview(props) {
         react_1.default.createElement(react_native_1.View, { style: [styles.root, { paddingTop: topInset }] },
             showMemoryPill ? (react_1.default.createElement(CaptureMemoryPill_1.CaptureMemoryPill, { style: {
                     position: 'absolute',
-                    top: topInset + (altOffered ? 76 : 8),
+                    top: topInset + 8,
                     left: 12,
                     zIndex: 21,
                 } })) : null,
-            (() => {
-                const pillText = showAlt && lazyAltDebugInfo ? lazyAltDebugInfo : debugInfo;
-                return pillText ? (react_1.default.createElement(react_native_1.View, { style: [
-                        styles.debugPill,
-                        { top: topInset + (altImageUri && altSize ? 76 : 8) },
-                    ], pointerEvents: "none", accessibilityRole: "text" },
-                    react_1.default.createElement(react_native_1.Text, { style: styles.debugPillText }, pillText))) : null;
-            })(),
+            debugInfo ? (react_1.default.createElement(react_native_1.View, { style: [styles.debugPill, { top: topInset + 8 }], pointerEvents: "none", accessibilityRole: "text" },
+                react_1.default.createElement(react_native_1.Text, { style: styles.debugPillText }, debugInfo))) : null,
             warnings && warnings.length > 0 && (react_1.default.createElement(react_native_1.View, { style: styles.warningBanner, accessibilityRole: "alert" }, warnings.map((w, i) => (react_1.default.createElement(react_native_1.Text, { key: `warn-${i}`, style: styles.warningText }, w))))),
-            altOffered && (react_1.default.createElement(react_native_1.View, { style: styles.abBar },
-                react_1.default.createElement(react_native_1.Text, { style: styles.abBarLabel }, altLoading
-                    ? 'Stitching high-level… (manual shown meanwhile)'
-                    : altFailed
-                        ? 'High-level stitch failed — showing manual'
-                        : 'Viewing the highlighted pipeline — tap to switch:'),
-                react_1.default.createElement(react_native_1.View, { style: styles.abSegments },
-                    react_1.default.createElement(react_native_1.Pressable, { style: [styles.abSeg, !showAlt && styles.abSegActive], onPress: () => setShowingAlt(false), accessibilityRole: "button", accessibilityState: { selected: !showAlt }, accessibilityLabel: "View manual pipeline (default)" },
-                        react_1.default.createElement(react_native_1.Text, { style: [styles.abSegText, !showAlt && styles.abSegTextActive] }, "Manual")),
-                    react_1.default.createElement(react_native_1.Pressable, { style: [styles.abSeg, showAlt && styles.abSegActive], onPress: showHighLevel, accessibilityRole: "button", accessibilityState: { selected: showAlt, busy: altLoading }, accessibilityLabel: "View high-level pipeline (computed on demand)" }, altLoading ? (react_1.default.createElement(react_native_1.ActivityIndicator, { size: "small", color: "#fff" })) : (react_1.default.createElement(react_native_1.Text, { style: [styles.abSegText, showAlt && styles.abSegTextActive] }, "High-level")))))),
             react_1.default.createElement(react_native_1.View, { style: styles.canvas, onLayout: onLayout },
-                imageBox && (react_1.default.createElement(react_native_1.Image, { source: { uri: activeUri }, style: [styles.image, imageBox], resizeMode: "stretch" })),
-                showCropControls && !showAlt && (react_1.default.createElement(react_1.default.Fragment, null,
+                imageBox && (react_1.default.createElement(react_native_1.Image, { source: { uri: imageUri }, style: [styles.image, imageBox], resizeMode: "stretch" })),
+                showCropControls && (react_1.default.createElement(react_1.default.Fragment, null,
                     edges.map((e, i) => (react_1.default.createElement(react_native_1.View, { key: `edge-${i}`, style: [styles.edge, e], pointerEvents: "none" }))),
                     screenCorners
                         && screenCorners.map((c, i) => (react_1.default.createElement(react_native_1.View, { key: `handle-${i}`, ...responders[i].panHandlers, hitSlop: {
@@ -327,26 +262,18 @@ function RectCropPreview(props) {
                 react_1.default.createElement(react_native_1.View, { style: styles.buttons },
                     react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [styles.btn, pressed && styles.btnPressed], onPress: onRetake, accessibilityRole: "button", accessibilityLabel: resolvedCopy.cropRetake },
                         react_1.default.createElement(react_native_1.Text, { style: styles.btnText }, resolvedCopy.cropRetake)),
-                    showCropControls && !showAlt && (react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [styles.btn, pressed && styles.btnPressed], onPress: () => onUseOriginal(), accessibilityRole: "button", accessibilityLabel: resolvedCopy.cropUseOriginal },
+                    showCropControls && (react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [styles.btn, pressed && styles.btnPressed], onPress: () => onUseOriginal(), accessibilityRole: "button", accessibilityLabel: resolvedCopy.cropUseOriginal },
                         react_1.default.createElement(react_native_1.Text, { style: styles.btnText }, resolvedCopy.cropUseOriginal))),
                     react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [
                             styles.btn,
                             styles.primary,
                             pressed && styles.btnPressed,
-                        ], onPress: showAlt
-                            ? () => onUseOriginal(activeUri)
-                            : showCropControls
-                                ? handleConfirm
-                                : () => onUseOriginal(), accessibilityRole: "button", accessibilityLabel: showAlt
-                            ? 'Use this output'
-                            : showCropControls
-                                ? resolvedCopy.cropConfirm
-                                : resolvedCopy.previewConfirm },
-                        react_1.default.createElement(react_native_1.Text, { style: styles.btnText }, showAlt
-                            ? 'Use this'
-                            : showCropControls
-                                ? resolvedCopy.cropConfirm
-                                : resolvedCopy.previewConfirm)))))));
+                        ], onPress: showCropControls ? handleConfirm : () => onUseOriginal(), accessibilityRole: "button", accessibilityLabel: showCropControls
+                            ? resolvedCopy.cropConfirm
+                            : resolvedCopy.previewConfirm },
+                        react_1.default.createElement(react_native_1.Text, { style: styles.btnText }, showCropControls
+                            ? resolvedCopy.cropConfirm
+                            : resolvedCopy.previewConfirm)))))));
 }
 /**
  * Absolute-positioned style for a 1-px-thick edge line between two
@@ -404,43 +331,6 @@ const styles = react_native_1.StyleSheet.create({
         fontSize: 13,
         fontWeight: '600',
     },
-    abBar: {
-        backgroundColor: '#1a1a1a',
-        paddingVertical: 10,
-        paddingHorizontal: 12,
-        borderBottomWidth: react_native_1.StyleSheet.hairlineWidth,
-        borderBottomColor: '#333',
-    },
-    abBarLabel: {
-        color: '#aaa',
-        fontSize: 11,
-        fontWeight: '600',
-        textAlign: 'center',
-        marginBottom: 8,
-    },
-    abSegments: {
-        flexDirection: 'row',
-        alignSelf: 'center',
-        backgroundColor: '#000',
-        borderRadius: 9,
-        padding: 3,
-    },
-    abSeg: {
-        paddingVertical: 7,
-        paddingHorizontal: 22,
-        borderRadius: 7,
-    },
-    abSegActive: {
-        backgroundColor: '#0A84FF',
-    },
-    abSegText: {
-        color: '#9aa',
-        fontSize: 14,
-        fontWeight: '700',
-    },
-    abSegTextActive: {
-        color: '#fff',
-    },
     canvas: { flex: 1 },
     image: { position: 'absolute' },
     edge: {

package/dist/stitching/incremental.d.ts

@@ -639,6 +639,23 @@ 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.
@@ -844,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;
@@ -875,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}@",
@@ -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,10 +1476,15 @@ public final class IncrementalStitcher: NSObject {
                             seamFinderType: payload.batchSeamFinderType,
                             captureOrientation: payload.captureOrientation,
                             useInscribedRectCrop: payload.batchEnableInscribedRectCrop,
-                            stitchMode: payload.batchStitchModeResolved,
-                            // Batch capture = the default output = MANUAL pipeline
-                            // (graphcut + multiband + the full memory-guard set).
-                            useManualPipeline: true
+                            // 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.
@@ -1537,6 +1580,11 @@ 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__.
@@ -2449,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]
@@ -2467,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:
@@ -2484,7 +2525,7 @@ 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
@@ -2502,7 +2543,43 @@ public final class IncrementalStitcher: NSObject {
                "[stitchMode.auto] tPose=%.3fm tImu=%.3fm r=%.3frad ratio=%.3f rotGuard=%d → %{public}@",
                tPose, imuTranslationMetres, rRadians, ratio,
                lowRotationGuard ? 1 : 0, mode)
-        return 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

package/ios/Sources/RNImageStitcher/IncrementalStitcherBridge.m

@@ -56,6 +56,10 @@ RCT_EXTERN_METHOD(markNextFrameAsLastKeyframe:(RCTPromiseResolveBlock)resolver
 RCT_EXTERN_METHOD(getMemoryFootprintMB:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 
+// 2026-06-16 — total physical RAM (MB) for the pill's RAM-aware pressure bands.
+RCT_EXTERN_METHOD(getDeviceTotalRamMB:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
 // 2026-05-16 — realtime+batch fusion (Option A "Replace on completion").
 // Run the shared C++ stitcher over a caller-supplied list of keyframe
 // JPEG paths and write a refined panorama to `outputPath`.  See JS

package/ios/Sources/RNImageStitcher/IncrementalStitcherBridge.swift

@@ -217,6 +217,10 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
         // and to PANORAMA when both are 0).
         let imuT = (options["imuTranslationMetres"] as? Double) ?? 0.0
         IncrementalStitcher.shared.updateImuTranslationMetres(imuT)
+        // 2026-06-16 — the EXPLICIT lens the user selected ('1x'|'0.5x'): the
+        // reliable zoom signal for the high-level warper tree (0.5x → spherical).
+        let lens = (options["lens"] as? String) ?? "1x"
+        IncrementalStitcher.shared.updateLens(lens)
         IncrementalStitcher.shared.finalize(
             toPath: outputPath,
             jpegQuality: quality
@@ -325,6 +329,17 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
         resolver(mb)
     }
 
+    /// Total physical RAM in MB.  Lets the DEV memory pill derive RAM-aware
+    /// pressure bands (iOS jetsam scales with device RAM) instead of fixed
+    /// thresholds.  NSProcessInfo.physicalMemory is exact + cheap.
+    @objc(getDeviceTotalRamMB:rejecter:)
+    public func getDeviceTotalRamMB(
+        resolver: @escaping RCTPromiseResolveBlock,
+        rejecter: @escaping RCTPromiseRejectBlock
+    ) {
+        resolver(Double(ProcessInfo.processInfo.physicalMemory) / (1024.0 * 1024.0))
+    }
+
     /// 2026-05-16 — realtime+batch fusion (Option A) bridge.  Marshal
     /// the options dictionary into the engine layer, dispatch the
     /// refinement off the bridge thread so the JS Promise doesn't block

package/ios/Sources/RNImageStitcher/OpenCVStitcher.mm

@@ -509,6 +509,17 @@ cv::detail::CameraParams cameraParamsFromPose(NSDictionary *pose) {
   // output); the on-demand high-level tab re-stitches with NO.
   cfg.useManualPipeline = useManualPipeline;
 
+  // 2026-06-16 — iOS resident-memory probe.  iOS has no /proc/self/statm, so the
+  // shared rss_mb() returned -1 — which (a) blinded the per-stitch profiling and
+  // (b) silently DISABLED the runtime-pressure half of the manual pipeline's OOM
+  // router (the lowBatchHeadroom STREAM trigger), on the very platform (jetsam)
+  // it protects.  Plug task_info(TASK_VM_INFO).phys_footprint (the metric jetsam
+  // evaluates) as the probe.  Set UNCONDITIONALLY — the OOM guards must work in
+  // release too; only the sampler + per-stitch record are gated by the compile
+  // flag (debug-on, release-off).
+  cfg.memProbeFn = []() -> double { return StitcherResidentMB(); };
+  cfg.enableMemoryProfiling = (RNIS_MEMORY_PROFILING != 0);
+
   // Marshal NSArray<NSString*> → std::vector<std::string>.  Strip the
   // `file://` scheme that some callers attach so the shared C++ can
   // cv::imread the raw filesystem path.
@@ -590,8 +601,17 @@ cv::detail::CameraParams cameraParamsFromPose(NSDictionary *pose) {
               framesIncluded:(NSInteger)r.framesIncluded
        finalConfidenceThresh:r.finalConfidenceThresh];
       if (!r.debugSummary.empty()) {
+        std::string dbg = r.debugSummary;
+        // iOS has no mallopt purge; the post-stitch settle read IS the leak
+        // floor (memFloor).  Append it so it rides debugSummary to JS like
+        // Android's post-purge value (gated; debug-only).
+        if (RNIS_MEMORY_PROFILING != 0) {
+          char fbuf[40];
+          snprintf(fbuf, sizeof(fbuf), ";memFloor=%.1f", StitcherResidentMB());
+          dbg += fbuf;
+        }
         result.debugSummary =
-            [NSString stringWithUTF8String:r.debugSummary.c_str()];
+            [NSString stringWithUTF8String:dbg.c_str()];
       }
       // 2026-06-15 — the eager A/B harness that ALSO stitched the high-level
       // alt on EVERY capture has been REMOVED.  Manual is now the default (this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",