@symbiote-native/sensors 0.1.0

package/src/core/native/exponent-light-sensor/index.ios.ts

@@ -0,0 +1,12 @@
+// The light sensor has no iOS native support (upstream ExpoLightSensor.ios.ts carries the
+// same TODO) — this stub always reports unavailable so LightSensorSensor degrades gracefully
+// instead of throwing when requireNativeModule() would fail to resolve a real module.
+import type { INativeSensorModule } from '../../device-sensor';
+import type { ILightSensorMeasurement } from '../../light-sensor';
+
+export const exponentLightSensor: INativeSensorModule<ILightSensorMeasurement> = {
+  addListener: () => ({ remove: () => {} }),
+  listenerCount: () => 0,
+  removeAllListeners: () => {},
+  isAvailableAsync: async () => false,
+};

package/src/core/native/exponent-light-sensor/index.ts

@@ -0,0 +1,5 @@
+// Base resolution for plain Node/vitest imports of './native/exponent-light-sensor', which
+// don't go through Metro's platform-extension picking — re-exports the iOS stub so headless
+// resolution stays side-effect-free and never calls requireNativeModule() outside a real RN
+// runtime. Metro still picks index.ios.ts/index.android.ts per real platform at bundle time.
+export { exponentLightSensor } from './index.ios';

package/src/core/native/exponent-magnetometer-uncalibrated.ts

@@ -0,0 +1,9 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { INativeSensorModule } from '../device-sensor';
+import type { IMagnetometerUncalibratedMeasurement } from '../magnetometer-uncalibrated';
+
+const EXPONENT_MAGNETOMETER_UNCALIBRATED_MODULE_NAME = 'ExponentMagnetometerUncalibrated';
+
+export const exponentMagnetometerUncalibrated = requireNativeModule<
+  INativeSensorModule<IMagnetometerUncalibratedMeasurement>
+>(EXPONENT_MAGNETOMETER_UNCALIBRATED_MODULE_NAME);

package/src/core/native/exponent-magnetometer.ts

@@ -0,0 +1,9 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { INativeSensorModule } from '../device-sensor';
+import type { IMagnetometerMeasurement } from '../magnetometer';
+
+const EXPONENT_MAGNETOMETER_MODULE_NAME = 'ExponentMagnetometer';
+
+export const exponentMagnetometer = requireNativeModule<
+  INativeSensorModule<IMagnetometerMeasurement>
+>(EXPONENT_MAGNETOMETER_MODULE_NAME);

package/src/core/native/exponent-pedometer.ts

@@ -0,0 +1,17 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription, PermissionResponse } from 'expo-modules-core';
+import type { IPedometerResult } from '../pedometer';
+
+const EXPONENT_PEDOMETER_MODULE_NAME = 'ExponentPedometer';
+
+export type IExponentPedometerModule = {
+  addListener(eventName: string, listener: (result: IPedometerResult) => void): EventSubscription;
+  getStepCountAsync?(startMs: number, endMs: number): Promise<IPedometerResult>;
+  isAvailableAsync(): Promise<boolean>;
+  getPermissionsAsync?(): Promise<PermissionResponse>;
+  requestPermissionsAsync?(): Promise<PermissionResponse>;
+};
+
+export const exponentPedometer = requireNativeModule<IExponentPedometerModule>(
+  EXPONENT_PEDOMETER_MODULE_NAME,
+);

package/src/core/pedometer.test.ts

