react-native-image-stitcher 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -16,6 +16,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-05-28
+
+### Added — Orientation-aware `<Camera>` (R2-lite)
+
+`<Camera>` now works correctly under both portrait-locked and
+non-locked iOS hosts.  Pre-v0.12 the component assumed the host
+had restricted `UISupportedInterfaceOrientations` to Portrait;
+removing that restriction broke control layout, camera-preview
+rotation across modal close, and panorama capture mode selection.
+
+Five coupled changes:
+
+1. **`useOrientationDrift` hook + `OrientationDriftModal`**
+   (PR-1).  Snapshots device orientation at capture start and
+   latches a `drifted: true` flag if the user rotates mid-
+   capture.  The incremental engine doesn't support cross-
+   orientation captures (per the engine spec at
+   `incremental.ts:373-403`), so `<Camera>` auto-cancels via
+   `incremental.cancel()` and shows the modal to explain.
+
+2. **New `onCaptureAbandoned` prop** on `<Camera>`.  Fires when
+   the SDK auto-cancels an in-flight capture.  Currently the only
+   reason is `'orientation-drift'`; the union signature keeps the
+   prop stable for future reasons (low memory, etc.).
+
+3. **4-way home-indicator-edge anchor** for the bottom-controls
+   row (Layer A).  Combines `useWindowDimensions()` and
+   `useDeviceOrientation()` to compute the JS edge that
+   corresponds to the device's home-indicator side, then anchors
+   shutter / lens / AR toggle there.  Matches iOS Camera's
+   behaviour: shutter stays within thumb reach regardless of tilt.
+
+4. **AR `takePhoto` orientation parameter** (Fix #2).  Pre-v0.12
+   `RNSARSession.takePhoto` hardcoded `.right` (90° CW) to
+   rotate ARKit's sensor-native landscape buffer to portrait,
+   assuming portrait hold.  Now switches on the device
+   orientation passed from `useDeviceOrientation()` so landscape
+   captures produce correctly-oriented photos.
+
+5. **Modal `supportedOrientations={[all 4]}`** on
+   `OrientationDriftModal` and `PanoramaSettingsModal`.  RN's iOS
+   `Modal` defaults to portrait-only, which force-rotates the
+   window scene when opened under a non-locked host — leaving
+   the underlying `<Camera>`'s ARSession with stale orientation
+   state on dismiss (preview rendered sideways).  Declaring all
+   four orientations keeps the window aligned through the modal
+   cycle.
+
+### Added — Comment cleanup across native + JS surfaces
+
+Stale "portrait-locked host" comments in
+`useDeviceOrientation.ts`, `incremental.ts`, `StitcherFrame.ts`,
+`OpenCVIncrementalStitcher.{h,mm}`, and
+`IncrementalFirstwinsEngine.kt` rewritten to acknowledge both
+host configurations.  Pose-derived orientation detection remains
+the single source of truth — that didn't change; the rationale
+just got more accurate.
+
+### Known follow-ups (deferred to v0.12.1 or v0.13)
+
+- Portrait + non-AR stitching can regress under fast horizontal
+  pans — likely drift detection over-firing on lateral
+  acceleration.  Needs debounce or motion-aware threshold.
+- Component-render tests (`<OrientationDriftModal>`,
+  `<PanoramaBandOverlay>` per-orientation, `<ViewportCropOverlay>`
+  per-orientation, `<Camera>` composition) need
+  `@testing-library/react-native` + a jest preset flip.  Tracked
+  for v0.12.1.
+- Portrait-upside-down landscape detection on non-locked hosts —
+  the JS dims signal is ambiguous between locked-portrait + flipped
+  device and non-locked + screen-flipped-180°.  Needs a separate
+  signal.
+- Slot/hybrid API on `<Camera>` to absorb `CaptureControlsBar`,
+  `IncrementalPanGuide`, `PanoramaGuidance`, etc. — v0.13.
+
 ## [0.11.1] — 2026-05-28
 
 ### Fixed — AR-mode composed worklets silently throw

package/README.md

@@ -140,6 +140,34 @@ See `src/camera/Camera.tsx` for the full TSDoc.  Highlights:
 | `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.). |
 
+## 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.
+
+**Mid-capture rotation safety** — the incremental engine doesn't
+support cross-orientation captures (a portrait capture's keyframes
+can't be mixed with landscape-pan frames).  If the user rotates
+mid-capture, `<Camera>` auto-abandons via `incremental.cancel()`,
+fires `onCaptureAbandoned('orientation-drift')` if the host wired
+the callback, and shows the `OrientationDriftModal` to explain why.
+Host opt-in via the `onCaptureAbandoned` prop — the default UX is
+the modal alone.
+
 ## Lens ↔ AR interaction
 
 | Action | `arPreference` | `lens` | UI |

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

@@ -38,8 +38,9 @@ import kotlin.math.sqrt
  *   V12.4 — central 70% (pan) × 85% (perpendicular) post-warp crop
  *   V12.6 — orientation detection from R_panToCam at first frame
  *           (NOT from JS-passed frameRotationDegrees, which is wrong
- *           under iOS interface-orientation lock — Android equivalent
- *           is screen-orientation lock; same fix applies)
+ *           under portrait-locked hosts — pose-derived detection
+ *           works regardless of host orientation config, so it's
+ *           the single source of truth)
  *   V12.7 — rectilinear path: skip cylindrical warp entirely.  First
  *           frame pasted raw onto canvas; subsequent frames contribute
  *           a narrow central strip placed by pose-delta around the

package/dist/camera/ARCameraView.d.ts

@@ -60,6 +60,16 @@ export interface ARCameraViewHandle {
      */
     takePhoto: (options?: {
         quality?: number;
+        /**
+         * v0.12.0 — device orientation at capture time, used to bake
+         * correct rotation into the saved JPEG.  Pass the value from
+         * `useDeviceOrientation()`.  Defaults to `'portrait'` on the
+         * native side if omitted (preserves pre-v0.12 behavior).
+         * Without this, AR-mode photos taken in landscape come out
+         * sideways because the native side previously hardcoded the
+         * rotate-to-portrait assumption.
+         */
+        orientation?: 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
     }) => Promise<{
         path: string;
         width: number;

package/dist/camera/ARCameraView.js

@@ -90,6 +90,7 @@ exports.ARCameraView = (0, react_1.forwardRef)(function ARCameraView({ style, gu
             return native.takePhoto({
                 path: '',
                 quality: options.quality ?? 90,
+                orientation: options.orientation ?? 'portrait',
             });
         },
         startRecording: (options) => {

package/dist/camera/Camera.d.ts

@@ -191,6 +191,26 @@ export interface CameraProps {
     onLensChange?: (lens: CameraLens) => void;
     onFramesDropped?: (info: FramesDroppedInfo) => void;
     onError?: (err: CameraError) => void;
+    /**
+     * v0.12.0 — fires when the SDK auto-abandons an in-progress
+     * capture without producing output.  `reason` is a string union
+     * so future reasons (network loss, low memory, etc.) can be added
+     * without breaking the callback signature.
+     *
+     * Currently the only reason in v0.12 is `'orientation-drift'`:
+     * the user rotated the device between Mode A (landscape + vertical
+     * pan) and Mode B (portrait + horizontal pan) mid-capture.  The
+     * engine docstring at `incremental.ts:373-403` is explicit that
+     * cross-mode capture is "best-effort, not supported," so the SDK
+     * decisively cancels the capture (`incremental.cancel()`) and
+     * surfaces `OrientationDriftModal` to explain what happened.
+     *
+     * Hosts use this callback to clean up their own state (e.g., reset
+     * a wizard step, log telemetry, surface their own retry UX in
+     * addition to the SDK's built-in modal).  No `onCapture` will fire
+     * for an abandoned capture.
+     */
+    onCaptureAbandoned?: (reason: 'orientation-drift') => void;
     /**
      * Optional host-supplied vision-camera frame processor.
      *

package/dist/camera/Camera.js

@@ -96,6 +96,8 @@ const buildPanoramaInitialSettings_1 = require("./buildPanoramaInitialSettings")
 const lowMemDevice_1 = require("./lowMemDevice");
 const useCapture_1 = require("./useCapture");
 const useDeviceOrientation_1 = require("./useDeviceOrientation");
+const useOrientationDrift_1 = require("./useOrientationDrift");
+const OrientationDriftModal_1 = require("./OrientationDriftModal");
 const incremental_1 = require("../stitching/incremental");
 const useFrameProcessorDriver_1 = require("../stitching/useFrameProcessorDriver");
 const useIncrementalStitcher_1 = require("../stitching/useIncrementalStitcher");
@@ -270,8 +272,16 @@ function extractPanoramaOverrides(props) {
  * The public `<Camera>` component.
  */
 function Camera(props) {
-    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', } = props;
+    const { defaultCaptureSource = 'ar', defaultLens = '1x', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', } = props;
     const insets = (0, react_native_safe_area_context_1.useSafeAreaInsets)();
+    // v0.12.0 — JS-layout orientation independent of device-physical.
+    // `useWindowDimensions().width > height` tells us if the OS
+    // rotated the framebuffer (only happens for non-locked hosts in
+    // device-landscape).  Combined with `useDeviceOrientation()` to
+    // pick the JS edge corresponding to the home-indicator side of
+    // the device — see `homeIndicatorEdge` below.
+    const jsWindow = (0, react_native_1.useWindowDimensions)();
+    const jsLandscape = jsWindow.width > jsWindow.height;
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
     const [lens, setLens] = (0, react_1.useState)(defaultLens);
@@ -435,6 +445,62 @@ function Camera(props) {
     // Safety: stop the driver if the component unmounts mid-recording.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     (0, react_1.useEffect)(() => () => { fpDriver.stop(); }, []);
+    // ── v0.12.0 — Orientation drift detection + auto-abandon ────────
+    //
+    // The incremental engine supports both portrait (Mode B, horizontal
+    // pan) and landscape (Mode A, vertical pan) capture as first-class,
+    // but the docstring at `incremental.ts:373-403` is explicit that
+    // mixing them mid-capture is "best-effort, not supported" — the
+    // output rotation becomes ambiguous and the stitched panorama is
+    // malformed.  v0.12 protects against this by snapshotting the
+    // orientation at `start()` and auto-cancelling the capture the
+    // instant the user rotates to a different orientation mid-flight.
+    //
+    // The modal is informational only — by the time it renders, the
+    // capture is already stopped.  No Continue/Resume affordance per
+    // the engine spec.
+    const drift = (0, useOrientationDrift_1.useOrientationDrift)(statusPhase === 'recording');
+    const [driftModalDismissed, setDriftModalDismissed] = (0, react_1.useState)(false);
+    // Reset the dismissed flag when a new capture starts (or any non-
+    // recording state) so the next drift event surfaces a fresh modal.
+    (0, react_1.useEffect)(() => {
+        if (statusPhase !== 'recording')
+            setDriftModalDismissed(false);
+    }, [statusPhase]);
+    (0, react_1.useEffect)(() => {
+        if (!drift.drifted || statusPhase !== 'recording')
+            return;
+        // Auto-abandon the in-flight capture.  Order matches handleHoldEnd's
+        // "stitch" path but skips finalize:
+        //   1. Stop pumping frames so no new keyframes arrive mid-cancel.
+        //   2. Tell the native engine to drop accumulated state
+        //      (`incremental.cancel()`).
+        //   3. Reset statusPhase back to idle.
+        //   4. Notify the host via `onCaptureAbandoned`.
+        //
+        // Wrapped in an IIFE because useEffect callbacks can't be async
+        // directly.  Errors from `incremental.cancel()` are caught + sent
+        // through `onError` — abandonment must succeed even if the engine
+        // is in a weird state.
+        void (async () => {
+            fpDriver.stop();
+            try {
+                await incremental.cancel();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                onError?.(new CameraError('PANORAMA_FINALIZE_FAILED', `cancel after orientation drift failed: ${message}`, err));
+            }
+            finally {
+                setStatusPhase('idle');
+                setRecordingStartedAt(null);
+                onCaptureAbandoned?.('orientation-drift');
+            }
+        })();
+        // Deps: re-run whenever drift latches OR recording state changes.
+        // Other deps are stable refs / setters.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [drift.drifted, statusPhase]);
     // v0.8.0 Phase 5 / v0.11.0 — frameProcessor prop semantics:
     //
     //   - Host supplied? → use host's processor.  The host's worklet
@@ -564,7 +630,14 @@ function Camera(props) {
                 // ARCameraView writes to its own tmp location; relocate to
                 // photoOutputPath via the native FileBridge so both branches
                 // return paths under the same dir.
-                const photo = await arViewRef.current.takePhoto({ quality: 90 });
+                // v0.12.0 — pass deviceOrientation so the AR takePhoto's
+                // native CIImage rotation matches the user's view.  Pre-
+                // v0.12 the native side hardcoded portrait, so landscape
+                // photos came out sideways.
+                const photo = await arViewRef.current.takePhoto({
+                    quality: 90,
+                    orientation: deviceOrientation,
+                });
                 try {
                     await (0, files_1.moveFile)(photo.path, photoOutputPath);
                 }
@@ -833,20 +906,116 @@ function Camera(props) {
             react_1.default.createElement(CaptureDebugOverlay_1.CaptureDebugOverlay, { incrementalState: incrementalState, imuTranslationMetres: isNonAR ? imuGate.getTranslationMetres() : null, captureSource: effectiveCaptureSource, frameSelectionMode: settings.frameSelection.mode, stitchMode: settings.stitcher.stitchMode }))),
         react_1.default.createElement(CaptureStitchStatsToast_1.CaptureStitchStatsToast, { message: stitchToast.message, topInset: insets.top }),
         showSettingsButton && (react_1.default.createElement(SettingsButton, { topInset: insets.top, onPress: () => setSettingsModalVisible(true) })),
-        react_1.default.createElement(react_native_1.View, { pointerEvents: "box-none", style: [styles.bottomArea, { paddingBottom: insets.bottom + 12 }] },
-            statusPhase === 'recording' && (react_1.default.createElement(PanoramaBandOverlay_1.PanoramaBandOverlay, { state: incrementalState, frameUris: batchKeyframeThumbnails, captureOrientation: deviceOrientation })),
-            react_1.default.createElement(react_native_1.View, { style: styles.bottomBar },
+        react_1.default.createElement(react_native_1.View, { pointerEvents: "box-none", style: bottomAreaStyleForEdge(homeIndicatorEdge(jsLandscape, deviceOrientation), insets.bottom + 12, insets.top + 12) },
+            statusPhase === 'recording' && (react_1.default.createElement(PanoramaBandOverlay_1.PanoramaBandOverlay, { state: incrementalState, frameUris: batchKeyframeThumbnails, captureOrientation: deviceOrientation, vertical: isSideEdge(homeIndicatorEdge(jsLandscape, deviceOrientation)) })),
+            react_1.default.createElement(react_native_1.View, { style: bottomBarStyleForEdge(homeIndicatorEdge(jsLandscape, deviceOrientation)) },
                 react_1.default.createElement(react_native_1.View, { style: styles.bottomBarLeft }),
                 react_1.default.createElement(react_native_1.View, { style: styles.bottomBarCenter },
                     react_1.default.createElement(LensChip, { lens: lens, onChange: handleLensChange, has0_5x: has0_5x }),
                     react_1.default.createElement(react_native_1.View, { style: styles.shutterWrap },
                         react_1.default.createElement(CameraShutter_1.CameraShutter, { onTap: handleTap, onHoldStart: enablePanoramaMode ? handleHoldStart : noop, onHoldComplete: enablePanoramaMode ? handleHoldEnd : noop, isProcessing: statusPhase === 'stitching', disabled: statusPhase === 'stitching' }))),
                 react_1.default.createElement(react_native_1.View, { style: styles.bottomBarRight }, lens === '1x' && isARSupportedOnDevice && (react_1.default.createElement(ARToggle, { arEnabled: arPreference, onToggle: handleARToggle }))))),
-        react_1.default.createElement(PanoramaSettingsModal_1.PanoramaSettingsModal, { visible: settingsModalVisible, settings: settings, onChange: setSettings, onClose: () => setSettingsModalVisible(false) })));
+        react_1.default.createElement(PanoramaSettingsModal_1.PanoramaSettingsModal, { visible: settingsModalVisible, settings: settings, onChange: setSettings, onClose: () => setSettingsModalVisible(false) }),
+        react_1.default.createElement(OrientationDriftModal_1.OrientationDriftModal, { visible: drift.drifted && !driftModalDismissed, captureOrientation: drift.captureOrientation, currentOrientation: drift.currentOrientation, onAcknowledge: () => setDriftModalDismissed(true) })));
 }
 function noop() {
     /* no-op handler used when panorama mode is disabled */
 }
+function homeIndicatorEdge(jsLandscape, deviceOrient) {
+    if (!jsLandscape)
+        return 'bottom';
+    if (deviceOrient === 'landscape-left')
+        return 'right';
+    if (deviceOrient === 'landscape-right')
+        return 'left';
+    return 'right';
+}
+/**
+ * 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.
+ */
+function isSideEdge(edge) {
+    return edge === 'left' || edge === 'right';
+}
+/**
+ * v0.12.0 — bottom-controls outer container positioning.  Anchors
+ * to the home-indicator JS edge with the appropriate flex direction
+ * so the band sits on the viewport side of the shutter (toward the
+ * camera preview centre).
+ */
+function bottomAreaStyleForEdge(edge, bottomInsetPx, topInsetPx) {
+    switch (edge) {
+        case 'bottom':
+            // Band above shutter row, both at JS-bottom.  JSX order
+            // [band, shutter] + flexDirection 'column' = band at top of
+            // stack (closer to screen centre), shutter at JS-bottom.
+            return {
+                position: 'absolute',
+                left: 0,
+                right: 0,
+                bottom: 0,
+                flexDirection: 'column',
+                alignItems: 'stretch',
+                paddingBottom: bottomInsetPx,
+            };
+        case 'top':
+            // Mirror of bottom.  column-reverse so JSX [band, shutter]
+            // renders [shutter, band] in JS, shutter at JS-top, band
+            // below it (toward screen centre).
+            return {
+                position: 'absolute',
+                left: 0,
+                right: 0,
+                top: 0,
+                flexDirection: 'column-reverse',
+                alignItems: 'stretch',
+                paddingTop: topInsetPx,
+            };
+        case 'right':
+            // Band to the left of shutter column, both at JS-right.
+            // flexDirection 'row' + JSX [band, shutter] = band at JS-left
+            // of container (screen centre side), shutter at JS-right.
+            return {
+                position: 'absolute',
+                top: 0,
+                bottom: 0,
+                right: 0,
+                flexDirection: 'row',
+                alignItems: 'stretch',
+                paddingRight: 12,
+            };
+        case 'left':
+            // Mirror of right.  row-reverse so JSX [band, shutter] gives
+            // band at JS-right (screen centre side), shutter at JS-left.
+            return {
+                position: 'absolute',
+                top: 0,
+                bottom: 0,
+                left: 0,
+                flexDirection: 'row-reverse',
+                alignItems: 'stretch',
+                paddingLeft: 12,
+            };
+    }
+}
+/**
+ * v0.12.0 — inner shutter-row flex direction.  Horizontal row for
+ * top/bottom anchors; vertical column for left/right anchors so
+ * the three slots (lens / shutter / AR) stack along the narrow
+ * side strip.  Buttons don't rotate — touch targets and text
+ * orient correctly via either (a) un-rotated framebuffer under
+ * portrait-lock or (b) OS-rotated framebuffer under non-locked.
+ */
+function bottomBarStyleForEdge(edge) {
+    const vertical = isSideEdge(edge);
+    return {
+        flexDirection: vertical ? 'column' : 'row',
+        paddingHorizontal: vertical ? 0 : 18,
+        paddingVertical: vertical ? 18 : 0,
+        alignItems: 'center',
+    };
+}
 const styles = react_native_1.StyleSheet.create({
     container: {
         flex: 1,

package/dist/camera/OrientationDriftModal.d.ts

@@ -0,0 +1,83 @@
+/**
+ * OrientationDriftModal — informational popup shown when the SDK
+ * auto-abandons an in-progress capture because the device rotated
+ * between Mode A (landscape + vertical pan) and Mode B (portrait
+ * + horizontal pan) mid-flight.
+ *
+ * ## When this modal appears
+ *
+ * In the v0.12 `<Camera>` integration, the modal is rendered while
+ * `useOrientationDrift(active).drifted === true`.  By the time the
+ * modal renders, the capture has ALREADY been stopped (the
+ * `<Camera>` component's drift effect calls the engine's `stop()`
+ * the same render).  The modal exists solely to explain to the
+ * user what happened — no "Continue" / "Resume" affordance because
+ * the engine docstring at `incremental.ts:373-403` is explicit
+ * that cross-mode capture is "best-effort, not supported" and
+ * continuing past drift produces malformed output.
+ *
+ * ## Layer-2 host usage
+ *
+ * Hosts using `CameraView` directly (rather than the flagship
+ * `<Camera>`) can compose this modal with `useOrientationDrift`
+ * for the same auto-abandon UX:
+ *
+ *   const drift = useOrientationDrift(captureActive);
+ *   useEffect(() => {
+ *     if (drift.drifted) {
+ *       // host abandons capture (engine stop + state cleanup)
+ *       stopCapture();
+ *     }
+ *   }, [drift.drifted]);
+ *
+ *   return <>
+ *     <CameraView ... />
+ *     <OrientationDriftModal
+ *       visible={drift.drifted}
+ *       captureOrientation={drift.captureOrientation}
+ *       currentOrientation={drift.currentOrientation}
+ *       onAcknowledge={dismissDriftModal}
+ *     />
+ *   </>;
+ *
+ * ## Accessibility
+ *
+ * Modal `role` defaults to RN's native dialog handling.  The OK
+ * button carries an `accessibilityRole='button'` + label.  Body
+ * text uses `accessibilityRole='text'` so the orientation summary
+ * is read by VoiceOver / TalkBack.
+ */
+import React from 'react';
+import { type DeviceOrientation } from './useDeviceOrientation';
+export interface OrientationDriftModalProps {
+    /**
+     * Show / hide.  In the `<Camera>` integration this is driven by
+     * the latched `drifted` flag from `useOrientationDrift`.
+     */
+    visible: boolean;
+    /**
+     * Orientation the capture started in.  Shown in the body copy
+     * ("Capture started in PORTRAIT") so the user understands the
+     * baseline.  `undefined` is tolerated (the modal hides the line);
+     * the prop is optional only to mirror `useOrientationDrift`'s
+     * return shape (which has `undefined` when inactive).  When the
+     * modal is `visible`, drift detection means this was non-
+     * undefined at the moment the flag latched — so undefined here
+     * is unlikely in practice.
+     */
+    captureOrientation: DeviceOrientation | undefined;
+    /**
+     * Current device orientation.  Shown in the body copy ("now
+     * LANDSCAPE-LEFT") so the user understands what changed.
+     */
+    currentOrientation: DeviceOrientation;
+    /**
+     * Tapped when the user dismisses with OK.  By the time the
+     * modal renders the capture is already stopped; this callback
+     * exists only to clear the latched drift state so the next
+     * capture can start fresh.
+     */
+    onAcknowledge: () => void;
+}
+export declare function OrientationDriftModal(props: OrientationDriftModalProps): React.JSX.Element;
+//# sourceMappingURL=OrientationDriftModal.d.ts.map

package/dist/camera/OrientationDriftModal.js

@@ -0,0 +1,159 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * OrientationDriftModal — informational popup shown when the SDK
+ * auto-abandons an in-progress capture because the device rotated
+ * between Mode A (landscape + vertical pan) and Mode B (portrait
+ * + horizontal pan) mid-flight.
+ *
+ * ## When this modal appears
+ *
+ * In the v0.12 `<Camera>` integration, the modal is rendered while
+ * `useOrientationDrift(active).drifted === true`.  By the time the
+ * modal renders, the capture has ALREADY been stopped (the
+ * `<Camera>` component's drift effect calls the engine's `stop()`
+ * the same render).  The modal exists solely to explain to the
+ * user what happened — no "Continue" / "Resume" affordance because
+ * the engine docstring at `incremental.ts:373-403` is explicit
+ * that cross-mode capture is "best-effort, not supported" and
+ * continuing past drift produces malformed output.
+ *
+ * ## Layer-2 host usage
+ *
+ * Hosts using `CameraView` directly (rather than the flagship
+ * `<Camera>`) can compose this modal with `useOrientationDrift`
+ * for the same auto-abandon UX:
+ *
+ *   const drift = useOrientationDrift(captureActive);
+ *   useEffect(() => {
+ *     if (drift.drifted) {
+ *       // host abandons capture (engine stop + state cleanup)
+ *       stopCapture();
+ *     }
+ *   }, [drift.drifted]);
+ *
+ *   return <>
+ *     <CameraView ... />
+ *     <OrientationDriftModal
+ *       visible={drift.drifted}
+ *       captureOrientation={drift.captureOrientation}
+ *       currentOrientation={drift.currentOrientation}
+ *       onAcknowledge={dismissDriftModal}
+ *     />
+ *   </>;
+ *
+ * ## Accessibility
+ *
+ * Modal `role` defaults to RN's native dialog handling.  The OK
+ * button carries an `accessibilityRole='button'` + label.  Body
+ * text uses `accessibilityRole='text'` so the orientation summary
+ * is read by VoiceOver / TalkBack.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrientationDriftModal = OrientationDriftModal;
+const react_1 = __importDefault(require("react"));
+const react_native_1 = require("react-native");
+/**
+ * Pretty-print a `DeviceOrientation` for body copy.  Returns the
+ * uppercase form because the modal copy reads as "Capture started
+ * in PORTRAIT, now LANDSCAPE-LEFT" — uppercase orientations stand
+ * out from the surrounding lowercase sentence.
+ */
+function formatOrientation(o) {
+    switch (o) {
+        case 'portrait':
+            return 'PORTRAIT';
+        case 'portrait-upside-down':
+            return 'PORTRAIT-UPSIDE-DOWN';
+        case 'landscape-left':
+            return 'LANDSCAPE-LEFT';
+        case 'landscape-right':
+            return 'LANDSCAPE-RIGHT';
+    }
+}
+function OrientationDriftModal(props) {
+    const { visible, captureOrientation, currentOrientation, onAcknowledge } = props;
+    return (react_1.default.createElement(react_native_1.Modal, { visible: visible, transparent: true, animationType: "fade", onRequestClose: onAcknowledge, accessibilityLabel: "Capture cancelled \u2014 orientation drift", 
+        // v0.12.0 — see PanoramaSettingsModal for the same prop's
+        // rationale.  Declaring all orientations prevents iOS from
+        // force-rotating the window to portrait when this modal opens
+        // mid-rotation, which would otherwise leave the underlying
+        // <Camera>'s ARSession in a stale-orientation state on dismiss.
+        supportedOrientations: [
+            'portrait',
+            'portrait-upside-down',
+            'landscape-left',
+            'landscape-right',
+        ] },
+        react_1.default.createElement(react_native_1.View, { style: styles.backdrop },
+            react_1.default.createElement(react_native_1.View, { style: styles.card },
+                react_1.default.createElement(react_native_1.Text, { style: styles.title, accessibilityRole: "header" }, "Capture cancelled"),
+                react_1.default.createElement(react_native_1.Text, { style: styles.body, accessibilityRole: "text" }, "Rotation detected mid-capture. Please hold the device steady and try again."),
+                captureOrientation !== undefined && (react_1.default.createElement(react_native_1.Text, { style: styles.subBody, accessibilityRole: "text" },
+                    "Capture started in ",
+                    formatOrientation(captureOrientation),
+                    ", now ",
+                    formatOrientation(currentOrientation),
+                    ".")),
+                react_1.default.createElement(react_native_1.Pressable, { style: ({ pressed }) => [
+                        styles.button,
+                        pressed && styles.buttonPressed,
+                    ], onPress: onAcknowledge, accessibilityRole: "button", accessibilityLabel: "OK" },
+                    react_1.default.createElement(react_native_1.Text, { style: styles.buttonLabel }, "OK"))))));
+}
+const styles = react_native_1.StyleSheet.create({
+    backdrop: {
+        flex: 1,
+        backgroundColor: 'rgba(0, 0, 0, 0.6)',
+        alignItems: 'center',
+        justifyContent: 'center',
+        paddingHorizontal: 32,
+    },
+    card: {
+        backgroundColor: '#1c1c1e',
+        borderRadius: 14,
+        paddingHorizontal: 20,
+        paddingVertical: 24,
+        width: '100%',
+        maxWidth: 340,
+    },
+    title: {
+        color: '#fff',
+        fontSize: 18,
+        fontWeight: '600',
+        marginBottom: 12,
+        textAlign: 'center',
+    },
+    body: {
+        color: '#e5e5ea',
+        fontSize: 15,
+        lineHeight: 21,
+        textAlign: 'center',
+        marginBottom: 12,
+    },
+    subBody: {
+        color: '#8e8e93',
+        fontSize: 13,
+        lineHeight: 18,
+        textAlign: 'center',
+        marginBottom: 20,
+    },
+    button: {
+        backgroundColor: '#0a84ff',
+        borderRadius: 10,
+        paddingVertical: 12,
+        alignItems: 'center',
+    },
+    buttonPressed: {
+        backgroundColor: '#0860c0',
+    },
+    buttonLabel: {
+        color: '#fff',
+        fontSize: 17,
+        fontWeight: '600',
+    },
+});
+//# sourceMappingURL=OrientationDriftModal.js.map