react-native-image-stitcher 0.12.0 → 0.14.0

package/src/camera/CameraView.tsx

@@ -33,6 +33,12 @@ export interface CameraViewProps {
   device: CameraDevice | null | undefined;
   /** Flash / torch state from ``useCapture().flash``. */
   flash?: 'off' | 'on';
+  /**
+   * v0.13.2 — zoom factor for the mounted device.  Used in multi-cam
+   * mode to switch lenses (0.5× ultra-wide ↔ 1× wide) on a single
+   * device.  `undefined` leaves vision-camera at its default zoom.
+   */
+  zoom?: number;
   /** Whether the preview is actively rendering.  Defaults to true. */
   isActive?: boolean;
   /**
@@ -103,6 +109,7 @@ export const CameraView = forwardRef<Camera | null, CameraViewProps>(function Ca
   {
     device,
     flash = 'off',
+    zoom,
     isActive = true,
     video = false,
     guidance,
@@ -150,6 +157,8 @@ export const CameraView = forwardRef<Camera | null, CameraViewProps>(function Ca
         isActive={isActive}
         photo
         video={video}
+        // v0.13.2 — multi-cam lens switch via zoom (undefined = default).
+        {...(zoom != null ? { zoom } : {})}
         // Bake the device orientation into the captured pixels.
         // Without this, vision-camera writes the file in the camera
         // sensor's native landscape and relies on EXIF metadata to

package/src/camera/CaptureHeader.tsx

@@ -81,15 +81,21 @@ export function CaptureHeader({
   colors,
   style,
 }: CaptureHeaderProps): React.JSX.Element {
-  const bg = colors?.background ?? '#000000';
+  // v0.13.1 — defaults are now transparent over the camera preview
+  // (matches the AR toggle / settings gear pill style); hosts using
+  // the header outside a camera context can pass solid colours via
+  // `colors`.  Title + gear get a text shadow for legibility over
+  // bright preview content; guidance row keeps a translucent pill
+  // background for the same reason.
+  const bg = colors?.background ?? 'transparent';
   const titleColor = colors?.title ?? '#ffffff';
   const accent = colors?.accent ?? '#FF9F0A';
-  const guidanceBg = colors?.guidanceBackground ?? 'rgba(255,255,255,0.08)';
+  const guidanceBg = colors?.guidanceBackground ?? 'rgba(0,0,0,0.45)';
   const guidanceColor = colors?.guidanceText ?? '#ffffff';
 
   return (
     <View style={[{ backgroundColor: bg }, style]}>
-      <View style={[styles.titleRow, { paddingTop: topInset + 8 }]}>
+      <View style={[styles.titleRow, { paddingTop: topInset + 4 }]}>
         {onBack ? (
           <Pressable
             onPress={onBack}
@@ -98,7 +104,7 @@ export function CaptureHeader({
             accessibilityLabel="Go back"
             style={styles.backButton}
           >
-            <Text style={[styles.backText, { color: accent }]}>
+            <Text style={[styles.backText, styles.textShadow, { color: accent }]}>
               {backLabel}
             </Text>
           </Pressable>
@@ -107,7 +113,7 @@ export function CaptureHeader({
           <View style={styles.backButton} />
         )}
         <Text
-          style={[styles.title, { color: titleColor }]}
+          style={[styles.title, styles.textShadow, { color: titleColor }]}
           numberOfLines={1}
           accessibilityRole="header"
         >
@@ -123,7 +129,7 @@ export function CaptureHeader({
             accessibilityLabel="Open panorama settings"
             style={styles.backButton}
           >
-            <Text style={[styles.gearIcon, { color: accent }]}>⚙</Text>
+            <Text style={[styles.gearIcon, styles.textShadow, { color: accent }]}>⚙</Text>
           </Pressable>
         ) : (
           <View style={styles.backButton} />
@@ -153,32 +159,49 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     alignItems: 'center',
     justifyContent: 'space-between',
-    paddingHorizontal: 16,
-    paddingBottom: 8,
+    paddingHorizontal: 12,
+    paddingBottom: 4,
   },
   backButton: {
-    minWidth: 64,
-    paddingVertical: 4,
+    minWidth: 56,
+    paddingVertical: 2,
   },
   backText: {
-    fontSize: 16,
+    fontSize: 14,
     fontWeight: '500',
   },
   title: {
     flex: 1,
     textAlign: 'center',
-    fontSize: 16,
+    fontSize: 14,
     fontWeight: '600',
   },
   guidance: {
-    paddingHorizontal: 16,
-    paddingVertical: 8,
+    // v0.13.1 — guidance row is now a centred pill inset from the
+    // edges (matches the AR-toggle / lens-chip pill style) rather
+    // than a full-width band.  The pill background gives it its
+    // own contrast over the preview without forcing a solid bar.
+    alignSelf: 'center',
+    marginTop: 4,
+    paddingHorizontal: 10,
+    paddingVertical: 5,
+    borderRadius: 12,
+    maxWidth: '90%',
   },
   guidanceText: {
-    fontSize: 13,
+    fontSize: 12,
+    textAlign: 'center',
   },
   gearIcon: {
-    fontSize: 22,
+    fontSize: 20,
     textAlign: 'right',
   },
+  // v0.13.1 — subtle text shadow so the (now-transparent) header
+  // text stays legible over bright preview content.  Same trick
+  // iOS Camera uses for the timestamp / mode labels.
+  textShadow: {
+    textShadowColor: 'rgba(0,0,0,0.65)',
+    textShadowOffset: { width: 0, height: 1 },
+    textShadowRadius: 2,
+  },
 });

package/src/camera/CapturePreview.tsx

@@ -109,6 +109,18 @@ export function CapturePreview({
       animationType="fade"
       transparent
       statusBarTranslucent
+      // v0.13.1 — RN's iOS <Modal> defaults to portrait-only, which
+      // pins the stitched-image preview to portrait even when the host
+      // app is in landscape (the preview appeared sideways/letterboxed
+      // under a non-locked host).  Declaring all four keeps the modal
+      // aligned with the interface.  Mirrors the v0.12 fix already on
+      // OrientationDriftModal + PanoramaSettingsModal.
+      supportedOrientations={[
+        'portrait',
+        'portrait-upside-down',
+        'landscape-left',
+        'landscape-right',
+      ]}
       onRequestClose={onClose}
     >
       <View style={styles.backdrop}>

package/src/camera/CaptureThumbnailStrip.tsx

@@ -99,6 +99,28 @@ export interface CaptureThumbnailStripProps {
    * stay under the strip's control to keep the count line consistent.
    */
   style?: StyleProp<ViewStyle>;
+  /**
+   * v0.13.1 — when `true`, the strip stacks thumbnails VERTICALLY
+   * (column, scrolls up/down) instead of the default horizontal row.
+   * `<Camera>` sets this from the same `isSideEdge(homeIndicatorEdge)`
+   * signal that drives PanoramaBandOverlay's `vertical`, so under a
+   * non-locked host in landscape the idle capture strip stacks along
+   * the home-indicator edge like the live band does (rather than
+   * running horizontally across the middle of the rotated screen).
+   * Default `false` (legacy horizontal strip) — unchanged for
+   * portrait-locked hosts.
+   */
+  vertical?: boolean;
+  /**
+   * v0.13.1 — counter-rotation applied to each thumbnail image so the
+   * captured scene reads upright when the device is held landscape
+   * under a PORTRAIT-LOCKED host (the JS framebuffer stays portrait, so
+   * the thumbnail would otherwise show 90° off).  `<Camera>` passes the
+   * `useContentRotation()` result; `{}` (no-op) in upright cases.
+   * Applies only to the strip's own images — orientation of the strip's
+   * scroll axis is handled separately by `vertical`.
+   */
+  contentRotation?: { transform?: ViewStyle['transform'] };
 }
 
 