@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const FAKE_NATIVE_PEDOMETER = {
+  addListener: vi.fn(() => ({ remove: vi.fn() })),
+  getStepCountAsync: vi.fn(async () => ({ steps: 42 })),
+  isAvailableAsync: vi.fn(async () => true),
+  getPermissionsAsync: vi.fn(),
+  requestPermissionsAsync: vi.fn(),
+};
+
+// The real ExponentPedometer native module only exists on device — resolving it via
+// requireNativeModule() at import time would throw in this headless test run, so the
+// module-lookup file is faked in place of `expo-modules-core`'s runtime resolution.
+vi.mock('./native/exponent-pedometer', () => ({
+  exponentPedometer: FAKE_NATIVE_PEDOMETER,
+}));
+
+// pedometer.ts pulls PermissionStatus/UnavailabilityError from expo-modules-core, whose real
+// entry transitively drags in the Flow-typed 'react-native' source that Vitest's Oxc transform
+// can't parse — same fake as device-sensor.test.ts / accelerometer.test.ts.
+vi.mock('expo-modules-core', () => ({
+  PermissionStatus: { GRANTED: 'granted', UNDETERMINED: 'undetermined', DENIED: 'denied' },
+  UnavailabilityError: class UnavailabilityError extends Error {
+    constructor(moduleName: string, propertyName: string) {
+      super(`${propertyName} is not available on ${moduleName}`);
+    }
+  },
+}));
+
+const {
+  watchStepCount,
+  getStepCountAsync,
+  isAvailableAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+} = await import('./pedometer');
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('Pedometer', () => {
+  it('watchStepCount subscribes through the dotted Exponent.pedometerUpdate event name', () => {
+    const listener = vi.fn();
+    watchStepCount(listener);
+
+    expect(FAKE_NATIVE_PEDOMETER.addListener).toHaveBeenCalledWith(
+      'Exponent.pedometerUpdate',
+      listener,
+    );
+  });
+
+  it('getStepCountAsync throws when the start date is after the end date', async () => {
+    const start = new Date('2026-07-15T00:00:00Z');
+    const end = new Date('2026-07-01T00:00:00Z');
+
+    await expect(getStepCountAsync(start, end)).rejects.toThrow(
+      'Pedometer: the start date must precede the end date.',
+    );
+    expect(FAKE_NATIVE_PEDOMETER.getStepCountAsync).not.toHaveBeenCalled();
+  });
+
+  it('getStepCountAsync throws an UnavailabilityError-shaped error when the native method is absent', async () => {
+    const { getStepCountAsync: nativeGetStepCountAsync } = FAKE_NATIVE_PEDOMETER;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_PEDOMETER.getStepCountAsync = undefined;
+
+    const start = new Date('2026-07-01T00:00:00Z');
+    const end = new Date('2026-07-15T00:00:00Z');
+
+    await expect(getStepCountAsync(start, end)).rejects.toThrow(
+      'getStepCountAsync is not available on ExponentPedometer',
+    );
+
+    FAKE_NATIVE_PEDOMETER.getStepCountAsync = nativeGetStepCountAsync;
+  });
+
+  it('getStepCountAsync calls through with millisecond values from each Date', async () => {
+    const start = new Date('2026-07-01T00:00:00Z');
+    const end = new Date('2026-07-15T00:00:00Z');
+
+    const result = await getStepCountAsync(start, end);
+
+    expect(FAKE_NATIVE_PEDOMETER.getStepCountAsync).toHaveBeenCalledWith(
+      start.getTime(),
+      end.getTime(),
+    );
+    expect(result).toEqual({ steps: 42 });
+  });
+
+  it('isAvailableAsync delegates to the native module', async () => {
+    await expect(isAvailableAsync()).resolves.toBe(true);
+    expect(FAKE_NATIVE_PEDOMETER.isAvailableAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('falls back to a granted default permission response when the native module has none', async () => {
+    const {
+      getPermissionsAsync: nativeGetPermissionsAsync,
+      requestPermissionsAsync: nativeRequestPermissionsAsync,
+    } = FAKE_NATIVE_PEDOMETER;
+    // @ts-expect-error -- simulating a platform where the native module exposes no permission methods
+    FAKE_NATIVE_PEDOMETER.getPermissionsAsync = undefined;
+    // @ts-expect-error -- simulating a platform where the native module exposes no permission methods
+    FAKE_NATIVE_PEDOMETER.requestPermissionsAsync = undefined;
+
+    const expectedDefault = {
+      granted: true,
+      expires: 'never',
+      canAskAgain: true,
+      status: 'granted',
+    };
+    await expect(getPermissionsAsync()).resolves.toEqual(expectedDefault);
+    await expect(requestPermissionsAsync()).resolves.toEqual(expectedDefault);
+
+    FAKE_NATIVE_PEDOMETER.getPermissionsAsync = nativeGetPermissionsAsync;
+    FAKE_NATIVE_PEDOMETER.requestPermissionsAsync = nativeRequestPermissionsAsync;
+  });
+});

package/src/core/pedometer.ts

@@ -0,0 +1,62 @@
+// Pedometer's upstream API (.vendors/expo/packages/expo-sensors/src/Pedometer.ts) is a set of
+// free functions, not a class — unlike every other sensor here it has no shared instance to hang
+// addListener/removeAllListeners/setUpdateInterval off, so it intentionally does NOT extend
+// DeviceSensor (see device-sensor.ts for that shared shape).
+import {
+  PermissionStatus,
+  UnavailabilityError,
+  type EventSubscription,
+  type PermissionResponse,
+} from 'expo-modules-core';
+import { exponentPedometer } from './native/exponent-pedometer';
+
+export type IPedometerResult = {
+  steps: number;
+};
+
+export type IPedometerUpdateCallback = (result: IPedometerResult) => void;
+
+// Upstream event name — the only sensor event in this package carrying a dot, because it is
+// Exponent's original (pre-Expo-rename) native module identifier.
+const PEDOMETER_UPDATE_EVENT_NAME = 'Exponent.pedometerUpdate';
+
+const DEFAULT_PERMISSION_RESPONSE: PermissionResponse = {
+  granted: true,
+  expires: 'never',
+  canAskAgain: true,
+  status: PermissionStatus.GRANTED,
+};
+
+export function watchStepCount(callback: IPedometerUpdateCallback): EventSubscription {
+  return exponentPedometer.addListener(PEDOMETER_UPDATE_EVENT_NAME, callback);
+}
+
+// iOS only in practice (Android has no native getStepCountAsync) — proven by the same
+// optional-native-method check upstream uses, not a Platform.OS branch.
+export async function getStepCountAsync(start: Date, end: Date): Promise<IPedometerResult> {
+  if (!exponentPedometer.getStepCountAsync) {
+    throw new UnavailabilityError('ExponentPedometer', 'getStepCountAsync');
+  }
+  if (start > end) {
+    throw new Error('Pedometer: the start date must precede the end date.');
+  }
+  return exponentPedometer.getStepCountAsync(start.getTime(), end.getTime());
+}
+
+export async function isAvailableAsync(): Promise<boolean> {
+  return exponentPedometer.isAvailableAsync();
+}
+
+export async function getPermissionsAsync(): Promise<PermissionResponse> {
+  if (!exponentPedometer.getPermissionsAsync) {
+    return DEFAULT_PERMISSION_RESPONSE;
+  }
+  return exponentPedometer.getPermissionsAsync();
+}
+
+export async function requestPermissionsAsync(): Promise<PermissionResponse> {
+  if (!exponentPedometer.requestPermissionsAsync) {
+    return DEFAULT_PERMISSION_RESPONSE;
+  }
+  return exponentPedometer.requestPermissionsAsync();
+}

package/src/react/hooks/use-accelerometer/index.ts

@@ -0,0 +1,21 @@
+// React lifecycle wiring over the framework-agnostic Accelerometer singleton (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+import { useEffect, useState } from 'react';
+import { Accelerometer, type IAccelerometerMeasurement } from '../../../core';
+
+export function useAccelerometer(updateIntervalMs?: number): IAccelerometerMeasurement | null {
+  const [measurement, setMeasurement] = useState<IAccelerometerMeasurement | null>(null);
+
+  useEffect(() => {
+    // Re-subscribing on interval change keeps the native update rate in sync with the
+    // caller's latest `updateIntervalMs` rather than only ever honoring the first mount's.
+    if (updateIntervalMs !== undefined) {
+      Accelerometer.setUpdateInterval(updateIntervalMs);
+    }
+
+    const subscription = Accelerometer.addListener(setMeasurement);
+    return () => subscription.remove();
+  }, [updateIntervalMs]);
+
+  return measurement;
+}

package/src/react/hooks/use-accelerometer/use-accelerometer.test.tsx

@@ -0,0 +1,81 @@
+// Co-located React-driven test (ADR 0025) for useAccelerometer. Mocks the whole `core`
+// module rather than expo-modules-core internals — this hook's own lifecycle wiring
+// (subscribe/unsubscribe/interval) is what's under test, not the core port itself, which
+// already has its own coverage in packages/sensors/src/core/*.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { useAccelerometer } from './index';
+import type { IAccelerometerMeasurement } from '../../../core';
+
+const { addListener, removeAllListeners, setUpdateInterval, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: (measurement: IAccelerometerMeasurement) => void) => ({
+      remove,
+    })),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  Accelerometer: { addListener, removeAllListeners, setUpdateInterval },
+}));
+
+const ROOT_TAG = 901;
+
+const results: Array<IAccelerometerMeasurement | null> = [];
+
+function Probe(props: { updateIntervalMs?: number }): ReactElement {
+  results.push(useAccelerometer(props.updateIntervalMs));
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useAccelerometer', () => {
+  it('reports null before any native measurement arrives', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest measurement once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    const measurement: IAccelerometerMeasurement = { x: 0.1, y: 0.2, z: 0.3, timestamp: 123 };
+    const listener = addListener.mock.calls[0][0];
+    listener(measurement);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(measurement));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the native update interval when updateIntervalMs is provided', () => {
+    mount(ROOT_TAG, createElement(Probe, { updateIntervalMs: 100 }));
+
+    expect(setUpdateInterval).toHaveBeenCalledWith(100);
+  });
+});

