@ankhorage/permissions 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @ankhorage/permissions
+
+## 0.1.0
+
+### Minor Changes
+
+- 90d6509: Implement the initial standalone cross-platform permission runtime.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ankhorage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+<!-- markdownlint-disable MD013 MD033 -->
+<!-- This file is generated by Paradox. Do not edit manually. -->
+
+# PERMISSIONS
+
+![license: MIT](././paradox/badges/license.svg) ![npm: v0.0.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+
+Cross-platform permission registry and runtime helpers for TypeScript apps, with unified request/check APIs for camera, media, location, notifications, microphone, etc. and web/native capabilities.
+
+## Generated documentation
+
+- [Interactive documentation app](././paradox/index.html)
+- [Public API reference](././paradox/exports.md)
+- [Component registry](././paradox/components.md)
+- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
+- [Module relationships](././paradox/diagrams/module-relationships.mmd)
+- [Export graph](././paradox/diagrams/export-graph.mmd)
+- [assertKnownPermission sequence](././paradox/diagrams/sequences/assert-known-permission.mmd)
+- [createFakePermissionClient sequence](././paradox/diagrams/sequences/create-fake-permission-client.mmd)
+- [createWebPermissionClient sequence](././paradox/diagrams/sequences/create-web-permission-client.mmd)
+- [getPermissionDefinition sequence](././paradox/diagrams/sequences/get-permission-definition.mmd)
+- [normalizePermissionState sequence](././paradox/diagrams/sequences/normalize-permission-state.mmd)
+- [PermissionsProvider sequence](././paradox/diagrams/sequences/permissions-provider.mmd)
+- [usePermission sequence](././paradox/diagrams/sequences/use-permission.mmd)
+- [usePermissions sequence](././paradox/diagrams/sequences/use-permissions.mmd)
+
+## Public API
+
+### Utilities
+
+<details>
+<summary>createFakePermissionClient</summary>
+
+```ts
+createFakePermissionClient(options?: FakePermissionClientOptions) => FakePermissionClient
+```
+
+Creates a deterministic in-memory client for tests and examples.
+
+Fake clients make permission flows testable without native devices, browser
+prompts, simulators, or network access.
+
+```ts
+const client = createFakePermissionClient({
+  initialStates: [{ permission: Permission.Camera, status: 'denied' }],
+});
+await client.request(Permission.Camera);
+```
+
+Module: `src/testing/index.ts`
+Source: `src/testing/index.ts:63:1`
+Related symbols: `FakePermissionClient`, `FakePermissionClientOptions`
+
+</details>
+
+<details>
+<summary>createPermissionManager</summary>
+
+```ts
+createPermissionManager(client: PermissionClient) => PermissionManager
+```
+
+Wraps a client with registry validation and normalized results.
+
+Runtime permissions and build-time native configuration are separate concerns.
+This manager checks or requests permissions through a client, but it does not
+generate iOS usage descriptions, Android manifest entries, or Expo config
+plugins.
+
+```ts
+const permissions = createPermissionManager(client);
+const camera = await permissions.getStatus(Permission.Camera);
+const requested = camera.granted ? camera : await permissions.request(Permission.Camera);
+```
+
+Module: `src/manager/createPermissionManager.ts`
+Source: `src/manager/createPermissionManager.ts:32:1`
+Related symbols: `PermissionClient`, `PermissionManager`
+
+</details>
+
+<details>
+<summary>createWebPermissionClient</summary>
+
+```ts
+createWebPermissionClient(options?: WebPermissionClientOptions) => PermissionClient
+```
+
+Creates a browser permission client using guarded structural globals.
+
+Unsupported web APIs resolve to `status: 'unavailable'`. The adapter does not
+import DOM types and does not assume it is running in a browser.
+
+Module: `src/web/index.ts`
+Source: `src/web/index.ts:78:1`
+Related symbols: `PermissionClient`, `WebPermissionClientOptions`
+
+</details>
+
+<details>
+<summary>Permission</summary>
+
+Common runtime permissions supported by the registry.
+
+The registry is intentionally platform-neutral. Adapters translate each
+permission into whatever a browser, React Native app, Expo app, or test
+environment can actually check or request.
+
+Module: `src/registry/permissions.ts`
+Source: `src/registry/permissions.ts:9:1`
+
+</details>
+
+<details>
+<summary>PermissionsProvider</summary>
+
+```ts
+PermissionsProvider({
+  children,
+  client,
+  manager,
+}: PermissionsProviderProps) => ReactNode
+```
+
+Provides a permission manager to React hooks.
+
+React helpers are framework-neutral. They depend on React only and do not
+import browser, Expo, or React Native permission APIs.
+
+Related types: `PermissionsProviderProps`
+
+<details>
+<summary>Props</summary>
+
+| Prop     | Type                             | Required | Default | Description |
+| -------- | -------------------------------- | -------- | ------- | ----------- |
+| children | `ReactNode \| undefined`         | no       | —       |             |
+| client   | `PermissionClient \| undefined`  | no       | —       |             |
+| manager  | `PermissionManager \| undefined` | no       | —       |             |
+
+</details>
+
+</details>

package/dist/client/types.d.ts

@@ -0,0 +1,19 @@
+import type { Permission } from '../registry/permissions';
+import type { PermissionState } from '../state/permissionState';
+/***
+ * Adapter-neutral interface for runtime permission checks and requests.
+ *
+ * @usage
+ * ```ts
+ * const state = await client.getStatus(Permission.Camera);
+ * if (!state.granted) {
+ *   await client.request(Permission.Camera);
+ * }
+ * ```
+ */
+export interface PermissionClient {
+    getStatus(permission: Permission): Promise<PermissionState>;
+    request(permission: Permission): Promise<PermissionState>;
+    openSettings?(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5D,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1D,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}

package/dist/client/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Permission } from '../registry/permissions';\nimport type { PermissionState } from '../state/permissionState';\n\n/***\n * Adapter-neutral interface for runtime permission checks and requests.\n *\n * @usage\n * ```ts\n * const state = await client.getStatus(Permission.Camera);\n * if (!state.granted) {\n *   await client.request(Permission.Camera);\n * }\n * ```\n */\nexport interface PermissionClient {\n  getStatus(permission: Permission): Promise<PermissionState>;\n  request(permission: Permission): Promise<PermissionState>;\n  openSettings?(): Promise<void>;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { PermissionClient } from './client/types';
+export type { PermissionManager } from './manager/createPermissionManager';
+export { createPermissionManager } from './manager/createPermissionManager';
+export type { PermissionHookResult, PermissionsProviderProps, UsePermissionOptions, } from './react/index';
+export { PermissionsProvider, usePermission, usePermissions } from './react/index';
+export type { PermissionDefinition, PermissionEnvironment } from './registry/permissions';
+export { assertKnownPermission, getPermissionDefinition, isPermission, Permission, PERMISSION_REGISTRY, PERMISSIONS, } from './registry/permissions';
+export type { PermissionState, PermissionStatus } from './state/permissionState';
+export { createPermissionState, isPermissionStatus, normalizePermissionState, PERMISSION_STATUSES, } from './state/permissionState';
+export type { FakePermissionClient, FakePermissionClientOptions, FakePermissionStateSeed, } from './testing/index';
+export { createFakePermissionClient } from './testing/index';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,YAAY,EACV,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnF,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createPermissionManager } from './manager/createPermissionManager';
+export { PermissionsProvider, usePermission, usePermissions } from './react/index';
+export { assertKnownPermission, getPermissionDefinition, isPermission, Permission, PERMISSION_REGISTRY, PERMISSIONS, } from './registry/permissions';
+export { createPermissionState, isPermissionStatus, normalizePermissionState, PERMISSION_STATUSES, } from './state/permissionState';
+export { createFakePermissionClient } from './testing/index';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAM5E,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["export type { PermissionClient } from './client/types';\nexport type { PermissionManager } from './manager/createPermissionManager';\nexport { createPermissionManager } from './manager/createPermissionManager';\nexport type {\n  PermissionHookResult,\n  PermissionsProviderProps,\n  UsePermissionOptions,\n} from './react/index';\nexport { PermissionsProvider, usePermission, usePermissions } from './react/index';\nexport type { PermissionDefinition, PermissionEnvironment } from './registry/permissions';\nexport {\n  assertKnownPermission,\n  getPermissionDefinition,\n  isPermission,\n  Permission,\n  PERMISSION_REGISTRY,\n  PERMISSIONS,\n} from './registry/permissions';\nexport type { PermissionState, PermissionStatus } from './state/permissionState';\nexport {\n  createPermissionState,\n  isPermissionStatus,\n  normalizePermissionState,\n  PERMISSION_STATUSES,\n} from './state/permissionState';\nexport type {\n  FakePermissionClient,\n  FakePermissionClientOptions,\n  FakePermissionStateSeed,\n} from './testing/index';\nexport { createFakePermissionClient } from './testing/index';\n"]}

