react-native-image-stitcher 0.11.1 → 0.13.0

package/dist/camera/Camera.js

@@ -83,19 +83,26 @@ const useARSession_1 = require("../ar/useARSession");
 const ARCameraView_1 = require("./ARCameraView");
 const CameraShutter_1 = require("./CameraShutter");
 const CameraView_1 = require("./CameraView");
+const CaptureHeader_1 = require("./CaptureHeader");
+const CapturePreview_1 = require("./CapturePreview");
+const CaptureThumbnailStrip_1 = require("./CaptureThumbnailStrip");
 const CaptureStatusOverlay_1 = require("./CaptureStatusOverlay");
 const CaptureDebugOverlay_1 = require("./CaptureDebugOverlay");
 const CaptureMemoryPill_1 = require("./CaptureMemoryPill");
 const CaptureKeyframePill_1 = require("./CaptureKeyframePill");
 const CaptureOrientationPill_1 = require("./CaptureOrientationPill");
 const CaptureStitchStatsToast_1 = require("./CaptureStitchStatsToast");
+const IncrementalPanGuide_1 = require("./IncrementalPanGuide");
 const PanoramaBandOverlay_1 = require("./PanoramaBandOverlay");
+const PanoramaGuidance_1 = require("./PanoramaGuidance");
 const PanoramaSettingsBridge_1 = require("./PanoramaSettingsBridge");
 const PanoramaSettingsModal_1 = require("./PanoramaSettingsModal");
 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,11 +277,25 @@ 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, flash: controlledFlash, onFlashChange, showFlashButton = true, panGuide = true, panoramaGuidance = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, 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);
+    // v0.13.0 — flash state.  Controlled by `controlledFlash` when the
+    // host supplies the `flash` prop; otherwise owned internally and
+    // toggled by the built-in flash button.  `effectiveFlash` below
+    // also forces 'off' in AR mode (ARKit / ARCore own the device's
+    // torch and don't surface it through vision-camera's pipeline).
+    const [internalFlash, setInternalFlash] = (0, react_1.useState)('off');
     const [settings, setSettings] = (0, react_1.useState)(() => (0, buildPanoramaInitialSettings_1.buildPanoramaInitialSettings)(extractPanoramaOverrides(props), (0, lowMemDevice_1.isLowMemDevice)()));
     const [settingsModalVisible, setSettingsModalVisible] = (0, react_1.useState)(false);
     const [statusPhase, setStatusPhase] = (0, react_1.useState)('idle');
@@ -435,6 +456,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 +641,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);
                 }
@@ -794,6 +878,22 @@ function Camera(props) {
     const handleARToggle = (0, react_1.useCallback)(() => {
         setArPreference((prev) => !prev);
     }, []);
+    // ── v0.13.0 — Flash control ─────────────────────────────────────
+    //
+    // `flashRequested` is what the host / built-in button asks for.
+    // `effectiveFlash` is what we actually drive into vision-camera —
+    // AR mode forces 'off' because ARKit / ARCore own AVCaptureDevice
+    // and the torch isn't exposed.  This way the button's visual state
+    // (a11y, styling) tracks `flashRequested` while the underlying
+    // camera always sees the correct value.
+    const flashRequested = controlledFlash ?? internalFlash;
+    const effectiveFlash = isAR ? 'off' : flashRequested;
+    const toggleFlash = (0, react_1.useCallback)(() => {
+        const next = flashRequested === 'on' ? 'off' : 'on';
+        if (controlledFlash == null)
+            setInternalFlash(next);
+        onFlashChange?.(next);
+    }, [flashRequested, controlledFlash, onFlashChange]);
     // ── JSX ─────────────────────────────────────────────────────────
     return (react_1.default.createElement(react_native_1.View, { style: [styles.container, style] },
         inFlightTransition ? (react_1.default.createElement(react_native_1.View, { style: [react_native_1.StyleSheet.absoluteFill, styles.transitionPlaceholder] },
@@ -805,7 +905,7 @@ function Camera(props) {
             // the very first buffered preview frame.  Android takeSnapshot
             // works either way.  Pattern matches AuditCaptureScreen.tsx
             // which has run on `video` (true) for months without issue.
-            video: true, flash: "off", style: react_native_1.StyleSheet.absoluteFill, 
+            video: true, flash: effectiveFlash, style: react_native_1.StyleSheet.absoluteFill, 
             // F8 (FrameProcessor port) — host-supplied worklet runs on
             // the camera producer thread for every frame.  Only wired
             // in non-AR mode; AR mode uses ARCameraView which doesn't
@@ -826,27 +926,136 @@ function Camera(props) {
                 onError?.(new CameraError('VISION_CAMERA_RUNTIME', `${codeStr}: ${msg}`, err));
             } })),
         react_1.default.createElement(CaptureStatusOverlay_1.CaptureStatusOverlay, { phase: statusPhase, topInset: insets.top, recordingStartedAt: recordingStartedAt ?? undefined }),
+        panGuide && (react_1.default.createElement(IncrementalPanGuide_1.IncrementalPanGuide, { active: statusPhase === 'recording' })),
+        panoramaGuidance && (react_1.default.createElement(PanoramaGuidance_1.PanoramaGuidance, { active: statusPhase === 'recording' })),
         settings.debug && (react_1.default.createElement(react_1.default.Fragment, null,
             react_1.default.createElement(CaptureOrientationPill_1.CaptureOrientationPill, { orientation: deviceOrientation, topInset: insets.top }),
             react_1.default.createElement(CaptureKeyframePill_1.CaptureKeyframePill, { state: incrementalState, topInset: insets.top }),
             react_1.default.createElement(CaptureMemoryPill_1.CaptureMemoryPill, { topInset: insets.top }),
             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, { style: styles.bottomBarLeft }),
+        headerTitle != null ? (react_1.default.createElement(react_native_1.View, { style: styles.headerWrap, pointerEvents: "box-none" },
+            react_1.default.createElement(CaptureHeader_1.CaptureHeader, { title: headerTitle, onBack: onHeaderBack, backLabel: headerBackLabel, guidance: headerGuidance, colors: headerColors, topInset: insets.top, onSettingsPress: showSettingsButton
+                    ? () => setSettingsModalVisible(true)
+                    : undefined }))) : (showSettingsButton && (react_1.default.createElement(SettingsButton, { topInset: insets.top, onPress: () => setSettingsModalVisible(true) }))),
+        thumbnails != null && statusPhase !== 'recording' && (react_1.default.createElement(react_native_1.View, { style: styles.thumbnailStripWrap, pointerEvents: "box-none" },
+            react_1.default.createElement(CaptureThumbnailStrip_1.CaptureThumbnailStrip, { items: thumbnails, minPhotos: thumbnailsMin, maxPhotos: thumbnailsMax, onItemPress: onThumbnailPress }))),
+        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 }, showFlashButton && (react_1.default.createElement(react_native_1.Pressable, { onPress: isAR ? undefined : toggleFlash, accessibilityRole: "button", accessibilityLabel: isAR ? 'Flash unavailable in AR mode' : `Flash ${flashRequested === 'on' ? 'on' : 'off'}`, accessibilityState: { selected: flashRequested === 'on', disabled: isAR }, disabled: isAR, hitSlop: 8, style: [
+                        styles.flashButton,
+                        flashRequested === 'on' && !isAR && styles.flashButtonActive,
+                        isAR && styles.flashButtonDisabled,
+                    ] },
+                    react_1.default.createElement(react_native_1.Text, { style: styles.flashIcon }, "\u26A1")))),
                 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) }),
