react-native-nitro-compass 1.1.0 → 1.2.1

package/README.md

@@ -1,25 +1,59 @@
 # react-native-nitro-compass
 
-Fast, accurate compass heading for React Native, powered by [Nitro Modules](https://github.com/mrousavy/nitro).
+[![npm version](https://img.shields.io/npm/v/react-native-nitro-compass.svg)](https://www.npmjs.com/package/react-native-nitro-compass)
+[![license](https://img.shields.io/npm/l/react-native-nitro-compass.svg)](./LICENSE)
+[![react-native](https://img.shields.io/badge/react--native-0.76%2B-61dafb)](https://reactnative.dev)
 
-- **Android**: `Sensor.TYPE_ROTATION_VECTOR` (gyro + accel + magnetometer sensor fusion), with `TYPE_GEOMAGNETIC_ROTATION_VECTOR` fallback for gyroless devices. Sensor delivery on a dedicated `HandlerThread` — never blocks the UI thread. Heading accuracy taken from `event.values[4]` of the rotation vector.
-- **iOS**: `CLLocationManager` heading via `CLHeading.magneticHeading`. Apple's stack already handles sensor fusion natively.
-- **JS API**: type-safe Nitro callbacks — no `NativeEventEmitter`, no string event names.
+Fast, accurate compass heading for React Native, powered by [Nitro Modules](https://github.com/mrousavy/nitro). Survives magnetic interference, supports true-north via geomagnetic location lookup, and drives a 60 fps Reanimated dial without thrashing React.
 
-## Why
-
-Most React Native compass libraries use the legacy `accelerometer + magnetometer + getRotationMatrix` Android approach, which is laggy, noisy, and requires a figure-8 calibration on every session. This library uses Android's modern fused rotation-vector sensor (recommended by Google since 2013), giving you stable headings without calibration on virtually any modern device.
-
-## Requirements
+```ts
+import { useCompass } from 'react-native-nitro-compass'
 
-- React Native 0.76.0 or higher
-- Node 18.0.0 or higher
-- `react-native-nitro-modules` peer dependency
+function CompassScreen() {
+  const { reading, quality, interfering } = useCompass()
+  return <Text>{reading?.heading.toFixed(0)}°</Text>
+}
+```
 
-## Install
+## Features
+
+- **Stateless interference recovery.** Heading snaps back the instant a magnet or laptop is removed — no waiting for the OS Kalman filter to unstick.
+- **Gyro complementary fusion.** `TYPE_GAME_ROTATION_VECTOR` carries heading smoothly through rapid turns and transient magnet events; mag samples pull it back to absolute via a ~1 s blend.
+- **Bias-jump interference detection.** Catches weak magnet events the field-magnitude check alone misses — e.g. another phone placed on top, where the corrected magnitude stays in-band but the OS still revises its hard-iron bias.
+- **Location-aware.** `setLocation(lat, lon)` tightens the Android interference band using the bundled WMM2025 model.
+- **Type-safe Nitro callbacks.** No `NativeEventEmitter`, no string event names.
+- **Ergonomic React hook.** `useCompass()` bundles subscription lifecycle, calibration/interference observation, and live-tuneable knobs into one call. Multiple mounts safely share a single native subscription.
+- **Reanimated-friendly.** Direct `addHeadingListener()` for 60 fps animations that run entirely on the UI thread.
+- **Live diagnostics.** `getDebugInfo()` surfaces all internal state for self-diagnosing user reports.
+- **Permission-aware.** Built-in `requestPermission()` / `permission` state — no extra dependency for the iOS authorization flow.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Permissions](#permissions)
+- [Quick start](#quick-start)
+- [`useCompass()` hook](#usecompass-hook)
+- [Listener helpers](#listener-helpers)
+- [Imperative API](#imperative-api)
+- [Recipes](#recipes)
+  - [True-north heading from location](#true-north-heading-from-location)
+  - [Smooth dial animation (Reanimated)](#smooth-dial-animation-reanimated)
+  - [Location-tightened interference](#location-tightened-interference)
+  - [Calibration UI](#calibration-ui)
+  - [Custom diagnostics panel](#custom-diagnostics-panel)
+- [Types](#types)
+- [Architecture](#architecture)
+- [Troubleshooting](#troubleshooting)
+- [Example app](#example-app)
+- [Acknowledgments](#acknowledgments)
+- [License](#license)
+
+## Installation
 
 ```sh
 npm install react-native-nitro-compass react-native-nitro-modules
+# or
+yarn add react-native-nitro-compass react-native-nitro-modules
 ```
 
 iOS:
@@ -28,187 +62,219 @@ iOS:
 cd ios && pod install
 ```
 
-## Usage
+**Requirements**: React Native ≥ 0.76, Node ≥ 18, [`react-native-nitro-modules`](https://github.com/mrousavy/nitro) installed as a peer dependency.
 
-```ts
-import { NitroCompass } from 'react-native-nitro-compass'
+## Permissions
 
-if (NitroCompass.hasCompass()) {
-  NitroCompass.start(1, ({ heading, accuracy }) => {
-    console.log(`heading: ${heading.toFixed(1)}°, accuracy: ±${accuracy}°`)
-  })
-}
+|                              | iOS                                                              | Android                                       |
+| ---                          | ---                                                              | ---                                           |
+| Compass heading              | `NSLocationWhenInUseUsageDescription` in `Info.plist`            | none — sensors are unrestricted               |
+| `setLocation()` (optional)   | reuses the same key — no extra permission                        | `ACCESS_COARSE_LOCATION` in your manifest     |
 
-// later…
-NitroCompass.stop()
+### iOS
+
+Add to `ios/<YourApp>/Info.plist`:
+
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>Used to read the device compass heading.</string>
 ```
 
-### API
+`CLLocationManager` only emits headings when location authorization is granted. The hook exposes `permission` and `requestPermission()` so you don't need a separate library to drive the prompt.
 
-```ts
-NitroCompass.start(filterDegrees: number, onHeading: (sample: CompassSample) => void): void
-NitroCompass.stop(): void
-NitroCompass.isStarted(): boolean
-NitroCompass.hasCompass(): boolean
-
-NitroCompass.setFilter(degrees: number): void
-NitroCompass.setSmoothing(alpha: number): void
-NitroCompass.getCurrentHeading(): CompassSample | undefined
-NitroCompass.getDiagnostics(): SensorDiagnostics | undefined
-NitroCompass.setDeclination(degrees: number): void
-NitroCompass.setOnCalibrationNeeded(onChange: (quality: AccuracyQuality) => void): void
-NitroCompass.setOnInterferenceDetected(onChange: (interferenceDetected: boolean) => void): void
-NitroCompass.setPauseOnBackground(enabled: boolean): void
+### Android
 
-interface CompassSample {
-  heading: number   // degrees, [0, 360); magnetic by default, true-north if setDeclination was called
-  accuracy: number  // degrees, smaller is better; -1 if unknown
-}
+The compass itself needs **no permission** — Android exposes the magnetometer and accelerometer to all apps. Only add `ACCESS_COARSE_LOCATION` if you plan to call `setLocation()` (or use the location recipe below):
 
-type AccuracyQuality = 'high' | 'medium' | 'low' | 'unreliable'
-type SensorKind = 'rotationVector' | 'geomagneticRotationVector' | 'coreLocation'
-interface SensorDiagnostics { sensor: SensorKind }
+```xml
+<!-- android/app/src/main/AndroidManifest.xml -->
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 ```
 
-- `filterDegrees` — minimum change between successive samples before the next one is delivered. Pass `0` for "every event"; typical UI values are `1`–`3`. Use `setFilter()` to change live without tearing down the subscription.
-- `setSmoothing(alpha)` — low-pass smoothing factor (EMA α) applied to heading samples on Android. Range `(0, 1]`, default `0.2` (~100 ms time constant at 50 Hz). `1.0` disables smoothing; smaller values smooth more (kills jitter, adds a touch of latency). **No-op on iOS** — `CLLocationManager` filters internally with Apple's own algorithm, so layering an EMA on top would only add latency. See [Smoothing](#smoothing) below.
-- `start()` is idempotent in the destructive sense — calling it while already started silently replaces the previous subscription with the new callback. `stop()` is idempotent and safe from inside the `onHeading` callback.
-- `getDiagnostics()` reports which sensor would produce headings on this device — useful for explaining quality differences (e.g. a phone falling back to `geomagneticRotationVector` will be more susceptible to magnetic interference than one using `rotationVector`). Safe to call before `start()`.
-- `accuracy` is a numeric uncertainty (degrees). On iOS it comes from `CLHeading.headingAccuracy` directly. On Android it comes from `event.values[4]` of the rotation-vector sensor; if the sensor stack does not publish that (rare), the module falls back to a coarse degree estimate from `SensorManager.SENSOR_STATUS_*` (`HIGH→5°`, `MEDIUM→15°`, `LOW→30°`).
-- `getCurrentHeading()` returns the most recently emitted sample (with declination already applied), or `undefined` if not started yet or no sample has arrived.
-
-### Calibration
+## Quick start
 
-`setOnCalibrationNeeded(cb)` registers a callback fired whenever the calibration bucket transitions. Each platform's bucket is derived from its **native** accuracy semantics, since the underlying values are not directly comparable:
+```tsx
+import { Text, View } from 'react-native'
+import { useCompass } from 'react-native-nitro-compass'
 
-- **iOS** uses `CLHeading.headingAccuracy` (degrees). Apple is conservative — even well-calibrated iPhones typically report `10–15°` and rarely below `5°` (per [Apple staff on the developer forums](https://developer.apple.com/forums/thread/79687)). Buckets: `<20°` → `'high'`, `<35°` → `'medium'`, `<55°` → `'low'`, otherwise `'unreliable'`. The system's "wave the device in a figure-8" prompt is suppressed and reported to your callback as `'unreliable'` — show your own UI when you receive that bucket.
-- **Android** uses `SensorManager.SENSOR_STATUS_*` from `onAccuracyChanged` directly (`HIGH` / `MEDIUM` / `LOW` / `UNRELIABLE`); when `event.values[4]` of the rotation vector publishes a per-sample degree estimate, that's used with thresholds `<5°` / `<15°` / `<30°`. **When magnetic interference is currently detected, the surfaced bucket is downgraded by one notch** (`HIGH→MEDIUM`, `MEDIUM→LOW`, `LOW→UNRELIABLE`) — Android's gyro+accel sensor fusion can keep the OS rotation-vector bucket high even while the magnetometer is being skewed, and surfacing `quality='high'` alongside `interfering=true` is contradictory UX.
+function Compass() {
+  const { reading, quality, interfering, hasCompass } = useCompass()
 
-Both platforms can plausibly emit `'high'` on a clean device — the threshold split just reflects each OS's reporting style.
+  if (!hasCompass) return <Text>No compass on this device.</Text>
+  if (!reading) return <Text>Acquiring heading…</Text>
 
-```ts
-NitroCompass.setOnCalibrationNeeded((q) => {
-  if (q === 'unreliable') showCalibrationToast()
-})
+  return (
+    <View>
+      <Text>{reading.heading.toFixed(0)}° (±{reading.accuracy.toFixed(0)}°)</Text>
+      {quality === 'unreliable' && <Text>Calibration needed</Text>}
+      {interfering && <Text>Magnetic interference detected</Text>}
+    </View>
+  )
+}
 ```
 
-### Magnetic interference
-
-`setOnInterferenceDetected(cb)` fires `true` when the raw magnetic field magnitude leaves the normal Earth band (~20–70 µT) and `false` when it returns. Typical sources are laptops, monitors, car engines, and large steel structures — these can skew heading by tens of degrees.
+That's the whole API for 90% of apps. Read on for true-north, smoother animation, and tunable behavior.
 
-Interference is surfaced two ways: (1) directly via this callback, and (2) on Android, the calibration bucket emitted by `setOnCalibrationNeeded` is downgraded by one notch while interference is detected (see the Calibration section above). On iOS, only the direct callback fires — `CLLocationManager`'s own accuracy reporting already responds to magnetometer disturbance, so a separate downgrade would double-count.
+## `useCompass()` hook
 
 ```ts
-NitroCompass.setOnInterferenceDetected((interfering) => {
-  if (interfering) showInterferenceWarning()
-  else hideInterferenceWarning()
-})
+function useCompass(options?: UseCompassOptions): UseCompassResult
 ```
 
-Android uses `Sensor.TYPE_MAGNETIC_FIELD` at ~5 Hz. iOS uses `CMDeviceMotion.magneticField` (calibrated, with the device's own hard-iron bias subtracted in real time) — note that no transitions are reported on iOS until CoreMotion's bias estimate converges, typically a second or two of normal device movement. Only triggered while `start()` is active; no debounce, so brief excursions still fire.
-
-### Magnetic vs true north
-
-Headings are **magnetic** by default. You can either apply declination in JS, or let the native side do it once via `setDeclination(deg)` so every emitted sample (and `getCurrentHeading()`) is true-north.
+Wraps the entire surface — subscription lifecycle, calibration/interference callbacks, live-tuneable knobs, permission flow — into one ergonomic call. Multiple `useCompass()` mounts safely share the same underlying native subscription.
 
-```ts
-import geomagnetism from 'geomagnetism'
+### Options
 
-const declination = geomagnetism.model().point([lat, lon]).decl
+| Option              | Type      | Default | Description                                                                                                              |
+| ---                 | ---       | ---     | ---                                                                                                                      |
+| `filterDegrees`     | `number`  | `1`     | Minimum change between successive samples in degrees. Pass `0` for "every event".                                        |
+| `smoothingAlpha`    | `number`  | `0.2`   | Low-pass smoothing factor (EMA α) on Android. `1.0` disables smoothing; smaller values smooth more. No-op on iOS.        |
+| `declination`       | `number`  | `0`     | Magnetic-to-true offset in signed degrees. When non-zero, every emitted sample is true-north. See [recipe](#true-north-heading-from-location). |
+| `pauseOnBackground` | `boolean` | `true`  | Pause the underlying sensor / location-manager subscription while the app is backgrounded.                               |
+| `enabled`           | `boolean` | `true`  | Toggle the heading subscription without unmounting. When `false`, `reading` stops updating but calibration/interference observation continues. |
 
-// Option A — JS-side
-const trueHeading = (heading + declination + 360) % 360
+`filterDegrees`, `smoothingAlpha`, `declination`, and `pauseOnBackground` map to global state on `NitroCompass` — if multiple hooks set them, last-write-wins.
 
-// Option B — native-side (subsequent samples are true-north)
-NitroCompass.setDeclination(declination)
-```
+### Result
 
-Pass `0` to revert to magnetic. Declination survives `stop()`/`start()` cycles.
+| Field                | Type                                          | Description                                                                                                              |
+| ---                  | ---                                           | ---                                                                                                                      |
+| `reading`            | `CompassSample \| null`                       | Latest emitted sample, or `null` until the first arrives.                                                                |
+| `quality`            | `AccuracyQuality \| null`                     | Coarse calibration bucket. Show your own calibration UI on `'unreliable'`.                                               |
+| `interfering`        | `boolean`                                     | `true` while external magnetic interference is detected.                                                                 |
+| `hasCompass`         | `boolean`                                     | Hardware availability — read once on first render.                                                                       |
+| `diagnostics`        | `SensorDiagnostics \| undefined`              | Which sensor backs the readings on this device.                                                                          |
+| `permission`         | `PermissionStatus`                            | Latest platform permission state. iOS may transition `'unknown'` → `'granted'`/`'denied'` after `requestPermission()`.   |
+| `getCurrentHeading`  | `() => CompassSample \| undefined`            | Synchronous read of the most recent sample. Stable identity.                                                             |
+| `recalibrate`        | `() => void`                                  | Force a best-effort sensor recalibration. Stable identity.                                                               |
+| `setLocation`        | `(lat: number, lon: number) => void`          | Tighten the Android interference gate via WMM2025. No-op on iOS. Stable identity.                                        |
+| `requestPermission`  | `() => Promise<PermissionStatus>`             | Prompt the platform permission dialog and update the hook's `permission` field. Stable identity.                         |
 
-### Smoothing
+The four function fields all have stable identities (via `useCallback`) so consumers' `useEffect` deps don't churn on every render.
 
-Android's raw `TYPE_ROTATION_VECTOR` output jitters by `±1–3°` even at rest, which produces a visibly twitchy compass dial. iOS's `CLLocationManager` filters internally; Android does not. The library applies a circular EMA low-pass filter on `(sin θ, cos θ)` (handles `359°→0°` wraparound cleanly) before delivering samples, with `α = 0.2` by default — the same value used in [phishman3579/android-compass](https://github.com/phishman3579/android-compass/blob/master/src/com/jwetherell/compass/common/LowPassFilter.java) and within the range used by [Trail Sense](https://github.com/kylecorry31/Trail-Sense)'s production compass code.
+## Listener helpers
 
-Tune live:
+For non-React code, three reference-counted listener primitives are exported. The first heading listener calls `start()` natively; the last `unsubscribe()` calls `stop()`.
 
 ```ts
-NitroCompass.setSmoothing(0.2)   // default — kills jitter, ~100 ms latency
-NitroCompass.setSmoothing(0.4)   // snappier, more visible jitter
-NitroCompass.setSmoothing(1.0)   // disabled — every sample passes through
+import {
+  addHeadingListener,
+  addCalibrationListener,
+  addInterferenceListener,
+} from 'react-native-nitro-compass'
+
+const off = addHeadingListener(({ heading, accuracy, fieldStrengthMicroTesla }) => {
+  // …
+})
+// later
+off()
 ```
 
-`setSmoothing` is a no-op on iOS — Apple's stack already filters heading internally, so layering an EMA on top would only add latency without removing noise.
+Mixing listener helpers with direct `NitroCompass.setOnCalibrationNeeded()` / `setOnInterferenceDetected()` will clobber the multiplex's internal callback slot — pick one path. `useCompass()` itself uses these helpers, so mixing the hook with `addHeadingListener` is fine.
 
-### Background pause
+## Imperative API
 
-By default the underlying sensor / location-manager subscription is silently paused while the app is backgrounded and resumed when it returns to the foreground; the JS callback and any declination set via `setDeclination` are preserved across the pause. To opt out (e.g. for a fitness tracker that needs heading while screen-off):
+For full control, drive the native HybridObject directly:
 
 ```ts
-NitroCompass.setPauseOnBackground(false)
+import { NitroCompass } from 'react-native-nitro-compass'
+
+if (NitroCompass.hasCompass()) {
+  NitroCompass.start(1, ({ heading }) => console.log(heading))
+}
+NitroCompass.stop()
 ```
 
-### `useCompass()` hook
+| Method                                                                       | Description                                                                                                              |
+| ---                                                                          | ---                                                                                                                      |
+| `start(filterDegrees, onHeading)`                                            | Begin emitting samples to `onHeading`. Idempotent — replaces any prior subscription.                                     |
+| `stop()`                                                                     | Stop the subscription. Safe to call when not started.                                                                    |
+| `isStarted()`                                                                | `true` between `start()` and `stop()`.                                                                                   |
+| `hasCompass()`                                                               | Hardware availability check.                                                                                             |
+| `setFilter(degrees)`                                                         | Update the deadband filter live without restarting.                                                                      |
+| `setSmoothing(alpha)`                                                        | Update the EMA smoothing factor (Android). Range `(0, 1]`. No-op on iOS.                                                 |
+| `setDeclination(degrees)`                                                    | Apply a magnetic-to-true offset to every emitted heading.                                                                |
+| `setLocation(latitude, longitude)`                                           | Tighten the Android interference gate using WMM2025. Pass `NaN` to revert. No-op on iOS.                                 |
+| `setPauseOnBackground(enabled)`                                              | Toggle automatic pause/resume on background.                                                                             |
+| `getCurrentHeading()`                                                        | Most recent sample, or `undefined`.                                                                                      |
+| `getDiagnostics()`                                                           | Which sensor backs headings on this device.                                                                              |
+| `getDebugInfo()`                                                             | Live snapshot of internal pipeline state — see [DebugInfo](#types).                                                      |
+| `setOnCalibrationNeeded(cb)`                                                 | Subscribe to calibration-bucket transitions.                                                                             |
+| `setOnInterferenceDetected(cb)`                                              | Subscribe to magnetic-interference transitions.                                                                          |
+| `recalibrate()`                                                              | Force a best-effort recalibration (re-register sensors on Android, dismiss heading-calibration overlay on iOS).          |
+| `getPermissionStatus()`                                                      | Synchronous read of the platform permission state.                                                                       |
+| `requestPermission()`                                                        | Promise — prompts iOS dialog if `notDetermined`, resolves with the resulting status.                                     |
+
+## Recipes
+
+### True-north heading from location
+
+Headings are **magnetic** by default. To convert to true-north you need the [magnetic declination](https://en.wikipedia.org/wiki/Magnetic_declination) at the user's location — it varies from ~0° on the agonic line to ±25° in some parts of the world. The library applies an offset for you when you call `setDeclination(deg)`; you compute that offset from a WMM model.
+
+Pair any geolocation library with [`geomagnetism`](https://github.com/manuelbieh/geomagnetism) (a static WMM2025 lookup, no native deps):
 
-For React consumers, the bundled hook wraps the entire surface — subscription lifecycle, calibration/interference callbacks, and the live-tuneable knobs — into one ergonomic call. Multiple `useCompass()` mounts safely share the same underlying native subscription via JS-side fan-out, so two screens can both consume heading without clobbering each other.
+```sh
+yarn add react-native-geolocation-service geomagnetism
+```
 
 ```tsx
+import { useEffect } from 'react'
+import { Platform, PermissionsAndroid } from 'react-native'
+import Geolocation from 'react-native-geolocation-service'
+import geomagnetism from 'geomagnetism'
 import { useCompass } from 'react-native-nitro-compass'
 
-function CompassView() {
-  const { reading, quality, interfering, hasCompass } = useCompass({
-    filterDegrees: 1,
-    smoothingAlpha: 0.2,
-    declination: 0,
-    pauseOnBackground: true,
-    enabled: true,
-  })
-
-  if (!hasCompass) return <Text>No compass on this device.</Text>
-  if (!reading) return <Text>Acquiring heading…</Text>
-
-  return (
-    <View>
-      <Text>{reading.heading.toFixed(0)}° (±{reading.accuracy.toFixed(0)}°)</Text>
-      {quality === 'unreliable' && <Text>Calibration needed</Text>}
-      {interfering && <Text>Magnetic interference</Text>}
-    </View>
-  )
+async function ensureLocationPermission(): Promise<boolean> {
+  if (Platform.OS === 'android') {
+    const result = await PermissionsAndroid.request(
+      PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION,
+    )
+    return result === PermissionsAndroid.RESULTS.GRANTED
+  }
+  return true
 }
-```
 
-```ts
-function useCompass(options?: UseCompassOptions): UseCompassResult
+function CompassScreen() {
+  const compass = useCompass()
+  const { setLocation } = compass
+
+  useEffect(() => {
+    let cancelled = false
+    void (async () => {
+      if (!(await ensureLocationPermission()) || cancelled) return
+
+      Geolocation.getCurrentPosition(
+        ({ coords }) => {
+          if (cancelled) return
+          // Tighten the interference band (Android-only).
+          setLocation(coords.latitude, coords.longitude)
+          // Apply true-north declination to every subsequent sample.
+          const decl = geomagnetism.model().point([coords.latitude, coords.longitude]).decl
+          NitroCompass.setDeclination(decl)
+        },
+        () => {/* fall back to magnetic heading + generic interference band */},
+        { enableHighAccuracy: false, timeout: 15_000, maximumAge: 60_000 },
+      )
+    })()
+    return () => { cancelled = true }
+  }, [setLocation])
+
+  return <Text>{compass.reading?.heading.toFixed(0)}° true</Text>
+}
 ```
 
-#### Options
+A few notes:
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `filterDegrees` | `number` | `1` | Minimum change between successive samples in degrees. Pass `0` for "every event". Updated live via `NitroCompass.setFilter()` whenever the prop changes. |
-| `smoothingAlpha` | `number` | `0.2` | Low-pass smoothing factor (EMA α) on Android. `1.0` disables smoothing; smaller values smooth more. No-op on iOS. See [Smoothing](#smoothing). |
-| `declination` | `number` | `0` | Magnetic-to-true offset in signed degrees. Pull from a model like [`geomagnetism`](https://github.com/kahirokunn/geomagnetism) keyed on the user's lat/lon. When non-zero, every emitted sample is true-north. |
-| `pauseOnBackground` | `boolean` | `true` | Pause the underlying sensor / location-manager subscription while the app is backgrounded and resume on foreground. |
-| `enabled` | `boolean` | `true` | Toggle the heading subscription without unmounting. When `false`, `reading` stops updating but calibration and interference observation continue (so you can still show warnings). |
-
-`filterDegrees`, `smoothingAlpha`, `declination`, and `pauseOnBackground` map to global state on `NitroCompass` — if multiple hooks set them, last-write-wins.
-
-#### Result
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `reading` | `CompassSample \| null` | Latest emitted sample (`{ heading, accuracy }`), or `null` until the first arrives. Heading is true-north when `declination` is set, magnetic otherwise. |
-| `quality` | `AccuracyQuality \| null` | Coarse calibration bucket — `'high'`, `'medium'`, `'low'`, or `'unreliable'`. `null` until the first transition. Show your own calibration UI on `'unreliable'`. |
-| `interfering` | `boolean` | `true` while the raw magnetic field magnitude is outside the normal Earth band (~20–70 µT) — laptops, monitors, car engines, steel structures. |
-| `hasCompass` | `boolean` | Hardware availability — read once on first render. Render a fallback when `false`. |
-| `diagnostics` | `SensorDiagnostics \| undefined` | Which sensor backs the readings on this device (`rotationVector`, `geomagneticRotationVector`, or `coreLocation`). Useful for explaining quality differences. |
-
-For non-React state managers, lower-level `addHeadingListener(cb): () => void`, `addCalibrationListener(cb): () => void`, and `addInterferenceListener(cb): () => void` are also exported. They are reference-counted: the first heading listener calls `start()`, the last unsubscribe calls `stop()`. Mixing these helpers with direct `NitroCompass.start()` / `setOnCalibrationNeeded()` / `setOnInterferenceDetected()` will clobber the multiplex's internal callback slot — pick one path.
+- **One-shot is enough.** Both declination and `expectedField` vary slowly with position (< 0.5 % per km), so a single fix at app start is fine for stationary users. For long-distance travelers, add a `Geolocation.watchPosition` with `distanceFilter: 10_000` (10 km) and `interval: 600_000` (10 min) — same accuracy, negligible battery cost. **Don't poll every second** — it has zero accuracy benefit and significant battery cost.
+- **Pass `NaN, NaN` and `0`** to revert when the user disables location: `setLocation(NaN, NaN); NitroCompass.setDeclination(0)`.
+- **iOS**: `setLocation` is a no-op (`CLLocationManager` already uses GPS-derived location internally), but `setDeclination` works the same way as on Android — both platforms apply it before the heading hits your callback.
 
 ### Smooth dial animation (Reanimated)
 
-`useCompass()` returns React state, so each sample re-renders the consumer — fine for a numeric readout, but a rotating dial driven that way will jitter on faster filter values. For 60 fps animations, subscribe with `addHeadingListener` and write directly into a Reanimated shared value on the UI thread:
+`useCompass()` triggers a React render on every emitted sample — fine for a numeric readout, but a rotating dial driven that way will jitter at high sample rates. For 60 fps animation, subscribe with `addHeadingListener` and write directly into a Reanimated shared value on the UI thread:
 
 ```tsx
+import { useEffect, useRef } from 'react'
 import Animated, { Easing, useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated'
 import { addHeadingListener } from 'react-native-nitro-compass'
 
@@ -231,54 +297,206 @@ function Dial() {
 }
 ```
 
-The same pattern is used in [example/components/Compass.tsx](./example/components/Compass.tsx).
+The pattern is used in [`example/components/Compass.tsx`](./example/components/Compass.tsx).
 
-## Permissions
+### Location-tightened interference
 
-- **iOS**: requires `NSLocationWhenInUseUsageDescription` in `Info.plist`. `CLLocationManager` only emits headings when location permission is granted.
-- **Android**: no permission required for the rotation-vector sensor.
+`setLocation(lat, lon)` replaces the generic 20–70 µT "Earth field" band with `expectedField ± 15 µT`, where `expectedField` comes from the WMM2025 model bundled in Android's `GeomagneticField`. This catches weak interference at high or low latitudes where the natural field exceeds 60 µT — exactly the cases where the generic band is too loose.
 
-## Example app
+The recipe is identical to [True-north heading from location](#true-north-heading-from-location); call both `setLocation` and `setDeclination` with the same fix.
 
-A bare React Native CLI app under [example/](./example) (RN 0.85.3, New Arch enabled) consumes the library via a local symlink. It demos the full surface — `useCompass()` for the readout, calibration / interference banners, and a Reanimated-driven dial that subscribes via `addHeadingListener` so the rotation runs entirely on the UI thread. Use it to test changes on a real device — the iOS Simulator has no compass and the Android emulator's magnetometer is faked.
+### Calibration UI
 
-First-time setup:
+```tsx
+import { Pressable, Text, View } from 'react-native'
+import { useCompass } from 'react-native-nitro-compass'
 
-```sh
-cd example
-npm install                       # symlinks ../ as react-native-nitro-compass
-cd ios && bundle install && bundle exec pod install && cd ..
+function CalibrationBanner() {
+  const { quality, recalibrate } = useCompass()
+  if (quality !== 'unreliable' && quality !== 'low') return null
+
+  return (
+    <View style={styles.banner}>
+      <Text>Tilt and rotate the device in different directions until accuracy improves.</Text>
+      <Pressable onPress={recalibrate}>
+        <Text>Refresh</Text>
+      </Pressable>
+    </View>
+  )
+}
+```
+
+`recalibrate()` re-registers the sensor listeners on Android (which often nudges the magnetometer driver to re-evaluate calibration) and dismisses the iOS heading-calibration overlay. The user still has to move the device — this just clears cached state so progress is reflected promptly.
+
+### Custom diagnostics panel
+
+For self-diagnosing user bug reports, poll `getDebugInfo()` behind a hidden footer:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { NitroCompass, type DebugInfo } from 'react-native-nitro-compass'
+
+function DebugPanel() {
+  const [info, setInfo] = useState<DebugInfo | null>(null)
+  useEffect(() => {
+    const id = setInterval(() => {
+      try { setInfo(NitroCompass.getDebugInfo()) } catch {}
+    }, 250)
+    return () => clearInterval(id)
+  }, [])
+  // …render info.interferenceActive, info.usingUncalibratedMag, info.fusedYawDeg, etc.
+}
+```
+
+A complete implementation lives at [`example/components/DebugPanel.tsx`](./example/components/DebugPanel.tsx).
+
+## Types
+
+```ts
+interface CompassSample {
+  heading: number                  // [0, 360); magnetic by default, true-north if setDeclination was called
+  accuracy: number                 // degrees; smaller is better; -1 if unknown
+  fieldStrengthMicroTesla: number  // µT magnitude of the local magnetic field; -1 until first reading
+}
+
+type AccuracyQuality = 'high' | 'medium' | 'low' | 'unreliable'
+
+type PermissionStatus = 'granted' | 'denied' | 'unknown'
+
+type SensorKind =
+  | 'magnetometer'                 // Android raw mag + accel
+  | 'coreLocation'                 // iOS CLLocationManager
+  | 'rotationVector'               // legacy, no longer returned
+  | 'geomagneticRotationVector'    // legacy, no longer returned
+
+interface SensorDiagnostics {
+  sensor: SensorKind
+}
+
+interface DebugInfo {
+  interferenceActive: boolean
+  msSinceLastBiasJump: number       // -1 if never seen / iOS
+  expectedFieldMicroTesla: number   // -1 if setLocation() not called
+  lastFieldMicroTesla: number       // -1 if no reading
+  fusedYawDeg: number               // NaN before first sample / iOS
+  lastYawRateDegPerS: number        // 0 if game-RV unavailable
+  hasGameRotationVector: boolean    // false on iOS
+  usingUncalibratedMag: boolean     // false on iOS
+}
 ```
 
-Run on a device:
+### `AccuracyQuality` thresholds
+
+The bucket is derived from a numeric heading-accuracy estimate on both platforms, but the thresholds differ because the underlying scales disagree:
+
+- **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`.
+
+When magnetic interference is detected on Android, the surfaced bucket is downgraded by one notch (`high` → `medium`, etc.) — calibration ("the magnetometer needs tuning") and interference ("the field is currently being skewed") are independent signals, and surfacing `quality='high'` alongside `interfering=true` is contradictory UX.
+
+## Architecture
+
+### Why not `TYPE_ROTATION_VECTOR`
+
+Most React Native compass libraries use Android's `TYPE_ROTATION_VECTOR`, which feels great until you put a magnet, a phone, or a laptop next to the device — the OS-level Kalman filter then holds a poisoned bias estimate for many seconds after the source is removed. This library computes heading directly from raw `accelerometer + magnetometer` via `getRotationMatrix()` (the same approach used by popular consumer compass apps), so recovery from interference is instant.
+
+We trade a few degrees of steady-state jitter for stateless behavior, then add back smoothness via two layers:
+
+1. **Adaptive input low-pass** on the accel and mag *vectors* before they enter `getRotationMatrix()`. Different α per sensor (accel is jerk-noisy, mag is hard-iron-noisy), and α is adaptive on gyro-derived yaw rate — strong filter when still, weak when turning fast.
+2. **Gyro complementary fusion** on top of the result. `TYPE_GAME_ROTATION_VECTOR` provides a Δyaw between events; we integrate that into a `fusedYawDeg` and let mag samples pull it back to absolute via a small (~1 s time constant) blend. During interference the blend is disabled — gyro alone carries heading until the field clears, then a one-shot snap re-syncs.
+
+The output is then run through an EMA on `(sin θ, cos θ)` (handles 359°→0° wraparound cleanly) before delivery — tunable via `setSmoothing()`.
+
+### Magnetic interference
+
+Detection on **Android** combines two signals:
+
+1. The raw magnetic field magnitude leaving the Earth band (~20–70 µT, or `expectedField ± 15 µT` if you've called `setLocation`).
+2. Recent OS hard-iron-bias jumps on `TYPE_MAGNETIC_FIELD_UNCALIBRATED`.
+
+The bias-jump signal catches *weak* interference events the magnitude check alone would miss — e.g. another phone placed on top of yours, where the corrected field magnitude stays near 50 µT but the OS still revises its bias estimate. Either signal flips `interfering` to `true`; both must clear (and a 1.5 s grace window expire) before `false` is reported.
+
+On **iOS**, detection uses `CMDeviceMotion.magneticField` (calibrated, with the device's own hard-iron bias subtracted in real time). Transitions wait for CoreMotion's bias estimate to converge (5 consecutive non-`uncalibrated` samples — typically a second or two of normal device movement after subscribe) so the first second post-`start()` doesn't fire false positives.
+
+### Background pause
+
+By default the underlying sensor / location-manager subscription is silently paused while the app is backgrounded and resumed on foreground — the JS callback, declination, and other settings are preserved across the pause. To opt out (e.g. for a fitness tracker that needs heading while screen-off):
+
+```ts
+NitroCompass.setPauseOnBackground(false)
+```
+
+## Troubleshooting
+
+### Heading is consistently off by N degrees
+
+You're seeing magnetic heading; you wanted true-north. Apply declination from a WMM model — see [True-north heading from location](#true-north-heading-from-location).
+
+If the offset is much larger than expected (>30°), the device is likely in a building with steel framing or near a strong electromagnetic source; check `interfering` and `lastFieldMicroTesla` via `getDebugInfo()`.
+
+### Heading is jittery
+
+- **Android**: increase `setSmoothing` damping — try `0.1` or `0.05` (default is `0.2`). Smaller α = more smoothing.
+- **Both platforms**: increase `filterDegrees` — `2` or `3` is plenty for a UI dial.
+- For 60 fps animations, subscribe with `addHeadingListener` and write directly into a Reanimated shared value (see the [Reanimated recipe](#smooth-dial-animation-reanimated)).
+
+### Calibration banner won't clear
+
+Call `recalibrate()` (or expose a "Refresh" button to the user). On Android this re-registers the sensor listeners, which often nudges the driver to re-evaluate calibration. The user still has to move the device — this just clears cached state so progress is reflected promptly.
+
+If the banner clears and immediately re-shows, the device is likely under sustained interference — check `interfering` and walk away from the source.
+
+### iOS: `start()` throws `Location authorization denied`
+
+The user has denied location permission in Settings. Drive the prompt via the hook:
+
+```tsx
+const { permission, requestPermission } = useCompass()
+if (permission === 'unknown') requestPermission()
+```
+
+iOS does not re-prompt once permission is denied — direct the user to Settings via `Linking.openSettings()`.
+
+### Android: heading is silent, no events
+
+- Verify `hasCompass` is `true`. The Android emulator has a faked magnetometer; on a real device, `getDefaultSensor(TYPE_MAGNETIC_FIELD)` should return non-null.
+- Wrap the start in a try/catch — `subscribe` will throw if either accelerometer or magnetometer is missing on the device (extremely rare on modern hardware).
+
+### Simulator shows no heading
+
+The iOS Simulator has no compass hardware — testing requires a physical device. The Android emulator's magnetometer is faked and stationary at a single point; it'll respond to manual rotation in the emulator's "Sensors" panel but won't track movement.
+
+## Example app
+
+A bare React Native CLI app under [example/](./example) (RN 0.85.3, New Arch enabled) consumes the library via a local symlink. It demos the full surface — `useCompass()` for the readout, calibration / interference banners, a Reanimated-driven dial, location-tightened interference via `react-native-geolocation-service`, and a collapsible debug panel polling `getDebugInfo()`. Use it to test changes on a real device — the iOS Simulator has no compass.
 
 ```sh
-# Terminal 1 — Metro
-npm start
+cd example
+npm install                                           # symlinks ../ as react-native-nitro-compass
+cd ios && bundle install && bundle exec pod install   # iOS only
 
-# Terminal 2 — build & launch
-npm run ios -- --device           # physical iPhone
-npm run android                   # physical device or emulator
+# back in example/
+npm start                                             # Metro
+npm run ios -- --device                               # physical iPhone
+npm run android                                       # physical device or emulator
 ```
 
-If you change the Nitrogen spec or any native source, regenerate and rebuild:
+If you change the Nitro spec or any native source, regenerate and rebuild:
 
 ```sh
 # from the repo root
 npm run codegen
 # then in example/
-cd ios && bundle exec pod install && cd ..   # iOS only
+cd ios && bundle exec pod install && cd ..
 npm run ios       # or npm run android
 ```
 
-The example imports `NitroCompass` directly from the workspace `src/` (via Metro `watchFolders`), so editing TypeScript only requires a Metro reload.
-
 ## Acknowledgments
 
-The Android rotation-vector pattern (sensor fusion, surface-rotation remapping, `getOrientation` extraction) is adapted from the MIT-licensed [Andromeda](https://github.com/kylecorry31/andromeda) sensor library by Kyle Corry, which powers the [Trail Sense](https://github.com/kylecorry31/Trail-Sense) wilderness navigation app.
+The Android sensor pattern (raw mag + accel fusion via `getRotationMatrix`, surface-rotation remapping, `getOrientation` extraction, EMA on `(sin θ, cos θ)`) is adapted from the MIT-licensed [Andromeda](https://github.com/kylecorry31/andromeda) sensor library by Kyle Corry, which powers the [Trail Sense](https://github.com/kylecorry31/Trail-Sense) wilderness navigation app.
 
 Bootstrapped with [create-nitro-module](https://github.com/patrickkabwe/create-nitro-module).
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+[MIT](./LICENSE)