react-native-image-stitcher 0.1.3 → 0.2.0

package/dist/sensors/useIMUTranslationGate.js

@@ -1,235 +1,139 @@
 "use strict";
 // SPDX-License-Identifier: Apache-2.0
 //
-// useIMUTranslationGate.ts — JS-side IMU translation tracker for the
-// non-AR translation-warning banner + (optional) gate force-accept.
-//
-// 2026-05-17 (Issue #4-A v3): rewritten on top of `expo-sensors`
-// `DeviceMotion` (which returns gravity-subtracted linear
-// acceleration via Apple's CoreMotion fusion on iOS and Android's
-// `TYPE_LINEAR_ACCELERATION` sensor on Android — both significantly
-// less noisy than raw accel + JS-side IIR gravity subtraction).
-// Tracks a SINGLE device-frame axis (device-X — the phone's lateral /
-// short side) rather than the 3D translation magnitude.
-//
-// Why exists
-// ──────────
-//
-// In non-AR mode the SDK has no ARSession pose stream, so the shared
-// C++ `KeyframeGate`'s translation-budget feature stays at zero and
-// never trips.  This hook fills the gap on the JS side and emits a
-// budget-crossed callback the host can wire to either:
-//
-//   (a) `markNextFrameAsLastKeyframe()` — tell the gate "force-accept
-//       the next frame regardless of overlap", so the trailing-edge
-//       frame still lands when the operator translates instead of
-//       rotates.
-//
-//   (b) A user-facing warning banner ("Rotate the camera instead of
-//       moving it sideways" — see AuditCaptureScreen).
-//
-// AuditCaptureScreen wires it to both.
+// useIMUTranslationGate — JS-side IMU translation tracker that fires
+// a callback when integrated lateral displacement on the device-X
+// axis exceeds a budget.  Drives `<Camera>`'s non-AR keyframe-
+// acceptance path: every time the gate fires, the host calls the
+// C++ engine's `markNextFrameAsLastKeyframe()` so the trailing frame
+// lands as a keyframe regardless of what the flow-novelty algorithm
+// alone would decide.
+//
+// V0.2 history note
+// ─────────────────
+// 0.1.x used `expo-sensors`' `DeviceMotion.acceleration`, which
+// returned gravity-subtracted linear acceleration via CoreMotion's
+// native fusion (iOS) / Android's `TYPE_LINEAR_ACCELERATION` sensor
+// (Android) — both significantly less noisy than raw accel + JS-side
+// gravity subtraction.  v0.2 drops the Expo modules dependency
+// (see CHANGELOG / docs/host-app-integration.md), so the gate is now
+// implemented on `react-native-sensors`' raw `accelerometer` with a
+// JS-side IIR low-pass to estimate the gravity vector.  The IIR
+// version is noisier — expect a few extra cm of apparent drift on a
+// stationary phone over several seconds — but the budget threshold
+// (~8 cm at default `flowMaxTranslationCm = 8`) and the anchor
+// resets (every accepted keyframe + recording start) keep the
+// per-interval drift window short enough that the budget still
+// meaningfully discriminates real translation from noise.
 //
 // Why device-X (the shorter side)
 // ───────────────────────────────
-//
 // We track motion ALONG the pan axis (the direction the operator is
 // supposed to be rotating-through but might be translating-through
-// instead) because translation orthogonal to the pan axis is
-// acceptable — vertical translation while panning horizontally in
-// portrait, for example, doesn't cause horizontal parallax.
-//
-// The pan axis maps to device-X in BOTH supported orientations
-// (per memory/ar-stitching-two-modes.md):
-//
-//   Portrait  + horizontal pan: device-X = user-left/right = pan axis.
+// instead).  In BOTH supported pan modes the pan axis maps to
+// device-X:
+//   Portrait  + horizontal pan: device-X = user-left/right.
 //   Landscape + vertical   pan: device-X has rotated 90° into the
-//                                user's up/down direction = pan axis.
-//
-// The lateral axis of the phone (its short side) always aligns with
-// the pan direction in either supported mode, so a single-axis
-// tracker works without needing to know which orientation we're in.
+//                                user's up/down direction.
+// So a single-axis tracker works without knowing the orientation.
 //
 // Drift mitigation
 // ────────────────
