react-native-image-stitcher 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -16,6 +16,187 @@ 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)
+
+The flagship `<Camera>` now ships built-in defaults for every UX
+chrome piece previously exposed only as a Layer-2 component.  Hosts
+adopting `<Camera>` directly get a complete capture surface — flash
+button, pan-speed pill, drift-marker guide, header chrome,
+capture-history strip, and post-stitch preview — without having to
+import and wire each piece by hand.
+
+All built-ins use the opt-out pattern: enabled by default, disabled
+by setting the corresponding boolean to `false` or by omitting the
+corresponding payload prop.  Hosts that want their own chrome can
+opt out per piece and layer custom UI on top of `<Camera>` (the
+Layer-2 components remain exported and are unchanged).
+
+#### Flash control
+
+- `flash?: 'on' | 'off'` — controlled torch state.  Omit to let
+  `<Camera>` own it internally.
+- `onFlashChange?` — fires on tap (controlled and uncontrolled both).
+- `showFlashButton?: boolean` (default `true`) — built-in flash button
+  in the bottom-left slot.  AR mode auto-disables (ARKit / ARCore own
+  the device's torch; surfaces "Flash unavailable in AR mode" a11y
+  label and greyed styling).
+
+#### Pan guidance
+
+- `panGuide?: boolean` (default `true`) — built-in
+  `IncrementalPanGuide` ("keep the arrow on the line" drift marker).
+- `panoramaGuidance?: boolean` (default `true`) — built-in
+  `PanoramaGuidance` pan-speed pill.
+- Both are gyroscope-driven and only subscribe to the sensor while
+  recording — no idle cost.
+
+#### Header
+
+- `headerTitle?: string` — when set, renders a built-in
+  `CaptureHeader` at the top of the screen.  The existing settings
+  gear is absorbed into the header's right side (no duplicate gear).
+- `onHeaderBack?`, `headerBackLabel?`, `headerGuidance?`,
+  `headerColors?` — pass-through to `CaptureHeader`.
+
+#### Capture history + preview
+
+- `thumbnails?: CaptureThumbnailItem[]` — when supplied (even `[]`),
+  renders the built-in `CaptureThumbnailStrip` above the bottom
+  controls.  Hidden during recording so it doesn't overlap the
+  panorama band overlay.
+- `thumbnailsMin?`, `thumbnailsMax?` — count-line hints.
+- `onThumbnailPress?` — replaces the strip's built-in
+  tap-to-preview modal with a host handler.
+- `capturePreview?` — when set, renders a built-in `CapturePreview`
+  modal showing the supplied image.  Use for post-stitch
+  confirmation; the host clears the prop on dismiss via
+  `onCapturePreviewClose`.
+- `capturePreviewActions?` — pass-through action buttons for the
+  preview modal.
+
+### Migration
+
+- Hosts that were importing Layer-2 components (`CaptureHeader`,
+  `CaptureControlsBar`, `IncrementalPanGuide`, `PanoramaGuidance`,
+  `CaptureThumbnailStrip`, `CapturePreview`) directly can now drop
+  those imports and use the corresponding `<Camera>` props.
+- The Layer-2 components remain exported and unchanged in v0.13 for
+  backward compatibility.  Deprecation of those exports is targeted
+  for v0.14.
+- No behaviour change for hosts that already use `<Camera>` and
+  don't supply any of the new props — every new built-in defaults
+  to the previous (omitted) UX, except the flash button which
+  appears in the now-occupied bottom-left slot.  Hosts that previously
+  rendered chrome in that slot above `<Camera>` can pass
+  `showFlashButton={false}`.
+
 ## [0.12.0] — 2026-05-28
 
 ### Added — Orientation-aware `<Camera>` (R2-lite)

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