@ankhorage/permissions 0.1.0

package/dist/registry/permissions.js

@@ -0,0 +1,108 @@
+/***
+ * 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 var Permission;
+(function (Permission) {
+    Permission["Camera"] = "camera";
+    Permission["Microphone"] = "microphone";
+    Permission["MediaLibrary"] = "mediaLibrary";
+    Permission["MediaLibraryWrite"] = "mediaLibraryWrite";
+    Permission["LocationForeground"] = "locationForeground";
+    Permission["LocationBackground"] = "locationBackground";
+    Permission["Notifications"] = "notifications";
+    Permission["Clipboard"] = "clipboard";
+})(Permission || (Permission = {}));
+/***
+ * Stable ordered list of known permissions.
+ */
+export const PERMISSIONS = [
+    Permission.Camera,
+    Permission.Microphone,
+    Permission.MediaLibrary,
+    Permission.MediaLibraryWrite,
+    Permission.LocationForeground,
+    Permission.LocationBackground,
+    Permission.Notifications,
+    Permission.Clipboard,
+];
+const PERMISSION_SET = new Set(PERMISSIONS);
+/***
+ * Metadata for known permissions.
+ */
+export const PERMISSION_REGISTRY = {
+    [Permission.Camera]: {
+        permission: Permission.Camera,
+        label: 'Camera',
+        description: 'Access to a device camera for capture or scanning workflows.',
+        environments: ['web', 'native', 'test'],
+    },
+    [Permission.Microphone]: {
+        permission: Permission.Microphone,
+        label: 'Microphone',
+        description: 'Access to a device microphone for audio recording or calls.',
+        environments: ['web', 'native', 'test'],
+    },
+    [Permission.MediaLibrary]: {
+        permission: Permission.MediaLibrary,
+        label: 'Media library',
+        description: 'Read access to photos, videos, or other local media assets.',
+        environments: ['native', 'test'],
+    },
+    [Permission.MediaLibraryWrite]: {
+        permission: Permission.MediaLibraryWrite,
+        label: 'Media library write',
+        description: 'Write access for saving media to a local library.',
+        environments: ['native', 'test'],
+    },
+    [Permission.LocationForeground]: {
+        permission: Permission.LocationForeground,
+        label: 'Foreground location',
+        description: 'Location access while the app or page is actively in use.',
+        environments: ['web', 'native', 'test'],
+    },
+    [Permission.LocationBackground]: {
+        permission: Permission.LocationBackground,
+        label: 'Background location',
+        description: 'Location access while the app is not actively in use.',
+        environments: ['native', 'test'],
+    },
+    [Permission.Notifications]: {
+        permission: Permission.Notifications,
+        label: 'Notifications',
+        description: 'Permission to show user-visible notifications.',
+        environments: ['web', 'native', 'test'],
+    },
+    [Permission.Clipboard]: {
+        permission: Permission.Clipboard,
+        label: 'Clipboard',
+        description: 'Read or write access to clipboard contents.',
+        environments: ['web', 'native', 'test'],
+    },
+};
+/***
+ * Returns true when a string is a registered permission identifier.
+ */
+export function isPermission(value) {
+    return PERMISSION_SET.has(value);
+}
+/***
+ * Throws for programmer errors where an invalid permission reaches runtime.
+ */
+export function assertKnownPermission(permission) {
+    if (!isPermission(permission)) {
+        throw new TypeError(`Unknown permission: ${permission}`);
+    }
+    return permission;
+}
+/***
+ * Reads registry metadata for a known permission.
+ */
+export function getPermissionDefinition(permission) {
+    return PERMISSION_REGISTRY[assertKnownPermission(permission)];
+}
+//# sourceMappingURL=permissions.js.map

