react-native-image-stitcher 0.9.0 → 0.10.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.10.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/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/stitching/__tests__/subscribeIncrementalState.refine.test.ts

@@ -0,0 +1,276 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit + integration coverage for the v0.10.0 PR B refine-progress
+ * lifecycle on the `IncrementalStateUpdate` channel.
+ *
+ * What this test is for:
+ *
+ *   - Contract: native emits a 4-stage sequence
+ *     `validating → stitching → writing → done` (and the failure
+ *     variant `validating → error`) with `refineStage` /
+ *     `refineProgress` / `refineFrames` / `refineError` keys.
+ *   - Regression: catches a future renamer of any of those keys
+ *     (subscribeIncrementalState would silently deliver `undefined`
+ *     for the missing fields, and the host's progress pill would
+ *     stop rendering — exactly the bug class we hit on iOS in PR B
+ *     before the bridgeless-interop fix).
+ *
+ * What this test is NOT for:
+ *
+ *   - Exercising the real native bridge — RCTEventEmitter under RN
+ *     bridgeless interop can only be tested on-device.  The bug we
+ *     fixed in PR B (sendEvent silently no-ops for certain body
+ *     shapes) is verified via the manual smoke test recorded in
+ *     CHANGELOG.md "Fixed — v0.10.0 PR B (iOS)".  This file pins
+ *     the JS-side contract that bridge fix has to satisfy.
+ *
+ * Mock surface: per-test `jest.mock('react-native', ...)` so the
+ * shared `jest.mocks/react-native.js` stays minimal (per the comment
+ * in that file).  We stub `NativeModules.IncrementalStitcher` and
+ * `NativeEventEmitter` together because `subscribeIncrementalState`
+ * wires them together internally.
+ */
+
+import type { IncrementalState } from '../incremental';
+
+// Hand-rolled event-emitter fake we can drive synchronously from
+// tests.  Modelled on RN's NativeEventEmitter shape: addListener
+// returns an object with a `.remove()` method.
+type Listener = (state: IncrementalState) => void;
+
+class FakeNativeEventEmitter {
+  private listeners: Map<string, Set<Listener>> = new Map();
+
+  constructor(_nativeModule: unknown) {
+    // No-op: real RN reads addListener/removeListeners off the
+    // native module for the listener-count contract; we don't.
+  }
+
+  addListener(eventType: string, listener: Listener) {
+    let set = this.listeners.get(eventType);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(eventType, set);
+    }
+    set.add(listener);
+    return {
+      remove: () => {
+        set!.delete(listener);
+      },
+    };
+  }
+
+  // Test-only helper: drive an event into all subscribers.
+  _emit(eventType: string, state: IncrementalState) {
+    const set = this.listeners.get(eventType);
+    if (!set) return;
+    for (const listener of set) {
+      listener(state);
+    }
+  }
+}
+
+// Shared emitter handle the per-test setup writes its asserts
+// against.  The mock factory below has to construct via `new`, so we
+// stash the latest instance here for the test to drive.
+let lastEmitter: FakeNativeEventEmitter | null = null;
+
+jest.mock('react-native', () => ({
+  NativeModules: {
+    IncrementalStitcher: {
+      // RCTEventEmitter / NativeEventEmitter contract — RN's runtime
+      // calls these when JS subscribes / unsubscribes so the native
+      // side can track listener count.  We just stub them.
+      addListener: jest.fn(),
+      removeListeners: jest.fn(),
+    },
+  },
+  NativeEventEmitter: jest.fn().mockImplementation((nativeModule: unknown) => {
+    lastEmitter = new FakeNativeEventEmitter(nativeModule);
+    return lastEmitter;
+  }),
+  Platform: { OS: 'ios', select: (spec: { ios?: unknown; default?: unknown }) => spec.ios ?? spec.default },
+}));
+
+// Import AFTER jest.mock so the SUT picks up the mocked module.
+import { subscribeIncrementalState } from '../incremental';
+
+// Build the base state shape the native side emits — matches the
+// fields IncrementalStateObject.asDictionary() includes on iOS and
+// Arguments.createMap() includes on Android.
+function makeBaseState(): IncrementalState {
+  return {
+    width: 1920,
+    height: 1080,
+    acceptedCount: 3,
+    outcome: 8, // acceptedHigh
+    confidence: 0.92,
+    overlapPercent: 18.5,
+    processingMs: 0,
+    isLandscape: false,
+    paintedExtent: 1920,
+    panExtent: 1920,
+    keyframeMax: 0,
+  } as IncrementalState;
+}
+
+describe('subscribeIncrementalState — refine progress lifecycle (v0.10.0 PR B)', () => {
+  beforeEach(() => {
+    lastEmitter = null;
+    jest.clearAllMocks();
+  });
+
+  it('returns null when the native IncrementalStitcher module is missing', () => {
+    // Temporarily blank the module.
+    const RN = jest.requireMock('react-native') as { NativeModules: Record<string, unknown> };
+    const saved = RN.NativeModules.IncrementalStitcher;
+    RN.NativeModules.IncrementalStitcher = undefined;
+    try {
+      expect(subscribeIncrementalState(() => {})).toBeNull();
+    } finally {
+      RN.NativeModules.IncrementalStitcher = saved;
+    }
+  });
+
+  it('returns an EmitterSubscription when subscribed; remove() stops delivery', () => {
+    const events: IncrementalState[] = [];
+    const sub = subscribeIncrementalState((s) => events.push(s));
+    expect(sub).not.toBeNull();
+    expect(lastEmitter).not.toBeNull();
+
+    lastEmitter!._emit('IncrementalStateUpdate', {
+      ...makeBaseState(),
+      refineStage: 'validating',
+      refineProgress: 0.05,
+      refineFrames: 3,
+    } as IncrementalState);
+    expect(events).toHaveLength(1);
+
+    sub!.remove();
+    lastEmitter!._emit('IncrementalStateUpdate', {
+      ...makeBaseState(),
+      refineStage: 'done',
+      refineProgress: 1.0,
+      refineFrames: 3,
+    } as IncrementalState);
+    expect(events).toHaveLength(1); // unchanged after remove()
+  });
+
+  it('happy-path: delivers validating → stitching → writing → done in order with correct refineStage', () => {
+    const stages: Array<{ stage: string | undefined; progress: number | undefined }> = [];
+    subscribeIncrementalState((s) => {
+      stages.push({ stage: s.refineStage, progress: s.refineProgress });
+    });
+
+    const sequence: Array<Pick<IncrementalState, 'refineStage' | 'refineProgress' | 'refineFrames'>> = [
+      { refineStage: 'validating', refineProgress: 0.05, refineFrames: 3 },
+      { refineStage: 'stitching',  refineProgress: 0.10, refineFrames: 3 },
+      { refineStage: 'writing',    refineProgress: 0.90, refineFrames: 3 },
+      { refineStage: 'done',       refineProgress: 1.00, refineFrames: 3 },
+    ];
+    for (const ev of sequence) {
+      lastEmitter!._emit('IncrementalStateUpdate', { ...makeBaseState(), ...ev } as IncrementalState);
+    }
+
+    expect(stages).toEqual([
+      { stage: 'validating', progress: 0.05 },
+      { stage: 'stitching',  progress: 0.10 },
+      { stage: 'writing',    progress: 0.90 },
+      { stage: 'done',       progress: 1.00 },
+    ]);
+  });
+
+  it('refineProgress is non-decreasing across the happy-path sequence (monotonicity contract)', () => {
+    const progresses: number[] = [];
+    subscribeIncrementalState((s) => {
+      if (s.refineProgress !== undefined) progresses.push(s.refineProgress);
+    });
+
+    for (const p of [0.05, 0.10, 0.90, 1.00]) {
+      lastEmitter!._emit('IncrementalStateUpdate', {
+        ...makeBaseState(),
+        refineStage: 'stitching', // stage is irrelevant for this assertion
+        refineProgress: p,
+        refineFrames: 3,
+      } as IncrementalState);
+    }
+
+    expect(progresses).toEqual([0.05, 0.10, 0.90, 1.00]);
+    for (let i = 1; i < progresses.length; i++) {
+      expect(progresses[i]).toBeGreaterThanOrEqual(progresses[i - 1]);
+    }
+  });
+
+  it('failure-path: validating → error carries refineError; no further stages emitted', () => {
+    const events: IncrementalState[] = [];
+    subscribeIncrementalState((s) => events.push(s));
+
+    lastEmitter!._emit('IncrementalStateUpdate', {
+      ...makeBaseState(),
+      refineStage: 'validating',
+      refineProgress: 0.05,
+      refineFrames: 3,
+    } as IncrementalState);
+    lastEmitter!._emit('IncrementalStateUpdate', {
+      ...makeBaseState(),
+      refineStage: 'error',
+      refineProgress: 1.0,
+      refineFrames: 3,
+      refineError: 'INVALID_FRAMES: missing JPEG at index 1',
+    } as IncrementalState);
+
+    expect(events).toHaveLength(2);
+    expect(events[0].refineStage).toBe('validating');
+    expect(events[1].refineStage).toBe('error');
+    expect(events[1].refineError).toBe('INVALID_FRAMES: missing JPEG at index 1');
+    // refineError is absent on the validating event.
+    expect(events[0].refineError).toBeUndefined();
+  });
+
+  it('refineFrames passes through unchanged (regression guard for key rename)', () => {
+    const seen: Array<number | undefined> = [];
+    subscribeIncrementalState((s) => seen.push(s.refineFrames));
+
+    for (const n of [3, 5, 8]) {
+      lastEmitter!._emit('IncrementalStateUpdate', {
+        ...makeBaseState(),
+        refineStage: 'stitching',
+        refineProgress: 0.5,
+        refineFrames: n,
+      } as IncrementalState);
+    }
+    expect(seen).toEqual([3, 5, 8]);
+  });
+
+  it('live (non-refine) state events leave refine fields undefined', () => {
+    // Asserts that the contract is "refine fields are only populated
+    // during a refine call" — so the example app's `if
+    // (s.refineStage === undefined) return;` short-circuit is sound.
+    const events: IncrementalState[] = [];
+    subscribeIncrementalState((s) => events.push(s));
+
+    lastEmitter!._emit('IncrementalStateUpdate', makeBaseState());
+    expect(events).toHaveLength(1);
+    expect(events[0].refineStage).toBeUndefined();
+    expect(events[0].refineProgress).toBeUndefined();
+    expect(events[0].refineFrames).toBeUndefined();
+    expect(events[0].refineError).toBeUndefined();
+  });
+
+  it('subscribes on the correct channel name "IncrementalStateUpdate" (cross-platform contract)', () => {
+    // If anyone renames the event constant on either side, the
+    // subscriber stops receiving events.  Pin the literal here.
+    let receivedOnRight = false;
+    let receivedOnWrong = false;
+    subscribeIncrementalState(() => {
+      receivedOnRight = true;
+    });
+    // Fire on a deliberately-wrong channel — should NOT deliver.
+    lastEmitter!._emit('SomeOtherChannel', makeBaseState());
+    expect(receivedOnRight).toBe(false);
+    expect(receivedOnWrong).toBe(false);
+    // Fire on the right channel — should deliver.
+    lastEmitter!._emit('IncrementalStateUpdate', makeBaseState());
+    expect(receivedOnRight).toBe(true);
+  });
+});

