react-native-image-stitcher 0.9.0 → 0.11.0

package/ios/Sources/RNImageStitcher/IncrementalStitcher.swift

@@ -1863,12 +1863,27 @@ public final class IncrementalStitcher: NSObject {
         config: [String: Any],
         completion: @escaping ([String: Any]?, NSError?) -> Void
     ) {
+        // v0.10.0 #15A — emit `validating` at the very top so JS sees
+        // refine activity even when validation fails fast.  Frames may
+        // be empty here; report whatever the caller asked for.
+        emitRefineProgress(
+            stage: "validating",
+            fraction: 0.05,
+            frames: framePaths.count,
+            errorMessage: nil
+        )
         guard framePaths.count >= 2 else {
+            let msg = "refinePanorama requires at least 2 framePaths (got \(framePaths.count))."
+            emitRefineProgress(
+                stage: "error",
+                fraction: 1.0,
+                frames: framePaths.count,
+                errorMessage: msg
+            )
             completion(nil, NSError(
                 domain: "RNImageStitcherIncremental",
                 code: 9101,
-                userInfo: [NSLocalizedDescriptionKey:
-                    "refinePanorama requires at least 2 framePaths (got \(framePaths.count))."]
+                userInfo: [NSLocalizedDescriptionKey: msg]
             ))
             return
         }
@@ -1876,11 +1891,17 @@ public final class IncrementalStitcher: NSObject {
         for p in framePaths {
             let cleaned = p.hasPrefix("file://") ? String(p.dropFirst(7)) : p
             if !fm.fileExists(atPath: cleaned) {
+                let msg = "refinePanorama: keyframe missing on disk — \(cleaned)"
+                emitRefineProgress(
+                    stage: "error",
+                    fraction: 1.0,
+                    frames: framePaths.count,
+                    errorMessage: msg
+                )
                 completion(nil, NSError(
                     domain: "RNImageStitcherIncremental",
                     code: 9102,
-                    userInfo: [NSLocalizedDescriptionKey:
-                        "refinePanorama: keyframe missing on disk — \(cleaned)"]
+                    userInfo: [NSLocalizedDescriptionKey: msg]
                 ))
                 return
             }
@@ -1912,7 +1933,18 @@ public final class IncrementalStitcher: NSObject {
                cleanedOutput,
                warper, blender, seam)
 
-        refineQueue.async {
+        // v0.10.0 #15A — capture for the inner closure; `self` is
+        // captured weakly so the progress emitter survives only as
+        // long as the IncrementalStitcher itself does.  An emitter
+        // call on a torn instance is a no-op via `?.`.
+        let frameCount = framePaths.count
+        refineQueue.async { [weak self] in
+            self?.emitRefineProgress(
+                stage: "stitching",
+                fraction: 0.1,
+                frames: frameCount,
+                errorMessage: nil
+            )
             // C2-style: closure captures only value-typed locals
             // (paths, output path, config strings).  No `self` access
             // is needed for the cv::Stitcher call — OpenCVStitcher is
@@ -1935,24 +1967,53 @@ public final class IncrementalStitcher: NSObject {
                 // OpenCVStitcher hit one of its six guarded failure
                 // returns; surface as a clean NSError.
                 if r.width == 0 && r.height == 0 {
+                    let msg = "refinePanorama: stitcher returned sentinel — see preceding [BatchStitcher] log for cause."
+                    self?.emitRefineProgress(
+                        stage: "error",
+                        fraction: 1.0,
+                        frames: frameCount,
+                        errorMessage: msg
+                    )
                     completion(nil, NSError(
                         domain: "RNImageStitcherIncremental",
                         code: 9107,
-                        userInfo: [NSLocalizedDescriptionKey:
-                            "refinePanorama: stitcher returned sentinel — see preceding [BatchStitcher] log for cause."]
+                        userInfo: [NSLocalizedDescriptionKey: msg]
                     ))
                     return
                 }
+                // Stitch succeeded — OpenCVStitcher writes the JPEG
+                // internally before returning, so "writing" really
+                // captures the final assembly + file I/O cost.  Emit
+                // here so JS can flip its label from "Stitching" to
+                // "Writing" before the done event fires.
+                self?.emitRefineProgress(
+                    stage: "writing",
+                    fraction: 0.9,
+                    frames: frameCount,
+                    errorMessage: nil
+                )
+                self?.emitRefineProgress(
+                    stage: "done",
+                    fraction: 1.0,
+                    frames: frameCount,
+                    errorMessage: nil
+                )
                 completion([
                     "panoramaPath": r.outputPath,
                     "width": Int(r.width),
                     "height": Int(r.height),
-                    "framesRequested": framePaths.count,
-                    "framesIncluded": framePaths.count,
+                    "framesRequested": frameCount,
+                    "framesIncluded": frameCount,
                     "framesDropped": 0,
                     "finalConfidenceThresh": -1.0,
                 ], nil)
             } catch let err as NSError {
+                self?.emitRefineProgress(
+                    stage: "error",
+                    fraction: 1.0,
+                    frames: frameCount,
+                    errorMessage: err.localizedDescription
+                )
                 completion(nil, err)
             }
         }
@@ -2092,6 +2153,74 @@ public final class IncrementalStitcher: NSObject {
         )
     }
 
+    /// v0.10.0 #15A — emit a refine-pipeline phase update on the same
+    /// `IncrementalStateUpdate` channel that carries `isRefining` /
+    /// `refinedPanoramaPath`.  Five `stage` values fire across the
+    /// lifetime of one `refinePanorama` call:
+    ///
+    ///   - `validating` (fraction 0.05) — synchronous input checks
+    ///   - `stitching`  (fraction 0.10) — start of the OpenCV stitch
+    ///   - `writing`    (fraction 0.90) — stitch returned, JPEG written
+    ///   - `done`       (fraction 1.00) — completion handler invoked
+    ///   - `error`      (fraction 1.00) — failure path (`errorMessage`
+    ///                                    is non-nil)
+    ///
+    /// `fraction` is intentionally coarse: OpenCV's `Stitcher` doesn't
+    /// expose stage-by-stage callbacks, so the 0.10 → 0.90 jump is a
+    /// single opaque step.  JS uses the `stage` string for the UI
+    /// label and `fraction` purely for spinner progress.
+    ///
+    /// Reuses the existing channel (rather than introducing a new
+    /// device-event name) so the JS subscriber doesn't need to wire
+    /// a second listener.  The payload carries the same skeleton
+    /// `emitRefinementState` emits (lastState fields preserved) so
+    /// `isRefining` / `refinedPanoramaPath` sticky-merge logic on the
+    /// JS side keeps working untouched.
+    private func emitRefineProgress(
+        stage: String,
+        fraction: Double,
+        frames: Int?,
+        errorMessage: String?
+    ) {
+        // Disk-trail breadcrumb — every refine emit lands here so a
+        // future regression can be diagnosed by pulling the bridge's
+        // debug file without needing live Console.app access.
+        IncrementalStitcher.fileLog(
+            "[refine.progress] stage=\(stage) frac=\(fraction) frames=\(frames ?? -1) hasError=\(errorMessage != nil)"
+        )
+        stateLock.lock()
+        let prev = self.lastState
+        stateLock.unlock()
+        let state = IncrementalStateObject(
+            panoramaPath: prev?.panoramaPath,
+            width: prev?.width ?? 0,
+            height: prev?.height ?? 0,
+            acceptedCount: prev?.acceptedCount ?? 0,
+            outcome: prev?.outcome ?? .acceptedHigh,
+            confidence: prev?.confidence ?? 1.0,
+            overlapPercent: prev?.overlapPercent ?? -1.0,
+            processingMs: 0,
+            isLandscape: prev?.isLandscape ?? false,
+            paintedExtent: prev?.paintedExtent ?? 0,
+            panExtent: prev?.panExtent ?? 0,
+            keyframeMax: prev?.keyframeMax ?? 0
+        )
+        var dict = state.asDictionary()
+        dict["refineStage"] = stage
+        dict["refineProgress"] = fraction
+        if let f = frames {
+            dict["refineFrames"] = f
+        }
+        if let e = errorMessage {
+            dict["refineError"] = e
+        }
+        NotificationCenter.default.post(
+            name: .retailensIncrementalStateUpdate,
+            object: nil,
+            userInfo: dict
+        )
+    }
+
     /// Cancel an in-progress capture without producing output.
     /// Same V12.1 synchronous-stop pattern as finalize.
     @objc public func cancel() {

package/ios/Sources/RNImageStitcher/IncrementalStitcherBridge.swift

@@ -33,6 +33,18 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
 
     public override init() {
         super.init()
+        // Under RN bridgeless interop the bridge's init() can be
+        // invoked twice on the same instance (observed via identical
+        // instance pointers firing the observer selector twice per
+        // notification).  Defensively remove any prior registration
+        // for this notification name before adding one, so the
+        // observer can only fire once per post regardless of how
+        // many times init runs.
+        NotificationCenter.default.removeObserver(
+            self,
+            name: .retailensIncrementalStateUpdate,
+            object: nil
+        )
         // Subscribe once at construction.  The handler self-checks
         // `hasListeners` before forwarding, so we don't have to
         // unsubscribe / resubscribe on every JS listener attach/detach.
@@ -58,9 +70,6 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
         return [Self.stateUpdateEvent]
     }
 
-    // (startObserving / stopObserving moved next to handleStateUpdate
-    //  for the PiP investigation; remove this comment after.)
-
     // MARK: - Module methods
 
     /// `options` (all optional, sensible defaults documented in
@@ -477,26 +486,53 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
 
     @objc private func handleStateUpdate(_ notification: Notification) {
         let hasPath = (notification.userInfo?["panoramaPath"] != nil)
-        if hasPath {
+        let refineStage = notification.userInfo?["refineStage"] as? String
+        if hasPath || refineStage != nil {
             IncrementalStitcher.fileLog(
-                "bridge handleStateUpdate hasListeners=\(hasListeners) hasPath=\(hasPath) thread=\(Thread.isMainThread ? "main" : "bg")"
+                "bridge handleStateUpdate hasListeners=\(hasListeners) hasPath=\(hasPath) refineStage=\(refineStage ?? "nil") thread=\(Thread.isMainThread ? "main" : "bg")"
             )
         }
-        guard hasListeners else { return }
+        guard hasListeners else {
+            if let stage = refineStage {
+                IncrementalStitcher.fileLog(
+                    "bridge handleStateUpdate DROPPED refineStage=\(stage) — hasListeners=false"
+                )
+            }
+            return
+        }
         guard let userInfo = notification.userInfo else { return }
-        // FIX: RCTEventEmitter.sendEvent is documented to be called
-        // from any thread, but in practice events from background
-        // threads can be dropped silently if the bridge is in
-        // certain states.  Dispatch to main queue to guarantee
-        // delivery.  See e.g. RN issues #19518, #28250.
+        // We deliver via `bridge.enqueueJSCall("RCTDeviceEventEmitter", "emit", ...)`
+        // rather than `RCTEventEmitter.sendEvent(...)` because under RN
+        // bridgeless interop `sendEvent` silently no-ops for some
+        // event-body shapes even when `_bridge` is non-nil and
+        // `_listenerCount > 0` (confirmed via os_log instrumentation
+        // during v0.10.0 PR B development — refine events with
+        // refineStage/refineProgress/refineFrames were not reaching
+        // any JS subscriber while live state events with a smaller
+        // body shape on the same channel were).  enqueueJSCall is
+        // the underlying mechanism sendEvent uses in Paper mode, so
+        // it is strictly at least as well-supported.
         DispatchQueue.main.async { [weak self] in
             guard let self = self else { return }
-            if hasPath {
+            if hasPath || refineStage != nil {
                 IncrementalStitcher.fileLog(
-                    "bridge sendEvent (main queue) body.panoramaPath=\(userInfo["panoramaPath"] ?? "MISSING")"
+                    "bridge enqueueJSCall (main queue) body.panoramaPath=\(userInfo["panoramaPath"] ?? "MISSING") refineStage=\(refineStage ?? "nil")"
                 )
             }
-            self.sendEvent(withName: Self.stateUpdateEvent, body: userInfo)
+            guard let bridge = self.bridge else {
+                if hasPath || refineStage != nil {
+                    IncrementalStitcher.fileLog(
+                        "bridge enqueueJSCall DROPPED — self.bridge is nil"
+                    )
+                }
+                return
+            }
+            bridge.enqueueJSCall(
+                "RCTDeviceEventEmitter",
+                method: "emit",
+                args: [Self.stateUpdateEvent, userInfo],
+                completion: nil
+            )
         }
     }
 

package/package.json

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

package/src/camera/Camera.tsx

@@ -323,26 +323,42 @@ export interface CameraProps {
    * }
    * ```
    *
-   * ## Non-AR mode tradeoff (HONEST)
+   * ## Non-AR mode composition (v0.11.0+)
    *
    * vision-camera's `<Camera>` accepts ONLY ONE frame processor.
    * The lib's internal `useFrameProcessorDriver` produces the
    * processor that drives first-party panorama stitching in non-AR
-   * mode.  If you supply your own via this prop, **the lib's
-   * first-party stitching is replaced** — panorama capture in
-   * non-AR mode will not produce stitched output until you remove
-   * the prop or fork the SDK to compose both worklets manually.
+   * mode.  If you supply your own via this prop, the lib's
+   * default processor is REPLACED — but as of v0.11.0 you can
+   * COMPOSE first-party stitching back into your worklet body
+   * using `useStitcherWorklet`:
    *
-   * For the common case (host wants worklet + lib wants stitching
-   * concurrently), prefer AR mode: the AR-mode path natively fans
-   * out to both the lib's first-party stitching AND every
-   * registered host worklet on every frame, with per-worklet
-   * failure isolation.
+   * ```tsx
+   * import {
+   *   Camera, useFrameProcessor, useStitcherWorklet,
+   *   type StitcherFrame,
+   * } from 'react-native-image-stitcher';
    *
-   * Composition for non-AR mode (lib stitching + host worklet on
-   * the same vc processor) is tracked as a v0.9+ follow-up;
-   * needs the lib's first-party logic exposed as a vc Frame
-   * Processor plugin the host's worklet can call.
+   * function MyScreen() {
+   *   const stitcher = useStitcherWorklet();
+   *   const fp = useFrameProcessor((frame: StitcherFrame) => {
+   *     'worklet';
+   *     hostPreLogic(frame);
+   *     stitcher.call(frame);   // ← first-party stitching
+   *     hostPostLogic(frame);
+   *   }, [stitcher.call]);
+   *   return <Camera frameProcessor={fp} ... />;
+   * }
+   * ```
+   *
+   * Hosts that DON'T call `useStitcherWorklet` from their worklet
+   * body replace first-party stitching for non-AR captures (a
+   * one-shot console.info documents this when the prop is first
+   * supplied).  AR mode is unaffected either way — the AR-mode
+   * dispatch path (v0.8.0 Phase 4b.i / 4b.iii) natively fans out
+   * to both the lib's first-party stitching AND every registered
+   * host worklet on every frame, with per-worklet failure
+   * isolation.
    *
    * ## AR mode behaviour
    *
@@ -841,24 +857,23 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => () => { fpDriver.stop(); }, []);
 
-  // v0.8.0 Phase 5 — frameProcessor prop semantics:
+  // v0.8.0 Phase 5 / v0.11.0 — frameProcessor prop semantics:
   //
-  //   - Host supplied? → use host's processor; lib's first-party
-  //     stitching is DISABLED in non-AR mode (vc accepts only one
-  //     processor).  One-shot console.info documents the tradeoff
-  //     so the host isn't surprised by "panorama capture stopped
-  //     producing output" in non-AR mode.  AR-mode capture is
-  //     unaffected — the AR-session dispatch path fans out to BOTH
-  //     first-party and host worklets independently.
+  //   - Host supplied? → use host's processor.  The host's worklet
+  //     body controls whether first-party stitching also fires:
+  //     call `stitcher.call(frame)` (from `useStitcherWorklet`)
+  //     inside the body to compose; omit to replace.  One-shot
+  //     console.info documents the choice so the host can spot a
+  //     missing `useStitcherWorklet` call before they go hunting
+  //     for "why is non-AR panorama capture not producing output".
+  //     AR-mode capture is unaffected either way — the AR-session
+  //     dispatch path fans out to BOTH first-party stitching AND
+  //     every host worklet independently.
   //
   //   - No host processor? → use `fpDriver.frameProcessor` which is
   //     the lib's internal worklet driving first-party stitching
   //     via `useFrameProcessorDriver`.  Default behaviour for the
   //     common "I just want panorama capture" case.
-  //
-  // The pre-v0.8.0 behaviour (host's prop silently ignored with
-  // a warning) is gone — Phase 5 plumbs the prop through.  The
-  // tradeoff is honestly documented in the CameraProps docstring.
   const hostFrameProcessorAcceptedWarnedRef = useRef(false);
   if (
     hostFrameProcessor != null
@@ -868,12 +883,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
     // eslint-disable-next-line no-console
     console.info(
       '[react-native-image-stitcher] Host frameProcessor supplied — '
-      + 'non-AR mode will run YOUR worklet instead of the lib\'s '
-      + 'first-party stitching plugin (vc accepts only one frame '
-      + 'processor).  Non-AR panorama capture will not produce '
-      + 'stitched output until this prop is removed.  AR-mode '
-      + 'capture is unaffected (AR-session dispatch fans out to '
-      + 'both first-party and host worklets independently).',
+      + 'non-AR mode will run YOUR composed worklet.  If you want '
+      + 'first-party panorama stitching alongside your own logic, '
+      + 'call `useStitcherWorklet()` and invoke `stitcher.call(frame)` '
+      + 'from your worklet body (see `<Camera>` `frameProcessor` '
+      + 'JSDoc for the composition pattern).  AR-mode capture is '
+      + 'unaffected (AR-session dispatch fans out to both '
+      + 'first-party and host worklets independently).',
     );
   }
   // The Frame Processor worklet bound to vision-camera's Camera.

package/src/camera/useCapture.ts

@@ -18,7 +18,7 @@
  *   - This hook does NOT persist captures.  Host apps hand the
  *     returned CaptureResult to their own storage layer (WatermelonDB
  *     insert, Redux dispatch, whatever).
- *   - Video recording lives in useVideoCapture (TODO).
+ *   - Video recording lives in useVideoCapture.
  *
  * The public API is designed to be minimal and replaceable: host apps
  * that prefer the raw vision-camera API can opt out of this hook and

package/src/index.ts

@@ -226,6 +226,19 @@ export type {
   FrameProcessorDriverHandle,
 } from './stitching/useFrameProcessorDriver';
 
+// v0.11.0 — composable first-party stitching as a worklet function.
+// Hosts that want to COMPOSE their own per-frame logic with the
+// lib's stitching (instead of REPLACING it via the <Camera>
+// `frameProcessor` prop) call this hook + invoke `stitcher.call`
+// inside their own `useFrameProcessor` body.  See
+// `docs/host-app-integration.md` § Tier 3 for the full pattern.
+export { useStitcherWorklet } from './stitching/useStitcherWorklet';
+export type {
+  UseStitcherWorkletOptions,
+  StitcherWorkletHandle,
+  StitcherWorkletInput,
+} from './stitching/useStitcherWorklet';
+
 // ── Batch stitching ───────────────────────────────────────────────────
 // Feed a video file straight to OpenCV's cv::Stitcher, bypassing the
 // incremental pipeline.  Useful when you have content captured