react-native-image-stitcher 0.5.0 → 0.6.0

package/ios/Sources/RNImageStitcher/IncrementalStitcher.swift

@@ -365,12 +365,12 @@ public final class IncrementalStitcher: NSObject {
     /// F8.3 — gate for `consumeFrameFromPlugin` (the vision-camera
     /// Frame Processor producer-thread entry point).  TRUE only when
     /// the current capture was started with
-    /// `frameSourceMode == "frameProcessor"`.  In any other mode
-    /// (especially the legacy `"jsDriver"` path which feeds via
-    /// `processFrameAtPath`), the plugin would double-feed the
-    /// engine — pixel buffers from the producer thread + JPEG paths
-    /// from the JS interval, racing on the same workQueue — so we
-    /// drop the producer-thread call.
+    /// `frameSourceMode == "frameProcessor"`.  In AR mode
+    /// (`frameSourceMode == "arSession"`) the plugin would double-feed
+    /// the engine alongside ARKit's `consumeFrame` delegate path —
+    /// pixel buffers from the producer thread + pixel buffers from the
+    /// ARSession delegate, racing on the same workQueue — so we drop
+    /// the producer-thread call.
     ///
     /// Set under `stateLock` in `start()`, cleared under `stateLock`
     /// in `cancel()` and `finalize()`, ALSO read under `stateLock`
@@ -476,6 +476,13 @@ public final class IncrementalStitcher: NSObject {
 
     private override init() {
         super.init()
+        // F8.3.H2 — runtime check that Swift's auto-bridged ObjC
+        // selector for `consumeFrameFromPlugin(...)` matches the
+        // selector string the plugin's .mm dispatches.  Asserts in
+        // dev builds; no-ops in release.  See the
+        // `_consumeFrameFromPluginSelectorPin` declaration below for
+        // the full rationale.
+        IncrementalStitcher._verifyConsumeFrameFromPluginSelector()
     }
 
     /// 2026-05-18 (iOS cross-orientation fix) — bridge entry-point
@@ -740,11 +747,13 @@ public final class IncrementalStitcher: NSObject {
         engineMode: String,
         captureOrientation: String = "portrait",
         configOverrides: [String: Any] = [:],
-        // 2026-05-18 (Issue #2 regression fix): "arSession" (default,
-        // legacy) registers as the ARSession's frame consumer.
-        // "jsDriver" skips that registration — frames will come in
-        // via processFrameAtPath instead.  Used by iOS non-AR
-        // captures (the vision-camera + gyro driver path).
+        // 2026-05-18 (Issue #2 regression fix): "arSession" (default)
+        // registers as the ARSession's frame consumer.
+        // "frameProcessor" skips that registration — frames come in
+        // via the vision-camera Frame Processor plugin's
+        // `consumeFrameFromPlugin` path instead.  The pre-v0.6
+        // "jsDriver" mode (push frames in from JS via
+        // processFrameAtPath) has been removed.
         frameSourceMode: String = "arSession"
     ) {
         stateLock.lock()
@@ -940,9 +949,9 @@ public final class IncrementalStitcher: NSObject {
         }
         self.isRunning = true
         // F8.3 — enable the Frame Processor plugin's producer-thread
-        // ingest only for the new "frameProcessor" mode.  Any other
-        // mode (arSession, jsDriver) keeps it OFF; see the ivar's
-        // declaration comment for why.
+        // ingest only for the new "frameProcessor" mode.  AR mode
+        // ("arSession") keeps it OFF; see the ivar's declaration
+        // comment for why.
         self.frameProcessorIngestEnabled = (frameSourceMode == "frameProcessor")
         self.snapshotJpegQuality = max(1, min(100, snapshotJpegQuality))
         self.snapshotEveryNAccepts = max(1, snapshotEveryNAccepts)
@@ -1092,9 +1101,10 @@ public final class IncrementalStitcher: NSObject {
         //                        `stateLock.try()` and corrupting
         //                        the gate's novelty math.
         //                        (Adversarial-review C1.)
-        //   * `jsDriver`       — DO NOT register.  Legacy path uses
-        //                        `processFrameAtPath`; bypasses
-        //                        consumeFrame entirely.
+        //
+        // The pre-v0.6 `jsDriver` mode (which pushed frames via
+        // `processFrameAtPath` and also skipped registration) has
+        // been removed.
         if frameSourceMode == "arSession" {
             RNSARSession.shared.incrementalConsumer = self
         }
@@ -2142,191 +2152,6 @@ public final class IncrementalStitcher: NSObject {
                self.keyframeGate.acceptedCount, self.keyframeGate.maxCount)
     }
 
-    /// Whether the engine is currently in batch-keyframe mode.
-    /// Bridge reads this to decide whether the JS-driven
-    /// `processFrameAtPath` path can use the lightweight
-    /// `addBatchKeyframePath` (path-only) entry below.
-    @objc public var isBatchKeyframeMode: Bool {
-        stateLock.lock()
-        defer { stateLock.unlock() }
-        return batchKeyframeMode
-    }
-
-    /// 2026-05-18 (Issue #2 v2) — JS-driver entry-point for
-    /// batch-keyframe captures.  Mirrors Android's behaviour: the
-    /// caller (JS side via the IncrementalStitcherBridge) hands us a
-    /// JPEG file path that already exists on disk (saved by
-    /// vision-camera's takeSnapshot), plus a synthetic pose derived
-    /// from gyro integration.  We:
-    ///
-    ///   1. Validate state (running + batchKeyframeMode).
-    ///   2. Ask the shared C++ KeyframeGate whether to accept this
-    ///      frame.  Pass `latchedPlane: nil` — non-AR captures have
-    ///      no plane; the C++ gate falls back to a pose-only
-    ///      angular-delta strategy.  We do NOT pass a pixel buffer:
-    ///      the Pose strategy doesn't need one, and avoiding the
-    ///      JPEG → CVPixelBuffer round-trip dodges the iOS
-    ///      orientation bugs that broke Issue 2 v1
-    ///      (UIImage/CGContext Y-flip + EXIF-vs-CGImage dimension
-    ///      mismatch — see the symptom in 2026-05-18 user report).
-    ///   3. If accepted, append the existing path + pose to the
-    ///      finalize-time lists.  No JPEG re-encode — the file on
-    ///      disk IS the keyframe.  `retailens::stitchFramePaths()`
-    ///      at finalize uses `cv::imread` which natively handles
-    ///      EXIF orientation, so the output panorama reads upright.
-    ///   4. Emit the same state-event the AR delegate path emits so
-    ///      the JS live band populates identically.
-    ///
-    /// Architecture note: this is structurally parallel to Android's
-    /// `IncrementalStitcher.kt::processFrameAtPath`
-    /// `batchKeyframeMode` branch (lines 573-627).  A follow-up
-    /// should extract the dispatch (gate-eval + path-append + emit)
-    /// into shared cpp/ so both platforms become 5-line wrappers
-    /// around a single C++ entry point.
-    @objc public func addBatchKeyframePath(
-        path: String,
-        pose: RNSARFramePose
-    ) -> Bool {
-        stateLock.lock()
-        guard self.isRunning, self.batchKeyframeMode else {
-            stateLock.unlock()
-            return false
-        }
-        stateLock.unlock()
-
-        // 2026-05-21 (v0.3) — pixel-aware Flow-strategy evaluation.
-        // Pre-0.3 this was `evaluate(pose:latchedPlane:)` with no pixel
-        // buffer, which forced the C++ gate to silently fall back to
-        // Pose strategy (same bug as Android non-AR; both fixed in
-        // v0.3).  We now decode the JPEG snapshot at `path` to a
-        // single-channel grayscale CVPixelBuffer and pass it through,
-        // so the gate's Flow strategy actually runs sparse-flow
-        // novelty on real image content.
-        //
-        // CGImageSource → CGContext into a OneComponent8 CVPixelBuffer.
-        // ~10-20 ms per snapshot on iPhone 13/16 Pro; well under the
-        // ~250 ms non-AR snapshot interval (~4 FPS cadence).  v0.4
-        // will replace this path entirely by moving non-AR capture to
-        // vision-camera's Frame Processor API (tracked at issue #11).
-        let decision: KeyframeGateDecision
-        if let grayBuffer = Self.decodeJpegToGrayscalePixelBuffer(path: path) {
-            decision = self.keyframeGate.evaluate(
-                pose: pose,
-                latchedPlane: nil,
-                pixelBuffer: grayBuffer
-            )
-        } else {
-            // JPEG decode failed (corrupt file, OOM, etc.).  Fall back
-            // to pose-only so the capture doesn't lock up — matches
-            // the C++ side's defensive grayData==nullptr handling
-            // inside evaluateWithFrame.
-            decision = self.keyframeGate.evaluate(
-                pose: pose,
-                latchedPlane: nil
-            )
-        }
-        if !decision.accept {
-            self.emitKeyframeRejectState(decision: decision)
-            return false
-        }
-
-        // Append path + pose to the finalize lists.  Take the lock
-        // briefly — these mutate state read by `finalize()`.
-        stateLock.lock()
-        self.keyframePaths.append(path)
-        self.keyframePoses.append(pose.asDictionary())
-        // 2026-05-22 (audit F2) — track first + last pose for the
-        // stitchMode auto-resolver.  iOS parity: Android records
-        // these in IncrementalStitcher.kt at the same accept points.
-        let poseArr = [pose.tx, pose.ty, pose.tz,
-                       pose.qx, pose.qy, pose.qz, pose.qw]
-        if self.batchFirstAcceptedPose == nil { self.batchFirstAcceptedPose = poseArr }
-        self.batchLastAcceptedPose = poseArr
-        let count = self.keyframePaths.count
-        stateLock.unlock()
-        os_log(.fault, log: Self.diagLog,
-               "[V16-batch-keyframe.js] accepted path #%d → %{public}@",
-               Int32(count), path)
-        self.emitBatchKeyframeAcceptedState(
-            thumbnailPath: path,
-            keyframeIndex: count - 1,
-            keyframeCount: count,
-            keyframeMax: self.keyframeGate.maxCount,
-            isLandscape: pose.imageWidth >= pose.imageHeight
-        )
-        return true
-    }
-
-    /// 2026-05-21 (v0.3) — decode a JPEG file at the given path into a
-    /// single-channel grayscale CVPixelBuffer (`kCVPixelFormatType_-
-    /// OneComponent8`) suitable for feeding into the C++ KeyframeGate's
-    /// Flow-strategy evaluate path.  The bridge's `evaluatePixelBuffer:`
-    /// has explicit OneComponent8 handling (added in v0.3) that reads
-    /// the base address as the Y plane directly, so no extra conversion
-    /// happens on the C++ side.
-    ///
-    /// Used by `addBatchKeyframePath` (the JS-driver non-AR path) so the
-    /// Flow strategy actually runs on real pixel data — pre-0.3 this
-    /// path called `evaluate(pose:latchedPlane:)` with no buffer and
-    /// the C++ side silently fell back to Pose strategy.
-    ///
-    /// Performance: ~10-20 ms for a 1920×1080 JPEG on iPhone 13/16 Pro.
-    /// Well under the ~250 ms non-AR snapshot interval (~4 FPS).
-    /// v0.4 will replace this path entirely via Frame Processor — see
-    /// issue #11.
-    ///
-    /// Returns nil on any failure (file missing, corrupt JPEG, OOM
-    /// on the CVPixelBufferCreate).  Callers fall back to the
-    /// pose-only evaluate so the capture doesn't lock up.
-    private static func decodeJpegToGrayscalePixelBuffer(
-        path: String
-    ) -> CVPixelBuffer? {
-        let url = URL(fileURLWithPath: path)
-        guard let imageSource = CGImageSourceCreateWithURL(url as CFURL, nil),
-              let cgImage = CGImageSourceCreateImageAtIndex(imageSource, 0, nil)
-        else {
-            return nil
-        }
-        let width = cgImage.width
-        let height = cgImage.height
-
-        var pixelBuffer: CVPixelBuffer?
-        let attrs: NSDictionary = [
-            kCVPixelBufferIOSurfacePropertiesKey: NSDictionary(),
-        ]
-        let status = CVPixelBufferCreate(
-            kCFAllocatorDefault,
-            width, height,
-            kCVPixelFormatType_OneComponent8,
-            attrs,
-            &pixelBuffer
-        )
-        guard status == kCVReturnSuccess, let buffer = pixelBuffer else {
-            return nil
-        }
-
-        CVPixelBufferLockBaseAddress(buffer, [])
-        defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
-        guard let baseAddress = CVPixelBufferGetBaseAddress(buffer) else {
-            return nil
-        }
-        let bytesPerRow = CVPixelBufferGetBytesPerRow(buffer)
-        let colorSpace = CGColorSpaceCreateDeviceGray()
-        guard let context = CGContext(
-            data: baseAddress,
-            width: width,
-            height: height,
-            bitsPerComponent: 8,
-            bytesPerRow: bytesPerRow,
-            space: colorSpace,
-            bitmapInfo: CGImageAlphaInfo.none.rawValue
-        ) else {
-            return nil
-        }
-        context.draw(cgImage, in: CGRect(x: 0, y: 0, width: width, height: height))
-        return buffer
-    }
-
     /// V16 Phase 1 — emit a state event when a batch-keyframe is
     /// saved.  Carries the on-disk thumbnail path so JS can render it
     /// in LiveFrameStrip + advance the "Keyframes: N/M" pill.
@@ -3112,14 +2937,15 @@ extension IncrementalStitcher: ARFrameConsumer {}
 //   * `pixelBuffer` from `frame.buffer` (vision-camera YUV biplanar)
 //   * `tx`/`ty`/`tz` = 0 (no AR translation; gyro only gives rotation)
 //   * `qx,qy,qz,qw` from JS-thread gyro-integrated yaw+pitch (synthesised
-//     as `q = q_yaw * q_pitch` — same convention as
-//     `useIncrementalJSDriver`'s pose synthesis)
+//     as `q = q_yaw * q_pitch`).  `useFrameProcessorDriver` and (pre-v0.6)
+//     `useIncrementalJSDriver` both produced quaternions with this layout.
 //   * `fx`/`fy` from frame dims + assumed FoV
 //   * `cx`/`cy` at image centre
 //   * `trackingStateRaw = 2` (= `.tracking`) — non-AR captures don't have
 //     a real ARKit tracking-quality signal; reporting `.tracking` keeps
-//     the engine's `trackingPoor` path inactive, matching the legacy
-//     `useIncrementalJSDriver` contract.
+//     the engine's `trackingPoor` path inactive.  Both the v0.6+
+//     `useFrameProcessorDriver` and the pre-v0.6 `useIncrementalJSDriver`
+//     follow(ed) this contract.
 extension IncrementalStitcher {
     @objc public func consumeFrameFromPlugin(
         pixelBuffer: CVPixelBuffer,
@@ -3158,4 +2984,57 @@ extension IncrementalStitcher {
         )
         consumeFrame(pixelBuffer: pixelBuffer, pose: pose)
     }
+
+    // F8.3.H2 — compile-time + runtime guard for the Swift⇄ObjC
+    // selector contract that `KeyframeGateFrameProcessor.mm`
+    // depends on.
+    //
+    // The .mm file forward-declares `IncrementalStitcher` and
+    // dispatches `[shared consumeFrameFromPluginWithPixelBuffer:tx:
+    // …:trackingStateRaw:]` by NAME — ObjC's late-binding means
+    // signature drift would silently link but crash at runtime
+    // with `NSInvalidArgumentException: unrecognized selector`
+    // on the first non-AR frame.
+    //
+    // This `#selector(...)` reference forces the Swift compiler
+    // to resolve the exact method signature.  If anyone renames a
+    // parameter label or adds/removes an argument, the
+    // `_consumeFrameFromPluginSelectorPin` expression fails to
+    // compile — the SDK won't build until the .mm's forward
+    // declaration is updated to match.  Stronger guarantee than a
+    // test that needs iOS-Simulator infrastructure to run.
+    //
+    // The runtime check below additionally pins the exact
+    // SELECTOR STRING the .mm dispatches.  In dev/debug builds it
+    // asserts; in release builds it's a no-op (the static let is
+    // initialised lazily and never read otherwise, so the runtime
+    // cost is one-time + tiny).  Drift between Swift's auto-
+    // generated selector name and the .mm's expected string
+    // (e.g., if Swift's bridging rules change) trips the assert.
+    private static let _consumeFrameFromPluginSelectorPin: Selector =
+        #selector(IncrementalStitcher.consumeFrameFromPlugin(
+            pixelBuffer:
+            tx: ty: tz:
+            qx: qy: qz: qw:
+            fx: fy: cx: cy:
+            imageWidth: imageHeight:
+            timestampMs:
+            trackingStateRaw:))
+
+    @inline(never)
+    private static func _verifyConsumeFrameFromPluginSelector() {
+        let expected =
+            "consumeFrameFromPluginWithPixelBuffer:tx:ty:tz:"
+            + "qx:qy:qz:qw:fx:fy:cx:cy:"
+            + "imageWidth:imageHeight:timestampMs:trackingStateRaw:"
+        let actual = NSStringFromSelector(_consumeFrameFromPluginSelectorPin)
+        assert(
+            actual == expected,
+            "Frame Processor selector drift — Swift's auto-bridged "
+            + "ObjC selector for consumeFrameFromPlugin is "
+            + "\(actual) but KeyframeGateFrameProcessor.mm's "
+            + "forward declaration expects \(expected).  Update the "
+            + ".mm to match (or fix the assumption here).",
+        )
+    }
 }

package/ios/Sources/RNImageStitcher/IncrementalStitcherBridge.m

@@ -65,14 +65,6 @@ RCT_EXTERN_METHOD(refinePanorama:(NSDictionary *)options
                   resolver:(RCTPromiseResolveBlock)resolver
                   rejecter:(RCTPromiseRejectBlock)rejecter)
 
-// 2026-05-17 (Issue #2) — iOS non-AR frame ingestion.  JS-side driver
-// hands snapshot file paths + gyro-derived pose to the engine so the
-// live band populates in non-AR mode (parity with Android).  See JS
-// `useIncrementalVisionCameraDriver`.
-RCT_EXTERN_METHOD(processFrameAtPath:(NSDictionary *)options
-                  resolver:(RCTPromiseResolveBlock)resolver
-                  rejecter:(RCTPromiseRejectBlock)rejecter)
-
 // 2026-05-18 (Iss 3) — keyframe storage management.  cleanupKeyframes
 // GCs stale per-session directories under Library/Application Support/
 // Captures; getKeyframeDir returns the active capture's session dir.

package/ios/Sources/RNImageStitcher/IncrementalStitcherBridge.swift

@@ -20,7 +20,6 @@
 import Foundation
 import React
 import os.log
-import ImageIO        // CGImageSource + kCGImagePropertyOrientation for EXIF read in processFrameAtPath
 
 @objc(IncrementalStitcherBridge)
 public final class IncrementalStitcherBridge: RCTEventEmitter {
@@ -75,10 +74,12 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
     /// Resolves with `{ ok: true }`.  Rejects when `frameSourceMode`
     /// (options dict) is 'arSession' (the default) AND the AR session
     /// isn't running — that path needs ARKit to deliver frames.
-    /// When `frameSourceMode` is 'jsDriver' the AR-session check is
-    /// skipped and the engine expects JS to feed frames via
-    /// `processFrameAtPath` (used by iOS non-AR captures since
-    /// 2026-05-18 / Issue #2 regression fix).
+    /// When `frameSourceMode` is 'frameProcessor' the AR-session check
+    /// is skipped and the engine expects the vision-camera Frame
+    /// Processor plugin (`CvFlowGateFrameProcessor`) to feed frames
+    /// via `consumeFrameFromPlugin`.  The pre-v0.6 'jsDriver' mode
+    /// (push frames in from JS via `processFrameAtPath`) has been
+    /// removed.
     @objc(start:resolver:rejecter:)
     public func start(
         options: NSDictionary,
@@ -251,127 +252,6 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
         resolver(["ok": true])
     }
 
-    /// 2026-05-18 (Issue #2 v2) — JS-driven frame ingestion for iOS
-    /// non-AR mode.  Mirrors Android's `processFrameAtPath` exactly:
-    /// the JPEG at `path` is already saved on disk by vision-camera
-    /// in its native EXIF-correct orientation.  We DO NOT decode the
-    /// image here.  Instead:
-    ///
-    ///   - Build a synthetic `RNSARFramePose` from the
-    ///     JS-supplied quaternion + intrinsics (no translation;
-    ///     non-AR captures don't have it).
-    ///   - Hand the path + pose to
-    ///     `IncrementalStitcher.addBatchKeyframePath`, which
-    ///     evaluates the shared-C++ KeyframeGate and (if accepted)
-    ///     records the path in the finalize-time keyframe list +
-    ///     emits the same state event the AR-delegate path emits.
-    ///   - `cv::imread` at finalize handles EXIF orientation
-    ///     natively, so the output panorama reads upright with no
-    ///     iOS-specific orientation handling needed in this bridge.
-    ///
-    /// History: Issue #2 v1 (commit 0e40f17) tried to decode the
-    /// JPEG into a CVPixelBuffer and reuse the existing AR
-    /// `consumeFrame(pixelBuffer:pose:)` path.  That introduced two
-    /// orientation bugs (CGContext Y-flip + UIImage.size vs
-    /// cgImage.width dim swap) → upside-down output AND canvas-
-    /// dimension overflow → OOM crashes (user-reported 2026-05-18).
-    /// Architecturally Android never decoded the image either, so
-    /// the right fix was to mirror that.
-    ///
-    /// `options` keys:
-    ///   - path (NSString, required) — local file path (no file://)
-    ///   - qx, qy, qz, qw (Double, required) — quaternion, JS-side
-    ///     gyro-integrated
-    ///   - fx, fy, cx, cy (Double, required) — intrinsics in sensor px
-    ///   - imageWidth, imageHeight (Int, required)
-    ///   - trackingPoor (Bool, optional, default false)
-    ///   - timestampMs (Double, optional, default = now)
-    ///
-    /// Only batch-keyframe captures are supported on this path right
-    /// now — other engines (hybrid / firstwins) need real pixel data
-    /// during the live phase, which isn't trivially derivable from a
-    /// JPEG path.  Reject with `E_NOT_BATCH_KEYFRAME` so the JS host
-    /// can fall back to the legacy stitchVideo path if needed.
-    @objc(processFrameAtPath:resolver:rejecter:)
-    public func processFrameAtPath(
-        options: NSDictionary,
-        resolver: @escaping RCTPromiseResolveBlock,
-        rejecter: @escaping RCTPromiseRejectBlock
-    ) {
-        guard let pathRaw = options["path"] as? String, !pathRaw.isEmpty else {
-            rejecter("E_NO_PATH", "processFrameAtPath: missing 'path'", nil)
-            return
-        }
-        // Strip optional file:// prefix — JS callers sometimes send
-        // file URIs, native APIs want filesystem paths.
-        let cleanPath = pathRaw.hasPrefix("file://")
-            ? String(pathRaw.dropFirst("file://".count))
-            : pathRaw
-
-        let engine = IncrementalStitcher.shared
-        guard engine.isBatchKeyframeMode else {
-            rejecter("E_NOT_BATCH_KEYFRAME",
-                     "processFrameAtPath only supports batch-keyframe "
-                     + "engine mode on iOS.  Configure "
-                     + "incrementalEngine='batch-keyframe' in start() "
-                     + "options, or fall back to the stitchVideo path.",
-                     nil)
-            return
-        }
-
-        let qx = (options["qx"] as? Double) ?? 0
-        let qy = (options["qy"] as? Double) ?? 0
-        let qz = (options["qz"] as? Double) ?? 0
-        let qw = (options["qw"] as? Double) ?? 1   // identity quat default
-        let fx = (options["fx"] as? Double) ?? 1000.0
-        let fy = (options["fy"] as? Double) ?? 1000.0
-        let cx = (options["cx"] as? Double) ?? 540.0
-        let cy = (options["cy"] as? Double) ?? 960.0
-        let imageWidth = (options["imageWidth"] as? Int) ?? 1080
-        let imageHeight = (options["imageHeight"] as? Int) ?? 1920
-        let trackingPoor = (options["trackingPoor"] as? Bool) ?? false
-        let timestampMs = (options["timestampMs"] as? Double)
-            ?? (Date().timeIntervalSince1970 * 1000.0)
-        let trackingState: RNSARTrackingState =
-            trackingPoor ? .limited : .tracking
-
-        let pose = RNSARFramePose(
-            tx: 0, ty: 0, tz: 0,           // no translation in non-AR
-            qx: qx, qy: qy, qz: qz, qw: qw,
-            fx: fx, fy: fy, cx: cx, cy: cy,
-            imageWidth: imageWidth, imageHeight: imageHeight,
-            timestampMs: timestampMs,
-            trackingState: trackingState
-        )
-
-        // 2026-05-18 (Iss #1 diag) — read EXIF Orientation tag from the
-        // keyframe JPEG before handing it to the engine.  vision-camera
-        // writes a JPEG with an EXIF tag matching the physical capture
-        // orientation (1=no rotation, 3=180°, 6=90°CW, 8=90°CCW).  The
-        // bake-rotation table in cpp/stitcher.cpp assumes the post-imread
-        // Mat is in user-view orientation (post-EXIF apply).  If the EXIF
-        // tag isn't what we expect for a given physical orientation, the
-        // input Mat to cv::Stitcher will be a different shape than the AR
-        // path produces (AR keyframes hardcode EXIF=6, commit 7b828f1) —
-        // which would explain why iOS non-AR landscape captures stitch
-        // but bake the wrong way.  CGImageSource is cheap (metadata-only;
-        // no decode).
-        var exifOrientation: Int = -1
-        if let src = CGImageSourceCreateWithURL(
-            URL(fileURLWithPath: cleanPath) as CFURL, nil
-        ),
-           let props = CGImageSourceCopyPropertiesAtIndex(src, 0, nil) as? [CFString: Any],
-           let o = props[kCGImagePropertyOrientation] as? Int {
-            exifOrientation = o
-        }
-        os_log(.fault, log: OSLog(subsystem: "com.tiger.retailens",
-                                  category: "stitcher.diag"),
-               "[V16-batch-keyframe.js] processFrameAtPath EXIF=%d imageW=%d imageH=%d path=%{public}@",
-               Int32(exifOrientation), Int32(imageWidth), Int32(imageHeight), cleanPath)
-
-        let accepted = engine.addBatchKeyframePath(path: cleanPath, pose: pose)
-        resolver(["ok": true, "accepted": accepted])
-    }
 
     /// 2026-05-18 (Iss 3) — bridge for `cleanupKeyframes`.  See the
     /// Swift method's docstring for behaviour.  Options dict keys:

package/ios/Sources/RNImageStitcher/KeyframeGateFrameProcessor.mm

@@ -140,13 +140,13 @@ static NSInteger kg_argInt(NSDictionary* args, NSString* key, NSInteger defaultV
   // Pose from worklet args.  Defaults are safe non-AR values:
   //   * tx/ty/tz = 0 (no translation in non-AR; gyro only gives rot)
   //   * qw = 1 (identity quaternion if JS hasn't supplied rotation)
-  //   * fx/fy/cx/cy = 0 → JS-driver caller MUST supply these (the
-  //     engine derives FoV from intrinsics; 0 would yield NaN FoV).
-  //     We default the principal point to image centre as a safer
-  //     fallback if only fx/fy are missing.
+  //   * fx/fy/cx/cy = 0 → the Frame Processor worklet caller MUST
+  //     supply these (the engine derives FoV from intrinsics; 0 would
+  //     yield NaN FoV).  We default the principal point to image
+  //     centre as a safer fallback if only fx/fy are missing.
   //   * trackingStateRaw = 2 → `.tracking` (non-AR captures don't
-  //     have a real tracking-quality signal; engine's `trackingPoor`
-  //     path stays inactive, matching legacy `useIncrementalJSDriver`).
+  //     have a real tracking-quality signal; reporting `.tracking`
+  //     keeps the engine's `trackingPoor` path inactive).
   double tx = kg_argDouble(arguments, @"tx", 0.0);
   double ty = kg_argDouble(arguments, @"ty", 0.0);
   double tz = kg_argDouble(arguments, @"tz", 0.0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.5.0",
+  "version": "0.6.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",