react-native-image-stitcher 0.15.2 → 0.16.1

package/cpp/stitcher.hpp

@@ -47,6 +47,23 @@
 #include <vector>
 
 
+// ── 2026-06-16 — memory-profiling compile gate (shared) ─────────────────
+// Hard gate for the peak sampler + per-stitch record + [memstat] phase logs
+// (stitcher.cpp) and the mallopt purge diagnostic READS (image_stitcher_jni.cpp).
+// Default: ON in debug, OFF in release, so production pays nothing.  Override
+// with -DRNIS_MEMORY_PROFILING=1 to profile a release build.  NDEBUG is the
+// portable signal both Gradle (Debug CMake config) and Xcode use, so this is
+// uniform across Android + iOS with no per-build-system flag.  Defined in the
+// shared header so all three native translation units agree.
+#ifndef RNIS_MEMORY_PROFILING
+#  ifdef NDEBUG
+#    define RNIS_MEMORY_PROFILING 0
+#  else
+#    define RNIS_MEMORY_PROFILING 1
+#  endif
+#endif
+
+
 namespace retailens {
 
 // Stable error codes.  Mirror the JS-side `StitchErrorCode` enum so
@@ -92,6 +109,7 @@ enum class StitchErrorCode : int32_t {
     ComposeResizeFailed         = 104,
     WarpFailed                  = 105,
     EmptyPanorama               = 106,
+    LowQualityStitch            = 107,  // post-stitch validator: disjoint/fragmented output
     InvalidArgument             = 200,
     UnknownCvException          = 300,
 };
@@ -196,6 +214,23 @@ struct StitchConfig {
     // flip it to true once the manual port is verified — separate
     // commit from this V2 introduction.
     bool        useManualPipeline    = false;
+
+    // ── 2026-06-16 — memory profiling hooks (DEV deploy gate) ───────────
+    // memProbeFn: resident-memory source in MB, or < 0 if unavailable.  When
+    // set it is the canonical reader used by rss_mb() (so the OOM guards, the
+    // phase logs, the peak sampler and the per-stitch record all use it).  Its
+    // reason for existing is iOS, which has no /proc/self/statm — the Obj-C++
+    // bridge plugs task_info(TASK_VM_INFO).phys_footprint here.  Android leaves
+    // it null and rss_mb() falls back to /proc.  Must be callable from a
+    // background thread (the peak sampler), so the closure must not touch
+    // thread-affine state.
+    std::function<double()> memProbeFn = nullptr;
+    // enableMemoryProfiling: runtime gate (plumbed from settings.debug) for the
+    // peak sampler + the per-stitch record + the [memstat] phase logs.  The
+    // COMPILE-time RNIS_MEMORY_PROFILING flag (off in release) is the hard gate;
+    // this is the per-call switch on top.  The mallopt(M_PURGE) CALL is NOT
+    // gated by this — only its diagnostic READS are.
+    bool        enableMemoryProfiling = false;
 };
 
 
@@ -225,6 +260,33 @@ struct StitchResult {
     // StitchConfig::stitchMode iff the fallback ran.  Defaults to
     // Panorama for back-compat in code paths that don't set it.
     StitchMode stitchModeUsed         = StitchMode::Panorama;
+
+    // 2026-06-14 (DEV overlay) — a human-readable, machine-parseable trace of
+    // the choices the stitcher actually made for THIS output, surfaced on the
+    // preview in __DEV__ so the user can see HOW a panorama was built without
+    // reading logcat/Console.  Semicolon-separated `key=value` pairs, e.g.
+    //   "pipe=manual;warp=spherical;route=batch;seam=graphcut;blend=multiband"
+    // Empty on builds that don't populate it (back-compat).  iOS marshals it up
+    // to the JS finalize dict; Android leaves it in the log for now.
+    std::string debugSummary;
+
+    // ── 2026-06-16 — per-stitch memory record (DEV profiling) ───────────
+    // All in MB; -1.0 when profiling is off or no memory source is available.
+    //   memBeforeMB: resident at entry (after the leak-fix once-guard).
+    //   memPeakMB:   max resident sampled DURING the stitch by the 50 ms peak
+    //                sampler — the transient warp-all + GraphCut + MultiBand
+    //                spike that the phase-boundary reads miss (it decides OOM).
+    //   memAfterMB:  resident after the pipeline returns (blender pyramids freed).
+    //   memFloorMB:  resident after the platform's post-stitch reclaim — Android
+    //                fills it after mallopt(M_PURGE); iOS after a settle read.
+    //                This is the leak-PLATEAU metric (the bridge sets it; the
+    //                core leaves it at -1).
+    //   memSource:   "phys_footprint" (iOS task_info) | "rss" (/proc) | "".
+    double      memBeforeMB = -1.0;
+    double      memPeakMB   = -1.0;
+    double      memAfterMB  = -1.0;
+    double      memFloorMB  = -1.0;
+    std::string memSource;
 };
 
 

package/cpp/warp_guard.hpp

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 #pragma once
 #include <cstdint>
+#include <cmath>
 
 // ─────────────────────────────────────────────────────────────────────
 // Warp-canvas size guard — shared by the warp pre-pass (which decides
@@ -21,6 +22,23 @@ namespace retailens {
 // frame, and blending several would jetsam-OOM the app.  100 megapixels.
 constexpr int64_t kMaxWarpPixels = 100LL * 1000LL * 1000LL;
 
+// Max size of the CUMULATIVE blend canvas — the bounding box over every
+// positioned warp rect (corner + size) that `cv::detail::Blender::prepare`
+// allocates as its CV_16SC3 accumulator (~6 bytes/px) plus a CV_8U mask
+// and, for MultiBand, Laplacian-pyramid overhead (~1.5-2× on top).  This
+// is a DIFFERENT axis from kMaxWarpPixels: a degenerate homography can
+// shift ONE frame's corner to a huge offset so the union spans gigapixels
+// while every individual frame's extent still passes the per-frame guard.
+// Guarding the union before prepare() is what actually stops crash B (the
+// 51 MB → 3.7 GB single-pan blow-up).
+//
+// 50 MP sizing: a valid 360° cylindrical canvas is ~9 MP (2π·~1200 px
+// focal × ~1200 px tall) and real field-log panoramas are ~1.3 MP, so
+// 50 MP is ~5× headroom over the widest legitimate pano (zero false
+// positives) while 50 MP × (6 + 1) bytes + pyramid overhead ≈ 500-600 MB
+// peak — comfortably under the 6 GB-class pre-stitch headroom.
+constexpr int64_t kMaxCanvasPixels = 50LL * 1000LL * 1000LL;
+
 // True if a warp ROI of `width`×`height` px is degenerate: non-positive
 // in either dimension, or strictly larger than `maxPixels` (so a canvas
 // exactly at the limit is still allowed).
@@ -38,4 +56,198 @@ inline bool warpRoiExceedsGuard(int width, int height,
   return pixels > maxPixels;
 }
 
+// True if the cumulative blend-canvas of `width`×`height` px is degenerate:
+// non-positive in either dimension, or strictly larger than `maxPixels`
+// (so a canvas exactly at the limit is still allowed).  Same int64 area
+// math as warpRoiExceedsGuard — the union of a degenerate corner offset is
+// exactly the case where int32 area would overflow.  Takes int64 dims
+// because the union is computed in int64 (a degenerate corner can exceed
+// the int32 range on its own).
+inline bool canvasExceedsGuard(int64_t width, int64_t height,
+                               int64_t maxPixels = kMaxCanvasPixels) {
+  if (width <= 0 || height <= 0) {
+    return true;
+  }
+  // width/height are already bounded by the caller's union math, but cap
+  // the multiply defensively: if either exceeds ~3 G the product overflows
+  // int64, and such a dimension is degenerate by any measure.
+  if (width > 3'000'000'000LL || height > 3'000'000'000LL) {
+    return true;
+  }
+  return width * height > maxPixels;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// RAM-aware output-canvas budget (the wide-pan blend-OOM fix).
+//
+// Distinct from the guards above: a VALID but wide pan produces a large
+// union canvas, and the BATCH + MultiBand blend peak scales with it (on a
+// 6 GB device a ~70 MP union hit ~2.97 GB RSS and was lmkd-killed mid-
+// blend).  Rather than REJECT a valid capture, we cap the canvas to a
+// memory budget by reducing compose scale — yielding a slightly-lower-res
+// but COMPLETE panorama.  The two functions below are the OpenCV-free,
+// unit-testable core of that cap (the warp/resize itself lives in
+// stitcher.cpp and is on-device-only).
+//
+// kBlendBytesPerUnionPx was back-solved from the on-device capture-14
+// failure: (2970 MB peak − ~330 MB baseline) / 70.7 MP ≈ 37.4 B per union
+// pixel.  Round up to 38 for headroom.  kBudgetCeilMP (42) keeps a 6 GB
+// device's predicted peak (~1.9 GB) under its lmkd death point while
+// staying ≤ kMaxCanvasPixels (50 MP) so the degenerate-canvas guard above
+// never fires on a cap-eligible pan.  kBudgetFloorMP (12) is > the widest
+// VALID 360° panorama (~9 MP), so a normal pano is provably never capped.
+constexpr double kBlendBytesPerUnionPx = 38.0;
+constexpr double kBlendRamFraction     = 0.30;
+constexpr double kBudgetFloorMP        = 12.0;
+constexpr double kBudgetCeilMP         = 42.0;
+
+// Output-canvas megapixel budget for a device with `totalRamMB` of RAM.
+// Monotonic-nondecreasing in RAM, clamped to [floor, ceil].  A non-
+// positive/sentinel RAM falls to the floor (the caller should resolve a
+// -1 sentinel to an assumed RAM before calling, but never get a <=0
+// budget regardless).
+inline double composeCanvasBudgetMP(double totalRamMB) {
+  const double raw = (totalRamMB * kBlendRamFraction) / kBlendBytesPerUnionPx;
+  if (raw < kBudgetFloorMP) return kBudgetFloorMP;
+  if (raw > kBudgetCeilMP)  return kBudgetCeilMP;
+  return raw;
+}
+
+// Linear downscale factor that brings a `canvasMP`-megapixel canvas down to
+// `budgetMP`.  Canvas area scales with factor², so factor = sqrt(budget /
+// canvas), clamped to [0.2, 1.0]: never UPSCALES (≤ 1.0 — a canvas already
+// within budget returns 1.0, a no-op), and never collapses below 0.2 (a
+// canvas still over budget after 0.2× is degenerate, which the separate
+// canvasExceedsGuard net catches on its own axis).  Returns 1.0 when either
+// input is non-positive (no div-by-zero; matches a "nothing to cap" no-op).
+inline double canvasDownscaleForBudget(double canvasMP, double budgetMP) {
+  if (canvasMP <= 0.0 || budgetMP <= 0.0 || canvasMP <= budgetMP) {
+    return 1.0;
+  }
+  double factor = std::sqrt(budgetMP / canvasMP);
+  if (factor < 0.2) factor = 0.2;
+  if (factor > 1.0) factor = 1.0;
+  return factor;
+}
+
+// Seam-finder downscale aspect, re-capped against the WARPED image size.
+//
+// The GraphCut seam finder must run at ~`seamMp` megapixels per image (what
+// cv::Stitcher's seam_est_resol targets) or its per-pixel max-flow graph
+// blows up — a wide-pan capture whose warped images spanned a 19 MP canvas
+// OOM-killed the app because the seam images were multi-MP, not 0.1 MP.
+//
+// The caller's `inputAspect` is derived from the INPUT frame size, but the
+// resize it feeds is applied to the WARPED images, which can be many× larger
+// (the warp expands a ~0.3 MP frame across the whole canvas).  So re-cap the
+// aspect so the LARGEST warped frame (`maxWarpedMp`) downscales to ≤ seamMp.
+// Never RAISES the aspect (only tightens it); a no-op when the warped images
+// are already ≤ seamMp or the inputs are degenerate.
+inline double cappedSeamAspect(double inputAspect, double maxWarpedMp,
+                               double seamMp) {
+  if (seamMp <= 0.0 || maxWarpedMp <= seamMp) {
+    return inputAspect;
+  }
+  const double capped = std::sqrt(seamMp / maxWarpedMp);
+  return (capped < inputAspect) ? capped : inputAspect;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Issue 3 — post-stitch disjointness check (pure).
+//
+// The confidence filter drops frames that don't register, but nothing
+// validated the OUTPUT: a frame that survived confidence yet landed
+// geometrically disconnected shows up as a separate blob in the coverage
+// mask ("disjointed image frames in the output").  Given the largest
+// connected component's area, the total covered area, and the frame count,
+// decide whether a MEANINGFUL fraction of coverage lies OUTSIDE the main
+// blob — i.e. the frames didn't fuse into one panorama.  Pure so the
+// threshold is unit-testable; the OpenCV connected-components extraction
+// (which feeds these areas) lives in stitcher.cpp's validateStitchOutput.
+//
+// Conservative by design: a normal panorama is ONE connected blob
+// (fragmentFraction ≈ 0), so the 0.15 default never trips on it; a whole
+// disconnected frame in a few-frame pan easily exceeds 15 % of coverage.
+constexpr double kMaxStitchFragmentFraction = 0.15;
+
+inline bool stitchOutputIsDisjoint(
+    double largestComponentArea, double totalCoveredArea, int numFrames,
+    double maxFragmentFraction = kMaxStitchFragmentFraction) {
+  if (numFrames < 2) return false;
+  if (totalCoveredArea <= 0.0 || largestComponentArea <= 0.0) return false;
+  const double fragmentFraction =
+      1.0 - (largestComponentArea / totalCoveredArea);
+  return fragmentFraction > maxFragmentFraction;
+}
+
+// Coverage-to-canvas UTILIZATION guard — the "black canvas" failure.  When
+// BundleAdjusterRay mis-places a weak boundary frame, PlaneWarper throws it
+// far off-axis so the union canvas balloons and the real content clusters in
+// one corner.  That is a single coherent blob, so `stitchOutputIsDisjoint`
+// (fragmentFraction ≈ 0) PASSES it — yet it's garbage.  Guard the ratio of
+// covered pixels to total panorama pixels instead.  A valid pano (cropped to
+// its coverage downstream) fills well above this; a marooned-corner canvas is
+// only a percent or two.  The 50 MP `canvasExceedsGuard` catches gigapixel
+// blowups; this catches the moderate 12–50 MP band it leaves open.
+constexpr double kMinStitchUtilization = 0.10;
+
+inline bool stitchOutputUnderutilized(
+    double totalCoveredArea, double canvasArea, int numFrames,
+    double minUtilization = kMinStitchUtilization) {
+  if (numFrames < 2) return false;
+  if (canvasArea <= 0.0 || totalCoveredArea <= 0.0) return false;
+  return (totalCoveredArea / canvasArea) < minUtilization;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Issue 6 — headroom-based memory gating (pure).
+//
+// We CANNOT measure the stitch's own allocation apart from the shared
+// process RSS (OpenCV uses malloc; there's no per-library accounting).  So
+// rather than a flat device-scaled RSS ceiling — which a memory-heavy HOST
+// app trips even when the stitch itself is small — we reason about HEADROOM:
+// estimate the per-process kill ceiling and gate on whether the stitch's
+// INCREMENTAL demand fits on top of the CURRENT process footprint.
+
+// Estimated per-process memory ceiling (MB) before the OS (iOS jetsam /
+// Android lmkd) kills the app, as a fraction of total device RAM.  Anchored
+// to the iPhone 16 Pro (8 GB) observed jetsam at ~3.38 GB ⇒ ~0.42.  Floored
+// so tiny (2 GB) devices still get a sane budget.
+constexpr double kProcessLimitFraction = 0.42;
+constexpr double kProcessBudgetFloorMB = 900.0;
+
+inline double perProcessMemoryBudgetMB(double totalRamMB) {
+  const double raw = totalRamMB * kProcessLimitFraction;
+  return (raw < kProcessBudgetFloorMB) ? kProcessBudgetFloorMB : raw;
+}
+
+// Smallest streaming-stitch peak we insist on having room for (one warped
+// frame + the CV_16SC3 accumulator + masks at compose resolution).
+// Conservative.
+constexpr double kMinStreamStitchMB = 350.0;
+
+// Early pre-stitch gate: abort BEFORE loading frames ONLY when the process
+// is already so close to its ceiling that even a minimal streaming stitch
+// won't fit on top of the current footprint.  A true last resort — scoped to
+// the stitch's MINIMAL incremental demand, not a flat device ceiling — so a
+// heavy host app with headroom remaining still proceeds.
+inline bool stitchExceedsMinimalHeadroom(double currentRssMB,
+                                         double totalRamMB) {
+  return currentRssMB + kMinStreamStitchMB
+         > perProcessMemoryBudgetMB(totalRamMB);
+}
+
+// Comfortable free headroom (MB) below which we prefer the STREAM+feather
+// path over BATCH (graphcut+multiband), whose blend peak can spike far above
+// STREAM's.  Used as an ADDITIONAL routing trigger alongside the fixed
+// canvas/held-set MP thresholds — it only ever makes routing MORE
+// conservative (more likely STREAM), never less, so it can't cause an OOM
+// that the fixed thresholds would have avoided.
+constexpr double kBatchHeadroomMB = 1000.0;
+
+inline bool lowBatchHeadroom(double currentRssMB, double totalRamMB) {
+  return (perProcessMemoryBudgetMB(totalRamMB) - currentRssMB)
+         < kBatchHeadroomMB;
+}
+
 }  // namespace retailens

package/dist/camera/Camera.d.ts

@@ -44,7 +44,12 @@ import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-nativ
 import { type CaptureHeaderProps } from './CaptureHeader';
 import { type CapturePreviewAction } from './CapturePreview';
 import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
+import { type CaptureStatusPhase } from './CaptureStatusOverlay';
+import { type PanoramaPropOverrides } from './buildPanoramaInitialSettings';
 import { type DeviceOrientation } from './useDeviceOrientation';
+import { type PanMode } from './panModeGate';
+import { type GuidanceCopy } from './cameraGuidanceCopy';
+import { type CaptureWarning } from './captureWarnings';
 export type CaptureSource = 'ar' | 'non-ar';
 /**
  * v0.13.2 — which capture sources the host ALLOWS.  A constraint on top
@@ -63,24 +68,43 @@ export type Blender = 'multiband' | 'feather';
 export type SeamFinder = 'graphcut' | 'skip';
 export type Warper = 'plane' | 'cylindrical' | 'spherical';
 /**
- * Result emitted via `onCapture`.  Discriminated union keyed on
- * `type` so consumers handle both photo and panorama outputs through
- * one callback path.
+ * Result emitted via `onCapture`.  Discriminated union keyed FIRST on
+ * `ok` (success vs. failure) and then on `type` (photo vs. panorama), so a
+ * host handles EVERY capture outcome — success, degraded success, and
+ * failure — through this one callback.
  *
- * Identifier `CameraCaptureResult` (vs. the SDK's existing
- * `CaptureResult` from `../types`) is intentional — the existing
- * CaptureResult shape has SDK-specific fields (deviceMetadata,
- * qualityReport, deviceUuid) that don't belong in the public RN
- * library's surface.  Step 3 (symbol rename) will retire the
- * historical SDK-specific names; for now we keep both types
- * side-by-side so the existing host code continues to work.
+ * ## v0.16 — unified success/failure + warnings (BREAKING)
+ *
+ * Previously `onCapture` fired only on success and carried no `ok` field;
+ * failures went *solely* to `onError`.  Hosts therefore had no single place
+ * to learn whether a capture succeeded, and no programmatic signal that a
+ * stitch was *degraded* (e.g. most frames dropped).  Now:
+ *
+ *   - `onCapture` ALWAYS fires once per capture attempt, with `ok:true`
+ *     (output present) or `ok:false` (carrying the `CameraError`).
+ *   - both success and failure carry `warnings: CaptureWarning[]` — non-fatal
+ *     quality signals (e.g. `LOW_FRAME_UTILIZATION` when <70 % of captured
+ *     frames survived, `LATERAL_DRIFT_FINALIZE` when item-6 stopped early).
+ *   - `onError` STILL fires on failure too (an unchanged mirror), so existing
+ *     error handling keeps working.
+ *
+ * Migration: gate on `ok` before reading `uri`/`width`/`height` —
+ * `if (!result.ok) { handle(result.error); return; }`.
+ *
+ * Identifier `CameraCaptureResult` (vs. the SDK's existing `CaptureResult`
+ * from `../types`) is intentional — the existing CaptureResult shape has
+ * SDK-specific fields that don't belong in the public RN library's surface.
  */
 export type CameraCaptureResult = {
+    ok: true;
     type: 'photo';
     uri: string;
     width: number;
     height: number;
+    /** Non-fatal quality signals (empty when none). */
+    warnings: CaptureWarning[];
 } | {
+    ok: true;
     type: 'panorama';
     uri: string;
     width: number;
@@ -99,12 +123,70 @@ export type CameraCaptureResult = {
      * cv::Stitcher at finalize).
      */
     stitchModeResolved?: 'panorama' | 'scans';
+    /**
+     * 2026-06-15 (DEV) — gyro rotation magnitude of the capture, in radians.
+     * Shown on the dev preview so the panorama-vs-SCANS rotation threshold can
+     * be tuned. `0` = no pose-derived rotation signal (non-AR with no poses).
+     */
+    rRadians?: number;
+    /**
+     * 2026-06-16 (DEV) — translation magnitude (m) + auto decision ratio
+     * (`>=0.55` → SCANS) that drove panorama-vs-SCANS. Shown on the dev
+     * readout alongside `rRadians` to tune the threshold from real captures.
+     */
+    tMeters?: number;
+    decisionRatio?: number;
+    /**
+     * 2026-06-14 (DEV overlay) — semicolon-separated `key=value` trace of the
+     * stitcher's runtime choices (pipe/warp/route/seam/blend) for this
+     * output.  Shown on the preview in __DEV__.  iOS only for now.
+     */
+    debugSummary?: string;
+    /**
+     * 2026-06-15 (iOS) — keyframe JPEG paths used for this stitch, so the
+     * preview can re-stitch them on demand via `refinePanorama` (the
+     * high-level tab).  iOS only; undefined elsewhere.
+     */
+    keyframePaths?: string[];
+    /**
+     * 2026-06-15 (iOS) — orientation this stitch baked in.  The on-demand
+     * high-level re-stitch passes it back so it matches the manual output's
+     * rotation (not the raw sensor landscape).  iOS only.
+     */
+    captureOrientation?: string;
+    /** Non-fatal quality signals (empty when none). */
+    warnings: CaptureWarning[];
+} | {
+    ok: false;
+    /** Which capture path failed. */
+    type: 'photo' | 'panorama';
+    /** The classified failure (same object handed to `onError`). */
+    error: CameraError;
+    /** Any warnings gathered before the failure (usually empty). */
+    warnings: CaptureWarning[];
 };
+/**
+ * The success-panorama variant of {@link CameraCaptureResult} — the exact
+ * shape stashed for the crop editor and re-emitted (with adjusted dims) once
+ * the user crops.  Narrowed so the crop-confirm spread keeps `uri`/`width`/
+ * `height`/`ok` without a cast.
+ */
+export type PanoramaCaptureResult = Extract<CameraCaptureResult, {
+    ok: true;
+    type: 'panorama';
+}>;
 /**
  * Errors surfaced via `onError`.  Classified codes so consumers can
  * branch on the kind of failure (toast vs retry vs report).
  */
-export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL' | 'STITCH_OOM' | 'OUTPUT_WRITE_FAILED'
+export type CameraErrorCode = 'CAMERA_PERMISSION_DENIED' | 'CAMERA_DEVICE_UNAVAILABLE' | 'PHOTO_CAPTURE_FAILED' | 'PANORAMA_START_FAILED' | 'PANORAMA_FINALIZE_FAILED' | 'STITCH_NEED_MORE_IMGS' | 'STITCH_HOMOGRAPHY_FAIL' | 'STITCH_CAMERA_PARAMS_FAIL'
+/**
+ * v0.16 — the native post-stitch validator rejected the output: the
+ * panorama came out disjoint / fragmented / wildly mis-proportioned
+ * (frames didn't connect into one coherent image).  Recoverable by
+ * re-capturing, so it carries "try again" copy.
+ */
+ | 'STITCH_LOW_QUALITY' | 'STITCH_OOM' | 'OUTPUT_WRITE_FAILED'
 /**
  * Vision-camera surfaced a runtime error that isn't a known
  * transient lifecycle event (those are swallowed inside the SDK's
@@ -156,6 +238,19 @@ export interface CameraProps {
     defaultRegistrationResolMP?: number;
     /** Forward-looking — see above. */
     defaultSeamEstimationResolMP?: number;
+    /**
+     * v0.16 — pass the whole stitcher config as a JSON object instead of the
+     * individual `default*` props above (canonical field names: `warperType` /
+     * `blenderType` / `seamFinderType` / `stitchMode` /
+     * `enableMaxInscribedRectCrop`).  Partial; any field set here wins over the
+     * matching flat prop.  Runtime ⚙️-panel edits still override at capture time. */
+    stitcher?: PanoramaPropOverrides['stitcher'];
+    /**
+     * v0.16 — pass the whole frame-gate config as a JSON object (canonical field
+     * names: `mode` / `maxKeyframes` / `overlapThreshold` / `maxKeyframeIntervalMs`
+     * / `flow`).  Partial; `flow` is deep-merged.  Wins over the flat `default*`
+     * props. */
+    frameSelection?: PanoramaPropOverrides['frameSelection'];
     /**
      * Crop strategy for the stitched panorama. `false` (default) keeps the
      * bounding-rect of non-black pixels, which preserves all stitched
@@ -248,12 +343,19 @@ export interface CameraProps {
      * decisively cancels the capture (`incremental.cancel()`) and
      * surfaces `OrientationDriftModal` to explain what happened.
      *
+     * v0.16 adds `'lateral-drift'`: the user moved the phone perpendicular to
+     * the pan arrow before enough frames were captured to stitch.  Rather than
+     * finalize into a misleading "need more images" error, the SDK abandons the
+     * capture and surfaces the `LateralMotionModal` with "follow the arrow"
+     * copy.  (A lateral drift AFTER enough frames still finalizes what was
+     * captured and fires `onCapture` with a `LATERAL_DRIFT_FINALIZE` warning.)
+     *
      * Hosts use this callback to clean up their own state (e.g., reset
      * a wizard step, log telemetry, surface their own retry UX in
      * addition to the SDK's built-in modal).  No `onCapture` will fire
      * for an abandoned capture.
      */
-    onCaptureAbandoned?: (reason: 'orientation-drift') => void;
+    onCaptureAbandoned?: (reason: 'orientation-drift' | 'lateral-drift') => void;
     /**
      * v0.13.0 — flash (torch) state.  Controlled-or-uncontrolled.
      *
@@ -495,6 +597,83 @@ export interface CameraProps {
      * CHANGELOG.)
      */
     frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
+    /**
+     * Which device holds the non-AR panorama capture accepts.
+     *
+     *   - `'vertical'` (DEFAULT) — LANDSCAPE-only, top→bottom pan.  Starting a
+     *     panorama in portrait is BLOCKED behind the rotate-to-landscape
+     *     prompt (item 2); the capture starts the instant they rotate to
+     *     landscape (either way up).
+     *   - `'horizontal'` — PORTRAIT-only, left→right pan.  Starting in
+     *     landscape is BLOCKED behind the rotate-to-portrait prompt; capture
+     *     starts on rotating to portrait (either way up).
+     *   - `'both'` — landscape OR portrait; the rotate gate never fires, the
+     *     user captures in whichever hold they're already in.
+     *
+     * **BREAKING (since the previous release accepted both holds ungated):**
+     * the default is now `'vertical'`.  Hosts that want left→right (portrait)
+     * panoramas use `panMode='horizontal'` (portrait-only) or `'both'`.  See
+     * CHANGELOG.
+     */
+    panMode?: PanMode;
+    /**
+     * Master switch for the in-capture pan-guidance surfaces (rotate
+     * prompt, pan how-to overlay, too-fast pill, blinking countdown).
+     * Default `true`.  Set `false` to suppress all of them (the lateral-
+     * drift FINALIZE behaviour and the crop preview are governed by their
+     * own props, not this flag).
+     */
+    panGuidance?: boolean;
+    /**
+     * Optional hard recording-TIME ceiling for a non-AR panorama, in
+     * milliseconds, used as a SAFETY cap alongside the primary keyframe-count
+     * auto-stop.  The default capture now finalizes when the configured
+     * keyframe count is reached (see the frame counter HUD), so this is `0`
+     * (disabled) by default.  Set it to a positive value to ALSO cap the
+     * recording by wall-clock time; when > 0 a blinking countdown (item 5)
+     * shows the seconds remaining and the capture auto-finalizes at 0.
+     *
+     * v0.16 — default changed `9000` → `0` (time cap is now opt-in; the
+     * keyframe-count stop is the default UX).
+     */
+    maxPanDurationMs?: number;
+    /**
+     * Gyro rate (rad/s) above which the pan is flagged "moving too fast"
+     * (item 4 — the transient amber pill).  Optional; forwards to
+     * `usePanMotion`'s `warnMaxRadPerSec` (default 1.0 rad/s there).
+     */
+    panTooFastThreshold?: number;
+    /**
+     * Cross-pan (lateral) drift budget in CENTIMETRES (item 6).  Once the
+     * operator's integrated sideways translation exceeds this for the
+     * hook's grace window, the capture FINALIZES what was captured and a
+     * one-button popup explains why.  Default `5`.  `0` disables the
+     * lateral-drift stop entirely.
+     */
+    lateralBudgetCm?: number;
+    /**
+     * Show the draggable-quad crop editor after a panorama finalizes, BEFORE
+     * emitting it via `onCapture`.  Default `false`.  When `true`, the user
+     * drags 4 corners over the stitched result; confirming crops in place
+     * (perspective-rectify when the quad isn't axis-aligned), "Use original"
+     * emits the un-cropped panorama, "Retake" discards it.  Takes precedence
+     * over {@link showPreview}.
+     */
+    rectCrop?: boolean;
+    /**
+     * Show a plain review screen after a panorama finalizes — the stitched
+     * image with [Retake] / [Confirm] and NO crop box.  Default `false`.
+     * Ignored when {@link rectCrop} is on (the crop editor is itself the
+     * preview).  With both off, `onCapture` fires immediately with no UI.
+     */
+    showPreview?: boolean;
+    /**
+     * Copy overrides for every guidance string (rotate prompt, pan hint,
+     * too-fast warning, lateral-stop popup, crop buttons).  Partial —
+     * unspecified keys fall back to {@link DEFAULT_GUIDANCE_COPY}.  Hosts
+     * localise or re-word the whole guidance surface in one place here.
+     */
+    guidanceCopy?: Partial<GuidanceCopy>;
 }
 /**
  * The public `<Camera>` component.
@@ -545,5 +724,23 @@ declare function isSideEdge(edge: HomeIndicatorEdge): boolean;
 export declare const _homeIndicatorEdgeForTests: typeof homeIndicatorEdge;
 /** @internal test-only — see `isSideEdge`. */
 export declare const _isSideEdgeForTests: typeof isSideEdge;
+/**
+ * cameraShouldUnmount — whether the live camera (<CameraView> /
+ * <ARCameraView>) should be UNMOUNTED (replaced by the placeholder) this
+ * render rather than mounted.
+ *
+ * True while a camera-switch transition or AR-support probe is in flight,
+ * OR during the stitch (statusPhase==='stitching').  The stitching case is
+ * the V12.14.8 OOM fix: unmounting frees vision-camera's AVCaptureSession +
+ * preview buffers (~150-250 MB) BEFORE the memory-heavy stitch, so the
+ * live-camera footprint and the stitch peak never coexist and jetsam (iOS)
+ * / lmkd (Android) don't OOM-kill the app.
+ *
+ * Pure + exported for test — the lib's jest config can't mount <Camera>,
+ * so this boolean is the unit-testable core of the OOM render gate.
+ */
+declare function cameraShouldUnmount(inFlightTransition: boolean, arSupportPending: boolean, statusPhase: CaptureStatusPhase): boolean;
+/** @internal test-only — see `cameraShouldUnmount`. */
+export declare const _cameraShouldUnmountForTests: typeof cameraShouldUnmount;
 export {};
 //# sourceMappingURL=Camera.d.ts.map