@symbiote-native/cellular 0.0.1

package/src/core/cellular.test.ts

@@ -0,0 +1,193 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const FAKE_NATIVE_CELLULAR = {
+  getCellularGenerationAsync: vi.fn(async () => 3),
+  allowsVoipAsync: vi.fn(async () => true),
+  getIsoCountryCodeAsync: vi.fn(async () => 'us'),
+  getCarrierNameAsync: vi.fn(async () => 'Fake Carrier'),
+  getMobileCountryCodeAsync: vi.fn(async () => '310'),
+  getMobileNetworkCodeAsync: vi.fn(async () => '260'),
+  getPermissionsAsync: vi.fn(async () => ({
+    status: 'granted',
+    expires: 'never',
+    granted: true,
+    canAskAgain: true,
+  })),
+  requestPermissionsAsync: vi.fn(async () => ({
+    status: 'granted',
+    expires: 'never',
+    granted: true,
+    canAskAgain: true,
+  })),
+};
+
+// The real ExpoCellular 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, same pattern
+// packages/haptics/src/core/haptics.test.ts uses.
+vi.mock('./native-module', () => ({
+  expoCellular: FAKE_NATIVE_CELLULAR,
+}));
+
+// expo-modules-core's real entry transitively imports 'react-native' for Platform/
+// TurboModuleRegistry, whose Flow-typed source Vitest's Oxc transform can't parse — same fake
+// packages/haptics/src/core/haptics.test.ts uses. PermissionStatus/UnavailabilityError are faked
+// alongside it for the same reason.
+const fakePlatform = { OS: 'android' as 'ios' | 'android' };
+
+vi.mock('expo-modules-core', () => ({
+  Platform: fakePlatform,
+  PermissionStatus: { GRANTED: 'granted', DENIED: 'denied', UNDETERMINED: 'undetermined' },
+  UnavailabilityError: class UnavailabilityError extends Error {
+    constructor(moduleName: string, propertyName: string) {
+      super(`${propertyName} is not available on ${moduleName}`);
+    }
+  },
+}));
+
+const {
+  getCellularGenerationAsync,
+  allowsVoipAsync,
+  getIsoCountryCodeAsync,
+  getCarrierNameAsync,
+  getMobileCountryCodeAsync,
+  getMobileNetworkCodeAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+} = await import('./cellular');
+
+afterEach(() => {
+  fakePlatform.OS = 'android';
+  vi.clearAllMocks();
+});
+
+describe('getCellularGenerationAsync', () => {
+  it('delegates to the native module unconditionally (no platform gate)', async () => {
+    await expect(getCellularGenerationAsync()).resolves.toBe(3);
+  });
+
+  it('still delegates on iOS', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getCellularGenerationAsync()).resolves.toBe(3);
+  });
+
+  it('throws an UnavailabilityError-shaped error when the native method is absent', async () => {
+    const { getCellularGenerationAsync: native } = FAKE_NATIVE_CELLULAR;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_CELLULAR.getCellularGenerationAsync = undefined;
+
+    await expect(getCellularGenerationAsync()).rejects.toThrow(
+      'getCellularGenerationAsync is not available on expo-cellular',
+    );
+
+    FAKE_NATIVE_CELLULAR.getCellularGenerationAsync = native;
+  });
+});
+
+describe('allowsVoipAsync', () => {
+  it('resolves null on iOS without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(allowsVoipAsync()).resolves.toBeNull();
+    expect(FAKE_NATIVE_CELLULAR.allowsVoipAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    await expect(allowsVoipAsync()).resolves.toBe(true);
+  });
+
+  it('throws an UnavailabilityError-shaped error when the native method is absent on Android', async () => {
+    const { allowsVoipAsync: native } = FAKE_NATIVE_CELLULAR;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_CELLULAR.allowsVoipAsync = undefined;
+
+    await expect(allowsVoipAsync()).rejects.toThrow(
+      'allowsVoipAsync is not available on expo-cellular',
+    );
+
+    FAKE_NATIVE_CELLULAR.allowsVoipAsync = native;
+  });
+});
+
+describe('getIsoCountryCodeAsync', () => {
+  it('resolves null on iOS without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getIsoCountryCodeAsync()).resolves.toBeNull();
+    expect(FAKE_NATIVE_CELLULAR.getIsoCountryCodeAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    await expect(getIsoCountryCodeAsync()).resolves.toBe('us');
+  });
+});
+
+describe('getCarrierNameAsync', () => {
+  it('resolves null on iOS without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getCarrierNameAsync()).resolves.toBeNull();
+    expect(FAKE_NATIVE_CELLULAR.getCarrierNameAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    await expect(getCarrierNameAsync()).resolves.toBe('Fake Carrier');
+  });
+});
+
+describe('getMobileCountryCodeAsync', () => {
+  it('resolves null on iOS without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getMobileCountryCodeAsync()).resolves.toBeNull();
+    expect(FAKE_NATIVE_CELLULAR.getMobileCountryCodeAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    await expect(getMobileCountryCodeAsync()).resolves.toBe('310');
+  });
+});
+
+describe('getMobileNetworkCodeAsync', () => {
+  it('resolves null on iOS without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getMobileNetworkCodeAsync()).resolves.toBeNull();
+    expect(FAKE_NATIVE_CELLULAR.getMobileNetworkCodeAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    await expect(getMobileNetworkCodeAsync()).resolves.toBe('260');
+  });
+});
+
+describe('getPermissionsAsync', () => {
+  it('delegates to the native module on Android', async () => {
+    await getPermissionsAsync();
+    expect(FAKE_NATIVE_CELLULAR.getPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('resolves a plain GRANTED literal on iOS without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getPermissionsAsync()).resolves.toEqual({
+      status: 'granted',
+      expires: 'never',
+      granted: true,
+      canAskAgain: true,
+    });
+    expect(FAKE_NATIVE_CELLULAR.getPermissionsAsync).not.toHaveBeenCalled();
+  });
+});
+
+describe('requestPermissionsAsync', () => {
+  it('delegates to the native module on Android', async () => {
+    await requestPermissionsAsync();
+    expect(FAKE_NATIVE_CELLULAR.requestPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('resolves a plain GRANTED literal on iOS without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(requestPermissionsAsync()).resolves.toEqual({
+      status: 'granted',
+      expires: 'never',
+      granted: true,
+      canAskAgain: true,
+    });
+    expect(FAKE_NATIVE_CELLULAR.requestPermissionsAsync).not.toHaveBeenCalled();
+  });
+});