-//
-// `DeviceMotion.acceleration` (gravity removed in native code via
-// IMU fusion) has a noise floor roughly 30-50 % lower than what the
-// previous raw-accel + JS IIR pipeline produced.  Single-axis math
-// further reduces apparent drift by ≈√3 vs the prior 3D magnitude.
-// Together they should keep the typical "stationary phone" reading
-// below ~5-10 cm even after several seconds.
-//
-// Anchor resets happen at (a) recording start (via the host calling
-// `resetAnchor()` from handleHoldStart) and (b) every accepted
-// keyframe — these bound the per-interval drift window to typically
-// 0.3-2 s.
-//
-// What we no longer do
-// ────────────────────
-//
-//   - JS-side 1-pole IIR for gravity subtraction (native API gives
-//     gravity-subtracted accel directly).
-//   - 3D vector magnitude (now single device-X axis).
-//   - Velocity damping (kept as a safety net at 5%/sample so a
-//     persistent noise-floor offset doesn't slowly drift the axis —
-//     low cost, high robustness).
+// 1. IIR low-pass on the raw X accel estimates the gravity offset.
+//    Subtracting that gives linear-acceleration-on-X.  Alpha = 0.9
+//    at the default 50 Hz sample rate → ~200 ms gravity tracking
+//    time constant.  Slow enough that hand motion (>1 Hz) gets
+//    through; fast enough to converge after device rotations within
+//    ~1 second.
+// 2. Per-sample velocity damping at 5 % so a constant noise-floor
+//    offset decays to ~1 % of its initial value in 2 s.  This caps
+//    apparent drift for a stationary phone.
+// 3. Anchor reset on recording start AND every accepted keyframe
+//    (callers do this) — bounds the integration window to typically
+//    0.3-2 s, well inside the regime where IIR-estimated linear
+//    accel is usable.
+//
+// Platform unit handling
+// ──────────────────────
+// `react-native-sensors`' accelerometer reports:
+//   iOS:     values in G's (multiples of 9.81 m/s²), via CoreMotion.
+//   Android: values in m/s², via Sensor.TYPE_ACCELEROMETER.
+// We scale iOS by `G_TO_MPS2` so the integration math stays in
+// standard m/s², m/s, m units.  Sign convention doesn't matter for
+// the gate because the gravity offset is estimated and subtracted
+// per-axis; what's left is the platform-agnostic linear acceleration.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useIMUTranslationGate = useIMUTranslationGate;
 const react_1 = require("react");
