react-native-image-stitcher 0.15.2 → 0.16.1

package/cpp/stitcher.cpp

@@ -30,18 +30,24 @@
 #include <opencv2/stitching/warpers.hpp>
 
 #include <algorithm>
+#include <atomic>
 #include <chrono>
 #include <cfloat>
 #include <cmath>
 #include <cstdarg>
 #include <cstdio>
 #include <cstring>
+#include <functional>
 #include <string>
+#include <thread>
 #include <unistd.h>
 #include <vector>
 
 #include "warp_guard.hpp"
 
+// RNIS_MEMORY_PROFILING is defined in stitcher.hpp (shared across the 3 native
+// translation units).  kMemProfilingCompiled exposes it as a constexpr below.
+
 
 namespace retailens {
 
@@ -69,12 +75,21 @@ void log_error(const LogFn& logFn, const char* tag, const char* fmt, ...) {
     logFn(2, tag, buf);
 }
 
-// Read /proc/self/statm to get RSS in MB.  Cheap (~20 µs).  Used at
-// pipeline phase boundaries to correlate logged peak memory with the
-// staging-resolution + retry decisions.  Returns -1 on read failure
-// (e.g., procfs not mounted — never happens on iOS/Android but we
-// guard for portability).
-double rss_mb() {
+// Compile-time gate as a constexpr (so dead branches fold away in release).
+constexpr bool kMemProfilingCompiled = (RNIS_MEMORY_PROFILING != 0);
+
+// Per-stitch resident-memory probe, installed for the duration of a stitch by
+// MemProbeScope below.  Lets rss_mb() (and therefore every OOM guard, phase log,
+// the peak sampler and the per-stitch record) read the platform's real source
+// without threading `config` through dozens of call sites.  Calls are serialized
+// (stitchFramePaths contract), and the sampler thread only reads it within the
+// scope's lifetime, so a plain file-static is safe.
+std::function<double()> g_memProbe;
+
+// Read /proc/self/statm to get RSS in MB.  Cheap (~20 µs).  Returns -1 when
+// procfs is absent — which is the case on iOS (no /proc), so this is the Android
+// path; iOS supplies g_memProbe instead.
+double rss_mb_proc() {
     FILE* f = std::fopen("/proc/self/statm", "r");
     if (f == nullptr) return -1.0;
     long size_pages = 0, resident_pages = 0;
@@ -85,6 +100,97 @@ double rss_mb() {
     return (double) resident_pages * (double) page_bytes / (1024.0 * 1024.0);
 }
 
+// Effective resident-memory reader (MB).  Prefers the installed probe (iOS
+// phys_footprint), else /proc (Android).  -1 when neither is available.  Used at
+// pipeline phase boundaries + by the OOM guards — making the guards work on iOS,
+// where they previously got -1 (the runtime-pressure router was dead).
+double rss_mb() {
+    if (g_memProbe) {
+        const double v = g_memProbe();
+        if (v >= 0.0) return v;
+    }
+    return rss_mb_proc();
+}
+
+// Which source rss_mb() is currently resolving to — for the per-stitch record.
+const char* mem_source_label() {
+    if (g_memProbe && g_memProbe() >= 0.0) return "phys_footprint";
+    if (rss_mb_proc() >= 0.0) return "rss";
+    return "";
+}
+
+// RAII: install/uninstall the resident-memory probe for one stitch.
+struct MemProbeScope {
+    explicit MemProbeScope(std::function<double()> probe) { g_memProbe = std::move(probe); }
+    ~MemProbeScope() { g_memProbe = nullptr; }
+    MemProbeScope(const MemProbeScope&) = delete;
+    MemProbeScope& operator=(const MemProbeScope&) = delete;
+};
+
+// DRY [memstat] phase log — gated, and (unlike the old inline form) skips the
+// rss_mb() read entirely when profiling is off, so release pays nothing.
+void log_memstat(const LogFn& logFn, bool enabled, const char* phase) {
+    if (!enabled || !logFn) return;
+    char buf[80];
+    std::snprintf(buf, sizeof(buf), "phase=%s rss=%.1f MB", phase, rss_mb());
+    logFn(0, "[memstat]", buf);
+}
+
+// Background peak-memory sampler.  Wakes every ~50 ms during a stitch and tracks
+// the max resident memory into `peak` — the ONLY way to catch the transient
+// warp-all + GraphCut + MultiBand spike, which the phase-boundary reads (taken
+// after the blender frees its pyramids) systematically miss.  RAII: the thread
+// starts in the ctor (when active) and is joined in stop()/dtor.  It is a pure
+// memory reader, not OpenCV work, so cv::setNumThreads(1) does not constrain it.
+class PeakSampler {
+public:
+    PeakSampler(bool active, std::atomic<double>& peak) : peak_(peak), active_(active) {
+        if (!active_) return;
+        thread_ = std::thread([this]() {
+            while (!stop_.load(std::memory_order_relaxed)) {
+                const double v = rss_mb();
+                double cur = peak_.load(std::memory_order_relaxed);
+                while (v > cur &&
+                       !peak_.compare_exchange_weak(cur, v, std::memory_order_relaxed)) {}
+                // Sleep in 10 ms slices so stop() is responsive (~50 ms cadence).
+                for (int i = 0; i < 5 && !stop_.load(std::memory_order_relaxed); ++i)
+                    std::this_thread::sleep_for(std::chrono::milliseconds(10));
+            }
+        });
+    }
+    void stop() {
+        if (!active_) return;
+        stop_.store(true, std::memory_order_relaxed);
+        if (thread_.joinable()) thread_.join();
+        active_ = false;
+    }
+    ~PeakSampler() { stop(); }
+    PeakSampler(const PeakSampler&) = delete;
+    PeakSampler& operator=(const PeakSampler&) = delete;
+private:
+    std::atomic<double>& peak_;
+    std::atomic<bool>    stop_{false};
+    std::thread          thread_;
+    bool                 active_;
+};
+
+// Total physical RAM in MB, read natively.  The Android JNI bridge sets no
+// availableRamMB, so without this a 6 GB device is mis-treated as the 4 GB
+// fallback (and the step-7.7 canvas budget + pre-stitch abort under-size).
+// _SC_PHYS_PAGES is TOTAL and stable across runs (unlike _SC_AVPHYS_PAGES,
+// which is free RAM and varies).  Returns -1.0 off Linux/Android (e.g. the
+// macOS cpp-test host); the caller resolves the sentinel.
+double device_total_ram_mb() {
+#if defined(__linux__)
+    const long pages = sysconf(_SC_PHYS_PAGES);
+    const long page_bytes = sysconf(_SC_PAGESIZE);
+    if (pages <= 0 || page_bytes <= 0) return -1.0;
+    return (double) pages * (double) page_bytes / (1024.0 * 1024.0);
+#else
+    return -1.0;
+#endif
+}
+
 double mat_mb(const cv::Mat& m) {
     if (m.empty()) return 0.0;
     return (double)(m.total() * m.elemSize()) / (1024.0 * 1024.0);
@@ -229,6 +335,100 @@ cv::Rect maxInscribedRectFromMask(const cv::Mat& mask) {
     return bestRect;
 }
 
+// Issue 3 — post-stitch output validator.  The confidence filter drops
+// frames that don't REGISTER, but nothing validated the final OUTPUT: a
+// frame that survived confidence yet landed geometrically disconnected
+// shows up as a separate blob in the coverage mask (the "disjointed image
+// frames in the output" users reported).  Run connected-components on the
+// coverage mask; if a meaningful fraction of the covered area lies OUTSIDE
+// the largest blob, reject the stitch as LowQualityStitch so the host can
+// prompt a retry rather than ship a broken panorama.
+//
+// Conservative by design: a coherent panorama is ONE connected blob, so a
+// good capture never trips; the threshold lives in the pure, unit-tested
+// retailens::stitchOutputIsDisjoint.  A small morphological close first
+// bridges sub-pixel seam gaps so a single panorama isn't mis-split, while
+// being far too small to merge a genuinely-detached floating frame.
+//
+// Fails OPEN: an empty/unreadable mask returns Ok (never block a capture on
+// a mask we couldn't analyse).
+StitchErrorCode validateStitchOutput(const cv::Mat& panorama,
+                                     const cv::Mat& coverage,
+                                     int numFrames,
+                                     const LogFn& logFn,
+                                     std::string& outMessage) {
+    if (panorama.empty()) return StitchErrorCode::Ok;  // handled elsewhere
+    // Build a binary coverage mask (same posture as choose_crop_rect).
+    cv::Mat mask;
+    const bool haveCoverage =
+        (!coverage.empty() && coverage.size() == panorama.size());
+    if (haveCoverage) {
+        cv::Mat cov1 = coverage;
+        if (coverage.channels() != 1) {
+            cv::cvtColor(coverage, cov1, cv::COLOR_BGR2GRAY);
+        }
+        cv::threshold(cov1, mask, 0, 255, cv::THRESH_BINARY);
+    } else {
+        cv::Mat gray;
+        cv::cvtColor(panorama, gray, cv::COLOR_BGR2GRAY);
+        cv::threshold(gray, mask, 0, 255, cv::THRESH_BINARY);
+    }
+    if (mask.empty() || mask.type() != CV_8UC1) return StitchErrorCode::Ok;
+    // Bridge thin seam gaps so a coherent pano isn't mis-split; the 5 px
+    // kernel is far smaller than the gap a detached frame leaves, so
+    // genuinely-separate blobs are NOT merged.
+    cv::Mat closed;
+    cv::morphologyEx(
+        mask, closed, cv::MORPH_CLOSE,
+        cv::getStructuringElement(cv::MORPH_ELLIPSE, cv::Size(5, 5)));
+    cv::Mat labels, stats, centroids;
+    const int n = cv::connectedComponentsWithStats(
+        closed, labels, stats, centroids, 8, CV_32S);
+    double totalArea = 0.0, largestArea = 0.0;
+    for (int i = 1; i < n; i++) {  // skip background label 0
+        const double a = stats.at<int>(i, cv::CC_STAT_AREA);
+        totalArea += a;
+        if (a > largestArea) largestArea = a;
+    }
+    const double fragmentFraction =
+        (totalArea > 0.0) ? (1.0 - largestArea / totalArea) : 0.0;
+    log_info(logFn, "[stitch-bc]",
+             "step11d: validate output components=%d largest=%.0f total=%.0f "
+             "fragment=%.3f frames=%d",
+             n - 1, largestArea, totalArea, fragmentFraction, numFrames);
+    if (retailens::stitchOutputIsDisjoint(largestArea, totalArea, numFrames)) {
+        char buf[176];
+        std::snprintf(buf, sizeof(buf),
+                      "stitch validation failed: disjoint output (%d "
+                      "components, %.0f%% of coverage outside the main frame)",
+                      n - 1, fragmentFraction * 100.0);
+        outMessage = buf;
+        return StitchErrorCode::LowQualityStitch;
+    }
+    // Utilization guard — the "black canvas".  A coherent blob marooned in a
+    // mostly-empty canvas passes the disjoint check above (one blob), so guard
+    // the coverage-to-canvas ratio too (mask is the full panorama size).
+    {
+        const double canvasArea = (double)mask.cols * (double)mask.rows;
+        if (retailens::stitchOutputUnderutilized(totalArea, canvasArea,
+                                                 numFrames)) {
+            const double util = canvasArea > 0.0 ? totalArea / canvasArea : 0.0;
+            log_info(logFn, "[stitch-bc]",
+                     "step11d: REJECT degenerate canvas — utilization=%.3f%% "
+                     "(content %.0f / canvas %dx%d)",
+                     util * 100.0, totalArea, mask.cols, mask.rows);
+            char buf[200];
+            std::snprintf(buf, sizeof(buf),
+                          "stitch validation failed: degenerate canvas "
+                          "(content fills %.2f%% of the %dx%d panorama)",
+                          util * 100.0, mask.cols, mask.rows);
+            outMessage = buf;
+            return StitchErrorCode::LowQualityStitch;
+        }
+    }
+    return StitchErrorCode::Ok;
+}
+
 // Pick the crop rectangle. Prefers the TRUE coverage mask from
 // cv::Stitcher::resultMask() (0xFF where a frame painted, 0 where
 // unfilled) so dark content is kept and only the never-covered wedges
@@ -297,77 +497,224 @@ static StitchResult stitchFramePathsImpl_(
     LogFn                           logFn);
 
 
+// ─────────────────────────────────────────────────────────────────────
+// Degenerate-warp guard helpers (shared by every throw site in the manual
+// pipeline's warp/compose stage).  Centralising them keeps the error
+// MESSAGE consistent across the four sites — the JS host classifies a
+// stitch failure by substring (see src/camera/classifyStitchError.ts /
+// cameraErrorMessages.ts → STITCH_CAMERA_PARAMS_FAIL "Please pan more
+// slowly"), so every degenerate-warp throw MUST carry "degenerate camera
+// params" + the stitchMode.  Both predicates live in cpp/warp_guard.hpp
+// (OpenCV-free + unit-tested); these builders add only the message + the
+// cv::Exception envelope.
+// ─────────────────────────────────────────────────────────────────────
+
+// Per-frame divergence: ONE warped frame's ROI exceeds kMaxWarpPixels
+// (broken estimator/BA on degenerate input — low feature count, near-
+// duplicate frames, motion-blurred rapid pan).  stitchMode tells you which
+// pipeline diverged: PANORAMA usually fails on translation-heavy input
+// (homography + BA-Ray assume pure rotation); SCANS on low-texture / low-
+// overlap input (affine needs enough matches).
+static cv::Exception degenerateFrameException(
+    int width, int height, StitchMode mode, size_t frameIdx) {
+  const char* modeStr =
+      (mode == StitchMode::Scans) ? "scans" : "panorama";
+  return cv::Exception(
+      cv::Error::StsOutOfRange,
+      std::string("warpRoi too large (") + std::to_string(width) + "x"
+          + std::to_string(height)
+          + ") — estimator produced degenerate camera params on this frame "
+          + "(stitchMode=" + modeStr + ", frameIdx="
+          + std::to_string(frameIdx) + ")",
+      "stitchFramePathsManual", __FILE__, __LINE__);
+}
+
+// Cumulative-canvas divergence: every per-frame ROI passed, but the UNION
+// bounding box that blender->prepare() allocates exceeds kMaxCanvasPixels
+// (a degenerate corner OFFSET blows the union to gigapixels while each
+// frame's own extent stays small).  This is the real crash-B net.
+static cv::Exception degenerateCanvasException(
+    int64_t width, int64_t height, StitchMode mode, size_t frames) {
+  const char* modeStr =
+      (mode == StitchMode::Scans) ? "scans" : "panorama";
+  return cv::Exception(
+      cv::Error::StsOutOfRange,
+      std::string("panorama canvas too large (") + std::to_string(width)
+          + "x" + std::to_string(height)
+          + ") — estimator produced degenerate camera params across the "
+          + "frame set (stitchMode=" + modeStr + ", frames="
+          + std::to_string(frames) + ")",
+      "stitchFramePathsManual", __FILE__, __LINE__);
+}
+
+// Bounding box over every positioned warp rect (corner + size) — exactly
+// what cv::detail::Blender::prepare() allocates as its CV_16SC3 canvas.
+// Computed in int64 so a degenerate corner offset (which can exceed the
+// int32 range on its own) doesn't overflow before canvasExceedsGuard()
+// gets to inspect it.  Yields 0×0 for an empty frame set.
+static void blendCanvasUnion(const std::vector<cv::Point>& corners,
+                             const std::vector<cv::Size>&  sizes,
+                             int64_t& unionW, int64_t& unionH) {
+  if (corners.empty()) { unionW = 0; unionH = 0; return; }
+  // Seed from frame 0 (avoids any sentinel / <climits> dependency).
+  int64_t minX = corners[0].x;
+  int64_t minY = corners[0].y;
+  int64_t maxX = static_cast<int64_t>(corners[0].x) + sizes[0].width;
+  int64_t maxY = static_cast<int64_t>(corners[0].y) + sizes[0].height;
+  for (size_t i = 1; i < corners.size(); i++) {
+    const int64_t x0 = corners[i].x;
+    const int64_t y0 = corners[i].y;
+    const int64_t x1 = x0 + sizes[i].width;
+    const int64_t y1 = y0 + sizes[i].height;
+    if (x0 < minX) minX = x0;
+    if (y0 < minY) minY = y0;
+    if (x1 > maxX) maxX = x1;
+    if (y1 > maxY) maxY = y1;
+  }
+  unionW = maxX - minX;
+  unionH = maxY - minY;
+}
+
+
 StitchResult stitchFramePaths(
     const std::vector<std::string>& framePaths,
     const std::string&              outputPath,
     const StitchConfig&             config,
     LogFn                           logFn)
 {
-    // 2026-05-22 (audit follow-up) — mode-fallback retry.  When the
-    // configured stitchMode produces degenerate camera params (the
-    // "warpRoi too large" crash users hit on translation-heavy
-    // captures stitched as PANORAMA, or low-texture inputs stitched
-    // as SCANS), automatically retry once with the OPPOSITE mode
-    // before giving up.  Symmetric: PANORAMA-then-SCANS or
-    // SCANS-then-PANORAMA depending on configured mode.
+    // ── v0.16.1 — native-heap leak fix (one-time) — ANDROID ONLY ────────
+    // The ~7-9 MB/stitch LIVE native-heap creep is OpenCV core's OWN pooled
+    // scratch — TBB per-worker TLS — re-primed as the calling thread migrates
+    // across the Kotlin Dispatchers.Default pool.  It is NOT app memory (every
+    // cv::Mat below is RAII / explicitly .release()'d) and NOT reclaimable by
+    // mallopt(M_PURGE) (those pools aren't serviced by bionic malloc).
+    // setNumThreads(1) removes the TBB worker pool so no per-worker scratch can
+    // accumulate.  Stitches are serialized and the keyframes are small, so the
+    // single-threaded cost is minor.  C++11 static-init is thread-safe; runs once.
     //
-    // Why this is safe to enable unconditionally:
-    //   - The retry only fires on a failed attempt (no perf hit on
-    //     happy paths).
-    //   - Both modes share the load-images and write-output stages,
-    //     so the per-frame I/O cost isn't duplicated — only the
-    //     estimator/BA/warp middle is re-run.
-    //   - Result reflects whichever mode succeeded (returned via
-    //     StitchResult.stitchModeUsed, populated below).
-    auto runOnce = [&](StitchMode modeOverride) -> StitchResult {
+    // 2026-06-16 (audit) — ANDROID-GATED.  The prebuilt iOS opencv2.xcframework
+    // uses the GCD parallel backend (NOT TBB — getBuildInformation reads
+    // "Parallel framework: GCD"), so there is no TBB pool to remove; pinning to
+    // 1 thread there is pure cost (serialized ORB/matcher/warp/blend + a
+    // single-core per-frame KeyframeGate) for ZERO memory benefit.  Recovering
+    // iOS's multi-core path.  setUseIPP(false) was dropped entirely — IPP is
+    // x86-only, a no-op on arm64 (both Android NDK and iOS).
+#if defined(__ANDROID__)
+    static const bool s_cvTuned = []() {
+        cv::setNumThreads(1);
+        return true;
+    }();
+    (void)s_cvTuned;
+#endif
+
+    // ── 2026-06-16 — per-stitch memory profiling (DEV; gated) ───────────
+    // Install the resident-memory probe (iOS phys_footprint; null on Android →
+    // /proc) for the whole stitch — including the retry + the high-level/manual
+    // impls below — so the OOM guards, phase logs, peak sampler + record all read
+    // the right source.  The sampler runs across both attempts (peak = the worse
+    // of the two, which is the conservative OOM number).  `finish()` stops the
+    // sampler + stamps the record onto whichever result we return.
+    const bool memProfiling = kMemProfilingCompiled && config.enableMemoryProfiling;
+    MemProbeScope memProbe(config.memProbeFn);
+    const std::string memSource =
+        memProfiling ? std::string(mem_source_label()) : std::string();
+    const double memBefore = memProfiling ? rss_mb() : -1.0;
+    std::atomic<double> peakMB{ memBefore };
+    PeakSampler sampler(memProfiling, peakMB);
+    auto finish = [&](StitchResult r) -> StitchResult {
+        sampler.stop();
+        if (memProfiling) {
+            const double memAfter = rss_mb();
+            r.memBeforeMB = memBefore;
+            r.memAfterMB  = memAfter;
+            r.memPeakMB   = std::max(peakMB.load(), std::max(memBefore, memAfter));
+            r.memSource   = memSource;
+            // memFloorMB stays -1; the platform bridge fills it after its
+            // post-stitch reclaim (Android mallopt(M_PURGE) / iOS settle read).
+            char mbuf[96];
+            std::snprintf(mbuf, sizeof(mbuf),
+                          "memBefore=%.1f;memPeak=%.1f;memAfter=%.1f;memSrc=%s",
+                          r.memBeforeMB, r.memPeakMB, r.memAfterMB, memSource.c_str());
+            if (!r.debugSummary.empty()) r.debugSummary += ";";
+            r.debugSummary += mbuf;
+        }
+        return r;
+    };
+
+    // 2026-06-16 — TWO-BRANCH fallback retry (only fires on a retryable failure;
+    // no happy-path cost; each attempt is a full independent run — memory does
+    // NOT stack, RAII frees between attempts):
+    //
+    //   HIGH-LEVEL caller (Android default, useManualPipeline=false): retry once
+    //     with the SPHERICAL warper — bounds the canvas on both axes (lower peak
+    //     ~16% measured + rescues a marooned plane/cylindrical warp).
+    //   MANUAL caller (iOS pre-Phase-2, useManualPipeline=true): the OLD
+    //     PANORAMA↔SCANS mode-fallback is PRESERVED so iOS does not regress until
+    //     its bridge is flipped to high-level (review #3/#4).  The dispatcher
+    //     guard routes SCANS→high-level affine; PANORAMA→manual (+ its own
+    //     plane→spherical self-rescue).
+    //
+    // PreStitchMemoryAbort is excluded from worthRetrying (a headroom abort is
+    // independent of warper/mode — retrying won't help).
+    auto runOnce = [&](StitchMode modeOverride,
+                       const std::string& warperOverride) -> StitchResult {
         StitchConfig cfg = config;
         cfg.stitchMode = modeOverride;
+        if (!warperOverride.empty()) cfg.warperType = warperOverride;
         return stitchFramePathsImpl_(framePaths, outputPath, cfg, logFn);
     };
-    StitchResult firstAttempt = runOnce(config.stitchMode);
+    StitchResult firstAttempt = runOnce(config.stitchMode, std::string());
+    firstAttempt.stitchModeUsed = config.stitchMode;
     if (firstAttempt.errorCode == StitchErrorCode::Ok) {
-        firstAttempt.stitchModeUsed = config.stitchMode;
-        return firstAttempt;
+        return finish(firstAttempt);
     }
-    // First attempt failed.  Try the opposite mode unless the error
-    // is something the opposite mode wouldn't fix (e.g. invalid
-    // argument count, file-read failure, OOM).
-    bool worthRetrying =
+    const bool worthRetrying =
         firstAttempt.errorCode == StitchErrorCode::UnknownCvException
         || firstAttempt.errorCode == StitchErrorCode::HomographyEstimationFailed
         || firstAttempt.errorCode == StitchErrorCode::CameraParamsAdjustFailed
         || firstAttempt.errorCode == StitchErrorCode::WarpFailed
-        || firstAttempt.errorCode == StitchErrorCode::EmptyPanorama;
+        || firstAttempt.errorCode == StitchErrorCode::EmptyPanorama
+        || firstAttempt.errorCode == StitchErrorCode::LowQualityStitch;
     if (!worthRetrying) {
-        firstAttempt.stitchModeUsed = config.stitchMode;
-        return firstAttempt;
+        return finish(firstAttempt);
     }
-    StitchMode fallbackMode =
-        (config.stitchMode == StitchMode::Panorama) ? StitchMode::Scans
-                                                    : StitchMode::Panorama;
-    log_info(logFn, "[stitch-fallback]",
-             "primary mode (%s) failed with code=%d msg=%s — retrying with %s",
-             config.stitchMode == StitchMode::Scans ? "scans" : "panorama",
-             static_cast<int>(firstAttempt.errorCode),
-             firstAttempt.errorMessage.c_str(),
-             fallbackMode == StitchMode::Scans ? "scans" : "panorama");
-    StitchResult secondAttempt = runOnce(fallbackMode);
-    if (secondAttempt.errorCode == StitchErrorCode::Ok) {
-        secondAttempt.stitchModeUsed = fallbackMode;
+    // HIGH-LEVEL: spherical warper rescue.
+    if (!config.useManualPipeline
+        && config.stitchMode == StitchMode::Panorama
+        && config.warperType != "spherical") {
+        log_info(logFn, "[stitch-fallback]",
+                 "high-level warper (%s) failed code=%d (%s) — retrying spherical",
+                 config.warperType.c_str(),
+                 static_cast<int>(firstAttempt.errorCode),
+                 firstAttempt.errorMessage.c_str());
+        StitchResult sph = runOnce(config.stitchMode, "spherical");
+        sph.stitchModeUsed = config.stitchMode;
+        if (sph.errorCode == StitchErrorCode::Ok) {
+            log_info(logFn, "[stitch-fallback]", "spherical rescue succeeded");
+            return finish(sph);
+        }
+        log_info(logFn, "[stitch-fallback]",
+                 "spherical rescue also failed code=%d — returning primary error",
+                 static_cast<int>(sph.errorCode));
+        return finish(firstAttempt);
+    }
+    // MANUAL: preserved opposite-mode fallback (iOS no-regression).
+    if (config.useManualPipeline) {
+        const StitchMode fallbackMode =
+            (config.stitchMode == StitchMode::Panorama) ? StitchMode::Scans
+                                                        : StitchMode::Panorama;
         log_info(logFn, "[stitch-fallback]",
-                 "fallback mode (%s) succeeded",
+                 "manual primary mode (%s) failed code=%d — retrying %s",
+                 config.stitchMode == StitchMode::Scans ? "scans" : "panorama",
+                 static_cast<int>(firstAttempt.errorCode),
                  fallbackMode == StitchMode::Scans ? "scans" : "panorama");
-        return secondAttempt;
+        StitchResult secondAttempt = runOnce(fallbackMode, std::string());
+        if (secondAttempt.errorCode == StitchErrorCode::Ok) {
+            secondAttempt.stitchModeUsed = fallbackMode;
+            return finish(secondAttempt);
+        }
     }
-    // Both attempts failed.  Return the FIRST attempt's error (it's
-    // what the operator's chosen mode produced — more useful for
-    // diagnosis than the fallback's failure).
-    log_info(logFn, "[stitch-fallback]",
-             "fallback mode (%s) also failed with code=%d — returning primary error",
-             fallbackMode == StitchMode::Scans ? "scans" : "panorama",
-             static_cast<int>(secondAttempt.errorCode));
-    firstAttempt.stitchModeUsed = config.stitchMode;
-    return firstAttempt;
+    return finish(firstAttempt);
 }
 
 // 2026-05-22 (audit follow-up) — renamed inner entry point so the
@@ -384,14 +731,53 @@ static StitchResult stitchFramePathsImpl_(
     // useManualPipeline for the tradeoffs.  Routing here keeps the
     // call-site signature identical so existing bridges (iOS Obj-C++,
     // Android JNI) don't need to know which path runs internally.
-    if (config.useManualPipeline) {
-        return stitchFramePathsManual(framePaths, outputPath, config, logFn);
+    //
+    // 2026-06-16 — SCANS always uses the high-level pipeline: the manual path is
+    // homography-only (no affine matcher/estimator/warper), so SCANS+manual
+    // would silently run a homography stitch.  The old mode-fallback enforced
+    // this in runOnce; now that runOnce is warper-only, enforce it here so a
+    // not-yet-migrated caller passing stitchMode=scans + useManualPipeline=true
+    // (e.g. iOS pre-Phase-2) still gets the correct affine SCANS path.
+    if (config.useManualPipeline && config.stitchMode != StitchMode::Scans) {
+        StitchResult r =
+            stitchFramePathsManual(framePaths, outputPath, config, logFn);
+        // 2026-06-15 — AUTO SPHERICAL FALLBACK.  The manual pipeline defaults to
+        // the PLANE warper (flat, natural for narrow / 1x pans).  Plane is
+        // unbounded, so a wide / off-axis pan can maroon content in a corner;
+        // validateStitchOutput rejects that as LowQualityStitch (the utilization
+        // / disjoint guard) BEFORE writing any file.  Rather than fail, retry
+        // ONCE with the SPHERICAL warper, which bounds both axes — flat when
+        // plane works, bounded only when it doesn't.  Skipped when the caller
+        // already asked for spherical, or the failure wasn't a quality rejection
+        // (OOM abort / read error won't be fixed by a different warper).
+        if (!r.success
+            && r.errorCode == StitchErrorCode::LowQualityStitch
+            && config.warperType != "spherical") {
+            log_info(logFn, "[stitch-bc]",
+                     "manual '%s' marooned (LowQualityStitch) — retrying once "
+                     "with spherical (bounded both axes)",
+                     config.warperType.c_str());
+            StitchConfig sph = config;
+            sph.warperType = "spherical";
+            return stitchFramePathsManual(framePaths, outputPath, sph, logFn);
+        }
+        return r;
     }
 
     const auto t0 = std::chrono::steady_clock::now();
     StitchResult result;
     result.framesRequested = static_cast<int32_t>(framePaths.size());
 
+    // 2026-06-16 (review #1) — outer crash-catch ladder over the WHOLE high-level
+    // body.  Now that high-level is the default pipeline, an OOM-class throw must
+    // NOT escape: cv::Stitcher PANORAMA internals (MultiBand pyramids, GraphCut,
+    // STL vectors) can throw std::bad_alloc (NOT a cv::Exception, so the narrow
+    // inner catch(cv::Exception&) misses it), and the post-stitch clone/crop/bake
+    // ops can throw cv::Exception(StsNoMem) OUTSIDE the inner catches — either
+    // would cross the JNI C-ABI → std::terminate/SIGABRT.  Mirror the manual
+    // path's ladder so any throw becomes a clean StitchResult error (which also
+    // makes the spherical rescue eligible).  The JNI adds a backstop too.
+    try {
     if (framePaths.size() < 2) {
         result.errorCode = StitchErrorCode::InvalidArgument;
         result.errorMessage = "Need at least 2 frames to stitch (got " +
@@ -417,7 +803,9 @@ static StitchResult stitchFramePathsImpl_(
              config.captureOrientation.c_str(),
              config.jpegQuality,
              config.useInscribedRectCrop ? 1 : 0);
-    log_info(logFn, "[memstat]", "phase=entry rss=%.1f MB", rss_mb());
+    // Gate the [memstat] phase logs (compile flag + runtime settings.debug).
+    const bool memstat = kMemProfilingCompiled && config.enableMemoryProfiling;
+    log_memstat(logFn, memstat, "entry");
 
     // ── 1.  Load input frames ───────────────────────────────────────
     std::vector<cv::Mat> images;
@@ -440,7 +828,7 @@ static StitchResult stitchFramePathsImpl_(
     }
     log_info(logFn, "[dimstat]", "loaded %zu frames total_input_data=%.2f MB",
              images.size(), totalInputMB);
-    log_info(logFn, "[memstat]", "phase=after_imread rss=%.1f MB", rss_mb());
+    log_memstat(logFn, memstat, "after_imread");
 
     // ── 2.  Configure cv::Stitcher ──────────────────────────────────
     const cv::Stitcher::Mode cvMode = (config.stitchMode == StitchMode::Scans)
@@ -482,7 +870,17 @@ static StitchResult stitchFramePathsImpl_(
     if (config.seamEstimationResolMP > 0.0) {
         stitcher->setSeamEstimationResol(config.seamEstimationResolMP);
     }
-    const double kHighLevelComposeFallbackMP = 1.0;
+    // 2026-06-16 (high-level safety) — RAM-aware compositing resolution.
+    // cv::Stitcher composes the whole canvas at once (no STREAM mode), so the
+    // per-frame compose MP directly sizes the peak.  1.0 MP is fine on 6 GB+
+    // (measured peak ~0.7-0.9 GB on the A35); on lower-RAM devices clamp to
+    // 0.6 MP so the unguarded high-level path can't out-grow the per-process
+    // budget.  An explicit caller override (compositingResolMP > 0) still wins.
+    double totalRamMB = (config.availableRamMB > 0.0)
+        ? config.availableRamMB : device_total_ram_mb();
+    if (totalRamMB <= 0.0) totalRamMB = 4.0 * 1024.0;  // conservative fallback
+    const double kHighLevelComposeFallbackMP =
+        (totalRamMB >= 5.0 * 1024.0) ? 1.0 : 0.6;
     const double composeMP = (config.compositingResolMP > 0.0)
         ? config.compositingResolMP : kHighLevelComposeFallbackMP;
     stitcher->setCompositingResol(composeMP);
@@ -503,7 +901,28 @@ static StitchResult stitchFramePathsImpl_(
     // with progressively lower thresholds [1.0 → 0.5 → 0.3] until
     // every frame is retained or we hit the floor.  SCANS skips the
     // higher thresholds (its default is already 0.3).
-    log_info(logFn, "[memstat]", "phase=before_stitch rss=%.1f MB", rss_mb());
+    // 2026-06-16 (high-level safety) — pre-stitch headroom abort.  The
+    // high-level path has no STREAM fallback or canvas downscale, so if the
+    // process is ALREADY so close to its per-process kill ceiling that even a
+    // minimal stitch won't fit on top, abort cleanly (surfaced via onError)
+    // rather than letting cv::Stitcher march into an lmkd/jetsam kill.  Reuses
+    // the manual path's headroom guard; rss_mb() is memProbeFn-backed so this
+    // works on iOS too (where /proc is absent).  Skipped when rss is unknown.
+    {
+        const double startRssMB = rss_mb();
+        if (startRssMB >= 0.0
+            && retailens::stitchExceedsMinimalHeadroom(startRssMB, totalRamMB)) {
+            result.errorCode = StitchErrorCode::PreStitchMemoryAbort;
+            result.errorMessage =
+                "Pre-stitch abort: insufficient memory headroom for high-level "
+                "stitch (rss=" + std::to_string(static_cast<int>(startRssMB)) +
+                "MB, budget=" + std::to_string(static_cast<int>(
+                    retailens::perProcessMemoryBudgetMB(totalRamMB))) + "MB)";
+            log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+            return result;
+        }
+    }
+    log_memstat(logFn, memstat, "before_stitch");
     const double kRetryThresholds[] = {1.0, 0.5, 0.3};
     const int kNumAttempts = sizeof(kRetryThresholds) / sizeof(double);
     cv::Mat panorama;
@@ -521,10 +940,14 @@ static StitchResult stitchFramePathsImpl_(
                  "attempt %d/%d panoConfidenceThresh=%.2f",
                  finalAttempt, kNumAttempts, thresh);
         try {
-            status = stitcher->stitch(images, panorama);
+            // 2026-06-16 (review #2) — TWO-PHASE: estimateTransform (registration
+            // + BA + leaveBiggestComponent at this threshold) here; composePanorama
+            // runs ONCE after the canvas-union guard below.  This is the ONLY way
+            // to inspect the estimated canvas BEFORE the warp/blend allocates it.
+            status = stitcher->estimateTransform(images);
         } catch (const cv::Exception& e) {
             result.errorCode = StitchErrorCode::UnknownCvException;
-            result.errorMessage = std::string("Stitcher::stitch threw on attempt ") +
+            result.errorMessage = std::string("Stitcher::estimateTransform threw on attempt ") +
                 std::to_string(finalAttempt) + ": " + e.what();
             log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
             return result;
@@ -555,19 +978,156 @@ static StitchResult stitchFramePathsImpl_(
     }
     if (status != cv::Stitcher::OK) {
         result.errorCode = statusToErrorCode(status);
-        result.errorMessage = "Stitcher::stitch failed at all " +
+        result.errorMessage = "Stitcher::estimateTransform failed at all " +
             std::to_string(finalAttempt) + " thresholds, last status code " +
             std::to_string(static_cast<int>(status));
         log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
         return result;
     }
+
+    // 2026-06-16 (review #2) — degenerate-canvas guard BEFORE composePanorama.
+    // estimateTransform succeeded; composePanorama will now warp+blend a canvas
+    // whose size is set by the estimated focals/rotations.  A divergent BA
+    // produces absurd focals → a gigapixel canvas → an lmkd/jetsam kill MID
+    // allocation that NO try/catch can intercept.  Project the warp-canvas union
+    // from cameras() + the configured warper at the registration/WORK scale
+    // (conservative: a valid pano is well under 1 MP here, so a union over
+    // kMaxCanvasPixels (50 MP) is unambiguously degenerate) and abort cleanly
+    // before the allocation.  Valid wide pans are bounded separately by the
+    // RAM-aware compositingResol above, so this only fires on a divergent
+    // estimate — and the abort routes to the outer wrapper's spherical rescue.
+    try {
+        const std::vector<cv::detail::CameraParams> cams = stitcher->cameras();
+        if (!cams.empty()) {
+            std::vector<double> focals;
+            focals.reserve(cams.size());
+            for (const auto& c : cams) focals.push_back(c.focal);
+            std::sort(focals.begin(), focals.end());
+            const double warpScale = focals[focals.size() / 2];  // median focal
+            cv::Ptr<cv::WarperCreator> wc = make_warper(config.warperType);
+            if (wc) {
+                cv::Ptr<cv::detail::RotationWarper> w =
+                    wc->create(static_cast<float>(warpScale));
+                const double workScale = stitcher->workScale();
+                int64_t minX = 0, minY = 0, maxX = 0, maxY = 0;
+                bool seeded = false;
+                for (size_t i = 0; i < cams.size() && i < images.size(); ++i) {
+                    cv::Mat K;
+                    cams[i].K().convertTo(K, CV_32F);
+                    const cv::Size workSz(
+                        std::max(1, (int)std::lround(images[i].cols * workScale)),
+                        std::max(1, (int)std::lround(images[i].rows * workScale)));
+                    const cv::Rect roi = w->warpRoi(workSz, K, cams[i].R);
+                    if (!seeded) {
+                        minX = roi.x; minY = roi.y;
+                        maxX = (int64_t)roi.x + roi.width;
+                        maxY = (int64_t)roi.y + roi.height;
+                        seeded = true;
+                    } else {
+                        minX = std::min<int64_t>(minX, roi.x);
+                        minY = std::min<int64_t>(minY, roi.y);
+                        maxX = std::max<int64_t>(maxX, (int64_t)roi.x + roi.width);
+                        maxY = std::max<int64_t>(maxY, (int64_t)roi.y + roi.height);
+                    }
+                }
+                if (seeded && canvasExceedsGuard(maxX - minX, maxY - minY)) {
+                    result.errorCode = StitchErrorCode::WarpFailed;
+                    result.errorMessage =
+                        "Degenerate high-level estimate: warp-canvas union " +
+                        std::to_string(maxX - minX) + "x" +
+                        std::to_string(maxY - minY) +
+                        " px (work scale) exceeds guard — aborting before "
+                        "composePanorama to avoid an OOM kill";
+                    log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+                    return result;  // → outer wrapper's spherical rescue (bounded)
+                }
+
+                // 2026-06-16 (review #2 + on-device data) — VALID-but-large canvas
+                // budget.  A wide PLANE pan peaked ~2520 MB on the 6 GB A35 (above
+                // its red line; OOM on 4 GB) — not degenerate (passed the guard
+                // above), just unbounded-plane-large.  Project the COMPOSE-scale
+                // canvas from the work-scale union (same geometry; resolution
+                // ratio composeScale/workScale) and, if it exceeds the RAM canvas
+                // budget, bound it BEFORE composePanorama: downscale
+                // compositingResol when a modest (≤2×) shrink suffices, else route
+                // to spherical (its geometry bounds the canvas at FULL resolution
+                // — data: ~5× lower peak).  This is the manual path's
+                // composeCanvasBudgetMP downscale, ported to high-level.
+                if (seeded && workScale > 0.0 && !images.empty()
+                    && images[0].total() > 0) {
+                    const double fullArea =
+                        static_cast<double>(images[0].cols) * images[0].rows;
+                    const double composeScale =
+                        std::min(1.0, std::sqrt(composeMP * 1e6 / fullArea));
+                    const double ratioCS = composeScale / workScale;
+                    const double workCanvasMP =
+                        static_cast<double>(maxX - minX) * (maxY - minY) / 1e6;
+                    const double composeCanvasMP = workCanvasMP * ratioCS * ratioCS;
+                    const double canvasBudgetMP =
+                        retailens::composeCanvasBudgetMP(totalRamMB);
+                    if (composeCanvasMP > canvasBudgetMP) {
+                        const double over = composeCanvasMP / canvasBudgetMP;
+                        if (over <= 2.0 || config.warperType == "spherical") {
+                            const double targetMP = composeMP / over;
+                            stitcher->setCompositingResol(targetMP);
+                            log_info(logFn, "[stitch]",
+                                     "canvas %.1f MP > budget %.1f MP (warp=%s) — "
+                                     "downscaled compositingResol %.2f→%.2f MP",
+                                     composeCanvasMP, canvasBudgetMP,
+                                     config.warperType.c_str(), composeMP, targetMP);
+                        } else {
+                            // >2× over on plane/cylindrical → spherical bounds it
+                            // geometrically (full res) far better than a big shrink.
+                            result.errorCode = StitchErrorCode::WarpFailed;
+                            result.errorMessage =
+                                "high-level canvas " +
+                                std::to_string(static_cast<int>(composeCanvasMP)) +
+                                " MP >> budget " +
+                                std::to_string(static_cast<int>(canvasBudgetMP)) +
+                                " MP for warper '" + config.warperType +
+                                "' — routing to spherical (bounded geometry)";
+                            log_info(logFn, "[stitch]", "%s",
+                                     result.errorMessage.c_str());
+                            return result;  // → outer wrapper's spherical rescue
+                        }
+                    }
+                }
+            }
+        }
+    } catch (const cv::Exception& e) {
+        // warpRoi can itself throw on a degenerate camera — treat as degenerate.
+        result.errorCode = StitchErrorCode::WarpFailed;
+        result.errorMessage =
+            std::string("Degenerate high-level estimate (warpRoi threw): ") + e.what();
+        log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+        return result;
+    }
+
+    // Canvas bounded → compose.
+    try {
+        status = stitcher->composePanorama(panorama);
+    } catch (const cv::Exception& e) {
+        result.errorCode = StitchErrorCode::UnknownCvException;
+        result.errorMessage =
+            std::string("Stitcher::composePanorama threw: ") + e.what();
+        log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+        return result;
+    }
+    if (status != cv::Stitcher::OK) {
+        result.errorCode = statusToErrorCode(status);
+        result.errorMessage = "Stitcher::composePanorama failed, status " +
+            std::to_string(static_cast<int>(status));
+        log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+        return result;
+    }
+
     log_info(logFn, "[dimstat]",
              "post-stitch panorama %dx%d %dch data=%.2f MB"
              " (framesIncluded=%d/%zu, finalThresh=%.2f, attempts=%d)",
              panorama.cols, panorama.rows, panorama.channels(),
              mat_mb(panorama),
              framesIncluded, framePaths.size(), finalThreshold, finalAttempt);
-    log_info(logFn, "[memstat]", "phase=after_stitch rss=%.1f MB", rss_mb());
+    log_memstat(logFn, memstat, "after_stitch");
 
     // ── 4.  Crop (coverage-aware inscribed rect, or bbox) ───────────
     // Pull cv::Stitcher's coverage mask (0xFF filled / 0 unfilled). It is
@@ -580,6 +1140,26 @@ static StitchResult stitchFramePathsImpl_(
             rm.copyTo(coverage);  // download UMat → Mat
         }
     }
+
+    // 2026-06-16 (high-level safety) — validate the output BEFORE cropping/
+    // writing.  The manual path has had this since v0.16; the high-level path
+    // shipped whatever cv::Stitcher produced.  Rejects the black-canvas /
+    // fragmented-output failures (utilization + disjoint guards) as
+    // LowQualityStitch so the host can surface a "retry" instead of a broken
+    // image.  Fails open on an empty coverage mask.
+    {
+        std::string validateMessage;
+        const StitchErrorCode validateCode = validateStitchOutput(
+            panorama, coverage, framesIncluded, logFn, validateMessage);
+        if (validateCode != StitchErrorCode::Ok) {
+            result.errorCode = validateCode;
+            result.errorMessage = validateMessage;
+            log_error(logFn, "[stitch]", "high-level REJECTED — %s",
+                      validateMessage.c_str());
+            return result;
+        }
+    }
+
     cv::Mat cropMask;
     const cv::Rect cropRect = choose_crop_rect(
         panorama, coverage, config.useInscribedRectCrop, logFn, cropMask);
@@ -595,14 +1175,14 @@ static StitchResult stitchFramePathsImpl_(
              mat_mb(cropped),
              config.useInscribedRectCrop ? 1 : 0,
              coverage.empty() ? 0 : 1);
-    log_info(logFn, "[memstat]", "phase=after_crop rss=%.1f MB", rss_mb());
+    log_memstat(logFn, memstat, "after_crop");
 
     // ── 5.  Bake rotation per capture orientation ───────────────────
     cv::Mat final_image = bake_rotation(cropped, config.captureOrientation, logFn);
     log_info(logFn, "[dimstat]",
              "post-bake_rotation %dx%d data=%.2f MB",
              final_image.cols, final_image.rows, mat_mb(final_image));
-    log_info(logFn, "[memstat]", "phase=after_bake_rotation rss=%.1f MB", rss_mb());
+    log_memstat(logFn, memstat, "after_bake_rotation");
 
     // ── 6.  Write JPEG ──────────────────────────────────────────────
     const int q = std::max(0, std::min(100, config.jpegQuality));
@@ -625,7 +1205,7 @@ static StitchResult stitchFramePathsImpl_(
     log_info(logFn, "[stitch]",
              "output written: %s (%dx%d)",
              outputPath.c_str(), final_image.cols, final_image.rows);
-    log_info(logFn, "[memstat]", "phase=after_imwrite rss=%.1f MB", rss_mb());
+    log_memstat(logFn, memstat, "after_imwrite");
 
     // Best-effort coverage sidecar (<output>.coverage.png), bake-rotated
     // to align with the JPEG, for the debug harness. Never fails stitch.
@@ -649,7 +1229,36 @@ static StitchResult stitchFramePathsImpl_(
     result.finalConfidenceThresh  = finalThreshold;
     result.durationMs             = std::chrono::duration_cast<std::chrono::milliseconds>(
                                        t1 - t0).count();
+    // DEV overlay — cv::Stitcher owns its own compositing; for PANORAMA mode it
+    // uses GraphCut seams + MultiBand blend by default, with the configured
+    // warper.  Surfaced on the preview in __DEV__.  See StitchResult::debugSummary.
+    result.debugSummary =
+        std::string("pipe=highlevel;warp=") + config.warperType +
+        ";route=batch;seam=graphcut;blend=multiband";
     return result;
+    } catch (const cv::Exception& e) {
+        result.success = false;
+        result.errorCode = StitchErrorCode::UnknownCvException;
+        result.errorMessage =
+            std::string("high-level cv::Exception (uncaught): ") + e.what();
+        log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+        return result;
+    } catch (const std::exception& e) {
+        // std::bad_alloc from cv::Stitcher's STL internals lands here (it is NOT
+        // a cv::Exception).  Clean error instead of std::terminate.
+        result.success = false;
+        result.errorCode = StitchErrorCode::UnknownCvException;
+        result.errorMessage =
+            std::string("high-level std::exception (likely OOM): ") + e.what();
+        log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+        return result;
+    } catch (...) {
+        result.success = false;
+        result.errorCode = StitchErrorCode::UnknownCvException;
+        result.errorMessage = "high-level unknown exception (uncaught)";
+        log_error(logFn, "[stitch]", "%s", result.errorMessage.c_str());
+        return result;
+    }
 }
 
 
@@ -780,23 +1389,49 @@ StitchResult stitchFramePathsManual(
     // MB threshold (real-device headroom) rather than 1200 MB (legacy
     // protection that caps a high-RAM device at low-RAM headroom).
     const double kAssumedTotalRAMGB = 4.0;
-    const double availableRamMB = (config.availableRamMB > 0.0)
+    // Single source of truth for device RAM, shared by the pre-stitch abort
+    // AND the step-7.7 canvas budget below.  Prefer the caller's value (iOS
+    // plumbs NSProcessInfo.physicalMemory); else read it natively (Android
+    // sets none); else fall back to the conservative 4 GB assumption.
+    double totalRamMB = (config.availableRamMB > 0.0)
         ? config.availableRamMB
-        : (kAssumedTotalRAMGB * 1024.0);
-    const double availableRamGB = availableRamMB / 1024.0;
-    const double kPreStitchAbortMB = std::max(700.0, availableRamGB * 300.0);
-    if (kStartResidentMB > kPreStitchAbortMB) {
+        : device_total_ram_mb();
+    if (totalRamMB <= 0.0) totalRamMB = kAssumedTotalRAMGB * 1024.0;
+
+    // Issue 6 — headroom-scoped pre-stitch gate (replaces the old flat
+    // `max(700, ram×300)` RSS ceiling).
+    //
+    // The old check compared whole-process RSS against a flat fraction of
+    // DEVICE RAM, so a memory-heavy HOST app could trip it even when the
+    // stitch itself was tiny — and on trip it HARD-ABORTED with no attempt
+    // to route to the lighter STREAM path.  We can't isolate the stitch's
+    // own allocation from the shared process RSS (OpenCV uses malloc; no
+    // per-library accounting), so instead of a device ceiling we reason
+    // about HEADROOM: estimate the per-process kill ceiling
+    // (perProcessMemoryBudgetMB) and abort here ONLY when the process is
+    // already so close to it that even a MINIMAL streaming stitch
+    // (kMinStreamStitchMB) won't fit on top of the current footprint.  That
+    // makes this a genuine last resort scoped to the stitch's minimal
+    // incremental demand — a heavy host with headroom remaining proceeds,
+    // and everything in between is handled downstream by the step-8 STREAM
+    // routing (now also headroom-aware — see lowBatchHeadroom there) and the
+    // step-7.7 canvas-budget downscale, which size to what the stitch needs
+    // rather than aborting.
+    const double perProcessBudgetMB =
+        retailens::perProcessMemoryBudgetMB(totalRamMB);
+    if (retailens::stitchExceedsMinimalHeadroom(kStartResidentMB, totalRamMB)) {
         log_error(logFn, "[stitch-bc]",
-                  "PRE-STITCH ABORT: mem=%.1fMB > %.1fMB threshold (totalRamMB=%.0f)",
-                  kStartResidentMB, kPreStitchAbortMB, availableRamMB);
-        // V16 fix-attempt 9 — sentinel return.  See validPairs<1 site
-        // below for the full root-cause analysis.  In the iOS original
-        // this returned an empty RNStitchResult; here we return
-        // a StitchResult with success=false + a stable error code so
-        // both bridges see a clean failure rather than an
-        // ambiguous "output written but zero pixels" surface.
+                  "PRE-STITCH ABORT: rss=%.1fMB + minStitch=%.0fMB > "
+                  "perProcessBudget=%.1fMB (totalRamMB=%.0f) — no headroom for "
+                  "even a minimal streaming stitch",
+                  kStartResidentMB, retailens::kMinStreamStitchMB,
+                  perProcessBudgetMB, totalRamMB);
+        // Sentinel return: success=false + stable code so both bridges see a
+        // clean failure.  Classified to STITCH_OOM in JS (classifyStitchError
+        // matches "memory abort").
         result.errorCode = StitchErrorCode::PreStitchMemoryAbort;
-        result.errorMessage = "Pre-stitch memory abort";
+        result.errorMessage =
+            "Pre-stitch memory abort: insufficient headroom for the stitch";
         // framesIncluded reflects best-known retained count at the
         // abort site — nothing has been loaded or matched yet.
         result.framesIncluded = 0;
@@ -846,10 +1481,15 @@ StitchResult stitchFramePathsManual(
                  origCount, kMaxFramesForStitch);
     }
 
-    // Load all input frames before invoking the stitcher.  Memory cost
-    // is N × frame size — for typical shelf captures (~2048×1536 RGB,
-    // ~9 MB / frame raw, but cv::imread decodes JPEG so resident
-    // footprint is bounded by the original sensor resolution).
+    // Load all input frames before invoking the stitcher.  Memory cost is
+    // N × decoded frame size.  NOTE — keyframe resolution is PLATFORM-SPLIT
+    // (verified 2026-06): on Android the keyframe JPEGs are pre-clamped to
+    // ~640px long edge at encode time (YuvImageConverter; the
+    // AR_KEYFRAME_MAX_LONG_EDGE guard fires on dimensions, so it covers the
+    // NON-AR path too), so the resident footprint here is ~0.3 MP/frame
+    // regardless of the chosen capture format.  On iOS the keyframes are
+    // written at NATIVE capture resolution (OpenCVKeyframeCollector, no
+    // clamp), so the footprint scales with the selected video format.
     //
     // V12.13 — breadcrumb each load.  If the landscape-only crash is
     // in cv::imread (e.g., decoding a JPEG produced by the new
@@ -1196,6 +1836,16 @@ StitchResult stitchFramePathsManual(
             if (config.stitchMode == StitchMode::Scans && thresh > 0.31f) {
                 continue;
             }
+            // Panorama: skip the 0.3 floor.  leaveBiggestComponent is
+            // monotonic in the threshold, so 0.3 only ever FORCES IN a weak
+            // boundary frame that survived neither 1.0 nor 0.5 — exactly the
+            // frame BundleAdjusterRay can't refine, which then mis-places under
+            // the unbounded plane warp and marooned the content in a corner
+            // ("black canvas").  Drop it and let that frame be pruned.  Scans
+            // keeps 0.3 (it floors there by design — see the >0.31 skip above).
+            if (config.stitchMode != StitchMode::Scans && thresh < 0.4f) {
+                continue;
+            }
             // Restore from backups before each attempt — leaveBiggest-
             // Component mutated them last time.  First attempt sees the
             // originals (backup == current), subsequent attempts get a
@@ -1631,6 +2281,12 @@ StitchResult stitchFramePathsManual(
         // blender / compose / crop) consumes the warper's OUTPUTS, so the
         // swap is transparent.  If even cylindrical diverges, the in-loop
         // guard (step8b) still throws — the genuine-failure safety net.
+        // The projection actually in use after the step7.6 fallback.  The
+        // fallback swaps `warper` but NOT warperCreator, so the step7.7 cap
+        // below (which re-creates the warper at a smaller scale) must
+        // re-create via THIS — otherwise it would silently revert
+        // cylindrical→plane on exactly the wide pan the fallback rescued.
+        std::string activeWarperType = config.warperType;
         if (config.warperType != "cylindrical" && !composeFrames.empty()) {
             bool wouldDiverge = false;
             size_t divergeFrame = 0;
@@ -1646,14 +2302,186 @@ StitchResult stitchFramePathsManual(
                     break;
                 }
             }
+            // Issue 4 — quality-driven projection.  PlaneWarper projects
+            // ~tan(theta), so on a WIDE sweep the frames at the pan extremes
+            // get visibly stretched/sheared — the "perspective at the ends"
+            // users notice — even when the warp wouldn't OOM.  Estimate the
+            // total angular sweep from the bundle-adjusted camera optical
+            // axes (first vs last frame); beyond kWidePanSweepDeg switch from
+            // plane to the bounded cylindrical projection (~theta), which
+            // keeps angular spacing uniform across the pan.
+            //
+            // The sweep angle (sweepDeg, below) is AXIS-AGNOSTIC — the 3D
+            // angle between the first/last optical axes — so a Mode-A
+            // landscape *vertical* pan trips this gate just as a horizontal
+            // one does.  cylindrical bounds only the HORIZONTAL angle; its
+            // vertical axis is UNBOUNDED, so a vertical sweep's end frames
+            // project to runaway coordinates and shear apart (fragmented
+            // output — confirmed on-device 2026-06-14, a regression from
+            // 6b11da0 vs the v0.6 plane baseline).  Use SPHERICAL, which
+            // bounds BOTH axes, so vertical AND horizontal wide pans stay
+            // coherent.  (Divergence guard + step-7.7 canvas budget cap are
+            // unaffected — spherical is still a bounded projection.)
+            constexpr double kWidePanSweepDeg = 45.0;
+            const char* kWidePanWarper = "spherical";
+            double sweepDeg = 0.0;
+            if (cameras.size() >= 2) {
+                auto opticalAxis = [](const cv::Mat& R) -> cv::Vec3d {
+                    cv::Mat Rd;
+                    R.convertTo(Rd, CV_64F);
+                    // Camera looks along +Z; world view dir = R·e_z = col 2.
+                    return cv::Vec3d(Rd.at<double>(0, 2),
+                                     Rd.at<double>(1, 2),
+                                     Rd.at<double>(2, 2));
+                };
+                const cv::Vec3d a0 = opticalAxis(cameras.front().R);
+                const cv::Vec3d aN = opticalAxis(cameras.back().R);
+                const double n0 = cv::norm(a0);
+                const double nN = cv::norm(aN);
+                if (n0 > 1e-9 && nN > 1e-9) {
+                    double c = a0.dot(aN) / (n0 * nN);
+                    c = std::max(-1.0, std::min(1.0, c));
+                    sweepDeg = std::acos(c) * 180.0 / CV_PI;
+                }
+            }
+            const bool widePan = sweepDeg >= kWidePanSweepDeg;
+
+            // Only switch the warper when a frame's warp ACTUALLY blows past
+            // the size guard (genuine divergence).  The `widePan` sweep-angle
+            // heuristic (>= kWidePanSweepDeg) was too aggressive — it fired on
+            // a NORMAL moderate vertical Mode-A pan and switched away from the
+            // PLANE warper that v0.6 used cleanly into the bounded-warper path,
+            // which fragmented/doubled the output (confirmed on-device
+            // 2026-06-14: stock cv::Stitcher AND v0.6 both stitch the exact
+            // same frames cleanly on the default/plane warper; only the
+            // post-v0.6 sweep-triggered switch broke it).  Keep the divergence
+            // guard (the real OOM/garbage protection) + spherical for that
+            // case; `widePan` stays only for the diagnostic log below.
             if (wouldDiverge) {
                 log_info(logFn, "[stitch-bc]",
-                         "step7.6: '%s' warp diverges at frame %zu (>%lld MP "
-                         "guard) -- falling back to cylindrical projection",
-                         config.warperType.c_str(), divergeFrame,
-                         (long long)(kMaxWarpPixels / 1000000));
-                if (auto cyl = make_warper("cylindrical")) {
-                    warper = cyl->create(warpedScale);
+                         "step7.6: switching '%s' -> %s (diverge=%d wide=%d "
+                         "sweep=%.1fdeg, frame %zu) for a bounded projection",
+                         config.warperType.c_str(), kWidePanWarper,
+                         wouldDiverge ? 1 : 0, widePan ? 1 : 0, sweepDeg,
+                         divergeFrame);
+                if (auto bounded = make_warper(kWidePanWarper)) {
+                    warper = bounded->create(warpedScale);
+                    activeWarperType = kWidePanWarper;
+                }
+            }
+        }
+
+        // Post-cap projected canvas megapixels — drives the step-8 path
+        // choice (wide canvases route to the low-memory STREAM+feather path).
+        // Set inside step 7.7 below.
+        double composeCanvasMpFinal = 0.0;
+        // Post-cap BATCH held-set = Σ of every warped frame's area.  This —
+        // not the union — is the real driver of BATCH blend memory (N warped
+        // frames + N exposure-comp UMat copies + MultiBand pyramids, all held
+        // at once).  A SMALL union with big/overlapping frames (e.g. the ~6×
+        // higher-res AR keyframes) can still blow a huge held-set, so step 8's
+        // STREAM route keys on this too, not just the union.  Set in step 7.7.
+        double composeHeldSetMpFinal = 0.0;
+        // Step 7.7: RAM-aware output-canvas budget cap (wide-pan blend-OOM
+        // fix).  A VALID but wide pan produces a large UNION canvas, and the
+        // BATCH + MultiBand blend peak scales with it (on a 6 GB A35 a
+        // ~70 MP union hit ~2.97 GB RSS and was lmkd-killed mid-blend, never
+        // reaching step11).  Unlike the degenerate-warp guards (per-frame
+        // 100 MP / cumulative 50 MP), this is a capture we want to COMPLETE,
+        // not reject — so cap the canvas to a memory budget by reducing
+        // compose scale, yielding a slightly-lower-res but complete pano.
+        // warpRoi() here is corner-only/cheap (no pixel warp yet) and reuses
+        // the EXACT union math blender->prepare() will allocate, so the probe
+        // predicts the real canvas.  No-op for normal panos: the budget floor
+        // (12 MP) exceeds the widest valid 360° pano (~9 MP), so the 13
+        // bounded captures see byte-identical behavior.
+        if (!composeFrames.empty()) {
+            std::vector<cv::Point> capCorners(composeFrames.size());
+            std::vector<cv::Size>  capSizes(composeFrames.size());
+            bool capOk = true;
+            for (size_t i = 0; i < composeFrames.size(); i++) {
+                if (composeFrames[i].empty()) { capOk = false; break; }
+                cv::Mat capK;
+                cameras[i].K().convertTo(capK, CV_32F);
+                const cv::Rect r = warper->warpRoi(
+                    composeFrames[i].size(), capK, cameras[i].R);
+                capCorners[i] = r.tl();
+                capSizes[i]   = r.size();
+            }
+            if (capOk) {
+                int64_t cw = 0, ch = 0;
+                blendCanvasUnion(capCorners, capSizes, cw, ch);
+                const double canvasMP = (double)cw * (double)ch / 1e6;
+                const double budgetMP = composeCanvasBudgetMP(totalRamMB);
+                const double downscale =
+                    canvasDownscaleForBudget(canvasMP, budgetMP);
+                composeCanvasMpFinal = canvasMP * downscale * downscale;
+                double heldSetMpRaw = 0.0;
+                for (const auto& s : capSizes) {
+                    heldSetMpRaw += (double)s.width * (double)s.height / 1e6;
+                }
+                composeHeldSetMpFinal = heldSetMpRaw * downscale * downscale;
+                // Always-on probe — confirms the RAM read (totalRamMB), the
+                // budget, the active projection, and whether the cap fired.
+                // Used to calibrate kBlendBytesPerUnionPx from real traces.
+                log_info(logFn, "[stitch-bc]",
+                         "step7.7: canvas probe union=%lldx%lld (%.1f MP) "
+                         "budget=%.1f MP totalRamMB=%.0f warper=%s downscale=%.3f",
+                         (long long)cw, (long long)ch, canvasMP, budgetMP,
+                         totalRamMB, activeWarperType.c_str(), downscale);
+                if (downscale < 1.0) {
+                    log_info(logFn, "[stitch-bc]",
+                             "step7.7: CAPPED downscale=%.3fx (canvasMP %.1f -> "
+                             "~%.1f, budget %.1f) — re-resizing composeFrames",
+                             downscale, canvasMP,
+                             canvasMP * downscale * downscale, budgetMP);
+                    // Co-scale EVERY quantity warpRoi depends on so the post-
+                    // cap canvas actually lands at ~budget: warpedScale,
+                    // compose_scale (read by the step9 seam aspect), and each
+                    // camera's intrinsics (focal/ppx/ppy — NOT R; mirrors the
+                    // step6 compose rescale; K() rebuilds on demand).
+                    warpedScale = (float)(warpedScale * downscale);
+                    compose_scale *= downscale;
+                    for (auto& cam : cameras) {
+                        cam.focal *= downscale;
+                        cam.ppx   *= downscale;
+                        cam.ppy   *= downscale;
+                    }
+                    // Re-resize composeFrames in place at the new scale.
+                    // INTER_LINEAR + pre-allocated dst + try/catch mirror the
+                    // step7c recycled-mmap SIGSEGV stability fix; on failure,
+                    // break out to the same failure handler step7c uses.
+                    try {
+                        for (size_t i = 0; i < composeFrames.size(); i++) {
+                            if (composeFrames[i].empty()) continue;
+                            const int nw = std::max(1,
+                                (int)std::round(composeFrames[i].cols * downscale));
+                            const int nh = std::max(1,
+                                (int)std::round(composeFrames[i].rows * downscale));
+                            cv::Mat resized(nh, nw, composeFrames[i].type());
+                            cv::resize(composeFrames[i], resized,
+                                       resized.size(), 0, 0, cv::INTER_LINEAR);
+                            composeFrames[i] = resized;
+                        }
+                    } catch (const cv::Exception& e) {
+                        log_error(logFn, "[stitch-bc]",
+                                  "step7.7: compose re-resize threw: %s", e.what());
+                        capturedErrorCode = StitchErrorCode::ComposeResizeFailed;
+                        capturedErrorMessage =
+                            std::string("Canvas-cap resize failed: ") + e.what();
+                        result.framesIncluded =
+                            static_cast<int32_t>(cameras.size());
+                        failedInsidePool = true;
+                        break;
+                    }
+                    // Re-create the warper at the new scale via the ACTIVE
+                    // projection (plane, or the step7.6 cylindrical fallback).
+                    if (auto w = make_warper(activeWarperType)) {
+                        warper = w->create(warpedScale);
+                    }
+                    log_info(logFn, "[stitch-bc]",
+                             "step7.7: cap applied new warpedScale=%.2f "
+                             "compose_scale=%.3f", warpedScale, compose_scale);
                 }
             }
         }
@@ -1679,7 +2507,62 @@ StitchResult stitchFramePathsManual(
         // Both paths feed the SAME blender (selected per caller's
         // blenderType).  Final blend happens after either path
         // completes.
-        const bool useSeam = (config.seamFinderType == "graphcut");
+        // Wide-canvas low-memory routing.  BATCH + MultiBand holds every
+        // warped frame at once + N exposure-comp UMat copies + builds
+        // Laplacian pyramids; on a 6 GB device a ~28 MP canvas peaked ~3 GB
+        // in the blend/exposure stage and was lmkd-killed — even after the
+        // step-9 cappedSeamAspect fix bounded the seam finder.  Above
+        // kLowMemCanvasMP, force the STREAM path (one warped frame at a time,
+        // no held set, no exposure copies, no GraphCut) + the FEATHER blender
+        // (single-pass, no pyramids) so a wide pan COMPLETES at full
+        // resolution instead of OOMing.  Below it, keep BATCH + MultiBand +
+        // GraphCut for the crisp seams typical small-canvas captures get.
+        // 2026-06-15 — RAM-gated STREAM-routing caps.  On high-RAM devices
+        // (≥5 GB physical → 6 GB+ nominal; Android sysconf reads a few hundred
+        // MB under the marketing figure, so the gate is 5000 not 6000) raise the
+        // caps so wide pans STAY on the sharp BATCH (GraphCut + MultiBand) path
+        // instead of dropping to STREAM+feather (softer).  Low-RAM devices keep
+        // the conservative 10/15 MP thresholds.  The lowHeadroom trigger below
+        // still backstops ACTUAL memory pressure regardless of these static
+        // caps, so raising them only lifts the pre-emptive ceiling, not the
+        // safety net (a memory-pressured 6 GB device still routes to STREAM).
+        const bool kHighRamDevice = totalRamMB >= 5000.0;
+        const double kLowMemCanvasMP = kHighRamDevice ? 16.0 : 10.0;
+        // Held-set guard: BATCH stayed safe at Σ-warped-area ≲13 MP but a
+        // 6-frame AR pan with a 9.6 MP union (under kLowMemCanvasMP) yet a
+        // ~32 MP held-set hit 3.6 GB and was lmkd-killed.  Route to STREAM on
+        // EITHER axis so a small-union/large-held-set capture (bigger or
+        // heavily-overlapping frames, e.g. high-res AR keyframes) can't slip
+        // into BATCH.  15 MP sits safely between the observed safe (≲13) and
+        // fatal (~32) held-sets.
+        const double kMaxBatchHeldSetMP = kHighRamDevice ? 22.0 : 15.0;
+        // Issue 6 — headroom-aware routing.  In addition to the fixed
+        // canvas/held-set MP thresholds (which bound the stitch's OWN size),
+        // route to STREAM when the process's CURRENT free headroom is thin —
+        // i.e. whatever else is resident (host app, RN, residual buffers)
+        // leaves little room for BATCH's multiband spike.  This is the
+        // "route, don't abort" half of Issue 6: under memory pressure we drop
+        // to the lighter STREAM+feather path instead of risking an OOM (or a
+        // hard pre-stitch abort).  It only ever makes routing MORE
+        // conservative, so it can't cause an OOM the fixed thresholds avoided.
+        const double rssAtRouteMB = rss_mb();
+        const bool lowHeadroom =
+            retailens::lowBatchHeadroom(rssAtRouteMB, totalRamMB);
+        const bool lowMemCanvas =
+            composeCanvasMpFinal > kLowMemCanvasMP
+            || composeHeldSetMpFinal > kMaxBatchHeldSetMP
+            || lowHeadroom;
+        const bool useSeam =
+            (config.seamFinderType == "graphcut") && !lowMemCanvas;
+        if (lowMemCanvas) {
+            log_info(logFn, "[stitch-bc]",
+                     "step8: union=%.1f MP held-set=%.1f MP rss=%.0fMB "
+                     "budget=%.0fMB (union>%.1f or held>%.1f or lowHeadroom=%d)"
+                     " — routing to STREAM+feather",
+                     composeCanvasMpFinal, composeHeldSetMpFinal, rssAtRouteMB,
+                     perProcessBudgetMB, kLowMemCanvasMP, kMaxBatchHeldSetMP,
+                     lowHeadroom ? 1 : 0);
+        }
         log_info(logFn, "[BatchStitcher]",
                  "step8: %s",
                  useSeam ? "BATCH (warp-all + seam + feed)"
@@ -1687,6 +2570,21 @@ StitchResult stitchFramePathsManual(
         log_info(logFn, "[stitch-bc]",
                  "step8 enter: %s", useSeam ? "BATCH" : "STREAM");
 
+        // DEV overlay (2026-06-14) — record the choices made for THIS output so
+        // the preview can show them in __DEV__.  `warp` is the configured warper
+        // (a divergence-only switch to spherical is rare + logged separately);
+        // route/seam/blend are the decisions just resolved above.  See
+        // StitchResult::debugSummary.
+        {
+            const bool useFeather =
+                (config.blenderType == "feather") || lowMemCanvas;
+            result.debugSummary =
+                std::string("pipe=manual;warp=") + config.warperType +
+                ";route=" + (useSeam ? "batch" : "stream") +
+                ";seam=" + (useSeam ? "graphcut" : "none") +
+                ";blend=" + (useFeather ? "feather" : "multiband");
+        }
+
         // Build the blender once — both paths feed into it.
         //
         // The "u != 0" UMat assertion we previously hit when running
@@ -1697,7 +2595,10 @@ StitchResult stitchFramePathsManual(
         // stitch, per-frame Mat releases, plus this stream path for
         // low-mem devices), both should run cleanly.
         cv::Ptr<cv::detail::Blender> blender;
-        if (config.blenderType == "feather") {
+        if (config.blenderType == "feather" || lowMemCanvas) {
+            // FEATHER for the wide-canvas low-memory path (lowMemCanvas) too —
+            // MultiBand's pyramids are the dominant blend allocation we're
+            // avoiding.
             blender = cv::detail::Blender::createDefault(
                 cv::detail::Blender::FEATHER, false);
             auto fb = blender.dynamicCast<cv::detail::FeatherBlender>();
@@ -1739,16 +2640,20 @@ StitchResult stitchFramePathsManual(
                     cv::Mat K;
                     cameras[i].K().convertTo(K, CV_32F);
 
-                    // V12.14.6 — clone input to break any recycled-mmap
-                    // link to prior captures' allocations.  cv::Mat::clone
-                    // forces a fresh memcpy into a freshly-allocated buffer.
-                    cv::Mat freshInput = composeFrames[i].clone();
+                    // 2026-06-16 (audit #5/L4) — warp composeFrames[i] DIRECTLY.
+                    // The old V12.14.6 `freshInput = composeFrames[i].clone()` (a
+                    // full-res malloc+memcpy+free per frame, as a recycled-mmap
+                    // defense) is disproven by the STREAM warp path below, which
+                    // passes the frame raw with no clone.  warp READS the input +
+                    // writes a SEPARATE output Mat, and composeFrames[i] is
+                    // released just after — so the copy bought nothing.  Removes N
+                    // full-res copies per BATCH stitch.
 
                     // V12.14.6 — pre-allocate output Mats via warpRoi() so
                     // cv::remap doesn't need to call create() internally
                     // (the suspect path that crashed in cv::resize too).
                     cv::Rect roi = warper->warpRoi(
-                        freshInput.size(), K, cameras[i].R);
+                        composeFrames[i].size(), K, cameras[i].R);
                     // 2026-05-18 (Issue #1 guard): cv::Stitcher's estimator
                     // + BA can produce wildly wrong camera parameters on
                     // degenerate input (low feature count, near-duplicate
@@ -1776,36 +2681,19 @@ StitchResult stitchFramePathsManual(
                                   i, roi.width, roi.height,
                                   (long long)roiPixels,
                                   (long long)kMaxWarpPixels);
-                        // 2026-05-22 (audit follow-up) — include
-                        // stitchMode + frame index in the error message
-                        // so the JS host can correlate the failure with
-                        // operator behaviour.  Pre-fix the error said
-                        // nothing about which pipeline diverged.  The
-                        // value tells you: PANORAMA usually fails on
-                        // translation-heavy input (homography + BA-Ray
-                        // assume pure rotation); SCANS usually fails on
-                        // low-texture or low-overlap input (affine needs
-                        // enough matches).
-                        const char* modeStr =
-                            (config.stitchMode == StitchMode::Scans) ? "scans" : "panorama";
-                        throw cv::Exception(
-                            cv::Error::StsOutOfRange,
-                            std::string("warpRoi too large (")
-                                + std::to_string(roi.width) + "x"
-                                + std::to_string(roi.height)
-                                + ") — estimator produced degenerate "
-                                + "camera params on this frame (stitchMode="
-                                + modeStr + ", frameIdx="
-                                + std::to_string(i) + ")",
-                            "stitchFramePathsManual",
-                            __FILE__, __LINE__);
+                        // Message + envelope built by the shared helper so
+                        // all four degenerate-warp throw sites stay in sync
+                        // (see degenerateFrameException above).  Lands in the
+                        // step8b catch below → WarpFailed.
+                        throw degenerateFrameException(
+                            roi.width, roi.height, config.stitchMode, i);
                     }
-                    imagesWarped[i].create(roi.size(), freshInput.type());
+                    imagesWarped[i].create(roi.size(), composeFrames[i].type());
                     masksWarped[i].create(roi.size(), CV_8U);
 
-                    cv::Mat mask(freshInput.size(), CV_8U, cv::Scalar(255));
+                    cv::Mat mask(composeFrames[i].size(), CV_8U, cv::Scalar(255));
                     corners[i] = warper->warp(
-                        freshInput, K, cameras[i].R, cv::INTER_LINEAR,
+                        composeFrames[i], K, cameras[i].R, cv::INTER_LINEAR,
                         cv::BORDER_CONSTANT, imagesWarped[i]);
                     warper->warp(mask, K, cameras[i].R, cv::INTER_NEAREST,
                                  cv::BORDER_CONSTANT, masksWarped[i]);
@@ -1875,14 +2763,33 @@ StitchResult stitchFramePathsManual(
             // Aspect from compose scale → seam scale (the rescale we
             // apply to existing compose-scale data, not the original).
             double seam_compose_aspect = seam_scale / compose_scale;
+            // BUGFIX (wide-pan GraphCut OOM): the aspect above is derived from
+            // the INPUT frame size (origMp), but the resize below is applied to
+            // the WARPED images, which span the whole canvas and can be many×
+            // larger (a ~0.3 MP frame warps across a multi-MP canvas on a wide
+            // pan).  Left uncapped, GraphCut ran on multi-MP seam images and
+            // its per-pixel max-flow graph exploded to GBs (a 19 MP-canvas
+            // capture was lmkd-killed here — 3.16 GB RSS + 2.1 GB swap).  Re-cap
+            // against the LARGEST warped frame so every seam image is ≤ SEAM_MP,
+            // which is what cv::Stitcher's seam_est_resol actually targets.
+            double maxWarpedMp = 0.0;
+            for (size_t i = 0; i < N; i++) {
+                maxWarpedMp = std::max(
+                    maxWarpedMp,
+                    (double)sizes[i].width * (double)sizes[i].height / 1e6);
+            }
+            seam_compose_aspect =
+                cappedSeamAspect(seam_compose_aspect, maxWarpedMp, SEAM_MP);
             {
                 auto _t = std::chrono::steady_clock::now();
                 double _ms = std::chrono::duration_cast<std::chrono::milliseconds>(
                     _t - t0).count();
                 log_info(logFn, "[BatchStitcher]",
-                         "step9: graph-cut seam finder "
-                         "(compose→seam aspect = %.3f, t+%.0fms)",
-                         seam_compose_aspect, _ms);
+                         "step9: graph-cut seam finder (maxWarpedMP=%.1f "
+                         "compose→seam aspect=%.4f → seamMP≈%.2f, t+%.0fms)",
+                         maxWarpedMp, seam_compose_aspect,
+                         maxWarpedMp * seam_compose_aspect * seam_compose_aspect,
+                         _ms);
             }
             auto _seamStart = std::chrono::steady_clock::now();
             log_info(logFn, "[stitch-bc]",
@@ -1965,17 +2872,51 @@ StitchResult stitchFramePathsManual(
             auto compensator = cv::detail::ExposureCompensator::createDefault(
                 cv::detail::ExposureCompensator::GAIN_BLOCKS);
             {
+                // 2026-06-16 (audit #1) — feed the compensator ZERO-COPY views,
+                // not deep copies.  With HAVE_OPENCL undefined (both platforms)
+                // getUMat(ACCESS_READ) shares the backing Mat buffer (no memcpy,
+                // no GPU transfer); feed() takes const& and only READS pixels to
+                // solve gains, so the output is byte-identical.  The old copyTo
+                // loop DOUBLED the full-res warped held-set (~60-90 MB transient)
+                // at the exact BATCH peak the canvas budget is tuned around —
+                // imagesWarped[]/masksWarped[] are still live here (released in
+                // the feed loop below).
                 std::vector<cv::UMat> compImgs(N), compMasks(N);
                 for (size_t i = 0; i < N; i++) {
-                    imagesWarped[i].copyTo(compImgs[i]);
-                    masksWarped[i].copyTo(compMasks[i]);
+                    compImgs[i]  = imagesWarped[i].getUMat(cv::ACCESS_READ);
+                    compMasks[i] = masksWarped[i].getUMat(cv::ACCESS_READ);
                 }
                 compensator->feed(corners, compImgs, compMasks);
             }
 
-            // Feed the blender, releasing each frame as we go.
-            log_info(logFn, "[stitch-bc]", "step10a: blender->prepare");
+            // Layer-2 guard (cumulative canvas): the union of all positioned
+            // warp rects is exactly what blender->prepare() allocates as its
+            // CV_16SC3 accumulator.  Every per-frame extent passed the
+            // step8b guard above, but a single degenerate corner OFFSET can
+            // still blow this union to gigapixels — the real crash-B path
+            // (51 MB → 3.7 GB on one rapid pan).  Guard BEFORE prepare().
+            int64_t canvasW = 0, canvasH = 0;
+            blendCanvasUnion(corners, sizes, canvasW, canvasH);
+            if (canvasExceedsGuard(canvasW, canvasH)) {
+                log_error(logFn, "[stitch-bc]",
+                          "step10a: blend canvas degenerate "
+                          "(%lldx%lld px) — treating as warp failure",
+                          (long long)canvasW, (long long)canvasH);
+                throw degenerateCanvasException(
+                    canvasW, canvasH, config.stitchMode, N);
+            }
+            // Feed the blender, releasing each frame as we go.  Log the union
+            // + RSS: the union here MUST equal the step7.7 post-cap probe — a
+            // mismatch means a co-scaled quantity was missed.  step10a2
+            // isolates the persistent MultiBand accumulator (~the term the
+            // canvas budget bounds).
+            log_info(logFn, "[stitch-bc]",
+                     "step10a: blender->prepare union=%lldx%lld (%.1f MP) mem=%.1fMB",
+                     (long long)canvasW, (long long)canvasH,
+                     (double)canvasW * (double)canvasH / 1e6, rss_mb());
             blender->prepare(corners, sizes);
+            log_info(logFn, "[stitch-bc]",
+                     "step10a2: prepared mem=%.1fMB", rss_mb());
             log_info(logFn, "[stitch-bc]",
                      "step10b: feeding blender (N=%zu)", N);
             for (size_t i = 0; i < N; i++) {
@@ -2005,6 +2946,20 @@ StitchResult stitchFramePathsManual(
             for (size_t i = 0; i < N; i++) {
                 cv::Mat K;
                 cameras[i].K().convertTo(K, CV_32F);
+                // Layer-1 guard (STREAM): probe the cheap warpRoi BEFORE the
+                // real mask warp below.  Unlike BATCH, the STREAM path had no
+                // per-frame net, so a degenerate ROI would OOM inside
+                // warper->warp()'s buildMaps/remap allocation right here.
+                const cv::Rect probe = warper->warpRoi(
+                    composeFrames[i].size(), K, cameras[i].R);
+                if (warpRoiExceedsGuard(probe.width, probe.height)) {
+                    log_error(logFn, "[stitch-bc]",
+                              "step8b(stream): warpRoi degenerate for frame "
+                              "%zu (%dx%d) — treating as warp failure",
+                              i, probe.width, probe.height);
+                    throw degenerateFrameException(
+                        probe.width, probe.height, config.stitchMode, i);
+                }
                 cv::Mat mask(composeFrames[i].size(), CV_8U, cv::Scalar(255));
                 cv::Mat tmpMaskWarped;
                 corners[i] = warper->warp(
@@ -2018,6 +2973,20 @@ StitchResult stitchFramePathsManual(
             // ~40-50 MB lower peak vs the BATCH path at 1.0 MP × 8
             // frames — the difference between staying under iOS' jetsam
             // threshold on a 2 GB device and getting WatchdogTermination.
+            // Layer-2 guard (cumulative canvas) — see the BATCH path for the
+            // rationale.  Same union check before the STREAM prepare().
+            {
+                int64_t canvasW = 0, canvasH = 0;
+                blendCanvasUnion(corners, sizes, canvasW, canvasH);
+                if (canvasExceedsGuard(canvasW, canvasH)) {
+                    log_error(logFn, "[stitch-bc]",
+                              "step10(stream): blend canvas degenerate "
+                              "(%lldx%lld px) — treating as warp failure",
+                              (long long)canvasW, (long long)canvasH);
+                    throw degenerateCanvasException(
+                        canvasW, canvasH, config.stitchMode, N);
+                }
+            }
             blender->prepare(corners, sizes);
             for (size_t i = 0; i < N; i++) {
                 cv::Mat K;
@@ -2060,6 +3029,27 @@ StitchResult stitchFramePathsManual(
                  "step11c: panorama 8U conversion done (panorama=%dx%d) mem=%.1fMB",
                  panorama.cols, panorama.rows, rss_mb());
 
+        // Issue 3 — post-stitch validation.  Reject a disjoint / fragmented
+        // output (frames that survived confidence but didn't fuse into one
+        // panorama) so the host gets a clean failure (→ STITCH_LOW_QUALITY,
+        // "try again") instead of a broken image.  Fails open on an
+        // unreadable mask.  Capture the failure into the strong locals +
+        // break out of the do/while(0) like the catch paths do.
+        {
+            std::string validateMessage;
+            const StitchErrorCode validateCode = validateStitchOutput(
+                panorama, panoramaMask,
+                static_cast<int>(cameras.size()), logFn, validateMessage);
+            if (validateCode != StitchErrorCode::Ok) {
+                log_error(logFn, "[stitch-bc]",
+                          "step11d: REJECTED — %s", validateMessage.c_str());
+                capturedErrorCode = validateCode;
+                capturedErrorMessage = validateMessage;
+                failedInsidePool = true;
+                break;
+            }
+        }
+
         // Record retained-frame count for telemetry.  In the high-level
         // path this comes from stitcher->component().size() after retry;
         // in the manual path it's whatever leaveBiggestComponent kept