@flighthq/permissions 0.3.0-next.906.07cea63 → 0.3.1-next.209.43ef1bc

package/dist/contract.d.ts

@@ -1,2 +1,3 @@
+export * from './enablePermissionGuards';
 export * from './permission';
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC"}

package/dist/contract.js

@@ -1,2 +1,3 @@
+export * from './enablePermissionGuards';
 export * from './permission';
 //# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC"}

package/dist/enablePermissionGuards.d.ts

@@ -0,0 +1,4 @@
+export declare function arePermissionGuardsEnabled(): boolean;
+export declare function disablePermissionGuards(): void;
+export declare function enablePermissionGuards(): void;
+//# sourceMappingURL=enablePermissionGuards.d.ts.map

package/dist/enablePermissionGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enablePermissionGuards.d.ts","sourceRoot":"","sources":["../src/enablePermissionGuards.ts"],"names":[],"mappings":"AAMA,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAMD,wBAAgB,sBAAsB,IAAI,IAAI,CAG7C"}

package/dist/enablePermissionGuards.js

@@ -0,0 +1,29 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setPermissionRequestFallbackGuard } from './permission';
+export function arePermissionGuardsEnabled() {
+    return _enabled;
+}
+export function disablePermissionGuards() {
+    setPermissionRequestFallbackGuard(null);
+    _enabled = false;
+}
+// Installs diagnostics for the one silent degradation in this package: `requestPermission` on a name with
+// no concrete request path falls back to a plain state query. Nothing throws, a plausible state comes back,
+// and no OS prompt ever appears — so a caller waiting on a prompt waits forever with no signal that the
+// name has no request route on this platform.
+export function enablePermissionGuards() {
+    setPermissionRequestFallbackGuard(warnPermissionRequestFallback);
+    _enabled = true;
+}
+function warnPermissionRequestFallback(name, state) {
+    // Keyed per name: a second name with no request path is a different observation worth reporting, while
+    // the same name asked every frame is not.
+    logOnce(`permissions:request-fallback:${name}`, LogLevel.Warn, {
+        message: `requestPermission('${name}'): no request path for this name on this backend, so it fell back to a plain state query and NO prompt was shown; the resulting '${state}' is a read, not a decision`,
+        name,
+        state,
+    }, 'permissions');
+}
+let _enabled = false;
+//# sourceMappingURL=enablePermissionGuards.js.map

