@symbiote-native/screen-orientation 0.0.1

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@symbiote-native/screen-orientation",
+  "version": "0.0.1",
+  "description": "expo-screen-orientation wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, and Angular adapters. Orientation locking (lockAsync/lockPlatformAsync/unlockAsync), the current orientation and lock, and an auto-updating orientation-change hook/composable/service.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/screen-orientation"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/screen-orientation#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-screen-orientation": "57.0.1",
+    "expo-modules-core": "57.0.5"
+  },
+  "peerDependencies": {
+    "@symbiote-native/engine": ">=0.1.7",
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "vue": ">=3.5.0",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/react": "0.2.8",
+    "@symbiote-native/vue": "0.3.8"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "^22",
+    "@angular/compiler-cli": "^22",
+    "@angular/core": "^22",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "typescript": "~6.0.0",
+    "@symbiote-native/test-utils": "0.1.6",
+    "@symbiote-native/engine": "0.1.7",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/vue": "0.3.8",
+    "@symbiote-native/react": "0.2.8"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,26 @@
+// ScreenOrientationService is the Angular-only lifecycle half; the free functions and event
+// subscription plumbing all live in core, shared with React/Vue.
+export { ScreenOrientationService } from './services/screen-orientation.service';
+export {
+  lockAsync,
+  lockPlatformAsync,
+  unlockAsync,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  getPlatformOrientationLockAsync,
+  supportsOrientationLockAsync,
+  addOrientationChangeListener,
+  removeOrientationChangeListeners,
+  removeOrientationChangeListener,
+  Orientation,
+  OrientationLock,
+  SizeClassIOS,
+  WebOrientationLock,
+  WebOrientation,
+  type PlatformOrientationInfo,
+  type ScreenOrientationInfo,
+  type OrientationChangeEvent,
+  type OrientationChangeListener,
+  type ScreenOrientationState,
+  type EventSubscription,
+} from '../core';

package/src/angular/services/screen-orientation.service/index.ts

@@ -0,0 +1,45 @@
+import { effect, inject, Injectable, Injector, signal, type Signal } from '@angular/core';
+import {
+  addOrientationChangeListener,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  Orientation,
+  OrientationLock,
+  type ScreenOrientationState,
+} from '../../../core';
+
+// Angular twin of React's `useScreenOrientation` hook and Vue's `useScreenOrientation`
+// composable.
+//
+//   readonly screenOrientation = inject(ScreenOrientationService).connect();
+//   // template: {{ screenOrientation().orientation }}
+@Injectable({ providedIn: 'root' })
+export class ScreenOrientationService {
+  private readonly injector = inject(Injector);
+
+  connect(): Signal<ScreenOrientationState> {
+    const screenOrientation = signal<ScreenOrientationState>({
+      orientation: Orientation.UNKNOWN,
+      orientationLock: OrientationLock.UNKNOWN,
+    });
+
+    effect(
+      onCleanup => {
+        Promise.all([getOrientationAsync(), getOrientationLockAsync()]).then(
+          ([orientation, orientationLock]) =>
+            screenOrientation.set({ orientation, orientationLock }),
+        );
+        const subscription = addOrientationChangeListener(event =>
+          screenOrientation.set({
+            orientation: event.orientationInfo.orientation,
+            orientationLock: event.orientationLock,
+          }),
+        );
+        onCleanup(() => subscription.remove());
+      },
+      { injector: this.injector },
+    );
+
+    return screenOrientation.asReadonly();
+  }
+}

package/src/angular/services/screen-orientation.service/screen-orientation.service.test.ts

@@ -0,0 +1,101 @@
+// Co-located Angular-driven test (ADR 0025) for ScreenOrientationService. See network's
+// network-state.service.test.ts for the shared rationale.
+
+import '@angular/compiler';
+import { Component, inject, type Signal } from '@angular/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mount, unmount } from '@symbiote-native/angular';
+import { installFabric } from '@symbiote-native/test-utils';
+import { ScreenOrientationService } from './index';
+
+type IScreenOrientationState = { orientation: number; orientationLock: number };
+type IOrientationChangeEvent = {
+  orientationLock: number;
+  orientationInfo: { orientation: number };
+};
+
+const addListenerMock = vi.fn();
+const removeMock = vi.fn();
+const getOrientationAsyncMock = vi.fn(async () => 1);
+const getOrientationLockAsyncMock = vi.fn(async () => 0);
+
+vi.mock('../../../core', () => ({
+  addOrientationChangeListener: (listener: (event: IOrientationChangeEvent) => void) =>
+    addListenerMock(listener),
+  getOrientationAsync: () => getOrientationAsyncMock(),
+  getOrientationLockAsync: () => getOrientationLockAsyncMock(),
+  Orientation: { UNKNOWN: 0, PORTRAIT_UP: 1 },
+  OrientationLock: { UNKNOWN: 9, DEFAULT: 0 },
+}));
+
+const ROOT_TAG = 974;
+const fabric = installFabric();
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+let capturedResult: Signal<IScreenOrientationState> | undefined;
+let capturedListener: ((event: IOrientationChangeEvent) => void) | undefined;
+
+@Component({
+  selector: 'symbiote-screen-orientation-host',
+  standalone: true,
+  template: '',
+})
+class ScreenOrientationHost {
+  readonly screenOrientation = inject(ScreenOrientationService).connect();
+
+  constructor() {
+    capturedResult = this.screenOrientation;
+  }
+}
+
+beforeEach(() => {
+  capturedResult = undefined;
+  capturedListener = undefined;
+  getOrientationAsyncMock.mockResolvedValue(1);
+  getOrientationLockAsyncMock.mockResolvedValue(0);
+  addListenerMock.mockImplementation(listener => {
+    capturedListener = listener;
+    return { remove: removeMock };
+  });
+});
+
+afterEach(() => {
+  unmount(ROOT_TAG);
+  fabric.reset();
+  vi.clearAllMocks();
+});
+
+describe('ScreenOrientationService.connect', () => {
+  it('reports Orientation/OrientationLock UNKNOWN before the initial fetch resolves', async () => {
+    mount(ROOT_TAG, ScreenOrientationHost);
+
+    expect(capturedResult?.()).toEqual({ orientation: 0, orientationLock: 9 });
+  });
+
+  it('reports the fetched state once getOrientationAsync()/getOrientationLockAsync() resolve', async () => {
+    mount(ROOT_TAG, ScreenOrientationHost);
+    await tick();
+
+    expect(capturedResult?.()).toEqual({ orientation: 1, orientationLock: 0 });
+  });
+
+  it('updates the signal when the registered listener fires', async () => {
+    mount(ROOT_TAG, ScreenOrientationHost);
+    await tick();
+
+    if (capturedListener === undefined) throw new Error('addListener callback was not captured');
+    capturedListener({ orientationLock: 5, orientationInfo: { orientation: 3 } });
+
+    expect(capturedResult?.()).toEqual({ orientation: 3, orientationLock: 5 });
+  });
+
+  it('removes the subscription when the host component is unmounted', async () => {
+    mount(ROOT_TAG, ScreenOrientationHost);
+    await tick();
+
+    unmount(ROOT_TAG);
+    await tick();
+
+    expect(removeMock).toHaveBeenCalledOnce();
+  });
+});

package/src/core/index.ts

@@ -0,0 +1,25 @@
+export {
+  lockAsync,
+  lockPlatformAsync,
+  unlockAsync,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  getPlatformOrientationLockAsync,
+  supportsOrientationLockAsync,
+  addOrientationChangeListener,
+  removeOrientationChangeListeners,
+  removeOrientationChangeListener,
+} from './screen-orientation';
+export {
+  Orientation,
+  OrientationLock,
+  SizeClassIOS,
+  WebOrientationLock,
+  WebOrientation,
+  type PlatformOrientationInfo,
+  type ScreenOrientationInfo,
+  type OrientationChangeEvent,
+  type OrientationChangeListener,
+  type ScreenOrientationState,
+} from './types';
+export type { EventSubscription } from 'expo-modules-core';

package/src/core/native-module.ts

@@ -0,0 +1,36 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import type {
+  Orientation,
+  OrientationChangeEvent,
+  OrientationLock,
+  WebOrientationLock,
+} from './types';
+
+const EXPO_SCREEN_ORIENTATION_MODULE_NAME = 'ExpoScreenOrientation';
+
+// The platform-specific lock param/return shape is a genuine per-platform union (Android sends/
+// returns a numeric constant, iOS an Orientation[], web a WebOrientationLock string) — never `any`,
+// so screen-orientation.ts can narrow it with typeof/Array.isArray instead of casting.
+export type IPlatformOrientationParam = number | Orientation[] | WebOrientationLock;
+
+// Every method is optional for the same reason every sibling package's native module type is
+// (network, device, battery) — each call site in screen-orientation.ts checks for the method's
+// presence itself and throws an UnavailabilityError, matching upstream's own per-platform
+// capability checks rather than assuming the native module implements the whole surface.
+export type INativeScreenOrientationModule = {
+  lockAsync?(orientationLock: OrientationLock): Promise<void>;
+  lockPlatformAsync?(platformOrientationParam: IPlatformOrientationParam): Promise<void>;
+  getOrientationAsync?(): Promise<Orientation>;
+  getOrientationLockAsync?(): Promise<OrientationLock>;
+  getPlatformOrientationLockAsync?(): Promise<IPlatformOrientationParam>;
+  supportsOrientationLockAsync?(orientationLock: OrientationLock): Promise<boolean>;
+  addListener(
+    eventName: 'expoDidUpdateDimensions',
+    listener: (event: OrientationChangeEvent) => void,
+  ): EventSubscription;
+};
+
+export const expoScreenOrientation = requireNativeModule<INativeScreenOrientationModule>(
+  EXPO_SCREEN_ORIENTATION_MODULE_NAME,
+);

package/src/core/screen-orientation.test.ts

@@ -0,0 +1,307 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const FAKE_NATIVE_SCREEN_ORIENTATION = {
+  lockAsync: vi.fn(async () => undefined),
+  lockPlatformAsync: vi.fn(async () => undefined),
+  getOrientationAsync: vi.fn(async () => 1),
+  getOrientationLockAsync: vi.fn(async () => 0),
+  getPlatformOrientationLockAsync: vi.fn(async () => 0),
+  supportsOrientationLockAsync: vi.fn(async () => true),
+  addListener: vi.fn(() => ({ remove: vi.fn() })),
+};
+
+// The real ExpoScreenOrientation 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/network/src/core/network.test.ts uses.
+vi.mock('./native-module', () => ({
+  expoScreenOrientation: FAKE_NATIVE_SCREEN_ORIENTATION,
+}));
+
+// 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/cellular/src/core/cellular.test.ts uses. Platform.OS is mutable per-test.
+const fakePlatform = { OS: 'ios' as 'ios' | 'android' | 'web' };
+
+vi.mock('expo-modules-core', () => ({
+  Platform: fakePlatform,
+  UnavailabilityError: class UnavailabilityError extends Error {
+    constructor(moduleName: string, propertyName: string) {
+      super(`${propertyName} is not available on ${moduleName}`);
+    }
+  },
+}));
+
+// Android doesn't emit `expoDidUpdateDimensions` — the module piggybacks on RN's own Dimensions
+// change event there instead (see the function-level comment in screen-orientation.ts).
+vi.mock('react-native', () => ({
+  Dimensions: { addEventListener: vi.fn(() => ({ remove: vi.fn() })) },
+}));
+
+const {
+  lockAsync,
+  lockPlatformAsync,
+  unlockAsync,
+  getOrientationAsync,
+  getOrientationLockAsync,
+  getPlatformOrientationLockAsync,
+  supportsOrientationLockAsync,
+  addOrientationChangeListener,
+  removeOrientationChangeListeners,
+  removeOrientationChangeListener,
+} = await import('./screen-orientation');
+const { Orientation, OrientationLock, WebOrientationLock } = await import('./types');
+const { Dimensions } = await import('react-native');
+
+afterEach(() => {
+  fakePlatform.OS = 'ios';
+  vi.clearAllMocks();
+  removeOrientationChangeListeners();
+});
+
+describe('lockAsync', () => {
+  it('delegates to the native module', async () => {
+    await lockAsync(OrientationLock.PORTRAIT_UP);
+
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.lockAsync).toHaveBeenCalledWith(
+      OrientationLock.PORTRAIT_UP,
+    );
+  });
+
+  it('no-ops on OrientationLock.OTHER without calling the native module', async () => {
+    await lockAsync(OrientationLock.OTHER);
+
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.lockAsync).not.toHaveBeenCalled();
+  });
+
+  it('throws a TypeError on an invalid lock value', async () => {
+    // @ts-expect-error -- simulating a caller passing a bogus lock value
+    await expect(lockAsync(999)).rejects.toThrow('Invalid Orientation Lock');
+  });
+
+  it('throws UnavailabilityError when the native method is absent', async () => {
+    const { lockAsync: native } = FAKE_NATIVE_SCREEN_ORIENTATION;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_SCREEN_ORIENTATION.lockAsync = undefined;
+
+    await expect(lockAsync(OrientationLock.PORTRAIT_UP)).rejects.toThrow(
+      'lockAsync is not available on ScreenOrientation',
+    );
+
+    FAKE_NATIVE_SCREEN_ORIENTATION.lockAsync = native;
+  });
+});
+
+describe('lockPlatformAsync', () => {
+  it('forwards the Android numeric constant on Android', async () => {
+    fakePlatform.OS = 'android';
+
+    await lockPlatformAsync({ screenOrientationConstantAndroid: 1 });
+
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.lockPlatformAsync).toHaveBeenCalledWith(1);
+  });
+
+  it('forwards the iOS orientation array on iOS', async () => {
+    fakePlatform.OS = 'ios';
+
+    await lockPlatformAsync({ screenOrientationArrayIOS: [Orientation.PORTRAIT_UP] });
+
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.lockPlatformAsync).toHaveBeenCalledWith([
+      Orientation.PORTRAIT_UP,
+    ]);
+  });
+
+  it('forwards the web orientation lock on web', async () => {
+    fakePlatform.OS = 'web';
+
+    await lockPlatformAsync({ screenOrientationLockWeb: WebOrientationLock.LANDSCAPE });
+
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.lockPlatformAsync).toHaveBeenCalledWith(
+      WebOrientationLock.LANDSCAPE,
+    );
+  });
+
+  it('throws a TypeError on an invalid iOS orientation entry', async () => {
+    fakePlatform.OS = 'ios';
+
+    // @ts-expect-error -- simulating a caller passing a bogus orientation value
+    await expect(lockPlatformAsync({ screenOrientationArrayIOS: [999] })).rejects.toThrow(
+      'is not a valid Orientation',
+    );
+  });
+
+  it('throws a TypeError when no matching platform option is supplied', async () => {
+    fakePlatform.OS = 'ios';
+
+    await expect(lockPlatformAsync({})).rejects.toThrow(
+      'cannot be called with undefined option properties',
+    );
+  });
+
+  it('throws UnavailabilityError when the native method is absent', async () => {
+    const { lockPlatformAsync: native } = FAKE_NATIVE_SCREEN_ORIENTATION;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_SCREEN_ORIENTATION.lockPlatformAsync = undefined;
+
+    await expect(lockPlatformAsync({ screenOrientationConstantAndroid: 1 })).rejects.toThrow(
+      'lockPlatformAsync is not available on ScreenOrientation',
+    );
+
+    FAKE_NATIVE_SCREEN_ORIENTATION.lockPlatformAsync = native;
+  });
+});
+
+describe('unlockAsync', () => {
+  it('delegates to lockAsync with OrientationLock.DEFAULT', async () => {
+    await unlockAsync();
+
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.lockAsync).toHaveBeenCalledWith(OrientationLock.DEFAULT);
+  });
+});
+
+describe('getOrientationAsync', () => {
+  it('delegates to the native module', async () => {
+    await expect(getOrientationAsync()).resolves.toBe(1);
+  });
+
+  it('throws UnavailabilityError when the native method is absent', async () => {
+    const { getOrientationAsync: native } = FAKE_NATIVE_SCREEN_ORIENTATION;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_SCREEN_ORIENTATION.getOrientationAsync = undefined;
+
+    await expect(getOrientationAsync()).rejects.toThrow();
+
+    FAKE_NATIVE_SCREEN_ORIENTATION.getOrientationAsync = native;
+  });
+});
+
+describe('getOrientationLockAsync', () => {
+  it('delegates to the native module when present', async () => {
+    await expect(getOrientationLockAsync()).resolves.toBe(0);
+  });
+
+  it('falls back to the last lock set via lockAsync when the native method is absent', async () => {
+    await lockAsync(OrientationLock.LANDSCAPE);
+    const { getOrientationLockAsync: native } = FAKE_NATIVE_SCREEN_ORIENTATION;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_SCREEN_ORIENTATION.getOrientationLockAsync = undefined;
+
+    await expect(getOrientationLockAsync()).resolves.toBe(OrientationLock.LANDSCAPE);
+
+    FAKE_NATIVE_SCREEN_ORIENTATION.getOrientationLockAsync = native;
+  });
+});
+
+describe('getPlatformOrientationLockAsync', () => {
+  it('wraps a numeric native value as screenOrientationConstantAndroid on Android', async () => {
+    fakePlatform.OS = 'android';
+    FAKE_NATIVE_SCREEN_ORIENTATION.getPlatformOrientationLockAsync.mockResolvedValueOnce(1);
+
+    await expect(getPlatformOrientationLockAsync()).resolves.toEqual({
+      screenOrientationConstantAndroid: 1,
+    });
+  });
+
+  it('wraps an array native value as screenOrientationArrayIOS on iOS', async () => {
+    fakePlatform.OS = 'ios';
+    FAKE_NATIVE_SCREEN_ORIENTATION.getPlatformOrientationLockAsync.mockResolvedValueOnce([
+      Orientation.LANDSCAPE_LEFT,
+    ]);
+
+    await expect(getPlatformOrientationLockAsync()).resolves.toEqual({
+      screenOrientationArrayIOS: [Orientation.LANDSCAPE_LEFT],
+    });
+  });
+
+  it('wraps a string native value as screenOrientationLockWeb on web', async () => {
+    fakePlatform.OS = 'web';
+    FAKE_NATIVE_SCREEN_ORIENTATION.getPlatformOrientationLockAsync.mockResolvedValueOnce(
+      WebOrientationLock.ANY,
+    );
+
+    await expect(getPlatformOrientationLockAsync()).resolves.toEqual({
+      screenOrientationLockWeb: WebOrientationLock.ANY,
+    });
+  });
+});
+
+describe('supportsOrientationLockAsync', () => {
+  it('delegates to the native module', async () => {
+    await expect(supportsOrientationLockAsync(OrientationLock.PORTRAIT)).resolves.toBe(true);
+  });
+
+  it('throws a TypeError on an invalid lock value', async () => {
+    // @ts-expect-error -- simulating a caller passing a bogus lock value
+    await expect(supportsOrientationLockAsync(999)).rejects.toThrow('Invalid Orientation Lock');
+  });
+
+  it('throws UnavailabilityError when the native method is absent', async () => {
+    const { supportsOrientationLockAsync: native } = FAKE_NATIVE_SCREEN_ORIENTATION;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_SCREEN_ORIENTATION.supportsOrientationLockAsync = undefined;
+
+    await expect(supportsOrientationLockAsync(OrientationLock.PORTRAIT)).rejects.toThrow();
+
+    FAKE_NATIVE_SCREEN_ORIENTATION.supportsOrientationLockAsync = native;
+  });
+});
+
+describe('addOrientationChangeListener', () => {
+  it('subscribes through the native expoDidUpdateDimensions event on iOS', () => {
+    fakePlatform.OS = 'ios';
+    const listener = vi.fn();
+
+    addOrientationChangeListener(listener);
+
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.addListener).toHaveBeenCalledWith(
+      'expoDidUpdateDimensions',
+      expect.any(Function),
+    );
+    expect(Dimensions.addEventListener).not.toHaveBeenCalled();
+  });
+
+  it('subscribes through RN Dimensions.addEventListener on Android', () => {
+    fakePlatform.OS = 'android';
+    const listener = vi.fn();
+
+    addOrientationChangeListener(listener);
+
+    expect(Dimensions.addEventListener).toHaveBeenCalledWith('change', expect.any(Function));
+    expect(FAKE_NATIVE_SCREEN_ORIENTATION.addListener).not.toHaveBeenCalled();
+  });
+
+  it('throws a TypeError when the listener is not a function', () => {
+    // @ts-expect-error -- simulating a caller passing a non-function listener
+    expect(() => addOrientationChangeListener('not-a-function')).toThrow();
+  });
+});
+
+describe('removeOrientationChangeListener / removeOrientationChangeListeners', () => {
+  it('removes a single subscription', () => {
+    const subscription = addOrientationChangeListener(vi.fn());
+    const removeSpy = vi.spyOn(subscription, 'remove');
+
+    removeOrientationChangeListener(subscription);
+
+    expect(removeSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws a TypeError when passed an invalid subscription', () => {
+    // @ts-expect-error -- simulating a caller passing a bogus subscription
+    expect(() => removeOrientationChangeListener(null)).toThrow(
+      'Must pass in a valid subscription',
+    );
+  });
+
+  it('removes every registered subscription', () => {
+    const first = addOrientationChangeListener(vi.fn());
+    const second = addOrientationChangeListener(vi.fn());
+    const firstRemove = vi.spyOn(first, 'remove');
+    const secondRemove = vi.spyOn(second, 'remove');
+
+    removeOrientationChangeListeners();
+
+    expect(firstRemove).toHaveBeenCalledTimes(1);
+    expect(secondRemove).toHaveBeenCalledTimes(1);
+  });
+});