package/dist/registry/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/registry/permissions.ts"],"names":[],"mappings":"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","sourcesContent":["/***\n * Common runtime permissions supported by the registry.\n *\n * @readme\n * The registry is intentionally platform-neutral. Adapters translate each\n * permission into whatever a browser, React Native app, Expo app, or test\n * environment can actually check or request.\n */\nexport enum Permission {\n  Camera = 'camera',\n  Microphone = 'microphone',\n  MediaLibrary = 'mediaLibrary',\n  MediaLibraryWrite = 'mediaLibraryWrite',\n  LocationForeground = 'locationForeground',\n  LocationBackground = 'locationBackground',\n  Notifications = 'notifications',\n  Clipboard = 'clipboard',\n}\n\n/***\n * Broad environment categories where a permission can be meaningful.\n */\nexport type PermissionEnvironment = 'web' | 'native' | 'test';\n\n/***\n * Describes a known permission without coupling the registry to a platform SDK.\n */\nexport interface PermissionDefinition {\n  readonly permission: Permission;\n  readonly label: string;\n  readonly description: string;\n  readonly environments: readonly PermissionEnvironment[];\n}\n\n/***\n * Stable ordered list of known permissions.\n */\nexport const PERMISSIONS = [\n  Permission.Camera,\n  Permission.Microphone,\n  Permission.MediaLibrary,\n  Permission.MediaLibraryWrite,\n  Permission.LocationForeground,\n  Permission.LocationBackground,\n  Permission.Notifications,\n  Permission.Clipboard,\n] as const;\n\nconst PERMISSION_SET = new Set<string>(PERMISSIONS);\n\n/***\n * Metadata for known permissions.\n */\nexport const PERMISSION_REGISTRY: Readonly<Record<Permission, PermissionDefinition>> = {\n  [Permission.Camera]: {\n    permission: Permission.Camera,\n    label: 'Camera',\n    description: 'Access to a device camera for capture or scanning workflows.',\n    environments: ['web', 'native', 'test'],\n  },\n  [Permission.Microphone]: {\n    permission: Permission.Microphone,\n    label: 'Microphone',\n    description: 'Access to a device microphone for audio recording or calls.',\n    environments: ['web', 'native', 'test'],\n  },\n  [Permission.MediaLibrary]: {\n    permission: Permission.MediaLibrary,\n    label: 'Media library',\n    description: 'Read access to photos, videos, or other local media assets.',\n    environments: ['native', 'test'],\n  },\n  [Permission.MediaLibraryWrite]: {\n    permission: Permission.MediaLibraryWrite,\n    label: 'Media library write',\n    description: 'Write access for saving media to a local library.',\n    environments: ['native', 'test'],\n  },\n  [Permission.LocationForeground]: {\n    permission: Permission.LocationForeground,\n    label: 'Foreground location',\n    description: 'Location access while the app or page is actively in use.',\n    environments: ['web', 'native', 'test'],\n  },\n  [Permission.LocationBackground]: {\n    permission: Permission.LocationBackground,\n    label: 'Background location',\n    description: 'Location access while the app is not actively in use.',\n    environments: ['native', 'test'],\n  },\n  [Permission.Notifications]: {\n    permission: Permission.Notifications,\n    label: 'Notifications',\n    description: 'Permission to show user-visible notifications.',\n    environments: ['web', 'native', 'test'],\n  },\n  [Permission.Clipboard]: {\n    permission: Permission.Clipboard,\n    label: 'Clipboard',\n    description: 'Read or write access to clipboard contents.',\n    environments: ['web', 'native', 'test'],\n  },\n};\n\n/***\n * Returns true when a string is a registered permission identifier.\n */\nexport function isPermission(value: string): value is Permission {\n  return PERMISSION_SET.has(value);\n}\n\n/***\n * Throws for programmer errors where an invalid permission reaches runtime.\n */\nexport function assertKnownPermission(permission: string): Permission {\n  if (!isPermission(permission)) {\n    throw new TypeError(`Unknown permission: ${permission}`);\n  }\n\n  return permission;\n}\n\n/***\n * Reads registry metadata for a known permission.\n */\nexport function getPermissionDefinition(permission: Permission): PermissionDefinition {\n  return PERMISSION_REGISTRY[assertKnownPermission(permission)];\n}\n"]}