package/src/core/cellular.ts

@@ -0,0 +1,131 @@
+// Hand-ported from .vendors/expo/packages/expo-cellular/src/Cellular.ts (sdk-57). Carrier/SIM
+// info (ISO country code, carrier name, MCC/MNC) and allowsVoipAsync are Android-only upstream —
+// each short-circuits to `null` on iOS before ever reaching the native module, since iOS exposes
+// none of this. getPermissionsAsync/requestPermissionsAsync mirror that same split: Android
+// delegates to the native module, every other platform needs no permission for cellular info at
+// all and resolves a plain GRANTED literal. Upstream's web branch (navigator.connection) is out
+// of scope — this repo has no web target for this package's native-module resolution path.
+import {
+  Platform,
+  PermissionStatus,
+  UnavailabilityError,
+  type PermissionResponse,
+} from 'expo-modules-core';
+import { expoCellular } from './native-module';
+import { CellularGeneration } from './types';
+
+const NATIVE_MODULE_NAME = 'expo-cellular';
+
+const GRANTED_PERMISSION_RESPONSE: PermissionResponse = {
+  status: PermissionStatus.GRANTED,
+  expires: 'never',
+  granted: true,
+  canAskAgain: true,
+};
+
+/** Gets the generation of the device's current connection. */
+export async function getCellularGenerationAsync(): Promise<CellularGeneration> {
+  if (!expoCellular.getCellularGenerationAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getCellularGenerationAsync');
+  }
+  return expoCellular.getCellularGenerationAsync();
+}
+
+/**
+ * Tells if the carrier of the SIM card allows to make VoIP calls on its network.
+ * @deprecated This method is deprecated and will be removed in a future SDK version.
+ * @platform android
+ */
+export async function allowsVoipAsync(): Promise<boolean | null> {
+  if (Platform.OS === 'ios') {
+    return null;
+  }
+  if (!expoCellular.allowsVoipAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'allowsVoipAsync');
+  }
+  return expoCellular.allowsVoipAsync();
+}
+
+/**
+ * Gets the ISO country code of the current registered operator's MCC (Mobile Country Code).
+ * @platform android
+ */
+export async function getIsoCountryCodeAsync(): Promise<string | null> {
+  if (Platform.OS === 'ios') {
+    return null;
+  }
+  if (!expoCellular.getIsoCountryCodeAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getIsoCountryCodeAsync');
+  }
+  return expoCellular.getIsoCountryCodeAsync();
+}
+
+/**
+ * Gets the name of the user's cellular service provider.
+ * @platform android
+ */
+export async function getCarrierNameAsync(): Promise<string | null> {
+  if (Platform.OS === 'ios') {
+    return null;
+  }
+  if (!expoCellular.getCarrierNameAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getCarrierNameAsync');
+  }
+  return expoCellular.getCarrierNameAsync();
+}
+
+/**
+ * Gets the mobile country code (MCC) of the device's current registered operator.
+ * @platform android
+ */
+export async function getMobileCountryCodeAsync(): Promise<string | null> {
+  if (Platform.OS === 'ios') {
+    return null;
+  }
+  if (!expoCellular.getMobileCountryCodeAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getMobileCountryCodeAsync');
+  }
+  return expoCellular.getMobileCountryCodeAsync();
+}
+
+/**
+ * Gets the mobile network code (MNC) of the device's current registered operator.
+ * @platform android
+ */
+export async function getMobileNetworkCodeAsync(): Promise<string | null> {
+  if (Platform.OS === 'ios') {
+    return null;
+  }
+  if (!expoCellular.getMobileNetworkCodeAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getMobileNetworkCodeAsync');
+  }
+  return expoCellular.getMobileNetworkCodeAsync();
+}
+
+/**
+ * Checks user's permissions for accessing cellular information. Android only — iOS/web need no
+ * permission for cellular info, so this always resolves granted there.
+ */
+export async function getPermissionsAsync(): Promise<PermissionResponse> {
+  if (Platform.OS === 'android') {
+    if (!expoCellular.getPermissionsAsync) {
+      throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getPermissionsAsync');
+    }
+    return expoCellular.getPermissionsAsync();
+  }
+  return GRANTED_PERMISSION_RESPONSE;
+}
+
+/**
+ * Asks the user to grant permissions for accessing cellular information. Android only — iOS/web
+ * need no permission for cellular info, so this always resolves granted there.
+ */
+export async function requestPermissionsAsync(): Promise<PermissionResponse> {
+  if (Platform.OS === 'android') {
+    if (!expoCellular.requestPermissionsAsync) {
+      throw new UnavailabilityError(NATIVE_MODULE_NAME, 'requestPermissionsAsync');
+    }
+    return expoCellular.requestPermissionsAsync();
+  }
+  return GRANTED_PERMISSION_RESPONSE;
+}

