CLAUDE: Fix Safari/iPad WebSocket connection issues

- Changed cookie SameSite policy from Lax to None with Secure=true
  for Safari ITP compatibility
- Fixed Nuxt composable context issue: moved useRuntimeConfig() from
  connect() callback to composable setup phase (required in Nuxt 4)
- Added GET /logout endpoint for easy browser-based logout
- Improved loading overlay with clear status indicators and action
  buttons (Retry, Re-Login, Dismiss)
- Added error handling with try-catch in WebSocket connect()
- Documented issue and fixes in .claude/SAFARI_WEBSOCKET_ISSUE.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/SAFARI_WEBSOCKET_ISSUE.md

@@ -0,0 +1,65 @@
+# Safari/iPad WebSocket Connection Issue
+
+## Problem Summary
+
+WebSocket connections intermittently fail on iPad Safari while working reliably on desktop browsers.
+
+**Pattern:**
+- Works initially after login
+- Randomly fails (minutes to hours later)
+- "Fixes itself" during debugging (suggesting cache/timing issues)
+- Desktop browsers never have this problem
+
+## Root Causes Identified
+
+### 1. Cookie SameSite Policy (Fixed 2025-11-28)
+Safari's ITP treats `SameSite=Lax` differently than Chrome/Firefox. Safari may not send cookies with fetch/XHR even on same-origin.
+
+**Fix:** Changed to `SameSite=None; Secure=true` in `backend/app/utils/cookies.py`
+
+### 2. Nuxt Composable Context Issue (Fixed 2025-11-28)
+`useRuntimeConfig()` was being called inside `connect()` function, which is invoked from:
+- `onMounted` hooks (valid context)
+- `setInterval` callbacks (INVALID context)
+
+In Nuxt 4, composables MUST be called during component setup, not inside callbacks.
+
+**Fix:** Moved `useRuntimeConfig()` to composable setup phase in `useWebSocket.ts`
+
+### 3. Potential Safari-Specific Issues (Not Yet Fixed)
+
+- **Safari ITP**: Can expire cookies unpredictably
+- **iOS Memory Management**: Safari may clear JS state when backgrounded
+- **Cached Old Code**: Safari may aggressively cache outdated JS bundles
+
+## Files Modified
+
+1. `backend/app/utils/cookies.py` - Cookie SameSite policy
+2. `frontend-sba/composables/useWebSocket.ts` - Composable context fix
+3. `backend/app/api/routes/auth.py` - Added GET /logout endpoint
+
+## Prevention Strategies
+
+### Short-term (Implemented)
+- Stuck state detector every 5 seconds
+- Multiple retry mechanisms in websocket.client.ts plugin
+- Error logging in connect() function
+
+### Long-term (Consider Implementing)
+1. **Token in WebSocket URL**: Pass short-lived auth token as query param (fallback if cookies fail)
+2. **Connection health indicator**: Visible UI showing connection state, not just loading spinner
+3. **Automatic logout/re-login flow**: If connection fails repeatedly, redirect to login
+
+## Debugging Steps
+
+1. Check backend logs: `tail -f logs/backend.log | grep -E "auth|Cookie|WebSocket"`
+2. Check browser console for `[WebSocket]` prefixed logs
+3. Verify cookies exist: Safari Settings > Advanced > Website Data > gameplay-demo.manticorum.com
+4. Force cache clear: Close Safari completely, reopen
+
+## History
+
+| Date | Issue | Fix | Result |
+|------|-------|-----|--------|
+| 2025-11-28 | SameSite=Lax not working on Safari | Changed to SameSite=None | Worked initially |
+| 2025-11-28 | useRuntimeConfig in callback | Moved to setup phase | Connected |

backend/app/api/routes/auth.py

@@ -526,6 +526,7 @@ async def verify_auth(authorization: str = Header(None)):
         return {"authenticated": False}
 
 
+@router.get("/logout")
 @router.post("/logout")
 async def logout(response: Response) -> dict:
     """

backend/app/utils/cookies.py

@@ -24,18 +24,15 @@ def is_secure_context() -> bool:
     """
     Check if cookies should use Secure flag.
 
-    Returns True if:
+    Returns True ONLY if APP_ENV is 'production'.
-    - APP_ENV is 'production', OR
-    - FRONTEND_URL starts with 'https://'
 
