react-native-image-stitcher 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -16,6 +16,111 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-06-01
+
+### Fixed — Android AR single-photo orientation (landscape was sideways)
+
+Android AR `takePhoto` baked the wrong rotation into landscape captures
+under a portrait-locked host: it derived the EXIF orientation from the
+window display rotation (`WindowManager.defaultDisplay.rotation`), which
+stays `ROTATION_0` when the activity is portrait-locked regardless of how
+the device is physically held — so a landscape photo got a portrait EXIF
+tag and came out 90° CW.  The JS layer already passed the gyro device
+orientation to `RNSARSession.takePhoto` (since v0.12), and iOS consumed
+it, but the Android native side dropped it.  Now Android threads the
+device orientation through `takePhoto → requestTakePhoto → encodeToJpeg`,
+mapping it to the correct `Surface.ROTATION_*` / EXIF tag.  iOS unchanged
+(already correct).  Verified on-device (Samsung A35) in both landscape
+orientations.
+
+### Added — `captureSources` constraint prop
+
+`<Camera>` gains `captureSources?: 'ar' | 'non-ar' | 'both'` (default
+`'both'`) — a constraint on which capture sources the host allows, layered
+over `defaultCaptureSource` (which picks the initial source within it):
+
+- `'both'`  — AR + non-AR; the runtime AR toggle is shown (unchanged
+  default behaviour).
+- `'ar'`    — AR only; the AR toggle is hidden (nothing to switch to) and
+  the 0.5×/1× lens chooser is hidden (ARKit/ARCore can't use the
+  ultra-wide), keeping capture on the AR-capable 1× lens.
+- `'non-ar'`— non-AR only; the AR toggle is hidden, the lens chooser stays.
+
+A single-source constraint overrides a conflicting `defaultCaptureSource`.
+Exported type: `CaptureSourcesMode`.  Verified on-device (A35) across all
+three modes.
+
+### Fixed — capability-aware lens selection (ultra-wide + flash on 0.5×)
+
+`<Camera>` now selects the back camera device by real capability instead
+of requesting a single physical lens per zoom level.  `selectCaptureDevice`:
+
+- **Prefers a multi-cam device** that spans wide + ultra-wide (lens
+  switched via `zoom`; torch available on every lens).  On devices that
+  expose such a device (e.g. iPhone 16 Pro — verified `multicam`), this
+  fixes the user-reported "0.5× shows the wide-angle FOV" bug AND makes
+  flash work on 0.5× (the mounted multi-cam device carries the torch).
+- **Falls back to a standalone ultra-wide** device-swap where no multi-cam
+  device exists (e.g. Samsung A35 — verified `standalone-uw`; vision-camera
+  surfaces the physical cameras separately there).  0.5× still shows the
+  ultra-wide FOV; flash hides because that standalone device is torchless.
+
+`has0_5x` is now derived from the real device inventory (was hardcoded
+`true`), so the lens chooser hides on wide-only hardware.  13 unit tests
+cover the selection matrix incl. both edge cases (ultra-wide only in a
+multi-cam group; ultra-wide only standalone).
+
+Verified on-device: iPhone 16 Pro (multicam — 0.5× FOV + flash both work)
+and Samsung A35 (standalone-uw — 0.5× FOV works, flash correctly hidden).
+
+### Added — Android portrait lock (SDK-enforced)
+
+`<Camera>` now locks its host Activity to portrait on Android while
+mounted, via `Activity.setRequestedOrientation`, **regardless of the
+host app's `AndroidManifest` `screenOrientation`**.  A landscape or
+unlocked host still gets a portrait camera screen.  The Activity's
+prior orientation is captured on mount and restored on unmount.
+Implemented in the native `RNSARSession` module (`lockPortrait()` /
+`unlockOrientation()`) and driven from a `<Camera>` mount effect, so
+it covers both the AR (ARCore) and non-AR (vision-camera) paths.
+There is no opt-out — Android capture is portrait-only by design.
+
+iOS is intentionally unchanged: supported orientations remain owned by
+the host `Info.plist`.  **Portrait is the recommended configuration on
+both platforms; landscape is supported on iOS** for hosts that need it.
+
+### Fixed — landscape preview + thumbnail orientation (non-locked iOS)
+
+- **Preview squish / sideways** under a non-locked host was caused by
+  an in-development `patch-package` patch to vision-camera's
+  `OrientationManager` (both `.kt` and `.swift`) that derived the
+  PREVIEW orientation from the accelerometer instead of the interface
+  orientation.  In a portrait host held landscape this forced a
+  landscape preview into a portrait surface.  The patch was removed and
+  vision-camera restored to pristine on both platforms.
+- **Band keyframe thumbnails rotated 90°**: the per-keyframe tiles in
+  `PanoramaBandOverlay` were double-rotated — the saved `keyframe-N.jpg`
+  is sensor-native landscape + EXIF Orientation 6, which `<Image>`
+  already auto-rotates, so the extra JS transform was redundant in the
+  portrait-locked (`vertical=false`) path.  The transform is now applied
+  only in the `vertical=true` (non-locked landscape) path.
+- **Stitched-preview / confirm modals stuck portrait**: `CapturePreview`
+  and `PanoramaConfirmModal` were missing `supportedOrientations`
+  (RN's iOS `<Modal>` defaults to portrait-only).  Both now declare all
+  four, matching `OrientationDriftModal` + `PanoramaSettingsModal`.
+- **Idle thumbnail strip horizontal in landscape**: `CaptureThumbnailStrip`
+  gained a `vertical` prop (wired from the same `isSideEdge` signal as
+  the band) so the idle strip stacks vertically along the home-indicator
+  edge under a non-locked host instead of running across the screen.
+
+### Removed — pan-guidance overlays no longer public
+
+`IncrementalPanGuide` (drift marker) and `PanoramaGuidance` (pan-speed
+pill) are no longer exported, and the `panGuide` / `panoramaGuidance`
+props were removed from `<Camera>`.  The components remain in the tree
+as internal-only code (not rendered).  Hosts that were passing these
+props should remove them.
+
 ## [0.13.0] — 2026-05-29
 
 ### Added — Layer-2 components absorbed into `<Camera>` (opt-out)

package/README.md

@@ -104,7 +104,11 @@ export function CaptureScreen() {
 
 ## `<Camera>` props (summary)
 
-See `src/camera/Camera.tsx` for the full TSDoc.  Highlights:
+> **Full reference:** [`docs/camera-component.md`](docs/camera-component.md)
+> covers every prop with purpose, default, behaviour notes, the
+> `CameraCaptureResult` / `CameraError` shapes, orientation
+> behaviour, and common compositions.  This README summary lists
+> the highlights only.
 
 ### Initial values (uncontrolled — read once at mount)
 
@@ -142,22 +146,34 @@ See `src/camera/Camera.tsx` for the full TSDoc.  Highlights:
 
 ## Orientation support
 
-`<Camera>` works in any device orientation regardless of host
-configuration.  No host setup required — the SDK adapts at runtime.
-
-**Portrait-locked host** (Info.plist `UISupportedInterfaceOrientations`
-restricted to Portrait — recommended for kiosks / single-task apps):
-the screen stays portrait; the SDK uses sensor-derived orientation
-for capture-mode selection and overlay layout.  This is the simpler
-configuration and the historical default.
-
-**Non-locked host** (Info.plist supports all 4 orientations — recommended
-for apps with other landscape-friendly screens): the screen rotates
-with the device.  `<Camera>`'s controls (shutter, lens chip, AR toggle)
-anchor to the home-indicator edge so they stay within thumb reach
-regardless of tilt — matching iOS Camera's behaviour.  The
-orientation-aware logic combines `useWindowDimensions()` (JS-layout)
-with `useDeviceOrientation()` (sensor) to compute the correct anchor.
+> **Recommended: portrait.**  `<Camera>` is designed and tuned for
+> portrait capture, and that is the recommended way to use it on both
+> platforms.  Landscape is supported on iOS for hosts that need it
+> (see below); on Android the camera is always portrait.
+
+**Android — always portrait (SDK-enforced).**  On Android `<Camera>`
+locks its host Activity to portrait while mounted (via
+`Activity.setRequestedOrientation`), **regardless of the host app's
+manifest** — even a fully landscape or unlocked host gets a portrait
+camera screen.  The prior orientation is restored when `<Camera>`
+unmounts.  No host setup is required and there is no opt-out: Android
+capture is portrait-only by design.
+
+**iOS — portrait recommended, landscape supported.**  iOS supported
+orientations are owned by the host's `Info.plist`
+(`UISupportedInterfaceOrientations`); the SDK does not override them.
+
+- *Portrait-only host* (Info.plist = Portrait — **recommended**): the
+  screen stays portrait; the SDK uses sensor-derived orientation for
+  capture-mode selection and overlay layout.  Simplest configuration.
+- *Non-locked host* (Info.plist supports all 4 — supported for apps
+  with other landscape-friendly screens): the screen rotates with the
+  device.  `<Camera>`'s controls (shutter, lens chip, AR toggle) and
+  the live thumbnail strip/band anchor to the home-indicator edge so
+  they stay within thumb reach regardless of tilt — matching iOS
+  Camera's behaviour.  The orientation-aware logic combines
+  `useWindowDimensions()` (JS-layout) with `useDeviceOrientation()`
+  (sensor) to compute the correct anchor.
 
 **Mid-capture rotation safety** — the incremental engine doesn't
 support cross-orientation captures (a portrait capture's keyframes

package/android/src/main/java/io/imagestitcher/rn/RNSARCameraView.kt

@@ -89,6 +89,14 @@ class RNSARCameraView @JvmOverloads constructor(
     internal data class TakePhotoRequest(
         val outputPath: String,
         val quality: Int,
+        // v0.13.2 — physical device orientation at capture time, from the
+        // JS `useDeviceOrientation()` hook (one of 'portrait' /
+        // 'portrait-upside-down' / 'landscape-left' / 'landscape-right').
+        // Used INSTEAD of the window display rotation so AR photos come
+        // out upright even under a PORTRAIT-LOCKED host (where the window
+        // rotation is always ROTATION_0 regardless of how the device is
+        // held — the cause of the "landscape AR photo is sideways" bug).
+        val orientation: String,
         val promise: com.facebook.react.bridge.Promise,
     )
     private val pendingTakePhoto =
@@ -101,9 +109,10 @@ class RNSARCameraView @JvmOverloads constructor(
     internal fun requestTakePhoto(
         outputPath: String,
         quality: Int,
+        orientation: String,
         promise: com.facebook.react.bridge.Promise,
     ) {
-        val req = TakePhotoRequest(outputPath, quality, promise)
+        val req = TakePhotoRequest(outputPath, quality, orientation, promise)
         val previous = pendingTakePhoto.getAndSet(req)
         previous?.promise?.reject(
             "ar-photo-superseded",
@@ -339,10 +348,15 @@ class RNSARCameraView @JvmOverloads constructor(
                 image,
                 req.outputPath,
                 jpegQuality = req.quality.coerceIn(1, 100),
-                displayRotation = if (lastDisplayRotation >= 0)
-                    lastDisplayRotation
-                else
-                    Surface.ROTATION_0,
+                // v0.13.2 — derive the encode rotation from the PHYSICAL
+                // device orientation (JS gyro), not the window display
+                // rotation.  Under a portrait-locked host the window stays
+                // ROTATION_0 regardless of how the device is held, so the
+                // old `lastDisplayRotation` path baked a portrait EXIF tag
+                // onto landscape captures → sideways photo.  The
+                // device-orientation → Surface.ROTATION_* mapping below
+                // feeds encodeToJpeg's existing EXIF table.
+                displayRotation = deviceOrientationToSurfaceRotation(req.orientation),
             )
             if (written == null) {
                 req.promise.reject(
@@ -632,6 +646,20 @@ class RNSARCameraView @JvmOverloads constructor(
         )
     }
 
+    /// v0.13.2 — map the JS physical device orientation to the
+    /// `Surface.ROTATION_*` value `YuvImageConverter.encodeToJpeg`
+    /// expects.  Mirrors the equivalence documented in encodeToJpeg's
+    /// EXIF table (ROTATION_0=portrait, _90=landscape-left,
+    /// _180=portrait-upside-down, _270=landscape-right).  Unknown /
+    /// missing → portrait (the safe pre-v0.12 default).
+    private fun deviceOrientationToSurfaceRotation(orientation: String): Int =
+        when (orientation) {
+            "landscape-left" -> Surface.ROTATION_90
+            "portrait-upside-down" -> Surface.ROTATION_180
+            "landscape-right" -> Surface.ROTATION_270
+            else -> Surface.ROTATION_0 // "portrait" + fallback
+        }
+
     private fun applyDisplayGeometry() {
         val session = sessionRef.get() ?: return
         val rotation = (context.getSystemService(Context.WINDOW_SERVICE) as? WindowManager)

package/android/src/main/java/io/imagestitcher/rn/RNSARSession.kt

@@ -3,6 +3,7 @@ package io.imagestitcher.rn
 
 import android.app.Activity
 import android.content.Context
+import android.content.pm.ActivityInfo
 import android.util.Log
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
@@ -58,6 +59,65 @@ class RNSARSession(reactContext: ReactApplicationContext)
     private val poseLog = mutableListOf<RNSARFramePose>()
     private val poseLogLock = ReentrantReadWriteLock()
 
+    // ── v0.13.1 — Android <Camera> portrait lock ────────────────────
+    //
+    // Unlike iOS (where supported orientations are a static Info.plist
+    // declaration the app can't override per-view at runtime), Android
+    // lets a view force its host Activity's orientation via
+    // `Activity.requestedOrientation`.  The SDK's `<Camera>` uses this
+    // to guarantee a portrait capture surface regardless of the host
+    // app's manifest — even a fully landscape/unlocked host gets a
+    // portrait camera while `<Camera>` is mounted.
+    //
+    // `lockPortrait()` is called from `Camera.tsx`'s mount effect and
+    // covers BOTH capture paths (AR ARCore view + non-AR vision-camera)
+    // because the lock lives on the Activity, not on either camera view.
+    // `unlockOrientation()` (mount-effect cleanup) restores the EXACT
+    // orientation the Activity had before we locked, so hosts with
+    // mixed-orientation screens get their prior setting back rather than
+    // a generic default.
+    //
+    // SCREEN_ORIENTATION_UNSET (-2) is our "nothing captured yet"
+    // sentinel; we never pass it to setRequestedOrientation.
+    private var priorRequestedOrientation: Int = ORIENTATION_UNSET
+
+    @ReactMethod
+    fun lockPortrait() {
+        val activity: Activity = reactApplicationContext.currentActivity ?: run {
+            Log.w(TAG, "lockPortrait: no current activity — skipping")
+            return
+        }
+        activity.runOnUiThread {
+            // Capture the prior value ONCE (first lock wins).  Guards
+            // against a remount double-capturing our own portrait value
+            // and losing the host's real prior orientation.
+            if (priorRequestedOrientation == ORIENTATION_UNSET) {
+                priorRequestedOrientation = activity.requestedOrientation
+            }
+            activity.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
+        }
+    }
+
+    @ReactMethod
+    fun unlockOrientation() {
+        val activity: Activity = reactApplicationContext.currentActivity ?: run {
+            Log.w(TAG, "unlockOrientation: no current activity — skipping")
+            return
+        }
+        activity.runOnUiThread {
+            if (priorRequestedOrientation != ORIENTATION_UNSET) {
+                activity.requestedOrientation = priorRequestedOrientation
+                priorRequestedOrientation = ORIENTATION_UNSET
+            } else {
+                // No capture on record (lock never ran or already
+                // restored) — fall back to UNSPECIFIED so we don't pin
+                // the host to whatever we last set.
+                activity.requestedOrientation =
+                    ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
+            }
+        }
+    }
+
     @ReactMethod
     fun isSupported(promise: Promise) {
         // `checkAvailability` can return UNKNOWN_CHECKING if the
@@ -395,6 +455,13 @@ class RNSARSession(reactContext: ReactApplicationContext)
         }
         val rawPath = if (options.hasKey("path")) options.getString("path") ?: "" else ""
         val quality = if (options.hasKey("quality")) options.getInt("quality") else 90
+        // v0.13.2 — physical device orientation from JS (useDeviceOrientation).
+        // Drives the saved JPEG's rotation so landscape AR captures are
+        // upright even under a portrait-locked host.  Defaults to
+        // 'portrait' (pre-v0.12 behaviour) when the host omits it.
+        val orientation =
+            if (options.hasKey("orientation")) options.getString("orientation") ?: "portrait"
+            else "portrait"
         val resolvedPath: String = if (rawPath.isNotEmpty()) {
             rawPath
         } else {
@@ -404,7 +471,7 @@ class RNSARSession(reactContext: ReactApplicationContext)
                 "RNImageStitcher-ar-${java.util.UUID.randomUUID()}.jpg",
             ).absolutePath
         }
-        view.requestTakePhoto(resolvedPath, quality, promise)
+        view.requestTakePhoto(resolvedPath, quality, orientation, promise)
     }
 
     @ReactMethod
@@ -776,6 +843,11 @@ class RNSARSession(reactContext: ReactApplicationContext)
         private const val TAG = "RNSARSession"
         private const val MAX_POSE_LOG = 600  // ~10 s @ 60Hz
 
+        // Sentinel for "no prior Activity orientation captured yet".
+        // Distinct from any real ActivityInfo.SCREEN_ORIENTATION_*
+        // value (those are >= -1); -2 is unused by the framework.
+        private const val ORIENTATION_UNSET = -2
+
         /**
          * Convenience accessor for the AR camera view (in Phase 4.4)
          * to reach the singleton-installed module instance.  We use

package/dist/camera/Camera.d.ts

@@ -44,7 +44,19 @@ import type { DrawableFrameProcessor, ReadonlyFrameProcessor } from 'react-nativ
 import { type CaptureHeaderProps } from './CaptureHeader';
 import { type CapturePreviewAction } from './CapturePreview';
 import { type CaptureThumbnailItem } from './CaptureThumbnailStrip';
+import { type DeviceOrientation } from './useDeviceOrientation';
 export type CaptureSource = 'ar' | 'non-ar';
+/**
+ * v0.13.2 — which capture sources the host ALLOWS.  A constraint on top
+ * of `defaultCaptureSource` (which picks the initial source within this
+ * constraint):
+ *   'both'   — AR and non-AR both available; AR toggle is shown.
+ *   'ar'     — AR only; AR toggle hidden (nothing to switch to), and the
+ *              0.5× lens chooser is hidden (ARKit/ARCore don't expose the
+ *              ultra-wide).
+ *   'non-ar' — non-AR only; AR toggle hidden.
+ */
+export type CaptureSourcesMode = 'ar' | 'non-ar' | 'both';
 export type CameraLens = '1x' | '0.5x';
 export type StitchMode = 'auto' | 'panorama' | 'scans';
 export type Blender = 'multiband' | 'feather';
@@ -142,6 +154,19 @@ export interface CameraProps {
     enablePhotoMode?: boolean;
     enablePanoramaMode?: boolean;
     showSettingsButton?: boolean;
+    /**
+     * v0.13.2 — which capture sources the host allows (default `'both'`).
+     * Constrains both the runtime AR toggle and `defaultCaptureSource`:
+     *   - `'both'`  : AR + non-AR; the AR toggle is shown so the user can
+     *     switch at runtime.
+     *   - `'ar'`    : AR only.  AR toggle hidden (nothing to toggle); the
+     *     0.5× lens chooser is also hidden (ARKit/ARCore can't use the
+     *     ultra-wide), so the camera stays on the AR-capable 1× lens.
+     *   - `'non-ar'`: non-AR only.  AR toggle hidden.
+     * When set to a single source, that source wins regardless of
+     * `defaultCaptureSource`.
+     */
+    captureSources?: CaptureSourcesMode;
     style?: StyleProp<ViewStyle>;
     /**
      * Which incremental stitcher engine to drive.  Default
@@ -256,22 +281,6 @@ export interface CameraProps {
      * `flash` prop) can opt out by setting this to `false`.
      */
     showFlashButton?: boolean;
-    /**
-     * v0.13.0 — show the built-in IncrementalPanGuide ("keep the
-     * arrow on the line" drift marker) while recording.  Defaults
-     * to `true`.  The guide is gyroscope-driven and only active
-     * during the recording phase (no idle sensor cost).  Hosts that
-     * want their own pan-guide chrome can opt out via `false`.
-     */
-    panGuide?: boolean;
-    /**
-     * v0.13.0 — show the built-in PanoramaGuidance pan-speed pill
-     * ("Pan slowly" / "Slow down" / "Too fast") while recording.
-     * Defaults to `true`.  Gyroscope-driven, only active during
-     * recording.  Hosts that want their own speed chrome can opt
-     * out via `false`.
-     */
-    panoramaGuidance?: boolean;
     /**
      * v0.13.0 — built-in CaptureHeader title.  When set, `<Camera>`
      * renders a top-of-screen header showing this title (centred)
@@ -476,4 +485,50 @@ export interface CameraProps {
  * The public `<Camera>` component.
  */
 export declare function Camera(props: CameraProps): React.JSX.Element;
+/**
+ * v0.12.0 — JS edge corresponding to the physical home-indicator
+ * side of the device.  This is where the shutter + controls anchor
+ * to so they're always within thumb reach of the user's grip
+ * (matching iOS Camera's behaviour).
+ *
+ * Combines two signals:
+ *   - `jsLandscape`: whether the OS rotated the framebuffer.  True
+ *     only for non-locked hosts in device-landscape.
+ *   - `deviceOrient`: physical device orientation from the sensor.
+ *
+ * Truth table:
+ *   | jsLandscape | deviceOrient        | edge   |
+ *   |---           |---                  |---     |
+ *   | false        | any                 | bottom | (portrait JS coords —
+ *   |              |                     |        |  device-bottom = JS-bottom
+ *   |              |                     |        |  in both locked and
+ *   |              |                     |        |  non-locked-portrait)
+ *   | true         | landscape-left      | right  | (screen rotated, home
+ *   |              |                     |        |  indicator on user-right)
+ *   | true         | landscape-right     | left   | (mirror)
+ *
+ * Caveats:
+ *   - Non-locked + upside-down doesn't surface JS-top here because
+ *     upside-down doesn't change window dimensions; we can't
+ *     distinguish locked-portrait-with-device-flipped from
+ *     non-locked-portrait-with-screen-flipped-180°.  Defaults to
+ *     JS-bottom which matches the more common locked case.  Add
+ *     handling here when a host needs upside-down support.
+ *   - jsLandscape=true with non-landscape device shouldn't happen
+ *     in steady state — only during a transition mid-rotation.
+ *     Falls through to 'right' as a defensive default.
+ */
+type HomeIndicatorEdge = 'bottom' | 'top' | 'left' | 'right';
+declare function homeIndicatorEdge(jsLandscape: boolean, deviceOrient: DeviceOrientation): HomeIndicatorEdge;
+/**
+ * v0.12.0 — true when the anchor edge is on a side (left/right), so
+ * the band + shutter row need to be vertical strips.  Top/bottom
+ * anchors yield horizontal strips.
+ */
+declare function isSideEdge(edge: HomeIndicatorEdge): boolean;
+/** @internal test-only — see `homeIndicatorEdge`. */
+export declare const _homeIndicatorEdgeForTests: typeof homeIndicatorEdge;
+/** @internal test-only — see `isSideEdge`. */
+export declare const _isSideEdgeForTests: typeof isSideEdge;
+export {};
 //# sourceMappingURL=Camera.d.ts.map