react-native-image-stitcher 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -16,6 +16,121 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.1] — 2026-06-01
+
+### Docs
+
+- Refresh the npm README for the v0.14 API: full `<Camera>` prop
+  reference (incl. `captureSources`), a complete capture-screen sample,
+  the portrait recommendation, and a 0.13.x → 0.14 migration note. (The
+  0.14.0 tarball shipped before this refresh landed; no code change.)
+- Add a Docusaurus docs site (published to GitHub Pages).
+
+## [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

@@ -8,10 +8,10 @@ AR-backed and IMU-fallback capture paths.
 
 | Feature | Behaviour |
 |---|---|
-| **Tap shutter** | Single photo via vision-camera's `takePhoto` (non-AR) or `ARFrame.capturedImage` (AR). |
+| **Tap shutter** | Single photo via vision-camera's `takePhoto` (non-AR) or ARCore/ARKit `capturedImage` (AR). |
 | **Hold shutter** | Panorama capture — pan and release.  Engine accumulates keyframes; stitches via `cv::Stitcher::PANORAMA` (or `SCANS` if the pose suggests a flat-translation scan). |
-| **Lens chip** | 1× / 0.5× toggle above the shutter.  Selecting 0.5× forces non-AR (AR sessions can't switch physical lenses mid-session). |
-| **AR toggle** | Bottom-right corner, conditional on the 1× lens.  Toggles between AR-pose-driven and IMU-driven capture paths. |
+| **Lens chip** | 1× / 0.5× toggle next to the shutter.  Shown only when the device actually has a usable ultra-wide (real capability detection, v0.14).  Hidden entirely in AR-only mode (`captureSources="ar"`). |
+| **Flash & AR pills** | Top-right pill stack, under the settings gear.  Flash toggles the torch (hidden on torchless lenses, e.g. a standalone ultra-wide).  AR pill toggles AR ↔ non-AR — shown only when `captureSources="both"` and the device supports AR. |
 | **Internal settings panel** | Opt-in gear icon (top-right) via `showSettingsButton` prop.  Exposes blender, seam finder, warper, flow-gate tunables — useful for internal testers; hidden from public consumers by default. |
 
 ## Installation
@@ -65,6 +65,15 @@ cd android && ./gradlew :app:assembleDebug   # Android
 
 ## Quick start
 
+> **Orientation: use portrait.** `<Camera>` is designed and tuned for
+> portrait capture. On Android it self-locks to portrait; on iOS,
+> portrait-only is the recommended host `Info.plist` configuration.
+> See [Orientation support](#orientation-support) for the full story
+> (landscape *is* supported on iOS if you need it).
+
+The minimum: resolve camera permission, then mount `<Camera>` with an
+`onCapture` handler.
+
 ```tsx
 import {
   Camera,
@@ -81,83 +90,244 @@ export function CaptureScreen() {
         'Panorama:',
         result.uri,
         `${result.framesIncluded}/${result.framesRequested} frames`,
+        `stitched as ${result.stitchModeResolved ?? 'n/a'}`,
       );
     }
   };
 
-  const handleError = (err: CameraError) => {
-    console.warn(err.code, err.message);
-  };
-
   return (
     <Camera
-      defaultCaptureSource="ar"
-      defaultLens="1x"
-      enablePhotoMode
-      enablePanoramaMode
       onCapture={handleCapture}
-      onError={handleError}
+      onError={(err: CameraError) => console.warn(err.code, err.message)}
     />
   );
 }
 ```
 
-## `<Camera>` props (summary)
+### A complete capture screen
 
-See `src/camera/Camera.tsx` for the full TSDoc.  Highlights:
+A realistic screen: requests permission up front, shows a capture
+history strip, opens a post-stitch preview modal, and persists the
+output to a directory you control. (The SDK does **not** request camera
+permission for you — the host owns that.)
 
-### Initial values (uncontrolled — read once at mount)
+```tsx
+import React, { useCallback, useEffect, useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { useCameraPermission } from 'react-native-vision-camera';
+import {
+  Camera,
+  type CameraCaptureResult,
+  type CameraError,
+  type CaptureThumbnailItem,
+} from 'react-native-image-stitcher';
 
-| Prop | Default | Notes |
-|---|---|---|
-| `defaultCaptureSource` | `'ar'` | `'ar'` ↔ `'non-ar'` |
-| `defaultLens` | `'1x'` | `'1x'` ↔ `'0.5x'` |
-| `defaultStitchMode` | `'auto'` | `'auto'`, `'panorama'`, `'scans'` |
-| `defaultBlender` | `'multiband'` | `'multiband'`, `'feather'` |
-| `defaultSeamFinder` | `'graphcut'` | `'graphcut'`, `'skip'` |
-| `defaultWarper` | `'plane'` | `'plane'`, `'cylindrical'`, `'spherical'` |
-| `defaultFlowNoveltyPercentile` | `0.85` | Range 0.50 – 0.99 |
-| `defaultFlowEvalEveryNFrames` | `5` | Range 1 – 10 |
-| `defaultFlowMaxTranslationCm` | `50` | 0 = disabled |
-| `defaultKeyframeMaxCount` | `6` | Range 3 – 10 |
-| `defaultKeyframeOverlapThreshold` | `0.20` | Range 0.20 – 0.60 |
+export function CaptureScreen() {
+  // 1. Camera permission is a HOST concern — resolve it BEFORE mounting
+  //    <Camera>. (Android treats unrequested permissions as denied even
+  //    when declared in the manifest, so the explicit call is required.)
+  const { hasPermission, requestPermission } = useCameraPermission();
+  useEffect(() => {
+    if (!hasPermission) requestPermission().catch(() => undefined);
+  }, [hasPermission, requestPermission]);
+
+  // 2. Capture history (drives the built-in thumbnail strip).
+  const [thumbnails, setThumbnails] = useState<CaptureThumbnailItem[]>([]);
+
+  // 3. Post-stitch preview modal — set on capture, cleared on close.
+  const [preview, setPreview] = useState<CameraCaptureResult | null>(null);
+
+  const onCapture = useCallback((result: CameraCaptureResult) => {
+    setPreview(result);
+    setThumbnails((prev) => [
+      ...prev,
+      { id: String(Date.now()), uri: result.uri, width: result.width, height: result.height },
+    ]);
+  }, []);
+
+  if (!hasPermission) return <View style={styles.fill} />; // or your own "grant access" UI
+
+  return (
+    <SafeAreaProvider>
+      <View style={styles.fill}>
+        <Camera
+          // Capture-mode controls
+          defaultCaptureSource="ar"   // start in AR mode (pose-driven)
+          captureSources="both"       // allow AR + non-AR; show the AR toggle
+          enablePhotoMode             // tap = photo
+          enablePanoramaMode          // hold + pan = panorama
+          // Output
+          outputDir={`${/* your app dir */ ''}/captures`}
+          // Header chrome (optional)
+          headerTitle="Capture"
+          headerGuidance="Tap for a photo. Hold + pan + release for a panorama."
+          // Capture history strip
+          thumbnails={thumbnails}
+          // Post-stitch preview modal (controlled — clear it on close)
+          capturePreview={preview ? { imageUri: preview.uri } : undefined}
+          onCapturePreviewClose={() => setPreview(null)}
+          // Events
+          onCapture={onCapture}
+          onError={(err: CameraError) => console.warn(err.code, err.message)}
+          onCaptureAbandoned={(reason) => console.log('abandoned:', reason)}
+        />
+      </View>
+    </SafeAreaProvider>
+  );
+}
+
+const styles = StyleSheet.create({ fill: { flex: 1, backgroundColor: '#000' } });
+```
+
+## `<Camera>` props (full reference)
+
+Every prop is optional. `<Camera>` works with no props at all (it just
+captures and you wire `onCapture`). Props fall into seven groups.
+
+> A deeper companion reference with composition recipes lives in
+> [`docs/camera-component.md`](docs/camera-component.md). The tables
+> below are the authoritative prop list.
+
+### Capture-source & lens (uncontrolled — read once at mount)
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `defaultCaptureSource` | `'ar' \| 'non-ar'` | `'ar'` | Initial capture path. Clamped to `captureSources` (below). |
+| `captureSources` | `'ar' \| 'non-ar' \| 'both'` | `'both'` | **(v0.14)** Which sources are allowed. `'both'` shows the AR toggle. `'ar'` hides the AR toggle **and** the lens chooser (ARKit/ARCore can't use the ultra-wide). `'non-ar'` hides the AR toggle, keeps the lens chooser. A single-source value overrides a conflicting `defaultCaptureSource`. |
+| `defaultLens` | `'1x' \| '0.5x'` | `'1x'` | Initial lens. The 0.5× chooser only appears if the device actually has a usable ultra-wide (real capability detection, v0.14). |
+
+### Panorama / stitcher tunables (uncontrolled — internal-tester knobs)
+
+These mirror the in-app settings panel; most apps never set them.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `defaultStitchMode` | `'auto' \| 'panorama' \| 'scans'` | `'auto'` | `'auto'` picks PANORAMA vs SCANS from the pose at finalize. |
+| `defaultBlender` | `'multiband' \| 'feather'` | `'multiband'` | cv::Stitcher blender. |
+| `defaultSeamFinder` | `'graphcut' \| 'skip'` | `'graphcut'` | Seam finder. |
+| `defaultWarper` | `'plane' \| 'cylindrical' \| 'spherical'` | `'plane'` | Projection surface. |
+| `defaultFlowNoveltyPercentile` | `number` | `0.85` | Keyframe-gate novelty threshold (0.50–0.99). |
+| `defaultFlowEvalEveryNFrames` | `number` | `5` | Flow-gate eval cadence (1–10). |
+| `defaultFlowMaxTranslationCm` | `number` | `50` | Max IMU translation between keyframes; 0 = disabled. |
+| `defaultKeyframeMaxCount` | `number` | `6` | Keyframe cap per capture (3–10). |
+| `defaultKeyframeOverlapThreshold` | `number` | `0.20` | Min overlap to accept a keyframe (0.20–0.60). |
+| `defaultCompositingResolMP` / `defaultRegistrationResolMP` / `defaultSeamEstimationResolMP` | `number` | — | Forward-looking cv::Stitcher resolution knobs (currently no-ops). |
 
 ### UI toggles
 
-| Prop | Default | Notes |
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `enablePhotoMode` | `boolean` | `true` | Tap = photo. When false, tap is a no-op. |
+| `enablePanoramaMode` | `boolean` | `true` | Hold + pan = panorama. When false, hold is a no-op. |
+| `showSettingsButton` | `boolean` | `false` | Gear icon → internal settings panel. Internal-tester only; leave off for public consumers. |
+| `style` | `StyleProp<ViewStyle>` | — | Outer container style. |
+
+### Flash (controlled or uncontrolled)
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `flash` | `'on' \| 'off'` | — | Controlled torch state. Omit to let `<Camera>` own it internally. |
+| `onFlashChange` | `(next: 'on' \| 'off') => void` | — | Fires on flash-button tap (controlled and uncontrolled). |
+| `showFlashButton` | `boolean` | `true` | Built-in flash pill (top-right). Auto-hidden when the mounted device has no torch (e.g. a standalone ultra-wide) and in AR mode. |
+
+### Header chrome (opt-in)
+
+Setting `headerTitle` renders a built-in top header; the settings gear is absorbed into it.
+
+| Prop | Type | Notes |
 |---|---|---|
-| `enablePhotoMode` | `true` | Tap-to-photo |
-| `enablePanoramaMode` | `true` | Hold-to-pan |
-| `showSettingsButton` | `false` | Internal-tester only; OFF for public consumers |
+| `headerTitle` | `string` | Shows the header when set. |
+| `headerGuidance` | `string` | Subtitle / guidance pill under the title. |
+| `onHeaderBack` | `() => void` | Renders a back affordance when provided. |
+| `headerBackLabel` | `string` | Custom back-button label. |
+| `headerColors` | `object` | Override header colours. |
 
-### Callbacks
+### Capture history + post-stitch preview
 
-| Prop | Fires when |
-|---|---|
-| `onCapture(result)` | Photo OR panorama capture completes successfully.  `result.type` discriminates. |
-| `onCaptureSourceChange(source)` | Effective capture source changes (e.g., user toggles AR, or selecting 0.5× forces non-AR). |
-| `onLensChange(lens)` | User taps the 1×/0.5× chip. |
-| `onFramesDropped(info)` | cv::Stitcher's confidence retry loop dropped one or more input frames. |
-| `onError(err)` | Classified error.  `err.code` from a known taxonomy (`STITCH_NEED_MORE_IMGS`, `STITCH_HOMOGRAPHY_FAIL`, `STITCH_CAMERA_PARAMS_FAIL`, `STITCH_OOM`, `CAMERA_PERMISSION_DENIED`, etc.). |
+| Prop | Type | Notes |
+|---|---|---|
+| `thumbnails` | `CaptureThumbnailItem[]` | When supplied (even `[]`), renders the built-in thumbnail strip. Hidden during recording. |
+| `thumbnailsMin` / `thumbnailsMax` | `number` | Optional count-line hints (e.g. quota guidance). |
+| `onThumbnailPress` | `(item) => void` | Replaces the strip's built-in tap-to-preview with your handler. |
+| `capturePreview` | `{ imageUri; imageWidth?; imageHeight?; title? }` | When set, renders the built-in preview modal. Controlled — clear it via `onCapturePreviewClose`. |
+| `capturePreviewActions` | `CapturePreviewAction[]` | Action buttons for the preview modal (e.g. Save / Retake). |
+| `onCapturePreviewClose` | `() => void` | Fires when the preview modal is dismissed. |
 
-## Orientation support
+### Callbacks & advanced
+
+| Prop | Type | Fires / purpose |
+|---|---|---|
+| `onCapture` | `(result: CameraCaptureResult) => void` | Photo OR panorama completes. `result.type` discriminates (`'photo'` / `'panorama'`). |
+| `onCaptureSourceChange` | `(source: CaptureSource) => void` | Effective source changes (AR toggle, or 0.5× forcing non-AR). |
+| `onLensChange` | `(lens: CameraLens) => void` | User taps the 1×/0.5× chip. |
+| `onFramesDropped` | `(info: FramesDroppedInfo) => void` | cv::Stitcher's confidence retry dropped input frame(s). |
+| `onCaptureAbandoned` | `(reason: 'orientation-drift') => void` | SDK auto-cancelled an in-flight capture (currently only mid-capture rotation). |
+| `onError` | `(err: CameraError) => void` | Classified error — see codes below. |
+| `outputDir` | `string` | Directory for saved JPEGs. The lib creates it if missing. |
+| `engine` | `'batch-keyframe' \| …` | Stitching engine. Default `'batch-keyframe'`; most apps leave it. |
+| `frameProcessor` | vision-camera frame processor | Host worklet composed with first-party stitching (see [`useStitcherWorklet`](docs/camera-component.md)). Advanced. |
+
+### `CameraCaptureResult`
+
+```ts
+type CameraCaptureResult =
+  | { type: 'photo'; uri: string; width: number; height: number }
+  | { type: 'panorama'; uri: string; width: number; height: number;
+      framesRequested: number; framesIncluded: number; framesDropped: number;
+      finalConfidenceThresh: number; durationMs: number;
+      stitchModeResolved?: 'panorama' | 'scans' };
+```
+
+### `CameraError` codes
 
-`<Camera>` works in any device orientation regardless of host
-configuration.  No host setup required — the SDK adapts at runtime.
+`err.code` is one of a fixed taxonomy so you can branch (toast vs retry vs report):
+`CAMERA_PERMISSION_DENIED`, `CAMERA_DEVICE_UNAVAILABLE`, `PHOTO_CAPTURE_FAILED`,
+`PANORAMA_START_FAILED`, `PANORAMA_FINALIZE_FAILED`, `STITCH_NEED_MORE_IMGS`,
+`STITCH_HOMOGRAPHY_FAIL`, `STITCH_CAMERA_PARAMS_FAIL`, `STITCH_OOM`,
+`OUTPUT_WRITE_FAILED`, plus `VISION_CAMERA_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.
+### Migration from 0.13.x
 
-**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.
+- **Removed:** the `panGuide` and `panoramaGuidance` props (the
+  drift-marker overlay + pan-speed pill). They are no longer part of the
+  public API and `<Camera>` no longer renders them. Remove these props
+  if you were passing them — they're now a no-op type error.
+- **Added:** `captureSources` (above).
+- **Behaviour:** flash + AR controls moved to a top-right pill stack; the
+  0.5× chooser now reflects real device capability; Android self-locks to
+  portrait. No code change required for any of these.
+
+## Orientation support
+
+> **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
@@ -170,14 +340,20 @@ the modal alone.
 
 ## Lens ↔ AR interaction
 
-| Action | `arPreference` | `lens` | UI |
-|---|---|---|---|
-| Initial mount with defaults | `true` | `1x` | AR toggle ON |
-| User switches to 0.5× | unchanged (`true`) | `0.5x` | AR toggle HIDDEN, forced non-AR |
-| User switches back to 1× | unchanged (`true`) | `1x` | AR toggle visible at its previous state |
-| User taps AR toggle off (on 1×) | `false` | `1x` | AR toggle OFF |
+The lens chooser and AR toggle interact, because ARKit/ARCore sessions
+can't switch to the ultra-wide. With `captureSources="both"` (default):
 
-The component owns the runtime state; the parent persists across launches via the `on*Change` callbacks if desired.
+| Action | AR preference | Lens | UI |
+|---|---|---|---|
+| Initial mount (defaults) | on | `1×` | AR pill ON |
+| Switch to 0.5× | unchanged | `0.5×` | AR pill HIDDEN; capture forced non-AR |
+| Switch back to 1× | unchanged | `1×` | AR pill visible at its previous state |
+| Tap AR pill off (on 1×) | off | `1×` | AR pill OFF |
+
+When `captureSources` is `'ar'` or `'non-ar'`, the AR pill never shows
+(nothing to toggle), and `'ar'` additionally hides the lens chooser. The
+component owns this runtime state; persist across launches via the
+`on*Change` callbacks if desired.
 
 ## Architecture notes
 

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