react-native-image-stitcher 0.14.1 → 0.14.2

package/CHANGELOG.md

@@ -16,6 +16,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.2] — 2026-06-03
+
+### Fixed — AR preview blank on first entry (intermittent camera-handoff race)
+
+`<Camera>` mounted the vision-camera preview before the device AR-support
+probe (`isSupported()`) resolved: `isAvailable` starts `false`, so
+`deriveEffectiveCaptureSource` returned `'non-ar'` and vision-camera's
+AVCaptureSession grabbed the camera.  When the probe resolved ~200-500 ms
+later and the source flipped to AR, ARKit's `session.run()` raced the
+still-open AVCaptureSession for the (mutually-exclusive) camera and lost
+with `ARError "Required sensor failed."` — leaving a blank AR preview and an
+"AR session has no current frame" error on the next capture.  Being
+timing-dependent it reproduced intermittently; toggling AR off→on recovered
+(that path releases the camera cleanly first).
+
+`useARSession` now exposes `supportProbed` (true once the one-shot
+`isSupported()` probe settles — success or failure).  `<Camera>` defers the
+initial camera mount while AR is the intended source but support is still
+unknown, rendering the "Switching camera…" placeholder instead of
+vision-camera, so vision-camera never contends for the camera when AR is the
+intent.
+
+### Fixed — consumer iOS pod build pulled in the lib's C++ gtest unit tests
+
+`RNImageStitcher.podspec`'s `cpp/**/*.{h,hpp,cpp}` glob slurped the lib's own
+`cpp/tests/*.cpp` (which `#include <gtest/gtest.h>`) into every host pod
+build, failing with `'gtest/gtest.h' file not found`.  Added
+`s.exclude_files = ['cpp/tests/**/*']`.
+
 ## [0.14.1] — 2026-06-01
 
 ### Docs

package/RNImageStitcher.podspec

@@ -37,6 +37,12 @@ Pod::Spec.new do |s|
   # (cpp/) that both iOS and Android compile from a single source.
   s.source_files = ['ios/Sources/**/*.{swift,h,m,mm}',
                     'cpp/**/*.{h,hpp,cpp}']
+  # Exclude the lib's own C++ unit tests — they #include <gtest/gtest.h>,
+  # which consumer apps don't vendor.  The `cpp/**/*.cpp` glob above
+  # otherwise slurps cpp/tests/*.cpp into every host pod build, failing
+  # with `'gtest/gtest.h' file not found`.  Tests build only in the lib's
+  # CI / example app, never in a consumer.
+  s.exclude_files = ['cpp/tests/**/*']
   # Restrict the umbrella header to ONLY the iOS-side Obj-C `.h`
   # files.  Without this, CocoaPods defaults every header in
   # `source_files` (including the C++ `.hpp` files under cpp/) to

package/dist/ar/useARSession.d.ts