package/src/react/hooks/use-barometer/index.ts

@@ -0,0 +1,21 @@
+// React lifecycle wiring over the framework-agnostic Barometer singleton (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+import { useEffect, useState } from 'react';
+import { Barometer, type IBarometerMeasurement } from '../../../core';
+
+export function useBarometer(updateIntervalMs?: number): IBarometerMeasurement | null {
+  const [measurement, setMeasurement] = useState<IBarometerMeasurement | null>(null);
+
+  useEffect(() => {
+    // Re-subscribing on interval change keeps the native update rate in sync with the
+    // caller's latest `updateIntervalMs` rather than only ever honoring the first mount's.
+    if (updateIntervalMs !== undefined) {
+      Barometer.setUpdateInterval(updateIntervalMs);
+    }
+
+    const subscription = Barometer.addListener(setMeasurement);
+    return () => subscription.remove();
+  }, [updateIntervalMs]);
+
+  return measurement;
+}

package/src/react/hooks/use-barometer/use-barometer.test.tsx

@@ -0,0 +1,83 @@
+// Co-located React-driven test (ADR 0025) for useBarometer. Mocks the whole `core`
+// module rather than expo-modules-core internals — this hook's own lifecycle wiring
+// (subscribe/unsubscribe/interval) is what's under test, not the core port itself, which
+// already has its own coverage in packages/sensors/src/core/*.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { useBarometer } from './index';
+import type { IBarometerMeasurement } from '../../../core';
+
+const { addListener, removeAllListeners, setUpdateInterval, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: (measurement: IBarometerMeasurement) => void) => ({ remove })),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  Barometer: { addListener, removeAllListeners, setUpdateInterval },
+}));
+
+const ROOT_TAG = 902;
+
+const results: Array<IBarometerMeasurement | null> = [];
+
+function Probe(props: { updateIntervalMs?: number }): ReactElement {
+  results.push(useBarometer(props.updateIntervalMs));
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useBarometer', () => {
+  it('reports null before any native measurement arrives', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest measurement once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    const measurement: IBarometerMeasurement = {
+      pressure: 1013.25,
+      relativeAltitude: 12.3,
+      timestamp: 123,
+    };
+    const listener = addListener.mock.calls[0][0];
+    listener(measurement);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(measurement));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the native update interval when updateIntervalMs is provided', () => {
+    mount(ROOT_TAG, createElement(Probe, { updateIntervalMs: 100 }));
+
+    expect(setUpdateInterval).toHaveBeenCalledWith(100);
+  });
+});

