react-native-nitro-compass 1.1.0 → 1.2.1

package/src/hook.ts

@@ -1,7 +1,8 @@
-import { useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import type {
   AccuracyQuality,
   CompassSample,
+  PermissionStatus,
   SensorDiagnostics,
 } from './specs/NitroCompass.nitro'
 import { NitroCompass } from './native'
@@ -60,6 +61,44 @@ export interface UseCompassResult {
   hasCompass: boolean
   /** Which sensor backs the readings on this device. */
   diagnostics: SensorDiagnostics | undefined
+  /**
+   * Latest platform permission status. Always `'granted'` on Android.
+   * On iOS may transition from `'unknown'` → `'granted'`/`'denied'`
+   * after `requestPermission()` resolves.
+   */
+  permission: PermissionStatus
+  /**
+   * Synchronous read of the most recent emitted sample (with declination
+   * already applied), or `undefined` if not started yet or no sample
+   * has arrived. Useful inside event handlers without re-rendering.
+   */
+  getCurrentHeading: () => CompassSample | undefined
+  /**
+   * Force a best-effort sensor recalibration. On Android this re-registers
+   * the sensor listeners (often nudges the magnetometer driver to
+   * re-evaluate calibration); on iOS it dismisses the heading-calibration
+   * overlay and stop/restarts heading updates.
+   */
+  recalibrate: () => void
+  /**
+   * Set the user's geographic location for a tighter interference gate.
+   * Android uses the WMM2025 model bundled in `GeomagneticField` to
+   * derive the expected field strength at the location; iOS is a no-op
+   * because `CLLocationManager` already uses GPS-derived location
+   * internally for all field-related reasoning. Pass `NaN` or
+   * out-of-range values to revert to the generic 20–70 µT band.
+   */
+  setLocation: (latitude: number, longitude: number) => void
+  /**
+   * Request the platform permission required to deliver headings.
+   * Android resolves immediately with `'granted'`. On iOS this prompts
+   * the system "Allow location" dialog if the status is `'unknown'`,
+   * resolving once the user makes a choice; subsequent calls resolve
+   * immediately with the cached status (iOS does not re-prompt). The
+   * hook's `permission` field updates automatically when the promise
+   * resolves.
+   */
+  requestPermission: () => Promise<PermissionStatus>
 }
 
 /**
@@ -84,14 +123,39 @@ export function useCompass(
   const [quality, setQuality] = useState<AccuracyQuality | null>(null)
   const [interfering, setInterfering] = useState(false)
 
-  const [hasCompass] = useState(() => NitroCompass.hasCompass())
-  const [diagnostics] = useState(() => NitroCompass.getDiagnostics())
+  // Wrap in try/catch so a missing/misconfigured native module doesn't
+  // throw during render — return safe defaults and let the host UI
+  // surface "no compass". Without this, the throw bubbles up and
+  // becomes a render error that blanks the screen.
+  const [hasCompass] = useState(() => {
+    try {
+      return NitroCompass.hasCompass()
+    } catch {
+      return false
+    }
+  })
+  const [diagnostics] = useState(() => {
+    try {
+      return NitroCompass.getDiagnostics()
+    } catch {
+      return undefined
+    }
+  })
+  const [permission, setPermission] = useState<PermissionStatus>(() => {
+    try {
+      return NitroCompass.getPermissionStatus()
+    } catch {
+      return 'unknown'
+    }
+  })
 
-  // Tracked via ref so the heading-subscription effect can re-apply
-  // the user's filter after a stop/start cycle without restarting on
-  // every filterDegrees change.
+  // Tracked via refs so the heading-subscription effect can re-apply
+  // the user's filter and smoothing after a stop/start cycle without
+  // restarting on every option change.
   const filterRef = useRef(filterDegrees)
   filterRef.current = filterDegrees
+  const smoothingRef = useRef(smoothingAlpha)
+  smoothingRef.current = smoothingAlpha
 
   useEffect(() => {
     NitroCompass.setFilter(filterDegrees)
@@ -120,14 +184,84 @@ export function useCompass(
   }, [hasCompass])
 
   useEffect(() => {
-    if (!hasCompass || !enabled) return
-    const off = addHeadingListener(setReading)
-    // Multiplex starts the sensor with a default filter; re-apply the
-    // current option after subscribing.
-    NitroCompass.setFilter(filterRef.current)
+    if (!hasCompass || !enabled) {
+      // When the user disables the hook, clear stale UI state.
+      // Without this, `reading` / `interfering` keep their last value
+      // forever, so the consumer's UI can't tell "subscription is off"
+      // from "compass is currently quiet".
+      setReading(null)
+      setInterfering(false)
+      return
+    }
+    let off: (() => void) | undefined
+    try {
+      off = addHeadingListener(setReading)
+      // Multiplex starts the sensor with a default filter; re-apply
+      // the current options after subscribing. recalibrate() can also
+      // reset native smoothing state, so we pin our chosen alpha back
+      // here as well.
+      NitroCompass.setFilter(filterRef.current)
+      NitroCompass.setSmoothing(smoothingRef.current)
+    } catch (e) {
+      // start() throws on iOS when location authorization is denied.
+      // Swallow it here so the hook tree doesn't unmount; consumers
+      // should call NitroCompass.requestPermission() explicitly before
+      // setting enabled=true if they want to recover.
+      // eslint-disable-next-line no-console
+      console.warn('[NitroCompass] failed to start heading subscription:', e)
+    }
     return off
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [hasCompass, enabled])
 
-  return { reading, quality, interfering, hasCompass, diagnostics }
+  // Stable callbacks so consumers' useEffect deps don't churn on every
+  // render. All four are thin wrappers around NitroCompass; the hook's
+  // own state isn't reactive to recalibrate/setLocation since neither
+  // changes any field returned here.
+  const getCurrentHeading = useCallback(() => {
+    try {
+      return NitroCompass.getCurrentHeading()
+    } catch {
+      return undefined
+    }
+  }, [])
+
+  const recalibrate = useCallback(() => {
+    try {
+      NitroCompass.recalibrate()
+    } catch {
+      // Native missing — nothing to do.
+    }
+  }, [])
+
+  const setLocation = useCallback((latitude: number, longitude: number) => {
+    try {
+      NitroCompass.setLocation(latitude, longitude)
+    } catch {
+      // Native missing — silently ignored.
+    }
+  }, [])
+
+  const requestPermission = useCallback(async (): Promise<PermissionStatus> => {
+    try {
+      const status = await NitroCompass.requestPermission()
+      setPermission(status)
+      return status
+    } catch {
+      return 'denied'
+    }
+  }, [])
+
+  return {
+    reading,
+    quality,
+    interfering,
+    hasCompass,
+    diagnostics,
+    permission,
+    getCurrentHeading,
+    recalibrate,
+    setLocation,
+    requestPermission,
+  }
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 import type {
   AccuracyQuality,
   CompassSample,
+  DebugInfo,
   NitroCompass as NitroCompassSpec,
   PermissionStatus,
   SensorDiagnostics,
@@ -12,6 +13,7 @@ export { NitroCompass } from './native'
 export type {
   AccuracyQuality,
   CompassSample,
+  DebugInfo,
   PermissionStatus,
   SensorDiagnostics,
   SensorKind,

package/src/multiplex.ts

@@ -82,6 +82,13 @@ export function addHeadingListener(cb: HeadingListener): () => void {
   }
 }
 
+// Module-level no-op kept stable so we can swap it back into the native
+// callback slot when the last listener leaves — releasing references
+// to old dispatcher closures, which matters when the JS module is
+// re-evaluated (Metro Fast Refresh, jest module reset).
+const NOOP_CALIBRATION = (_: AccuracyQuality) => {}
+const NOOP_INTERFERENCE = (_: boolean) => {}
+
 /**
  * Subscribe to calibration-bucket transitions. Only fires while a
  * heading subscription is active. Returns the unsubscribe function.
@@ -95,7 +102,17 @@ export function addCalibrationListener(
   }
   calibrationListeners.add(cb)
   return () => {
-    calibrationListeners.delete(cb)
+    if (!calibrationListeners.delete(cb)) return
+    if (calibrationListeners.size === 0) {
+      // Detach our dispatcher from the native side. Without this, a
+      // module reload (Metro Fast Refresh, jest resetModules) leaves
+      // the old dispatcher pinned in native memory while a new module
+      // load installs a *second* dispatcher pointing at a fresh
+      // listener Set — splitting events between the two and silently
+      // dropping the now-orphaned listeners.
+      NitroCompass.setOnCalibrationNeeded(NOOP_CALIBRATION)
+      calibrationRegistered = false
+    }
   }
 }
 
@@ -112,6 +129,10 @@ export function addInterferenceListener(
   }
   interferenceListeners.add(cb)
   return () => {
-    interferenceListeners.delete(cb)
+    if (!interferenceListeners.delete(cb)) return
+    if (interferenceListeners.size === 0) {
+      NitroCompass.setOnInterferenceDetected(NOOP_INTERFERENCE)
+      interferenceRegistered = false
+    }
   }
 }

package/src/specs/NitroCompass.nitro.ts

@@ -2,7 +2,7 @@ import type { HybridObject } from 'react-native-nitro-modules'
 
 /**
  * One compass heading sample, delivered to the JS callback registered with
- * `start()`. Both fields are in degrees.
+ * `start()`. Angular fields are in degrees; field strength is in microtesla.
  *
  * - `heading`: heading clockwise from north, in `[0, 360)`. Magnetic by
  *   default; if you call `setDeclination(deg)` the offset is applied
@@ -10,48 +10,131 @@ import type { HybridObject } from 'react-native-nitro-modules'
  *   `getCurrentHeading()`).
  * - `accuracy`: estimated heading uncertainty in degrees, or `-1` when the
  *   platform has not yet reported a usable accuracy. Smaller is better.
- *   On Android this is read from `event.values[4]` of the rotation-vector
- *   sensor when available, otherwise mapped from `SensorManager.SENSOR_STATUS_*`.
- *   On iOS this is `CLHeading.headingAccuracy`.
+ *   On Android, mapped from the magnetometer's `SENSOR_STATUS_*` accuracy
+ *   bucket (the figure-8 calibration signal). On iOS this is
+ *   `CLHeading.headingAccuracy`.
+ * - `fieldStrengthMicroTesla`: magnitude of the local magnetic field in
+ *   microteslas (µT), or `-1` when no reading is available yet. Earth's
+ *   field is normally 25–65 µT; values well outside this band signal
+ *   external interference (laptops, monitors, magnets, metal). Useful
+ *   for rendering a "strength" meter à la consumer compass apps.
  */
 export interface CompassSample {
   heading: number
   accuracy: number
+  fieldStrengthMicroTesla: number
 }
 
 /**
- * Coarse calibration bucket reported via `setOnCalibrationNeeded`. Buckets
- * are derived from numeric heading accuracy on both platforms (same
- * thresholds), so values agree across iOS and Android:
+ * Coarse calibration bucket reported via `setOnCalibrationNeeded`. The
+ * bucket is derived from a numeric heading-accuracy estimate on both
+ * platforms, but the thresholds differ because the underlying scales
+ * disagree:
  *
- *   `<5°` → `high`, `<15°` → `medium`, `<30°` → `low`, otherwise `unreliable`.
+ * - **Android** — direct mapping from `SensorManager.SENSOR_STATUS_*`:
+ *   `HIGH` → `high`, `MEDIUM` → `medium`, `LOW` → `low`,
+ *   `UNRELIABLE`/`NO_CONTACT` → `unreliable`. The numeric `accuracy`
+ *   field on `CompassSample` is a synthetic upper bound (`<5°`,
+ *   `<15°`, `<30°`, `-1`).
+ * - **iOS** — bucketed from `CLHeading.headingAccuracy` (degrees) with
+ *   relaxed thresholds because Apple's stack rarely reports under 5°
+ *   even on a perfectly-calibrated compass:
+ *   `<20°` → `high`, `<35°` → `medium`, `<55°` → `low`, otherwise
+ *   `unreliable`. `unreliable` is also reported when iOS asks to
+ *   display its built-in calibration UI (we suppress the system UI so
+ *   you can render your own banner).
  *
- * On iOS `unreliable` is also reported when the system asks to display
- * its built-in calibration UI (we suppress it).
+ * The buckets are intended for UX ("show calibrate prompt") — exact
+ * cross-platform parity isn't possible because the platforms emit
+ * different underlying signals.
  */
 export type AccuracyQuality = 'high' | 'medium' | 'low' | 'unreliable'
 
 /**
  * Identifies which underlying sensor / framework is producing headings.
  *
- * - `rotationVector` — Android `Sensor.TYPE_ROTATION_VECTOR` (gyro + accel
- *   + magnetometer fused). Best quality.
- * - `geomagneticRotationVector` — Android
- *   `Sensor.TYPE_GEOMAGNETIC_ROTATION_VECTOR` (accel + magnetometer only).
- *   Used as fallback on gyroless / budget devices; lower update rate and
- *   more susceptible to magnetic interference.
+ * - `magnetometer` — Android raw `TYPE_MAGNETIC_FIELD` + `TYPE_ACCELEROMETER`
+ *   computed via `SensorManager.getRotationMatrix()` + `getOrientation()`.
+ *   Stateless: snaps back instantly when external interference (magnets,
+ *   electronics) is removed, instead of waiting for OS-level fusion to
+ *   re-converge.
  * - `coreLocation` — iOS `CLLocationManager` heading. Apple's stack
  *   handles fusion natively.
+ * - `rotationVector` / `geomagneticRotationVector` — legacy values kept
+ *   in the union for source compatibility; no longer returned by current
+ *   builds.
  */
 export type SensorKind =
+  | 'magnetometer'
+  | 'coreLocation'
   | 'rotationVector'
   | 'geomagneticRotationVector'
-  | 'coreLocation'
 
 export interface SensorDiagnostics {
   sensor: SensorKind
 }
 
+/**
+ * Live introspection of the native compass pipeline. Use for
+ * diagnosing user-reported issues (heading wrong, banner stuck,
+ * compass frozen) — none of these fields are needed for normal
+ * operation.
+ *
+ * Numeric fields use `-1` (or `NaN` for `fusedYawDeg`) as a
+ * "not-applicable / not-yet-available" sentinel; consumers should
+ * treat those as missing rather than literal values. Most fields
+ * are Android-only — iOS uses `CLLocationManager` and doesn't expose
+ * the underlying state, so the iOS implementation reports a minimal
+ * subset (`lastFieldMicroTesla`, `interferenceActive`).
+ */
+export interface DebugInfo {
+  /**
+   * Whether the library currently considers external interference to
+   * be active. Driven by field-magnitude band checks AND (Android,
+   * uncalibrated mag only) recent OS hard-iron-bias jumps.
+   */
+  interferenceActive: boolean
+  /**
+   * Milliseconds since the most recent OS hard-iron bias jump on
+   * Android's uncalibrated magnetometer. `-1` if never seen.
+   * iOS / fallback path: always `-1`.
+   */
+  msSinceLastBiasJump: number
+  /**
+   * The expected magnetic field magnitude (µT) at the user's
+   * location, derived from `setLocation()`. Used to tighten the
+   * interference band. `-1` if `setLocation()` hasn't been called
+   * with valid coordinates.
+   */
+  expectedFieldMicroTesla: number
+  /**
+   * Most recent measured field magnitude (µT) — same value surfaced
+   * on `CompassSample.fieldStrengthMicroTesla`. `-1` if no reading.
+   */
+  lastFieldMicroTesla: number
+  /**
+   * Current value of the gyro-corrected fused yaw (deg, [0, 360)).
+   * `NaN` before any sample has been processed, or on iOS where
+   * gyro fusion is handled inside CLLocationManager.
+   */
+  fusedYawDeg: number
+  /**
+   * Latest yaw rate (deg/s) derived from game-rotation-vector
+   * deltas. Used to drive the adaptive input low-pass filter.
+   * `0` if game-RV is unavailable / hasn't fired yet.
+   */
+  lastYawRateDegPerS: number
+  /** Whether `TYPE_GAME_ROTATION_VECTOR` is currently producing events. Always `false` on iOS. */
+  hasGameRotationVector: boolean
+  /**
+   * Whether Android is sourcing magnetometer data from
+   * `TYPE_MAGNETIC_FIELD_UNCALIBRATED` (preferred — bias-jump
+   * detection works) vs. the `TYPE_MAGNETIC_FIELD` fallback. Always
+   * `false` on iOS.
+   */
+  usingUncalibratedMag: boolean
+}
+
 /**
  * Platform permission state required to deliver headings.
  *
@@ -129,9 +212,17 @@ export interface NitroCompass extends HybridObject<{ ios: 'swift'; android: 'kot
    */
   getDiagnostics(): SensorDiagnostics | undefined
 
+  /**
+   * Snapshot of the internal compass pipeline. Only intended for
+   * diagnosing user-reported issues — see {@link DebugInfo} for
+   * field-by-field semantics. Cheap to call (no allocations beyond
+   * the returned object); poll at any rate the host UI prefers.
+   */
+  getDebugInfo(): DebugInfo
+
   /**
    * Whether the device has the hardware required for a compass reading.
-   * Android: a rotation-vector sensor (fused or geomagnetic) is present.
+   * Android: both a magnetometer and an accelerometer are present.
    * iOS: `CLLocationManager.headingAvailable()`.
    */
   hasCompass(): boolean
@@ -151,6 +242,25 @@ export interface NitroCompass extends HybridObject<{ ios: 'swift'; android: 'kot
    */
   setDeclination(degrees: number): void
 
+  /**
+   * Set the user's geographic location for a tighter interference
+   * gate. With a valid location, the library replaces the generic
+   * 20–70 µT "Earth field band" with `expectedField ± 15 µT`, where
+   * `expectedField` comes from the WMM2025 model shipped on Android
+   * (`GeomagneticField`). This catches weak interference the generic
+   * band misses — especially at high/low latitudes where Earth's
+   * field is naturally near or above 60 µT.
+   *
+   * Pass `NaN` for either coordinate, or values outside the valid
+   * range (`|lat| > 90`, `|lon| > 180`), to revert to the generic
+   * band. Survives across `start`/`stop`.
+   *
+   * **No-op on iOS.** `CLLocationManager` uses GPS-derived location
+   * internally for all field-related reasoning; layering our own
+   * lookup on top would be redundant.
+   */
+  setLocation(latitude: number, longitude: number): void
+
   /**
    * Register a callback fired when the calibration bucket transitions.
    * Replaces any previously registered callback. Pass a no-op to mute.
@@ -191,6 +301,25 @@ export interface NitroCompass extends HybridObject<{ ios: 'swift'; android: 'kot
    */
   setPauseOnBackground(enabled: boolean): void
 
+  /**
+   * Force a best-effort sensor recalibration. Resets internal smoothing
+   * and quality-bucket state, then re-registers the underlying sensor
+   * listeners. On many Android OEMs the re-registration nudges the
+   * magnetometer driver to re-evaluate soft/hard-iron calibration, which
+   * unsticks an `UNRELIABLE` bucket that's lingering after a strong
+   * magnetic excursion (e.g. another phone placed on top, then removed).
+   *
+   * On iOS this dismisses the system heading-calibration overlay and
+   * stops/restarts heading updates. Apple's stack handles the
+   * underlying calibration internally.
+   *
+   * Idempotent — safe to call when not started, in which case it's a
+   * no-op. Calibration recovery still requires the user to move the
+   * device through varying orientations; this method just clears the
+   * library's cached state so progress is reflected promptly.
+   */
+  recalibrate(): void
+
   /**
    * Read the current platform permission state synchronously.
    * On Android this is always `'granted'` (sensors require no permission);