package/dist/enablePermissionGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enablePermissionGuards.js","sourceRoot":"","sources":["../src/enablePermissionGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,iCAAiC,EAAE,MAAM,cAAc,CAAC;AAEjE,MAAM,UAAU,0BAA0B;IACxC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,iCAAiC,CAAC,IAAI,CAAC,CAAC;IACxC,QAAQ,GAAG,KAAK,CAAC;AACnB,CAAC;AAED,0GAA0G;AAC1G,4GAA4G;AAC5G,wGAAwG;AACxG,8CAA8C;AAC9C,MAAM,UAAU,sBAAsB;IACpC,iCAAiC,CAAC,6BAA6B,CAAC,CAAC;IACjE,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,SAAS,6BAA6B,CAAC,IAAoB,EAAE,KAAsB;IACjF,uGAAuG;IACvG,0CAA0C;IAC1C,OAAO,CACL,gCAAgC,IAAI,EAAE,EACtC,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EAAE,sBAAsB,IAAI,qIAAqI,KAAK,6BAA6B;QAC1M,IAAI;QACJ,KAAK;KACN,EACD,aAAa,CACd,CAAC;AACJ,CAAC;AAED,IAAI,QAAQ,GAAG,KAAK,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { getPermissionState, requestPermission } from './contract';
+export { disablePermissionGuards, enablePermissionGuards, explainPermissionState, getPermissionState, getPermissionStates, requestPermission, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { getPermissionState, requestPermission } from './contract';
+export { disablePermissionGuards, enablePermissionGuards, explainPermissionState, getPermissionState, getPermissionStates, requestPermission, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/permission.d.ts

@@ -1,7 +1,10 @@
-import type { PermissionBackend, PermissionName, PermissionState } from '@flighthq/types/contract';
+import type { PermissionBackend, PermissionName, PermissionRequestFallbackGuard, PermissionState, PermissionStateExplanation } from '@flighthq/types/contract';
 export declare function createWebPermissionBackend(): PermissionBackend;
+export declare function explainPermissionState(name: PermissionName): Promise<PermissionStateExplanation>;
 export declare function getPermissionBackend(): PermissionBackend;
 export declare function getPermissionState(name: PermissionName): Promise<PermissionState>;
+export declare function getPermissionStates(names: readonly PermissionName[]): Promise<PermissionState[]>;
 export declare function requestPermission(name: PermissionName): Promise<PermissionState>;
 export declare function setPermissionBackend(backend: PermissionBackend | null): void;
+export declare function setPermissionRequestFallbackGuard(guard: PermissionRequestFallbackGuard | null): void;
 //# sourceMappingURL=permission.d.ts.map

package/dist/permission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAOnG,wBAAgB,0BAA0B,IAAI,iBAAiB,CAS9D;AAGD,wBAAgB,oBAAoB,IAAI,iBAAiB,CAGxD;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEjF;AAKD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEhF;AAGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAE5E"}
+{"version":3,"file":"permission.d.ts","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,8BAA8B,EAC9B,eAAe,EACf,0BAA0B,EAC3B,MAAM,0BAA0B,CAAC;AAOlC,wBAAgB,0BAA0B,IAAI,iBAAiB,CAS9D;AAUD,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAiBtG;AAGD,wBAAgB,oBAAoB,IAAI,iBAAiB,CAMxD;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEjF;AAMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAEhG;AAKD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEhF;AAGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAE5E;AAKD,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,8BAA8B,GAAG,IAAI,GAAG,IAAI,CAEpG"}

package/dist/permission.js

@@ -13,10 +13,39 @@ export function createWebPermissionBackend() {
         },
     };
 }
+// Reports WHY a state read came out the way it did, for the caller who got 'prompt' and cannot act on it.
+// That one value means three different things — undecided, unqueryable name, or no Permissions API at all —
+// and they have opposite remedies. Runs the same read as getPermissionState and reports which branch the
+// web backend took, so it is a companion probe rather than a second source of truth.
+//
+// A custom backend has no branches to report: its answer is whatever it returned, described as 'decided'
+// for a definite state and 'undecided' for 'prompt'. Only the built-in web backend can distinguish
+// 'unqueryable' from 'unsupported', because only it knows whether navigator.permissions exists.
+export async function explainPermissionState(name) {
+    const backend = getPermissionBackend();
+    if (backend !== _webBackend) {
+        const state = await backend.getState(name);
+        return { name, source: state === 'prompt' ? 'undecided' : 'decided', state };
+    }
+    const permissions = getWebPermissions();
+    if (permissions === null) {
+        return { name, source: 'unsupported', state: readWebFallbackPermissionState(name) };
+    }
+    try {
+        const status = await permissions.query({ name });
+        const state = status.state;
+        return { name, source: state === 'prompt' ? 'undecided' : 'decided', state };
+    }
+    catch {
+        return { name, source: 'unqueryable', state: readWebFallbackPermissionState(name) };
+    }
+}
 // The active permission backend, lazily defaulting to the web backend. There is always a backend.
 export function getPermissionBackend() {
-    if (_backend === null)
+    if (_backend === null) {
         _backend = createWebPermissionBackend();
+        _webBackend = _backend;
+    }
     return _backend;
 }
 // Resolves the current state of a named permission without prompting. Returns 'granted', 'denied',