package/src/react/hooks/use-device-motion/index.ts

@@ -0,0 +1,21 @@
+// React lifecycle wiring over the framework-agnostic DeviceMotion singleton (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+import { useEffect, useState } from 'react';
+import { DeviceMotion, type IDeviceMotionMeasurement } from '../../../core';
+
+export function useDeviceMotion(updateIntervalMs?: number): IDeviceMotionMeasurement | null {
+  const [measurement, setMeasurement] = useState<IDeviceMotionMeasurement | null>(null);
+
+  useEffect(() => {
+    // Re-subscribing on interval change keeps the native update rate in sync with the
+    // caller's latest `updateIntervalMs` rather than only ever honoring the first mount's.
+    if (updateIntervalMs !== undefined) {
+      DeviceMotion.setUpdateInterval(updateIntervalMs);
+    }
+
+    const subscription = DeviceMotion.addListener(setMeasurement);
+    return () => subscription.remove();
+  }, [updateIntervalMs]);
+
+  return measurement;
+}

package/src/react/hooks/use-device-motion/use-device-motion.test.tsx

@@ -0,0 +1,88 @@
+// Co-located React-driven test (ADR 0025) for useDeviceMotion. Mocks the whole `core`
+// module rather than expo-modules-core internals — this hook's own lifecycle wiring
+// (subscribe/unsubscribe/interval) is what's under test, not the core port itself, which
+// already has its own coverage in packages/sensors/src/core/*.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { useDeviceMotion } from './index';
+import type { IDeviceMotionMeasurement } from '../../../core';
+
+const { addListener, removeAllListeners, setUpdateInterval, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: (measurement: IDeviceMotionMeasurement) => void) => ({
+      remove,
+    })),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  DeviceMotion: { addListener, removeAllListeners, setUpdateInterval },
+}));
+
+const ROOT_TAG = 902;
+
+const results: Array<IDeviceMotionMeasurement | null> = [];
+
+function Probe(props: { updateIntervalMs?: number }): ReactElement {
+  results.push(useDeviceMotion(props.updateIntervalMs));
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useDeviceMotion', () => {
+  it('reports null before any native measurement arrives', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest measurement once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    const measurement: IDeviceMotionMeasurement = {
+      acceleration: { x: 0.1, y: 0.2, z: 0.3, timestamp: 123 },
+      accelerationIncludingGravity: { x: 0.1, y: 0.2, z: 9.8, timestamp: 123 },
+      rotation: { alpha: 1, beta: 2, gamma: 3, timestamp: 123 },
+      rotationRate: { alpha: 0.1, beta: 0.2, gamma: 0.3, timestamp: 123 },
+      interval: 16,
+      orientation: 0, // DeviceMotionOrientation.Portrait
+    };
+    const listener = addListener.mock.calls[0][0];
+    listener(measurement);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(measurement));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the native update interval when updateIntervalMs is provided', () => {
+    mount(ROOT_TAG, createElement(Probe, { updateIntervalMs: 100 }));
+
+    expect(setUpdateInterval).toHaveBeenCalledWith(100);
+  });
+});