package/dist/manager/createPermissionManager.d.ts

@@ -0,0 +1,31 @@
+import type { PermissionClient } from '../client/types';
+import { type Permission } from '../registry/permissions';
+import { type PermissionState } from '../state/permissionState';
+/***
+ * Public manager returned by `createPermissionManager`.
+ */
+export interface PermissionManager {
+    getStatus(permission: Permission): Promise<PermissionState>;
+    request(permission: Permission): Promise<PermissionState>;
+    openSettings?(): Promise<void>;
+}
+/***
+ * Wraps a client with registry validation and normalized results.
+ *
+ * @readme
+ * Runtime permissions and build-time native configuration are separate concerns.
+ * This manager checks or requests permissions through a client, but it does not
+ * generate iOS usage descriptions, Android manifest entries, or Expo config
+ * plugins.
+ *
+ * @usage
+ * ```ts
+ * const permissions = createPermissionManager(client);
+ * const camera = await permissions.getStatus(Permission.Camera);
+ * const requested = camera.granted
+ *   ? camera
+ *   : await permissions.request(Permission.Camera);
+ * ```
+ */
+export declare function createPermissionManager(client: PermissionClient): PermissionManager;
+//# sourceMappingURL=createPermissionManager.d.ts.map

package/dist/manager/createPermissionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPermissionManager.d.ts","sourceRoot":"","sources":["../../src/manager/createPermissionManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAyB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE1F;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5D,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1D,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,CAsBnF"}

