react-native-image-stitcher 0.11.1 → 0.13.0

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

package/src/camera/useOrientationDrift.ts

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 { useEffect, useState } from 'react';
+
+import {
+  useDeviceOrientation,
+  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;
+}
+
+
+const INITIAL_STATE: DriftState = {
+  captureOrientation: undefined,
+  drifted: false,
+};
+
+
+/**
+ * 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 function _computeDriftStateForTests(
+  prev: DriftState,
+  active: boolean,
+  currentOrientation: DeviceOrientation,
+): DriftState {
+  if (!active) {
+    // active is false (or just transitioned to false).  Clear the
+    // snapshot + drift flag.  Idempotent when already cleared.
+    if (prev.captureOrientation === undefined && !prev.drifted) {
+      return prev;
+    }
+    return INITIAL_STATE;
+  }
+
+  // active is true.
+  if (prev.captureOrientation === undefined) {
+    // false → true transition.  Snapshot the current orientation.
+    // drifted starts false because, by definition, the current
+    // orientation matches itself.
+    return { captureOrientation: currentOrientation, drifted: false };
+  }
+
+  // active is steady true.  Check for drift.  Latching: once
+  // drifted is true, never set it back to false until active
+  // flips (handled above).
+  if (!prev.drifted && currentOrientation !== prev.captureOrientation) {
+    return { captureOrientation: prev.captureOrientation, drifted: true };
+  }
+
+  // No transition + no new drift.  Return prev to avoid an
+  // unnecessary state update + re-render.
+  return prev;
+}
+
+
+export function useOrientationDrift(
+  active: boolean,
+): UseOrientationDriftReturn {
+  const currentOrientation = useDeviceOrientation();
+  const [state, setState] = useState<DriftState>(INITIAL_STATE);
+
+  useEffect(() => {
+    setState((prev) => _computeDriftStateForTests(prev, active, currentOrientation));
+  }, [active, currentOrientation]);
+
+  return {
+    drifted: state.drifted,
+    captureOrientation: state.captureOrientation,
+    currentOrientation,
+  };
+}

package/src/index.ts

@@ -162,6 +162,19 @@ export { useCapture } from './camera/useCapture';
 export type { TakePhotoCallOptions } from './camera/useCapture';
 export { useVideoCapture } from './camera/useVideoCapture';
 export { useDeviceOrientation } from './camera/useDeviceOrientation';
+export type { DeviceOrientation } from './camera/useDeviceOrientation';
+
+// v0.12.0 — orientation-aware Camera (R2-lite).  `useOrientationDrift`
+// snapshots the device orientation at capture start and latches a
+// `drifted` flag if the user rotates mid-capture.  Pairs with
+// `OrientationDriftModal` for the auto-abandon UX flow.  The
+// flagship `<Camera>` component wires both internally (PR-2);
+// Layer-2 hosts using `CameraView` directly can compose the pair
+// manually (see the modal's docstring for the integration pattern).
+export { useOrientationDrift } from './camera/useOrientationDrift';
+export type { UseOrientationDriftReturn } from './camera/useOrientationDrift';
+export { OrientationDriftModal } from './camera/OrientationDriftModal';
+export type { OrientationDriftModalProps } from './camera/OrientationDriftModal';
 
 // ── Incremental stitching engine ──────────────────────────────────────
 // JS bindings around the native `IncrementalStitcher` module.  Use

package/src/stitching/incremental.ts

@@ -139,9 +139,11 @@ export interface IncrementalState {
    * at the FIRST-FRAME determination thereafter.
    *
    * **This is the single source of truth for orientation across
-   * the SDK + host.**  JS-side hooks (e.g. `useDeviceOrientation`,
-   * `useWindowDimensions`) are unreliable when iOS interface-
-   * orientation lock is on; pose-derived detection is.  UI
+   * the SDK + host.**  Pose-derived detection is preferred over
+   * JS-side hooks because it works identically regardless of host
+   * configuration — `useWindowDimensions` reports JS-portrait when
+   * the host is portrait-locked (even with the device in landscape),
+   * while pose data reflects what the camera actually saw.  UI
    * components that need to know orientation (band overlay, dim
    * bars, pan guide) MUST consume `state.isLandscape` rather
    * than re-detecting.