-    This ensures cookies work correctly when accessing via HTTPS
+    In development, we don't set Secure flag even if FRONTEND_URL is HTTPS,
-    even in development mode.
+    because the WebSocket may connect to localhost (HTTP) and secure cookies
+    won't be sent over HTTP connections.
+
+    For production deployments behind HTTPS reverse proxy, set APP_ENV=production.
     """
-    if getattr(settings, "app_env", "development") == "production":
+    return getattr(settings, "app_env", "development") == "production"
-        return True
-    # Also enable Secure if frontend URL is HTTPS (common in dev with tunnels/proxies)
-    frontend_url = getattr(settings, "frontend_url", "")
-    return frontend_url.startswith("https://")
 
 
 def set_auth_cookies(
@@ -48,24 +45,28 @@ def set_auth_cookies(
 
     Security settings:
     - HttpOnly: Prevents XSS access to tokens
-    - Secure: HTTPS only in production
+    - Secure: True (required for SameSite=None)
-    - SameSite=Lax: CSRF protection while allowing top-level navigations
+    - SameSite=None: Required for Safari to send cookies with fetch/XHR requests
     - Path: Limits cookie scope
 
+    Note: Safari's ITP treats SameSite=Lax cookies as "not sent" for XHR/fetch
+    requests even on same-origin. SameSite=None with Secure=true fixes this.
+
     Args:
         response: FastAPI Response object
         access_token: JWT access token
         refresh_token: JWT refresh token
     """
     # Access token - short-lived, sent to all requests (needed for SSR cookie forwarding)
+    # Using SameSite=None for Safari compatibility (requires Secure=true)
     response.set_cookie(
         key=ACCESS_TOKEN_COOKIE,
         value=access_token,
         max_age=ACCESS_TOKEN_MAX_AGE,
         httponly=True,
-        secure=is_secure_context(),
+        secure=True,  # Required for SameSite=None
-        samesite="lax",
+        samesite="none",  # Safari requires this for fetch() to include cookies
-        path="/",  # Root path so cookies are sent with all requests including SSR
+        path="/",
     )
 
     # Refresh token - long-lived, restricted to auth endpoints only
@@ -74,8 +75,8 @@ def set_auth_cookies(
         value=refresh_token,
         max_age=REFRESH_TOKEN_MAX_AGE,
         httponly=True,
-        secure=is_secure_context(),
+        secure=True,  # Required for SameSite=None
-        samesite="lax",
+        samesite="none",  # Safari requires this for fetch() to include cookies
         path="/api/auth",
     )
 

frontend-sba/composables/useWebSocket.ts