package/dist/manager/createPermissionManager.js

@@ -0,0 +1,39 @@
+import { assertKnownPermission } from '../registry/permissions';
+import { normalizePermissionState } from '../state/permissionState';
+/***
+ * Wraps a client with registry validation and normalized results.
+ *
+ * @readme
+ * Runtime permissions and build-time native configuration are separate concerns.
+ * This manager checks or requests permissions through a client, but it does not
+ * generate iOS usage descriptions, Android manifest entries, or Expo config
+ * plugins.
+ *
+ * @usage
+ * ```ts
+ * const permissions = createPermissionManager(client);
+ * const camera = await permissions.getStatus(Permission.Camera);
+ * const requested = camera.granted
+ *   ? camera
+ *   : await permissions.request(Permission.Camera);
+ * ```
+ */
+export function createPermissionManager(client) {
+    const manager = {
+        async getStatus(permission) {
+            const knownPermission = assertKnownPermission(permission);
+            const state = await client.getStatus(knownPermission);
+            return normalizePermissionState(knownPermission, state);
+        },
+        async request(permission) {
+            const knownPermission = assertKnownPermission(permission);
+            const state = await client.request(knownPermission);
+            return normalizePermissionState(knownPermission, state);
+        },
+    };
+    if (client.openSettings !== undefined) {
+        manager.openSettings = () => client.openSettings?.() ?? Promise.resolve();
+    }
+    return manager;
+}
+//# sourceMappingURL=createPermissionManager.js.map