package/src/core/index.ts

@@ -0,0 +1,16 @@
+export {
+  getCellularGenerationAsync,
+  allowsVoipAsync,
+  getIsoCountryCodeAsync,
+  getCarrierNameAsync,
+  getMobileCountryCodeAsync,
+  getMobileNetworkCodeAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+} from './cellular';
+export {
+  CellularGeneration,
+  PermissionStatus,
+  type PermissionResponse,
+  type PermissionExpiration,
+} from './types';

package/src/core/native-module.ts

@@ -0,0 +1,24 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { PermissionResponse } from 'expo-modules-core';
+import type { CellularGeneration } from './types';
+
+const EXPO_CELLULAR_MODULE_NAME = 'ExpoCellular';
+
+// Every method is optional — each call site checks for its presence before calling through and
+// throws an UnavailabilityError itself, same convention as
+// packages/haptics/src/core/native-module.ts and packages/local-auth/src/core/native-module.ts.
+// Most of these only exist on the Android native module (CellularModule.kt) — iOS short-circuits
+// on Platform.OS before ever reaching them (see core/cellular.ts), since carrier/SIM info isn't
+// exposed by iOS.
+export type INativeCellularModule = {
+  getCellularGenerationAsync?(): Promise<CellularGeneration>;
+  allowsVoipAsync?(): Promise<boolean>;
+  getIsoCountryCodeAsync?(): Promise<string | null>;
+  getCarrierNameAsync?(): Promise<string | null>;
+  getMobileCountryCodeAsync?(): Promise<string | null>;
+  getMobileNetworkCodeAsync?(): Promise<string | null>;
+  getPermissionsAsync?(): Promise<PermissionResponse>;
+  requestPermissionsAsync?(): Promise<PermissionResponse>;
+};
+
+export const expoCellular = requireNativeModule<INativeCellularModule>(EXPO_CELLULAR_MODULE_NAME);

