@symbiote-native/brightness 0.0.1

package/src/angular/services/permissions.service/index.ts

@@ -0,0 +1,37 @@
+// Angular twin of React's usePermissions hook and Vue's usePermissions composable.
+// `connect()` auto-fetches once (no ongoing subscription to clean up, so no Injector/effect
+// needed, unlike BatteryStateService) and returns a readonly signal; get()/request() are
+// imperative one-shot methods.
+//
+//   readonly status = inject(PermissionsService).connect();
+//   // template: {{ status()?.granted }}
+import { Injectable, signal, type Signal } from '@angular/core';
+import {
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  type PermissionResponse,
+} from '../../../core';
+
+@Injectable({ providedIn: 'root' })
+export class PermissionsService {
+  private readonly status = signal<PermissionResponse | null>(null);
+
+  connect(): Signal<PermissionResponse | null> {
+    if (this.status() === null) {
+      void this.get();
+    }
+    return this.status.asReadonly();
+  }
+
+  async get(): Promise<PermissionResponse> {
+    const response = await getPermissionsAsync();
+    this.status.set(response);
+    return response;
+  }
+
+  async request(): Promise<PermissionResponse> {
+    const response = await requestPermissionsAsync();
+    this.status.set(response);
+    return response;
+  }
+}

package/src/angular/services/permissions.service/permissions.service.test.ts

