react-native-image-stitcher 0.11.0 → 0.12.0

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

package/dist/camera/PanoramaBandOverlay.js

@@ -141,26 +141,50 @@ const MULTI_THUMB_HARD_CAP = 32; // safety net; host typically caps at 24
  *     reads as user-right-arrow (pointing along the horizontal pan
  *     direction).
  */
-function layoutFor(orientation) {
+function layoutFor(orientation, vertical) {
     const commonInner = {
         alignItems: 'center',
         paddingHorizontal: BAND_PADDING,
         paddingVertical: BAND_PADDING,
         backgroundColor: 'rgba(0, 0, 0, 0.55)',
     };
-    // 2026-05-19 — repositioned tethered to the shutter (no longer
-    // edge-pinned via absolute positioning).  The parent stack in
-    // Camera.tsx now puts this band in a vertical column immediately
-    // above the shutter row.  The SDK's orientation lock holds the UI
-    // in portrait regardless of physical device rotation, so the band
-    // is ALWAYS a horizontal strip in JS coordinates.  In landscape
-    // (physically held), the rendered strip visually appears as a
-    // vertical column on the viewport-side of the shutter.
+    // v0.12.0 — band structural orientation tracks the host's
+    // `vertical` flag (which the host derives from JS layout
+    // orientation):
     //
-    // What still varies by physical orientation: the order in which
-    // thumbnails should appear so newest is at the user-perceived
-    // "leading edge" of the pan.  That's the flexDirection (row vs
-    // row-reverse) and the arrow glyph.
+    //   vertical=false  Horizontal strip in JS coords.  Under
+    //                   portrait-lock + device-landscape this appears
+    //                   as a vertical column on user-right via the
+    //                   un-rotated framebuffer.
+    //   vertical=true   Vertical column in JS coords.  Non-locked
+    //                   + device-landscape — band lives along the
+    //                   JS-side strip where the home indicator is.
+    //
+    // What still varies by physical orientation regardless: the
+    // thumbnail flow direction so newest sits at the user-perceived
+    // pan-leading edge (flexDirection + arrowGlyph).
+    if (vertical) {
+        // Vertical band in JS coords (non-locked landscape).  The OS
+        // rotated the framebuffer so user-top = JS-top, user-bottom =
+        // JS-bottom — same scroll direction regardless of whether the
+        // device is landscape-left or landscape-right.  Latest grows
+        // toward user-bottom (= JS-bottom).  flexDirection 'column'
+        // puts array[0]/oldest at JS-top.
+        return {
+            kind: 'landscape',
+            band: {
+                marginHorizontal: 8,
+                marginVertical: 16,
+                width: BAND_THICKNESS,
+                flexDirection: 'column',
+                ...commonInner,
+            },
+            flexDirection: 'column',
+            arrowGlyph: '↓',
+        };
+    }
+    // vertical=false branch: pre-v0.12 horizontal-strip behavior
+    // keyed on device-physical orientation for thumbnail direction.
     if (orientation === 'landscape-left') {
         // Phone rotated 90° CCW from portrait (home indicator on the
         // user's RIGHT).  With UI orientation-locked to portrait:
@@ -221,7 +245,7 @@ function layoutFor(orientation) {
         arrowGlyph: '→',
     };
 }
-function PanoramaBandOverlay({ state, frameUris, captureOrientation, }) {
+function PanoramaBandOverlay({ state, frameUris, captureOrientation, vertical = false, }) {
     // 2026-05-18 (Issue #3 fix) — orientation source priority:
     //   1. `captureOrientation` prop from the host (4-way; correct
     //      for landscape-left vs landscape-right disambiguation).
@@ -231,7 +255,7 @@ function PanoramaBandOverlay({ state, frameUris, captureOrientation, }) {
     //      sensibly before any orientation info is available).
     const resolvedOrientation = captureOrientation
         ?? (state?.isLandscape ? 'landscape-left' : 'portrait');
-    const layout = (0, react_1.useMemo)(() => layoutFor(resolvedOrientation), [resolvedOrientation]);
+    const layout = (0, react_1.useMemo)(() => layoutFor(resolvedOrientation, vertical), [resolvedOrientation, vertical]);
     const scrollRef = (0, react_1.useRef)(null);
     // Trim incoming URIs to a hard cap.  The host already caps at 24
     // (AuditCaptureScreen) but defence-in-depth keeps the ScrollView
@@ -245,26 +269,22 @@ function PanoramaBandOverlay({ state, frameUris, captureOrientation, }) {
             : frameUris;
     }, [frameUris]);
     const hasMultiThumb = cappedFrameUris.length > 0;
-    // Auto-scroll on content-size change.
-    //
-    // 2026-05-18 (Issue #4 fix-b): the direction depends on flex
-    // direction.  In `row` (portrait, landscape-right) the LATEST
-    // item is at JS-rightmost → scrollToEnd shows it.  In
-    // `row-reverse` (landscape-left) the latest is at JS-leftmost →
-    // scrollTo({x: 0}) shows it.  The earlier always-scrollToEnd
-    // behaviour scrolled to OLDEST in row-reverse, which hid the
-    // just-captured frame off-screen at user-bottom.
+    // Auto-scroll on content-size change.  `*-reverse` puts latest at
+    // scroll origin (scrollTo {0,0}); normal `row`/`column` puts
+    // latest at scroll end (scrollToEnd).
+    const isReverse = layout.flexDirection === 'row-reverse' ||
+        layout.flexDirection === 'column-reverse';
     const onContentSizeChange = (0, react_1.useCallback)(() => {
         const sv = scrollRef.current;
         if (!sv)
             return;
-        if (layout.flexDirection === 'row-reverse') {
+        if (isReverse) {
             sv.scrollTo({ x: 0, y: 0, animated: false });
         }
         else {
             sv.scrollToEnd({ animated: false });
         }
-    }, [layout.flexDirection]);
+    }, [isReverse]);
     // ── Single cumulative thumbnail (live-engine fallback) ──────────
     //
     // Same fill-ratio math as V12.14.9.  Kept so live-stitching engines
@@ -285,25 +305,63 @@ function PanoramaBandOverlay({ state, frameUris, captureOrientation, }) {
     const singleThumbPanLen = (0, react_1.useMemo)(() => {
         return Math.max(SINGLE_THUMB_INNER, SINGLE_THUMB_MAX_PAN_LEN * fillRatio);
     }, [fillRatio]);
-    // V12.14.9 — rotate the panorama image 90° in landscape mode so
-    // the captured scene reads UPRIGHT to the user in landscape head-up
-    // view.  See original comment in the pre-V16 PanoramaBandOverlay for
-    // the full reasoning.  Portrait+horizontal-pan mode (the other
-    // supported mode) doesn't need rotation.
+    // Image rotation transform for thumbnails.  Captured frames are in
+    // user-perspective orientation (the capture pipeline rotates the
+    // sensor-native bytes via `outputOrientation="device"` + EXIF
+    // baking in `normaliseOrientation`).  The thumbnail BOX is in
+    // JS coords.  When JS coords are device-aligned (portrait-lock,
+    // i.e. vertical=false here) and the device is in landscape, the
+    // image content is rotated 90° from the box's axes → appears
+    // sideways without compensation.  Apply a counter-rotation to
+    // line content up with the box's perceived "top".
     //
-    // 2026-05-18 (Issue #3) — derive from `resolvedOrientation` instead
-    // of the deprecated 2-way `isLandscape`.  In landscape-RIGHT we
-    // rotate −90° so the captured scene still reads upright (the
-    // opposite sense from landscape-LEFT).
-    const singleImageStyle = (0, react_1.useMemo)(() => {
-        if (resolvedOrientation === 'landscape-left') {
-            return [react_native_1.StyleSheet.absoluteFill, { transform: [{ rotate: '90deg' }] }];
-        }
-        if (resolvedOrientation === 'landscape-right') {
-            return [react_native_1.StyleSheet.absoluteFill, { transform: [{ rotate: '-90deg' }] }];
+    // When vertical=true (non-locked + device-landscape; JS coords
+    // rotated with screen), the box IS user-aligned already.  No
+    // rotation needed — the image is already correctly oriented for
+    // direct display.
+    //
+    // V12.14.9 → v0.12.0 — extended from single-thumb (cumulative
+    // panorama image fallback) to the multi-thumb path too.  Pre-
+    // v0.12 the multi-thumb keyframe thumbnails had no rotation
+    // transform, so they appeared sideways in portrait-locked
+    // landscape captures (the case the example app's batch-keyframe
+    // engine hits).
+    const thumbRotationTransform = (0, react_1.useMemo)(() => {
+        // Empirical observation (on-device test 2026-05-28): captured
+        // per-keyframe JPEGs ARE saved in sensor-native landscape (not
+        // user-perspective), despite the cumulative panorama getting
+        // device-orientation rotation via finalize().  So:
+        //
+        //   jsPortrait box + landscape device: box is device-aligned;
+        //     image's "up" is at file-right (sensor convention).  Rotate
+        //     90° CW (landscape-left) / 90° CCW (landscape-right) to
+        //     align image up with box up.
+        //   jsLandscape box + landscape device: box is user-aligned via
+        //     OS screen rotation; image's "up" still at file-right.  To
+        //     align image up with box up, rotate the OPPOSITE direction
+        //     from the jsPortrait case — the screen-rotation already
+        //     handles half the work; we just need to compensate for the
+        //     remaining mismatch.
+        if (vertical) {
+            if (resolvedOrientation === 'landscape-left')
+                return [{ rotate: '-90deg' }];
+            if (resolvedOrientation === 'landscape-right')
+                return [{ rotate: '90deg' }];
+            return undefined;
         }
-        return react_native_1.StyleSheet.absoluteFill;
-    }, [resolvedOrientation]);
+        if (resolvedOrientation === 'landscape-left')
+            return [{ rotate: '90deg' }];
+        if (resolvedOrientation === 'landscape-right')
+            return [{ rotate: '-90deg' }];
+        return undefined;
+    }, [resolvedOrientation, vertical]);
+    const singleImageStyle = (0, react_1.useMemo)(() => thumbRotationTransform
+        ? [react_native_1.StyleSheet.absoluteFill, { transform: thumbRotationTransform }]
+        : react_native_1.StyleSheet.absoluteFill, [thumbRotationTransform]);
+    // Same rotation applied to the per-keyframe (multi-thumb) tiles.
+    const multiThumbStyle = (0, react_1.useMemo)(() => thumbRotationTransform
+        ? [styles.multiThumb, { transform: thumbRotationTransform }]
+        : styles.multiThumb, [thumbRotationTransform]);
     return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [styles.bandBase, layout.band] }, hasMultiThumb ? (
     // Multi-thumb path: one image per accepted keyframe, scrolling
     // horizontally (in JS-coords) within the band.  Content
@@ -316,7 +374,10 @@ function PanoramaBandOverlay({ state, frameUris, captureOrientation, }) {
     // adjacent to the newest thumbnail.  Previously it was a
     // sibling of the ScrollView at the band's far end, which
     // looked detached when there were only a few thumbnails.
-    react_1.default.createElement(react_native_1.ScrollView, { ref: scrollRef, horizontal: true, showsHorizontalScrollIndicator: false, showsVerticalScrollIndicator: false, style: styles.thumbScroll, contentContainerStyle: [
+    react_1.default.createElement(react_native_1.ScrollView, { ref: scrollRef, 
+        // Horizontal scroll in JS-portrait bands; vertical scroll
+        // in JS-landscape (non-locked host) bands.
+        horizontal: layout.kind === 'portrait', showsHorizontalScrollIndicator: false, showsVerticalScrollIndicator: false, style: styles.thumbScroll, contentContainerStyle: [
             styles.thumbScrollContent,
             { flexDirection: layout.flexDirection },
         ], onContentSizeChange: onContentSizeChange },
@@ -328,7 +389,7 @@ function PanoramaBandOverlay({ state, frameUris, captureOrientation, }) {
             // Composite key: idx prevents collisions if the same path
             // ever gets re-emitted (shouldn't happen but cheap to be
             // defensive).  URI segment helps RN's image cache key.
-            key: `${idx}-${uri}`, source: { uri }, style: styles.multiThumb, resizeMode: "cover", fadeDuration: 0 }))),
+            key: `${idx}-${uri}`, source: { uri }, style: multiThumbStyle, resizeMode: "cover", fadeDuration: 0 }))),
         react_1.default.createElement(react_native_1.View, { style: styles.arrowTrack },
             react_1.default.createElement(react_native_1.Text, { style: styles.arrowGlyph }, layout.arrowGlyph)))) : (react_1.default.createElement(react_1.default.Fragment, null,
         react_1.default.createElement(react_native_1.View, { style: [

package/dist/camera/PanoramaSettingsModal.js

@@ -145,7 +145,21 @@ function PanoramaSettingsModal({ visible, settings, onChange, onClose, }) {
     // Flow-tunables section.  Mirrors the type-level optionality of
     // `frameSelection.flow`.
     const showFlowTunables = settings.frameSelection.mode === 'flow-based';
-    return (react_1.default.createElement(react_native_1.Modal, { visible: visible, animationType: "slide", transparent: true, statusBarTranslucent: true, onRequestClose: onClose },
+    return (react_1.default.createElement(react_native_1.Modal, { visible: visible, animationType: "slide", transparent: true, statusBarTranslucent: true, onRequestClose: onClose, 
+        // v0.12.0 — RN's iOS Modal defaults to portrait-only.  When a
+        // host removes its UIInterfaceOrientations portrait lock to
+        // support landscape capture, opening this modal while in
+        // landscape would force iOS to rotate the window scene to
+        // portrait, then the underlying <Camera>'s ARSession can end
+        // up with stale display-transform state on dismiss (preview
+        // renders sideways).  Declaring all orientations keeps the
+        // window aligned with the device throughout the modal cycle.
+        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.sheet },
                 react_1.default.createElement(react_native_1.View, { style: styles.header },

package/dist/camera/ViewportCropOverlay.d.ts

@@ -1,37 +1,41 @@
 /**
- * ViewportCropOverlay — V12.12.
+ * ViewportCropOverlay — V12.12 + v0.12.0 orientation-aware (R2-lite).
  *
  * Translucent dim bars on the camera preview's PAN-AXIS edges
- * showing where the panorama engine's source-crop is.  Earlier
- * versions (V12.11 Step B) put the bars on JS-top/bottom because
- * the engine clipped the long sensor axis (perpendicular to pan
- * in landscape, along pan in portrait) — that produced visible
- * bars on the user-LEFT/RIGHT in landscape, which is the WRONG
- * place: those edges aren't what the engine clips.
- *
- * V12.12: engine now clips ALONG the pan axis.  In sensor-native
- * coords:
- *   • landscape capture (vertical pan): clip = sensor Y (rows).
- *     User perceives this as TOP and BOTTOM of their landscape view.
- *   • portrait capture (horizontal pan): clip = sensor X (cols).
- *     User perceives this as LEFT and RIGHT of their portrait view.
- *
- * In JS coords (the host app is portrait-locked):
- *   • portrait device: user-left/right == JS-left/right.  Bars on
- *                       JS-left/right.
- *   • landscape device: user-top/bottom == JS-left/right (because
- *                       the user's vertical maps to JS-horizontal
- *                       under portrait-lock).  Bars on JS-left/right.
- *
- * So in BOTH device orientations the bars sit at JS-left and JS-right.
- * **No orientation detection needed in this component.**  The
- * engine has already arranged for the clip to manifest at the same
- * JS edges regardless of physical device orientation.
- *
- * Bar width = `(1 - panFraction) / 2` of the JS-horizontal extent.
- * For the default `kPanAxisFractionRect = 0.70` engine constant,
- * each bar is 15 % wide — visibly substantial, matching what the
- * engine clips out per frame.
+ * showing where the panorama engine's source-crop is.  The engine
+ * clips ALONG the pan axis:
+ *
+ *   • Portrait capture (horizontal pan / Mode B):
+ *     clip = sensor X (cols).  User perceives this as LEFT and RIGHT
+ *     of their portrait view.
+ *
+ *   • Landscape capture (vertical pan / Mode A):
+ *     clip = sensor Y (rows).  User perceives this as TOP and BOTTOM
+ *     of their landscape view.
+ *
+ * ## v0.12.0 update (R2-lite)
+ *
+ * Pre-v0.12 this component assumed the host app was orientation-
+ * locked to portrait, in which case ALL device orientations mapped
+ * to JS-left + JS-right for the bars (because the user's vertical
+ * mapped to JS-horizontal under portrait-lock).  Under R2-lite the
+ * SDK no longer holds the UI in portrait, so JS coordinates align
+ * with the physical device orientation reported by
+ * `useDeviceOrientation()`.  The bars now live at:
+ *
+ *   portrait, portrait-upside-down → JS-left + JS-right  (horizontal pan)
+ *   landscape-left, landscape-right → JS-top  + JS-bottom (vertical pan)
+ *
+ * Mounting: the flagship `<Camera>` component mounts this overlay
+ * by default in v0.12.0 (PR-3 wiring); Layer-2 hosts can mount it
+ * themselves via the public export.
+ *
+ * ## Bar dimensions
+ *
+ * Bar `(1 - panFraction) / 2` of the pan-axis extent.  For the
+ * default engine constant `kPanAxisFractionRect = 0.70`, each bar
+ * is 15 % of the pan-axis extent — visibly substantial, matching
+ * what the engine clips out per frame.
  */
 import React from 'react';
 export interface ViewportCropOverlayProps {

package/dist/camera/ViewportCropOverlay.js

@@ -1,39 +1,43 @@
 "use strict";
 // SPDX-License-Identifier: Apache-2.0
 /**
- * ViewportCropOverlay — V12.12.
+ * ViewportCropOverlay — V12.12 + v0.12.0 orientation-aware (R2-lite).
  *
  * Translucent dim bars on the camera preview's PAN-AXIS edges
- * showing where the panorama engine's source-crop is.  Earlier
- * versions (V12.11 Step B) put the bars on JS-top/bottom because
- * the engine clipped the long sensor axis (perpendicular to pan
- * in landscape, along pan in portrait) — that produced visible
- * bars on the user-LEFT/RIGHT in landscape, which is the WRONG
- * place: those edges aren't what the engine clips.
+ * showing where the panorama engine's source-crop is.  The engine
+ * clips ALONG the pan axis:
  *
- * V12.12: engine now clips ALONG the pan axis.  In sensor-native
- * coords:
- *   • landscape capture (vertical pan): clip = sensor Y (rows).
- *     User perceives this as TOP and BOTTOM of their landscape view.
- *   • portrait capture (horizontal pan): clip = sensor X (cols).
- *     User perceives this as LEFT and RIGHT of their portrait view.
+ *   • Portrait capture (horizontal pan / Mode B):
+ *     clip = sensor X (cols).  User perceives this as LEFT and RIGHT
+ *     of their portrait view.
  *
- * In JS coords (the host app is portrait-locked):
- *   • portrait device: user-left/right == JS-left/right.  Bars on
- *                       JS-left/right.
- *   • landscape device: user-top/bottom == JS-left/right (because
- *                       the user's vertical maps to JS-horizontal
- *                       under portrait-lock).  Bars on JS-left/right.
+ *   • Landscape capture (vertical pan / Mode A):
+ *     clip = sensor Y (rows).  User perceives this as TOP and BOTTOM
+ *     of their landscape view.
  *
- * So in BOTH device orientations the bars sit at JS-left and JS-right.
- * **No orientation detection needed in this component.**  The
- * engine has already arranged for the clip to manifest at the same
- * JS edges regardless of physical device orientation.
+ * ## v0.12.0 update (R2-lite)
  *
- * Bar width = `(1 - panFraction) / 2` of the JS-horizontal extent.
- * For the default `kPanAxisFractionRect = 0.70` engine constant,
- * each bar is 15 % wide — visibly substantial, matching what the
- * engine clips out per frame.
+ * Pre-v0.12 this component assumed the host app was orientation-
+ * locked to portrait, in which case ALL device orientations mapped
+ * to JS-left + JS-right for the bars (because the user's vertical
+ * mapped to JS-horizontal under portrait-lock).  Under R2-lite the
+ * SDK no longer holds the UI in portrait, so JS coordinates align
+ * with the physical device orientation reported by
+ * `useDeviceOrientation()`.  The bars now live at:
+ *
+ *   portrait, portrait-upside-down → JS-left + JS-right  (horizontal pan)
+ *   landscape-left, landscape-right → JS-top  + JS-bottom (vertical pan)
+ *
+ * Mounting: the flagship `<Camera>` component mounts this overlay
+ * by default in v0.12.0 (PR-3 wiring); Layer-2 hosts can mount it
+ * themselves via the public export.
+ *
+ * ## Bar dimensions
+ *
+ * Bar `(1 - panFraction) / 2` of the pan-axis extent.  For the
+ * default engine constant `kPanAxisFractionRect = 0.70`, each bar
+ * is 15 % of the pan-axis extent — visibly substantial, matching
+ * what the engine clips out per frame.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -42,14 +46,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ViewportCropOverlay = ViewportCropOverlay;
 const react_1 = __importDefault(require("react"));
 const react_native_1 = require("react-native");
+const useDeviceOrientation_1 = require("./useDeviceOrientation");
 function ViewportCropOverlay({ panFraction, }) {
+    const orientation = (0, useDeviceOrientation_1.useDeviceOrientation)();
     if (panFraction >= 1)
         return null;
-    // (1 - panFraction) / 2 of the JS-horizontal extent on each side.
+    // (1 - panFraction) / 2 of the pan-axis extent on each side.
     const barPercent = `${((1 - panFraction) / 2) * 100}%`;
-    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: styles.root },
+    const isLandscape = orientation === 'landscape-left' || orientation === 'landscape-right';
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: styles.root }, isLandscape ? (react_1.default.createElement(react_1.default.Fragment, null,
+        react_1.default.createElement(react_native_1.View, { style: [styles.bar, { left: 0, right: 0, top: 0, height: barPercent }] }),
+        react_1.default.createElement(react_native_1.View, { style: [styles.bar, { left: 0, right: 0, bottom: 0, height: barPercent }] }))) : (react_1.default.createElement(react_1.default.Fragment, null,
         react_1.default.createElement(react_native_1.View, { style: [styles.bar, { left: 0, top: 0, bottom: 0, width: barPercent }] }),
-        react_1.default.createElement(react_native_1.View, { style: [styles.bar, { right: 0, top: 0, bottom: 0, width: barPercent }] })));
+        react_1.default.createElement(react_native_1.View, { style: [styles.bar, { right: 0, top: 0, bottom: 0, width: barPercent }] })))));
 }
 const styles = react_native_1.StyleSheet.create({
     root: {

package/dist/camera/useDeviceOrientation.d.ts

@@ -1,15 +1,24 @@
 /**
  * useDeviceOrientation — physical device orientation hook.
  *
- * The host app is portrait-locked at the iOS app level (so the
- * camera preview, header, controls, and thumbnails stay in their
- * portrait positions even when the user holds the phone sideways
- * for a vertical pan).  But text overlays — the REC banner, the
- * pan-speed pill, the live frame strip — need to follow the
- * physical device orientation so they stay readable in the user's
- * hands.  RN's `useWindowDimensions` can't help with this when
- * the app is orientation-locked: window dimensions don't change
- * when only the device rotates.
+ * Hooks into the accelerometer to report the device's physical
+ * orientation as a 4-way `DeviceOrientation` value.  Works
+ * identically regardless of host configuration:
+ *
+ *   - Portrait-locked host (Info.plist UISupportedInterfaceOrientations
+ *     restricted to Portrait):  RN's `useWindowDimensions` returns
+ *     portrait dims regardless of physical tilt.  This hook reads
+ *     the sensor directly, so text overlays (REC banner, pan-speed
+ *     pill, live frame strip) can still follow the user's hold.
+ *   - Non-locked host (Info.plist supports all 4):  the OS rotates
+ *     the framebuffer with the device; `useWindowDimensions` reflects
+ *     the rotated JS layout.  This hook still reports physical tilt
+ *     — useful in combination with window dims to detect whether
+ *     the screen rotated to match the device (`<Camera>`'s v0.12
+ *     `homeIndicatorEdge` logic uses both signals together).
+ *
+ * Either way the sensor is the single source of truth for "where
+ * the user's hands actually are."
  *
  * 2026-05-21 (v0.2 — Expo modules removal) — rewritten back onto
  * `react-native-sensors` accelerometer.  `expo-sensors`'