package/src/core/types.ts

@@ -0,0 +1,23 @@
+// Hand-ported from .vendors/expo/packages/expo-cellular/src/Cellular.types.ts (sdk-57).
+// PermissionResponse/PermissionStatus/PermissionExpiration come straight from
+// expo-modules-core (which re-exports PermissionsInterface) — never from the `expo`
+// meta-package, unlike upstream's own Cellular.ts.
+export {
+  PermissionStatus,
+  type PermissionResponse,
+  type PermissionExpiration,
+} from 'expo-modules-core';
+
+/** Telecommunication technology used to establish a cellular connection. */
+export enum CellularGeneration {
+  /** The device's connection generation could not be determined. */
+  UNKNOWN = 0,
+  /** 2nd generation (GPRS/EDGE-class) connection. */
+  CELLULAR_2G = 1,
+  /** 3rd generation (UMTS/HSPA-class) connection. */
+  CELLULAR_3G = 2,
+  /** 4th generation (LTE-class) connection. */
+  CELLULAR_4G = 3,
+  /** 5th generation (NR-class) connection. */
+  CELLULAR_5G = 4,
+}

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

@@ -0,0 +1,39 @@
+// React lifecycle wiring over the framework-agnostic core (core/cellular.ts) — fetches the
+// current permission status on mount, then exposes request/get to re-check imperatively.
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  type PermissionResponse,
+} from '../../../core';
+
+export function usePermissions(): [
+  PermissionResponse | null,
+  () => Promise<PermissionResponse>,
+  () => Promise<PermissionResponse>,
+] {
+  const isMounted = useRef(true);
+  const [status, setStatus] = useState<PermissionResponse | null>(null);
+
+  const getPermission = useCallback(async () => {
+    const response = await getPermissionsAsync();
+    if (isMounted.current) setStatus(response);
+    return response;
+  }, []);
+
+  const requestPermission = useCallback(async () => {
+    const response = await requestPermissionsAsync();
+    if (isMounted.current) setStatus(response);
+    return response;
+  }, []);
+
+  useEffect(() => {
+    isMounted.current = true;
+    void getPermission();
+    return () => {
+      isMounted.current = false;
+    };
+  }, [getPermission]);
+
+  return [status, requestPermission, getPermission];
+}

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

