react-native-image-stitcher 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -16,6 +16,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-05-21
+
+> [!IMPORTANT]
+> This release changes the peer-dependency contract in a
+> backward-incompatible way (semver-minor in 0.x).  The public hook
+> surface is preserved — no JS code changes are required for any
+> host that doesn't directly import `expo-sensors`.  Verified end-
+> to-end on iPhone 16 Pro (iOS 26.4.2) + Samsung Galaxy A35
+> (Android, SM_A356U1).
+
+### Removed
+
+- **`expo-sensors` is no longer a peer dependency.**  The SDK used to
+  pull in the entire Expo modules runtime (`expo`, `expo-modules-core`,
+  `expo-modules-autolinking`, `expo-sensors`) just for two hooks —
+  `useDeviceOrientation` and `useIMUTranslationGate`.  That tax was
+  disproportionate to the value (see the host-integration burden in
+  [`docs/host-app-integration.md`](docs/host-app-integration.md)).
+  Both hooks have been re-homed onto `react-native-sensors` (already
+  a peer dep), so the SDK now works on bare React Native with no
+  Expo modules infrastructure.
+
+### Changed
+
+- **`useDeviceOrientation` rewritten on `react-native-sensors`
+  accelerometer.**  Same `DeviceOrientation` return type, same
+  threshold-based dominant-axis classifier, same public signature.
+  The internal-only change is the source: instead of
+  `expo-sensors`' `DeviceMotion` (which normalised Android signs to
+  iOS convention for us), we now subscribe to
+  `react-native-sensors`' accelerometer and do the platform sign-
+  flip explicitly in JS (`Platform.OS === 'android' ? -value : value`).
+  Threshold is now platform-dependent because iOS reports in G's
+  and Android in m/s² — see the file header for the per-platform
+  numbers and the Issue #3 history that motivated keeping iOS as
+  the reference convention.
+- **`useIMUTranslationGate` rewritten on `react-native-sensors`
+  accelerometer + JS-side IIR gravity subtraction.**  Same public
+  signature, same options, same return shape, same on-budget-
+  exceeded callback semantics, same anchor-reset behaviour.  The
+  internal change: in 0.1.x the hook consumed `DeviceMotion.accel-
+  eration` (gravity-subtracted via CoreMotion's native fusion on iOS
+  / Android's `TYPE_LINEAR_ACCELERATION` on Android — both produced
+  by hardware sensor fusion).  v0.2 consumes raw accelerometer and
+  estimates the gravity vector with a JS IIR low-pass (alpha = 0.9
+  at 50 Hz → ~200 ms time constant), then subtracts.  **Noise
+  trade-off**: the JS IIR is measurably noisier than CoreMotion's
+  native fusion — expect a few extra cm of apparent drift on a
+  stationary phone over several seconds.  With the per-sample
+  velocity damping (5 %) and the anchor reset on every accepted
+  keyframe, the drift stays bounded inside a 0.3-2 s integration
+  window, which is comfortably under the default 8 cm budget.  If
+  the IIR floor becomes a problem in practice, we'll consider
+  moving the fusion into a small native module rather than re-
+  introducing the Expo modules dependency.
+
+### Migration from 0.1.x
+
+No JS code changes are required for any host — the public surface
+that survives 0.1.x → 0.2.0 is source-compatible.
+
+Native-side, you can now optionally rip out the entire Expo modules
+host wiring (Podfile `use_expo_modules!` macro, `AppDelegate.swift`
+Expo factory, `MainApplication.kt` `ExpoReactHostFactory`, the gradle
+`expo-root-project` plugin, the two `patch-package` patches for Expo
+SDK 55 on RN 0.84) — that whole section of
+[`docs/host-app-integration.md`](docs/host-app-integration.md) is
+optional from 0.2.0 onward and will be removed from the doc in a
+follow-up commit.
+
+## [0.1.3] — 2026-05-21
+
+### Changed
+
+- **Docs / source-comment cleanup.** Removed the leftover
+  pre-extraction RetaiLens-monorepo framing from the README — this repo
+  is now the canonical, self-contained source of `react-native-image-
+  stitcher`, not a downstream subtree of anything.  Source-file path
+  comments and iOS GCD queue labels now use the canonical
+  `io.imagestitcher.*` namespace and `react-native-image-stitcher/`
+  repo path instead of the leftover `com.retailens.*` /
+  `retailens-capture-sdk/` references that survived the 0.1.0 rename.
+  GCD label change affects: `RNSARSession.poseLogQueue`,
+  `IncrementalStitcher.workQueue`, `IncrementalStitcher.refineQueue` —
+  labels are diagnostic-only (Instruments / crash-report symbolication),
+  no public-API or behaviour impact.  The CHANGELOG.md migration table
+  for [0.1.0] retains the historical `com.retailens.capturesdk` name
+  intentionally — it documents the rename that shipped, not the
+  current state.
+- **CHANGELOG.** Added compare-links for [0.1.1] and [0.1.2] and fixed
+  the [Unreleased] compare base.  Annotated the [0.1.0] "Deliberately
+  NOT exported" section with a header note explaining that most of
+  those entries were promoted to public in [0.1.1] — see the 0.1.1
+  *Added* list for the current public surface.
+
 ## [0.1.2] — 2026-05-20
 
 ### Added