@@ -24,6 +53,13 @@ export function getPermissionBackend() {
 export function getPermissionState(name) {
     return getPermissionBackend().getState(name);
 }
+// Batch form of getPermissionState. Results are returned in INPUT ORDER as a parallel array rather than a
+// keyed record: the caller may legitimately pass the same name twice, and an array preserves that where a
+// record would silently collapse it. Queries run concurrently; a state read never throws, so neither does
+// this.
+export function getPermissionStates(names) {
+    return Promise.all(names.map((name) => getPermissionState(name)));
+}
 // Requests a named permission, triggering the OS prompt where the platform supports it. Resolves to
 // the resulting state; a name with no request path falls back to a plain state query, and a missing
 // API resolves to a sentinel rather than throwing.
@@ -34,12 +70,17 @@ export function requestPermission(name) {
 export function setPermissionBackend(backend) {
     _backend = backend;
 }
-let _backend = null;
-// Maps a PermissionName to its Permissions-API query descriptor name. The built-in names are already
-// valid descriptor names, so this is identity for them; an unlisted name is queried under itself.
-function getPermissionQueryDescriptorName(name) {
-    return _permissionQueryDescriptors[name] ?? name;
+// Diagnostics seam for the silent degradation in requestPermission: a name with no concrete request path
+// resolves to a plain state query, so no prompt ever appears and the caller cannot tell. Core stays
+// message-free; enablePermissionGuards installs the reporter.
+export function setPermissionRequestFallbackGuard(guard) {
+    _requestFallbackGuard = guard;
 }
+let _backend = null;
+let _requestFallbackGuard = null;
+// Identity of the lazily-created default, so explainPermissionState can tell whether the active backend is
+// the web one whose branches it knows how to describe.
+let _webBackend = null;
 // The per-name fallback state when the Permissions API is absent or the name is unqueryable.
 // notifications is still readable synchronously via Notification.permission ('default' → 'prompt');
 // every other name resolves to the 'prompt' sentinel.
@@ -55,9 +96,7 @@ async function readWebPermissionState(name) {
     const permissions = getWebPermissions();
     if (permissions !== null) {
         try {
-            const status = await permissions.query({
-                name: getPermissionQueryDescriptorName(name),
-            });
+            const status = await permissions.query({ name });
             return status.state;
         }
         catch {
@@ -109,6 +148,23 @@ async function requestWebNotificationPermission() {
         return 'prompt';
     }
 }
+// Observes a MIDI access grant purely for the prompt; the access object is discarded, mirroring the
+// discarded geolocation position. sysex is not requested — that is a strictly larger prompt than the
+// 'midi' permission this name denotes.
+async function requestWebMidiPermission() {
+    if (typeof navigator === 'undefined')
+        return 'prompt';
+    const request = navigator.requestMIDIAccess;
+    if (typeof request !== 'function')
+        return 'prompt';
+    try {
+        await request.call(navigator);
+        return 'granted';
+    }
+    catch {
+        return 'denied';
+    }
+}
 async function requestWebPersistentStoragePermission() {
     const storage = getWebStorageManager();
     if (storage === null || typeof storage.persist !== 'function')
@@ -120,11 +176,33 @@ async function requestWebPersistentStoragePermission() {
         return 'prompt';
     }
 }
+// Takes a screen wake lock and releases it immediately — the prompt is the only thing wanted, the same
+// shape as getUserMedia's stop-tracks. Holding the lock would be a lasting side effect the caller did not
+// ask for; releasing keeps the trigger observation-only.
+async function requestWebScreenWakeLockPermission() {
+    if (typeof navigator === 'undefined')
+        return 'prompt';
+    const wakeLock = navigator
+        .wakeLock;
+    if (wakeLock === undefined || typeof wakeLock.request !== 'function')
+        return 'prompt';
+    try {
+        const sentinel = await wakeLock.request('screen');
+        if (typeof sentinel?.release === 'function')
+            await sentinel.release();
+        return 'granted';
+    }
+    catch {
+        return 'denied';
+    }
+}
 async function requestWebPermission(name) {
     const router = _permissionRequestRouters[name];
     if (router !== undefined)
         return await router();
-    return await readWebPermissionState(name);
+    const state = await readWebPermissionState(name);
+    _requestFallbackGuard?.(name, state);
+    return state;
 }
 // Stops every track of a granted media stream, releasing the device. Guards a missing getTracks so a
 // stubbed or partial stream never throws.
@@ -168,23 +246,13 @@ function getWebStorageManager() {
         return null;
     return navigator.storage ?? null;
 }
-const _permissionQueryDescriptors = {
-    camera: 'camera',
-    microphone: 'microphone',
-    geolocation: 'geolocation',
-    notifications: 'notifications',
-    'clipboard-read': 'clipboard-read',
-    'clipboard-write': 'clipboard-write',
-    'persistent-storage': 'persistent-storage',
-    push: 'push',
-    midi: 'midi',
-    'screen-wake-lock': 'screen-wake-lock',
-};
 const _permissionRequestRouters = {
     camera: () => requestWebMediaPermission('video'),
     microphone: () => requestWebMediaPermission('audio'),
     geolocation: requestWebGeolocationPermission,
     notifications: requestWebNotificationPermission,
     'persistent-storage': requestWebPersistentStoragePermission,
+    midi: requestWebMidiPermission,
+    'screen-wake-lock': requestWebScreenWakeLockPermission,
 };
 //# sourceMappingURL=permission.js.map

package/dist/permission.js.map

@@ -1 +1 @@
-{"version":3,"file":"permission.js","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../src/permission.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/permissions",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.1-next.209.43ef1bc",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,7 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.1-next.209.43ef1bc",
+    "@flighthq/types": "0.3.1-next.209.43ef1bc"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enablePermissionGuards.test.ts

@@ -0,0 +1,83 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { arePermissionGuardsEnabled, disablePermissionGuards, enablePermissionGuards } from './enablePermissionGuards';
+import { requestPermission, setPermissionBackend } from './permission';
+
+function captureLog(run: () => Promise<void>): Promise<readonly LogEntry[]> {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  return run()
+    .then(() => getMemoryLogSinkEntries(sink))
+    .finally(() => removeLogSink(sink.sink));
+}
+
+function messageOf(entry: Readonly<LogEntry>): string {
+  const data = entry.data;
+  return typeof data === 'string' ? data : String(data.message);
+}
+
+afterEach(() => {
+  disablePermissionGuards();
+  setPermissionBackend(null);
+  vi.unstubAllGlobals();
+});
+
+describe('arePermissionGuardsEnabled', () => {
+  it('reports whether diagnostics are installed', () => {
+    expect(arePermissionGuardsEnabled()).toBe(false);
+    enablePermissionGuards();
+    expect(arePermissionGuardsEnabled()).toBe(true);
+    disablePermissionGuards();
+    expect(arePermissionGuardsEnabled()).toBe(false);
+  });
+});
+
+describe('disablePermissionGuards', () => {
+  it('returns the silent degradation to silence', async () => {
+    vi.stubGlobal('navigator', { permissions: { query: async () => ({ state: 'prompt' }) } });
+    enablePermissionGuards();
+    disablePermissionGuards();
+
+    const entries = await captureLog(async () => {
+      await requestPermission('acme.disabled-name');
+    });
+
+    expect(entries.length).toBe(0);
+  });
+});
+
+describe('enablePermissionGuards', () => {
+  // logOnce suppresses a key for the whole PROCESS, so the fire and the stays-quiet assertions live in
+  // ONE test in order, and every test in this file uses a distinct permission name.
+  it('WARNS that a request showed no prompt, then suppresses the repeat', async () => {
+    vi.stubGlobal('navigator', { permissions: { query: async () => ({ state: 'prompt' }) } });
+    enablePermissionGuards();
+
+    const entries = await captureLog(async () => {
+      await requestPermission('acme.no-request-path');
+    });
+    expect(entries.length).toBe(1);
+    // The consequence is the point: a caller waiting on a prompt waits forever.
+    expect(messageOf(entries[0])).toContain('NO prompt was shown');
+    expect(messageOf(entries[0])).toContain('acme.no-request-path');
+
+    const repeat = await captureLog(async () => {
+      await requestPermission('acme.no-request-path');
+    });
+    expect(repeat.length).toBe(0);
+  });
+
+  it('stays SILENT for a name that has a real request path', async () => {
+    vi.stubGlobal('navigator', { permissions: { query: async () => ({ state: 'prompt' }) } });
+    vi.stubGlobal('Notification', { permission: 'default', requestPermission: async () => 'granted' });
+    enablePermissionGuards();
+
+    const entries = await captureLog(async () => {
+      expect(await requestPermission('notifications')).toBe('granted');
+    });
+
+    expect(entries.length).toBe(0);
+  });
+});

package/src/permission.test.ts

@@ -3,10 +3,13 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
   createWebPermissionBackend,
+  explainPermissionState,
   getPermissionBackend,
   getPermissionState,
+  getPermissionStates,
   requestPermission,
   setPermissionBackend,
+  setPermissionRequestFallbackGuard,
 } from './permission';
 
 // A recording mock backend: relays a fixed state and captures the last name each method saw.
@@ -149,10 +152,95 @@ describe('createWebPermissionBackend', () => {
   });
 
   it('request falls back to a state query for a name with no request path', async () => {
+    // 'push' has no concrete web trigger; midi and screen-wake-lock now do, so they are no longer
+    // examples of this branch.
     const query = vi.fn(async () => ({ state: 'granted' }));
     vi.stubGlobal('navigator', { permissions: { query } });
+    expect(await createWebPermissionBackend().request('push')).toBe('granted');
+    expect(query).toHaveBeenCalledWith({ name: 'push' });
+  });
+
+  it('request routes midi through requestMIDIAccess, discarding the access object', async () => {
+    const requestMIDIAccess = vi.fn(async () => ({ inputs: 'discarded' }));
+    vi.stubGlobal('navigator', { requestMIDIAccess });
     expect(await createWebPermissionBackend().request('midi')).toBe('granted');
-    expect(query).toHaveBeenCalledWith({ name: 'midi' });
+    expect(requestMIDIAccess).toHaveBeenCalledOnce();
+  });
+
+  it('request reports midi denial rather than throwing', async () => {
+    vi.stubGlobal('navigator', {
+      requestMIDIAccess: async () => {
+        throw new Error('denied');
+      },
+    });
+    expect(await createWebPermissionBackend().request('midi')).toBe('denied');
+  });
+
+  it('request takes a screen wake lock and RELEASES it immediately', async () => {
+    const release = vi.fn(async () => {});
+    const request = vi.fn(async () => ({ release }));
+    vi.stubGlobal('navigator', { wakeLock: { request } });
+    expect(await createWebPermissionBackend().request('screen-wake-lock')).toBe('granted');
+    expect(request).toHaveBeenCalledWith('screen');
+    // Holding the lock would be a lasting side effect the caller never asked for.
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('request resolves to a sentinel when the wake-lock API is absent, and denied when it rejects', async () => {
+    vi.stubGlobal('navigator', {});
+    expect(await createWebPermissionBackend().request('screen-wake-lock')).toBe('prompt');
+    vi.stubGlobal('navigator', {
+      wakeLock: {
+        request: async () => {
+          throw new Error('denied');
+        },
+      },
+    });
+    expect(await createWebPermissionBackend().request('screen-wake-lock')).toBe('denied');
+  });
+});
+
+describe('explainPermissionState', () => {
+  afterEach(() => {
+    setPermissionBackend(null);
+    vi.unstubAllGlobals();
+  });
+
+  it('separates the three meanings of a bare prompt: undecided, unqueryable, and unsupported', async () => {
+    // No Permissions API at all.
+    vi.stubGlobal('navigator', {});
+    expect(await explainPermissionState('camera')).toMatchObject({ source: 'unsupported', state: 'prompt' });
+
+    // Present but rejects this descriptor name.
+    vi.stubGlobal('navigator', {
+      permissions: {
+        query: () => Promise.reject(new Error('bad name')),
+      },
+    });
+    setPermissionBackend(null);
+    expect(await explainPermissionState('acme.unknown')).toMatchObject({ source: 'unqueryable' });
+
+    // Present, queryable, genuinely not decided.
+    vi.stubGlobal('navigator', { permissions: { query: () => Promise.resolve({ state: 'prompt' }) } });
+    setPermissionBackend(null);
+    expect(await explainPermissionState('camera')).toMatchObject({ source: 'undecided', state: 'prompt' });
+  });
+
+  it('reports a definite answer as decided, and carries the name through', async () => {
+    vi.stubGlobal('navigator', { permissions: { query: () => Promise.resolve({ state: 'granted' }) } });
+    expect(await explainPermissionState('geolocation')).toEqual({
+      name: 'geolocation',
+      source: 'decided',
+      state: 'granted',
+    });
+  });
+
+  it('describes a custom backend without claiming branches it cannot observe', async () => {
+    // A host backend has no Permissions API to inspect, so unqueryable/unsupported are not assertable.
+    setPermissionBackend(fakeBackend('prompt'));
+    expect(await explainPermissionState('camera')).toMatchObject({ source: 'undecided' });
+    setPermissionBackend(fakeBackend('denied'));
+    expect(await explainPermissionState('camera')).toMatchObject({ source: 'decided', state: 'denied' });
   });
 });
 
@@ -178,6 +266,27 @@ describe('getPermissionState', () => {
   });
 });
 
+describe('getPermissionStates', () => {
+  afterEach(() => setPermissionBackend(null));
+
+  it('resolves in INPUT order, preserving a repeated name rather than collapsing it', async () => {
+    const states: Record<string, PermissionState> = { camera: 'granted', microphone: 'denied' };
+    setPermissionBackend({
+      getState: (name: PermissionName) => Promise.resolve(states[name] ?? 'prompt'),
+      request: () => Promise.resolve('prompt' as PermissionState),
+    });
+
+    expect(await getPermissionStates(['microphone', 'camera', 'microphone'])).toEqual(['denied', 'granted', 'denied']);
+  });
+
+  it('returns an empty array for no names, without touching the backend', async () => {
+    const backend = fakeBackend('granted');
+    setPermissionBackend(backend);
+    expect(await getPermissionStates([])).toEqual([]);
+    expect(backend.lastGetState).toBeNull();
+  });
+});
+
 describe('requestPermission', () => {
   it('dispatches to the active backend and relays the resolved state', async () => {
     const backend = fakeBackend('granted');
@@ -198,3 +307,33 @@ describe('setPermissionBackend', () => {
     expect(restored.getState).toBeInstanceOf(Function);
   });
 });
+
+describe('setPermissionRequestFallbackGuard', () => {
+  afterEach(() => {
+    setPermissionRequestFallbackGuard(null);
+    setPermissionBackend(null);
+    vi.unstubAllGlobals();
+  });
+
+  it('reports only the names that silently degraded to a query, and stops once cleared', async () => {
+    const seen: string[] = [];
+    // No request path for 'push'; 'notifications' has one via Notification.requestPermission.
+    vi.stubGlobal('navigator', { permissions: { query: () => Promise.resolve({ state: 'prompt' }) } });
+    vi.stubGlobal('Notification', {
+      permission: 'default',
+      requestPermission: () => Promise.resolve('granted'),
+    });
+    setPermissionRequestFallbackGuard((name) => seen.push(name));
+
+    expect(await requestPermission('push')).toBe('prompt');
+    expect(seen).toEqual(['push']);
+
+    // A name WITH a router prompts for real and must not be reported as a fallback.
+    expect(await requestPermission('notifications')).toBe('granted');
+    expect(seen).toEqual(['push']);
+
+    setPermissionRequestFallbackGuard(null);
+    await requestPermission('push');
+    expect(seen).toEqual(['push']);
+  });
+});