-const expo_sensors_1 = require("expo-sensors");
-/**
- * IMU-based translation tracker — single-axis (device-X / pan axis),
- * fused IMU via `expo-sensors` `DeviceMotion`.  See file header for
- * algorithm + rationale.  No platform-specific code; the underlying
- * native fusion is platform-aware (CoreMotion on iOS, fused
- * `TYPE_LINEAR_ACCELERATION` on Android).
- */
-function useIMUTranslationGate(options) {
-    const { enabled, budgetMeters = 0.40, sampleIntervalMs = 20, onBudgetExceeded, debug = false, } = options;
-    // Integrator state, kept in refs so the listener can write without
-    // re-creating its closure on every render.
-    // ─ velX  : velocity along device-X (m/s)
-    // ─ posX  : position along device-X (m)
-    // ─ lastMs: epoch ms of the previous sample (for dt)
-    // ─ budgetCrossed: debounce flag — clears on resetAnchor
-    // ─ sampleCount: rolling counter for debug log throttle
-    // ─ anchorMs: timestamp of the most recent resetAnchor (or first
-    //             sample) — gives "time since anchor" in debug output
-    const velX = (0, react_1.useRef)(0);
-    const posX = (0, react_1.useRef)(0);
-    const lastMs = (0, react_1.useRef)(0);
-    const budgetCrossed = (0, react_1.useRef)(false);
-    const sampleCount = (0, react_1.useRef)(0);
-    const anchorMs = (0, react_1.useRef)(0);
-    // Keep the callback in a ref so we don't tear down + re-subscribe
-    // on every prop change.  React idiom for stable callback identity.
-    const onBudgetExceededRef = (0, react_1.useRef)(onBudgetExceeded);
-    (0, react_1.useEffect)(() => { onBudgetExceededRef.current = onBudgetExceeded; }, [onBudgetExceeded]);
+const react_native_1 = require("react-native");
+const react_native_sensors_1 = require("react-native-sensors");
+const DEFAULT_BUDGET_METERS = 0.40;
+const DEFAULT_SAMPLE_INTERVAL_MS = 20;
+/// Per-sample multiplicative damping on the velocity integrator.
+/// 5 % at 50 Hz → constant offset decays to ~1 % in 2 s.  Bounds
+/// the apparent-drift window for a stationary phone.
+const VELOCITY_DAMPING_PER_SAMPLE = 0.05;
+/// IIR low-pass coefficient for the gravity estimate.  At 50 Hz
+/// this gives ~200 ms time constant.  Higher = slower gravity
+/// tracking (more lag during device rotation, less hand-motion
+/// bleed into the gravity estimate); lower = faster.
+const GRAVITY_IIR_ALPHA = 0.9;
+/// 1 G in m/s².  Standard gravity per CGPM 1901 (good to all the
+/// digits anyone cares about for this application).
+const G_TO_MPS2 = 9.81;
+function useIMUTranslationGate({ enabled, budgetMeters = DEFAULT_BUDGET_METERS, sampleIntervalMs = DEFAULT_SAMPLE_INTERVAL_MS, onBudgetExceeded, }) {
+    // All running-integrator state lives in a single ref so the
+    // subscription callback can update it without forcing a re-render
+    // every frame (50 Hz worth of re-renders would tank performance).
+    const stateRef = (0, react_1.useRef)({
+        posX: 0,
+        velX: 0,
+        /// NaN sentinel for "uninitialised"; first sample seeds it.
+        gravityX: NaN,
+        fired: false,
+    });
+    // Latest onBudgetExceeded callback in a ref so callers can pass
+    // an inline closure that captures fresh state without us re-
+    // subscribing the sensor (which would reset the integrators).
+    const onExceededRef = (0, react_1.useRef)(onBudgetExceeded);
+    onExceededRef.current = onBudgetExceeded;
+    const resetAnchor = (0, react_1.useCallback)(() => {
+        const s = stateRef.current;
+        s.posX = 0;
+        s.velX = 0;
+        s.fired = false;
+        // s.gravityX is intentionally preserved — see header.
+    }, []);
     (0, react_1.useEffect)(() => {
-        if (debug) {
-            // eslint-disable-next-line no-console
-            console.log(`[IMUTransGate] effect re-run: enabled=${enabled} `
-                + `budget=${budgetMeters.toFixed(2)}m sampleIntervalMs=${sampleIntervalMs}`);
-        }
         if (!enabled)
             return;
-        // Lock in the DeviceMotion update rate.  Other expo-sensors
-        // consumers in the SDK can override later; the LAST setter wins
-        // per Expo's docs, which is fine because our budget logic
-        // tolerates a wide range of cadences.
-        expo_sensors_1.DeviceMotion.setUpdateInterval(sampleIntervalMs);
-        // Reset state on (re-)engage so the first measurement after
-        // enabled-toggles-true doesn't carry stale velocity from a
-        // previous capture session.
-        velX.current = 0;
-        posX.current = 0;
-        lastMs.current = 0;
-        budgetCrossed.current = false;
-        sampleCount.current = 0;
-        anchorMs.current = Date.now();
-        // 2026-05-18 (Issue #3 diagnostics) — track whether we've ever
-        // received a non-null `acceleration` for this subscription.  If
-        // the user reports "no logs" we can correlate with these
-        // start-of-subscription and first-real-data markers.
-        let everGotData = false;
-        let nullSampleCount = 0;
-        if (debug) {
-            // eslint-disable-next-line no-console
-            console.log('[IMUTransGate] subscribing to DeviceMotion');
-        }
-        const sub = expo_sensors_1.DeviceMotion.addListener((m) => {
-            const a = m.acceleration; // gravity-subtracted (m/s²)
-            if (!a) {
-                nullSampleCount += 1;
-                if (debug && nullSampleCount === 1) {
-                    // eslint-disable-next-line no-console
-                    console.log('[IMUTransGate] first sample: acceleration=null '
-                        + '(CoreMotion warming up; will retry on next sample)');
-                }
-                if (debug && nullSampleCount > 0 && nullSampleCount % 100 === 0) {
-                    // eslint-disable-next-line no-console
-                    console.log(`[IMUTransGate] STILL receiving null acceleration after `
-                        + `${nullSampleCount} samples — sensor source may be broken`);
-                }
-                return; // can be null briefly on cold start
-            }
-            if (debug && !everGotData) {
-                everGotData = true;
-                // eslint-disable-next-line no-console
-                console.log(`[IMUTransGate] first real sample: ax=${a.x.toFixed(3)} `
-                    + `ay=${a.y.toFixed(3)} az=${a.z.toFixed(3)} m/s² `
-                    + `(after ${nullSampleCount} null sample(s))`);
-            }
-            const now = Date.now();
-            if (lastMs.current === 0) {
-                lastMs.current = now;
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.accelerometer, sampleIntervalMs);
+        const scale = react_native_1.Platform.OS === 'ios' ? G_TO_MPS2 : 1;
+        const dt = sampleIntervalMs / 1000.0;
+        const sub = react_native_sensors_1.accelerometer.subscribe(({ x }) => {
+            const ax = x * scale; // device-X acceleration in m/s²
+            const s = stateRef.current;
+            // First sample: seed gravity from this reading.  Assumes the
+            // phone is roughly stationary at recording start — true in
+            // practice because the operator just tap-and-held the shutter.
+            if (Number.isNaN(s.gravityX)) {
+                s.gravityX = ax;
                 return;
             }
-            const dt = Math.max(0, Math.min(0.1, (now - lastMs.current) / 1000.0));
-            lastMs.current = now;
-            if (dt === 0)
-                return;
-            // Single-axis integration along device-X (lateral / pan axis).
-            // See file header for why device-X is the right axis in both
-            // portrait and landscape captures.
-            velX.current += a.x * dt;
-            velX.current *= 0.95; // 5%/sample damping — see file header
-            posX.current += velX.current * dt;
-            const mag = Math.abs(posX.current);
-            // 2026-05-18 (Issue #4 investigation) — debug-gated diagnostic
-            // log.  Throttled to every 20th sample (~400 ms at 50 Hz) so
-            // the log isn't a firehose.  When this runs and we still see
-            // posX hovering at < 5 cm during a real translation, the
-            // sensor source isn't capturing what we think it is.
-            sampleCount.current += 1;
-            if (debug && sampleCount.current % 20 === 0) {
-                const secs = (now - anchorMs.current) / 1000.0;
-                // eslint-disable-next-line no-console
-                console.log(`[IMUTransGate] t+${secs.toFixed(2)}s `
-                    + `ax=${a.x.toFixed(3)}m/s² `
-                    + `velX=${velX.current.toFixed(4)}m/s `
-                    + `posX=${posX.current.toFixed(4)}m `
-                    + `(|mag|=${mag.toFixed(4)}m, budget=${budgetMeters.toFixed(2)}m, crossed=${budgetCrossed.current})`);
-            }
-            // Budget crossing — fire exactly once per crossing (the
-            // `budgetCrossed` flag clears on `resetAnchor`).
-            if (!budgetCrossed.current && mag >= budgetMeters) {
-                budgetCrossed.current = true;
-                if (debug) {
-                    // eslint-disable-next-line no-console
-                    console.log(`[IMUTransGate] BUDGET CROSSED at posX=${posX.current.toFixed(4)}m `
-                        + `(budget=${budgetMeters.toFixed(2)}m)`);
-                }
-                onBudgetExceededRef.current();
+            // IIR low-pass to track the gravity component on device-X.
+            s.gravityX = GRAVITY_IIR_ALPHA * s.gravityX + (1 - GRAVITY_IIR_ALPHA) * ax;
+            // Linear acceleration on X = raw - gravity estimate.
+            const linX = ax - s.gravityX;
+            // Single integration with per-sample velocity damping.
+            s.velX = (s.velX + linX * dt) * (1 - VELOCITY_DAMPING_PER_SAMPLE);
+            s.posX += s.velX * dt;
+            if (!s.fired && Math.abs(s.posX) > budgetMeters) {
+                s.fired = true;
+                onExceededRef.current();
             }
         });
-        return () => {
-            if (debug) {
-                // eslint-disable-next-line no-console
-                console.log(`[IMUTransGate] unsubscribing (everGotData=${everGotData}, `
-                    + `nullSamples=${nullSampleCount}, realSamples=${sampleCount.current})`);
-            }
-            sub.remove();
-        };
-    }, [enabled, budgetMeters, sampleIntervalMs, debug]);
-    // 2026-05-18 (Issue B meta-bug fix): wrap the returned functions in
-    // useCallback so the hook's return value is REFERENTIALLY STABLE
-    // across renders.  Consumer code (AuditCaptureScreen) puts `imuGate`
-    // in a useEffect dep array; without stability that effect re-runs
-    // every render, wiping out the prevAcceptedCount delta-tracker
-    // (which is what caused the resetAnchor-too-often bug we just
-    // diagnosed).  These functions only touch refs, so empty-deps
-    // useCallback is safe — no stale-closure risk.
-    const resetAnchor = (0, react_1.useCallback)(() => {
-        velX.current = 0;
-        posX.current = 0;
-        lastMs.current = 0;
-        budgetCrossed.current = false;
-        sampleCount.current = 0;
-        anchorMs.current = Date.now();
-    }, []);
-    const getCurrentTranslationM = (0, react_1.useCallback)(() => Math.abs(posX.current), []);
-    return { resetAnchor, getCurrentTranslationM };
+        return () => sub.unsubscribe();
+    }, [enabled, budgetMeters, sampleIntervalMs]);
+    return { resetAnchor };
 }
 //# sourceMappingURL=useIMUTranslationGate.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -53,7 +53,6 @@
   "homepage": "https://github.com/bhargavkanda/react-native-image-stitcher#readme",
   "devDependencies": {
     "@types/react": "^19.0.0",
-    "expo-sensors": "^14.0.0",
     "react": "^19.0.0",
     "react-native": "^0.84.0",
     "react-native-safe-area-context": "^4.0.0",
@@ -67,7 +66,6 @@
     "react-native": ">=0.72.0",
     "react-native-vision-camera": ">=4.7.0",
     "react-native-sensors": ">=7.0.0",
-    "expo-sensors": ">=14.0.0",
     "react-native-safe-area-context": ">=4.0.0"
   }
 }

package/src/camera/Camera.tsx

@@ -661,7 +661,11 @@ export function Camera(props: CameraProps): React.JSX.Element {
     return () => { cancelled = true; };
   }, [isAR, lens]);
 
