react-native-image-stitcher 0.14.2 → 0.15.1

package/ios/Sources/RNImageStitcher/RNSARCameraView.swift

@@ -54,7 +54,10 @@ public final class RNSARCameraView: UIView {
 
     private func setupView() {
         arSCNView = ARSCNView(frame: bounds)
-        arSCNView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        // Do NOT set autoresizingMask — we manage the ARSCNView frame
+        // manually in layoutSubviews() to achieve letterboxing.
+        // autoresizingMask would fight that and re-expand the view to
+        // fill our bounds on every Auto Layout pass.
 
         // Bind to the singleton's session.  This is the critical
         // line — without it, ARSCNView would try to create its own
@@ -71,18 +74,84 @@ public final class RNSARCameraView: UIView {
         arSCNView.showsStatistics = false
         arSCNView.automaticallyUpdatesLighting = false
 
-        // Black background while ARKit is initialising so the user
-        // sees a clean frame instead of whatever was there before.
+        // Black background: fills the letterbox bars (the areas of
+        // this view outside ARSCNView's letterboxed sub-rect).
         backgroundColor = .black
         addSubview(arSCNView)
     }
 
     public override func layoutSubviews() {
         super.layoutSubviews()
-        // RN's flexbox can re-bound this view at any time; keep the
-        // ARSCNView locked to our bounds.  autoresizingMask handles
-        // most cases but isn't always enough on rotation transitions.
-        arSCNView.frame = bounds
+        // Letterbox the ARSCNView to show the full camera FOV.
+        //
+        // ARSCNView's internal renderer always uses resizeAspectFill
+        // (fills its view, crops if aspect ratios differ).  If we give
+        // it our full bounds (portrait 9:21) and the camera image is
+        // effectively portrait 3:4 (4:3 sensor rotated for device
+        // orientation), it crops ~19% off each horizontal edge —
+        // exactly the "viewport ≠ captured frame" bug.
+        //
+        // Fix: set ARSCNView's frame to the largest rect inside our
+        // bounds that has the camera's content aspect ratio.  When
+        // ARSCNView fills a same-AR sub-rect, there is nothing to crop
+        // and the user sees the full captured scene.  The parent view's
+        // black background fills the remainder.
+        arSCNView.frame = letterboxedFrame()
+    }
+
+    /// Returns the largest `CGRect` inside `bounds` that matches the
+    /// camera's content aspect ratio (accounting for device orientation),
+    /// centred within `bounds`.
+    private func letterboxedFrame() -> CGRect {
+        let aspect = cameraContentAspect()
+        let bw = bounds.width
+        let bh = bounds.height
+        guard bw > 0, bh > 0, aspect > 0 else { return bounds }
+
+        // Try fitting by width first; if height overflows, fit by height.
+        let hByWidth = bw / aspect
+        if hByWidth <= bh {
+            // Content fits within height — horizontal bars top+bottom.
+            let y = (bh - hByWidth) / 2
+            return CGRect(x: 0, y: y, width: bw, height: hByWidth)
+        } else {
+            // Vertical bars left+right.
+            let wByHeight = bh * aspect
+            let x = (bw - wByHeight) / 2
+            return CGRect(x: x, y: 0, width: wByHeight, height: bh)
+        }
+    }
+
+    /// Camera content aspect ratio (W÷H) in the current device orientation.
+    ///
+    /// The ARKit sensor is physically landscape (e.g. 1920 × 1440, aspect 4/3).
+    /// When the device is portrait the ARSCNView displays the scene rotated,
+    /// so the effective content aspect is 3/4.  We invert accordingly so the
+    /// letterboxed frame always reflects what the user is actually looking at.
+    ///
+    /// Source priority:
+    ///   1. `currentFrame.camera.imageResolution` — live, most accurate.
+    ///   2. Active session config's `videoFormat.imageResolution` — stable
+    ///      after `arSession.run(…)` and before the first frame.
+    ///   3. 4:3 hardcoded fallback — correct for every iPhone ARKit camera.
+    private func cameraContentAspect() -> CGFloat {
+        let rawResolution: CGSize? = {
+            if let res = RNSARSession.shared.arSession.currentFrame?.camera.imageResolution {
+                return CGSize(width: res.width, height: res.height)
+            }
+            if let fmt = (RNSARSession.shared.arSession.configuration as? ARWorldTrackingConfiguration)?.videoFormat {
+                return CGSize(width: fmt.imageResolution.width, height: fmt.imageResolution.height)
+            }
+            return nil
+        }()
+
+        // Raw sensor aspect (always landscape > 1 for iPhone cameras).
+        let sensorAspect: CGFloat = rawResolution.map { $0.width / $0.height } ?? (4.0 / 3.0)
+
+        // In portrait mode (view taller than wide) the displayed scene
+        // is effectively portrait → invert the sensor aspect.
+        let deviceIsPortrait = bounds.height > bounds.width
+        return deviceIsPortrait ? (1.0 / sensorAspect) : sensorAspect
     }
 
     public override func didMoveToWindow() {
@@ -99,6 +168,12 @@ public final class RNSARCameraView: UIView {
             if !RNSARSession.shared.isRunning {
                 RNSARSession.shared.start()
             }
+            // Re-layout after session start: the configuration's
+            // videoFormat (and shortly after, currentFrame) are now
+            // available for a more accurate aspect ratio.  On iOS all
+            // ARKit cameras are 4:3 so this is a no-op in practice,
+            // but it keeps the code correct for future configs.
+            setNeedsLayout()
         } else {
             // Removed from window — stop the session.  Don't clear
             // the pose log here; the host explicitly clears between

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.2",
+  "version": "0.15.1",
   "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/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,
   };
 }
 
@@ -884,7 +899,7 @@ function extractPanoramaOverrides(props: CameraProps): PanoramaPropOverrides {
  */
 export function Camera(props: CameraProps): React.JSX.Element {
   const {
-    defaultCaptureSource = 'ar',
+    defaultCaptureSource = 'non-ar',
     defaultLens = '1x',
     captureSources = 'both',
     enablePhotoMode = true,
@@ -1433,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
@@ -1576,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,
       );
@@ -1590,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;
@@ -1615,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'