package/dist/state/permissionState.d.ts

@@ -0,0 +1,43 @@
+import type { Permission } from '../registry/permissions';
+/***
+ * Normalized permission statuses shared by adapters and UI code.
+ *
+ * Denial is normal control flow. Unexpected adapter failures may still throw,
+ * but user denial should be represented as a permission state.
+ */
+export type PermissionStatus = 'unknown' | 'granted' | 'denied' | 'blocked' | 'limited' | 'unavailable';
+/***
+ * Stable ordered list of normalized statuses.
+ */
+export declare const PERMISSION_STATUSES: readonly ["unknown", "granted", "denied", "blocked", "limited", "unavailable"];
+/***
+ * Normalized result returned by permission clients and managers.
+ */
+export interface PermissionState {
+    readonly permission: Permission;
+    readonly status: PermissionStatus;
+    readonly canAskAgain?: boolean;
+    readonly granted: boolean;
+    readonly requestedAt?: Date;
+    readonly reason?: string;
+}
+export interface CreatePermissionStateInput {
+    readonly permission: Permission;
+    readonly status: PermissionStatus;
+    readonly canAskAgain?: boolean;
+    readonly requestedAt?: Date;
+    readonly reason?: string;
+}
+/***
+ * Returns true when a string is one of the normalized statuses.
+ */
+export declare function isPermissionStatus(value: string): value is PermissionStatus;
+/***
+ * Creates a normalized state and derives the `granted` convenience flag.
+ */
+export declare function createPermissionState(input: CreatePermissionStateInput): PermissionState;
+/***
+ * Normalizes an adapter result to the requested permission and status shape.
+ */
+export declare function normalizePermissionState(permission: Permission, state: PermissionState): PermissionState;
+//# sourceMappingURL=permissionState.d.ts.map

package/dist/state/permissionState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionState.d.ts","sourceRoot":"","sources":["../../src/state/permissionState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,aAAa,CAAC;AAElB;;GAEG;AACH,eAAO,MAAM,mBAAmB,gFAOgB,CAAC;AAIjD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,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;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,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,WAAW,CAAC,EAAE,IAAI,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,gBAAgB,CAE3E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,eAAe,CASxF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,eAAe,GACrB,eAAe,CAQjB"}

package/dist/state/permissionState.js

@@ -0,0 +1,44 @@
+/***
+ * Stable ordered list of normalized statuses.
+ */
+export const PERMISSION_STATUSES = [
+    'unknown',
+    'granted',
+    'denied',
+    'blocked',
+    'limited',
+    'unavailable',
+];
+const PERMISSION_STATUS_SET = new Set(PERMISSION_STATUSES);
+/***
+ * Returns true when a string is one of the normalized statuses.
+ */
+export function isPermissionStatus(value) {
+    return PERMISSION_STATUS_SET.has(value);
+}
+/***
+ * Creates a normalized state and derives the `granted` convenience flag.
+ */
+export function createPermissionState(input) {
+    return {
+        permission: input.permission,
+        status: input.status,
+        canAskAgain: input.canAskAgain,
+        granted: input.status === 'granted',
+        requestedAt: input.requestedAt,
+        reason: input.reason,
+    };
+}
+/***
+ * Normalizes an adapter result to the requested permission and status shape.
+ */
+export function normalizePermissionState(permission, state) {
+    return createPermissionState({
+        permission,
+        status: state.status,
+        canAskAgain: state.canAskAgain,
+        requestedAt: state.requestedAt,
+        reason: state.reason,
+    });
+}
+//# sourceMappingURL=permissionState.js.map

