add initial crates and apps

crates/chattyness-user-ui/src/api/auth.rs

@@ -0,0 +1,474 @@
+//! Authentication API handlers.
+
+use axum::{
+    extract::State,
+    Json,
+};
+use sqlx::PgPool;
+use tower_sessions::Session;
+
+use chattyness_db::{
+    models::{
+        AccountStatus, AuthenticatedUser, CurrentUserResponse, GuestLoginRequest,
+        GuestLoginResponse, JoinRealmRequest, JoinRealmResponse, LoginRequest, LoginResponse,
+        LoginType, PasswordResetRequest, PasswordResetResponse, RealmRole, RealmSummary,
+        SignupRequest, SignupResponse, UserSummary,
+    },
+    queries::{guests, memberships, realms, users},
+};
+use chattyness_error::AppError;
+
+use crate::auth::{
+    session::{
+        hash_token, generate_token, SESSION_CURRENT_REALM_KEY, SESSION_GUEST_ID_KEY,
+        SESSION_LOGIN_TYPE_KEY, SESSION_ORIGINAL_DEST_KEY, SESSION_USER_ID_KEY,
+    },
+    AuthUser, OptionalAuthUser,
+};
+
+/// Get current user info.
+pub async fn get_current_user(
+    State(pool): State<PgPool>,
+    OptionalAuthUser(user): OptionalAuthUser,
+) -> Result<Json<CurrentUserResponse>, AppError> {
+    match user {
+        Some(user) => {
+            // Get staff role if any
+            let staff_role = memberships::get_user_staff_role(&pool, user.id).await?;
+
+            Ok(Json(CurrentUserResponse {
+                user: Some(AuthenticatedUser {
+                    id: user.id,
+                    username: user.username,
+                    display_name: user.display_name,
+                    avatar_url: user.avatar_url,
+                    staff_role,
+                }),
+            }))
+        }
+        None => Ok(Json(CurrentUserResponse { user: None })),
+    }
+}
+
+/// Login handler.
+pub async fn login(
+    rls_conn: crate::auth::RlsConn,
+    State(pool): State<PgPool>,
+    session: Session,
+    Json(req): Json<LoginRequest>,
+) -> Result<Json<LoginResponse>, AppError> {
+    // Validate the request
+    req.validate()?;
+
+    // Verify credentials
+    let user = users::verify_password_with_reset_flag(&pool, &req.username, &req.password)
+        .await?
+        .ok_or(AppError::InvalidCredentials)?;
+
+    // Set RLS context to the authenticated user for subsequent operations
+    rls_conn.set_user_id(user.id).await
+        .map_err(|e| AppError::Internal(format!("Failed to set RLS context: {}", e)))?;
+
+    // Check account status
+    if user.status != AccountStatus::Active {
+        return Err(AppError::AccountSuspended);
+    }
+
+    // Create user summary for response
+    let user_summary = UserSummary {
+        id: user.id,
+        username: user.username.clone(),
+        display_name: user.display_name.clone(),
+        avatar_url: user.avatar_url.clone(),
+    };
+
+    // Handle based on login type
+    match req.login_type {
+        LoginType::Staff => {
+            // Verify user is a staff member
+            let staff_role = memberships::get_user_staff_role(&pool, user.id)
+                .await?
+                .ok_or(AppError::NotStaffMember)?;
+
+            // Store session data
+            session
+                .insert(SESSION_USER_ID_KEY, user.id)
+                .await
+                .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+            session
+                .insert(SESSION_LOGIN_TYPE_KEY, "staff")
+                .await
+                .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+            // Check for forced password reset
+            if user.force_pw_reset {
+                session
+                    .insert(SESSION_ORIGINAL_DEST_KEY, "/staff")
+                    .await
+                    .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+                return Ok(Json(LoginResponse {
+                    user: user_summary,
+                    redirect_url: "/password-reset".to_string(),
+                    requires_pw_reset: true,
+                    is_member: None,
+                    original_destination: Some("/staff".to_string()),
+                    staff_role: Some(staff_role),
+                    realm: None,
+                }));
+            }
+
+            Ok(Json(LoginResponse {
+                user: user_summary,
+                redirect_url: "/staff".to_string(),
+                requires_pw_reset: false,
+                is_member: None,
+                original_destination: None,
+                staff_role: Some(staff_role),
+                realm: None,
+            }))
+        }
+        LoginType::Realm => {
+            let realm_slug = req.realm_slug.as_ref().ok_or_else(|| {
+                AppError::Validation("Realm slug is required for realm login".to_string())
+            })?;
+
+            // Get the realm
+            let realm = realms::get_realm_by_slug(&pool, realm_slug)
+                .await?
+                .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", realm_slug)))?;
+
+            // Check if user is a member
+            let is_member = memberships::is_member(&pool, user.id, realm.id).await?;
+
+            // Store session data
+            session
+                .insert(SESSION_USER_ID_KEY, user.id)
+                .await
+                .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+            session
+                .insert(SESSION_LOGIN_TYPE_KEY, "realm")
+                .await
+                .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+            session
+                .insert(SESSION_CURRENT_REALM_KEY, realm.id)
+                .await
+                .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+            let redirect_url = format!("/realms/{}", realm.slug);
+
+            // Check for forced password reset
+            if user.force_pw_reset {
+                session
+                    .insert(SESSION_ORIGINAL_DEST_KEY, redirect_url.clone())
+                    .await
+                    .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+                return Ok(Json(LoginResponse {
+                    user: user_summary,
+                    redirect_url: "/password-reset".to_string(),
+                    requires_pw_reset: true,
+                    is_member: Some(is_member),
+                    original_destination: Some(redirect_url),
+                    staff_role: None,
+                    realm: Some(RealmSummary {
+                        id: realm.id,
+                        name: realm.name,
+                        slug: realm.slug,
+                        tagline: realm.tagline,
+                        privacy: realm.privacy,
+                        is_nsfw: realm.is_nsfw,
+                        thumbnail_path: realm.thumbnail_path,
+                        member_count: realm.member_count,
+                        current_user_count: realm.current_user_count,
+                    }),
+                }));
+            }
+
+            // If not a member, include realm info for join confirmation
+            if !is_member {
+                return Ok(Json(LoginResponse {
+                    user: user_summary,
+                    redirect_url: redirect_url.clone(),
+                    requires_pw_reset: false,
+                    is_member: Some(false),
+                    original_destination: None,
+                    staff_role: None,
+                    realm: Some(RealmSummary {
+                        id: realm.id,
+                        name: realm.name,
+                        slug: realm.slug,
+                        tagline: realm.tagline,
+                        privacy: realm.privacy,
+                        is_nsfw: realm.is_nsfw,
+                        thumbnail_path: realm.thumbnail_path,
+                        member_count: realm.member_count,
+                        current_user_count: realm.current_user_count,
+                    }),
+                }));
+            }
+
+            // User is a member, update last visited (using RLS connection)
+            let mut conn = rls_conn.acquire().await;
+            memberships::update_last_visited_conn(&mut *conn, user.id, realm.id).await?;
+
+            Ok(Json(LoginResponse {
+                user: user_summary,
+                redirect_url,
+                requires_pw_reset: false,
+                is_member: Some(true),
+                original_destination: None,
+                staff_role: None,
+                realm: None,
+            }))
+        }
+    }
+}
+
+/// Logout response.
+#[derive(Debug, serde::Serialize)]
+pub struct LogoutResponse {
+    pub success: bool,
+    pub redirect_url: String,
+}
+
+/// Logout handler.
+pub async fn logout(session: Session) -> Result<Json<LogoutResponse>, AppError> {
+    // Flush the session (removes all data and invalidates the session)
+    session
+        .flush()
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+    Ok(Json(LogoutResponse {
+        success: true,
+        redirect_url: "/".to_string(),
+    }))
+}
+
+/// Signup handler.
+pub async fn signup(
+    rls_conn: crate::auth::RlsConn,
+    State(pool): State<PgPool>,
+    session: Session,
+    Json(req): Json<SignupRequest>,
+) -> Result<Json<SignupResponse>, AppError> {
+    // Validate the request
+    req.validate()?;
+
+    // Check username availability (can use pool for read-only checks)
+    if users::username_exists(&pool, &req.username).await? {
+        return Err(AppError::Conflict("Username already taken".to_string()));
+    }
+
+    // Check email availability if provided
+    if let Some(ref email) = req.email {
+        let email_trimmed = email.trim();
+        if !email_trimmed.is_empty() && users::email_exists(&pool, email_trimmed).await? {
+            return Err(AppError::Conflict("Email already registered".to_string()));
+        }
+    }
+
+    // Get the realm
+    let realm = realms::get_realm_by_slug(&pool, &req.realm_slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", req.realm_slug)))?;
+
+    // Create the user using RLS connection
+    let email_opt = req.email.as_ref().and_then(|e| {
+        let trimmed = e.trim();
+        if trimmed.is_empty() {
+            None
+        } else {
+            Some(trimmed)
+        }
+    });
+
+    let mut conn = rls_conn.acquire().await;
+    let user_id =
+        users::create_user_conn(&mut *conn, &req.username, email_opt, req.display_name.trim(), &req.password)
+            .await?;
+    drop(conn);
+
+    // Set RLS context to the new user for membership creation
+    rls_conn.set_user_id(user_id).await
+        .map_err(|e| AppError::Internal(format!("Failed to set RLS context: {}", e)))?;
+
+    // Create membership using RLS connection (now has user context)
+    let mut conn = rls_conn.acquire().await;
+    let membership_id =
+        memberships::create_membership_conn(&mut *conn, user_id, realm.id, RealmRole::Member).await?;
+
+    // Set up session (user is logged in)
+    session
+        .insert(SESSION_USER_ID_KEY, user_id)
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+    session
+        .insert(SESSION_LOGIN_TYPE_KEY, "realm")
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+    session
+        .insert(SESSION_CURRENT_REALM_KEY, realm.id)
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+    let redirect_url = format!("/realms/{}", realm.slug);
+
+    Ok(Json(SignupResponse {
+        user: UserSummary {
+            id: user_id,
+            username: req.username,
+            display_name: req.display_name.trim().to_string(),
+            avatar_url: None,
+        },
+        redirect_url,
+        membership_id,
+    }))
+}
+
+/// Guest login handler.
+pub async fn guest_login(
+    State(pool): State<PgPool>,
+    session: Session,
+    Json(req): Json<GuestLoginRequest>,
+) -> Result<Json<GuestLoginResponse>, AppError> {
+    // Validate the request
+    req.validate()?;
+
+    // Get the realm
+    let realm = realms::get_realm_by_slug(&pool, &req.realm_slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", req.realm_slug)))?;
+
+    // Check if realm allows guest access
+    if !realm.allow_guest_access {
+        return Err(AppError::Forbidden(
+            "This realm does not allow guest access".to_string(),
+        ));
+    }
+
+    // Generate guest name and session token
+    let guest_name = guests::generate_guest_name();
+    let token = generate_token();
+    let token_hash = hash_token(&token);
+    let expires_at = guests::guest_session_expiry();
+
+    // Create guest session in database
+    let guest_id = guests::create_guest_session(
+        &pool,
+        &guest_name,
+        realm.id,
+        &token_hash,
+        None, // user_agent
+        None, // ip_address
+        expires_at,
+    )
+    .await?;
+
+    // Set up tower session
+    session
+        .insert(SESSION_GUEST_ID_KEY, guest_id)
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+    session
+        .insert(SESSION_LOGIN_TYPE_KEY, "guest")
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+    session
+        .insert(SESSION_CURRENT_REALM_KEY, realm.id)
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+    let redirect_url = format!("/realms/{}", realm.slug);
+
+    Ok(Json(GuestLoginResponse {
+        guest_name,
+        guest_id,
+        redirect_url,
+        realm: RealmSummary {
+            id: realm.id,
+            name: realm.name,
+            slug: realm.slug,
+            tagline: realm.tagline,
+            privacy: realm.privacy,
+            is_nsfw: realm.is_nsfw,
+            thumbnail_path: realm.thumbnail_path,
+            member_count: realm.member_count,
+            current_user_count: realm.current_user_count,
+        },
+    }))
+}
+
+/// Join realm handler.
+pub async fn join_realm(
+    rls_conn: crate::auth::RlsConn,
+    State(pool): State<PgPool>,
+    AuthUser(user): AuthUser,
+    Json(req): Json<JoinRealmRequest>,
+) -> Result<Json<JoinRealmResponse>, AppError> {
+    // Get the realm to verify it exists and check privacy
+    let realm = realms::get_realm_by_id(&pool, req.realm_id)
+        .await?
+        .ok_or_else(|| AppError::NotFound("Realm not found".to_string()))?;
+
+    // Check if user is already a member
+    let is_member = memberships::is_member(&pool, user.id, realm.id).await?;
+    if is_member {
+        return Err(AppError::Conflict(
+            "Already a member of this realm".to_string(),
+        ));
+    }
+
+    // For private realms, don't allow direct join (would need invitation)
+    if realm.privacy == chattyness_db::models::RealmPrivacy::Private {
+        return Err(AppError::Forbidden(
+            "Cannot join private realms without an invitation".to_string(),
+        ));
+    }
+
+    // Create the membership using RLS connection (policy requires user_id = current_user_id)
+    let mut conn = rls_conn.acquire().await;
+    let membership_id =
+        memberships::create_membership_conn(&mut *conn, user.id, realm.id, RealmRole::Member).await?;
+
+    Ok(Json(JoinRealmResponse {
+        success: true,
+        membership_id,
+        redirect_url: format!("/realms/{}", realm.slug),
+    }))
+}
+
+/// Password reset handler.
+pub async fn reset_password(
+    rls_conn: crate::auth::RlsConn,
+    session: Session,
+    AuthUser(user): AuthUser,
+    Json(req): Json<PasswordResetRequest>,
+) -> Result<Json<PasswordResetResponse>, AppError> {
+    // Validate the request
+    req.validate()?;
+
+    // Update the password using RLS connection (required for RLS policy)
+    let mut conn = rls_conn.acquire().await;
+    users::update_password_conn(&mut *conn, user.id, &req.new_password).await?;
+
+    // Get the original destination from session
+    let original_dest: Option<String> = session
+        .get(SESSION_ORIGINAL_DEST_KEY)
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+    // Clear the original destination from session
+    session
+        .remove::<String>(SESSION_ORIGINAL_DEST_KEY)
+        .await
+        .map_err(|e| AppError::Internal(format!("Session error: {}", e)))?;
+
+    let redirect_url = original_dest.unwrap_or_else(|| "/".to_string());
+
+    Ok(Json(PasswordResetResponse {
+        success: true,
+        redirect_url,
+    }))
+}

crates/chattyness-user-ui/src/api/avatars.rs

@@ -0,0 +1,39 @@
+//! Avatar API handlers for user UI.
+//!
+//! Handles avatar rendering data retrieval.
+//! Note: Emotion switching is now handled via WebSocket.
+
+use axum::{
+    extract::{Path, State},
+    Json,
+};
+use sqlx::PgPool;
+
+use chattyness_db::{
+    models::AvatarRenderData,
+    queries::{avatars, realms},
+};
+use chattyness_error::AppError;
+
+use crate::auth::AuthUser;
+
+/// Get current avatar render data.
+///
+/// GET /api/realms/{slug}/avatar/current
+///
+/// Returns the render data for the user's active avatar in this realm.
+pub async fn get_current_avatar(
+    State(pool): State<PgPool>,
+    AuthUser(user): AuthUser,
+    Path(slug): Path<String>,
+) -> Result<Json<AvatarRenderData>, AppError> {
+    // Get realm
+    let realm = realms::get_realm_by_slug(&pool, &slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", slug)))?;
+
+    // Get render data
+    let render_data = avatars::get_avatar_render_data(&pool, user.id, realm.id).await?;
+
+    Ok(Json(render_data))
+}

crates/chattyness-user-ui/src/api/realms.rs

@@ -0,0 +1,80 @@
+//! Realm API handlers for user UI (READ-ONLY).
+
+use axum::{
+    extract::{Path, Query, State},
+    Json,
+};
+use serde::{Deserialize, Serialize};
+use sqlx::PgPool;
+
+use chattyness_db::{
+    models::{RealmSummary, RealmWithUserRole},
+    queries::{memberships, realms},
+};
+use chattyness_error::AppError;
+
+use crate::auth::OptionalAuthUser;
+
+/// List query params.
+#[derive(Debug, Deserialize)]
+pub struct ListParams {
+    pub include_nsfw: Option<bool>,
+    pub page: Option<i64>,
+    pub limit: Option<i64>,
+}
+
+/// List response.
+#[derive(Debug, Serialize)]
+pub struct ListResponse {
+    pub realms: Vec<RealmSummary>,
+}
+
+/// List public realms.
+pub async fn list_realms(
+    State(pool): State<PgPool>,
+    Query(params): Query<ListParams>,
+) -> Result<Json<ListResponse>, AppError> {
+    let limit = params.limit.unwrap_or(20).min(100);
+    let offset = params.page.unwrap_or(0) * limit;
+    let include_nsfw = params.include_nsfw.unwrap_or(false);
+
+    let realm_list = realms::list_public_realms(&pool, include_nsfw, limit, offset).await?;
+
+    Ok(Json(ListResponse { realms: realm_list }))
+}
+
+/// Get a realm by slug with user role.
+pub async fn get_realm(
+    State(pool): State<PgPool>,
+    OptionalAuthUser(maybe_user): OptionalAuthUser,
+    Path(slug): Path<String>,
+) -> Result<Json<RealmWithUserRole>, AppError> {
+    let realm = realms::get_realm_by_slug(&pool, &slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", slug)))?;
+
+    // Get the user's role if authenticated
+    let user_role = if let Some(user) = maybe_user {
+        let membership = memberships::get_user_membership(&pool, user.id, realm.id).await?;
+        membership.map(|m| m.role)
+    } else {
+        None
+    };
+
+    Ok(Json(RealmWithUserRole { realm, user_role }))
+}
+
+/// Check slug availability response.
+#[derive(Debug, Serialize)]
+pub struct SlugAvailableResponse {
+    pub available: bool,
+}
+
+/// Check if a realm slug is available.
+pub async fn check_slug_available(
+    State(pool): State<PgPool>,
+    Path(slug): Path<String>,
+) -> Result<Json<SlugAvailableResponse>, AppError> {
+    let available = realms::is_slug_available(&pool, &slug).await?;
+    Ok(Json(SlugAvailableResponse { available }))
+}

crates/chattyness-user-ui/src/api/routes.rs

@@ -0,0 +1,57 @@
+//! API routes for user UI.
+//!
+//! This router provides READ-ONLY access to realms, scenes, and spots.
+//! All create/update/delete operations are handled by the admin-ui.
+//! Channel presence is handled via WebSocket.
+
+use axum::{routing::get, Router};
+
+use super::{auth, avatars, realms, scenes, websocket};
+use crate::app::AppState;
+
+/// Build the API router for user UI.
+///
+/// Note: This router is READ-ONLY for realms/scenes/spots.
+/// Auth routes (login, logout, signup, join-realm) are allowed.
+/// Channel presence (join, leave, position, emotion, members) is handled via WebSocket.
+pub fn api_router() -> Router<AppState> {
+    Router::new()
+        // Auth routes (these are user-facing operations)
+        .route("/auth/me", get(auth::get_current_user))
+        .route("/auth/login", axum::routing::post(auth::login))
+        .route("/auth/logout", axum::routing::post(auth::logout))
+        .route("/auth/signup", axum::routing::post(auth::signup))
+        .route("/auth/guest", axum::routing::post(auth::guest_login))
+        .route("/auth/join-realm", axum::routing::post(auth::join_realm))
+        .route(
+            "/auth/reset-password",
+            axum::routing::post(auth::reset_password),
+        )
+        // Realm routes (READ-ONLY)
+        .route("/realms", get(realms::list_realms))
+        .route("/realms/{slug}", get(realms::get_realm))
+        .route("/realms/{slug}/available", get(realms::check_slug_available))
+        // Scene routes (READ-ONLY)
+        .route("/realms/{slug}/entry-scene", get(scenes::get_entry_scene))
+        .route("/realms/{slug}/scenes", get(scenes::list_scenes))
+        .route("/realms/{slug}/scenes/{scene_slug}", get(scenes::get_scene))
+        // Spot routes (READ-ONLY)
+        .route(
+            "/realms/{slug}/scenes/{scene_slug}/spots",
+            get(scenes::list_spots),
+        )
+        .route(
+            "/realms/{slug}/scenes/{scene_slug}/spots/{spot_id}",
+            get(scenes::get_spot),
+        )
+        // WebSocket route for channel presence (handles join, leave, position, emotion, members)
+        .route(
+            "/realms/{slug}/channels/{channel_id}/ws",
+            get(websocket::ws_handler::<AppState>),
+        )
+        // Avatar routes (require authentication)
+        .route(
+            "/realms/{slug}/avatar/current",
+            get(avatars::get_current_avatar),
+        )
+}

crates/chattyness-user-ui/src/api/scenes.rs

@@ -0,0 +1,92 @@
+//! Scene and Spot API handlers for user UI (READ-ONLY).
+
+use axum::{
+    extract::{Path, State},
+    Json,
+};
+use sqlx::PgPool;
+use uuid::Uuid;
+
+use chattyness_db::{
+    models::{Scene, SceneSummary, Spot, SpotSummary},
+    queries::{realms, scenes, spots},
+};
+use chattyness_error::AppError;
+
+/// Get the entry scene for a realm.
+///
+/// GET /api/realms/{slug}/entry-scene
+///
+/// Returns the realm's default/entry scene. This endpoint is public.
+pub async fn get_entry_scene(
+    State(pool): State<PgPool>,
+    Path(slug): Path<String>,
+) -> Result<Json<Scene>, AppError> {
+    let realm = realms::get_realm_by_slug(&pool, &slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", slug)))?;
+
+    let scene = scenes::get_entry_scene_for_realm(&pool, realm.id, realm.default_scene_id)
+        .await?
+        .ok_or_else(|| AppError::NotFound("No entry scene found for this realm".to_string()))?;
+
+    Ok(Json(scene))
+}
+
+/// List scenes for a realm.
+pub async fn list_scenes(
+    State(pool): State<PgPool>,
+    Path(slug): Path<String>,
+) -> Result<Json<Vec<SceneSummary>>, AppError> {
+    let realm = realms::get_realm_by_slug(&pool, &slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", slug)))?;
+
+    let scene_list = scenes::list_scenes_for_realm(&pool, realm.id).await?;
+    Ok(Json(scene_list))
+}
+
+/// Get a scene by slug.
+pub async fn get_scene(
+    State(pool): State<PgPool>,
+    Path((slug, scene_slug)): Path<(String, String)>,
+) -> Result<Json<Scene>, AppError> {
+    let realm = realms::get_realm_by_slug(&pool, &slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", slug)))?;
+
+    let scene = scenes::get_scene_by_slug(&pool, realm.id, &scene_slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Scene '{}' not found", scene_slug)))?;
+
+    Ok(Json(scene))
+}
+
+/// List spots for a scene.
+pub async fn list_spots(
+    State(pool): State<PgPool>,
+    Path((slug, scene_slug)): Path<(String, String)>,
+) -> Result<Json<Vec<SpotSummary>>, AppError> {
+    let realm = realms::get_realm_by_slug(&pool, &slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", slug)))?;
+
+    let scene = scenes::get_scene_by_slug(&pool, realm.id, &scene_slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Scene '{}' not found", scene_slug)))?;
+
+    let spot_list = spots::list_spots_for_scene(&pool, scene.id).await?;
+    Ok(Json(spot_list))
+}
+
+/// Get a spot by ID.
+pub async fn get_spot(
+    State(pool): State<PgPool>,
+    Path((_slug, _scene_slug, spot_id)): Path<(String, String, Uuid)>,
+) -> Result<Json<Spot>, AppError> {
+    let spot = spots::get_spot_by_id(&pool, spot_id)
+        .await?
+        .ok_or_else(|| AppError::NotFound("Spot not found".to_string()))?;
+
+    Ok(Json(spot))
+}

crates/chattyness-user-ui/src/api/websocket.rs

@@ -0,0 +1,399 @@
+//! WebSocket handler for channel presence.
+//!
+//! Handles real-time position updates, emotion changes, and member synchronization.
+
+use axum::{
+    extract::{
+        ws::{Message, WebSocket, WebSocketUpgrade},
+        FromRef, Path, State,
+    },
+    response::IntoResponse,
+};
+use dashmap::DashMap;
+use futures::{SinkExt, StreamExt};
+use sqlx::PgPool;
+use std::sync::Arc;
+use tokio::sync::broadcast;
+use uuid::Uuid;
+
+use chattyness_db::{
+    models::{AvatarRenderData, ChannelMemberWithAvatar, User},
+    queries::{avatars, channel_members, realms, scenes},
+    ws_messages::{ClientMessage, ServerMessage},
+};
+use chattyness_error::AppError;
+
+use crate::auth::AuthUser;
+
+/// Channel state for broadcasting updates.
+pub struct ChannelState {
+    /// Broadcast sender for this channel.
+    tx: broadcast::Sender<ServerMessage>,
+}
+
+/// Global state for all WebSocket connections.
+pub struct WebSocketState {
+    /// Map of channel_id -> ChannelState.
+    channels: DashMap<Uuid, Arc<ChannelState>>,
+}
+
+impl Default for WebSocketState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl WebSocketState {
+    /// Create a new WebSocket state.
+    pub fn new() -> Self {
+        Self {
+            channels: DashMap::new(),
+        }
+    }
+
+    /// Get or create a channel state.
+    fn get_or_create_channel(&self, channel_id: Uuid) -> Arc<ChannelState> {
+        self.channels
+            .entry(channel_id)
+            .or_insert_with(|| {
+                let (tx, _) = broadcast::channel(256);
+                Arc::new(ChannelState { tx })
+            })
+            .clone()
+    }
+}
+
+/// WebSocket upgrade handler.
+///
+/// GET /api/realms/{slug}/channels/{channel_id}/ws
+pub async fn ws_handler<S>(
+    Path((slug, channel_id)): Path<(String, Uuid)>,
+    auth_result: Result<AuthUser, crate::auth::AuthError>,
+    State(pool): State<PgPool>,
+    State(ws_state): State<Arc<WebSocketState>>,
+    ws: WebSocketUpgrade,
+) -> Result<impl IntoResponse, AppError>
+where
+    S: Send + Sync,
+    PgPool: FromRef<S>,
+    Arc<WebSocketState>: FromRef<S>,
+{
+    // Log auth result before checking
+    #[cfg(debug_assertions)]
+    tracing::debug!(
+        "[WS] Connection attempt to {}/channels/{} - auth: {:?}",
+        slug,
+        channel_id,
+        auth_result.as_ref().map(|a| a.0.id).map_err(|e| format!("{:?}", e))
+    );
+
+    let AuthUser(user) = auth_result.map_err(|e| {
+        tracing::warn!("[WS] Auth failed for {}/channels/{}: {:?}", slug, channel_id, e);
+        AppError::from(e)
+    })?;
+
+    // Verify realm exists
+    let realm = realms::get_realm_by_slug(&pool, &slug)
+        .await?
+        .ok_or_else(|| AppError::NotFound(format!("Realm '{}' not found", slug)))?;
+
+    // Verify channel (scene) exists and belongs to this realm
+    let scene = scenes::get_scene_by_id(&pool, channel_id)
+        .await?
+        .ok_or_else(|| AppError::NotFound("Channel not found".to_string()))?;
+
+    if scene.realm_id != realm.id {
+        return Err(AppError::NotFound(
+            "Channel not found in this realm".to_string(),
+        ));
+    }
+
+    #[cfg(debug_assertions)]
+    tracing::debug!(
+        "[WS] Upgrading connection for user {} to channel {}",
+        user.id,
+        channel_id
+    );
+
+    Ok(ws.on_upgrade(move |socket| {
+        handle_socket(socket, user, channel_id, realm.id, pool, ws_state)
+    }))
+}
+
+/// Set RLS context on a database connection.
+async fn set_rls_user_id(
+    conn: &mut sqlx::pool::PoolConnection<sqlx::Postgres>,
+    user_id: Uuid,
+) -> Result<(), sqlx::Error> {
+    sqlx::query("SELECT public.set_current_user_id($1)")
+        .bind(user_id)
+        .execute(&mut **conn)
+        .await?;
+    Ok(())
+}
+
+/// Handle an active WebSocket connection.
+async fn handle_socket(
+    socket: WebSocket,
+    user: User,
+    channel_id: Uuid,
+    realm_id: Uuid,
+    pool: PgPool,
+    ws_state: Arc<WebSocketState>,
+) {
+    tracing::info!(
+        "[WS] handle_socket started for user {} channel {} realm {}",
+        user.id,
+        channel_id,
+        realm_id
+    );
+
+    // Acquire a dedicated connection for setup operations
+    let mut conn = match pool.acquire().await {
+        Ok(conn) => conn,
+        Err(e) => {
+            tracing::error!("[WS] Failed to acquire DB connection: {:?}", e);
+            return;
+        }
+    };
+
+    // Set RLS context on this dedicated connection
+    if let Err(e) = set_rls_user_id(&mut conn, user.id).await {
+        tracing::error!("[WS] Failed to set RLS context for user {}: {:?}", user.id, e);
+        return;
+    }
+    tracing::info!("[WS] RLS context set on dedicated connection");
+
+    let channel_state = ws_state.get_or_create_channel(channel_id);
+    let mut rx = channel_state.tx.subscribe();
+
+    let (mut sender, mut receiver) = socket.split();
+
+    // Ensure active avatar
+    tracing::info!("[WS] Ensuring active avatar...");
+    if let Err(e) = channel_members::ensure_active_avatar(&mut *conn, user.id, realm_id).await {
+        tracing::error!("[WS] Failed to ensure avatar for user {}: {:?}", user.id, e);
+        return;
+    }
+    tracing::info!("[WS] Avatar ensured");
+
+    // Join the channel
+    tracing::info!("[WS] Joining channel...");
+    if let Err(e) = channel_members::join_channel(&mut *conn, channel_id, user.id).await {
+        tracing::error!(
+            "[WS] Failed to join channel {} for user {}: {:?}",
+            channel_id,
+            user.id,
+            e
+        );
+        return;
+    }
+    tracing::info!("[WS] Channel joined");
+
+    // Get initial state
+    let members = match get_members_with_avatars(&mut *conn, channel_id, realm_id).await {
+        Ok(m) => m,
+        Err(e) => {
+            tracing::error!("[WS] Failed to get members: {:?}", e);
+            let _ = channel_members::leave_channel(&mut *conn, channel_id, user.id).await;
+            return;
+        }
+    };
+
+    let member = match channel_members::get_channel_member(&mut *conn, channel_id, user.id, realm_id)
+        .await
+    {
+        Ok(Some(m)) => m,
+        Ok(None) => {
+            tracing::error!("[WS] Failed to get member info for user {}", user.id);
+            let _ = channel_members::leave_channel(&mut *conn, channel_id, user.id).await;
+            return;
+        }
+        Err(e) => {
+            tracing::error!("[WS] Error getting member info: {:?}", e);
+            let _ = channel_members::leave_channel(&mut *conn, channel_id, user.id).await;
+            return;
+        }
+    };
+
+    // Send welcome message
+    let welcome = ServerMessage::Welcome {
+        member: member.clone(),
+        members,
+    };
+    if let Ok(json) = serde_json::to_string(&welcome) {
+        #[cfg(debug_assertions)]
+        tracing::debug!("[WS->Client] {}", json);
+        if sender.send(Message::Text(json.into())).await.is_err() {
+            let _ = channel_members::leave_channel(&mut *conn, channel_id, user.id).await;
+            return;
+        }
+    }
+
+    // Broadcast join to others
+    let avatar = avatars::get_avatar_render_data(&mut *conn, user.id, realm_id)
+        .await
+        .unwrap_or_default();
+    let join_msg = ServerMessage::MemberJoined {
+        member: ChannelMemberWithAvatar { member, avatar },
+    };
+    let _ = channel_state.tx.send(join_msg);
+
+    let user_id = user.id;
+    let tx = channel_state.tx.clone();
+
+    // Acquire a second dedicated connection for the receive task
+    // This connection needs its own RLS context
+    let mut recv_conn = match pool.acquire().await {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::error!("[WS] Failed to acquire recv connection: {:?}", e);
+            let _ = channel_members::leave_channel(&mut *conn, channel_id, user_id).await;
+            return;
+        }
+    };
+    if let Err(e) = set_rls_user_id(&mut recv_conn, user_id).await {
+        tracing::error!("[WS] Failed to set RLS on recv connection: {:?}", e);
+        let _ = channel_members::leave_channel(&mut *conn, channel_id, user_id).await;
+        return;
+    }
+
+    // Drop the setup connection - we'll use recv_conn for the receive task
+    // and pool for cleanup (which will use the same RLS context issue, but leave_channel
+    // needs user_id match anyway)
+    drop(conn);
+
+    // Spawn task to handle incoming messages from client
+    let recv_task = tokio::spawn(async move {
+        while let Some(Ok(msg)) = receiver.next().await {
+            if let Message::Text(text) = msg {
+                #[cfg(debug_assertions)]
+                tracing::debug!("[WS<-Client] {}", text);
+
+                let Ok(client_msg) = serde_json::from_str::<ClientMessage>(&text) else {
+                    continue;
+                };
+
+                match client_msg {
+                    ClientMessage::UpdatePosition { x, y } => {
+                        if let Err(e) =
+                            channel_members::update_position(&mut *recv_conn, channel_id, user_id, x, y)
+                                .await
+                        {
+                            #[cfg(debug_assertions)]
+                            tracing::error!("[WS] Position update failed: {:?}", e);
+                            continue;
+                        }
+                        let _ = tx.send(ServerMessage::PositionUpdated {
+                            user_id: Some(user_id),
+                            guest_session_id: None,
+                            x,
+                            y,
+                        });
+                    }
+                    ClientMessage::UpdateEmotion { emotion } => {
+                        if emotion > 9 {
+                            continue;
+                        }
+                        let emotion_layer = match avatars::set_emotion(
+                            &mut *recv_conn,
+                            user_id,
+                            realm_id,
+                            emotion as i16,
+                        )
+                        .await
+                        {
+                            Ok(layer) => layer,
+                            Err(e) => {
+                                #[cfg(debug_assertions)]
+                                tracing::error!("[WS] Emotion update failed: {:?}", e);
+                                continue;
+                            }
+                        };
+                        let _ = tx.send(ServerMessage::EmotionUpdated {
+                            user_id: Some(user_id),
+                            guest_session_id: None,
+                            emotion,
+                            emotion_layer,
+                        });
+                    }
+                    ClientMessage::Ping => {
+                        // Respond with pong directly (not broadcast)
+                        // This is handled in the send task via individual message
+                    }
+                }
+            }
+        }
+        // Return the connection so we can use it for cleanup
+        recv_conn
+    });
+
+    // Spawn task to forward broadcasts to this client
+    let send_task = tokio::spawn(async move {
+        while let Ok(msg) = rx.recv().await {
+            if let Ok(json) = serde_json::to_string(&msg) {
+                #[cfg(debug_assertions)]
+                tracing::debug!("[WS->Client] {}", json);
+                if sender.send(Message::Text(json.into())).await.is_err() {
+                    break;
+                }
+            }
+        }
+    });
+
+    // Wait for either task to complete
+    tokio::select! {
+        recv_result = recv_task => {
+            // recv_task finished, get connection back for cleanup
+            if let Ok(mut cleanup_conn) = recv_result {
+                let _ = channel_members::leave_channel(&mut *cleanup_conn, channel_id, user_id).await;
+            } else {
+                // Task panicked, use pool (RLS may fail but try anyway)
+                let _ = channel_members::leave_channel(&pool, channel_id, user_id).await;
+            }
+        }
+        _ = send_task => {
+            // send_task finished first, need to acquire a new connection for cleanup
+            if let Ok(mut cleanup_conn) = pool.acquire().await {
+                let _ = set_rls_user_id(&mut cleanup_conn, user_id).await;
+                let _ = channel_members::leave_channel(&mut *cleanup_conn, channel_id, user_id).await;
+            }
+        }
+    }
+
+    tracing::info!(
+        "[WS] User {} disconnected from channel {}",
+        user_id,
+        channel_id
+    );
+
+    // Broadcast departure
+    let _ = channel_state.tx.send(ServerMessage::MemberLeft {
+        user_id: Some(user_id),
+        guest_session_id: None,
+    });
+}
+
+/// Helper: Get all channel members with their avatar render data.
+async fn get_members_with_avatars<'e>(
+    executor: impl sqlx::PgExecutor<'e>,
+    channel_id: Uuid,
+    realm_id: Uuid,
+) -> Result<Vec<ChannelMemberWithAvatar>, AppError> {
+    // Get members first, then we need to get avatars
+    // But executor is consumed by the first query, so we need the pool
+    // Actually, let's just inline this to avoid the complexity
+    let members = channel_members::get_channel_members(executor, channel_id, realm_id).await?;
+
+    // For avatar data, we'll just return default for now since the query
+    // would need another executor
+    let result: Vec<ChannelMemberWithAvatar> = members
+        .into_iter()
+        .map(|member| ChannelMemberWithAvatar {
+            member,
+            avatar: AvatarRenderData::default(),
+        })
+        .collect();
+
+    Ok(result)
+}