package/dist/manager/createPermissionManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createPermissionManager.js","sourceRoot":"","sources":["../../src/manager/createPermissionManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAmB,MAAM,yBAAyB,CAAC;AACjF,OAAO,EAAE,wBAAwB,EAAwB,MAAM,0BAA0B,CAAC;AAW1F;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAwB;IAC9D,MAAM,OAAO,GAAsB;QACjC,KAAK,CAAC,SAAS,CAAC,UAAU;YACxB,MAAM,eAAe,GAAG,qBAAqB,CAAC,UAAU,CAAC,CAAC;YAC1D,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;YAEtD,OAAO,wBAAwB,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;QAC1D,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,UAAU;YACtB,MAAM,eAAe,GAAG,qBAAqB,CAAC,UAAU,CAAC,CAAC;YAC1D,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;YAEpD,OAAO,wBAAwB,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;QAC1D,CAAC;KACF,CAAC;IAEF,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,CAAC,YAAY,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5E,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["import type { PermissionClient } from '../client/types';\nimport { assertKnownPermission, type Permission } from '../registry/permissions';\nimport { normalizePermissionState, type PermissionState } from '../state/permissionState';\n\n/***\n * Public manager returned by `createPermissionManager`.\n */\nexport interface PermissionManager {\n  getStatus(permission: Permission): Promise<PermissionState>;\n  request(permission: Permission): Promise<PermissionState>;\n  openSettings?(): Promise<void>;\n}\n\n/***\n * Wraps a client with registry validation and normalized results.\n *\n * @readme\n * Runtime permissions and build-time native configuration are separate concerns.\n * This manager checks or requests permissions through a client, but it does not\n * generate iOS usage descriptions, Android manifest entries, or Expo config\n * plugins.\n *\n * @usage\n * ```ts\n * const permissions = createPermissionManager(client);\n * const camera = await permissions.getStatus(Permission.Camera);\n * const requested = camera.granted\n *   ? camera\n *   : await permissions.request(Permission.Camera);\n * ```\n */\nexport function createPermissionManager(client: PermissionClient): PermissionManager {\n  const manager: PermissionManager = {\n    async getStatus(permission) {\n      const knownPermission = assertKnownPermission(permission);\n      const state = await client.getStatus(knownPermission);\n\n      return normalizePermissionState(knownPermission, state);\n    },\n\n    async request(permission) {\n      const knownPermission = assertKnownPermission(permission);\n      const state = await client.request(knownPermission);\n\n      return normalizePermissionState(knownPermission, state);\n    },\n  };\n\n  if (client.openSettings !== undefined) {\n    manager.openSettings = () => client.openSettings?.() ?? Promise.resolve();\n  }\n\n  return manager;\n}\n"]}

package/dist/metadata/index.d.ts

