react-native-image-stitcher 0.15.2 → 0.16.1

package/CHANGELOG.md

@@ -14,7 +14,177 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > during 0.x are bumped to a new MINOR (e.g., 0.1 → 0.2), and the
 > upgrade path is documented in this CHANGELOG.
 
-## [Unreleased]
+## [0.16.1] — 2026-06-16
+
+### Changed — high-level `cv::Stitcher` is now the default pipeline
+
+The batch finalize now drives OpenCV's high-level `cv::Stitcher`
+(PANORAMA) on both platforms instead of the hand-rolled `cv::detail`
+("manual") path.  In testing it produced consistently better seams and
+lower, more stable peak memory.  This is a **behaviour change, not an
+API change** — the public surface (`<Camera>`, the hooks, the finalize
+options) is unchanged; only the stitched output and memory profile
+differ.
+
+The warper is chosen per-capture (pure function of the selected lens +
+pan direction), always `PANORAMA`:
+
+| Lens  | Mode A (vertical pan) | Mode B (horizontal pan) |
+| ----- | --------------------- | ----------------------- |
+| 1×    | plane                 | cylindrical             |
+| 0.5×  | spherical             | spherical               |
+
+The lens comes from the explicit `1x` / `0.5x` the user selected
+(plumbed through the finalize options); the previous FOV-from-intrinsics
+heuristic was unreliable on multi-camera devices and is gone, along with
+the now-redundant rotation-vs-translation (ex-SCANS) branch.
+
+### Added — production memory hardening on the high-level path
+
+The OOM guards that previously only covered the manual path were ported
+across, so the new default is memory-safe under pressure:
+
+- pre-stitch RSS headroom abort (also works on iOS now via the
+  `phys_footprint` probe, which revives the runtime-pressure router);
+- RAM-aware compositing resolution;
+- two-phase `estimateTransform` → project the warp canvas → abort if
+  degenerate, downscale or route to the bounded spherical warper if
+  over budget;
+- a full C++ catch ladder + a JNI backstop so an allocation failure can
+  no longer cross the C-ABI and abort the process;
+- a warper→spherical rescue (high-level) with the manual `PANORAMA` ↔
+  `SCANS` mode-fallback preserved for the iOS manual callers.
+
+### Fixed
+
+- The native allocator is purged after each stitch, and on Android the
+  OpenCV worker pool is pinned to one thread, eliminating the per-stitch
+  RSS creep observed on the manual path.
+
+## [0.16.0] — 2026-06-15
+
+### Added — first-time-user panorama capture GUIDANCE
+
+A set of opt-in-by-default guidance surfaces that coach the operator
+through a non-AR hold-and-pan panorama.  All seven are wired into
+`<Camera>` automatically and read directly from new props (none are
+threaded through `PanoramaSettings`):
+
+1. **Mode gate + 2. rotate-to-landscape prompt.** Starting a panorama
+   while the phone is held portrait under Mode A is blocked behind a
+   "Rotate to landscape" caption; the capture starts the instant the
+   user rotates to landscape (either way up).  Releasing the shutter
+   before rotating cancels the pending start.
+3. **Pan how-to overlay.** A brief code-drawn looping graphic (phone +
+   sweeping band) + bouncing direction arrow (down for landscape Mode A,
+   right for portrait Mode B) shown for ~2.5 s at the start of each
+   recording.
+4. **"Moving too fast" pill.** A transient amber pill while the gyro
+   pan rate exceeds the warn threshold.
+5. **Blinking countdown + auto-finalize.** A blinking whole-seconds
+   countdown; at 0 the capture auto-finalizes (stitches what was
+   captured — same path as releasing the shutter).
+6. **Lateral-drift stop.** If the operator drifts sideways out of the
+   pan plane beyond the budget, the capture FINALIZES what was captured
+   and a one-button popup explains why.
+7. **Post-stitch review surface.** Optional. `rectCrop` shows a
+   draggable-quad crop editor (drag four corners; confirm perspective-
+   rectifies in place via `cv::warpPerspective` when the quad isn't
+   axis-aligned, "Use original" emits un-cropped, "Retake" discards).
+   `showPreview` shows the same screen with NO crop box — just the
+   stitched image with [Retake]/[Confirm]. With both off, `onCapture`
+   fires immediately.
+
+New `<Camera>` props (all optional): `panMode`, `panGuidance`
+(default `true`), `maxPanDurationMs` (default `9000`; `0` disables the
+countdown + auto-finalize), `panTooFastThreshold`, `lateralBudgetCm`
+(default `5`; `0` disables the lateral stop), `rectCrop`
+(default `false`), `showPreview` (default `false`), and
+`guidanceCopy` (partial override of every guidance string). A skewed
+crop quad is always perspective-rectified (there is no opt-out flag).
+
+New public exports: the `PanMode` type, `GuidanceCopy` +
+`DEFAULT_GUIDANCE_COPY`, the `usePanMotion` hook, the five guidance
+components (`RotateToLandscapePrompt`, `PanHowToOverlay`,
+`CaptureCountdownOverlay`, `LateralMotionModal`, `RectCropPreview`) with
+their prop types, and the `cropQuad` perspective-rectify helper.
+
+### Added — capture hardening
+
+Follow-up hardening on top of the guidance set, driven by on-device
+testing:
+
+- **Guidance graphics are now code-drawn, not GIFs.** The rotate-to-
+  landscape and pan-capture animations are rendered with pure RN
+  `View` + `Animated` (`guidanceGraphics.tsx`) — resolution-independent
+  (no pixelation on high-density screens) and themeable via
+  `GUIDANCE_TOKENS`. Removes the bundled GIF assets AND the Android
+  host's previous need to add Fresco's `animated-gif` module.
+- **Crop editor seeds from the max-inscribed rectangle.** With
+  `rectCrop`, the draggable quad now opens on the tightest clean
+  rectangle (native `computeInscribedRect`) instead of a blind 8 %
+  inset, and the editor gains an explicit **"Use original"** button
+  (emit the stitch un-cropped) plus a warning banner. When the editor is
+  on, the native auto-crop is forced off so the full bordered panorama
+  is available to drag.
+- **`onCapture` carries `warnings`.** Both success and failure results
+  include `warnings: CaptureWarning[]` — `LOW_FRAME_UTILIZATION` (<70 %
+  of captured frames used) and `LATERAL_DRIFT_FINALIZE`. New exports:
+  `CaptureWarning`, `CaptureWarningCode`, `PanoramaCaptureResult`.
+- **Post-stitch validation.** A disjoint / fragmented stitch (frames
+  that survived confidence but didn't fuse into one panorama) is now
+  rejected with the new `STITCH_LOW_QUALITY` error code + "try again"
+  copy, instead of emitting a broken image.
+- **Quality-driven warper.** Wide pans switch from plane to the bounded
+  cylindrical projection based on the estimated sweep angle (not only on
+  an OOM-divergence fallback), reducing end-of-pan perspective stretch.
+- **Headroom-based memory gating.** The flat process-RSS pre-stitch
+  abort is replaced by a per-process headroom model: under memory
+  pressure the pipeline routes to the lighter STREAM+feather path rather
+  than hard-aborting, and the pre-stitch abort fires only when there's
+  no room for even a minimal stitch on top of the current footprint —
+  so a memory-heavy host app no longer trips it spuriously.
+
+### Added — `stitcher` / `frameSelection` config as JSON-object props
+
+`<Camera>` now accepts the full stitcher and frame-gate config as JSON
+objects — `stitcher={{ warperType, blenderType, seamFinderType,
+stitchMode, enableMaxInscribedRectCrop }}` and
+`frameSelection={{ mode, maxKeyframes, overlapThreshold,
+maxKeyframeIntervalMs, flow }}` (both partial; `flow` is deep-merged).
+Object fields win over the matching flat `default*` props, which remain
+supported. This is the recommended way to configure the pipeline.
+
+### Changed (BREAKING)
+
+- **`onCapture` is now a discriminated union keyed on `ok`.** It fires
+  once per capture attempt — on success (`ok:true`, discriminated
+  further by `type`) AND on failure (`ok:false`, carrying `error:
+  CameraError`); previously it fired only on success and failures went
+  solely to `onError`. `onError` STILL fires on failure as an unchanged
+  mirror. **Migration:** gate on `result.ok` before reading
+  `uri`/`width`/`height` — `if (!result.ok) { handle(result.error);
+  return; }`. Both branches also carry the new `warnings` array.
+- **`<Camera>` now defaults to `panMode='vertical'` (landscape-only,
+  top→bottom panorama).** Previously the component accepted both
+  landscape and portrait holds with no gate.  `panMode` options are now
+  `'vertical'` (landscape-only; portrait holds gated behind the
+  rotate-to-landscape prompt), `'horizontal'` (portrait-only, left→right;
+  landscape holds gated behind the rotate-to-portrait prompt), and
+  `'both'` (either, ungated).  **Hosts that want portrait/left→right
+  panoramas pass `panMode='horizontal'` or `'both'`.**
+- **Stitch defaults moved to more robust values.** `stitchMode` now
+  defaults to `'panorama'` (was `'auto'` — the auto-resolver's SCANS
+  branch keys off double-integrated IMU translation, which is unreliable
+  during rotation); `warperType` defaults to `'spherical'` (was
+  `'plane'` — bounds both axes, fixing fragmented wide/vertical pans);
+  and the keyframe gate is denser (`maxKeyframes` → 8, a 1.5 s
+  `maxKeyframeIntervalMs` time gate re-enabled — bounding a static/slow
+  capture to ~12 s before the 8-keyframe auto-finalize, `overlapThreshold`
+  → 0.15).  **Migration:** hosts relying on the previous behaviour set the
+  values explicitly via the new `stitcher` / `frameSelection` props (or
+  the matching flat `default*` props) — e.g. `stitcher={{ stitchMode:
+  'auto', warperType: 'plane' }}`.
 
 ## [0.15.2] — 2026-06-11
 

package/README.md

@@ -83,6 +83,15 @@ import {
 
 export function CaptureScreen() {
   const handleCapture = (result: CameraCaptureResult) => {
+    // `onCapture` fires on success AND failure — gate on `ok` first.
+    if (!result.ok) {
+      console.warn('capture failed:', result.error.code, result.error.message);
+      return;
+    }
+    // Non-fatal quality signals (e.g. <70% of frames used). Always present.
+    if (result.warnings.length > 0) {
+      console.warn('warnings:', result.warnings.map((w) => w.code));
+    }
     if (result.type === 'photo') {
       console.log('Photo:', result.uri, result.width, result.height);
     } else {
@@ -98,6 +107,8 @@ export function CaptureScreen() {
   return (
     <Camera
       onCapture={handleCapture}
+      // onError still fires on failure too (an unchanged mirror of the
+      // ok:false result above).
       onError={(err: CameraError) => console.warn(err.code, err.message)}
     />
   );
@@ -135,10 +146,13 @@ export function CaptureScreen() {
   // 2. Capture history (drives the built-in thumbnail strip).
   const [thumbnails, setThumbnails] = useState<CaptureThumbnailItem[]>([]);
 
-  // 3. Post-stitch preview modal — set on capture, cleared on close.
-  const [preview, setPreview] = useState<CameraCaptureResult | null>(null);
+  // 3. Post-stitch preview modal — set on success, cleared on close.
+  const [preview, setPreview] = useState<
+    Extract<CameraCaptureResult, { ok: true }> | null
+  >(null);
 
   const onCapture = useCallback((result: CameraCaptureResult) => {
+    if (!result.ok) return; // failures go to onError; nothing to preview
     setPreview(result);
     setThumbnails((prev) => [
       ...prev,
@@ -260,12 +274,12 @@ Setting `headerTitle` renders a built-in top header; the settings gear is absorb
 
 | Prop | Type | Fires / purpose |
 |---|---|---|
-| `onCapture` | `(result: CameraCaptureResult) => void` | Photo OR panorama completes. `result.type` discriminates (`'photo'` / `'panorama'`). |
+| `onCapture` | `(result: CameraCaptureResult) => void` | Fires once per capture attempt. **Gate on `result.ok` first** (`true` = output present, discriminated further by `result.type`; `false` carries `result.error`). Both carry `result.warnings: CaptureWarning[]` (e.g. `LOW_FRAME_UTILIZATION`). |
 | `onCaptureSourceChange` | `(source: CaptureSource) => void` | Effective source changes (AR toggle, or 0.5× forcing non-AR). |
 | `onLensChange` | `(lens: CameraLens) => void` | User taps the 1×/0.5× chip. |
 | `onFramesDropped` | `(info: FramesDroppedInfo) => void` | cv::Stitcher's confidence retry dropped input frame(s). |
 | `onCaptureAbandoned` | `(reason: 'orientation-drift') => void` | SDK auto-cancelled an in-flight capture (currently only mid-capture rotation). |
-| `onError` | `(err: CameraError) => void` | Classified error — see codes below. |
+| `onError` | `(err: CameraError) => void` | Classified error — fires on failure as an unchanged mirror of the `ok:false` `onCapture` result. See codes below. |
 | `outputDir` | `string` | Directory for saved JPEGs. The lib creates it if missing. |
 | `engine` | `'batch-keyframe' \| …` | Stitching engine. Default `'batch-keyframe'`; most apps leave it. |
 | `frameProcessor` | vision-camera frame processor | Host worklet composed with first-party stitching (see [`useStitcherWorklet`](docs/camera-component.md)). Advanced. |
@@ -320,7 +334,119 @@ import { Alert } from 'react-native';
 ```
 
 It lives in the SDK (not per-host) so every consumer shows the same guidance for
-the same failure. The `example/` app uses it end-to-end.
+the same failure. The `example/` app uses it end-to-end. To localise this copy,
+pass an `overrides` map as the second argument — see
+[Internationalization](#internationalization-i18n) below.
+
+## Internationalization (i18n)
+
+Every user-facing string the SDK can show is **overridable** — there is no
+bundled `locale` prop. By design you supply the translated strings from your
+own i18n catalogue (i18next, FormatJS, etc.); the SDK never ships translations
+it can't keep in sync with your wording. There are exactly **two** surfaces, and
+together they cover **100 %** of what a user reads:
+
+### 1. `guidanceCopy` — everything the SDK renders on screen
+
+A single `Partial<GuidanceCopy>` prop. Pass the keys you want to translate;
+omitted keys fall back to the English default. This covers the rotate prompt,
+the pan hint, the live "too fast" cue, the lateral-drift popups, the crop-editor
+buttons, the **capture-status banner**, and the **crop-editor warning banners**:
+
+Each default is the **exact, complete** source string — translate it verbatim
+(keep the `{included}` / `{requested}` / `{percent}` placeholders in
+`warnLowFrameUtilization`), or `import { DEFAULT_GUIDANCE_COPY }` to seed your
+catalogue programmatically.
+
+| Key | Where it appears | English default (translate verbatim) |
+| --- | --- | --- |
+| `rotateToLandscape` | rotate prompt | `Rotate to landscape` |
+| `rotateToPortrait` | rotate prompt | `Rotate to portrait` |
+| `panHint` | pan how-to overlay | `Pan slowly top to bottom` |
+| `tooFast` | speed-cue pill | `Moving too fast — slow down` |
+| `lateralStopTitle` | lateral-drift popup (stitched) | `Keep the pan straight` |
+| `lateralStopBody` | lateral-drift popup (stitched) | `You moved sideways. Pan in one direction only — we stitched what you captured.` |
+| `lateralStopDismiss` | lateral-drift popup button | `Got it` |
+| `lateralWrongDirectionTitle` | lateral-drift popup (too few frames) | `Follow the arrow` |
+| `lateralWrongDirectionBody` | lateral-drift popup (too few frames) | `You moved the phone the wrong way. Pan slowly in the direction the arrow shows, in one straight line.` |
+| `cropConfirm` | crop-editor button | `Crop` |
+| `cropReset` | crop-editor button | `Reset` |
+| `cropUseOriginal` | crop-editor button | `Use original` |
+| `cropRetake` | crop-editor button | `Retake` |
+| `previewConfirm` | preview accept button (`showPreview`) | `Confirm` |
+| `statusRecording` | status banner | `Hold steady — pan slowly` |
+| `statusStitching` | status banner | `Stitching panorama…` |
+| `warnLowFrameUtilization` | crop warning **(template)** | `Only {included} of {requested} captured frames ({percent}%) could be used — the panorama may be incomplete. Pan more slowly and steadily next time.` |
+| `warnLateralDriftFinalize` | crop warning | `Capture stopped early because the phone drifted sideways — only the part captured before the drift was stitched.` |
+| `warnHighPanSpeed` | crop warning | `The capture was taken faster than the recommended pace — the result may not be the best. Pan more slowly next time.` |
+
+> **Templates:** `warnLowFrameUtilization` is interpolated at runtime — your
+> translation must keep the `{included}`, `{requested}` and `{percent}`
+> placeholders (an unknown placeholder is left verbatim rather than throwing).
+> Overriding a `warn*` key re-words **both** the on-screen banner **and** the
+> `message` carried on `onCapture(...).warnings[]`. The matching machine-readable
+> `code` (e.g. `HIGH_PAN_SPEED`) is always present regardless of wording, so you
+> can also branch on the code instead of the string.
+
+### 2. `userFacingStitchError(code, overrides?)` — the host-rendered error alert
+
+The recoverable-stitch-error copy is rendered by **you** (in `onError`), so it's
+localised at the call site: pass an `overrides` map (keyed by the codes in the
+exported `RECOVERABLE_STITCH_CODES`) and any match wins over the bundled English;
+omitted codes keep the default.
+
+```tsx
+import {
+  Camera,
+  userFacingStitchError,
+  RECOVERABLE_STITCH_CODES,
+  DEFAULT_GUIDANCE_COPY,
+  type GuidanceCopy,
+  type UserFacingStitchErrorOverrides,
+} from 'react-native-image-stitcher';
+import { Alert } from 'react-native';
+import { useTranslation } from 'react-i18next';
+
+function CaptureScreen() {
+  const { t } = useTranslation();
+
+  // (1) SDK-rendered copy — translate the keys you care about.
+  const guidanceCopy: Partial<GuidanceCopy> = {
+    rotateToLandscape: t('pano.rotateToLandscape'),
+    statusRecording: t('pano.statusRecording'),
+    // keep the placeholders in the template translation:
+    warnLowFrameUtilization: t('pano.warnLowFrames'), // "{included}/{requested} ({percent}%) …"
+    // …any subset; the rest stay English via DEFAULT_GUIDANCE_COPY
+  };
+
+  // (2) Host-rendered error alerts — translate by code.
+  const errorCopy: UserFacingStitchErrorOverrides = Object.fromEntries(
+    RECOVERABLE_STITCH_CODES.map((code) => [
+      code,
+      { title: t(`pano.err.${code}.title`), message: t(`pano.err.${code}.msg`) },
+    ]),
+  );
+
+  return (
+    <Camera
+      guidanceCopy={guidanceCopy}
+      onError={(err) => {
+        const friendly = userFacingStitchError(err.code, errorCopy);
+        if (friendly) Alert.alert(friendly.title, friendly.message);
+        else reportGenericError(err);
+      }}
+    />
+  );
+}
+```
+
+`DEFAULT_GUIDANCE_COPY` and `DEFAULT_CAPTURE_WARNING_COPY` are exported so you can
+seed your translation catalogue from the source strings, and
+`RECOVERABLE_STITCH_GUIDANCE` exposes the built-in error copy for the same reason.
+
+> **Full worked example** — a Spanish `es.json` catalogue (both surfaces) plus a
+> host language-setting that switches the copy at runtime: see the
+> [Internationalization guide](https://bhargavkanda.github.io/react-native-image-stitcher/docs/i18n#worked-example-spanish-with-a-dynamic-language-setting).
 
 ### Migration from 0.13.x
 

package/android/src/main/cpp/image_stitcher_jni.cpp

@@ -28,6 +28,15 @@
 
 #include <string>
 #include <vector>
+#include <cstdio>    // /proc/self/statm read for the purge diagnostic
+#include <unistd.h>  // sysconf — device RAM for the manual-pipeline budget
+#include <dlfcn.h>   // dlsym — resolve mallopt() at runtime (API-gated; see below)
+
+// M_PURGE (release free pages back to the OS) was added to bionic at API 28;
+// define it for our minSdk-24 build (a harmless no-op on the older allocator).
+#ifndef M_PURGE
+#define M_PURGE (-101)
+#endif
 
 
 #define LOG_TAG "BatchStitcher.JNI"
@@ -63,6 +72,59 @@ void androidLogBridge(int level, const char* tag, const char* msg) {
     __android_log_print(prio, LOG_TAG, "%s %s", tag ? tag : "", msg ? msg : "");
 }
 
+// 2026-06-15 — last successful stitch's debugSummary (pipe/warp/route/seam/blend).
+// The nativeStitchFramePaths return is a jintArray which can't carry a string,
+// so we stash it here and expose it via the lightweight nativeLastDebugSummary()
+// getter that Kotlin calls right after a successful stitch (same thread → no
+// concurrency).  Mirrors the iOS RNStitchResult.debugSummary surface so the DEV
+// overlay shows warp/route/seam/blend on Android too, not just mode/score.
+std::string g_lastDebugSummary;
+
+// Return the just-finished stitch's freed native memory to the OS.  cv::Mat /
+// the OpenCV allocator keep freed blocks in a process-wide pool, so without this
+// the native-heap RSS baseline ratchets up ~10-15 MB per capture (dumpsys showed
+// the creep in Native Heap, not Graphics).  mallopt() was exported by bionic at
+// API 26 but our minSdk is 24, so resolve it at runtime via dlsym and call only
+// when present (it is on every API-26+ device, including the test A35).
+double procRssMB() {
+    FILE* f = fopen("/proc/self/statm", "r");
+    if (f == nullptr) return -1.0;
+    long sizePages = 0, residentPages = 0;
+    const int n = fscanf(f, "%ld %ld", &sizePages, &residentPages);
+    fclose(f);
+    if (n != 2) return -1.0;
+    return static_cast<double>(residentPages)
+        * static_cast<double>(sysconf(_SC_PAGE_SIZE)) / (1024.0 * 1024.0);
+}
+
+// Returns the POST-purge RSS in MB (the leak-plateau "floor"), or -1 when the
+// diagnostic reads are gated off.  The mallopt(M_PURGE) CALL is UNCONDITIONAL —
+// it's the leak fix; only its before/after READS + the log are gated (3A), so a
+// release build pays nothing while debug builds surface memFloor.
+double purgeNativeAllocator(bool profiling) {
+    using MalloptFn = int (*)(int, int);
+    // Resolve mallopt at runtime (API-26 symbol; minSdk 24).  Prefer an explicit
+    // libc.so handle — RTLD_DEFAULT from a dlopen'd .so doesn't always reach
+    // libc on Android — then fall back to RTLD_DEFAULT.
+    static MalloptFn fn = []() -> MalloptFn {
+        void* h = dlopen("libc.so", RTLD_NOLOAD | RTLD_NOW);
+        void* s = (h != nullptr) ? dlsym(h, "mallopt") : nullptr;
+        if (s == nullptr) s = dlsym(RTLD_DEFAULT, "mallopt");
+        return reinterpret_cast<MalloptFn>(s);
+    }();
+    const double before = profiling ? procRssMB() : -1.0;
+    if (fn != nullptr) fn(M_PURGE, 0);          // the fix — always runs
+    if (!profiling) return -1.0;
+    const double after = procRssMB();
+    // Diagnostic: shows whether mallopt resolved and how much RSS the purge
+    // actually returned to the OS.  If mallopt=MISSING → dlsym failed; if
+    // resolved but before≈after → the residual isn't allocator-retained (real
+    // leak) and M_PURGE can't help.
+    LOGI("[memstat] purge: mallopt=%s rss %.1f -> %.1f MB",
+         (fn != nullptr) ? "ok" : "MISSING", before, after);
+    return after;  // memFloor — the post-purge plateau metric
+}
+
 }  // namespace
 
 
@@ -81,7 +143,8 @@ Java_io_imagestitcher_rn_BatchStitcher_nativeStitchFramePaths(
         jdouble registrationResolMP,
         jdouble seamEstimationResolMP,
         jdouble compositingResolMP,
-        jstring stitchModeStr) {
+        jstring stitchModeStr,
+        jboolean useManualPipeline) {
 
     if (framePaths == nullptr) {
         throw_runtime(env, "framePaths is null");
@@ -116,24 +179,89 @@ Java_io_imagestitcher_rn_BatchStitcher_nativeStitchFramePaths(
         ? retailens::StitchMode::Panorama
         : retailens::StitchMode::Scans;
 
-    // 2026-06-07 — unify on the manual cv::detail pipeline.  It won the
-    // on-device A/B: equals the high-level cv::Stitcher on quality after
-    // parity AND is strictly more robust — the cylindrical fallback, warp
-    // guard, and exposure comp all live only in the manual path, so the
-    // high-level path garbages wide/0.5x captures.  Mirrors iOS'
-    // OpenCVStitcher.mm.  See docs/stitch-pipeline-architecture.md §7.
-    cfg.useManualPipeline = true;
-    // Match iOS' parity resolution: the manual entry's default registration
-    // is 0.3 MP (vs the high-level's 0.6); bump to 0.6 unless the caller set
-    // an explicit value.  (compositingResolMP already arrives as 1.0.)
+    // 2026-06-15 — pipeline is caller-selectable (mirrors iOS).  The batch
+    // finalize passes useManualPipeline=true: ALL the memory/OOM hardening
+    // lives on the manual path (PreStitchMemoryAbort, RAM-aware canvas-budget
+    // downscale, STREAM/BATCH held-set routing, the black-canvas utilization
+    // guard); the high-level cv::Stitcher path calls NONE of it — so manual is
+    // both the preferred output AND the memory-safe one.  The on-demand
+    // HIGH-LEVEL preview tab calls refinePanorama with useManualPipeline=false
+    // to re-stitch the captured keyframes via stock cv::Stitcher.
+    //
+    // WARPER: NOT hardcoded — cfg.warperType carries the caller's choice (set
+    // above from the JS `warperType`, which defaults to "spherical" and is
+    // settable via the ⚙️ panel / the host's `defaultWarper` prop).  The JS
+    // default is the single source of truth now (mirrors iOS).  Choosing "plane"
+    // re-arms the manual pipeline's dynamic plane→spherical fallback/divergence
+    // switch (they only fire when warperType != "spherical").
+    cfg.useManualPipeline = (useManualPipeline == JNI_TRUE);
+    // 2026-06-16 — memory profiling (DEV).  Gated by the compile flag (debug-on,
+    // release-off); Android leaves memProbeFn null so rss_mb() uses /proc.
+    cfg.enableMemoryProfiling = (RNIS_MEMORY_PROFILING != 0);
+    if (cfg.warperType.empty()) cfg.warperType = "spherical";
     if (cfg.registrationResolMP <= 0.0) {
         cfg.registrationResolMP = 0.6;
     }
+    // Plumb the device's physical RAM so the manual pipeline's memory budget
+    // (perProcessMemoryBudgetMB = RAM × 0.42, floored at 900 MB) scales to the
+    // ACTUAL device instead of the assumed-4GB fallback (which over-throttles a
+    // 6–8 GB phone into STREAM+feather → blurrier).  iOS passes physicalMemory;
+    // on Android we read it from sysconf here (no JNI signature change needed).
+    if (cfg.availableRamMB <= 0.0) {
+        const long pages    = sysconf(_SC_PHYS_PAGES);
+        const long pageSize = sysconf(_SC_PAGE_SIZE);
+        if (pages > 0 && pageSize > 0) {
+            cfg.availableRamMB =
+                static_cast<double>(pages) * static_cast<double>(pageSize)
+                / (1024.0 * 1024.0);
+        }
+    }
 
     const std::string outPath = jstring_to_string(env, outputPath);
 
-    retailens::StitchResult result = retailens::stitchFramePaths(
-        paths, outPath, cfg, &androidLogBridge);
+    // 2026-06-16 (review #1) — backstop try/catch at the JNI C-ABI boundary.
+    // stitchFramePaths now has its own catch ladders (high-level + manual), so
+    // this should never fire — but a C++ exception crossing into JNI is UB
+    // (std::terminate/SIGABRT), so we NEVER let one through: convert any escape
+    // into a Java exception the Kotlin layer can catch.
+    retailens::StitchResult result;
+    try {
+        result = retailens::stitchFramePaths(
+            paths, outPath, cfg, &androidLogBridge);
+    } catch (const std::exception& e) {
+        throw_runtime(env, std::string("native stitch crashed: ") + e.what());
+        return nullptr;
+    } catch (...) {
+        throw_runtime(env, "native stitch crashed (unknown exception)");
+        return nullptr;
+    }
+
+    // Return the stitch's freed native memory to the OS so the native-heap RSS
+    // baseline doesn't ratchet up ~10-15 MB per capture (see purgeNativeAllocator).
+    // Applies to BOTH pipelines (they share the OpenCV/bionic allocator).  The
+    // post-purge RSS is the leak-plateau "floor" — append it to debugSummary so
+    // it rides the existing nativeLastDebugSummary() path to JS (no new bridge).
+    const double memFloor = purgeNativeAllocator(RNIS_MEMORY_PROFILING != 0);
+    if ((RNIS_MEMORY_PROFILING != 0) && memFloor >= 0.0) {
+        char fbuf[40];
+        std::snprintf(fbuf, sizeof(fbuf), ";memFloor=%.1f", memFloor);
+        if (!result.debugSummary.empty()) result.debugSummary += fbuf;
+        // 2026-06-16 — one authoritative per-stitch memory line to logcat (the
+        // sampler peak otherwise only rides debugSummary to the on-screen
+        // overlay).  pipe/warp/mode lets each line be attributed to a preview
+        // tab: pipe=manual warp=plane mode=panorama = "As captured" primary;
+        // pipe=highlevel warp=plane = HL·Plane; warp=spherical = HL·Sph;
+        // mode=scans = SCANS.  Grep `[memstat] record:` to harvest all of them.
+        LOGI("[memstat] record: pipe=%s warp=%s mode=%s before=%.1f peak=%.1f "
+             "after=%.1f floor=%.1f src=%s frames=%d/%d",
+             cfg.useManualPipeline ? "manual" : "highlevel",
+             cfg.warperType.c_str(),
+             (result.stitchModeUsed == retailens::StitchMode::Scans)
+                 ? "scans" : "panorama",
+             result.memBeforeMB, result.memPeakMB, result.memAfterMB, memFloor,
+             result.memSource.c_str(),
+             result.framesIncluded, result.framesRequested);
+    }
 
     if (!result.success) {
         const std::string msg = "Stitch failed: " + result.errorMessage +
@@ -142,6 +270,10 @@ Java_io_imagestitcher_rn_BatchStitcher_nativeStitchFramePaths(
         return nullptr;
     }
 
+    // Stash the run's debugSummary for nativeLastDebugSummary() (jintArray
+    // can't carry a string).  Read by Kotlin right after this returns.
+    g_lastDebugSummary = result.debugSummary;
+
     // Return [width, height, framesRequested, framesIncluded, finalThresholdMilli]
     // — same JNI return layout as the previous file (Kotlin already
     // parses indices 0-4).  The threshold is multiplied by 1000 +
@@ -157,3 +289,12 @@ Java_io_imagestitcher_rn_BatchStitcher_nativeStitchFramePaths(
     env->SetIntArrayRegion(dims, 0, 5, values);
     return dims;
 }
+
+// Returns the debugSummary of the most recent successful stitch (pipe/warp/
+// route/seam/blend).  Kotlin calls this right after nativeStitchFramePaths so
+// the value is fresh (stitches are serialized on one background thread).
+extern "C" JNIEXPORT jstring JNICALL
+Java_io_imagestitcher_rn_BatchStitcher_nativeLastDebugSummary(
+        JNIEnv* env, jobject /*thiz*/) {
+    return env->NewStringUTF(g_lastDebugSummary.c_str());
+}

package/android/src/main/cpp/keyframe_gate_jni.cpp

@@ -311,23 +311,30 @@ Java_io_imagestitcher_rn_KeyframeGate_nativeEvaluateWithFrame(
         }
     }
 
-    // Pin the byte[] for the duration of the gate evaluate.  Use
-    // GetPrimitiveArrayCritical (zero-copy, JVM pins the GC) over
-    // GetByteArrayElements (may copy on some VMs) because at 30-60
-    // Hz of 2 MB Y-planes, the copy cost adds up.  Evaluate is
-    // ~1-5 ms so the pin window is short.  Always paired with
-    // ReleasePrimitiveArrayCritical even on the error paths below.
+    // 2026-06-16 (audit #4) — pin the byte[] ONLY to INGEST it.
+    // GetPrimitiveArrayCritical is zero-copy (the JVM pins the GC) — preferred
+    // over GetByteArrayElements (which may copy a 2 MB Y-plane at 30-60 Hz) —
+    // but it blocks the GC for the pin's whole life.  So we keep that life to a
+    // single downscale: ingestWorkingFrame() reads the pinned bytes into an
+    // OWNED working frame, we Release IMMEDIATELY, then evaluateWithWorkingMat()
+    // runs the heavy OpenCV (goodFeaturesToTrack / optical flow) with the pin
+    // already gone — no longer stalling the GC or the frame-rate producer
+    // thread.  Always paired with ReleasePrimitiveArrayCritical, even on errors.
     retailens::KeyframeGateDecision d;
     if (grayBytes && grayWidth > 0 && grayHeight > 0 && grayStride >= grayWidth) {
         void* raw = env->GetPrimitiveArrayCritical(grayBytes, nullptr);
         if (raw) {
-            d = gate(handle)->evaluateWithFrame(
-                pose, planePtr,
+            gate(handle)->ingestWorkingFrame(
                 static_cast<const uint8_t*>(raw),
                 static_cast<int32_t>(grayWidth),
                 static_cast<int32_t>(grayHeight),
                 static_cast<int32_t>(grayStride));
             env->ReleasePrimitiveArrayCritical(grayBytes, raw, JNI_ABORT);
+            // Pin released — heavy OpenCV now runs outside the critical section.
+            d = gate(handle)->evaluateWithWorkingMat(
+                pose, planePtr,
+                static_cast<int32_t>(grayWidth),
+                static_cast<int32_t>(grayHeight));
         } else {
             // GetPrimitiveArrayCritical failed (rare, but defensive).
             // Fall back to pose-only path so we degrade gracefully