+        react_1.default.createElement(CapturePreview_1.CapturePreview, { visible: capturePreview != null, imageUri: capturePreview?.imageUri ?? '', imageWidth: capturePreview?.imageWidth, imageHeight: capturePreview?.imageHeight, title: capturePreview?.title, actions: capturePreviewActions, onClose: onCapturePreviewClose ?? noop })));
 }
 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,
@@ -876,6 +1085,8 @@ const styles = react_native_1.StyleSheet.create({
     },
     bottomBarLeft: {
         flex: 1,
+        alignItems: 'flex-start',
+        justifyContent: 'flex-end',
     },
     bottomBarCenter: {
         flex: 1,
@@ -889,5 +1100,35 @@ const styles = react_native_1.StyleSheet.create({
     shutterWrap: {
         marginTop: 12,
     },
+    headerWrap: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+    },
+    thumbnailStripWrap: {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom: 160,
+    },
+    flashButton: {
+        width: 44,
+        height: 44,
+        borderRadius: 22,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: 'rgba(0,0,0,0.45)',
+    },
+    flashButtonActive: {
+        backgroundColor: '#ffd34d',
+    },
+    flashButtonDisabled: {
+        opacity: 0.35,
+    },
+    flashIcon: {
+        fontSize: 20,
+        color: '#ffffff',
+    },
 });
 //# sourceMappingURL=Camera.js.map

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

package/dist/camera/PanoramaBandOverlay.d.ts

@@ -70,6 +70,18 @@ import type { IncrementalState } from '../stitching/incremental';
  */
 export type BandCaptureOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
 export interface PanoramaBandOverlayProps {
+    /**
+     * v0.12.0 — `true` when the band should render as a vertical
+     * column in JS (anchor edge is JS-left or JS-right, i.e.
+     * non-locked host with device-landscape).  `false` (default)
+     * renders the legacy horizontal strip — covers portrait-locked
+     * hosts in any device orientation AND non-locked hosts in
+     * portrait.  The flagship `<Camera>` derives this from
+     * `useWindowDimensions()` + `useDeviceOrientation()` (see
+     * `homeIndicatorEdge` in `Camera.tsx`); Layer-2 hosts pass it
+     * directly.
+     */
+    vertical?: boolean;
     /**
      * Latest engine state.  Pass `useIncrementalStitcher().state`.
      * Used for single-thumb fallback URI and fill-ratio when no
@@ -103,5 +115,5 @@ export interface PanoramaBandOverlayProps {
      */
     captureOrientation?: BandCaptureOrientation;
 }
-export declare function PanoramaBandOverlay({ state, frameUris, captureOrientation, }: PanoramaBandOverlayProps): React.JSX.Element | null;
+export declare function PanoramaBandOverlay({ state, frameUris, captureOrientation, vertical, }: PanoramaBandOverlayProps): React.JSX.Element | null;
 //# sourceMappingURL=PanoramaBandOverlay.d.ts.map