@@ -0,0 +1,115 @@
+// Co-located React-driven test (ADR 0025) for usePermissions. See
+// packages/battery/src/react/hooks/use-battery-state/use-battery-state.test.tsx for the shared
+// rationale (mocks `core`, not expo-modules-core internals), adapted here to test the
+// get/request permission pair instead of a listener subscription.
+
+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 { usePermissions } from './index';
+
+type IPermissionResponse = {
+  status: string;
+  expires: 'never';
+  granted: boolean;
+  canAskAgain: boolean;
+};
+
+const GRANTED: IPermissionResponse = {
+  status: 'granted',
+  expires: 'never',
+  granted: true,
+  canAskAgain: true,
+};
+const DENIED: IPermissionResponse = {
+  status: 'denied',
+  expires: 'never',
+  granted: false,
+  canAskAgain: true,
+};
+
+const { getPermissionsAsync, requestPermissionsAsync } = vi.hoisted(() => ({
+  getPermissionsAsync: vi.fn(async () => GRANTED),
+  requestPermissionsAsync: vi.fn(async () => GRANTED),
+}));
+
+vi.mock('../../../core', () => ({
+  getPermissionsAsync,
+  requestPermissionsAsync,
+}));
+
+const ROOT_TAG = 953;
+
+let latestStatus: IPermissionResponse | null = null;
+let requestFn: (() => Promise<IPermissionResponse>) | undefined;
+let getFn: (() => Promise<IPermissionResponse>) | undefined;
+
+function Probe(): ReactElement {
+  const [status, request, get] = usePermissions();
+  latestStatus = status;
+  requestFn = request;
+  getFn = get;
+  return createElement(View);
+}
+
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  latestStatus = null;
+  requestFn = undefined;
+  getFn = undefined;
+  vi.clearAllMocks();
+  getPermissionsAsync.mockResolvedValue(GRANTED);
+  requestPermissionsAsync.mockResolvedValue(GRANTED);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+describe('usePermissions', () => {
+  it('starts at null before the initial getPermissionsAsync() resolves', () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    expect(latestStatus).toBeNull();
+  });
+
+  it('fetches the permission status on mount', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+
+    await vi.waitFor(() => expect(latestStatus).toEqual(GRANTED));
+    expect(getPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('requestPermission() re-fetches and updates the status', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+    await vi.waitFor(() => expect(latestStatus).toEqual(GRANTED));
+
+    requestPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await requestFn?.();
+
+    await vi.waitFor(() => expect(latestStatus).toEqual(DENIED));
+  });
+
+  it('getPermission() re-fetches and updates the status', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+    await vi.waitFor(() => expect(latestStatus).toEqual(GRANTED));
+
+    getPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await getFn?.();
+
+    await vi.waitFor(() => expect(latestStatus).toEqual(DENIED));
+  });
+
+  it('does not update state after unmount', async () => {
+    mount(ROOT_TAG, createElement(Probe));
+    await vi.waitFor(() => expect(latestStatus).toEqual(GRANTED));
+
+    unmount(ROOT_TAG);
+    getPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await getFn?.();
+
+    // state setter is guarded by isMounted, so the captured value from before unmount stands
+    expect(latestStatus).toEqual(GRANTED);
+  });
+});

package/src/react/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/cellular/react: the React entry over the framework-agnostic core, plus
+// usePermissions — the only stateful surface this package needs a lifecycle wrapper for.
+export { usePermissions } from './hooks/use-permissions';
+export * from '../core';

package/src/vue/composables/use-permissions/index.ts

@@ -0,0 +1,34 @@
+// Vue lifecycle wiring over the framework-agnostic core (core/cellular.ts) — fetches the
+// current permission status on mount, then exposes request/get to re-check imperatively.
+import { onMounted, ref, type Ref } from '@vue/runtime-core';
+import {
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  type PermissionResponse,
+} from '../../../core';
+
+export function usePermissions(): {
+  status: Ref<PermissionResponse | null>;
+  request: () => Promise<PermissionResponse>;
+  get: () => Promise<PermissionResponse>;
+} {
+  const status = ref<PermissionResponse | null>(null);
+
+  const get = async () => {
+    const response = await getPermissionsAsync();
+    status.value = response;
+    return response;
+  };
+
+  const request = async () => {
+    const response = await requestPermissionsAsync();
+    status.value = response;
+    return response;
+  };
+
+  onMounted(() => {
+    void get();
+  });
+
+  return { status, request, get };
+}