-  // IMU translation gate — only in non-AR mode.
+  // IMU translation gate — only engaged in non-AR mode.  Fires when
+  // the operator's lateral hand motion exceeds the budget, telling
+  // the C++ engine to force-accept the next frame.  This is what
+  // keeps non-AR captures producing keyframes at all (the flow-
+  // novelty algorithm alone is too strict in practice).
   const imuGate = useIMUTranslationGate({
     enabled:
       isNonAR

package/src/camera/useDeviceOrientation.ts

@@ -12,42 +12,49 @@
  * the app is orientation-locked: window dimensions don't change
  * when only the device rotates.
  *
- * 2026-05-18 (Issue #3) — rewritten on top of `expo-sensors`
- * `DeviceMotion` (CoreMotion-fused on iOS, SensorManager on
- * Android).  The previous implementation used
- * `react-native-sensors` raw accelerometer with an Android-only
- * sign convention (`y > 0` ⇒ portrait), which silently failed on
- * iOS — Apple's CoreMotion convention is `y < 0` ⇒ portrait
- * because device-Y points from the phone's bottom to the top,
- * and gravity in that frame is `-Y`.  Users on iOS saw the hook
- * stuck at its initial value ('portrait') regardless of physical
- * rotation, which cascaded into wrong panorama bake-rotation and
- * a broken landscape band layout.
+ * 2026-05-21 (v0.2 — Expo modules removal) — rewritten back onto
+ * `react-native-sensors` accelerometer.  `expo-sensors`'
+ * `DeviceMotion` was used previously (Issue #3 / 2026-05-18) because
+ * it normalised Android signs to iOS convention for us, but that
+ * pulled the entire Expo modules runtime into every consuming
+ * host app — a heavy tax for one orientation hook (see
+ * `docs/host-app-integration.md`).  We now do the same sign
+ * normalisation explicitly in JS and stay on `react-native-sensors`
+ * (already a peer dep for the pan-guide gyroscope).
  *
  * Sign conventions used here (per platform docs):
  *
- *   iOS (CMDeviceMotion.accelerationIncludingGravity, reported in
- *   m/s² in the device reference frame):
- *     portrait              → y ≈ -9.8
- *     portrait-upside-down  → y ≈ +9.8
- *     landscape-left  (home indicator on user's RIGHT) → x ≈ +9.8
- *     landscape-right (home indicator on user's LEFT)  → x ≈ -9.8
+ *   iOS (CMAccelerometerData, reported in G's; react-native-sensors
+ *   passes through, in m/s²-ish G-multiples):
+ *     portrait              → y ≈ -1   (gravity along device -Y)
+ *     portrait-upside-down  → y ≈ +1
+ *     landscape-left  (home indicator on user's RIGHT) → x ≈ +1
+ *     landscape-right (home indicator on user's LEFT)  → x ≈ -1
  *
- *   Android (Sensor.TYPE_ACCELEROMETER, reaction-force convention):
- *     portrait              → y ≈ +9.8   ← opposite sign vs iOS
+ *   Android (Sensor.TYPE_ACCELEROMETER, reaction-force convention,
+ *   m/s²):
+ *     portrait              → y ≈ +9.8  ← OPPOSITE SIGN vs iOS
  *     portrait-upside-down  → y ≈ -9.8
  *     landscape-left        → x ≈ -9.8
  *     landscape-right       → x ≈ +9.8
  *
- *   We flip the Android x/y to match the iOS convention before
- *   classification so the rest of the logic stays platform-
- *   independent.  The classification then unambiguously maps to
- *   the user-visible `DeviceOrientation` enum.
+ *   We flip the Android x/y signs to match the iOS convention
+ *   before classification, so the classifier stays platform-
+ *   agnostic and operates entirely in iOS-convention values.
+ *   (Previous react-native-sensors implementation, pre-Issue-#3,
+ *   forgot this — Apple's CoreMotion convention is `y < 0` ⇒
+ *   portrait, but the old code used `y > 0` ⇒ portrait, so iOS
+ *   was stuck at the initial value regardless of rotation.  Don't
+ *   regress.)
  */
 
 import { useEffect, useState } from 'react';
-import { DeviceMotion } from 'expo-sensors';
-import type { DeviceMotionMeasurement } from 'expo-sensors';
+import { Platform } from 'react-native';
+import {
+  accelerometer,
+  setUpdateIntervalForType,
+  SensorTypes,
+} from 'react-native-sensors';
 
 
 export type DeviceOrientation =
@@ -57,59 +64,43 @@ export type DeviceOrientation =
   | 'landscape-right';
 
 
-/// Threshold (m/s²) above which gravity dominance is considered
-/// conclusive.  5 m/s² out of ~9.8 means the phone is at least ~30°
-/// tilted toward that axis — comfortable for stable orientation
-/// classification without flipping on minor wobbles.
-const DOMINANT_AXIS_THRESHOLD = 5.0;
+/// Threshold above which a single axis is considered to dominate.
+/// Phone-at-rest under gravity reads ~1 G on whichever axis is
+/// aligned with vertical; the off-axis reading is ~0.  Anything
+/// more than half a G (~5 m/s² on Android, ~0.5 on iOS in G's) is
+/// safely in "dominant" territory without flipping on small wobbles.
+/// We compare against the magnitude after sign-normalisation, so
+/// the threshold is platform-dependent: iOS reports in G's,
+/// Android in m/s².
+const DOMINANT_AXIS_THRESHOLD_IOS = 0.5;        // G's
+const DOMINANT_AXIS_THRESHOLD_ANDROID = 5.0;    // m/s²
 
 /// Sample at ~10 Hz — plenty for orientation detection (phones
 /// don't physically flip faster than this).
 const SAMPLE_INTERVAL_MS = 100;
 
 
-function classify(x: number, y: number): DeviceOrientation | null {
-  // 2026-05-18 (Issue #3 round 2) — re-derived sign convention.
-  //
-  // Through expo-sensors, BOTH platforms normalize to the iOS
-  // CoreMotion gravity-vector convention: stationary phone reports
-  // the gravity vector itself in the device frame.  Device axes:
-  // +X points from phone-left to phone-right; +Y from phone-bottom
-  // to phone-top; +Z out of the screen toward the viewer.
-  //
-  // Per-orientation gravity-vector signs in the device frame:
-  //
-  //   portrait (upright)      → y ≈ -9.8
-  //     Phone-Y points up in world; gravity is along device -Y.
-  //
-  //   portrait-upside-down    → y ≈ +9.8
-  //     Phone-Y points down in world; gravity is along device +Y.
-  //
-  //   landscape-left  (Apple: home indicator on user's RIGHT;
-  //                    phone rotated 90° CCW from portrait):
-  //     phone-X axis points from user-bottom to user-top in this
-  //     orientation, so gravity (world-down) is along device -X.
-  //     → x ≈ -9.8
-  //
-  //   landscape-right (Apple: home indicator on user's LEFT;
-  //                    phone rotated 90° CW from portrait):
-  //     phone-X axis points from user-top to user-bottom, so
-  //     gravity is along device +X.
-  //     → x ≈ +9.8
-  //
-  // The earlier implementation had an Android-specific axis flip
-  // baked in.  Removed — expo-sensors normalizes Android signs to
-  // match iOS, and the platform branch was producing wrong values
-  // (Android portrait → reported as portrait-upside-down; iOS
-  // landscape-left → reported as landscape-right).
+function classify(
+  x: number,
+  y: number,
+  threshold: number,
+): DeviceOrientation | null {
+  // Inputs are in iOS-convention gravity-vector signs:
+  //   +X points from phone-left to phone-right; +Y from phone-
+  //   bottom to phone-top; +Z out of the screen toward the viewer.
+  //   At rest under gravity:
+  //     portrait (upright)   → y ≈ -g  (phone-Y points up; gravity is -Y)
+  //     portrait-upside-down → y ≈ +g
+  //     landscape-left       → x ≈ -g  (phone-X points up; gravity is -X)
+  //     landscape-right      → x ≈ +g
   if (Math.abs(y) > Math.abs(x)) {
-    if (y < -DOMINANT_AXIS_THRESHOLD) return 'portrait';
-    if (y > DOMINANT_AXIS_THRESHOLD) return 'portrait-upside-down';
+    if (y < -threshold) return 'portrait';
+    if (y > threshold) return 'portrait-upside-down';
   } else {
-    if (x < -DOMINANT_AXIS_THRESHOLD) return 'landscape-left';
-    if (x > DOMINANT_AXIS_THRESHOLD) return 'landscape-right';
+    if (x < -threshold) return 'landscape-left';
+    if (x > threshold) return 'landscape-right';
   }
-  // Phone face-up or face-down (z dominates): keep the previous
+  // Phone face-up or face-down (z dominates) — keep the previous
   // orientation rather than flicker.
   return null;
 }
@@ -119,21 +110,26 @@ export function useDeviceOrientation(): DeviceOrientation {
   const [orientation, setOrientation] = useState<DeviceOrientation>('portrait');
 
   useEffect(() => {
-    DeviceMotion.setUpdateInterval(SAMPLE_INTERVAL_MS);
+    setUpdateIntervalForType(SensorTypes.accelerometer, SAMPLE_INTERVAL_MS);
+
+    const isAndroid = Platform.OS === 'android';
+    const threshold = isAndroid
+      ? DOMINANT_AXIS_THRESHOLD_ANDROID
+      : DOMINANT_AXIS_THRESHOLD_IOS;
 
     let last: DeviceOrientation = 'portrait';
-    const sub = DeviceMotion.addListener((m: DeviceMotionMeasurement) => {
-      const g = m.accelerationIncludingGravity;
-      // First emissions can be null on cold start while CoreMotion
-      // warms up; skip until data arrives.
-      if (!g) return;
-      const next = classify(g.x, g.y);
+    const sub = accelerometer.subscribe(({ x, y }) => {
+      // Normalise Android reaction-force convention to iOS gravity
+      // convention by flipping signs.  No-op on iOS.
+      const gx = isAndroid ? -x : x;
+      const gy = isAndroid ? -y : y;
+      const next = classify(gx, gy, threshold);
       if (next && next !== last) {
         last = next;
         setOrientation(next);
       }
     });
-    return () => sub.remove();
+    return () => sub.unsubscribe();
   }, []);
 
   return orientation;

package/src/index.ts

@@ -54,6 +54,9 @@ export type {
 // ─────────────────────────────────────────────────────────────────────
 // Hosts running their own non-AR capture flow can reuse this hook to
 // get the same translation-budget gating logic <Camera> uses internally.
+// As of v0.2 this hook is implemented on `react-native-sensors` raw
+// accelerometer + JS IIR gravity subtraction (was `expo-sensors`'
+// fused DeviceMotion through 0.1.x — see the hook's file header).
 export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
 export type {
   UseIMUTranslationGateOptions,