react-native-image-stitcher 0.11.1 → 0.12.0

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`'

package/dist/camera/useDeviceOrientation.js

@@ -3,15 +3,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`'

package/dist/camera/useOrientationDrift.d.ts

@@ -0,0 +1,104 @@
+/**
+ * useOrientationDrift — detects mid-capture device rotation.
+ *
+ * Pairs with `useDeviceOrientation()` to surface the case where the
+ * user rotates the device *during* an active capture.  The
+ * incremental stitching engine supports both portrait (Mode B,
+ * horizontal pan) and landscape (Mode A, vertical pan) capture
+ * modes as first-class — but mixing them mid-capture produces
+ * malformed output ("cross-mode capture is best-effort," per
+ * `incremental.ts:373-403`).  Hosts that want to protect against
+ * this use this hook + `OrientationDriftModal` together: the
+ * `<Camera>` flagship component auto-abandons capture the instant
+ * `drifted === true` (PR-2 wiring); the modal surfaces an
+ * explanatory popup to the user.
+ *
+ * ## API contract
+ *
+ * Pass `active` true while a capture is in flight, false otherwise.
+ * Returns:
+ *
+ *   - `captureOrientation` — the orientation snapshotted at the
+ *     moment `active` transitioned false → true.  `undefined` when
+ *     `active` is false.
+ *   - `currentOrientation` — live orientation from
+ *     `useDeviceOrientation()`.  Always defined (defaults to
+ *     `'portrait'` until the accelerometer's first sample).
+ *   - `drifted` — `true` IFF `active` is currently true AND
+ *     `currentOrientation !== captureOrientation` at some point
+ *     since the snapshot.  **Latching** — once true, stays true
+ *     until `active` flips back to false.  This is intentional:
+ *     after detection, callers should auto-abandon the capture
+ *     (engine `stop()`); allowing the flag to clear before then
+ *     would mask the drift if the user rotated back to the
+ *     original orientation between the detection tick and the
+ *     callers' abandonment effect.
+ *
+ * ## Semantics by transition
+ *
+ *   - `active` false → true:  snapshot `currentOrientation`;
+ *     reset `drifted` to false.
+ *   - `active` true (steady):  if `currentOrientation !==
+ *     captureOrientation` at any point, latch `drifted = true`.
+ *   - `active` true → false:  clear snapshot; reset `drifted`.
+ *
+ * ## Why a separate hook (rather than inlining in `<Camera>`)
+ *
+ * Hosts using the Layer-2 building blocks (`CameraView` directly,
+ * custom capture UX) can reuse this hook without mounting the
+ * full `<Camera>` flagship.  Same composition pattern as
+ * `useIMUTranslationGate` and `useKeyframeStream`.
+ *
+ * ## Testing
+ *
+ * The pure state-transition function `_computeDriftStateForTests`
+ * is exported separately so jest can exercise all 5 transition
+ * cases without booting a React render.  The hook itself is a
+ * thin wrapper around it (verified via on-device manual flow in
+ * the v0.12 verification checklist).
+ */
+import { type DeviceOrientation } from './useDeviceOrientation';
+export interface UseOrientationDriftReturn {
+    /**
+     * `true` IFF a capture is active and the device has rotated since
+     * the snapshot taken at capture start.  Latching: once true, stays
+     * true until `active` flips false.
+     */
+    drifted: boolean;
+    /**
+     * Snapshot of `currentOrientation` at the moment `active`
+     * transitioned false → true.  `undefined` when `active` is false.
+     */
+    captureOrientation: DeviceOrientation | undefined;
+    /**
+     * Live device orientation from `useDeviceOrientation()`.  Always
+     * defined.  Exposed so callers (e.g. the drift modal) can show
+     * "captured in PORTRAIT, now LANDSCAPE-LEFT" copy without
+     * mounting `useDeviceOrientation()` themselves.
+     */
+    currentOrientation: DeviceOrientation;
+}
+/**
+ * Internal state of the drift detector.  Two scalar pieces: the
+ * snapshotted capture orientation (undefined when inactive) + the
+ * latched drift flag.
+ */
+interface DriftState {
+    captureOrientation: DeviceOrientation | undefined;
+    drifted: boolean;
+}
+/**
+ * Pure state-transition function for the drift detector.  Exported
+ * with a `_` prefix to signal "internal — not part of the public
+ * API."  Jest uses this directly so tests don't need a React
+ * renderer (the lib's jest config is pure-data / no RN preset).
+ *
+ * Given the previous state + the current `active` flag + the
+ * current device orientation, returns the new state.  Idempotent
+ * when nothing changed (returns the same object reference) so
+ * downstream `useState(setState)` calls become no-ops.
+ */
+export declare function _computeDriftStateForTests(prev: DriftState, active: boolean, currentOrientation: DeviceOrientation): DriftState;
+export declare function useOrientationDrift(active: boolean): UseOrientationDriftReturn;
+export {};
+//# sourceMappingURL=useOrientationDrift.d.ts.map