@@ -134,6 +156,8 @@ export function CaptureThumbnailStrip({
   disablePreview = false,
   onItemPress,
   style,
+  vertical = false,
+  contentRotation,
 }: CaptureThumbnailStripProps): React.JSX.Element {
   // Built-in preview state — only used when the host hasn't
   // provided its own onItemPress handler.  Letting the host pass a
@@ -185,10 +209,13 @@ export function CaptureThumbnailStrip({
     <View style={[styles.root, { backgroundColor }, style]}>
       <FlatList
         data={items}
-        horizontal
+        horizontal={!vertical}
         showsHorizontalScrollIndicator={false}
+        showsVerticalScrollIndicator={false}
         keyExtractor={(item) => item.id}
-        contentContainerStyle={styles.listContent}
+        contentContainerStyle={
+          vertical ? styles.listContentVertical : styles.listContent
+        }
         ListEmptyComponent={
           <View
             style={[styles.placeholder, { borderColor: textColor }]}
@@ -210,12 +237,15 @@ export function CaptureThumbnailStrip({
             // re-created on every parent render.
             style={[
               styles.thumbWrapper,
+              // Spacing runs along the scroll axis: marginRight for the
+              // horizontal strip, marginBottom for the vertical column.
+              vertical ? styles.thumbWrapperVertical : styles.thumbWrapperHorizontal,
               { width: thumbWidth(item), height: THUMB_HEIGHT },
             ]}
           >
             <Image
               source={{ uri: item.uri }}
-              style={styles.thumbImage}
+              style={[styles.thumbImage, contentRotation]}
               resizeMode="cover"
             />
           </Pressable>
@@ -246,12 +276,22 @@ const styles = StyleSheet.create({
     paddingHorizontal: 12,
     alignItems: 'center',
   },
+  listContentVertical: {
+    paddingVertical: 12,
+    alignItems: 'center',
+  },
   thumbWrapper: {
-    marginRight: 8,
     borderRadius: 4,
     overflow: 'hidden',
     backgroundColor: '#222',
   },
+  // Spacing applied along the scroll axis (see render site).
+  thumbWrapperHorizontal: {
+    marginRight: 8,
+  },
+  thumbWrapperVertical: {
+    marginBottom: 8,
+  },
   thumbImage: {
     width: '100%',
     height: '100%',

package/src/camera/PanoramaBandOverlay.tsx

@@ -198,6 +198,60 @@ interface Layout {
  *     reads as user-right-arrow (pointing along the horizontal pan
  *     direction).
  */
+/**
+ * v0.13.1 — pure rotation-decision helpers, extracted for unit testing
+ * (the lib's jest config is pure-TS, no component mounting; see
+ * jest.config.js).  These encode the orientation contract the band
+ * relies on, so a regression in the angles/branches is caught in CI
+ * rather than only on-device.
+ *
+ * `bandThumbRotation` — the CSS rotate transform that aligns a thumb's
+ * pixels with the band box.  Returns the transform array RN expects, or
+ * `undefined` for "no rotation".  Two regimes:
+ *   - vertical=false (portrait-locked UI): the box is device-aligned, so
+ *     a landscape device needs a 90° counter-rotation (CW for
+ *     landscape-left, CCW for landscape-right).
+ *   - vertical=true (non-locked, OS-rotated framebuffer): the screen
+ *     rotation already did half the work, so the compensation is the
+ *     OPPOSITE sign.
+ * Exported as `_bandThumbRotationForTests`.
+ */
+function bandThumbRotation(
+  orientation: BandCaptureOrientation,
+  vertical: boolean,
+): Array<{ rotate: string }> | undefined {
+  if (vertical) {
+    if (orientation === 'landscape-left') return [{ rotate: '-90deg' }];
+    if (orientation === 'landscape-right') return [{ rotate: '90deg' }];
+    return undefined;
+  }
+  if (orientation === 'landscape-left') return [{ rotate: '90deg' }];
+  if (orientation === 'landscape-right') return [{ rotate: '-90deg' }];
+  return undefined;
+}
+
+/**
+ * v0.13.1 — the rotation actually applied to the per-keyframe (multi-
+ * thumb) TILES.  This is the EXIF double-rotation fix: the saved
+ * `keyframe-N.jpg` is sensor-native landscape + EXIF Orientation 6, which
+ * RN's <Image> already auto-rotates upright.  So in the portrait-locked
+ * (vertical=false) path NO further transform is applied — adding one
+ * double-rotates (the original v0.12 bug).  Only the non-locked
+ * (vertical=true) path needs the compensation.  Returns `undefined` for
+ * "no transform".  Exported as `_tileRotationForTests`.
+ */
+function tileRotation(
+  orientation: BandCaptureOrientation,
+  vertical: boolean,
+): Array<{ rotate: string }> | undefined {
+  return vertical ? bandThumbRotation(orientation, vertical) : undefined;
+}
+
+/** @internal test-only export — see `bandThumbRotation`. */
+export const _bandThumbRotationForTests = bandThumbRotation;
+/** @internal test-only export — see `tileRotation`. */
+export const _tileRotationForTests = tileRotation;
+
 function layoutFor(
   orientation: BandCaptureOrientation,
   vertical: boolean,
@@ -401,33 +455,13 @@ export function PanoramaBandOverlay({
   // 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]);
+  // Rotation for the single cumulative thumb (panorama-*.jpg, a JFIF
+  // with NO EXIF tag → RN does not auto-rotate it, so the transform is
+  // always needed).  See `bandThumbRotation` for the angle contract.
+  const thumbRotationTransform = useMemo(
+    () => bandThumbRotation(resolvedOrientation, vertical),
+    [resolvedOrientation, vertical],
+  );
 
   const singleImageStyle = useMemo(
     () =>
@@ -437,14 +471,42 @@ export function PanoramaBandOverlay({
     [thumbRotationTransform],
   );
 
-  // Same rotation applied to the per-keyframe (multi-thumb) tiles.
-  const multiThumbStyle = useMemo(
-    () =>
-      thumbRotationTransform
-        ? [styles.multiThumb, { transform: thumbRotationTransform }]
-        : styles.multiThumb,
-    [thumbRotationTransform],
-  );
+  // v0.13.1 — per-keyframe tile rotation is conditional on `vertical`.
+  //
+  // The keyframe JPEGs (`keyframe-N.jpg`) are saved as sensor-native
+  // landscape PIXELS *plus* an EXIF Orientation tag (= 6, "rotate 90°
+  // CW for display") — verified on-device: Android SM-A356U1 640×480
+  // + EXIF6, iOS iPhone16Pro 1920×1080 + EXIF6.  RN's <Image> (Fresco
+  // on Android, ImageIO on iOS) HONORS EXIF and auto-rotates each tile
+  // to gravity-upright on its own.  Whether a *further* JS transform is
+  // needed depends on the band box's coordinate frame:
+  //
+  //   vertical=false (portrait-locked UI): box is in portrait JS coords,
+  //     which align with the EXIF-upright tile → NO transform.  Applying
+  //     one here double-rotates (the original v0.12 bug — tiles appeared
+  //     90° off in portrait-locked landscape captures).  Verified fixed
+  //     on Android portrait-lock.
+  //   vertical=true (non-locked host, device-landscape): box is in
+  //     landscape JS coords, rotated 90° from the EXIF-upright tile →
+  //     the counter-rotation is STILL required (verified on iOS: with no
+  //     transform the tiles sit 90° off).
+  //
+  // So reuse `thumbRotationTransform` (which already encodes the correct
+  // per-orientation angle) ONLY in the vertical=true branch.
+  //
+  // The single cumulative thumb above always needs the transform: its
+  // source (`panorama-*.jpg`) is a JFIF with NO EXIF tag (verified:
+  // header ff d8 ff e0), so RN never auto-rotates it.
+  //
+  // Stitcher is unaffected — it reads `keyframe-N.jpg` with EXIF IGNORED
+  // (IMREAD_IGNORE_ORIENTATION) so it still gets the sensor-native
+  // pixels its pose intrinsics expect.  Display-only.
+  const multiThumbStyle = useMemo(() => {
+    const tileTransform = tileRotation(resolvedOrientation, vertical);
+    return tileTransform
+      ? [styles.multiThumb, { transform: tileTransform }]
+      : styles.multiThumb;
+  }, [resolvedOrientation, vertical]);
 
   return (
     <View pointerEvents="none" style={[styles.bandBase, layout.band]}>

package/src/camera/PanoramaConfirmModal.tsx

@@ -88,6 +88,16 @@ export function PanoramaConfirmModal({
       animationType="fade"
       transparent
       statusBarTranslucent
+      // v0.13.1 — RN's iOS <Modal> defaults to portrait-only.  Declare
+      // all four so the confirm modal stays aligned with the interface
+      // under a non-locked host.  Mirrors OrientationDriftModal +
+      // PanoramaSettingsModal (v0.12) and CapturePreview (v0.13.1).
+      supportedOrientations={[
+        'portrait',
+        'portrait-upside-down',
+        'landscape-left',
+        'landscape-right',
+      ]}
       onRequestClose={onDiscard}
     >
       <View style={styles.backdrop}>

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

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for the band/tile orientation-decision functions in
+ * `PanoramaBandOverlay` — the pure logic behind the v0.13.1 EXIF
+ * double-rotation fix.
+ *
+ * Why test the pure functions, not a render: the lib's jest config is
+ * pure-TS (`ts-jest` + node env, no `@testing-library/react-native`;
+ * see jest.config.js header).  The orientation contract lives entirely
+ * in `bandThumbRotation` / `tileRotation`, which the component now calls
+ * directly — so exercising them here covers the real code path.
+ *
+ * The bug these guard against:
+ *   Saved `keyframe-N.jpg` files are sensor-native LANDSCAPE pixels with
+ *   EXIF Orientation = 6 ("rotate 90° CW").  RN's <Image> auto-rotates
+ *   them upright.  v0.12 ALSO applied a JS rotate transform to the tiles
+ *   → double-rotation → thumbnails 90° off in portrait-locked landscape.
+ *   The fix: tiles get NO transform in the portrait-locked
+ *   (vertical=false) path; the single cumulative thumb (no EXIF) still
+ *   does.
+ */
+
+// Mock react-native so importing the SUT module doesn't pull the native
+// StyleSheet/Image bridge (we only call the pure functions).  Matches
+// the mocking approach in useOrientationDrift.test.ts.
+jest.mock('react-native', () => ({
+  Image: 'Image',
+  ScrollView: 'ScrollView',
+  StyleSheet: { create: (s: Record<string, unknown>) => s, absoluteFill: {} },
+  Text: 'Text',
+  View: 'View',
+}));
+
+import {
+  _bandThumbRotationForTests as bandThumbRotation,
+  _tileRotationForTests as tileRotation,
+  type BandCaptureOrientation,
+} from '../PanoramaBandOverlay';
+
+const PORTRAIT: BandCaptureOrientation = 'portrait';
+const UPSIDE: BandCaptureOrientation = 'portrait-upside-down';
+const LEFT: BandCaptureOrientation = 'landscape-left';
+const RIGHT: BandCaptureOrientation = 'landscape-right';
+
+describe('bandThumbRotation — single cumulative thumb (no EXIF source)', () => {
+  describe('vertical=false (portrait-locked UI)', () => {
+    it('does not rotate in portrait', () => {
+      expect(bandThumbRotation(PORTRAIT, false)).toBeUndefined();
+    });
+
+    it('does not rotate in portrait-upside-down', () => {
+      expect(bandThumbRotation(UPSIDE, false)).toBeUndefined();
+    });
+
+    it('rotates 90° CW for landscape-left', () => {
+      expect(bandThumbRotation(LEFT, false)).toEqual([{ rotate: '90deg' }]);
+    });
+
+    it('rotates 90° CCW for landscape-right (opposite sign of left)', () => {
+      expect(bandThumbRotation(RIGHT, false)).toEqual([{ rotate: '-90deg' }]);
+    });
+  });
+
+  describe('vertical=true (non-locked, OS-rotated framebuffer)', () => {
+    it('does not rotate in portrait', () => {
+      expect(bandThumbRotation(PORTRAIT, true)).toBeUndefined();
+    });
+
+    it('uses the OPPOSITE sign from the portrait-locked case (left)', () => {
+      // vertical=false → 90deg, so vertical=true → -90deg.
+      expect(bandThumbRotation(LEFT, true)).toEqual([{ rotate: '-90deg' }]);
+      expect(bandThumbRotation(LEFT, true)).not.toEqual(
+        bandThumbRotation(LEFT, false),
+      );
+    });
+
+    it('uses the OPPOSITE sign from the portrait-locked case (right)', () => {
+      expect(bandThumbRotation(RIGHT, true)).toEqual([{ rotate: '90deg' }]);
+      expect(bandThumbRotation(RIGHT, true)).not.toEqual(
+        bandThumbRotation(RIGHT, false),
+      );
+    });
+  });
+});
+
+describe('tileRotation — per-keyframe tiles (EXIF-6 source, the fix)', () => {
+  describe('vertical=false (portrait-locked) — the regression case', () => {
+    it.each<[BandCaptureOrientation]>([
+      [PORTRAIT],
+      [UPSIDE],
+      [LEFT],
+      [RIGHT],
+    ])(
+      'applies NO transform for %s (EXIF already auto-rotates → no double-rotate)',
+      (orientation) => {
+        expect(tileRotation(orientation, false)).toBeUndefined();
+      },
+    );
+
+    it('specifically does NOT rotate landscape tiles (the v0.12 bug)', () => {
+      // Pre-fix this returned [{rotate:'90deg'}] / [{rotate:'-90deg'}]
+      // on top of the EXIF auto-rotate → tiles 90° off.  Must be undefined.
+      expect(tileRotation(LEFT, false)).toBeUndefined();
+      expect(tileRotation(RIGHT, false)).toBeUndefined();
+    });
+  });
+
+  describe('vertical=true (non-locked landscape) — transform still needed', () => {
+    it('matches bandThumbRotation in the vertical path', () => {
+      // In the OS-rotated case the box is landscape JS coords, 90° off
+      // the EXIF-upright tile, so the compensation IS required.
+      expect(tileRotation(LEFT, true)).toEqual(bandThumbRotation(LEFT, true));
+      expect(tileRotation(RIGHT, true)).toEqual(bandThumbRotation(RIGHT, true));
+    });
+
+    it('does not rotate in portrait even when vertical', () => {
+      expect(tileRotation(PORTRAIT, true)).toBeUndefined();
+    });
+  });
+});

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

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Unit tests for `homeIndicatorEdge` + `isSideEdge` — the pure functions
+ * that produce the `vertical` flag driving PanoramaBandOverlay and
+ * CaptureThumbnailStrip layout under non-locked hosts.
+ *
+ *   vertical = isSideEdge(homeIndicatorEdge(jsLandscape, deviceOrient))
+ *
+ * Contract (v0.12 orientation-aware Camera):
+ *   - Portrait JS layout (jsLandscape=false) → 'bottom' edge → NOT a
+ *     side edge → vertical=false (horizontal strip, the portrait-locked
+ *     case that's the recommended config).
+ *   - Landscape JS layout → 'right'/'left' edge → side edge →
+ *     vertical=true (the strip/band stack along the home-indicator edge).
+ *
+ * Pure-TS test per jest.config.js (no component mount).  The functions
+ * are imported via Camera.tsx's `_*ForTests` handles; react-native and
+ * the heavy native deps are mocked so the import resolves in node env.
+ */
+
+// The SUT lives in Camera.tsx, which transitively imports the entire
+// camera surface (vision-camera, worklets, sensors, native modules).
+// We only call two pure functions, so stub the whole dependency tree.
+jest.mock('react-native', () => ({
+  NativeModules: {},
+  Platform: { OS: 'ios', select: (o: Record<string, unknown>) => o.ios },
+  Pressable: 'Pressable',
+  StyleSheet: { create: (s: Record<string, unknown>) => s, absoluteFill: {} },
+  Text: 'Text',
+  View: 'View',
+  Image: 'Image',
+  ScrollView: 'ScrollView',
+  Animated: { View: 'Animated.View', Value: class {}, timing: () => ({ start: () => undefined }) },
+  Modal: 'Modal',
+  ActivityIndicator: 'ActivityIndicator',
+  useWindowDimensions: () => ({ width: 0, height: 0 }),
+  requireNativeComponent: () => 'NativeComponent',
+  UIManager: { getViewManagerConfig: () => ({}) },
+  findNodeHandle: () => 1,
+}));
+jest.mock('react-native-safe-area-context', () => ({
+  useSafeAreaInsets: () => ({ top: 0, bottom: 0, left: 0, right: 0 }),
+}));
+jest.mock('react-native-sensors', () => ({
+  accelerometer: { subscribe: jest.fn(() => ({ unsubscribe: jest.fn() })) },
+  setUpdateIntervalForType: jest.fn(),
+  SensorTypes: { accelerometer: 'accelerometer' },
+}));
+jest.mock('react-native-worklets-core', () => ({ Worklets: {} }));
+jest.mock('react-native-vision-camera', () => ({
+  Camera: 'Camera',
+  useCameraDevice: jest.fn(),
+  useCameraPermission: jest.fn(),
+}));
+
+import {
+  _homeIndicatorEdgeForTests as homeIndicatorEdge,
+  _isSideEdgeForTests as isSideEdge,
+} from '../Camera';
+import type { DeviceOrientation } from '../useDeviceOrientation';
+
+const PORTRAIT: DeviceOrientation = 'portrait';
+const UPSIDE: DeviceOrientation = 'portrait-upside-down';
+const LEFT: DeviceOrientation = 'landscape-left';
+const RIGHT: DeviceOrientation = 'landscape-right';
+
+// The composed signal the band/strip actually consume.
+const vertical = (jsLandscape: boolean, o: DeviceOrientation) =>
+  isSideEdge(homeIndicatorEdge(jsLandscape, o));
+
+describe('homeIndicatorEdge', () => {
+  it('returns bottom for any portrait JS layout (jsLandscape=false)', () => {
+    // Portrait JS layout always anchors bottom regardless of the sensor
+    // value — this is the portrait-locked case (the recommended config).
+    for (const o of [PORTRAIT, UPSIDE, LEFT, RIGHT]) {
+      expect(homeIndicatorEdge(false, o)).toBe('bottom');
+    }
+  });
+
+  it('anchors RIGHT for landscape-left device in landscape JS layout', () => {
+    expect(homeIndicatorEdge(true, LEFT)).toBe('right');
+  });
+
+  it('anchors LEFT for landscape-right device in landscape JS layout', () => {
+    expect(homeIndicatorEdge(true, RIGHT)).toBe('left');
+  });
+
+  it('falls through to right for non-landscape sensor + landscape JS (transient)', () => {
+    // jsLandscape=true with a portrait sensor reading only happens
+    // mid-rotation; defensive default is 'right'.
+    expect(homeIndicatorEdge(true, PORTRAIT)).toBe('right');
+    expect(homeIndicatorEdge(true, UPSIDE)).toBe('right');
+  });
+});
+
+describe('isSideEdge', () => {
+  it('is true only for left/right edges', () => {
+    expect(isSideEdge('left')).toBe(true);
+    expect(isSideEdge('right')).toBe(true);
+    expect(isSideEdge('bottom')).toBe(false);
+    expect(isSideEdge('top')).toBe(false);
+  });
+});
+
+describe('vertical flag (composed) — what the strip/band consume', () => {
+  it('is FALSE for portrait-locked layout (horizontal strip, recommended)', () => {
+    for (const o of [PORTRAIT, UPSIDE, LEFT, RIGHT]) {
+      expect(vertical(false, o)).toBe(false);
+    }
+  });
+
+  it('is TRUE for both landscape orientations under a non-locked host', () => {
+    expect(vertical(true, LEFT)).toBe(true);
+    expect(vertical(true, RIGHT)).toBe(true);
+  });
+});