@@ -0,0 +1,107 @@
+// Co-located Angular-driven test (ADR 0025) for PermissionsService. See battery's
+// battery-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 { PermissionsService } from './index';
+import { PermissionStatus, type PermissionResponse } from '../../../core';
+
+const { getPermissionsAsync, requestPermissionsAsync } = vi.hoisted(() => ({
+  getPermissionsAsync: vi.fn(),
+  requestPermissionsAsync: vi.fn(),
+}));
+
+// Same enum-shaped-object mock trick packages/battery/src/angular/services/battery-state.service's
+// test uses for BatteryState.
+vi.mock('../../../core', () => ({
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  PermissionStatus: { GRANTED: 'granted', DENIED: 'denied', UNDETERMINED: 'undetermined' },
+}));
+
+const GRANTED: PermissionResponse = {
+  status: PermissionStatus.GRANTED,
+  granted: true,
+  canAskAgain: true,
+  expires: 'never',
+};
+const DENIED: PermissionResponse = {
+  status: PermissionStatus.DENIED,
+  granted: false,
+  canAskAgain: true,
+  expires: 'never',
+};
+
+const ROOT_TAG = 973;
+const fabric = installFabric();
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+let capturedStatus: Signal<PermissionResponse | null> | undefined;
+let capturedService: PermissionsService | undefined;
+
+@Component({
+  selector: 'symbiote-permissions-host',
+  standalone: true,
+  template: '',
+})
+class PermissionsHost {
+  readonly service = inject(PermissionsService);
+  readonly status = this.service.connect();
+
+  constructor() {
+    capturedStatus = this.status;
+    capturedService = this.service;
+  }
+}
+
+beforeEach(() => {
+  capturedStatus = undefined;
+  capturedService = undefined;
+  vi.clearAllMocks();
+  getPermissionsAsync.mockResolvedValue(GRANTED);
+  requestPermissionsAsync.mockResolvedValue(GRANTED);
+});
+
+afterEach(() => {
+  unmount(ROOT_TAG);
+  fabric.reset();
+});
+
+describe('PermissionsService.connect', () => {
+  it('reports null before the initial fetch resolves', () => {
+    mount(ROOT_TAG, PermissionsHost);
+
+    expect(capturedStatus?.()).toBe(null);
+  });
+
+  it('reports the fetched status once getPermissionsAsync() resolves', async () => {
+    mount(ROOT_TAG, PermissionsHost);
+    await tick();
+
+    expect(capturedStatus?.()).toEqual(GRANTED);
+    expect(getPermissionsAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('request() delegates to requestPermissionsAsync and updates the signal', async () => {
+    mount(ROOT_TAG, PermissionsHost);
+    await tick();
+
+    requestPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await capturedService?.request();
+
+    expect(capturedStatus?.()).toEqual(DENIED);
+  });
+
+  it('get() re-fetches and updates the signal', async () => {
+    mount(ROOT_TAG, PermissionsHost);
+    await tick();
+
+    getPermissionsAsync.mockResolvedValueOnce(DENIED);
+    await capturedService?.get();
+
+    expect(capturedStatus?.()).toEqual(DENIED);
+  });
+});

package/src/core/brightness.test.ts

@@ -0,0 +1,334 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const FAKE_NATIVE_BRIGHTNESS = {
+  getBrightnessAsync: vi.fn(async () => 0.5),
+  setBrightnessAsync: vi.fn(async () => undefined),
+  getSystemBrightnessAsync: vi.fn(async () => 0.6),
+  setSystemBrightnessAsync: vi.fn(async () => undefined),
+  restoreSystemBrightnessAsync: vi.fn(async () => undefined),
+  isUsingSystemBrightnessAsync: vi.fn(async () => true),
+  getSystemBrightnessModeAsync: vi.fn(async () => 1),
+  setSystemBrightnessModeAsync: vi.fn(async () => undefined),
+  getPermissionsAsync: vi.fn(async () => ({ status: 'granted', granted: true })),
+  requestPermissionsAsync: vi.fn(async () => ({ status: 'granted', granted: true })),
+  addListener: vi.fn(() => ({ remove: vi.fn() })),
+};
+
+// The real ExpoBrightness 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/battery/src/core/battery.test.ts and packages/haptics/src/core/haptics.test.ts use.
+vi.mock('./native-module', () => ({
+  expoBrightness: FAKE_NATIVE_BRIGHTNESS,
+}));
+
+// 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, since Platform.OS gates every
+// system-brightness branch here.
+const fakePlatform = { OS: 'ios' 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 {
+  isAvailableAsync,
+  getBrightnessAsync,
+  setBrightnessAsync,
+  getSystemBrightnessAsync,
+  setSystemBrightnessAsync,
+  restoreSystemBrightnessAsync,
+  isUsingSystemBrightnessAsync,
+  getSystemBrightnessModeAsync,
+  setSystemBrightnessModeAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  addBrightnessListener,
+} = await import('./brightness');
+const { BrightnessMode } = await import('./types');
+
+afterEach(() => {
+  fakePlatform.OS = 'ios';
+  vi.clearAllMocks();
+});
+
+describe('isAvailableAsync', () => {
+  it('resolves true when the native module implements getBrightnessAsync', async () => {
+    await expect(isAvailableAsync()).resolves.toBe(true);
+  });
+
+  it('resolves false when the native method is absent', async () => {
+    const { getBrightnessAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_BRIGHTNESS.getBrightnessAsync = undefined;
+
+    await expect(isAvailableAsync()).resolves.toBe(false);
+
+    FAKE_NATIVE_BRIGHTNESS.getBrightnessAsync = native;
+  });
+});
+
+describe('getBrightnessAsync', () => {
+  it('delegates to the native module', async () => {
+    await expect(getBrightnessAsync()).resolves.toBe(0.5);
+  });
+
+  it('throws an UnavailabilityError-shaped error when the native method is absent', async () => {
+    const { getBrightnessAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_BRIGHTNESS.getBrightnessAsync = undefined;
+
+    await expect(getBrightnessAsync()).rejects.toThrow(
+      'getBrightnessAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.getBrightnessAsync = native;
+  });
+});
+
+describe('setBrightnessAsync', () => {
+  it('delegates to the native module', async () => {
+    await setBrightnessAsync(0.4);
+    expect(FAKE_NATIVE_BRIGHTNESS.setBrightnessAsync).toHaveBeenCalledWith(0.4);
+  });
+
+  it('clamps a value above 1 down to 1', async () => {
+    await setBrightnessAsync(1.5);
+    expect(FAKE_NATIVE_BRIGHTNESS.setBrightnessAsync).toHaveBeenCalledWith(1);
+  });
+
+  it('clamps a value below 0 up to 0', async () => {
+    await setBrightnessAsync(-0.5);
+    expect(FAKE_NATIVE_BRIGHTNESS.setBrightnessAsync).toHaveBeenCalledWith(0);
+  });
+
+  it('throws a TypeError when the clamped value is NaN', async () => {
+    await expect(setBrightnessAsync(NaN)).rejects.toThrow(
+      'setBrightnessAsync cannot be called with NaN',
+    );
+    expect(FAKE_NATIVE_BRIGHTNESS.setBrightnessAsync).not.toHaveBeenCalled();
+  });
+
+  it('throws an UnavailabilityError-shaped error when the native method is absent', async () => {
+    const { setBrightnessAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating a platform where the native module has no such method
+    FAKE_NATIVE_BRIGHTNESS.setBrightnessAsync = undefined;
+
+    await expect(setBrightnessAsync(0.5)).rejects.toThrow(
+      'setBrightnessAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.setBrightnessAsync = native;
+  });
+});
+
+describe('getSystemBrightnessAsync', () => {
+  it('delegates to getBrightnessAsync on non-Android platforms', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getSystemBrightnessAsync()).resolves.toBe(0.5);
+    expect(FAKE_NATIVE_BRIGHTNESS.getSystemBrightnessAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    fakePlatform.OS = 'android';
+    await expect(getSystemBrightnessAsync()).resolves.toBe(0.6);
+  });
+
+  it('throws an UnavailabilityError-shaped error on Android when the native method is absent', async () => {
+    fakePlatform.OS = 'android';
+    const { getSystemBrightnessAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating an Android build missing this native method
+    FAKE_NATIVE_BRIGHTNESS.getSystemBrightnessAsync = undefined;
+
+    await expect(getSystemBrightnessAsync()).rejects.toThrow(
+      'getSystemBrightnessAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.getSystemBrightnessAsync = native;
+  });
+});
+
+describe('setSystemBrightnessAsync', () => {
+  it('delegates to setBrightnessAsync on non-Android platforms', async () => {
+    fakePlatform.OS = 'ios';
+    await setSystemBrightnessAsync(0.3);
+    expect(FAKE_NATIVE_BRIGHTNESS.setBrightnessAsync).toHaveBeenCalledWith(0.3);
+    expect(FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    fakePlatform.OS = 'android';
+    await setSystemBrightnessAsync(0.3);
+    expect(FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessAsync).toHaveBeenCalledWith(0.3);
+  });
+
+  it('clamps out-of-range values before delegating', async () => {
+    fakePlatform.OS = 'android';
+    await setSystemBrightnessAsync(2);
+    expect(FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessAsync).toHaveBeenCalledWith(1);
+  });
+
+  it('throws a TypeError when the clamped value is NaN', async () => {
+    await expect(setSystemBrightnessAsync(NaN)).rejects.toThrow(
+      'setSystemBrightnessAsync cannot be called with NaN',
+    );
+  });
+
+  it('throws an UnavailabilityError-shaped error on Android when the native method is absent', async () => {
+    fakePlatform.OS = 'android';
+    const { setSystemBrightnessAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating an Android build missing this native method
+    FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessAsync = undefined;
+
+    await expect(setSystemBrightnessAsync(0.5)).rejects.toThrow(
+      'setSystemBrightnessAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessAsync = native;
+  });
+});
+
+describe('restoreSystemBrightnessAsync', () => {
+  it('no-ops on non-Android platforms without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await restoreSystemBrightnessAsync();
+    expect(FAKE_NATIVE_BRIGHTNESS.restoreSystemBrightnessAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    fakePlatform.OS = 'android';
+    await restoreSystemBrightnessAsync();
+    expect(FAKE_NATIVE_BRIGHTNESS.restoreSystemBrightnessAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws an UnavailabilityError-shaped error on Android when the native method is absent', async () => {
+    fakePlatform.OS = 'android';
+    const { restoreSystemBrightnessAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating an Android build missing this native method
+    FAKE_NATIVE_BRIGHTNESS.restoreSystemBrightnessAsync = undefined;
+
+    await expect(restoreSystemBrightnessAsync()).rejects.toThrow(
+      'restoreSystemBrightnessAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.restoreSystemBrightnessAsync = native;
+  });
+});
+
+describe('isUsingSystemBrightnessAsync', () => {
+  it('resolves false on non-Android platforms without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(isUsingSystemBrightnessAsync()).resolves.toBe(false);
+    expect(FAKE_NATIVE_BRIGHTNESS.isUsingSystemBrightnessAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    fakePlatform.OS = 'android';
+    await expect(isUsingSystemBrightnessAsync()).resolves.toBe(true);
+  });
+
+  it('throws an UnavailabilityError-shaped error on Android when the native method is absent', async () => {
+    fakePlatform.OS = 'android';
+    const { isUsingSystemBrightnessAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating an Android build missing this native method
+    FAKE_NATIVE_BRIGHTNESS.isUsingSystemBrightnessAsync = undefined;
+
+    await expect(isUsingSystemBrightnessAsync()).rejects.toThrow(
+      'isUsingSystemBrightnessAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.isUsingSystemBrightnessAsync = native;
+  });
+});
+
+describe('getSystemBrightnessModeAsync', () => {
+  it('resolves UNKNOWN on non-Android platforms without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await expect(getSystemBrightnessModeAsync()).resolves.toBe(BrightnessMode.UNKNOWN);
+    expect(FAKE_NATIVE_BRIGHTNESS.getSystemBrightnessModeAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android', async () => {
+    fakePlatform.OS = 'android';
+    await expect(getSystemBrightnessModeAsync()).resolves.toBe(1);
+  });
+
+  it('throws an UnavailabilityError-shaped error on Android when the native method is absent', async () => {
+    fakePlatform.OS = 'android';
+    const { getSystemBrightnessModeAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating an Android build missing this native method
+    FAKE_NATIVE_BRIGHTNESS.getSystemBrightnessModeAsync = undefined;
+
+    await expect(getSystemBrightnessModeAsync()).rejects.toThrow(
+      'getSystemBrightnessModeAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.getSystemBrightnessModeAsync = native;
+  });
+});
+
+describe('setSystemBrightnessModeAsync', () => {
+  it('no-ops on non-Android platforms without calling the native module', async () => {
+    fakePlatform.OS = 'ios';
+    await setSystemBrightnessModeAsync(BrightnessMode.AUTOMATIC);
+    expect(FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessModeAsync).not.toHaveBeenCalled();
+  });
+
+  it('no-ops on Android when passed UNKNOWN', async () => {
+    fakePlatform.OS = 'android';
+    await setSystemBrightnessModeAsync(BrightnessMode.UNKNOWN);
+    expect(FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessModeAsync).not.toHaveBeenCalled();
+  });
+
+  it('delegates to the native module on Android with a concrete mode', async () => {
+    fakePlatform.OS = 'android';
+    await setSystemBrightnessModeAsync(BrightnessMode.MANUAL);
+    expect(FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessModeAsync).toHaveBeenCalledWith(
+      BrightnessMode.MANUAL,
+    );
+  });
+
+  it('throws an UnavailabilityError-shaped error on Android when the native method is absent', async () => {
+    fakePlatform.OS = 'android';
+    const { setSystemBrightnessModeAsync: native } = FAKE_NATIVE_BRIGHTNESS;
+    // @ts-expect-error -- simulating an Android build missing this native method
+    FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessModeAsync = undefined;
+
+    await expect(setSystemBrightnessModeAsync(BrightnessMode.MANUAL)).rejects.toThrow(
+      'setSystemBrightnessModeAsync is not available on expo-brightness',
+    );
+
+    FAKE_NATIVE_BRIGHTNESS.setSystemBrightnessModeAsync = native;
+  });
+});
+
+describe('getPermissionsAsync', () => {
+  it('passes straight through to the native module', async () => {
+    await expect(getPermissionsAsync()).resolves.toEqual({ status: 'granted', granted: true });
+  });
+});
+
+describe('requestPermissionsAsync', () => {
+  it('passes straight through to the native module', async () => {
+    await expect(requestPermissionsAsync()).resolves.toEqual({ status: 'granted', granted: true });
+  });
+});
+
+describe('addBrightnessListener', () => {
+  it('subscribes through the Expo.brightnessDidChange event name', () => {
+    const listener = vi.fn();
+    addBrightnessListener(listener);
+
+    expect(FAKE_NATIVE_BRIGHTNESS.addListener).toHaveBeenCalledWith(
+      'Expo.brightnessDidChange',
+      listener,
+    );
+  });
+});

package/src/core/brightness.ts

@@ -0,0 +1,155 @@
+// Hand-ported from .vendors/expo/packages/expo-brightness/src/Brightness.ts (sdk-57). The
+// system-brightness surface (mode, "using system brightness", restore) is Android-only —
+// upstream branches every one of those on `Platform.OS !== 'android'` before ever reaching the
+// native module, so those branches are preserved verbatim rather than guessed.
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+
+import { expoBrightness } from './native-module';
+import { BrightnessMode, type BrightnessEvent, type PermissionResponse } from './types';
+
+const NATIVE_MODULE_NAME = 'expo-brightness';
+
+function clampBrightness(brightnessValue: number, callerName: string): number {
+  const clamped = Math.max(0, Math.min(brightnessValue, 1));
+  if (Number.isNaN(clamped)) {
+    throw new TypeError(`${callerName} cannot be called with ${brightnessValue}`);
+  }
+  return clamped;
+}
+
+/** Whether the brightness API is available on the current device. */
+export async function isAvailableAsync(): Promise<boolean> {
+  return !!expoBrightness.getBrightnessAsync;
+}
+
+/** Gets the current brightness level of the device's main screen, between `0` and `1`. */
+export async function getBrightnessAsync(): Promise<number> {
+  if (!expoBrightness.getBrightnessAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getBrightnessAsync');
+  }
+  return expoBrightness.getBrightnessAsync();
+}
+
+/**
+ * Sets the current screen brightness. On iOS this only affects the screen while the app is
+ * foregrounded; on Android it persists until changed again.
+ */
+export async function setBrightnessAsync(brightnessValue: number): Promise<void> {
+  const clamped = clampBrightness(brightnessValue, 'setBrightnessAsync');
+  if (!expoBrightness.setBrightnessAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setBrightnessAsync');
+  }
+  await expoBrightness.setBrightnessAsync(clamped);
+}
+
+/**
+ * Gets the system-wide brightness. On iOS the app-local and system brightness are the same
+ * value, so this delegates to `getBrightnessAsync`.
+ * @platform android
+ */
+export async function getSystemBrightnessAsync(): Promise<number> {
+  if (Platform.OS !== 'android') {
+    return getBrightnessAsync();
+  }
+  if (!expoBrightness.getSystemBrightnessAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getSystemBrightnessAsync');
+  }
+  return expoBrightness.getSystemBrightnessAsync();
+}
+
+/**
+ * Sets the system-wide brightness. On iOS this delegates to `setBrightnessAsync`, since there is
+ * no separate system-level brightness to set.
+ * @platform android
+ */
+export async function setSystemBrightnessAsync(brightnessValue: number): Promise<void> {
+  const clamped = clampBrightness(brightnessValue, 'setSystemBrightnessAsync');
+  if (Platform.OS !== 'android') {
+    return setBrightnessAsync(clamped);
+  }
+  if (!expoBrightness.setSystemBrightnessAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setSystemBrightnessAsync');
+  }
+  await expoBrightness.setSystemBrightnessAsync(clamped);
+}
+
+/**
+ * Resets the system brightness to the value it had before this app started controlling it. A
+ * no-op on every platform except Android.
+ * @platform android
+ */
+export async function restoreSystemBrightnessAsync(): Promise<void> {
+  if (Platform.OS !== 'android') {
+    return;
+  }
+  if (!expoBrightness.restoreSystemBrightnessAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'restoreSystemBrightnessAsync');
+  }
+  await expoBrightness.restoreSystemBrightnessAsync();
+}
+
+/**
+ * Whether the app is currently controlling the system brightness (as opposed to only its own
+ * window's brightness). Always `false` on every platform except Android.
+ * @platform android
+ */
+export async function isUsingSystemBrightnessAsync(): Promise<boolean> {
+  if (Platform.OS !== 'android') {
+    return false;
+  }
+  if (!expoBrightness.isUsingSystemBrightnessAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'isUsingSystemBrightnessAsync');
+  }
+  return expoBrightness.isUsingSystemBrightnessAsync();
+}
+
+/**
+ * Gets the system brightness mode (`AUTOMATIC` / `MANUAL`). Always resolves `UNKNOWN` on every
+ * platform except Android.
+ * @platform android
+ */
+export async function getSystemBrightnessModeAsync(): Promise<BrightnessMode> {
+  if (Platform.OS !== 'android') {
+    return BrightnessMode.UNKNOWN;
+  }
+  if (!expoBrightness.getSystemBrightnessModeAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getSystemBrightnessModeAsync');
+  }
+  return expoBrightness.getSystemBrightnessModeAsync();
+}
+
+/**
+ * Sets the system brightness mode. A no-op on every platform except Android, and also a no-op
+ * when passed `BrightnessMode.UNKNOWN` (there is nothing meaningful to set it to).
+ * @platform android
+ */
+export async function setSystemBrightnessModeAsync(brightnessMode: BrightnessMode): Promise<void> {
+  if (Platform.OS !== 'android' || brightnessMode === BrightnessMode.UNKNOWN) {
+    return;
+  }
+  if (!expoBrightness.setSystemBrightnessModeAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setSystemBrightnessModeAsync');
+  }
+  await expoBrightness.setSystemBrightnessModeAsync(brightnessMode);
+}
+
+/** Checks user's permissions for accessing the system brightness. */
+export async function getPermissionsAsync(): Promise<PermissionResponse> {
+  return expoBrightness.getPermissionsAsync();
+}
+
+/** Asks the user for permission to access the system brightness. */
+export async function requestPermissionsAsync(): Promise<PermissionResponse> {
+  return expoBrightness.requestPermissionsAsync();
+}
+
+/**
+ * Subscribes to brightness changes. Only fires on iOS — never on Android or web.
+ * @platform ios
+ */
+export function addBrightnessListener(
+  listener: (event: BrightnessEvent) => void,
+): EventSubscription {
+  return expoBrightness.addListener('Expo.brightnessDidChange', listener);
+}

package/src/core/index.ts

@@ -0,0 +1,22 @@
+export {
+  isAvailableAsync,
+  getBrightnessAsync,
+  setBrightnessAsync,
+  getSystemBrightnessAsync,
+  setSystemBrightnessAsync,
+  restoreSystemBrightnessAsync,
+  isUsingSystemBrightnessAsync,
+  getSystemBrightnessModeAsync,
+  setSystemBrightnessModeAsync,
+  getPermissionsAsync,
+  requestPermissionsAsync,
+  addBrightnessListener,
+} from './brightness';
+export {
+  BrightnessMode,
+  PermissionStatus,
+  type BrightnessEvent,
+  type PermissionExpiration,
+  type PermissionResponse,
+} from './types';
+export type { EventSubscription } from 'expo-modules-core';

package/src/core/native-module.ts

@@ -0,0 +1,32 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import type { BrightnessEvent, BrightnessMode, PermissionResponse } from './types';
+
+const EXPO_BRIGHTNESS_MODULE_NAME = 'ExpoBrightness';
+
+// Every system-brightness / brightness-mode method is optional and Android-only — each call
+// site checks for its presence before calling through and throws an UnavailabilityError itself,
+// matching upstream's own per-platform capability checks rather than assuming the native module
+// implements the whole surface (same convention as packages/local-auth/src/core/native-module.ts
+// and packages/haptics/src/core/native-module.ts). getBrightnessAsync/setBrightnessAsync are
+// also optional so isAvailableAsync can probe for them without throwing.
+export type INativeBrightnessModule = {
+  getBrightnessAsync?(): Promise<number>;
+  setBrightnessAsync?(value: number): Promise<void>;
+  getSystemBrightnessAsync?(): Promise<number>;
+  setSystemBrightnessAsync?(value: number): Promise<void>;
+  restoreSystemBrightnessAsync?(): Promise<void>;
+  isUsingSystemBrightnessAsync?(): Promise<boolean>;
+  getSystemBrightnessModeAsync?(): Promise<BrightnessMode>;
+  setSystemBrightnessModeAsync?(mode: BrightnessMode): Promise<void>;
+  getPermissionsAsync(): Promise<PermissionResponse>;
+  requestPermissionsAsync(): Promise<PermissionResponse>;
+  addListener(
+    eventName: 'Expo.brightnessDidChange',
+    listener: (event: BrightnessEvent) => void,
+  ): EventSubscription;
+};
+
+export const expoBrightness = requireNativeModule<INativeBrightnessModule>(
+  EXPO_BRIGHTNESS_MODULE_NAME,
+);