♻️(frontend) refactor prejoin layout for better extensibility

Major refactoring of prejoin interface to improve user onboarding and
camera/microphone permission handling:

* Create extensible hint message system for easier addition of
  permission-related guidance.
* Design flexible layout structure to accommodate future camera/mic
  options and component selection features.
* Establish foundation for comprehensive prejoin redesign

In upcoming commits, UX will be enhanced to a smoother user
experience when joining calls and requesting media permissions.

src/frontend/src/features/rooms/components/Conference.tsx

@@ -1,7 +1,10 @@
 import { useEffect, useMemo, useState } from 'react'
 import { useQuery } from '@tanstack/react-query'
 import { useTranslation } from 'react-i18next'
-import { LiveKitRoom } from '@livekit/components-react'
+import {
+  LiveKitRoom,
+  usePersistentUserChoices,
+} from '@livekit/components-react'
 import {
   DisconnectReason,
   MediaDeviceFailure,
@@ -31,18 +34,20 @@ import { isFireFox } from '@/utils/livekit'
 
 export const Conference = ({
   roomId,
-  userConfig,
   initialRoomData,
   mode = 'join',
 }: {
   roomId: string
-  userConfig: LocalUserChoices
   mode?: 'join' | 'create'
   initialRoomData?: ApiRoom
 }) => {
   const posthog = usePostHog()
   const { data: apiConfig } = useConfig()
 
+  const { userChoices: userConfig } = usePersistentUserChoices() as {
+    userChoices: LocalUserChoices
+  }
+
   useEffect(() => {
     posthog.capture('visit-room', { slug: roomId })
   }, [roomId, posthog])

src/frontend/src/features/rooms/components/Join.tsx

@@ -2,13 +2,13 @@ import { useTranslation } from 'react-i18next'
 import { usePreviewTracks } from '@livekit/components-react'
 import { css } from '@/styled-system/css'
 import { Screen } from '@/layout/Screen'
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { LocalVideoTrack, Track } from 'livekit-client'
 import { H } from '@/primitives/H'
 import { SelectToggleDevice } from '../livekit/components/controls/SelectToggleDevice'
 import { Field } from '@/primitives/Field'
 import { Button, Dialog, Text, Form } from '@/primitives'
-import { HStack, VStack } from '@/styled-system/jsx'
+import { VStack } from '@/styled-system/jsx'
 import { Heading } from 'react-aria-components'
 import { RiImageCircleAiFill } from '@remixicon/react'
 import {
@@ -27,7 +27,6 @@ import { ApiLobbyStatus, ApiRequestEntry } from '../api/requestEntry'
 import { Spinner } from '@/primitives/Spinner'
 import { ApiAccessLevel } from '../api/ApiRoom'
 import { useLoginHint } from '@/hooks/useLoginHint'
-import { LocalUserChoices } from '@/stores/userChoices'
 
 const onError = (e: Error) => console.error('ERROR', e)
 
@@ -72,45 +71,23 @@ const Effects = ({
         </Text>
         <EffectsConfiguration videoTrack={videoTrack} onSubmit={onSubmit} />
       </Dialog>
-      <div
-        className={css({
-          position: 'absolute',
-          right: 0,
-          bottom: '0',
-          padding: '1rem',
-          zIndex: '1',
-        })}
+      <Button
+        variant="whiteCircle"
+        onPress={openDialog}
+        tooltip={t('description')}
+        aria-label={t('description')}
       >
-        <Button
-          variant="whiteCircle"
-          onPress={openDialog}
-          tooltip={t('description')}
-          aria-label={t('description')}
-        >
-          <RiImageCircleAiFill size={24} />
-        </Button>
-      </div>
-      <div
-        className={css({
-          position: 'absolute',
-          left: 0,
-          right: 0,
-          bottom: 0,
-          height: '20%',
-          backgroundImage:
-            'linear-gradient(0deg, rgba(0,0,0,0.7) 0%, rgba(255,255,255,0) 100%)',
-          borderBottomRadius: '1rem',
-        })}
-      />
+        <RiImageCircleAiFill size={24} />
+      </Button>
     </>
   )
 }
 
 export const Join = ({
-  onSubmit,
+  enterRoom,
   roomId,
 }: {
-  onSubmit: (choices: LocalUserChoices) => void
+  enterRoom: () => void
   roomId: string
 }) => {
   const { t } = useTranslation('rooms', { keyPrefix: 'join' })
@@ -132,23 +109,14 @@ export const Join = ({
     saveProcessorSerialized,
   } = usePersistentUserChoices()
 
-  const [processor, setProcessor] = useState(
-    BackgroundProcessorFactory.deserializeProcessor(processorSerialized)
-  )
-
-  useEffect(() => {
-    saveProcessorSerialized(processor?.serialize())
-  }, [
-    processor,
-    saveProcessorSerialized,
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    JSON.stringify(processor?.serialize()),
-  ])
-
   const tracks = usePreviewTracks(
     {
       audio: { deviceId: audioDeviceId },
-      video: { deviceId: videoDeviceId },
+      video: {
+        deviceId: videoDeviceId,
+        processor:
+          BackgroundProcessorFactory.deserializeProcessor(processorSerialized),
+      },
     },
     onError
   )
@@ -170,12 +138,14 @@ export const Join = ({
   )
 
   const videoEl = useRef(null)
+  const isVideoInitiated = useRef(false)
 
   useEffect(() => {
     const videoElement = videoEl.current as HTMLVideoElement | null
 
     const handleVideoLoaded = () => {
       if (videoElement) {
+        isVideoInitiated.current = true
         videoElement.style.opacity = '1'
       }
     }
@@ -192,25 +162,6 @@ export const Join = ({
     }
   }, [videoTrack, videoEnabled])
 
-  const enterRoom = useCallback(() => {
-    onSubmit({
-      audioEnabled,
-      videoEnabled,
-      audioDeviceId,
-      videoDeviceId,
-      username,
-      processorSerialized: processor?.serialize(),
-    })
-  }, [
-    onSubmit,
-    audioEnabled,
-    videoEnabled,
-    audioDeviceId,
-    videoDeviceId,
-    username,
-    processor,
-  ])
-
   // Room data strategy:
   // 1. Initial fetch is performed to check access and get LiveKit configuration
   // 2. Data remains valid for 6 hours to avoid unnecessary refetches
@@ -269,15 +220,19 @@ export const Join = ({
     enterRoom()
   }
 
-  // This hook is used to setup the persisted user choice processor on initialization.
-  // So it's on purpose that processor is not included in the deps.
-  // We just want to wait for the videoTrack to be loaded to apply the default processor.
-  useEffect(() => {
-    if (processor && videoTrack && !videoTrack.getProcessor()) {
-      videoTrack.setProcessor(processor)
+  const hintMessage = useMemo(() => {
+    if (!videoEnabled) {
+      return 'cameraDisabled'
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [videoTrack])
+
+    if (!isVideoInitiated.current) {
+      return 'cameraStarting'
+    }
+
+    if (videoTrack && videoEnabled) {
+      return ''
+    }
+  }, [videoTrack, videoEnabled])
 
   const renderWaitingState = () => {
     switch (status) {
@@ -361,141 +316,216 @@ export const Join = ({
       <div
         className={css({
           display: 'flex',
-          alignItems: 'flex-start',
           justifyContent: 'center',
+          alignItems: 'center',
+          width: '100%',
+          flexDirection: 'column',
           flexGrow: 1,
+          gap: { base: '1rem', sm: '2rem', lg: 0 },
           lg: {
-            alignItems: 'center',
+            flexDirection: 'row',
           },
         })}
       >
         <div
           className={css({
             display: 'flex',
-            height: 'auto',
             alignItems: 'center',
             justifyContent: 'center',
-            gap: '2rem',
-            padding: '0 2rem',
-            flexDirection: 'column',
-            minWidth: 0,
             width: '100%',
+            minWidth: 0,
+            maxWidth: '764px',
             lg: {
-              flexDirection: 'row',
-              width: 'auto',
-              height: '570px',
+              height: '540px',
+              flexGrow: 1,
             },
           })}
         >
           <div
             className={css({
-              width: '100%',
-              lg: {
-                width: '740px',
-              },
+              display: 'inline-flex',
+              flexDirection: 'column',
+              flexGrow: 1,
+              minWidth: 0,
+              flexShrink: { base: 0, sm: 1 },
             })}
           >
             <div
               className={css({
                 borderRadius: '1rem',
+                flex: '0 1',
+                minWidth: '320px',
+                margin: {
+                  base: '0.5rem',
+                  sm: '1rem',
+                  lg: '1rem 0.5rem 1rem 1rem',
+                },
                 overflow: 'hidden',
                 position: 'relative',
-                width: '100%',
-                height: 'auto',
-                aspectRatio: 16 / 9,
-                '--tw-shadow':
-                  '0 10px 15px -5px #00000010, 0 4px 5px -6px #00000010',
-                '--tw-shadow-colored':
-                  '0 10px 15px -5px var(--tw-shadow-color), 0 8px 10px -6px var(--tw-shadow-color)',
-                boxShadow:
-                  'var(--tw-ring-offset-shadow, 0 0 #0000), var(--tw-ring-shadow, 0 0 #0000), var(--tw-shadow)',
-                backgroundColor: 'black',
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
               })}
             >
-              {videoTrack && videoEnabled ? (
-                // eslint-disable-next-line jsx-a11y/media-has-caption
-                <video
-                  ref={videoEl}
-                  width="1280"
-                  height="720"
-                  className={css({
-                    display: 'block',
-                    width: '100%',
-                    height: '100%',
-                    objectFit: 'cover',
-                    transform: 'rotateY(180deg)',
-                    opacity: 0,
-                    transition: 'opacity 0.3s ease-in-out',
-                    borderRadius: '1rem',
-                  })}
-                  disablePictureInPicture
-                  disableRemotePlayback
-                />
-              ) : (
+              <div
+                className={css({
+                  position: 'relative',
+                  width: '100%',
+                  height: 'fit-content',
+                  aspectRatio: '16 / 9',
+                })}
+              >
                 <div
                   className={css({
+                    backgroundColor: 'black',
+                    position: 'absolute',
+                    boxSizing: 'border-box',
+                    top: 0,
                     width: '100%',
                     height: '100%',
-                    color: 'white',
-                    display: 'flex',
-                    justifyContent: 'center',
-                    alignItems: 'center',
+                    overflow: 'hidden',
                   })}
                 >
-                  <p
+                  <div
+                    aria-label={t(
+                      `videoPreview.${videoEnabled ? 'enabled' : 'disabled'}`
+                    )}
+                    role="status"
                     className={css({
-                      fontSize: '24px',
-                      fontWeight: '300',
+                      position: 'absolute',
+                      top: 0,
+                      width: '100%',
                     })}
                   >
-                    {!videoEnabled && t('cameraDisabled')}
-                    {videoEnabled && !videoTrack && t('cameraStarting')}
-                  </p>
+                    <div
+                      className={css({
+                        width: '100%',
+                        height: 'auto',
+                        aspectRatio: '16 / 9',
+                        overflow: 'hidden',
+                        position: 'absolute',
+                        top: '-2px',
+                        left: '-2px',
+                        pointerEvents: 'none',
+                        transform: 'scale(1.02)',
+                      })}
+                    >
+                      {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
+                      <video
+                        ref={videoEl}
+                        width="1280"
+                        height="720"
+                        style={{
+                          display: !videoEnabled ? 'none' : undefined,
+                        }}
+                        className={css({
+                          position: 'absolute',
+                          transform: 'rotateY(180deg)',
+                          opacity: 0,
+                          height: '100%',
+                          transition: 'opacity 0.3s ease-in-out',
+                          objectFit: 'cover',
+                        })}
+                        disablePictureInPicture
+                        disableRemotePlayback
+                      />
+                    </div>
+                  </div>
+                  <div
+                    role="alert"
+                    className={css({
+                      display: 'flex',
+                      flexDirection: 'column',
+                      height: '100%',
+                      width: '100%',
+                      justifyContent: 'center',
+                      textAlign: 'center',
+                      alignItems: 'center',
+                      padding: '0.24rem',
+                      boxSizing: 'border-box',
+                    })}
+                  >
+                    <p
+                      className={css({
+                        fontWeight: '400',
+                        fontSize: { base: '1rem', sm: '1.25rem', lg: '1.5rem' },
+                        textWrap: 'balance',
+                        color: 'white',
+                      })}
+                    >
+                      {hintMessage && t(hintMessage)}
+                    </p>
+                  </div>
                 </div>
-              )}
-              <Effects videoTrack={videoTrack} onSubmit={setProcessor} />
+                <div
+                  className={css({
+                    position: 'absolute',
+                    right: '1rem',
+                    bottom: '1rem',
+                    zIndex: '1',
+                  })}
+                >
+                  <Effects
+                    videoTrack={videoTrack}
+                    onSubmit={(processor) =>
+                      saveProcessorSerialized(processor?.serialize())
+                    }
+                  />
+                </div>
+              </div>
+            </div>
+            <div
+              className={css({
+                display: 'flex',
+                justifyContent: 'center',
+                gap: '2%',
+                width: '80%',
+                marginX: 'auto',
+              })}
+            >
+              <div>
+                <SelectToggleDevice
+                  source={Track.Source.Microphone}
+                  initialState={audioEnabled}
+                  track={audioTrack}
+                  initialDeviceId={audioDeviceId}
+                  onChange={(enabled) => saveAudioInputEnabled(enabled)}
+                  onDeviceError={(error) => console.error(error)}
+                  onActiveDeviceChange={(deviceId) =>
+                    saveAudioInputDeviceId(deviceId ?? '')
+                  }
+                  variant="tertiary"
+                />
+              </div>
+              <div>
+                <SelectToggleDevice
+                  source={Track.Source.Camera}
+                  initialState={videoEnabled}
+                  track={videoTrack}
+                  initialDeviceId={videoDeviceId}
+                  onChange={(enabled) => saveVideoInputEnabled(enabled)}
+                  onDeviceError={(error) => console.error(error)}
+                  onActiveDeviceChange={(deviceId) =>
+                    saveVideoInputDeviceId(deviceId ?? '')
+                  }
+                  variant="tertiary"
+                />
+              </div>
             </div>
-            <HStack justify="center" padding={1.5}>
-              <SelectToggleDevice
-                source={Track.Source.Microphone}
-                initialState={audioEnabled}
-                track={audioTrack}
-                initialDeviceId={audioDeviceId}
-                onChange={(enabled) => saveAudioInputEnabled(enabled)}
-                onDeviceError={(error) => console.error(error)}
-                onActiveDeviceChange={(deviceId) =>
-                  saveAudioInputDeviceId(deviceId ?? '')
-                }
-                variant="tertiary"
-              />
-              <SelectToggleDevice
-                source={Track.Source.Camera}
-                initialState={videoEnabled}
-                track={videoTrack}
-                initialDeviceId={videoDeviceId}
-                onChange={(enabled) => saveVideoInputEnabled(enabled)}
-                onDeviceError={(error) => console.error(error)}
-                onActiveDeviceChange={(deviceId) =>
-                  saveVideoInputDeviceId(deviceId ?? '')
-                }
-                variant="tertiary"
-              />
-            </HStack>
-          </div>
-          <div
-            className={css({
-              width: '100%',
-              flexShrink: 0,
-              padding: '0',
-              sm: {
-                width: '448px',
-                padding: '0 3rem 9rem 3rem',
-              },
-            })}
-          >
-            {renderWaitingState()}
           </div>
         </div>
+        <div
+          className={css({
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            flex: '0 0 448px',
+            position: 'relative',
+            margin: '1rem 1rem 1rem 0.5rem',
+          })}
+        >
+          {renderWaitingState()}
+        </div>
       </div>
     </Screen>
   )

src/frontend/src/features/rooms/routes/Room.tsx

@@ -1,5 +1,4 @@
 import { useEffect, useState } from 'react'
-import { usePersistentUserChoices } from '@livekit/components-react'
 import { useLocation, useParams } from 'wouter'
 import { ErrorScreen } from '@/components/ErrorScreen'
 import { useUser, UserAware } from '@/features/auth'
@@ -10,12 +9,10 @@ import {
   isRoomValid,
   normalizeRoomId,
 } from '@/features/rooms/utils/isRoomValid'
-import { LocalUserChoices } from '@/stores/userChoices'
 
 export const Room = () => {
   const { isLoggedIn } = useUser()
-  const { userChoices: existingUserChoices } = usePersistentUserChoices()
-  const [userConfig, setUserConfig] = useState<LocalUserChoices | null>(null)
+  const [hasSubmittedEntry, setHasSubmittedEntry] = useState(false)
 
   const { roomId } = useParams()
   const [location, setLocation] = useLocation()
@@ -48,10 +45,10 @@ export const Room = () => {
     return <ErrorScreen />
   }
 
-  if (!userConfig && !skipJoinScreen) {
+  if (!hasSubmittedEntry && !skipJoinScreen) {
     return (
       <UserAware>
-        <Join onSubmit={setUserConfig} roomId={roomId} />
+        <Join enterRoom={() => setHasSubmittedEntry(true)} roomId={roomId} />
       </UserAware>
     )
   }
@@ -62,10 +59,6 @@ export const Room = () => {
         initialRoomData={initialRoomData}
         roomId={roomId}
         mode={mode}
-        userConfig={{
-          ...existingUserChoices,
-          ...userConfig,
-        }}
       />
     </UserAware>
   )

src/frontend/src/primitives/Select.tsx

@@ -1,6 +1,6 @@
 import { type ReactNode } from 'react'
 import { styled } from '@/styled-system/jsx'
-import { RiArrowDropDownLine } from '@remixicon/react'
+import { RemixiconComponentType, RiArrowDropDownLine } from '@remixicon/react'
 import {
   Button,
   ListBox,
@@ -12,12 +12,14 @@ import {
 import { Box } from './Box'
 import { StyledPopover } from './Popover'
 import { menuRecipe } from '@/primitives/menuRecipe.ts'
+import { css } from '@/styled-system/css'
 
 const StyledButton = styled(Button, {
   base: {
     width: 'full',
     display: 'flex',
     justifyContent: 'space-between',
+    alignItems: 'center',
     paddingY: 0.125,
     paddingX: 0.25,
     border: '1px solid',
@@ -53,22 +55,40 @@ const StyledSelectValue = styled(SelectValue, {
   },
 })
 
+const StyledIcon = styled('div', {
+  base: {
+    marginRight: '0.35rem',
+    flexShrink: 0,
+  },
+})
+
 export const Select = <T extends string | number>({
   label,
+  iconComponent,
   items,
   errors,
   ...props
 }: Omit<SelectProps<object>, 'items' | 'label' | 'errors'> & {
+  iconComponent?: RemixiconComponentType
   label: ReactNode
   items: Array<{ value: T; label: ReactNode }>
   errors?: ReactNode
 }) => {
+  const IconComponent = iconComponent
   return (
     <RACSelect {...props}>
       {label}
       <StyledButton>
+        {!!IconComponent && (
+          <StyledIcon>
+            <IconComponent size={18} />
+          </StyledIcon>
+        )}
         <StyledSelectValue />
-        <RiArrowDropDownLine aria-hidden="true" />
+        <RiArrowDropDownLine
+          aria-hidden="true"
+          className={css({ flexShrink: 0 })}
+        />
       </StyledButton>
       <StyledPopover>
         <Box size="sm" type="popover" variant="control">