@symbiote-native/brightness 0.0.1 → 0.2.0

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

@@ -5,6 +5,11 @@
 //
 //   readonly status = inject(PermissionsService).connect();
 //   // template: {{ status()?.granted }}
+//
+// The auto-fetch has nobody to reject to, so its failure lands in the `error` signal instead of
+// escaping as an unhandled rejection: a null status with a non-null error is how a consumer tells
+// "the fetch failed" from "not fetched yet". get()/request() still reject to their direct caller —
+// only the automatic call is made safe.
 import { Injectable, signal, type Signal } from '@angular/core';
 import {
   getPermissionsAsync,
@@ -15,10 +20,21 @@ import {
 @Injectable({ providedIn: 'root' })
 export class PermissionsService {
   private readonly status = signal<PermissionResponse | null>(null);
+  private readonly fetchError = signal<Error | null>(null);
+  private isAutoFetchStarted = false;
+
+  /** Why the auto-fetch left `status` at null. Cleared by the next successful get()/request(). */
+  readonly error: Signal<Error | null> = this.fetchError.asReadonly();
 
   connect(): Signal<PermissionResponse | null> {
-    if (this.status() === null) {
-      void this.get();
+    // Latched rather than guarded on `status() === null`: a failed fetch leaves status null
+    // forever, so the old guard turned every later connect() into another native call — unbounded
+    // once connect() is reached from a change-detected expression instead of a field initializer.
+    if (!this.isAutoFetchStarted) {
+      this.isAutoFetchStarted = true;
+      this.get().catch((cause: unknown) => {
+        this.fetchError.set(cause instanceof Error ? cause : new Error(String(cause)));
+      });
     }
     return this.status.asReadonly();
   }
@@ -26,12 +42,14 @@ export class PermissionsService {
   async get(): Promise<PermissionResponse> {
     const response = await getPermissionsAsync();
     this.status.set(response);
+    this.fetchError.set(null);
     return response;
   }
 
   async request(): Promise<PermissionResponse> {
     const response = await requestPermissionsAsync();
     this.status.set(response);
+    this.fetchError.set(null);
     return response;
   }
 }

package/src/core/brightness.ts

@@ -90,8 +90,11 @@ export async function restoreSystemBrightnessAsync(): Promise<void> {
 }
 
 /**
- * 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.
+ * Whether the activity's window has NO brightness override of its own, so the system-wide
+ * brightness is what the screen shows. Native reads `screenBrightness == BRIGHTNESS_OVERRIDE_NONE`,
+ * which cannot tell "the app set the system value" apart from "the app never touched brightness" —
+ * it reports only that `setBrightnessAsync` is not currently overriding this window.
+ * Always `false` on every platform except Android.
  * @platform android
  */
 export async function isUsingSystemBrightnessAsync(): Promise<boolean> {

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

@@ -2,6 +2,11 @@
 // the current permission status on mount, then exposes get/request as imperative callbacks.
 // Mirrors the shape @symbiote-native/cellular's own usePermissions ships in parallel, so both
 // stay byte-for-byte consistent.
+//
+// The mount fetch has nobody to reject to, so its failure lands in the 4th tuple slot (`error`)
+// instead of escaping as an unhandled rejection: a null status with a non-null error is how a
+// consumer tells "the fetch failed" from "not fetched yet". get()/request() still reject to their
+// direct caller — only the automatic call is made safe.
 import { useCallback, useEffect, useRef, useState } from 'react';
 import {
   getPermissionsAsync,
@@ -13,29 +18,39 @@ export function usePermissions(): [
   PermissionResponse | null,
   () => Promise<PermissionResponse>,
   () => Promise<PermissionResponse>,
+  Error | null,
 ] {
   const isMounted = useRef(true);
   const [status, setStatus] = useState<PermissionResponse | null>(null);
+  const [error, setError] = useState<Error | null>(null);
 
   const getPermission = useCallback(async () => {
     const response = await getPermissionsAsync();
-    if (isMounted.current) setStatus(response);
+    if (isMounted.current) {
+      setStatus(response);
+      setError(null);
+    }
     return response;
   }, []);
 
   const requestPermission = useCallback(async () => {
     const response = await requestPermissionsAsync();
-    if (isMounted.current) setStatus(response);
+    if (isMounted.current) {
+      setStatus(response);
+      setError(null);
+    }
     return response;
   }, []);
 
   useEffect(() => {
     isMounted.current = true;
-    void getPermission();
+    getPermission().catch((cause: unknown) => {
+      if (isMounted.current) setError(cause instanceof Error ? cause : new Error(String(cause)));
+    });
     return () => {
       isMounted.current = false;
     };
   }, [getPermission]);
 
-  return [status, requestPermission, getPermission];
+  return [status, requestPermission, getPermission, error];
 }

package/src/react/index.ts

@@ -4,23 +4,4 @@
 // mirrors the lifecycle-bucket naming convention of adapters/react/src/hooks.
 
 export { usePermissions } from './hooks/use-permissions';
-export {
-  isAvailableAsync,
-  getBrightnessAsync,
-  setBrightnessAsync,
-  getSystemBrightnessAsync,
-  setSystemBrightnessAsync,
-  restoreSystemBrightnessAsync,
-  isUsingSystemBrightnessAsync,
-  getSystemBrightnessModeAsync,
-  setSystemBrightnessModeAsync,
-  getPermissionsAsync,
-  requestPermissionsAsync,
-  addBrightnessListener,
-  BrightnessMode,
-  PermissionStatus,
-  type BrightnessEvent,
-  type PermissionExpiration,
-  type PermissionResponse,
-  type EventSubscription,
-} from '../core';
+export * from '../core';

package/src/svelte/index.ts

@@ -0,0 +1,7 @@
+// @symbiote-native/brightness/svelte: the Svelte entry over the framework-agnostic core. Same
+// reasoning as the React and Vue entries — only the permission surface gets a lifecycle rune,
+// every other export is a plain re-export — mirrors the lifecycle-bucket naming convention of
+// adapters/svelte/src/runes (never `hooks/`/`composables/`, those are React's and Vue's terms).
+
+export { usePermissions } from './runes/use-permissions.svelte';
+export * from '../core';

package/src/svelte/runes/use-permissions.svelte.ts

@@ -0,0 +1,65 @@
+// Svelte lifecycle wiring over the framework-agnostic core (core/brightness.ts) — auto-fetches
+// the current permission status on mount, then exposes get/request as imperative callbacks. The
+// Svelte twin of vue/composables/use-permissions and react/hooks/use-permissions.
+//
+// `.svelte.ts` (not `.ts`): runes ($state/$effect) are only usable in a file with this extension
+// outside an actual `.svelte` component. `runes/` is Svelte's own term for the bucket React calls
+// `hooks/` and Vue calls `composables/` — see adapters/svelte/src/runes.
+//
+// Vue's onMounted collapses into a `$effect` with no teardown (there is no ongoing subscription
+// here, just a one-shot get). The effect only WRITES `status` (through `get()`), never reads it,
+// so its dependency set stays empty and it fires exactly once on mount.
+//
+// `status` comes back as a GETTER on the returned object rather than a raw `$state` variable:
+// Svelte 5 reactivity is lexically scoped to the declaring module, so a raw `let x = $state(...)`
+// handed out of a plain function arrives dead at the caller. Reading `.status` is the Svelte
+// equivalent of unwrapping Vue's `Ref` via `.value`.
+//
+// The mount fetch has nobody to reject to, so its failure lands in `error` (a second boxed getter,
+// same reason as `status`) instead of escaping as an unhandled rejection: a null status with a
+// non-null error is how a consumer tells "the fetch failed" from "not fetched yet".
+// get()/request() still reject to their direct caller — only the automatic call is made safe.
+import { getPermissionsAsync, requestPermissionsAsync, type PermissionResponse } from '../../core';
+
+export function usePermissions(): {
+  readonly status: PermissionResponse | null;
+  readonly error: Error | null;
+  request: () => Promise<PermissionResponse>;
+  get: () => Promise<PermissionResponse>;
+} {
+  let status = $state<PermissionResponse | null>(null);
+  let error = $state<Error | null>(null);
+
+  const get = async (): Promise<PermissionResponse> => {
+    const response = await getPermissionsAsync();
+    status = response;
+    error = null;
+    return response;
+  };
+
+  const request = async (): Promise<PermissionResponse> => {
+    const response = await requestPermissionsAsync();
+    status = response;
+    error = null;
+    return response;
+  };
+
+  $effect(() => {
+    // The catch runs after the effect has settled, so writing `error` there adds no dependency and
+    // the effect still fires exactly once.
+    get().catch((cause: unknown) => {
+      error = cause instanceof Error ? cause : new Error(String(cause));
+    });
+  });
+
+  return {
+    get status(): PermissionResponse | null {
+      return status;
+    },
+    get error(): Error | null {
+      return error;
+    },
+    request,
+    get,
+  };
+}

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,6 @@
+// Pulls in svelte's ambient global declarations ($state/$effect/...) for this package's tsc
+// program. adapters/svelte gets these for free because render.ts does a real value import from
+// 'svelte' (any file in a program importing a module loads its ambient globals for the whole
+// program); this package has no such import, so a triple-slash reference does the same job
+// explicitly rather than relying on an incidental side-effect.
+/// <reference types="svelte" />

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

@@ -2,6 +2,11 @@
 // current permission status on mount (mirrors use-battery-level's onMounted/onUnmounted style,
 // but there is no ongoing subscription to tear down here, just a one-shot get), then exposes
 // get/request as imperative callbacks.
+//
+// The mount fetch has nobody to reject to, so its failure lands in the `error` ref instead of
+// escaping as an unhandled rejection: a null status with a non-null error is how a consumer tells
+// "the fetch failed" from "not fetched yet". get()/request() still reject to their direct caller —
+// only the automatic call is made safe.
 import { onMounted, ref, type Ref } from '@vue/runtime-core';
 import {
   getPermissionsAsync,
@@ -11,26 +16,32 @@ import {
 
 export function usePermissions(): {
   status: Ref<PermissionResponse | null>;
+  error: Ref<Error | null>;
   request: () => Promise<PermissionResponse>;
   get: () => Promise<PermissionResponse>;
 } {
   const status = ref<PermissionResponse | null>(null);
+  const error = ref<Error | null>(null);
 
   const get = async () => {
     const response = await getPermissionsAsync();
     status.value = response;
+    error.value = null;
     return response;
   };
 
   const request = async () => {
     const response = await requestPermissionsAsync();
     status.value = response;
+    error.value = null;
     return response;
   };
 
   onMounted(() => {
-    void get();
+    get().catch((cause: unknown) => {
+      error.value = cause instanceof Error ? cause : new Error(String(cause));
+    });
   });
 
-  return { status, request, get };
+  return { status, error, request, get };
 }

package/src/vue/index.ts

@@ -4,23 +4,4 @@
 // adapters/vue/src/composables (never `hooks/`, that's React's term).
 
 export { usePermissions } from './composables/use-permissions';
-export {
-  isAvailableAsync,
-  getBrightnessAsync,
-  setBrightnessAsync,
-  getSystemBrightnessAsync,
-  setSystemBrightnessAsync,
-  restoreSystemBrightnessAsync,
-  isUsingSystemBrightnessAsync,
-  getSystemBrightnessModeAsync,
-  setSystemBrightnessModeAsync,
-  getPermissionsAsync,
-  requestPermissionsAsync,
-  addBrightnessListener,
-  BrightnessMode,
-  PermissionStatus,
-  type BrightnessEvent,
-  type PermissionExpiration,
-  type PermissionResponse,
-  type EventSubscription,
-} from '../core';
+export * from '../core';

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

@@ -1,107 +0,0 @@
-// 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);
-  });
-});