package/dist/state/permissionState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionState.js","sourceRoot":"","sources":["../../src/state/permissionState.ts"],"names":[],"mappings":"AAgBA;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS;IACT,SAAS;IACT,QAAQ;IACR,SAAS;IACT,SAAS;IACT,aAAa;CACiC,CAAC;AAEjD,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAS,mBAAmB,CAAC,CAAC;AAsBnE;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,qBAAqB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiC;IACrE,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,OAAO,EAAE,KAAK,CAAC,MAAM,KAAK,SAAS;QACnC,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAsB,EACtB,KAAsB;IAEtB,OAAO,qBAAqB,CAAC;QAC3B,UAAU;QACV,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { Permission } from '../registry/permissions';\n\n/***\n * Normalized permission statuses shared by adapters and UI code.\n *\n * Denial is normal control flow. Unexpected adapter failures may still throw,\n * but user denial should be represented as a permission state.\n */\nexport type PermissionStatus =\n  | 'unknown'\n  | 'granted'\n  | 'denied'\n  | 'blocked'\n  | 'limited'\n  | 'unavailable';\n\n/***\n * Stable ordered list of normalized statuses.\n */\nexport const PERMISSION_STATUSES = [\n  'unknown',\n  'granted',\n  'denied',\n  'blocked',\n  'limited',\n  'unavailable',\n] as const satisfies readonly PermissionStatus[];\n\nconst PERMISSION_STATUS_SET = new Set<string>(PERMISSION_STATUSES);\n\n/***\n * Normalized result returned by permission clients and managers.\n */\nexport interface PermissionState {\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}\n\nexport interface CreatePermissionStateInput {\n  readonly permission: Permission;\n  readonly status: PermissionStatus;\n  readonly canAskAgain?: boolean;\n  readonly requestedAt?: Date;\n  readonly reason?: string;\n}\n\n/***\n * Returns true when a string is one of the normalized statuses.\n */\nexport function isPermissionStatus(value: string): value is PermissionStatus {\n  return PERMISSION_STATUS_SET.has(value);\n}\n\n/***\n * Creates a normalized state and derives the `granted` convenience flag.\n */\nexport function createPermissionState(input: CreatePermissionStateInput): PermissionState {\n  return {\n    permission: input.permission,\n    status: input.status,\n    canAskAgain: input.canAskAgain,\n    granted: input.status === 'granted',\n    requestedAt: input.requestedAt,\n    reason: input.reason,\n  };\n}\n\n/***\n * Normalizes an adapter result to the requested permission and status shape.\n */\nexport function normalizePermissionState(\n  permission: Permission,\n  state: PermissionState,\n): PermissionState {\n  return createPermissionState({\n    permission,\n    status: state.status,\n    canAskAgain: state.canAskAgain,\n    requestedAt: state.requestedAt,\n    reason: state.reason,\n  });\n}\n"]}

package/dist/testing/index.d.ts

@@ -0,0 +1,49 @@
+import type { PermissionClient } from '../client/types';
+import type { Permission } from '../registry/permissions';
+import { type PermissionState, type PermissionStatus } from '../state/permissionState';
+/***
+ * Seed format accepted by the fake client.
+ */
+export type FakePermissionStateSeed = PermissionState | {
+    readonly permission: Permission;
+    readonly status: PermissionStatus;
+    readonly canAskAgain?: boolean;
+    readonly reason?: string;
+};
+/***
+ * Options for deterministic fake clients.
+ */
+export interface FakePermissionClientOptions {
+    readonly initialStates?: readonly FakePermissionStateSeed[];
+    readonly requestStates?: readonly FakePermissionStateSeed[];
+    readonly now?: () => Date;
+    readonly openSettings?: () => Promise<void>;
+}
+/***
+ * Test client that stores permission states in memory.
+ */
+export interface FakePermissionClient extends PermissionClient {
+    setState(state: FakePermissionStateSeed): void;
+    setStatus(permission: Permission, status: PermissionStatus, options?: {
+        readonly canAskAgain?: boolean;
+        readonly reason?: string;
+    }): void;
+    getSnapshot(): readonly PermissionState[];
+}
+/***
+ * Creates a deterministic in-memory client for tests and examples.
+ *
+ * @readme
+ * Fake clients make permission flows testable without native devices, browser
+ * prompts, simulators, or network access.
+ *
+ * @usage
+ * ```ts
+ * const client = createFakePermissionClient({
+ *   initialStates: [{ permission: Permission.Camera, status: 'denied' }],
+ * });
+ * await client.request(Permission.Camera);
+ * ```
+ */
+export declare function createFakePermissionClient(options?: FakePermissionClientOptions): FakePermissionClient;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAElC;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAC/B,eAAe,GACf;IACE,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,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC5D,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,QAAQ,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC/C,SAAS,CACP,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;QAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;KAC1B,GACA,IAAI,CAAC;IACR,WAAW,IAAI,SAAS,eAAe,EAAE,CAAC;CAC3C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,2BAAgC,GACxC,oBAAoB,CA4EtB"}

