- {/* Empty state */}
-
+ {/* Present students section */}
+ {isLoading ? (
- 🏫
+ Loading classroom...
-
- No Students Present
-
-
- When students join your classroom for practice, they'll appear here. Share your classroom
- code to get started.
-
+ ) : presentStudents.length > 0 ? (
+
+
+
+ Students Present
+
+ {presentStudents.length}
+
+
-
-
+
+ {presentStudents.map((student) => (
+
handleRemoveStudent(student.id)}
+ isRemoving={
+ leaveClassroom.isPending && leaveClassroom.variables?.playerId === student.id
+ }
+ isDark={isDark}
+ />
+ ))}
+
+
+ ) : (
+ /* Empty state */
+
+
+ 🏫
+
+
+ No Students Present
+
+
+ When students join your classroom for practice, they'll appear here. Share your
+ classroom code to get started.
+
+
+
+
+ )}
{/* Instructions */}
Share your classroom code with parents
Parents enroll their child using the code
- Students appear here when they start practicing
+ When practicing, students can "enter" the classroom
+ You'll see them appear here in real-time
+ {/* Main button */}
+
+
+ {/* Dropdown menu */}
+ {isOpen && (
+ <>
+ {/* Backdrop */}
+
setIsOpen(false)}
+ />
+
+ {/* Menu */}
+
+
+
+ {playerName}'s Classrooms
+
+
+
+ {loadingClassrooms || loadingPresence ? (
+
+ Loading...
+
+ ) : (
+
+ {/* Current presence */}
+ {currentPresence && currentClassroom && (
+
+
+
+
+
+ Currently in
+
+
+
+
+
+ {currentClassroom.name}
+
+
+ )}
+
+ {/* Enrolled classrooms list */}
+ {enrolledClassrooms
+ .filter((c) => c.id !== currentPresence?.classroomId)
+ .map((classroom) => (
+
handleEnter(classroom.id)}
+ isEntering={
+ enterClassroom.isPending &&
+ enterClassroom.variables?.classroomId === classroom.id
+ }
+ isDisabled={!!currentPresence}
+ isDark={isDark}
+ />
+ ))}
+
+ {enrolledClassrooms.length === 0 && (
+
+ Not enrolled in any classrooms
+
+ )}
+
+ )}
+
+
+ )}
+
+ )
+}
+
+interface ClassroomMenuItemProps {
+ classroom: Classroom
+ onEnter: () => void
+ isEntering: boolean
+ isDisabled: boolean
+ isDark: boolean
+}
+
+function ClassroomMenuItem({
+ classroom,
+ onEnter,
+ isEntering,
+ isDisabled,
+ isDark,
+}: ClassroomMenuItemProps) {
+ return (
+
+
+
+
+
+ )
+}
diff --git a/apps/web/src/components/classroom/PendingApprovalsSection.tsx b/apps/web/src/components/classroom/PendingApprovalsSection.tsx
new file mode 100644
index 00000000..2ea4fa7a
--- /dev/null
+++ b/apps/web/src/components/classroom/PendingApprovalsSection.tsx
@@ -0,0 +1,255 @@
+'use client'
+
+import { useCallback } from 'react'
+import { useTheme } from '@/contexts/ThemeContext'
+import {
+ usePendingApprovalsForParent,
+ useApproveEnrollmentRequestAsParent,
+ useDenyEnrollmentRequestAsParent,
+ type EnrollmentRequestWithRelations,
+} from '@/hooks/useClassroom'
+import { css } from '../../../styled-system/css'
+
+/**
+ * PendingApprovalsSection - Shows pending enrollment requests for parents
+ *
+ * When a teacher initiates enrollment for a parent's child, the parent
+ * sees it here and can approve or deny.
+ */
+export function PendingApprovalsSection() {
+ const { resolvedTheme } = useTheme()
+ const isDark = resolvedTheme === 'dark'
+
+ const { data: requests = [], isLoading } = usePendingApprovalsForParent()
+ const approveRequest = useApproveEnrollmentRequestAsParent()
+ const denyRequest = useDenyEnrollmentRequestAsParent()
+
+ const handleApprove = useCallback(
+ (requestId: string) => {
+ approveRequest.mutate(requestId)
+ },
+ [approveRequest]
+ )
+
+ const handleDeny = useCallback(
+ (requestId: string) => {
+ denyRequest.mutate(requestId)
+ },
+ [denyRequest]
+ )
+
+ // Don't render if no pending requests
+ if (isLoading || requests.length === 0) {
+ return null
+ }
+
+ return (
+
+
+ 📬
+ Enrollment Requests
+
+ {requests.length}
+
+
+
+
+ A teacher has requested to enroll your child in their classroom.
+
+
+
+ {requests.map((request) => (
+
handleApprove(request.id)}
+ onDeny={() => handleDeny(request.id)}
+ isApproving={approveRequest.isPending && approveRequest.variables === request.id}
+ isDenying={denyRequest.isPending && denyRequest.variables === request.id}
+ isDark={isDark}
+ />
+ ))}
+
+ )
+}
+
+interface PendingApprovalCardProps {
+ request: EnrollmentRequestWithRelations
+ onApprove: () => void
+ onDeny: () => void
+ isApproving: boolean
+ isDenying: boolean
+ isDark: boolean
+}
+
+function PendingApprovalCard({
+ request,
+ onApprove,
+ onDeny,
+ isApproving,
+ isDenying,
+ isDark,
+}: PendingApprovalCardProps) {
+ const player = request.player
+ const classroom = request.classroom
+
+ return (
+
+
+
+ {player?.emoji ?? '?'}
+
+
+
+ {player?.name ?? 'Unknown Student'}
+
+
+ Classroom: {classroom?.name ?? 'Unknown'}
+
+
+
+
+
+
+
+
+
+ )
+}
diff --git a/apps/web/src/components/classroom/StudentManagerTab.tsx b/apps/web/src/components/classroom/StudentManagerTab.tsx
index 8a02f04a..efde9522 100644
--- a/apps/web/src/components/classroom/StudentManagerTab.tsx
+++ b/apps/web/src/components/classroom/StudentManagerTab.tsx
@@ -402,7 +402,7 @@ function EnrolledStudentCard({
})}
>
{
+ const res = await api('enrollment-requests/pending')
+ if (!res.ok) throw new Error('Failed to fetch pending approvals')
+ const data = await res.json()
+ return data.requests
+}
+
+/**
+ * Approve enrollment request as parent
+ */
+async function approveRequestAsParent(
+ requestId: string
+): Promise<{ request: EnrollmentRequest; enrolled: boolean }> {
+ const res = await api(`enrollment-requests/${requestId}/approve`, { method: 'POST' })
+ if (!res.ok) {
+ const data = await res.json()
+ throw new Error(data.error || 'Failed to approve request')
+ }
+ return res.json()
+}
+
+/**
+ * Deny enrollment request as parent
+ */
+async function denyRequestAsParent(requestId: string): Promise
{
+ const res = await api(`enrollment-requests/${requestId}/deny`, { method: 'POST' })
+ if (!res.ok) {
+ const data = await res.json()
+ throw new Error(data.error || 'Failed to deny request')
+ }
+ const data = await res.json()
+ return data.request
+}
+
+// ============================================================================
+// Parent Enrollment Approval Hooks
+// ============================================================================
+
+/**
+ * Get pending enrollment requests for current user as parent
+ *
+ * These are requests initiated by teachers for the user's children,
+ * where parent approval hasn't been given yet.
+ */
+export function usePendingApprovalsForParent() {
+ return useQuery({
+ queryKey: classroomKeys.pendingParentApprovals(),
+ queryFn: fetchPendingApprovalsForParent,
+ staleTime: 30 * 1000, // 30 seconds
+ })
+}
+
+/**
+ * Approve enrollment request as parent
+ */
+export function useApproveEnrollmentRequestAsParent() {
+ const queryClient = useQueryClient()
+
+ return useMutation({
+ mutationFn: approveRequestAsParent,
+ onSuccess: (result) => {
+ // Invalidate pending parent approvals
+ queryClient.invalidateQueries({
+ queryKey: classroomKeys.pendingParentApprovals(),
+ })
+ // If fully approved, classroom enrollments will be updated too
+ // (but we don't know the classroomId from this response, so broader invalidation)
+ if (result.enrolled) {
+ queryClient.invalidateQueries({
+ queryKey: ['classrooms'],
+ })
+ }
+ },
+ })
+}
+
+/**
+ * Deny enrollment request as parent
+ */
+export function useDenyEnrollmentRequestAsParent() {
+ const queryClient = useQueryClient()
+
+ return useMutation({
+ mutationFn: denyRequestAsParent,
+ onSuccess: () => {
+ // Invalidate pending parent approvals
+ queryClient.invalidateQueries({
+ queryKey: classroomKeys.pendingParentApprovals(),
+ })
+ },
+ })
+}
+
+// ============================================================================
+// Classroom Presence API Functions
+// ============================================================================
+
+export interface PresenceStudent extends Player {
+ enteredAt: string
+ enteredBy: string
+}
+
+/**
+ * Fetch students currently present in a classroom
+ */
+async function fetchClassroomPresence(classroomId: string): Promise {
+ const res = await api(`classrooms/${classroomId}/presence`)
+ if (!res.ok) throw new Error('Failed to fetch classroom presence')
+ const data = await res.json()
+ return data.students
+}
+
+/**
+ * Enter a student into a classroom
+ */
+async function enterClassroom(params: {
+ classroomId: string
+ playerId: string
+}): Promise<{ success: boolean; error?: string }> {
+ const res = await api(`classrooms/${params.classroomId}/presence`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ playerId: params.playerId }),
+ })
+ const data = await res.json()
+ if (!res.ok) {
+ return { success: false, error: data.error || 'Failed to enter classroom' }
+ }
+ return { success: true }
+}
+
+/**
+ * Remove a student from a classroom
+ */
+async function leaveClassroom(params: { classroomId: string; playerId: string }): Promise {
+ const res = await api(`classrooms/${params.classroomId}/presence/${params.playerId}`, {
+ method: 'DELETE',
+ })
+ if (!res.ok) {
+ const data = await res.json()
+ throw new Error(data.error || 'Failed to leave classroom')
+ }
+}
+
+// ============================================================================
+// Classroom Presence Hooks
+// ============================================================================
+
+/**
+ * Get students currently present in a classroom
+ */
+export function useClassroomPresence(classroomId: string | undefined) {
+ return useQuery({
+ queryKey: classroomKeys.presence(classroomId ?? ''),
+ queryFn: () => fetchClassroomPresence(classroomId!),
+ enabled: !!classroomId,
+ staleTime: 15 * 1000, // 15 seconds - presence changes frequently
+ refetchInterval: 30 * 1000, // Poll every 30 seconds for real-time feel
+ })
+}
+
+/**
+ * Enter a student into a classroom
+ */
+export function useEnterClassroom() {
+ const queryClient = useQueryClient()
+
+ return useMutation({
+ mutationFn: enterClassroom,
+ onSuccess: (result, { classroomId, playerId }) => {
+ if (result.success) {
+ // Invalidate teacher's view of classroom presence
+ queryClient.invalidateQueries({
+ queryKey: classroomKeys.presence(classroomId),
+ })
+ // Invalidate student's view of their own presence
+ queryClient.invalidateQueries({
+ queryKey: ['players', playerId, 'presence'],
+ })
+ }
+ },
+ })
+}
+
+/**
+ * Remove a student from a classroom
+ */
+export function useLeaveClassroom() {
+ const queryClient = useQueryClient()
+
+ return useMutation({
+ mutationFn: leaveClassroom,
+ onSuccess: (_, { classroomId, playerId }) => {
+ // Invalidate teacher's view of classroom presence
+ queryClient.invalidateQueries({
+ queryKey: classroomKeys.presence(classroomId),
+ })
+ // Invalidate student's view of their own presence
+ queryClient.invalidateQueries({
+ queryKey: ['players', playerId, 'presence'],
+ })
+ },
+ })
+}
+
+// ============================================================================
+// Student Enrollment API Functions
+// ============================================================================
+
+export interface PresenceInfo {
+ playerId: string
+ classroomId: string
+ enteredAt: string
+ enteredBy: string
+ classroom?: Classroom
+}
+
+/**
+ * Fetch classrooms a student is enrolled in
+ */
+async function fetchEnrolledClassrooms(playerId: string): Promise {
+ const res = await api(`players/${playerId}/enrolled-classrooms`)
+ if (!res.ok) throw new Error('Failed to fetch enrolled classrooms')
+ const data = await res.json()
+ return data.classrooms
+}
+
+/**
+ * Fetch student's current classroom presence
+ */
+async function fetchStudentPresence(playerId: string): Promise {
+ const res = await api(`players/${playerId}/presence`)
+ if (!res.ok) throw new Error('Failed to fetch student presence')
+ const data = await res.json()
+ return data.presence
+}
+
+// ============================================================================
+// Student Enrollment Hooks
+// ============================================================================
+
+/**
+ * Get classrooms a student is enrolled in
+ */
+export function useEnrolledClassrooms(playerId: string | undefined) {
+ return useQuery({
+ queryKey: ['players', playerId, 'enrolled-classrooms'],
+ queryFn: () => fetchEnrolledClassrooms(playerId!),
+ enabled: !!playerId,
+ staleTime: 60 * 1000, // 1 minute
+ })
+}
+
+/**
+ * Get student's current classroom presence
+ */
+export function useStudentPresence(playerId: string | undefined) {
+ return useQuery({
+ queryKey: ['players', playerId, 'presence'],
+ queryFn: () => fetchStudentPresence(playerId!),
+ enabled: !!playerId,
+ staleTime: 30 * 1000, // 30 seconds
+ })
+}
diff --git a/apps/web/src/hooks/useClassroomSocket.ts b/apps/web/src/hooks/useClassroomSocket.ts
new file mode 100644
index 00000000..d0841f91
--- /dev/null
+++ b/apps/web/src/hooks/useClassroomSocket.ts
@@ -0,0 +1,74 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { io, type Socket } from 'socket.io-client'
+import { useQueryClient } from '@tanstack/react-query'
+import { classroomKeys } from '@/lib/queryKeys'
+import type { StudentEnteredEvent, StudentLeftEvent } from '@/lib/classroom/socket-events'
+
+/**
+ * Hook for real-time classroom presence updates via WebSocket
+ *
+ * When a student enters or leaves the classroom, this hook receives the event
+ * and automatically invalidates the React Query cache so the UI updates.
+ *
+ * @param classroomId - The classroom to subscribe to
+ * @returns Whether the socket is connected
+ */
+export function useClassroomSocket(classroomId: string | undefined): { connected: boolean } {
+ const [connected, setConnected] = useState(false)
+ const socketRef = useRef(null)
+ const queryClient = useQueryClient()
+
+ useEffect(() => {
+ if (!classroomId) return
+
+ // Create socket connection
+ const socket = io({
+ path: '/api/socket',
+ reconnection: true,
+ reconnectionDelay: 1000,
+ reconnectionAttempts: 5,
+ })
+ socketRef.current = socket
+
+ socket.on('connect', () => {
+ console.log('[ClassroomSocket] Connected')
+ setConnected(true)
+ // Join the classroom channel
+ socket.emit('join-classroom', { classroomId })
+ })
+
+ socket.on('disconnect', () => {
+ console.log('[ClassroomSocket] Disconnected')
+ setConnected(false)
+ })
+
+ // Listen for student entered event
+ socket.on('student-entered', (data: StudentEnteredEvent) => {
+ console.log('[ClassroomSocket] Student entered:', data.playerName)
+ // Invalidate the presence query to refetch
+ queryClient.invalidateQueries({
+ queryKey: classroomKeys.presence(classroomId),
+ })
+ })
+
+ // Listen for student left event
+ socket.on('student-left', (data: StudentLeftEvent) => {
+ console.log('[ClassroomSocket] Student left:', data.playerName)
+ // Invalidate the presence query to refetch
+ queryClient.invalidateQueries({
+ queryKey: classroomKeys.presence(classroomId),
+ })
+ })
+
+ // Cleanup on unmount
+ return () => {
+ socket.emit('leave-classroom', { classroomId })
+ socket.disconnect()
+ socketRef.current = null
+ }
+ }, [classroomId, queryClient])
+
+ return { connected }
+}
diff --git a/apps/web/src/hooks/usePlayerPresenceSocket.ts b/apps/web/src/hooks/usePlayerPresenceSocket.ts
new file mode 100644
index 00000000..d9128ec3
--- /dev/null
+++ b/apps/web/src/hooks/usePlayerPresenceSocket.ts
@@ -0,0 +1,65 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { io, type Socket } from 'socket.io-client'
+import { useQueryClient } from '@tanstack/react-query'
+import type { PresenceRemovedEvent } from '@/lib/classroom/socket-events'
+
+/**
+ * Hook for real-time player presence updates via WebSocket
+ *
+ * When a student is removed from a classroom (by teacher or parent),
+ * this hook receives the event and invalidates the React Query cache
+ * so the UI updates without requiring a page reload.
+ *
+ * @param playerId - The player to subscribe to
+ * @returns Whether the socket is connected
+ */
+export function usePlayerPresenceSocket(playerId: string | undefined): { connected: boolean } {
+ const [connected, setConnected] = useState(false)
+ const socketRef = useRef(null)
+ const queryClient = useQueryClient()
+
+ useEffect(() => {
+ if (!playerId) return
+
+ // Create socket connection
+ const socket = io({
+ path: '/api/socket',
+ reconnection: true,
+ reconnectionDelay: 1000,
+ reconnectionAttempts: 5,
+ })
+ socketRef.current = socket
+
+ socket.on('connect', () => {
+ console.log('[PlayerPresenceSocket] Connected')
+ setConnected(true)
+ // Join the player channel
+ socket.emit('join-player', { playerId })
+ })
+
+ socket.on('disconnect', () => {
+ console.log('[PlayerPresenceSocket] Disconnected')
+ setConnected(false)
+ })
+
+ // Listen for presence removed event (when teacher or parent removes student from classroom)
+ socket.on('presence-removed', (data: PresenceRemovedEvent) => {
+ console.log('[PlayerPresenceSocket] Presence removed:', data)
+ // Invalidate the student's presence query to refetch
+ queryClient.invalidateQueries({
+ queryKey: ['players', playerId, 'presence'],
+ })
+ })
+
+ // Cleanup on unmount
+ return () => {
+ socket.emit('leave-player', { playerId })
+ socket.disconnect()
+ socketRef.current = null
+ }
+ }, [playerId, queryClient])
+
+ return { connected }
+}
diff --git a/apps/web/src/lib/classroom/presence-manager.ts b/apps/web/src/lib/classroom/presence-manager.ts
index c141c00f..a08ed75d 100644
--- a/apps/web/src/lib/classroom/presence-manager.ts
+++ b/apps/web/src/lib/classroom/presence-manager.ts
@@ -19,10 +19,12 @@ import {
classroomEnrollments,
classroomPresence,
classrooms,
+ players,
type ClassroomPresence,
type Classroom,
type Player,
} from '@/db/schema'
+import { getSocketIO } from '@/lib/socket-io'
// ============================================================================
// Enter/Leave Classroom
@@ -97,6 +99,20 @@ export async function enterClassroom(params: EnterClassroomParams): Promise {
+ // Get current presence before deleting (need classroomId for socket event)
+ const presence = await db.query.classroomPresence.findFirst({
+ where: eq(classroomPresence.playerId, playerId),
+ })
+
+ if (!presence) return
+
await db.delete(classroomPresence).where(eq(classroomPresence.playerId, playerId))
+
+ // Emit socket event for real-time updates to teacher
+ const io = await getSocketIO()
+ if (io) {
+ const player = await db.query.players.findFirst({
+ where: eq(players.id, playerId),
+ })
+ io.to(`classroom:${presence.classroomId}`).emit('student-left', {
+ playerId,
+ playerName: player?.name ?? 'Unknown',
+ })
+ }
}
/**
* Remove a student from a specific classroom (if they're in it)
+ *
+ * @param removedBy - Who initiated the removal: 'teacher' or 'self'
*/
-export async function leaveSpecificClassroom(playerId: string, classroomId: string): Promise {
- await db
+export async function leaveSpecificClassroom(
+ playerId: string,
+ classroomId: string,
+ removedBy: 'teacher' | 'self' = 'self'
+): Promise {
+ const deleted = await db
.delete(classroomPresence)
.where(
and(eq(classroomPresence.playerId, playerId), eq(classroomPresence.classroomId, classroomId))
)
+ .returning()
+
+ // Only emit if something was actually deleted
+ if (deleted.length > 0) {
+ const io = await getSocketIO()
+ if (io) {
+ const player = await db.query.players.findFirst({
+ where: eq(players.id, playerId),
+ })
+ // Notify the classroom (for teacher's view)
+ io.to(`classroom:${classroomId}`).emit('student-left', {
+ playerId,
+ playerName: player?.name ?? 'Unknown',
+ })
+ // Notify the player (for student's view)
+ io.to(`player:${playerId}`).emit('presence-removed', {
+ classroomId,
+ removedBy,
+ })
+ }
+ }
}
/**
diff --git a/apps/web/src/lib/classroom/socket-events.ts b/apps/web/src/lib/classroom/socket-events.ts
index 188f5a21..dc1136e2 100644
--- a/apps/web/src/lib/classroom/socket-events.ts
+++ b/apps/web/src/lib/classroom/socket-events.ts
@@ -51,6 +51,15 @@ export interface StudentLeftEvent {
playerName: string
}
+// ============================================================================
+// Player Presence Events (sent to player:${playerId} channel)
+// ============================================================================
+
+export interface PresenceRemovedEvent {
+ classroomId: string
+ removedBy: 'teacher' | 'self'
+}
+
// ============================================================================
// Session Observation Events (sent to session:${sessionId} channel)
// ============================================================================
@@ -108,10 +117,13 @@ export interface ClassroomServerToClientEvents {
'enrollment-approved': (data: EnrollmentApprovedEvent) => void
'enrollment-denied': (data: EnrollmentDeniedEvent) => void
- // Presence events
+ // Presence events (classroom channel)
'student-entered': (data: StudentEnteredEvent) => void
'student-left': (data: StudentLeftEvent) => void
+ // Player presence events (player channel)
+ 'presence-removed': (data: PresenceRemovedEvent) => void
+
// Session observation events
'practice-state': (data: PracticeStateEvent) => void
'tutorial-state': (data: TutorialStateEvent) => void
@@ -128,6 +140,8 @@ export interface ClassroomClientToServerEvents {
// Channel subscriptions
'join-classroom': (data: { classroomId: string }) => void
'leave-classroom': (data: { classroomId: string }) => void
+ 'join-player': (data: { playerId: string }) => void
+ 'leave-player': (data: { playerId: string }) => void
'observe-session': (data: { sessionId: string; observerId: string }) => void
'stop-observing': (data: { sessionId: string }) => void
diff --git a/apps/web/src/lib/queryKeys.ts b/apps/web/src/lib/queryKeys.ts
index 1a30eb89..2bc788cb 100644
--- a/apps/web/src/lib/queryKeys.ts
+++ b/apps/web/src/lib/queryKeys.ts
@@ -43,4 +43,5 @@ export const classroomKeys = {
detail: (id: string) => [...classroomKeys.all, 'detail', id] as const,
enrollments: (id: string) => [...classroomKeys.all, 'enrollments', id] as const,
presence: (id: string) => [...classroomKeys.all, 'presence', id] as const,
+ pendingParentApprovals: () => [...classroomKeys.all, 'pendingParentApprovals'] as const,
}
diff --git a/apps/web/src/lib/viewer.ts b/apps/web/src/lib/viewer.ts
index 218b4637..3c6fd4a7 100644
--- a/apps/web/src/lib/viewer.ts
+++ b/apps/web/src/lib/viewer.ts
@@ -1,5 +1,7 @@
+import { eq } from 'drizzle-orm'
import { cookies, headers } from 'next/headers'
import { auth } from '@/auth'
+import { db, schema } from '@/db'
import { GUEST_COOKIE_NAME, verifyGuestToken } from './guest-token'
/**
@@ -65,3 +67,89 @@ export async function getViewerId(): Promise {
throw new Error('No valid viewer session found')
}
}
+
+/**
+ * Get or create a user record from a guestId
+ *
+ * This is the core function for converting a guest session identifier
+ * into a database user record. If no user exists for the guestId,
+ * one is created automatically.
+ *
+ * @param guestId - The guest session identifier
+ * @returns The user record from the database
+ */
+async function getOrCreateUserFromGuestId(guestId: string) {
+ let user = await db.query.users.findFirst({
+ where: eq(schema.users.guestId, guestId),
+ })
+
+ if (!user) {
+ const [newUser] = await db.insert(schema.users).values({ guestId }).returning()
+ user = newUser
+ }
+
+ return user
+}
+
+/**
+ * Get the database user.id for the current viewer
+ *
+ * IMPORTANT: This returns the actual database user.id, NOT the guestId.
+ * Use this when you need to pass a user ID to authorization functions
+ * like canPerformAction(), or any function that expects a database user.id.
+ *
+ * For authenticated users: returns session.user.id directly
+ * For guests: looks up or creates the user record by guestId, returns user.id
+ * For unknown: throws an error
+ *
+ * @throws Error if no valid viewer found
+ */
+export async function getDbUserId(): Promise {
+ const viewer = await getViewer()
+
+ switch (viewer.kind) {
+ case 'user':
+ // Authenticated users already have a database user.id in their session
+ return viewer.session.user!.id
+ case 'guest': {
+ // Guests need to look up their user record by guestId
+ const user = await getOrCreateUserFromGuestId(viewer.guestId)
+ return user.id
+ }
+ case 'unknown':
+ throw new Error('No valid viewer session found')
+ }
+}
+
+/**
+ * Get the full user record for the current viewer
+ *
+ * This returns the complete database user record, useful when you need
+ * more than just the user.id (e.g., for checking user properties).
+ *
+ * For authenticated users: looks up user by session.user.id
+ * For guests: looks up or creates user by guestId
+ * For unknown: throws an error
+ *
+ * @throws Error if no valid viewer found
+ */
+export async function getViewerUser() {
+ const viewer = await getViewer()
+
+ switch (viewer.kind) {
+ case 'user': {
+ const user = await db.query.users.findFirst({
+ where: eq(schema.users.id, viewer.session.user!.id),
+ })
+ if (!user) {
+ throw new Error('Authenticated user not found in database')
+ }
+ return user
+ }
+ case 'guest': {
+ return getOrCreateUserFromGuestId(viewer.guestId)
+ }
+ case 'unknown':
+ throw new Error('No valid viewer session found')
+ }
+}
diff --git a/apps/web/src/socket-server.ts b/apps/web/src/socket-server.ts
index e6cbf502..d1227aa0 100644
--- a/apps/web/src/socket-server.ts
+++ b/apps/web/src/socket-server.ts
@@ -740,6 +740,26 @@ export function initializeSocketServer(httpServer: HTTPServer) {
}
})
+ // Player: Join player channel (for students to receive their own presence updates)
+ socket.on('join-player', async ({ playerId }: { playerId: string }) => {
+ try {
+ await socket.join(`player:${playerId}`)
+ console.log(`👤 User joined player channel: ${playerId}`)
+ } catch (error) {
+ console.error('Error joining player channel:', error)
+ }
+ })
+
+ // Player: Leave player channel
+ socket.on('leave-player', async ({ playerId }: { playerId: string }) => {
+ try {
+ await socket.leave(`player:${playerId}`)
+ console.log(`👤 User left player channel: ${playerId}`)
+ } catch (error) {
+ console.error('Error leaving player channel:', error)
+ }
+ })
+
// Session Observation: Start observing a practice session
socket.on(
'observe-session',