react-native-image-stitcher 0.14.1 → 0.15.0

package/ios/Sources/RNImageStitcher/RNSARSession.swift

@@ -485,40 +485,14 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         isRunning = true
         currentTrackingState = .initialising
 
-        // v0.8.0 Phase 3c — install the worklet runtime + register
-        // the first-party stitching callback.  The delegate's
-        // per-frame ingest now routes through
-        // `RNSARWorkletRuntime.dispatchFrame` (see
-        // `session(_:didUpdate:)` below) which invokes this
-        // callback synchronously.  Net behavior is byte-identical
-        // to the pre-Phase-3c direct `consumer.consumeFrame(...)`
-        // call.  The indirection sets up the seam where Phase 4
-        // will fan out to host worklets without touching this
-        // first-party path.
-        RNSARWorkletRuntime.shared().installIfNeeded()
-        RNSARWorkletRuntime.shared().setFirstPartyCallback {
-            [weak self] arFrame, pose in
-            // ARKit pool reuse contract: must consume the pixel
-            // buffer before returning.  The consumer's
-            // `consumeFrame` does that synchronously inside the
-            // call (NV12 → cv::Mat sync, then heavy work on its
-            // own queue).  We're on the same thread as the
-            // delegate (ARSession.delegateQueue), so the contract
-            // holds end-to-end.
-            guard let self = self else { return }
-            guard let consumer = self.incrementalConsumer else { return }
-            consumer.consumeFrame(pixelBuffer: arFrame.capturedImage,
-                                  pose: pose)
-        }
+        // Per-frame ingest calls `incrementalConsumer.consumeFrame`
+        // directly from `session(_:didUpdate:)` below. (The v0.8
+        // worklet-runtime indirection that used to live here was archived
+        // in the batch-keyframe cleanup — see archive/.)
     }
 
     @objc public func stop() {
         guard isRunning else { return }
-        // v0.8.0 Phase 3c — drop the first-party callback so the
-        // closure's `[weak self]` reference can be released
-        // immediately + no in-flight delegate frame re-enters the
-        // engine after stop.  Idempotent.
-        RNSARWorkletRuntime.shared().setFirstPartyCallback(nil)
         arSession.pause()
         isRunning = false
         currentTrackingState = .notAvailable
@@ -602,11 +576,12 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         // `useFrameProcessor` TS hook + a JSI plugin entry point)
         // without changing this first-party path.
         //
-        // ARKit pool reuse contract: still satisfied — the runtime
-        // invokes the callback synchronously on the delegate
-        // thread, and the callback's `consumer.consumeFrame(...)`
-        // does the same NV12 → cv::Mat sync conversion as before.
-        RNSARWorkletRuntime.shared().dispatchFrame(frame, pose: pose)
+        // ARKit pool reuse contract: consumeFrame does the NV12 →
+        // cv::Mat sync conversion synchronously on the delegate thread
+        // before returning, so the captured pixel buffer is safe for
+        // ARKit to recycle after this call.
+        incrementalConsumer?.consumeFrame(pixelBuffer: frame.capturedImage,
+                                          pose: pose)
 
         // If recording is in flight, append this frame to the
         // asset writer DIRECTLY — no queue hop.

package/ios/Sources/RNImageStitcher/Stitcher.swift

@@ -151,11 +151,11 @@ public enum Stitcher {
         // IncrementalStitcher) hit the method directly with
         // the right value.
         captureOrientation: nil,
-        // V16 Phase 1b.fix5c — generic Stitcher API defaults the
-        // crop strategy to bbox-only (matches the operator-default
-        // in the panorama settings modal).  Callers that want
-        // inscribed-rect can use IncrementalStitcher with
-        // the toggle on.
+        // V16 Phase 1b.fix5c — generic Stitcher API keeps the crop
+        // strategy at bbox-only (conservative; the panorama-capture
+        // path now defaults to inscribed-rect via the settings).
+        // Callers that want inscribed-rect can use IncrementalStitcher
+        // with the toggle on.
         useInscribedRectCrop: false,
         // 2026-05-22 (audit F2) — legacy video-stitch API doesn't
         // expose stitchMode in its options dict yet.  nil falls
@@ -193,6 +193,72 @@ public enum Stitcher {
     }
   }
 
+  /// v0.15 debug — compute the max-inscribed rectangle of the image
+  /// (no file change), for the example app's crop-visualisation harness.
+  public static func computeInscribedRect(
+    imagePath: String
+  ) throws -> (x: Int, y: Int, width: Int, height: Int, imageWidth: Int, imageHeight: Int) {
+    do {
+      let d = try OpenCVStitcher.computeInscribedRect(atPath: imagePath)
+      return (
+        x: d["x"]?.intValue ?? 0,
+        y: d["y"]?.intValue ?? 0,
+        width: d["width"]?.intValue ?? 0,
+        height: d["height"]?.intValue ?? 0,
+        imageWidth: d["imageWidth"]?.intValue ?? 0,
+        imageHeight: d["imageHeight"]?.intValue ?? 0
+      )
+    } catch let nsError as NSError {
+      throw StitcherError.fromNSError(nsError)
+    }
+  }
+
+  /// v0.15 debug — crop the image to an explicit rectangle (overwrite
+  /// in place) and re-encode at `quality`.  Pairs with the
+  /// computeInscribedRect debug harness.
+  public static func cropToRect(
+    imagePath: String,
+    x: Int,
+    y: Int,
+    width: Int,
+    height: Int,
+    quality: Int
+  ) throws -> (width: Int, height: Int) {
+    do {
+      let d = try OpenCVStitcher.cropToRect(
+        atPath: imagePath,
+        x: x,
+        y: y,
+        width: width,
+        height: height,
+        quality: quality
+      )
+      return (width: d["width"]?.intValue ?? 0, height: d["height"]?.intValue ?? 0)
+    } catch let nsError as NSError {
+      throw StitcherError.fromNSError(nsError)
+    }
+  }
+
+  /// v0.15 debug — write a red-tinted mask overlay (excluded pixels =
+  /// red) next to the image and report what fraction the brightness mask
+  /// drops. Pairs with the inscribed-rect debug harness.
+  public static func debugMaskOverlay(
+    imagePath: String,
+    threshold: Int
+  ) throws -> (maskPath: String, width: Int, height: Int, excludedPercent: Int) {
+    do {
+      let d = try OpenCVStitcher.debugMaskOverlay(atPath: imagePath, threshold: threshold)
+      return (
+        maskPath: d["maskPath"] as? String ?? "",
+        width: (d["width"] as? NSNumber)?.intValue ?? 0,
+        height: (d["height"] as? NSNumber)?.intValue ?? 0,
+        excludedPercent: (d["excludedPercent"] as? NSNumber)?.intValue ?? 0
+      )
+    } catch let nsError as NSError {
+      throw StitcherError.fromNSError(nsError)
+    }
+  }
+
   /// Combined pipeline: extract frames from a recorded video,
   /// stitch them into a panorama, write the result to
   /// `options.outputPath`.  Used by the host app's tap-and-hold
@@ -202,38 +268,21 @@ public enum Stitcher {
   /// All temp frame extraction lives in /tmp and is torn down by
   /// the ObjC layer regardless of success or failure.
   public static func stitchVideo(
-    _ options: StitchVideoOptions,
-    poses: [[String: Any]]? = nil
+    _ options: StitchVideoOptions
   ) throws -> StitchResult {
     do {
-      let result: RNStitchResult
-      if let poses = poses, !poses.isEmpty {
-        // Phase 5: pose-driven path.  Skips features → matching →
-        // BundleAdjuster on the native side; cv::detail::CameraParams
-        // come straight from the ARKit poses with the appropriate
-        // coordinate-system flip (Y-up → Y-down, -Z → +Z).
-        result = try OpenCVStitcher.stitchVideo(
-          atPath: options.videoPath,
-          outputPath: options.outputPath,
-          maxFrames: options.maxFrames,
-          jpegQuality: options.jpegQuality,
-          warperType: options.warperType,
-          blenderType: options.blenderType,
-          seamFinderType: options.seamFinderType,
-          poses: poses
-        )
-      } else {
-        // Existing feature-matched path.
-        result = try OpenCVStitcher.stitchVideo(
-          atPath: options.videoPath,
-          outputPath: options.outputPath,
-          maxFrames: options.maxFrames,
-          jpegQuality: options.jpegQuality,
-          warperType: options.warperType,
-          blenderType: options.blenderType,
-          seamFinderType: options.seamFinderType
-        )
-      }
+      // The pose-driven video stitch (the old native `withPoses:`
+      // path) was archived in the 2026-06 batch-keyframe cleanup;
+      // this now always runs the feature-matched compose.
+      let result = try OpenCVStitcher.stitchVideo(
+        atPath: options.videoPath,
+        outputPath: options.outputPath,
+        maxFrames: options.maxFrames,
+        jpegQuality: options.jpegQuality,
+        warperType: options.warperType,
+        blenderType: options.blenderType,
+        seamFinderType: options.seamFinderType
+      )
       return StitchResult(
         outputPath: result.outputPath,
         width: result.width,

package/ios/Sources/RNImageStitcher/StitcherBridge.m

@@ -25,4 +25,17 @@ RCT_EXTERN_METHOD(normaliseOrientation:(NSDictionary *)options
                   resolver:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 
+// v0.15 debug harness (inscribed-rect visualisation in the example app).
+RCT_EXTERN_METHOD(computeInscribedRect:(NSDictionary *)options
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+RCT_EXTERN_METHOD(cropToRect:(NSDictionary *)options
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
+RCT_EXTERN_METHOD(debugMaskOverlay:(NSDictionary *)options
+                  resolver:(RCTPromiseResolveBlock)resolver
+                  rejecter:(RCTPromiseRejectBlock)rejecter)
+
 @end

package/ios/Sources/RNImageStitcher/StitcherBridge.swift

@@ -95,10 +95,6 @@ public class StitcherBridge: NSObject {
     let warperType = (options["warperType"] as? String) ?? "plane"
     let blenderType = (options["blenderType"] as? String) ?? "multiband"
     let seamFinderType = (options["seamFinderType"] as? String) ?? "graphcut"
-    // Optional pose log from the host's RNSARSession snapshot.
-    // When present and non-empty, the native stitcher routes to the
-    // pose-driven path (skips features → matching → BA).
-    let poses = options["poses"] as? [[String: Any]]
 
     let stitchOpts = StitchVideoOptions(
       videoPath: videoPath,
@@ -112,7 +108,7 @@ public class StitcherBridge: NSObject {
 
     DispatchQueue.global(qos: .userInitiated).async {
       do {
-        let result = try Stitcher.stitchVideo(stitchOpts, poses: poses)
+        let result = try Stitcher.stitchVideo(stitchOpts)
         resolver([
           "outputPath": result.outputPath,
           "width": result.width,
@@ -179,6 +175,137 @@ public class StitcherBridge: NSObject {
     }
   }
 
+  /// v0.15 debug — compute the max-inscribed rectangle of `imagePath`
+  /// without modifying it.  Resolves
+  /// `{ x, y, width, height, imageWidth, imageHeight }`.
+  @objc(computeInscribedRect:resolver:rejecter:)
+  public func computeInscribedRect(
+    options: NSDictionary,
+    resolver: @escaping RCTPromiseResolveBlock,
+    rejecter: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let imagePath = options["imagePath"] as? String else {
+      rejecter("invalid-options", "imagePath must be a string", nil)
+      return
+    }
+    DispatchQueue.global(qos: .userInitiated).async {
+      do {
+        let r = try Stitcher.computeInscribedRect(imagePath: imagePath)
+        resolver([
+          "x": r.x,
+          "y": r.y,
+          "width": r.width,
+          "height": r.height,
+          "imageWidth": r.imageWidth,
+          "imageHeight": r.imageHeight,
+        ])
+      } catch let err as StitcherError {
+        switch err {
+        case .insufficientFrames(let count):
+          rejecter("insufficient-frames", "(unexpected for computeInscribedRect) frames=\(count)", err)
+        case .readFailed(let path):
+          rejecter("read-failed", "Could not read image: \(path)", err)
+        case .writeFailed(let path):
+          rejecter("write-failed", "Could not write image: \(path)", err)
+        case .opencvFailed(let code, let message):
+          rejecter("opencv-failed-\(code)", message, err)
+        }
+      } catch {
+        rejecter("unknown", "Unexpected computeInscribedRect failure: \(error)", error)
+      }
+    }
+  }
+
+  /// v0.15 debug — crop `imagePath` to the rectangle in `options`
+  /// (`x`, `y`, `width`, `height`) at `quality` (default 90), overwriting
+  /// in place.  Resolves the final `{ width, height }`.
+  @objc(cropToRect:resolver:rejecter:)
+  public func cropToRect(
+    options: NSDictionary,
+    resolver: @escaping RCTPromiseResolveBlock,
+    rejecter: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let imagePath = options["imagePath"] as? String else {
+      rejecter("invalid-options", "imagePath must be a string", nil)
+      return
+    }
+    let x = (options["x"] as? NSNumber)?.intValue ?? 0
+    let y = (options["y"] as? NSNumber)?.intValue ?? 0
+    let width = (options["width"] as? NSNumber)?.intValue ?? 0
+    let height = (options["height"] as? NSNumber)?.intValue ?? 0
+    let quality = (options["quality"] as? NSNumber)?.intValue ?? 90
+    DispatchQueue.global(qos: .userInitiated).async {
+      do {
+        let dims = try Stitcher.cropToRect(
+          imagePath: imagePath,
+          x: x,
+          y: y,
+          width: width,
+          height: height,
+          quality: quality
+        )
+        resolver([
+          "width": dims.width,
+          "height": dims.height,
+        ])
+      } catch let err as StitcherError {
+        switch err {
+        case .insufficientFrames(let count):
+          rejecter("insufficient-frames", "(unexpected for cropToRect) frames=\(count)", err)
+        case .readFailed(let path):
+          rejecter("read-failed", "Could not read image: \(path)", err)
+        case .writeFailed(let path):
+          rejecter("write-failed", "Could not write image: \(path)", err)
+        case .opencvFailed(let code, let message):
+          rejecter("opencv-failed-\(code)", message, err)
+        }
+      } catch {
+        rejecter("unknown", "Unexpected cropToRect failure: \(error)", error)
+      }
+    }
+  }
+
+  /// v0.15 debug — write a red-tinted mask overlay for `imagePath`
+  /// (excluded pixels red). `threshold` optional (default 1, matching the
+  /// inscribed-rect mask). Resolves
+  /// `{ maskPath, width, height, excludedPercent }`.
+  @objc(debugMaskOverlay:resolver:rejecter:)
+  public func debugMaskOverlay(
+    options: NSDictionary,
+    resolver: @escaping RCTPromiseResolveBlock,
+    rejecter: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let imagePath = options["imagePath"] as? String else {
+      rejecter("invalid-options", "imagePath must be a string", nil)
+      return
+    }
+    let threshold = (options["threshold"] as? NSNumber)?.intValue ?? 1
+    DispatchQueue.global(qos: .userInitiated).async {
+      do {
+        let r = try Stitcher.debugMaskOverlay(imagePath: imagePath, threshold: threshold)
+        resolver([
+          "maskPath": r.maskPath,
+          "width": r.width,
+          "height": r.height,
+          "excludedPercent": r.excludedPercent,
+        ])
+      } catch let err as StitcherError {
+        switch err {
+        case .insufficientFrames(let count):
+          rejecter("insufficient-frames", "(unexpected for debugMaskOverlay) frames=\(count)", err)
+        case .readFailed(let path):
+          rejecter("read-failed", "Could not read image: \(path)", err)
+        case .writeFailed(let path):
+          rejecter("write-failed", "Could not write image: \(path)", err)
+        case .opencvFailed(let code, let message):
+          rejecter("opencv-failed-\(code)", message, err)
+        }
+      } catch {
+        rejecter("unknown", "Unexpected debugMaskOverlay failure: \(error)", error)
+      }
+    }
+  }
+
   @objc(stitch:resolver:rejecter:)
   public func stitch(
     options: NSDictionary,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,10 +25,11 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "jest",
     "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test",
     "postinstall": "node scripts/postinstall-fetch-binaries.js"
   },
   "keywords": [

package/src/ar/useARSession.ts

@@ -69,6 +69,15 @@ export interface UseARSessionReturn {
    * older iPhones, simulators, and unsupported Android devices.
    */
   isAvailable: boolean;
+  /**
+   * Whether the one-shot `isSupported()` probe has resolved (success OR
+   * failure).  `false` only during the brief async window right after
+   * mount; `true` thereafter.  Lets consumers distinguish "AR not
+   * supported" (probed && !isAvailable) from "support not yet known"
+   * (!probed), so they don't prematurely mount the non-AR camera and
+   * lose a camera-handoff race when AR is the intended source.
+   */
+  supportProbed: boolean;
   /**
    * Whether the session is currently running.  True between
    * `start()` and `stop()`.
@@ -128,6 +137,7 @@ const STATE_POLL_INTERVAL_MS = 500;
 
 export function useARSession(): UseARSessionReturn {
   const [isAvailable, setIsAvailable] = useState(false);
+  const [supportProbed, setSupportProbed] = useState(false);
   const [isRunning, setIsRunning] = useState(false);
   const [trackingState, setTrackingState] = useState<ARTrackingState>(
     ARTrackingState.NotAvailable,
@@ -140,11 +150,30 @@ export function useARSession(): UseARSessionReturn {
   // AR support shouldn't crash anything — `isAvailable` stays
   // false and the rest of the SDK falls back to vision-camera.
   useEffect(() => {
-    if (!native) return;
-    native.isSupported().then(setIsAvailable).catch((err) => {
-      // eslint-disable-next-line no-console
-      console.warn('[useARSession] isSupported failed', err);
-    });
+    if (!native) {
+      // No native module at all — treat the probe as resolved
+      // (unsupported) so consumers don't wait forever for AR.
+      setSupportProbed(true);
+      return;
+    }
+    let cancelled = false;
+    native
+      .isSupported()
+      .then((ok) => {
+        if (!cancelled) setIsAvailable(ok);
+      })
+      .catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn('[useARSession] isSupported failed', err);
+      })
+      .finally(() => {
+        // Mark the probe resolved either way so the non-AR fallback
+        // (or AR mount) can proceed exactly once support is known.
+        if (!cancelled) setSupportProbed(true);
+      });
+    return () => {
+      cancelled = true;
+    };
   }, [native]);
 
   const stopPolling = useCallback(() => {
@@ -200,6 +229,7 @@ export function useARSession(): UseARSessionReturn {
 
   return {
     isAvailable,
+    supportProbed,
     isRunning,
     trackingState,
     start,

package/src/camera/Camera.tsx

@@ -242,6 +242,11 @@ export interface CameraProps {
   defaultFlowMaxTranslationCm?: number;
   defaultKeyframeMaxCount?: number;
   defaultKeyframeOverlapThreshold?: number;
+  /** Time-budget force-accept (ms) for the keyframe gate — accept a
+   *  keyframe at least this often during a pan even if novelty is low,
+   *  so slow / static pans don't leave temporal gaps.  `0` disables it.
+   *  Default 2000 (2 s).  Applies to both AR and non-AR captures. */
+  defaultMaxKeyframeIntervalMs?: number;
   /** Forward-looking — wires through to cv::Stitcher's compositingResol
    *  once PanoramaSettings exposes the field (currently a no-op). */
   defaultCompositingResolMP?: number;
@@ -250,6 +255,28 @@ export interface CameraProps {
   /** Forward-looking — see above. */
   defaultSeamEstimationResolMP?: number;
 
+  // ── Inscribed-rect crop (v0.15) ───────────────────────────────────
+  /**
+   * Crop strategy for the stitched panorama. `false` (default) keeps the
+   * bounding-rect of non-black pixels, which preserves all stitched
+   * content but may leave black corners. `true` crops to the maximum
+   * axis-aligned rectangle inscribed in the coverage mask — clean edges,
+   * no black corners (slightly more CPU at finalize) — but it can shrink
+   * the output substantially on lopsided / ultra-wide masks, which is why
+   * it's opt-in.
+   *
+   * Implemented as a start-time stitcher config (like the other
+   * stitcher settings), so this value is read once at mount to seed the
+   * initial setting; the in-app settings modal can override it at
+   * runtime. It changes image geometry (the crop), not encoding.
+   *
+   * Since the default is `false`, only pass this prop to opt in:
+   * @example
+   * // Crop to a clean inscribed rectangle (no black corners):
+   * <Camera maxInscribedRectCrop={true} />
+   */
+  maxInscribedRectCrop?: boolean;
+
   // ── UI knobs ──────────────────────────────────────────────────────
   enablePhotoMode?: boolean;
   enablePanoramaMode?: boolean;
@@ -270,27 +297,13 @@ export interface CameraProps {
   style?: StyleProp<ViewStyle>;
 
   /**
-   * Which incremental stitcher engine to drive.  Default
-   * `'batch-keyframe'` — collects accepted JPEGs and runs
-   * `cv::Stitcher` once at finalize time.  This is the v0.4+
-   * production default and what the v0.5 Frame Processor migration
-   * exercises.
-   *
-   * Switch to a live engine (`'firstwins-rectilinear'` or
-   * `'hybrid'`) for low-latency in-flight stitching.  Live engines
-   * exercise the F8.6 pixel-buffer ingest path (skipping the JPEG
-   * encode/decode round-trip; ~30–50 ms saved per accept) when the
-   * Frame Processor driver is active.
-   *
-   * See `docs/f8-frame-processor-plan.md` and the v0.5.0
-   * CHANGELOG for the trade-offs between batch-keyframe and live
-   * engines.
+   * Which stitcher engine to drive.  Only `'batch-keyframe'` is
+   * supported (and the default): it collects accepted keyframe JPEGs
+   * during the hold-pan-release capture and runs the stitch once at
+   * finalize.  The live engines (hybrid / slit-scan / firstwins) were
+   * archived in the batch-keyframe cleanup — see `archive/`.
    */
-  engine?: 'batch-keyframe'
-    | 'hybrid'
-    | 'slitscan-rotate' | 'slitscan-both'
-    | 'firstwins' | 'firstwins-zoomed' | 'firstwins-rectilinear'
-    | 'slitscan';
+  engine?: 'batch-keyframe';
 
   /**
    * Optional destination directory for captures.  When set, the lib
@@ -865,6 +878,8 @@ function extractPanoramaOverrides(props: CameraProps): PanoramaPropOverrides {
     defaultFlowMaxTranslationCm: props.defaultFlowMaxTranslationCm,
     defaultKeyframeMaxCount: props.defaultKeyframeMaxCount,
     defaultKeyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold,
+    defaultMaxKeyframeIntervalMs: props.defaultMaxKeyframeIntervalMs,
+    maxInscribedRectCrop: props.maxInscribedRectCrop,
   };
 }
 
@@ -979,7 +994,8 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // (older iPhones, ARCore-less Androids, simulators) stay `false`
   // forever, which forces non-AR capture everywhere and hides the
   // AR toggle in the bottom bar (see JSX below).
-  const { isAvailable: isARSupportedOnDevice } = useARSession();
+  const { isAvailable: isARSupportedOnDevice, supportProbed: isARSupportProbed } =
+    useARSession();
 
   const effectiveCaptureSource = deriveEffectiveCaptureSource(
     arPreference,
@@ -988,6 +1004,23 @@ export function Camera(props: CameraProps): React.JSX.Element {
   );
   const isAR = effectiveCaptureSource === 'ar';
   const isNonAR = !isAR;
+
+  // v0.14.2 — camera-handoff race guard.  While AR is the preferred
+  // source but the one-shot `isSupported()` probe hasn't resolved yet,
+  // `deriveEffectiveCaptureSource` returns 'non-ar' (because
+  // `isARSupportedOnDevice` is still false), which would mount
+  // <CameraView> and let vision-camera's AVCaptureSession grab the
+  // camera.  The switch to AR ~200-500ms later then fails with ARKit
+  // "Required sensor failed" (ARKit and AVCaptureSession can't share the
+  // camera), leaving a blank AR preview — intermittent and timing-
+  // dependent.  Defer the initial mount until the probe settles: while
+  // pending we render the "Switching camera…" placeholder instead of any
+  // camera, so vision-camera never contends for the device when AR is the
+  // intent.  Conditions mirror deriveEffectiveCaptureSource's own
+  // non-support gates (arPreference, lens) so this is true in exactly the
+  // cases that resolve to AR once support is confirmed.
+  const arSupportPending =
+    arPreference && lens !== '0.5x' && !isARSupportProbed;
   const deviceOrientation = useDeviceOrientation();
 
   // v0.13.1 — counter-rotation for control CONTENT (AR toggle, lens
@@ -1415,6 +1448,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         width = result.width;
         height = result.height;
       }
+
       onCapture?.({ type: 'photo', uri, width, height });
     } catch (err) {
       const e = err instanceof CameraError
@@ -1558,7 +1592,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         isNonAR ? imuGate.getTotalAbsMetres() : 0;
       const result = await incremental.finalize(
         panoOutputPath,
-        90,
+        90, // default JPEG quality
         deviceOrientation,
         imuTotalTranslationM,
       );
@@ -1572,6 +1606,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
           included: result.framesIncluded,
         });
       }
+
       onCapture?.({
         type: 'panorama',
         // Native finalize() returns a bare `/data/.../foo.jpg` path;
@@ -1597,7 +1632,11 @@ export function Camera(props: CameraProps): React.JSX.Element {
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       const code: CameraErrorCode =
-        /need more images/i.test(message) ? 'STITCH_NEED_MORE_IMGS'
+        // Insufficient overlap surfaces two ways: cv::Stitcher's
+        // ERR_NEED_MORE_IMGS ("need more images") and the manual
+        // pipeline's "0 valid pairwise matches / frames may not overlap
+        // enough" — both are the same recoverable "pan more slowly" case.
+        /need more images|pairwise match|overlap enough/i.test(message) ? 'STITCH_NEED_MORE_IMGS'
         : /homography/i.test(message) ? 'STITCH_HOMOGRAPHY_FAIL'
         : /camera params/i.test(message) ? 'STITCH_CAMERA_PARAMS_FAIL'
         : /out of memory|oom/i.test(message) ? 'STITCH_OOM'
@@ -1690,7 +1729,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
           only ONE camera component is alive at a time; matches the
           monorepo's working pattern and avoids the Camera2-in-use
           conflict that "always mount both" caused on Android. */}
-      {inFlightTransition ? (
+      {inFlightTransition || arSupportPending ? (
         <View style={[StyleSheet.absoluteFill, styles.transitionPlaceholder]}>
           <Text style={styles.transitionLabel}>Switching camera…</Text>
         </View>