package/dist/testing/index.js

@@ -0,0 +1,95 @@
+import { assertKnownPermission, PERMISSIONS } from '../registry/permissions';
+import { createPermissionState, } from '../state/permissionState';
+/***
+ * Creates a deterministic in-memory client for tests and examples.
+ *
+ * @readme
+ * Fake clients make permission flows testable without native devices, browser
+ * prompts, simulators, or network access.
+ *
+ * @usage
+ * ```ts
+ * const client = createFakePermissionClient({
+ *   initialStates: [{ permission: Permission.Camera, status: 'denied' }],
+ * });
+ * await client.request(Permission.Camera);
+ * ```
+ */
+export function createFakePermissionClient(options = {}) {
+    const now = options.now ?? (() => new Date());
+    const states = new Map();
+    const requestStates = new Map();
+    for (const permission of PERMISSIONS) {
+        states.set(permission, createPermissionState({
+            permission,
+            status: 'unknown',
+            canAskAgain: true,
+        }));
+    }
+    for (const state of options.initialStates ?? []) {
+        states.set(state.permission, normalizeSeed(state));
+    }
+    for (const state of options.requestStates ?? []) {
+        requestStates.set(state.permission, normalizeSeed(state));
+    }
+    const client = {
+        getStatus(permission) {
+            return Promise.resolve(getStoredState(states, assertKnownPermission(permission)));
+        },
+        request(permission) {
+            const knownPermission = assertKnownPermission(permission);
+            const requestState = requestStates.get(knownPermission) ?? getStoredState(states, knownPermission);
+            const nextState = createPermissionState({
+                permission: knownPermission,
+                status: requestState.status,
+                canAskAgain: requestState.canAskAgain,
+                requestedAt: now(),
+                reason: requestState.reason,
+            });
+            states.set(knownPermission, nextState);
+            return Promise.resolve(nextState);
+        },
+        openSettings: options.openSettings,
+        setState(state) {
+            const normalizedState = normalizeSeed(state);
+            states.set(normalizedState.permission, normalizedState);
+        },
+        setStatus(permission, status, statusOptions = {}) {
+            const knownPermission = assertKnownPermission(permission);
+            states.set(knownPermission, createPermissionState({
+                permission: knownPermission,
+                status,
+                canAskAgain: statusOptions.canAskAgain,
+                reason: statusOptions.reason,
+            }));
+        },
+        getSnapshot() {
+            return PERMISSIONS.map((permission) => getStoredState(states, permission));
+        },
+    };
+    if (options.openSettings === undefined) {
+        delete client.openSettings;
+    }
+    return client;
+}
+function normalizeSeed(seed) {
+    return createPermissionState({
+        permission: assertKnownPermission(seed.permission),
+        status: seed.status,
+        canAskAgain: seed.canAskAgain,
+        requestedAt: 'requestedAt' in seed ? seed.requestedAt : undefined,
+        reason: seed.reason,
+    });
+}
+function getStoredState(states, permission) {
+    const state = states.get(permission);
+    if (state === undefined) {
+        return createPermissionState({
+            permission,
+            status: 'unknown',
+            canAskAgain: true,
+        });
+    }
+    return state;
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PermissionClient } from '../client/types';\nimport type { Permission } from '../registry/permissions';\nimport { assertKnownPermission, PERMISSIONS } from '../registry/permissions';\nimport {\n  createPermissionState,\n  type PermissionState,\n  type PermissionStatus,\n} from '../state/permissionState';\n\n/***\n * Seed format accepted by the fake client.\n */\nexport type FakePermissionStateSeed =\n  | PermissionState\n  | {\n      readonly permission: Permission;\n      readonly status: PermissionStatus;\n      readonly canAskAgain?: boolean;\n      readonly reason?: string;\n    };\n\n/***\n * Options for deterministic fake clients.\n */\nexport interface FakePermissionClientOptions {\n  readonly initialStates?: readonly FakePermissionStateSeed[];\n  readonly requestStates?: readonly FakePermissionStateSeed[];\n  readonly now?: () => Date;\n  readonly openSettings?: () => Promise<void>;\n}\n\n/***\n * Test client that stores permission states in memory.\n */\nexport interface FakePermissionClient extends PermissionClient {\n  setState(state: FakePermissionStateSeed): void;\n  setStatus(\n    permission: Permission,\n    status: PermissionStatus,\n    options?: {\n      readonly canAskAgain?: boolean;\n      readonly reason?: string;\n    },\n  ): void;\n  getSnapshot(): readonly PermissionState[];\n}\n\n/***\n * Creates a deterministic in-memory client for tests and examples.\n *\n * @readme\n * Fake clients make permission flows testable without native devices, browser\n * prompts, simulators, or network access.\n *\n * @usage\n * ```ts\n * const client = createFakePermissionClient({\n *   initialStates: [{ permission: Permission.Camera, status: 'denied' }],\n * });\n * await client.request(Permission.Camera);\n * ```\n */\nexport function createFakePermissionClient(\n  options: FakePermissionClientOptions = {},\n): FakePermissionClient {\n  const now = options.now ?? (() => new Date());\n  const states = new Map<Permission, PermissionState>();\n  const requestStates = new Map<Permission, PermissionState>();\n\n  for (const permission of PERMISSIONS) {\n    states.set(\n      permission,\n      createPermissionState({\n        permission,\n        status: 'unknown',\n        canAskAgain: true,\n      }),\n    );\n  }\n\n  for (const state of options.initialStates ?? []) {\n    states.set(state.permission, normalizeSeed(state));\n  }\n\n  for (const state of options.requestStates ?? []) {\n    requestStates.set(state.permission, normalizeSeed(state));\n  }\n\n  const client: FakePermissionClient = {\n    getStatus(permission) {\n      return Promise.resolve(getStoredState(states, assertKnownPermission(permission)));\n    },\n\n    request(permission) {\n      const knownPermission = assertKnownPermission(permission);\n      const requestState =\n        requestStates.get(knownPermission) ?? getStoredState(states, knownPermission);\n      const nextState = createPermissionState({\n        permission: knownPermission,\n        status: requestState.status,\n        canAskAgain: requestState.canAskAgain,\n        requestedAt: now(),\n        reason: requestState.reason,\n      });\n\n      states.set(knownPermission, nextState);\n\n      return Promise.resolve(nextState);\n    },\n\n    openSettings: options.openSettings,\n\n    setState(state) {\n      const normalizedState = normalizeSeed(state);\n      states.set(normalizedState.permission, normalizedState);\n    },\n\n    setStatus(permission, status, statusOptions = {}) {\n      const knownPermission = assertKnownPermission(permission);\n      states.set(\n        knownPermission,\n        createPermissionState({\n          permission: knownPermission,\n          status,\n          canAskAgain: statusOptions.canAskAgain,\n          reason: statusOptions.reason,\n        }),\n      );\n    },\n\n    getSnapshot() {\n      return PERMISSIONS.map((permission) => getStoredState(states, permission));\n    },\n  };\n\n  if (options.openSettings === undefined) {\n    delete client.openSettings;\n  }\n\n  return client;\n}\n\nfunction normalizeSeed(seed: FakePermissionStateSeed): PermissionState {\n  return createPermissionState({\n    permission: assertKnownPermission(seed.permission),\n    status: seed.status,\n    canAskAgain: seed.canAskAgain,\n    requestedAt: 'requestedAt' in seed ? seed.requestedAt : undefined,\n    reason: seed.reason,\n  });\n}\n\nfunction getStoredState(\n  states: ReadonlyMap<Permission, PermissionState>,\n  permission: Permission,\n): PermissionState {\n  const state = states.get(permission);\n\n  if (state === undefined) {\n    return createPermissionState({\n      permission,\n      status: 'unknown',\n      canAskAgain: true,\n    });\n  }\n\n  return state;\n}\n"]}