@@ -160,6 +255,16 @@ The following are intentionally internal so the public surface stays
 small.  If you have a real use-case for any of these, please open an
 issue describing it.
 
+> [!NOTE]
+> **This list reflects the v0.1.0 surface as shipped.**  Most of the
+> entries below — the layer-2 hooks, views, UI components, and
+> incremental-engine primitives — were subsequently promoted to public
+> in [0.1.1].  See the 0.1.1 *Added* section for the current public
+> surface; only a few items below remain internal in later releases
+> (`CameraShutter`, `PanoramaConfirmModal`, `IncrementalStitcherView`,
+> `stitchFrames`, `StitchNotImplementedError`, `runQualityCheck`,
+> `normaliseOrientation`).
+
 - `useCapture`, `useDeviceOrientation` — internal hooks `<Camera>`
   composes; expose these only after we have a story for what their
   separate-from-`<Camera>` use-case looks like.
@@ -206,5 +311,9 @@ Native module names also changed:
 - iOS pod: `RetaiLensCaptureSDK` → `RNImageStitcher`
 - iOS xcframework: shipped as `opencv2.xcframework` (linked from `RNImageStitcher.podspec`)
 
-[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.3...v0.2.0
+[0.1.3]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/bhargavkanda/react-native-image-stitcher/releases/tag/v0.1.0

package/README.md

@@ -4,15 +4,6 @@
 One `<Camera>` component, both tap-to-photo and hold-to-pan modes, both
 AR-backed and IMU-fallback capture paths.
 
-> [!NOTE]
-> This package lives in the [RetaiLens monorepo](https://github.com/bhargav-kanda/RetaiLens)
-> under `retailens-capture-sdk/` during development.  At publication
-> (see [`2026-05-15-react-native-image-stitcher-publication.md`](https://github.com/bhargav-kanda/RetaiLens/blob/main/docs/site-content/design/2026-05-15-react-native-image-stitcher-publication.md))
-> the public subset is `git subtree split` extracted to a standalone
-> repo at `github.com/bhargavkanda/react-native-image-stitcher` and
-> published to npm.  This README describes the **public lib** as it
-> will look post-extraction.
-
 ## What it does
 
 | Feature | Behaviour |

package/android/src/main/cpp/keyframe_gate_jni.cpp

@@ -2,7 +2,7 @@
 //
 // keyframe_gate_jni.cpp — JNI bindings exposing the shared C++
 // retailens::KeyframeGate (in ../../../../cpp/) to the Kotlin side
-// (com.retailens.capturesdk.KeyframeGate).
+// (io.imagestitcher.rn.KeyframeGate).
 //
 // Architecture parity with iOS:
 //   iOS uses an Obj-C++ bridge (KeyframeGateBridge.mm) to wrap the

package/android/src/main/java/io/imagestitcher/rn/BatchStitcher.kt

@@ -50,7 +50,7 @@ class BatchStitcher(reactContext: ReactApplicationContext)
      * JNI bridge to our custom-built OpenCV stitcher.  Mirrors iOS'
      * OpenCVStitcher.stitchFramePaths so the batch-keyframe flow has
      * parity across platforms.  Implementation:
-     *   retailens-capture-sdk/android/src/main/cpp/image_stitcher_jni.cpp
+     *   react-native-image-stitcher/android/src/main/cpp/image_stitcher_jni.cpp
      *
      * @param framePaths  input JPEG paths in capture order (≥2 required)
      * @param outputPath  destination JPEG path

package/android/src/main/java/io/imagestitcher/rn/IncrementalStitcher.kt

@@ -193,7 +193,7 @@ class IncrementalStitcher(
     /// (handleBatchKeyframeFrame above) with the same pose-driven
     /// 40%-new-content algorithm iOS has used since the V16 ship.
     /// Both platforms call into retailens::KeyframeGate (in
-    /// retailens-capture-sdk/cpp/keyframe_gate.cpp) — see that file
+    /// react-native-image-stitcher/cpp/keyframe_gate.cpp) — see that file
     /// for the algorithm.
     ///
     /// Lifetime: owned for the life of the module.  Closed in
@@ -1159,7 +1159,7 @@ class IncrementalStitcher(
     // iOS exposes these on the IncrementalStitcherBridge (NOT on the
     // ARSession module) so the JS code calls
     //   getIncrementalNativeModule().getARPlaneStatus()
-    // (see retailens-capture-sdk/src/stitching/incremental.ts:535).
+    // (see react-native-image-stitcher/src/stitching/incremental.ts:535).
     // Both methods delegate to the AR session singleton — same pattern
     // as iOS' IncrementalStitcherBridge.swift, where the bridge holds
     // the RN @objc surface and the singleton holds the AR algorithm.

package/android/src/main/java/io/imagestitcher/rn/KeyframeGate.kt

@@ -3,7 +3,7 @@ package io.imagestitcher.rn
 
 /**
  * Kotlin facade over the shared C++ KeyframeGate (in
- * retailens-capture-sdk/cpp/keyframe_gate.{hpp,cpp}).
+ * react-native-image-stitcher/cpp/keyframe_gate.{hpp,cpp}).
  *
  * Architecture parity with iOS:
  *   iOS uses an Obj-C++ bridge (KeyframeGateBridge.mm) to wrap the

package/dist/camera/Camera.js

@@ -375,7 +375,11 @@ function Camera(props) {
         });
         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 = (0, useIMUTranslationGate_1.useIMUTranslationGate)({
         enabled: isNonAR
             && statusPhase === 'recording'

package/dist/camera/useDeviceOrientation.d.ts

@@ -11,37 +11,40 @@
  * 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.)
  */
 export type DeviceOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
 export declare function useDeviceOrientation(): DeviceOrientation;

package/dist/camera/useDeviceOrientation.js

@@ -13,118 +13,105 @@
  * 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.)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useDeviceOrientation = useDeviceOrientation;
 const react_1 = require("react");
-const expo_sensors_1 = require("expo-sensors");
-/// 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;
+const react_native_1 = require("react-native");
+const react_native_sensors_1 = require("react-native-sensors");
+/// 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, y) {
-    // 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, y, threshold) {
+    // 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)
+        if (y < -threshold)
             return 'portrait';
-        if (y > DOMINANT_AXIS_THRESHOLD)
+        if (y > threshold)
             return 'portrait-upside-down';
     }
     else {
-        if (x < -DOMINANT_AXIS_THRESHOLD)
+        if (x < -threshold)
             return 'landscape-left';
-        if (x > DOMINANT_AXIS_THRESHOLD)
+        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;
 }
 function useDeviceOrientation() {
     const [orientation, setOrientation] = (0, react_1.useState)('portrait');
     (0, react_1.useEffect)(() => {
-        expo_sensors_1.DeviceMotion.setUpdateInterval(SAMPLE_INTERVAL_MS);
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.accelerometer, SAMPLE_INTERVAL_MS);
+        const isAndroid = react_native_1.Platform.OS === 'android';
+        const threshold = isAndroid
+            ? DOMINANT_AXIS_THRESHOLD_ANDROID
+            : DOMINANT_AXIS_THRESHOLD_IOS;
         let last = 'portrait';
-        const sub = expo_sensors_1.DeviceMotion.addListener((m) => {
-            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 = react_native_sensors_1.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/dist/index.js

@@ -42,6 +42,9 @@ Object.defineProperty(exports, "ARTrackingState", { enumerable: true, get: funct
 // ─────────────────────────────────────────────────────────────────────
 // 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).
 var useIMUTranslationGate_1 = require("./sensors/useIMUTranslationGate");
 Object.defineProperty(exports, "useIMUTranslationGate", { enumerable: true, get: function () { return useIMUTranslationGate_1.useIMUTranslationGate; } });
 // ═════════════════════════════════════════════════════════════════════

package/dist/sensors/useIMUTranslationGate.d.ts

@@ -1,70 +1,42 @@
 export interface UseIMUTranslationGateOptions {
     /**
-     * Whether the gate is engaged.  Pass `false` to skip the subscription
-     * entirely — useful when the host is in AR mode (where the gate
-     * gets pose-derived translation natively).  Hot-toggleable;
-     * subscribing/unsubscribing is cheap.
+     * Whether the gate is engaged.  Pass `false` to skip the
+     * subscription entirely — useful when the host is in AR mode
+     * (where the gate gets pose-derived translation natively).
+     * Hot-toggleable; subscribing/unsubscribing is cheap.
      */
     enabled: boolean;
     /**
      * Translation budget in METRES along the device-X (pan) axis.
-     * When the integrated displacement magnitude exceeds this since
-     * the last accept, the hook fires `onBudgetExceeded`.  Default
-     * 0.40 m / 40 cm (80 % of the 50 cm default
-     * `flowMaxTranslationCm`).  Caller typically passes
-     * `panoramaSettings.flowMaxTranslationCm * 0.8 / 100`.
+     * Default 0.40 m / 40 cm.  Callers in `<Camera>` typically pass
+     * `panoramaSettings.flowMaxTranslationCm / 100.0` (default 8 cm).
      */
     budgetMeters?: number;
     /**
-     * Update interval in MILLISECONDS for the DeviceMotion sensor.
-     * Default 20 ms ≈ 50 Hz.  Lower (faster sampling) = more accurate
-     * integration; higher = lower CPU + battery.  Matches the previous
-     * raw-accel cadence so reset/integrate behaviour stays comparable.
+     * Update interval in MILLISECONDS for the accelerometer.
+     * Default 20 ms ≈ 50 Hz.  Lower = more accurate integration;
+     * higher = lower CPU + battery.
      */
     sampleIntervalMs?: number;
     /**
      * Fired exactly once per "budget crossing" — i.e., when the
      * running translation along device-X crosses `budgetMeters` from
      * below.  The host is responsible for both (a) calling
-     * `IncrementalStitcher.markNextFrameAsLastKeyframe()` and
-     * (b) invoking the returned `resetAnchor()` once the next
-     * keyframe actually accepts, so the integrator restarts from zero.
+     * `IncrementalStitcher.markNextFrameAsLastKeyframe()` to force-
+     * accept the next frame, and (b) invoking the returned
+     * `resetAnchor()` once that next keyframe actually accepts, so
+     * the integrator restarts from zero.
      */
     onBudgetExceeded: () => void;
-    /**
-     * 2026-05-18 (Issue #4 investigation) — when true, log every Nth
-     * accelerometer sample (default N=20 ≈ 400 ms at 50 Hz) showing
-     * the current `acceleration.x`, accumulated `posX`, and time
-     * since anchor reset.  Helps diagnose drift behaviour vs real
-     * translation magnitude in field testing.  Defaults to false —
-     * production captures stay quiet.
-     */
-    debug?: boolean;
 }
 export interface UseIMUTranslationGateReturn {
     /**
-     * Reset the running translation to zero.  Call this at recording
-     * start AND after each confirmed keyframe accept — the typical
-     * wiring is to subscribe to `IncrementalStateUpdate` and
-     * call `resetAnchor()` from inside the listener AND from the host's
-     * `handleHoldStart`.
+     * Reset the position + velocity integrators to zero AND clear the
+     * "already fired" latch so `onBudgetExceeded` can fire again.
+     * The gravity IIR estimate is intentionally preserved — it
+     * benefits from continuous history across anchors.
      */
     resetAnchor: () => void;
-    /**
-     * Read the current running displacement along device-X in METRES.
-     * Returns the absolute value (sign is uninteresting — either left
-     * or right counts the same toward the budget).
-     * Useful for the on-screen debug HUD ("translation since last
-     * accept: 0.07 m").  Not exposed via state — host polls if needed.
-     */
-    getCurrentTranslationM: () => number;
 }
-/**
- * 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).
- */
-export declare function useIMUTranslationGate(options: UseIMUTranslationGateOptions): UseIMUTranslationGateReturn;
+export declare function useIMUTranslationGate({ enabled, budgetMeters, sampleIntervalMs, onBudgetExceeded, }: UseIMUTranslationGateOptions): UseIMUTranslationGateReturn;
 //# sourceMappingURL=useIMUTranslationGate.d.ts.map