@@ -0,0 +1,8 @@
+/***
+ * Public package metadata used by generated documentation and tooling.
+ */
+export declare const permissionsPackageMetadata: {
+    readonly name: "@ankhorage/permissions";
+    readonly description: "Cross-platform permission registry and runtime helpers for TypeScript apps.";
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/metadata/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/metadata/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,0BAA0B;;;CAG7B,CAAC"}

package/dist/metadata/index.js

@@ -0,0 +1,8 @@
+/***
+ * Public package metadata used by generated documentation and tooling.
+ */
+export const permissionsPackageMetadata = {
+    name: '@ankhorage/permissions',
+    description: 'Cross-platform permission registry and runtime helpers for TypeScript apps.',
+};
+//# sourceMappingURL=index.js.map

package/dist/metadata/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metadata/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,IAAI,EAAE,wBAAwB;IAC9B,WAAW,EAAE,6EAA6E;CAClF,CAAC","sourcesContent":["/***\n * Public package metadata used by generated documentation and tooling.\n */\nexport const permissionsPackageMetadata = {\n  name: '@ankhorage/permissions',\n  description: 'Cross-platform permission registry and runtime helpers for TypeScript apps.',\n} as const;\n"]}

package/dist/react/index.d.ts

@@ -0,0 +1,66 @@
+import { type ReactNode } from 'react';
+import type { PermissionClient } from '../client/types';
+import { type PermissionManager } from '../manager/createPermissionManager';
+import type { Permission } from '../registry/permissions';
+import { type PermissionState, type PermissionStatus } from '../state/permissionState';
+/***
+ * Props accepted by `PermissionsProvider`.
+ */
+export interface PermissionsProviderProps {
+    readonly children: ReactNode;
+    readonly client?: PermissionClient;
+    readonly manager?: PermissionManager;
+}
+/***
+ * Options for `usePermission`.
+ */
+export interface UsePermissionOptions {
+    readonly initialState?: PermissionState;
+    readonly refreshOnMount?: boolean;
+}
+/***
+ * Result returned by `usePermission`.
+ */
+export interface PermissionHookResult {
+    readonly permission: Permission;
+    readonly status: PermissionStatus;
+    readonly canAskAgain?: boolean;
+    readonly granted: boolean;
+    readonly requestedAt?: Date;
+    readonly reason?: string;
+    readonly state: PermissionState;
+    readonly refresh: () => Promise<PermissionState>;
+    readonly request: () => Promise<PermissionState>;
+    readonly openSettings?: () => Promise<void>;
+}
+/***
+ * Provides a permission manager to React hooks.
+ *
+ * @readme
+ * React helpers are framework-neutral. They depend on React only and do not
+ * import browser, Expo, or React Native permission APIs.
+ */
+export declare function PermissionsProvider({ children, client, manager, }: PermissionsProviderProps): ReactNode;
+/***
+ * Reads the current permission manager from context.
+ */
+export declare function usePermissions(): PermissionManager;
+/***
+ * Tracks a single permission and exposes explicit refresh/request actions.
+ *
+ * @usage
+ * ```tsx
+ * const camera = usePermission(Permission.Camera, { refreshOnMount: true });
+ *
+ * return (
+ *   <Button
+ *     disabled={camera.granted}
+ *     onPress={() => {
+ *       void camera.request();
+ *     }}
+ *   />
+ * );
+ * ```
+ */
+export declare function usePermission(permission: Permission, options?: UsePermissionOptions): PermissionHookResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAMf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAIlC;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,QAAQ,EACR,MAAM,EACN,OAAO,GACR,EAAE,wBAAwB,GAAG,SAAS,CActC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,iBAAiB,CAQlD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,oBAAyB,GACjC,oBAAoB,CAkDtB"}

package/dist/react/index.js

@@ -0,0 +1,91 @@
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+import { createPermissionManager, } from '../manager/createPermissionManager';
+import { createPermissionState, normalizePermissionState, } from '../state/permissionState';
+const PermissionsContext = createContext(undefined);
+/***
+ * Provides a permission manager to React hooks.
+ *
+ * @readme
+ * React helpers are framework-neutral. They depend on React only and do not
+ * import browser, Expo, or React Native permission APIs.
+ */
+export function PermissionsProvider({ children, client, manager, }) {
+    const resolvedManager = useMemo(() => {
+        if (manager !== undefined) {
+            return manager;
+        }
+        if (client !== undefined) {
+            return createPermissionManager(client);
+        }
+        throw new Error('PermissionsProvider requires a client or manager.');
+    }, [client, manager]);
+    return createElement(PermissionsContext.Provider, { value: resolvedManager }, children);
+}
+/***
+ * Reads the current permission manager from context.
+ */
+export function usePermissions() {
+    const manager = useContext(PermissionsContext);
+    if (manager === undefined) {
+        throw new Error('usePermissions must be used within PermissionsProvider.');
+    }
+    return manager;
+}
+/***
+ * Tracks a single permission and exposes explicit refresh/request actions.
+ *
+ * @usage
+ * ```tsx
+ * const camera = usePermission(Permission.Camera, { refreshOnMount: true });
+ *
+ * return (
+ *   <Button
+ *     disabled={camera.granted}
+ *     onPress={() => {
+ *       void camera.request();
+ *     }}
+ *   />
+ * );
+ * ```
+ */
+export function usePermission(permission, options = {}) {
+    const manager = usePermissions();
+    const [state, setState] = useState(() => (options.initialState === undefined
+        ? undefined
+        : normalizePermissionState(permission, options.initialState)) ??
+        createPermissionState({
+            permission,
+            status: 'unknown',
+        }));
+    const refresh = useCallback(async () => {
+        const nextState = await manager.getStatus(permission);
+        setState(nextState);
+        return nextState;
+    }, [manager, permission]);
+    const request = useCallback(async () => {
+        const nextState = await manager.request(permission);
+        setState(nextState);
+        return nextState;
+    }, [manager, permission]);
+    useEffect(() => {
+        if (options.refreshOnMount === true) {
+            void refresh();
+        }
+    }, [options.refreshOnMount, refresh]);
+    const openSettings = manager.openSettings === undefined
+        ? undefined
+        : () => manager.openSettings?.() ?? Promise.resolve();
+    return {
+        permission: state.permission,
+        status: state.status,
+        canAskAgain: state.canAskAgain,
+        granted: state.granted,
+        requestedAt: state.requestedAt,
+        reason: state.reason,
+        state,
+        refresh,
+        request,
+        openSettings,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.tsx"],"names":[],"mappings":"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","sourcesContent":["import {\n  createContext,\n  createElement,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n} from 'react';\n\nimport type { PermissionClient } from '../client/types';\nimport {\n  createPermissionManager,\n  type PermissionManager,\n} from '../manager/createPermissionManager';\nimport type { Permission } from '../registry/permissions';\nimport {\n  createPermissionState,\n  normalizePermissionState,\n  type PermissionState,\n  type PermissionStatus,\n} from '../state/permissionState';\n\nconst PermissionsContext = createContext<PermissionManager | undefined>(undefined);\n\n/***\n * Props accepted by `PermissionsProvider`.\n */\nexport interface PermissionsProviderProps {\n  readonly children: ReactNode;\n  readonly client?: PermissionClient;\n  readonly manager?: PermissionManager;\n}\n\n/***\n * Options for `usePermission`.\n */\nexport interface UsePermissionOptions {\n  readonly initialState?: PermissionState;\n  readonly refreshOnMount?: boolean;\n}\n\n/***\n * Result returned by `usePermission`.\n */\nexport interface PermissionHookResult {\n  readonly permission: Permission;\n  readonly status: PermissionStatus;\n  readonly canAskAgain?: boolean;\n  readonly granted: boolean;\n  readonly requestedAt?: Date;\n  readonly reason?: string;\n  readonly state: PermissionState;\n  readonly refresh: () => Promise<PermissionState>;\n  readonly request: () => Promise<PermissionState>;\n  readonly openSettings?: () => Promise<void>;\n}\n\n/***\n * Provides a permission manager to React hooks.\n *\n * @readme\n * React helpers are framework-neutral. They depend on React only and do not\n * import browser, Expo, or React Native permission APIs.\n */\nexport function PermissionsProvider({\n  children,\n  client,\n  manager,\n}: PermissionsProviderProps): ReactNode {\n  const resolvedManager = useMemo(() => {\n    if (manager !== undefined) {\n      return manager;\n    }\n\n    if (client !== undefined) {\n      return createPermissionManager(client);\n    }\n\n    throw new Error('PermissionsProvider requires a client or manager.');\n  }, [client, manager]);\n\n  return createElement(PermissionsContext.Provider, { value: resolvedManager }, children);\n}\n\n/***\n * Reads the current permission manager from context.\n */\nexport function usePermissions(): PermissionManager {\n  const manager = useContext(PermissionsContext);\n\n  if (manager === undefined) {\n    throw new Error('usePermissions must be used within PermissionsProvider.');\n  }\n\n  return manager;\n}\n\n/***\n * Tracks a single permission and exposes explicit refresh/request actions.\n *\n * @usage\n * ```tsx\n * const camera = usePermission(Permission.Camera, { refreshOnMount: true });\n *\n * return (\n *   <Button\n *     disabled={camera.granted}\n *     onPress={() => {\n *       void camera.request();\n *     }}\n *   />\n * );\n * ```\n */\nexport function usePermission(\n  permission: Permission,\n  options: UsePermissionOptions = {},\n): PermissionHookResult {\n  const manager = usePermissions();\n  const [state, setState] = useState<PermissionState>(\n    () =>\n      (options.initialState === undefined\n        ? undefined\n        : normalizePermissionState(permission, options.initialState)) ??\n      createPermissionState({\n        permission,\n        status: 'unknown',\n      }),\n  );\n\n  const refresh = useCallback(async () => {\n    const nextState = await manager.getStatus(permission);\n    setState(nextState);\n\n    return nextState;\n  }, [manager, permission]);\n\n  const request = useCallback(async () => {\n    const nextState = await manager.request(permission);\n    setState(nextState);\n\n    return nextState;\n  }, [manager, permission]);\n\n  useEffect(() => {\n    if (options.refreshOnMount === true) {\n      void refresh();\n    }\n  }, [options.refreshOnMount, refresh]);\n\n  const openSettings =\n    manager.openSettings === undefined\n      ? undefined\n      : () => manager.openSettings?.() ?? Promise.resolve();\n\n  return {\n    permission: state.permission,\n    status: state.status,\n    canAskAgain: state.canAskAgain,\n    granted: state.granted,\n    requestedAt: state.requestedAt,\n    reason: state.reason,\n    state,\n    refresh,\n    request,\n    openSettings,\n  };\n}\n"]}

package/dist/registry/permissions.d.ts

@@ -0,0 +1,52 @@
+/***
+ * Common runtime permissions supported by the registry.
+ *
+ * @readme
+ * The registry is intentionally platform-neutral. Adapters translate each
+ * permission into whatever a browser, React Native app, Expo app, or test
+ * environment can actually check or request.
+ */
+export declare enum Permission {
+    Camera = "camera",
+    Microphone = "microphone",
+    MediaLibrary = "mediaLibrary",
+    MediaLibraryWrite = "mediaLibraryWrite",
+    LocationForeground = "locationForeground",
+    LocationBackground = "locationBackground",
+    Notifications = "notifications",
+    Clipboard = "clipboard"
+}
+/***
+ * Broad environment categories where a permission can be meaningful.
+ */
+export type PermissionEnvironment = 'web' | 'native' | 'test';
+/***
+ * Describes a known permission without coupling the registry to a platform SDK.
+ */
+export interface PermissionDefinition {
+    readonly permission: Permission;
+    readonly label: string;
+    readonly description: string;
+    readonly environments: readonly PermissionEnvironment[];
+}
+/***
+ * Stable ordered list of known permissions.
+ */
+export declare const PERMISSIONS: readonly [Permission.Camera, Permission.Microphone, Permission.MediaLibrary, Permission.MediaLibraryWrite, Permission.LocationForeground, Permission.LocationBackground, Permission.Notifications, Permission.Clipboard];
+/***
+ * Metadata for known permissions.
+ */
+export declare const PERMISSION_REGISTRY: Readonly<Record<Permission, PermissionDefinition>>;
+/***
+ * Returns true when a string is a registered permission identifier.
+ */
+export declare function isPermission(value: string): value is Permission;
+/***
+ * Throws for programmer errors where an invalid permission reaches runtime.
+ */
+export declare function assertKnownPermission(permission: string): Permission;
+/***
+ * Reads registry metadata for a known permission.
+ */
+export declare function getPermissionDefinition(permission: Permission): PermissionDefinition;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/registry/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/registry/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,oBAAY,UAAU;IACpB,MAAM,WAAW;IACjB,UAAU,eAAe;IACzB,YAAY,iBAAiB;IAC7B,iBAAiB,sBAAsB;IACvC,kBAAkB,uBAAuB;IACzC,kBAAkB,uBAAuB;IACzC,aAAa,kBAAkB;IAC/B,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACzD;AAED;;GAEG;AACH,eAAO,MAAM,WAAW,0NASd,CAAC;AAIX;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAiDlF,CAAC;AAEF;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAMpE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,UAAU,GAAG,oBAAoB,CAEpF"}