package/dist/web/index.d.ts

@@ -0,0 +1,60 @@
+import type { PermissionClient } from '../client/types';
+type BrowserPermissionName = 'camera' | 'microphone' | 'geolocation' | 'notifications';
+type BrowserPermissionState = 'granted' | 'denied' | 'prompt';
+type NotificationPermissionState = 'default' | 'denied' | 'granted';
+interface BrowserPermissionStatus {
+    readonly state: BrowserPermissionState;
+}
+interface BrowserPermissions {
+    query(descriptor: {
+        readonly name: BrowserPermissionName;
+    }): Promise<BrowserPermissionStatus>;
+}
+interface MediaStreamTrackLike {
+    stop(): void;
+}
+interface MediaStreamLike {
+    getTracks(): readonly MediaStreamTrackLike[];
+}
+interface MediaDevicesLike {
+    getUserMedia(constraints: {
+        readonly audio?: boolean;
+        readonly video?: boolean;
+    }): Promise<MediaStreamLike>;
+}
+interface GeolocationLike {
+    getCurrentPosition(success: () => void, error: () => void, options?: {
+        readonly maximumAge?: number;
+        readonly timeout?: number;
+    }): void;
+}
+interface NavigatorLike {
+    readonly permissions?: BrowserPermissions;
+    readonly mediaDevices?: MediaDevicesLike;
+    readonly geolocation?: GeolocationLike;
+}
+interface NotificationLike {
+    readonly permission: NotificationPermissionState;
+    requestPermission(): Promise<NotificationPermissionState> | NotificationPermissionState;
+}
+interface WebGlobalLike {
+    readonly isSecureContext?: boolean;
+    readonly navigator?: NavigatorLike;
+    readonly Notification?: NotificationLike;
+}
+/***
+ * Options for the browser permission adapter.
+ */
+export interface WebPermissionClientOptions {
+    readonly global?: WebGlobalLike;
+}
+/***
+ * Creates a browser permission client using guarded structural globals.
+ *
+ * @readme
+ * Unsupported web APIs resolve to `status: 'unavailable'`. The adapter does not
+ * import DOM types and does not assume it is running in a browser.
+ */
+export declare function createWebPermissionClient(options?: WebPermissionClientOptions): PermissionClient;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAQxD,KAAK,qBAAqB,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,eAAe,CAAC;AACvF,KAAK,sBAAsB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC9D,KAAK,2BAA2B,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpE,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;CACxC;AAED,UAAU,kBAAkB;IAC1B,KAAK,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAA;KAAE,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC/F;AAED,UAAU,oBAAoB;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED,UAAU,eAAe;IACvB,SAAS,IAAI,SAAS,oBAAoB,EAAE,CAAC;CAC9C;AAED,UAAU,gBAAgB;IACxB,YAAY,CAAC,WAAW,EAAE;QACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;KAC1B,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC9B;AAED,UAAU,eAAe;IACvB,kBAAkB,CAChB,OAAO,EAAE,MAAM,IAAI,EACnB,KAAK,EAAE,MAAM,IAAI,EACjB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;KAC3B,GACA,IAAI,CAAC;CACT;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC;CACxC;AAED,UAAU,gBAAgB;IACxB,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC;IACjD,iBAAiB,IAAI,OAAO,CAAC,2BAA2B,CAAC,GAAG,2BAA2B,CAAC;CACzF;AAED,UAAU,aAAa;IACrB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,0BAA+B,GACvC,gBAAgB,CAiDlB"}