package/src/vue/composables/use-permissions/use-permissions.test.ts

@@ -0,0 +1,103 @@
+// Co-located Vue-driven test (ADR 0025) for usePermissions. See
+// packages/battery/src/vue/composables/use-battery-state/use-battery-state.test.ts for the
+// shared rationale, adapted here to test the get/request permission pair instead of a listener
+// subscription.
+
+import { defineComponent, h } from '@vue/runtime-core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount } from '@symbiote-native/vue';
+import { installFabric } from '@symbiote-native/test-utils';
+import { usePermissions } from './index';
+
+type IPermissionResponse = {
+  status: string;
+  expires: 'never';
+  granted: boolean;
+  canAskAgain: boolean;
+};
+
+const GRANTED: IPermissionResponse = {
+  status: 'granted',
+  expires: 'never',
+  granted: true,
+  canAskAgain: true,
+};
+const DENIED: IPermissionResponse = {
+  status: 'denied',
+  expires: 'never',
+  granted: false,
+  canAskAgain: true,
+};
+
+const getPermissionsAsyncMock = vi.fn(async () => GRANTED);
+const requestPermissionsAsyncMock = vi.fn(async () => GRANTED);
+
+vi.mock('../../../core', () => ({
+  getPermissionsAsync: () => getPermissionsAsyncMock(),
+  requestPermissionsAsync: () => requestPermissionsAsyncMock(),
+}));
+
+const ROOT_TAG = 9953;
+const fabric = installFabric();
+
+beforeEach(() => {
+  fabric.reset();
+  getPermissionsAsyncMock.mockClear();
+  requestPermissionsAsyncMock.mockClear();
+  getPermissionsAsyncMock.mockResolvedValue(GRANTED);
+  requestPermissionsAsyncMock.mockResolvedValue(GRANTED);
+});
+
+afterEach(() => unmount(ROOT_TAG));
+
+function mountPermissions(): ReturnType<typeof usePermissions> {
+  let result: ReturnType<typeof usePermissions> | undefined;
+  mount(
+    ROOT_TAG,
+    defineComponent({
+      setup: () => {
+        result = usePermissions();
+        return () => h('symbiote-text', {}, 'cellular');
+      },
+    }),
+  );
+  if (result === undefined) {
+    throw new Error('setup() did not run');
+  }
+  return result;
+}
+
+describe('usePermissions (Vue)', () => {
+  it('starts at null before the initial get() resolves', () => {
+    const { status } = mountPermissions();
+
+    expect(status.value).toBeNull();
+  });
+
+  it('fetches the permission status on mount', async () => {
+    const { status } = mountPermissions();
+
+    await vi.waitFor(() => expect(status.value).toEqual(GRANTED));
+    expect(getPermissionsAsyncMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('request() re-fetches and updates the ref', async () => {
+    const { status, request } = mountPermissions();
+    await vi.waitFor(() => expect(status.value).toEqual(GRANTED));
+
+    requestPermissionsAsyncMock.mockResolvedValueOnce(DENIED);
+    await request();
+
+    expect(status.value).toEqual(DENIED);
+  });
+
+  it('get() re-fetches and updates the ref', async () => {
+    const { status, get } = mountPermissions();
+    await vi.waitFor(() => expect(status.value).toEqual(GRANTED));
+
+    getPermissionsAsyncMock.mockResolvedValueOnce(DENIED);
+    await get();
+
+    expect(status.value).toEqual(DENIED);
+  });
+});