package/src/stitching/incremental.ts

@@ -261,6 +261,48 @@ export interface IncrementalState {
    * keyframes on disk.
    */
   refinedPanoramaPath?: string;
+
+  /**
+   * v0.10.0 (#15A) — current phase of an in-flight `refinePanorama`
+   * call.  Fires from both the explicit `module.refinePanorama(...)`
+   * JS API path AND the hybrid-engine auto-refine path (which calls
+   * the same native refinePanorama internally).
+   *
+   * Lifecycle:
+   *   - `"validating"` (fraction 0.05) — synchronous input checks
+   *   - `"stitching"`  (fraction 0.10) — OpenCV stitch in flight
+   *   - `"writing"`    (fraction 0.90) — stitch done, JPEG written
+   *   - `"done"`       (fraction 1.00) — success
+   *   - `"error"`      (fraction 1.00) — failure; `refineError` is set
+   *
+   * Coarse on purpose: OpenCV's Stitcher doesn't expose mid-pipeline
+   * progress, so the 0.10 → 0.90 jump is one opaque step.  Use
+   * `refineStage` for a stage label; use `refineProgress` purely for
+   * spinner progress.
+   *
+   * Undefined when no refinement is in flight.
+   */
+  refineStage?: 'validating' | 'stitching' | 'writing' | 'done' | 'error';
+  /**
+   * v0.10.0 (#15A) — coarse progress fraction in `[0, 1]` aligned
+   * with `refineStage`.  See `refineStage` for the per-stage value
+   * mapping.  Undefined when no refinement is in flight.
+   */
+  refineProgress?: number;
+  /**
+   * v0.10.0 (#15A) — number of input frames the in-flight refine is
+   * processing.  Useful for the UI label
+   * (`Stitching 6 frames…`).  Mirrors the `framesRequested` field
+   * returned in the explicit refinePanorama resolution.  Undefined
+   * when no refinement is in flight.
+   */
+  refineFrames?: number;
+  /**
+   * v0.10.0 (#15A) — present only when `refineStage === 'error'`.
+   * Human-readable error message; the same text the rejected promise
+   * carries.  Use to render a one-line failure pill.
+   */
+  refineError?: string;
 }