@@ -67,6 +67,15 @@ export interface UseARSessionReturn {
      * older iPhones, simulators, and unsupported Android devices.
      */
     isAvailable: boolean;
+    /**
+     * Whether the one-shot `isSupported()` probe has resolved (success OR
+     * failure).  `false` only during the brief async window right after
+     * mount; `true` thereafter.  Lets consumers distinguish "AR not
+     * supported" (probed && !isAvailable) from "support not yet known"
+     * (!probed), so they don't prematurely mount the non-AR camera and
+     * lose a camera-handoff race when AR is the intended source.
+     */
+    supportProbed: boolean;
     /**
      * Whether the session is currently running.  True between
      * `start()` and `stop()`.

package/dist/ar/useARSession.js

@@ -56,6 +56,7 @@ function getNativeModule() {
 const STATE_POLL_INTERVAL_MS = 500;
 function useARSession() {
     const [isAvailable, setIsAvailable] = (0, react_1.useState)(false);
+    const [supportProbed, setSupportProbed] = (0, react_1.useState)(false);
     const [isRunning, setIsRunning] = (0, react_1.useState)(false);
     const [trackingState, setTrackingState] = (0, react_1.useState)(ARTrackingState.NotAvailable);
     const pollRef = (0, react_1.useRef)(null);
@@ -64,12 +65,32 @@ function useARSession() {
     // AR support shouldn't crash anything — `isAvailable` stays
     // false and the rest of the SDK falls back to vision-camera.
     (0, react_1.useEffect)(() => {
-        if (!native)
+        if (!native) {
+            // No native module at all — treat the probe as resolved
+            // (unsupported) so consumers don't wait forever for AR.
+            setSupportProbed(true);
             return;
-        native.isSupported().then(setIsAvailable).catch((err) => {
+        }
+        let cancelled = false;
+        native
+            .isSupported()
+            .then((ok) => {
+            if (!cancelled)
+                setIsAvailable(ok);
+        })
+            .catch((err) => {
             // eslint-disable-next-line no-console
             console.warn('[useARSession] isSupported failed', err);
+        })
+            .finally(() => {
+            // Mark the probe resolved either way so the non-AR fallback
+            // (or AR mount) can proceed exactly once support is known.
+            if (!cancelled)
+                setSupportProbed(true);
         });
+        return () => {
+            cancelled = true;
+        };
     }, [native]);
     const stopPolling = (0, react_1.useCallback)(() => {
         if (pollRef.current !== null) {
@@ -122,6 +143,7 @@ function useARSession() {
     }, [native]);
     return {
         isAvailable,
+        supportProbed,
         isRunning,
         trackingState,
         start,

package/dist/camera/Camera.js

@@ -328,10 +328,25 @@ function Camera(props) {
     // (older iPhones, ARCore-less Androids, simulators) stay `false`
     // forever, which forces non-AR capture everywhere and hides the
     // AR toggle in the bottom bar (see JSX below).
-    const { isAvailable: isARSupportedOnDevice } = (0, useARSession_1.useARSession)();
+    const { isAvailable: isARSupportedOnDevice, supportProbed: isARSupportProbed } = (0, useARSession_1.useARSession)();
     const effectiveCaptureSource = deriveEffectiveCaptureSource(arPreference, lens, isARSupportedOnDevice);
     const isAR = effectiveCaptureSource === 'ar';
     const isNonAR = !isAR;
+    // v0.14.2 — camera-handoff race guard.  While AR is the preferred
+    // source but the one-shot `isSupported()` probe hasn't resolved yet,
+    // `deriveEffectiveCaptureSource` returns 'non-ar' (because
+    // `isARSupportedOnDevice` is still false), which would mount
+    // <CameraView> and let vision-camera's AVCaptureSession grab the
+    // camera.  The switch to AR ~200-500ms later then fails with ARKit
+    // "Required sensor failed" (ARKit and AVCaptureSession can't share the
+    // camera), leaving a blank AR preview — intermittent and timing-
+    // dependent.  Defer the initial mount until the probe settles: while
+    // pending we render the "Switching camera…" placeholder instead of any
+    // camera, so vision-camera never contends for the device when AR is the
+    // intent.  Conditions mirror deriveEffectiveCaptureSource's own
+    // non-support gates (arPreference, lens) so this is true in exactly the
+    // cases that resolve to AR once support is confirmed.
+    const arSupportPending = arPreference && lens !== '0.5x' && !isARSupportProbed;
     const deviceOrientation = (0, useDeviceOrientation_1.useDeviceOrientation)();
     // v0.13.1 — counter-rotation for control CONTENT (AR toggle, lens
     // pill, flash icon, thumbnails) so their labels read upright relative
@@ -970,7 +985,7 @@ function Camera(props) {
             : insets.top + 8;
     // ── JSX ─────────────────────────────────────────────────────────
     return (react_1.default.createElement(react_native_1.View, { style: [styles.container, style] },
-        inFlightTransition ? (react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] },
+        inFlightTransition || arSupportPending ? (react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] },
             react_1.default.createElement(react_native_1.Text, { style: styles.transitionLabel }, "Switching camera\u2026"))) : isAR ? (react_1.default.createElement(ARCameraView_1.ARCameraView, { ref: arViewRef, style: react_native_1.StyleSheet.absoluteFill })) : (react_1.default.createElement(CameraView_1.CameraView, { ref: visionCameraRef, device: capture.device, isActive: true, 
             // `video={true}` is REQUIRED for takeSnapshot to work on iOS.
             // vision-camera v4's iOS implementation of takeSnapshot waits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "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/ar/useARSession.ts

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

package/src/camera/Camera.tsx

@@ -979,7 +979,8 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // (older iPhones, ARCore-less Androids, simulators) stay `false`
   // forever, which forces non-AR capture everywhere and hides the
   // AR toggle in the bottom bar (see JSX below).
-  const { isAvailable: isARSupportedOnDevice } = useARSession();
+  const { isAvailable: isARSupportedOnDevice, supportProbed: isARSupportProbed } =
+    useARSession();
 
   const effectiveCaptureSource = deriveEffectiveCaptureSource(
     arPreference,
@@ -988,6 +989,23 @@ export function Camera(props: CameraProps): React.JSX.Element {
   );
   const isAR = effectiveCaptureSource === 'ar';
   const isNonAR = !isAR;
+
+  // v0.14.2 — camera-handoff race guard.  While AR is the preferred
+  // source but the one-shot `isSupported()` probe hasn't resolved yet,
+  // `deriveEffectiveCaptureSource` returns 'non-ar' (because
+  // `isARSupportedOnDevice` is still false), which would mount
+  // <CameraView> and let vision-camera's AVCaptureSession grab the
+  // camera.  The switch to AR ~200-500ms later then fails with ARKit
+  // "Required sensor failed" (ARKit and AVCaptureSession can't share the
+  // camera), leaving a blank AR preview — intermittent and timing-
+  // dependent.  Defer the initial mount until the probe settles: while
+  // pending we render the "Switching camera…" placeholder instead of any
+  // camera, so vision-camera never contends for the device when AR is the
+  // intent.  Conditions mirror deriveEffectiveCaptureSource's own
+  // non-support gates (arPreference, lens) so this is true in exactly the
+  // cases that resolve to AR once support is confirmed.
+  const arSupportPending =
+    arPreference && lens !== '0.5x' && !isARSupportProbed;
   const deviceOrientation = useDeviceOrientation();
 
   // v0.13.1 — counter-rotation for control CONTENT (AR toggle, lens
@@ -1690,7 +1708,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
           only ONE camera component is alive at a time; matches the
           monorepo's working pattern and avoids the Camera2-in-use
           conflict that "always mount both" caused on Android. */}
-      {inFlightTransition ? (
+      {inFlightTransition || arSupportPending ? (
         <View style={[StyleSheet.absoluteFill, styles.transitionPlaceholder]}>
           <Text style={styles.transitionLabel}>Switching camera…</Text>
         </View>