fix: add pending browser permission state (#1718)

### Overview

Previously there was no way to track if the SDK is currently prompting
browser for a device permission. For example:

1. Call has camera enabled by default. User visits the call page for the
first time. Browser permission prompt is displayed, but in the meanwhile
camera toggle is showing that camera is enabled (because
`hasBrowserPermission` is true for `prompt` state, and
`optimisticStatus` is `enabled`).
2. Permissions have been reset, and user tries to enable camera. Once
again, browser permission prompt is displayed, but in the meanwhile
camera toggle is showing that camera is enabled.

We now introduce another permission state apart from `prompt`, `granted`
and `denied`: **`prompting`**. This state is in effect while browser
prompt is visible, i.e. when permission state is `prompt` and
`getUserMedia` promise is pending.

### Implementation notes

New browser permission state `prompting` is added to `BrowserPermission`
class.

This state is exposed via the `isPermissionPending$` observable in input
media device manager state.

State hooks for camera and microphone state also return this flag.

Default device toggles support this flag and display the new "?" badge
while permission is pending:

![Screenshot 2025-03-12 at 13 03
37](https://github.com/user-attachments/assets/4966c66e-f9f2-4ed4-8b9f-3513f3bd67d7)

Docs are to follow.

---

There are also two other minor changes in this PR.

The `settled()` check in concurrency.ts is fixed to prevent possible
race conditions. Previously, it was possible to check for `settled()`,
then add more promises to the queue, and `settled()` will resolve
_before_ these newly added promises are resolved.

`isTogglePending` flag is returned from device-related call state hooks.
It can be used to display a loader while camera/microphone are
enabled/disabled. It's not used by our default toggle buttons, but it's
nice to have.

Author: myandrienko

packages/client/src/devices/BrowserPermission.ts

@@ -9,12 +9,14 @@ interface BrowserPermissionConfig {
   queryName: PermissionName;
 }
 
+export type BrowserPermissionState = PermissionState | 'prompting';
+
 export class BrowserPermission {
   private ready: Promise<void>;
   private disposeController = new AbortController();
-  private state: PermissionState | undefined;
+  private state: BrowserPermissionState | undefined;
   private wasPrompted: boolean = false;
-  private listeners = new Set<(state: PermissionState) => void>();
+  private listeners = new Set<(state: BrowserPermissionState) => void>();
   private logger = getLogger(['permissions']);
 
   constructor(private readonly permission: BrowserPermissionConfig) {
@@ -83,6 +85,7 @@ export class BrowserPermission {
 
         try {
           this.wasPrompted = true;
+          this.setState('prompting');
           const stream = await navigator.mediaDevices.getUserMedia(
             this.permission.constraints,
           );
@@ -112,23 +115,21 @@ export class BrowserPermission {
             error: e,
             permission: this.permission,
           });
+          this.setState('prompt');
           throw e;
         }
       },
     );
   }
 
-  listen(cb: (state: PermissionState) => void) {
+  listen(cb: (state: BrowserPermissionState) => void) {
     this.listeners.add(cb);
     if (this.state) cb(this.state);
     return () => this.listeners.delete(cb);
   }
 
   asObservable() {
-    return fromEventPattern<PermissionState>(
-      (handler) => this.listen(handler),
-      (handler, unlisten) => unlisten(),
-    ).pipe(
+    return this.getStateObservable().pipe(
       // In some browsers, the 'change' event doesn't reliably emit and hence,
       // permissionState stays in 'prompt' state forever.
       // Typically, this happens when a user grants one-time permission.
@@ -137,7 +138,20 @@ export class BrowserPermission {
     );
   }
 
-  private setState(state: PermissionState) {
+  getIsPromptingObservable() {
+    return this.getStateObservable().pipe(
+      map((state) => state === 'prompting'),
+    );
+  }
+
+  private getStateObservable() {
+    return fromEventPattern<BrowserPermissionState>(
+      (handler) => this.listen(handler),
+      (handler, unlisten) => unlisten(),
+    );
+  }
+
+  private setState(state: BrowserPermissionState) {
     if (this.state !== state) {
       this.state = state;
       this.listeners.forEach((listener) => listener(state));

packages/client/src/devices/InputMediaDeviceManagerState.ts

@@ -67,6 +67,12 @@ export abstract class InputMediaDeviceManagerState<C = MediaTrackConstraints> {
    */
   hasBrowserPermission$: Observable<boolean>;
 
+  /**
+   * An observable that emits `true` when SDK is prompting for browser permission
+   * (i.e. browser's UI for allowing or disallowing device access is visible)
+   */
+  isPromptingPermission$: Observable<boolean>;
+
   /**
    * Constructs new InputMediaDeviceManagerState instance.
    *
@@ -81,6 +87,10 @@ export abstract class InputMediaDeviceManagerState<C = MediaTrackConstraints> {
     this.hasBrowserPermission$ = permission
       ? permission.asObservable().pipe(shareReplay(1))
       : of(true);
+
+    this.isPromptingPermission$ = permission
+      ? permission.getIsPromptingObservable().pipe(shareReplay(1))
+      : of(false);
   }
 
   /**

packages/client/src/devices/__tests__/mocks.ts

@@ -221,4 +221,5 @@ export const emitDeviceIds = (values: MediaDeviceInfo[]) => {
 
 export const mockBrowserPermission = {
   asObservable: () => of(true),
+  getIsPromptingObservable: () => of(false),
 } as BrowserPermission;

packages/client/src/helpers/concurrency.ts

@@ -48,7 +48,10 @@ export function hasPending(tag: string | symbol) {
 }
 
 export async function settled(tag: string | symbol) {
-  await pendingPromises.get(tag)?.promise;
+  let pending: PendingPromise | undefined;
+  while ((pending = pendingPromises.get(tag))) {
+    await pending.promise;
+  }
 }
 
 /**

packages/react-bindings/src/hooks/callStateHooks.ts

@@ -9,6 +9,7 @@ import {
   CallStatsReport,
   Comparator,
   EgressResponse,
+  InputDeviceStatus,
   MemberResponse,
   OwnCapability,
   StreamVideoParticipant,
@@ -357,28 +358,27 @@ export const useCameraState = () => {
   const devices$ = useMemo(() => camera.listDevices(), [camera]);
 
   const { state } = camera;
-  const status = useObservableValue(state.status$);
-  const optimisticStatus = useObservableValue(state.optimisticStatus$);
   const direction = useObservableValue(state.direction$);
   const mediaStream = useObservableValue(state.mediaStream$);
   const selectedDevice = useObservableValue(state.selectedDevice$);
   const devices = useObservableValue(devices$, EMPTY_DEVICES_ARRAY);
   const hasBrowserPermission = useObservableValue(state.hasBrowserPermission$);
-  const isMute = status !== 'enabled';
-  const optimisticIsMute = optimisticStatus !== 'enabled';
+  const isPromptingPermission = useObservableValue(
+    state.isPromptingPermission$,
+  );
 
   return {
     camera,
-    status,
-    optimisticStatus,
-    isEnabled: status === 'enabled',
     direction,
     mediaStream,
     devices,
     hasBrowserPermission,
+    isPromptingPermission,
     selectedDevice,
-    isMute,
-    optimisticIsMute,
+    ...getComputedStatus(
+      useObservableValue(state.status$),
+      useObservableValue(state.optimisticStatus$),
+    ),
   };
 };
 
@@ -394,28 +394,27 @@ export const useMicrophoneState = () => {
   const devices$ = useMemo(() => microphone.listDevices(), [microphone]);
 
   const { state } = microphone;
-  const status = useObservableValue(state.status$);
-  const optimisticStatus = useObservableValue(state.optimisticStatus$);
   const mediaStream = useObservableValue(state.mediaStream$);
   const selectedDevice = useObservableValue(state.selectedDevice$);
   const devices = useObservableValue(devices$, EMPTY_DEVICES_ARRAY);
   const hasBrowserPermission = useObservableValue(state.hasBrowserPermission$);
+  const isPromptingPermission = useObservableValue(
+    state.isPromptingPermission$,
+  );
   const isSpeakingWhileMuted = useObservableValue(state.speakingWhileMuted$);
-  const isMute = status !== 'enabled';
-  const optimisticIsMute = optimisticStatus !== 'enabled';
 
   return {
     microphone,
-    status,
-    optimisticStatus,
-    isEnabled: status === 'enabled',
     mediaStream,
     devices,
     selectedDevice,
     hasBrowserPermission,
+    isPromptingPermission,
     isSpeakingWhileMuted,
-    isMute,
-    optimisticIsMute,
+    ...getComputedStatus(
+      useObservableValue(state.status$),
+      useObservableValue(state.optimisticStatus$),
+    ),
   };
 };
 
@@ -452,20 +451,13 @@ export const useScreenShareState = () => {
   const call = useCall();
   const { screenShare } = call as Call;
 
-  const status = useObservableValue(screenShare.state.status$);
-  const pendingStatus = useObservableValue(screenShare.state.optimisticStatus$);
-  const mediaStream = useObservableValue(screenShare.state.mediaStream$);
-  const isMute = status !== 'enabled';
-  const optimisticStatus = pendingStatus ?? status;
-  const optimisticIsMute = optimisticStatus !== 'enabled';
-
   return {
     screenShare,
-    mediaStream,
-    status,
-    optimisticStatus,
-    isMute,
-    optimisticIsMute,
+    mediaStream: useObservableValue(screenShare.state.mediaStream$),
+    ...getComputedStatus(
+      useObservableValue(screenShare.state.status$),
+      useObservableValue(screenShare.state.optimisticStatus$),
+    ),
   };
 };
 
@@ -496,3 +488,19 @@ export const useIsCallCaptioningInProgress = (): boolean => {
   const { captioning$ } = useCallState();
   return useObservableValue(captioning$);
 };
+
+function getComputedStatus(
+  status: InputDeviceStatus,
+  pendingStatus: InputDeviceStatus,
+) {
+  const optimisticStatus = pendingStatus ?? status;
+
+  return {
+    status,
+    optimisticStatus,
+    isEnabled: status === 'enabled',
+    isMute: status !== 'enabled',
+    optimisticIsMute: optimisticStatus !== 'enabled',
+    isTogglePending: optimisticStatus !== status,
+  };
+}

packages/react-sdk/src/components/CallControls/ToggleAudioButton.tsx

@@ -30,8 +30,12 @@ export const ToggleAudioPreviewButton = (
   const { caption, onMenuToggle, ...restCompositeButtonProps } = props;
   const { t } = useI18n();
   const { useMicrophoneState } = useCallStateHooks();
-  const { microphone, optimisticIsMute, hasBrowserPermission } =
-    useMicrophoneState();
+  const {
+    microphone,
+    optimisticIsMute,
+    hasBrowserPermission,
+    isPromptingPermission,
+  } = useMicrophoneState();
   const [tooltipDisabled, setTooltipDisabled] = useState(false);
   const handleClick = createCallControlHandler(props, () =>
     microphone.toggle(),
@@ -74,6 +78,13 @@ export const ToggleAudioPreviewButton = (
             children="!"
           />
         )}
+        {isPromptingPermission && (
+          <span
+            className="str-video__pending-permission"
+            title={t('Waiting for permission')}
+            children="?"
+          />
+        )}
       </CompositeButton>
     </WithTooltip>
   );
@@ -102,8 +113,12 @@ export const ToggleAudioPublishingButton = (
     useRequestPermission(OwnCapability.SEND_AUDIO);
 
   const { useMicrophoneState } = useCallStateHooks();
-  const { microphone, optimisticIsMute, hasBrowserPermission } =
-    useMicrophoneState();
+  const {
+    microphone,
+    optimisticIsMute,
+    hasBrowserPermission,
+    isPromptingPermission,
+  } = useMicrophoneState();
   const [tooltipDisabled, setTooltipDisabled] = useState(false);
   const handleClick = createCallControlHandler(props, async () => {
     if (!hasPermission) {
@@ -154,6 +169,14 @@ export const ToggleAudioPublishingButton = (
             {(!hasBrowserPermission || !hasPermission) && (
               <span className="str-video__no-media-permission">!</span>
             )}
+            {isPromptingPermission && (
+              <span
+                className="str-video__pending-permission"
+                title={t('Waiting for permission')}
+              >
+                ?
+              </span>
+            )}
           </CompositeButton>
         </WithTooltip>
       </PermissionNotification>

packages/react-sdk/src/components/CallControls/ToggleVideoButton.tsx

@@ -36,7 +36,12 @@ export const ToggleVideoPreviewButton = (
   } = props;
   const { t } = useI18n();
   const { useCameraState } = useCallStateHooks();
-  const { camera, optimisticIsMute, hasBrowserPermission } = useCameraState();
+  const {
+    camera,
+    optimisticIsMute,
+    hasBrowserPermission,
+    isPromptingPermission,
+  } = useCameraState();
   const [tooltipDisabled, setTooltipDisabled] = useState(false);
   const handleClick = createCallControlHandler(props, () => camera.toggle());
 
@@ -79,6 +84,13 @@ export const ToggleVideoPreviewButton = (
             children="!"
           />
         )}
+        {isPromptingPermission && (
+          <span
+            className="str-video__pending-permission"
+            title={t('Waiting for permission')}
+            children="?"
+          />
+        )}
       </CompositeButton>
     </WithTooltip>
   );
@@ -107,7 +119,12 @@ export const ToggleVideoPublishingButton = (
     useRequestPermission(OwnCapability.SEND_VIDEO);
 
   const { useCameraState, useCallSettings } = useCallStateHooks();
-  const { camera, optimisticIsMute, hasBrowserPermission } = useCameraState();
+  const {
+    camera,
+    optimisticIsMute,
+    hasBrowserPermission,
+    isPromptingPermission,
+  } = useCameraState();
   const callSettings = useCallSettings();
   const isPublishingVideoAllowed = callSettings?.video.enabled;
   const [tooltipDisabled, setTooltipDisabled] = useState(false);
@@ -170,6 +187,14 @@ export const ToggleVideoPublishingButton = (
               !isPublishingVideoAllowed) && (
               <span className="str-video__no-media-permission">!</span>
             )}
+            {isPromptingPermission && (
+              <span
+                className="str-video__pending-permission"
+                title={t('Waiting for permission')}
+              >
+                ?
+              </span>
+            )}
           </CompositeButton>
         </WithTooltip>
       </PermissionNotification>