react-native-image-stitcher 0.11.1 → 0.12.0

package/src/camera/PanoramaBandOverlay.tsx

@@ -87,6 +87,18 @@ export type BandCaptureOrientation =
   | '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
@@ -138,8 +150,12 @@ interface Layout {
   kind: LayoutKind;
   /** Outer container style — positioning + flexDirection. */
   band: ViewStyle;
-  /** Direction used by both the outer band AND the scroll content. */
-  flexDirection: 'row' | 'row-reverse';
+  /**
+   * Direction used by both the outer band AND the scroll content.
+   * row/row-reverse for horizontal bands; column/column-reverse for
+   * vertical bands (non-locked host in landscape, jsLandscape=true).
+   */
+  flexDirection: 'row' | 'row-reverse' | 'column' | 'column-reverse';
   /** Unicode arrow pointing along the user-perceived pan axis. */
   arrowGlyph: string;
 }
@@ -182,26 +198,53 @@ interface Layout {
  *     reads as user-right-arrow (pointing along the horizontal pan
  *     direction).
  */
-function layoutFor(orientation: BandCaptureOrientation): Layout {
+function layoutFor(
+  orientation: BandCaptureOrientation,
+  vertical: boolean,
+): Layout {
   const commonInner: ViewStyle = {
     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):
+  //
+  //   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: 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.
+  // 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:
@@ -268,6 +311,7 @@ export function PanoramaBandOverlay({
   state,
   frameUris,
   captureOrientation,
+  vertical = false,
 }: PanoramaBandOverlayProps): React.JSX.Element | null {
   // 2026-05-18 (Issue #3 fix) — orientation source priority:
   //   1. `captureOrientation` prop from the host (4-way; correct
@@ -280,8 +324,8 @@ export function PanoramaBandOverlay({
     captureOrientation
     ?? (state?.isLandscape ? 'landscape-left' : 'portrait');
   const layout = useMemo(
-    () => layoutFor(resolvedOrientation),
-    [resolvedOrientation],
+    () => layoutFor(resolvedOrientation, vertical),
+    [resolvedOrientation, vertical],
   );
 
   const scrollRef = useRef<ScrollView | null>(null);
@@ -299,24 +343,21 @@ export function PanoramaBandOverlay({
 
   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 = 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) ──────────
   //
@@ -339,27 +380,70 @@ export function PanoramaBandOverlay({
     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).
+  // 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 = useMemo<
+    Array<{ rotate: string }> | undefined
+  >(() => {
+    // 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;
+    }
+    if (resolvedOrientation === 'landscape-left') return [{ rotate: '90deg' }];
+    if (resolvedOrientation === 'landscape-right') return [{ rotate: '-90deg' }];
+    return undefined;
+  }, [resolvedOrientation, vertical]);
+
   const singleImageStyle = useMemo(
-    () => {
-      if (resolvedOrientation === 'landscape-left') {
-        return [StyleSheet.absoluteFill, { transform: [{ rotate: '90deg' }] }];
-      }
-      if (resolvedOrientation === 'landscape-right') {
-        return [StyleSheet.absoluteFill, { transform: [{ rotate: '-90deg' }] }];
-      }
-      return StyleSheet.absoluteFill;
-    },
-    [resolvedOrientation],
+    () =>
+      thumbRotationTransform
+        ? [StyleSheet.absoluteFill, { transform: thumbRotationTransform }]
+        : StyleSheet.absoluteFill,
+    [thumbRotationTransform],
+  );
+
+  // Same rotation applied to the per-keyframe (multi-thumb) tiles.
+  const multiThumbStyle = useMemo(
+    () =>
+      thumbRotationTransform
+        ? [styles.multiThumb, { transform: thumbRotationTransform }]
+        : styles.multiThumb,
+    [thumbRotationTransform],
   );
 
   return (
@@ -378,7 +462,9 @@ export function PanoramaBandOverlay({
         // looked detached when there were only a few thumbnails.
         <ScrollView
           ref={scrollRef}
-          horizontal
+          // 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}
@@ -395,7 +481,7 @@ export function PanoramaBandOverlay({
               // defensive).  URI segment helps RN's image cache key.
               key={`${idx}-${uri}`}
               source={{ uri }}
-              style={styles.multiThumb}
+              style={multiThumbStyle}
               resizeMode="cover"
               fadeDuration={0}
             />

package/src/camera/PanoramaSettingsModal.tsx

@@ -164,6 +164,20 @@ export function PanoramaSettingsModal({
       transparent
       statusBarTranslucent
       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',
+      ]}
     >
       <View style={styles.backdrop}>
         <View style={styles.sheet}>

package/src/camera/ViewportCropOverlay.tsx

@@ -1,43 +1,49 @@
 // 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.
  */
 
 import React from 'react';
 import { StyleSheet, View } from 'react-native';
 
+import { useDeviceOrientation } from './useDeviceOrientation';
+
 
 export interface ViewportCropOverlayProps {
   /**
@@ -52,15 +58,31 @@ export interface ViewportCropOverlayProps {
 export function ViewportCropOverlay({
   panFraction,
 }: ViewportCropOverlayProps): React.JSX.Element | null {
+  const orientation = 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}%` as const;
 
+  const isLandscape =
+    orientation === 'landscape-left' || orientation === 'landscape-right';
+
   return (
     <View pointerEvents="none" style={styles.root}>
-      <View style={[styles.bar, { left: 0, top: 0, bottom: 0, width: barPercent }]} />
-      <View style={[styles.bar, { right: 0, top: 0, bottom: 0, width: barPercent }]} />
+      {isLandscape ? (
+        <>
+          {/* Vertical-pan capture: bars at JS-top + JS-bottom. */}
+          <View style={[styles.bar, { left: 0, right: 0, top: 0, height: barPercent }]} />
+          <View style={[styles.bar, { left: 0, right: 0, bottom: 0, height: barPercent }]} />
+        </>
+      ) : (
+        <>
+          {/* Horizontal-pan capture: bars at JS-left + JS-right. */}
+          <View style={[styles.bar, { left: 0, top: 0, bottom: 0, width: barPercent }]} />
+          <View style={[styles.bar, { right: 0, top: 0, bottom: 0, width: barPercent }]} />
+        </>
+      )}
     </View>
   );
 }

package/src/camera/__tests__/useOrientationDrift.test.ts

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for `useOrientationDrift` — exercises the pure
+ * state-transition function `_computeDriftStateForTests` directly.
+ *
+ * Why not test the hook end-to-end via render: the lib's jest
+ * config is `preset: 'ts-jest'` + `testEnvironment: 'node'` — no
+ * React Native preset, no `@testing-library/react-native`.  See the
+ * jest.config.js header comment: "If we ever add component-render
+ * tests we'd flip to the RN preset then."  The component-render
+ * tests for `<OrientationDriftModal>`, `<PanoramaBandOverlay>`,
+ * `<ViewportCropOverlay>`, and `<Camera>` composition (all called
+ * out in the v0.12 plan) will all need that flip.  Setting it up
+ * is grouped in Phase 5 of the plan (Tests) rather than scattered
+ * across each PR.  For PR-1, the pure state-transition function
+ * carries the full behavioural contract — same approach
+ * `useThrottledFrameProcessor.test.ts` uses for its throttle gate.
+ *
+ * The 5 cases below cover the full state machine per the plan
+ * (lines 119, 277):
+ *
+ *   (a) no change → not drifted
+ *   (b) orientation changes during active=true → drifted
+ *   (c) drift state survives further changes (latching)
+ *   (d) inactive → captureOrientation undefined
+ *   (e) active resets snapshot (false → true → false → true cycle)
+ */
+
+// Mock `react-native-sensors` BEFORE importing the SUT.  The hook
+// itself transitively pulls in `useDeviceOrientation` which imports
+// `accelerometer` from `react-native-sensors` — an ES module that
+// jest can't parse without the RN preset (which jest.config.js
+// intentionally avoids; see config header comment).  We're only
+// testing the pure transition function below, but TS imports are
+// transitive so we still need to silence the chain.
+jest.mock('react-native-sensors', () => ({
+  accelerometer: { subscribe: jest.fn(() => ({ unsubscribe: jest.fn() })) },
+  setUpdateIntervalForType: jest.fn(),
+  SensorTypes: { accelerometer: 'accelerometer' },
+}));
+
+// eslint-disable-next-line import/first
+import { _computeDriftStateForTests } from '../useOrientationDrift';
+
+const INITIAL = { captureOrientation: undefined, drifted: false };
+
+describe('_computeDriftStateForTests (useOrientationDrift core logic)', () => {
+  describe('(a) no change → not drifted', () => {
+    it('stays in initial state when active is false from the start', () => {
+      const next = _computeDriftStateForTests(INITIAL, false, 'portrait');
+      expect(next).toEqual({ captureOrientation: undefined, drifted: false });
+    });
+
+    it('snapshots orientation when active flips true, drifted starts false', () => {
+      const next = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      expect(next).toEqual({ captureOrientation: 'portrait', drifted: false });
+    });
+
+    it('stays clean when active=true and orientation does not change', () => {
+      const after1 = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, true, 'portrait');
+      const after3 = _computeDriftStateForTests(after2, true, 'portrait');
+      expect(after3).toEqual({ captureOrientation: 'portrait', drifted: false });
+      // Reference equality: once steady, returns the prev ref so
+      // React's setState becomes a no-op (no re-render).
+      expect(after2).toBe(after1);
+      expect(after3).toBe(after2);
+    });
+  });
+
+  describe('(b) orientation changes during active=true → drifted', () => {
+    it('latches drifted=true when orientation changes mid-active', () => {
+      const after1 = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, true, 'landscape-left');
+      expect(after2).toEqual({ captureOrientation: 'portrait', drifted: true });
+    });
+
+    it('captures the ORIGINAL orientation in captureOrientation, not the new one', () => {
+      const after1 = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, true, 'landscape-right');
+      // captureOrientation MUST remain the snapshot (portrait), not
+      // the current rotation — that's how the drift modal copy
+      // ("captured in PORTRAIT, now LANDSCAPE-RIGHT") works.
+      expect(after2.captureOrientation).toBe('portrait');
+    });
+
+    it('detects drift to any of the 3 other orientations', () => {
+      const cases: Array<['portrait', 'portrait-upside-down' | 'landscape-left' | 'landscape-right']> = [
+        ['portrait', 'portrait-upside-down'],
+        ['portrait', 'landscape-left'],
+        ['portrait', 'landscape-right'],
+      ];
+      for (const [captured, drifted] of cases) {
+        const after1 = _computeDriftStateForTests(INITIAL, true, captured);
+        const after2 = _computeDriftStateForTests(after1, true, drifted);
+        expect(after2.drifted).toBe(true);
+      }
+    });
+  });
+
+  describe('(c) drift state survives further changes (latching)', () => {
+    it('stays drifted even if the user rotates back to the captured orientation', () => {
+      // User rotates portrait → landscape (drift triggers) → portrait
+      // (back to original).  The flag MUST stay latched.  Rationale:
+      // the engine docstring says cross-mode capture is "best-effort,
+      // not supported" — a brief rotation pollutes the buffer even
+      // if the user rotates back, so the safe action is decisive
+      // abandonment regardless of post-detection orientation.
+      const after1 = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, true, 'landscape-left');
+      const after3 = _computeDriftStateForTests(after2, true, 'portrait');
+      expect(after3).toEqual({ captureOrientation: 'portrait', drifted: true });
+    });
+
+    it('stays drifted across multiple subsequent orientation changes', () => {
+      const after1 = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, true, 'landscape-left');
+      const after3 = _computeDriftStateForTests(after2, true, 'landscape-right');
+      const after4 = _computeDriftStateForTests(after3, true, 'portrait-upside-down');
+      expect(after4.drifted).toBe(true);
+      expect(after4.captureOrientation).toBe('portrait');
+    });
+  });
+
+  describe('(d) inactive → captureOrientation undefined', () => {
+    it('clears the snapshot when active flips back to false', () => {
+      const after1 = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, false, 'portrait');
+      expect(after2).toEqual({ captureOrientation: undefined, drifted: false });
+    });
+
+    it('clears the drift flag when active flips back to false', () => {
+      const after1 = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, true, 'landscape-left');
+      expect(after2.drifted).toBe(true);
+      const after3 = _computeDriftStateForTests(after2, false, 'landscape-left');
+      expect(after3).toEqual({ captureOrientation: undefined, drifted: false });
+    });
+
+    it('is idempotent — no state change when inactive and already clear', () => {
+      const after1 = _computeDriftStateForTests(INITIAL, false, 'portrait');
+      const after2 = _computeDriftStateForTests(after1, false, 'landscape-left');
+      // Same ref → setState becomes a no-op.
+      expect(after2).toBe(after1);
+    });
+  });
+
+  describe('(e) active resets snapshot', () => {
+    it('re-snapshots on a fresh active cycle (false → true → false → true)', () => {
+      // Cycle 1: capture in portrait, drift.
+      const c1a = _computeDriftStateForTests(INITIAL, true, 'portrait');
+      const c1b = _computeDriftStateForTests(c1a, true, 'landscape-left');
+      expect(c1b).toEqual({ captureOrientation: 'portrait', drifted: true });
+
+      // Stop the capture.
+      const cleared = _computeDriftStateForTests(c1b, false, 'landscape-left');
+      expect(cleared).toEqual({ captureOrientation: undefined, drifted: false });
+
+      // Cycle 2: re-capture, now in landscape-left.  Snapshot
+      // should be landscape-left, NOT carry over the old portrait.
+      const c2a = _computeDriftStateForTests(cleared, true, 'landscape-left');
+      expect(c2a).toEqual({ captureOrientation: 'landscape-left', drifted: false });
+
+      // And staying in landscape-left should not drift.
+      const c2b = _computeDriftStateForTests(c2a, true, 'landscape-left');
+      expect(c2b.drifted).toBe(false);
+    });
+  });
+});

package/src/camera/useDeviceOrientation.ts

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