@@ -45,6 +45,13 @@ const lastConnectionAttempt = ref<number | null>(null)
 export function useWebSocket() {
   // State is now module-level singleton (above)
 
+  // ============================================================================
+  // Configuration (MUST be called during setup, not inside callbacks)
+  // ============================================================================
+
+  const config = useRuntimeConfig()
+  const wsUrl = config.public.wsUrl
+
   // ============================================================================
   // Stores
   // ============================================================================
@@ -81,10 +88,9 @@ export function useWebSocket() {
    * Connect to WebSocket server with JWT authentication
    */
   function connect() {
-    if (!canConnect.value) {
+    // REMOVED: Auth guard - let backend authenticate via cookies
-      console.warn('[WebSocket] Cannot connect: not authenticated or token invalid')
+    // The auth store state may not sync properly from SSR to client,
-      return
+    // but cookies ARE sent automatically. Backend will reject if invalid.
-    }
 
     if (isConnected.value || isConnecting.value) {
       console.warn('[WebSocket] Already connected or connecting')
@@ -95,25 +101,27 @@ export function useWebSocket() {
     connectionError.value = null
     lastConnectionAttempt.value = Date.now()
 
-    const config = useRuntimeConfig()
-    const wsUrl = config.public.wsUrl
-
     console.log('[WebSocket] Connecting to', wsUrl)
 
-    // Create or reuse socket instance
+    try {
-    if (!socketInstance) {
+      // Create or reuse socket instance
-      socketInstance = io(wsUrl, {
+      if (!socketInstance) {
-        withCredentials: true, // Send cookies automatically
+        socketInstance = io(wsUrl, {
-        autoConnect: false,
+          withCredentials: true, // Send cookies automatically
-        reconnection: false, // We handle reconnection manually for better control
+          autoConnect: false,
-        transports: ['websocket', 'polling'],
+          reconnection: false, // We handle reconnection manually for better control
-      })
+          transports: ['websocket', 'polling'],
+        })
 
-      setupEventListeners()
+        setupEventListeners()
+      }
+
+      socketInstance.connect()
+    } catch (err) {
+      console.error('[WebSocket] Connection error:', err)
+      isConnecting.value = false
+      connectionError.value = err instanceof Error ? err.message : 'Connection failed'
     }
-
-    // Connect
-    socketInstance.connect()
   }
 
   /**
@@ -217,6 +225,11 @@ export function useWebSocket() {
       connectionError.value = null
       reconnectionAttempts = 0
 
+      // Update global flag for plugin failsafe
+      if (typeof window !== 'undefined') {
+        window.__ws_connected = true
+      }
+
       // Update game store
       gameStore.setConnected(true)
 
@@ -229,6 +242,11 @@ export function useWebSocket() {
       isConnected.value = false
       isConnecting.value = false
 
+      // Update global flag for plugin failsafe
+      if (typeof window !== 'undefined') {
+        window.__ws_connected = false
+      }
+
       // Update game store
       gameStore.setConnected(false)
 
@@ -518,6 +536,34 @@ export function useWebSocket() {
     }
   )
 
+  // ============================================================================
+  // Stuck State Detection
+  // ============================================================================
+
+  // Detects when auth is true but connection hasn't happened (race condition fallback)
+  let stuckStateCheckInterval: NodeJS.Timeout | null = null
+
+  function startStuckStateDetection() {
+    if (stuckStateCheckInterval) return
+
+    stuckStateCheckInterval = setInterval(() => {
+      // Try to connect if not connected - don't check auth state
+      // Backend will authenticate via cookies
+      if (!isConnected.value && !isConnecting.value) {
+        console.warn('[WebSocket] STUCK STATE DETECTED: Not connected. Attempting connect...')
+        connect()
+        startHeartbeat()
+      }
+    }, 5000) // Check every 5 seconds
+  }
+
+  function stopStuckStateDetection() {
+    if (stuckStateCheckInterval) {
+      clearInterval(stuckStateCheckInterval)
+      stuckStateCheckInterval = null
+    }
+  }
+
   // ============================================================================
   // Lifecycle
   // ============================================================================
@@ -526,6 +572,9 @@ export function useWebSocket() {
   onMounted(async () => {
     console.log('[WebSocket] onMounted - isAuthenticated:', authStore.isAuthenticated)
 
+    // Start stuck state detection to catch race conditions
+    startStuckStateDetection()
+
     // If not authenticated, try to check auth first (handles SSR hydration case)
     if (!authStore.isAuthenticated) {
       console.log('[WebSocket] Not authenticated on mount, checking auth...')
@@ -543,6 +592,7 @@ export function useWebSocket() {
   onUnmounted(() => {
     console.log('[WebSocket] Component unmounted, cleaning up')
     stopHeartbeat()
+    stopStuckStateDetection()
     // Don't disconnect on unmount - keep connection alive for app
     // Only disconnect when explicitly requested or user logs out
   })

frontend-sba/pages/games/[id].vue

@@ -31,12 +31,6 @@
               <p class="text-sm text-yellow-700">
                 {{ connectionStatus === 'connecting' ? 'Connecting to game server...' : 'Disconnected from server. Attempting to reconnect...' }}
               </p>
-              <!-- Debug info -->
-              <p class="text-xs text-yellow-600 mt-1">
-                Auth: {{ authStore.isAuthenticated ? 'Yes' : 'No' }} |
-                Connecting: {{ isConnecting ? 'Yes' : 'No' }} |
-                Error: {{ connectionError || 'None' }}
-              </p>
             </div>
           </div>
           <button
@@ -180,24 +174,56 @@
         v-if="isLoading"
         class="fixed inset-0 bg-black/50 backdrop-blur-sm flex items-center justify-center z-50"
       >
-        <div class="bg-white dark:bg-gray-800 rounded-xl p-8 shadow-2xl text-center">
+        <div class="bg-white dark:bg-gray-800 rounded-xl p-8 shadow-2xl text-center max-w-sm mx-4">
-          <div class="w-16 h-16 mx-auto mb-4 border-4 border-primary border-t-transparent rounded-full animate-spin"/>
+          <!-- Show spinner only if actively connecting -->
-          <p class="text-gray-900 dark:text-white font-semibold">Loading game...</p>
+          <div v-if="isConnecting" class="w-16 h-16 mx-auto mb-4 border-4 border-primary border-t-transparent rounded-full animate-spin"/>
-          <!-- Debug info -->
+
-          <p class="text-xs text-gray-500 mt-4">
+          <!-- Show error state if not connecting -->
-            Auth: {{ authStore.isAuthenticated ? 'Yes' : 'No' }} |
+          <div v-else class="w-16 h-16 mx-auto mb-4 bg-red-100 dark:bg-red-900 rounded-full flex items-center justify-center">
-            Connected: {{ isConnected ? 'Yes' : 'No' }} |
+            <svg xmlns="http://www.w3.org/2000/svg" class="h-8 w-8 text-red-600 dark:text-red-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-            Connecting: {{ isConnecting ? 'Yes' : 'No' }}
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+            </svg>
+          </div>
+
+          <p class="text-gray-900 dark:text-white font-semibold">
+            {{ isConnecting ? 'Connecting to game...' : 'Connection Failed' }}
           </p>
-          <p class="text-xs text-gray-500 mt-1">
+
-            Error: {{ connectionError || 'None' }}
+          <!-- Status info -->
-          </p>
+          <div class="mt-4 p-3 bg-gray-100 dark:bg-gray-700 rounded-lg text-left">
-          <button
+            <div class="flex items-center gap-2 text-sm">
-            @click="retryWithAuth"
+              <span :class="authStore.isAuthenticated ? 'text-green-600' : 'text-red-600'">●</span>
-            class="mt-4 px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition"
+              <span class="text-gray-700 dark:text-gray-300">Auth: {{ authStore.isAuthenticated ? 'OK' : 'Failed' }}</span>
-          >
+            </div>
-            Retry Connection
+            <div class="flex items-center gap-2 text-sm mt-1">
-          </button>
+              <span :class="isConnected ? 'text-green-600' : isConnecting ? 'text-yellow-600' : 'text-red-600'">●</span>
+              <span class="text-gray-700 dark:text-gray-300">WebSocket: {{ isConnected ? 'Connected' : isConnecting ? 'Connecting...' : 'Disconnected' }}</span>
+            </div>
+            <p v-if="connectionError" class="text-xs text-red-600 mt-2">{{ connectionError }}</p>
+          </div>
+
+          <!-- Action buttons -->
+          <div class="mt-4 flex flex-col gap-2">
+            <button
+              @click="forceReconnect"
+              class="w-full px-4 py-2 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-lg transition"
+            >
+              Retry Connection
+            </button>
+            <button
+              v-if="!authStore.isAuthenticated"
+              @click="navigateTo('/auth/login?return_url=' + encodeURIComponent($route.fullPath))"
+              class="w-full px-4 py-2 text-sm font-medium text-gray-700 dark:text-gray-200 bg-gray-200 dark:bg-gray-600 hover:bg-gray-300 dark:hover:bg-gray-500 rounded-lg transition"
+            >
+              Re-Login
+            </button>
+            <button
+              @click="isLoading = false"
+              class="w-full px-4 py-2 text-sm font-medium text-gray-500 hover:text-gray-700 dark:hover:text-gray-300 transition"
+            >
+              Dismiss (view page anyway)
+            </button>
+          </div>
         </div>
       </div>
 
@@ -631,22 +657,16 @@ const updateScoreBoardHeight = () => {
 
 // Lifecycle
 onMounted(async () => {
-  console.log('[Game Page] Mounted for game:', gameId.value)
+  // Try to connect WebSocket immediately - cookies will be sent automatically
-
+  // Backend will authenticate via cookies and reject if invalid
-  // Verify authentication via cookies
+  if (!isConnected.value && !isConnecting.value) {
-  const isAuthed = await authStore.checkAuth()
+    connect()
-  console.log('[Game Page] Auth check - isAuthenticated:', authStore.isAuthenticated)
-
-  if (!isAuthed) {
-    console.warn('[Game Page] Not authenticated - redirecting to login')
-    navigateTo('/auth/login?redirect=' + encodeURIComponent(route.fullPath))
-    return
   }
 
-  console.log('[Game Page] Authenticated as:', authStore.currentUser?.username)
+  // Also check auth store (for display purposes)
+  authStore.checkAuth()
 
-  // WebSocket auto-connects via watch on isAuthenticated in useWebSocket composable
+  // Wait for connection, then join game
-  // Just wait for connection, then join game
   watch(isConnected, async (connected) => {
     if (connected) {
       connectionStatus.value = 'connected'