package/src/react/hooks/use-gyroscope/index.ts

@@ -0,0 +1,21 @@
+// React lifecycle wiring over the framework-agnostic Gyroscope singleton (core/) —
+// mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
+import { useEffect, useState } from 'react';
+import { Gyroscope, type IGyroscopeMeasurement } from '../../../core';
+
+export function useGyroscope(updateIntervalMs?: number): IGyroscopeMeasurement | null {
+  const [measurement, setMeasurement] = useState<IGyroscopeMeasurement | null>(null);
+
+  useEffect(() => {
+    // Re-subscribing on interval change keeps the native update rate in sync with the
+    // caller's latest `updateIntervalMs` rather than only ever honoring the first mount's.
+    if (updateIntervalMs !== undefined) {
+      Gyroscope.setUpdateInterval(updateIntervalMs);
+    }
+
+    const subscription = Gyroscope.addListener(setMeasurement);
+    return () => subscription.remove();
+  }, [updateIntervalMs]);
+
+  return measurement;
+}

package/src/react/hooks/use-gyroscope/use-gyroscope.test.tsx

@@ -0,0 +1,79 @@
+// Co-located React-driven test (ADR 0025) for useGyroscope. Mocks the whole `core`
+// module rather than expo-modules-core internals — this hook's own lifecycle wiring
+// (subscribe/unsubscribe/interval) is what's under test, not the core port itself, which
+// already has its own coverage in packages/sensors/src/core/*.test.ts.
+
+import { createElement, type ReactElement } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount, View } from '@symbiote-native/react';
+import { installFabric } from '@symbiote-native/test-utils';
+import { useGyroscope } from './index';
+import type { IGyroscopeMeasurement } from '../../../core';
+
+const { addListener, removeAllListeners, setUpdateInterval, remove } = vi.hoisted(() => {
+  const remove = vi.fn();
+  return {
+    addListener: vi.fn((_listener: (measurement: IGyroscopeMeasurement) => void) => ({ remove })),
+    removeAllListeners: vi.fn(),
+    setUpdateInterval: vi.fn(),
+    remove,
+  };
+});
+
+vi.mock('../../../core', () => ({
+  Gyroscope: { addListener, removeAllListeners, setUpdateInterval },
+}));
+
+const ROOT_TAG = 902;
+
+const results: Array<IGyroscopeMeasurement | null> = [];
+
+function Probe(props: { updateIntervalMs?: number }): ReactElement {
+  results.push(useGyroscope(props.updateIntervalMs));
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  results.length = 0;
+  vi.clearAllMocks();
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('useGyroscope', () => {
+  it('reports null before any native measurement arrives', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    expect(results[results.length - 1]).toBeNull();
+  });
+
+  it('updates to the latest measurement once the native listener fires', async () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    const measurement: IGyroscopeMeasurement = { x: 0.1, y: 0.2, z: 0.3, timestamp: 123 };
+    const listener = addListener.mock.calls[0][0];
+    listener(measurement);
+
+    // The mock invokes the listener directly, outside the engine's event dispatcher
+    // (setEventDispatcher in render.ts), which is what normally flushes a native-driven
+    // setState synchronously — so the resulting re-render lands on a later microtask here.
+    await vi.waitFor(() => expect(results[results.length - 1]).toEqual(measurement));
+  });
+
+  it('unsubscribes from the native listener on unmount', () => {
+    mount(ROOT_TAG, createElement(Probe, {}));
+
+    unmount(ROOT_TAG);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets the native update interval when updateIntervalMs is provided', () => {
+    mount(ROOT_TAG, createElement(Probe, { updateIntervalMs: 100 }));
+
+    expect(setUpdateInterval).toHaveBeenCalledWith(100);
+  });
+});