spine-framework 0.3.125 → 0.3.126

package/.framework/src/contexts/AuthContext.tsx

@@ -1,56 +1,72 @@
-/**
- * @module src/contexts/AuthContext
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * React authentication context and provider for the Spine frontend.
- * Manages the full Supabase auth lifecycle: initial session hydration,
- * login, logout, auth state change events, and a server-side user context
- * fetch (principal, account, roles, permissions).
- *
- * **Session hydration strategy:**
- * 1. On mount, restore user from `localStorage` with TTL/version check
- *    (cross-tab sync, survives page reloads without a loading flash)
- * 2. Always verify stored context with the server before rendering routes
- * 3. Subscribe to `supabase.auth.onAuthStateChange` for `SIGNED_IN`,
- *    `TOKEN_REFRESHED`, and `SIGNED_OUT` events
- *
- * **Race-condition guards:**
- * - `isLoggingIn` ref prevents `onAuthStateChange` from re-fetching context
- *   while `login()` is already in progress
- * - `onAuthStateChange` checks current user ref before async fetch
- * - `checkAuth` always verifies with server, even with stored user
- *
- * **Account scope:** Calls `setAccountId(userContext.account_id)` after
- * every successful context fetch, keeping `src/lib/api.ts` in sync.
- *
- * @seeAlso src/lib/supabase.ts (supabase client singleton)
- * @seeAlso src/lib/api.ts (setAccountId, apiFetch, onUnauthorized)
- * @seeAlso src/types/auth.ts (User shape)
- * @seeAlso functions/auth.ts (backend `/api/auth?action=context` endpoint)
- */
 
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="AuthContext_module_header_1783749485" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Auth module imports and constants"]
+// CIL[DOC-RESPONSIBILITY responsibility="Define React context types and storage constants"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-context" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/015_simplify_apps_table.sql\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="type definitions" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Sets up imports and storage constants for auth management" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-context. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/015_simplify_apps_table.sql, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/RolesPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React, { createContext, useContext, useEffect, useState, useRef, useCallback } from 'react'
 import { supabase } from '../lib/supabase'
 import { setAccountId, apiFetch, onUnauthorized } from '../lib/api'
 import { User } from '../types/auth'
 
-// ─── STORAGE ──────────────────────────────────────────────────────────────────
-
-/** Version stamp for stored user; bump when User shape changes */
 const STORAGE_VERSION = 1
 const STORAGE_KEY = 'spine_user'
-/** Max age (ms) before stored user is considered stale and discarded */
-const STORAGE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
-const SESSION_TIMEOUT_MS = 15000 // guard against stale Supabase sessions hanging on reload
-
+const STORAGE_TTL_MS = 24 * 60 * 60 * 1000
+const SESSION_TIMEOUT_MS = 15000
+// CIL[END chunk_id="AuthContext_module_header_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_storeduserenvelope_1783749485" type="interface" identity="StoredUserEnvelope" parent="none"]
+// CIL[DOC-MACRO purpose="Define stored user envelope interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for localStorage user storage"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-types" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Envelope wrapper for user data with version and timestamp" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-types. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface StoredUserEnvelope {
   version: number
   timestamp: number
   user: User
 }
-
+// CIL[END chunk_id="AuthContext_storeduserenvelope_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_readstoreduser_1783749485" type="function" identity="readStoredUser" parent="none"]
+// CIL[DOC-MACRO purpose="Read stored user from localStorage"]
+// CIL[DOC-RESPONSIBILITY responsibility="Retrieve and validate cached user data"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="User | null" errors="none" side_effects="localStorage read"]
+// CIL[DOC-MICRO logic_summary="Validates version and TTL before returning cached user" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 1. Direct calls: 0. Related files: \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function readStoredUser(): User | null {
   try {
     const raw = localStorage.getItem(STORAGE_KEY)
@@ -63,7 +79,21 @@ function readStoredUser(): User | null {
     return null
   }
 }
-
+// CIL[END chunk_id="AuthContext_readstoreduser_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_writestoreduser_1783749485" type="function" identity="writeStoredUser" parent="none"]
+// CIL[DOC-MACRO purpose="Write user to localStorage"]
+// CIL[DOC-RESPONSIBILITY responsibility="Cache user data with envelope wrapper"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="localStorage write"]
+// CIL[DOC-MICRO logic_summary="Stores user in envelope or removes entry if null" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 1. Direct calls: 0. Related files: custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 function writeStoredUser(user: User | null) {
   try {
     if (user) {
@@ -77,14 +107,23 @@ function writeStoredUser(user: User | null) {
       localStorage.removeItem(STORAGE_KEY)
     }
   } catch {
-    // Storage unavailable (private browsing, quota exceeded)
   }
 }
-
-/**
- * Wrapper around supabase.auth.getSession() that times out to prevent the
- * app from getting stuck on a corrupted/stale stored session.
- */
+// CIL[END chunk_id="AuthContext_writestoreduser_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_getsessionwithtimeout_1783749485" type="function" identity="getSessionWithTimeout" parent="none"]
+// CIL[DOC-MACRO purpose="Get Supabase session with timeout"]
+// CIL[DOC-RESPONSIBILITY responsibility="Prevent hanging on stale sessions"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[\".framework/src/pages/admin/RolesPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="session data" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Races session fetch against timeout to prevent hanging" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/RolesPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function getSessionWithTimeout(): Promise<{ data: { session: any | null } }> {
   try {
     return await Promise.race([
@@ -97,38 +136,45 @@ async function getSessionWithTimeout(): Promise<{ data: { session: any | null }
     return { data: { session: null } }
   }
 }
-
-// ─── TYPES ───────────────────────────────────────────────────────────────────
-
-/**
- * Shape of the value provided by `AuthContext`.
- *
- * @prop user - Resolved server-side user context, or null if unauthenticated
- * @prop isLoading - True during initial `checkAuth` (prevents premature redirects)
- * @prop login - Sign in with email/password and hydrate user context
- * @prop logout - Sign out and clear user + account scope
- * @prop refreshUser - Re-fetch user context from the server (e.g. after role change)
- */
+// CIL[END chunk_id="AuthContext_getsessionwithtimeout_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_authcontexttype_1783749485" type="interface" identity="AuthContextType" parent="none"]
+// CIL[DOC-MACRO purpose="Define auth context interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for auth context value"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-types" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Defines shape of auth context with user state and actions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-types. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface AuthContextType {
   user: User | null
   isLoading: boolean
-  login: (email: string, password: string) => Promise<void>
+  login: (email: string, password: string) => Promise<User | null>
   logout: () => Promise<void>
-  refreshUser: () => Promise<void>
+  refreshUser: () => Promise<User | null>
 }
 
 const AuthContext = createContext<AuthContextType | undefined>(undefined)
-
-// ─── useAuth ─────────────────────────────────────────────────────────────────
-
-/**
- * Hook to access the authentication context. Must be called inside `AuthProvider`.
- *
- * @returns `AuthContextType` — user, isLoading, login, logout, refreshUser
- * @throws Error('useAuth must be used within an AuthProvider') if called outside provider
- * @sideEffects none (read-only context access)
- * @calledBy every component that needs the current user or auth actions
- */
+// CIL[END chunk_id="AuthContext_authcontexttype_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_useauth_1783749485" type="function" identity="useAuth" parent="none"]
+// CIL[DOC-MACRO purpose="Access auth context hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide auth context to components"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="AuthContextType" errors="throws if no provider" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Returns auth context with safety check" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function useAuth() {
   const context = useContext(AuthContext)
   if (context === undefined) {
@@ -136,44 +182,54 @@ export function useAuth() {
   }
   return context
 }
-
+// CIL[END chunk_id="AuthContext_useauth_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_authproviderprops_1783749485" type="interface" identity="AuthProviderProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define auth provider props interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definition for AuthProvider component"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-types" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Simple props interface with only children" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-types. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface AuthProviderProps {
   children: React.ReactNode
 }
-
-// ─── INTERNAL HELPERS ───────────────────────────────────────────────────────────
-
-/**
- * Fetches the server-side user context from `GET /api/auth` with retry.
- * Returns null on any persistent error rather than throwing, so callers
- * can apply fallback logic without try/catch.
- *
- * Retries up to `maxRetries` times on network errors and 5xx responses.
- * Does NOT retry 401/403 (auth failures are not transient).
- *
- * @returns Resolved `User` object or null on failure
- * @throws never (all errors are caught internally)
- * @sideEffects Network request via apiFetch; console logging
- * @calledBy AuthProvider.login, AuthProvider.refreshUser, AuthProvider.checkAuth
- */
+// CIL[END chunk_id="AuthContext_authproviderprops_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_fetchusercontext_1783749485" type="function" identity="fetchUserContext" parent="none"]
+// CIL[DOC-MACRO purpose="Fetch user context with retry"]
+// CIL[DOC-RESPONSIBILITY responsibility="Get server-side user data with resilience"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-utility" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="User | null" errors="none" side_effects="API calls"]
+// CIL[DOC-MICRO logic_summary="Retries on network errors with exponential backoff" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-utility. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function fetchUserContext(maxRetries = 2): Promise<User | null> {
   let lastError: unknown = null
 
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
       if (attempt > 0) {
-        // Exponential backoff: 200ms, 800ms, 3200ms
         await new Promise(r => setTimeout(r, 200 * Math.pow(4, attempt - 1)))
       }
 
       const response = await apiFetch('/api/auth', { method: 'GET' })
 
-      // Don't retry auth failures
       if (response.status === 401 || response.status === 403) {
         return null
       }
 
-      // Retry on 5xx
       if (response.status >= 500) {
         lastError = new Error(`Server error: ${response.status}`)
         continue
@@ -188,45 +244,34 @@ async function fetchUserContext(maxRetries = 2): Promise<User | null> {
       return data.data
     } catch (error) {
       lastError = error
-      // Network error (TypeError: Failed to fetch) — retry
       if (error instanceof TypeError) continue
-      // Other errors — don't retry
       return null
     }
   }
   return null
 }
-
-// ─── AuthProvider ──────────────────────────────────────────────────────────────
-
-/**
- * Root authentication provider. Wrap the entire application with this component
- * to enable `useAuth()` in any descendant.
- *
- * @param children - React subtree to wrap
- * @sideEffects
- *   - Reads/writes `localStorage` key `spine_user` for persistence
- *   - Calls `setAccountId` (mutates `src/lib/api.ts` module state)
- *   - Subscribes to `supabase.auth.onAuthStateChange`; unsubscribes on unmount
- *   - Registers 401 interceptor via `onUnauthorized`
- * @calledBy src/main.tsx (app root)
- *
- * @example
- * ```tsx
- * <AuthProvider>
- *   <App />
- * </AuthProvider>
- * ```
- */
+// CIL[END chunk_id="AuthContext_fetchusercontext_1783749485"]
+// CIL[BEGIN chunk_id="AuthContext_authprovider_1783749485" type="function" identity="AuthProvider" parent="none"]
+// CIL[DOC-MACRO purpose="Manage authentication state and lifecycle"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle auth flow, storage sync, and session management"]
+// CIL[DOC-CONTEXT module="AuthContext" layer="frontend-provider" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Provider component" errors="auth errors" side_effects="localStorage, API calls, Supabase auth"]
+// CIL[DOC-MICRO logic_summary="Complex auth provider with storage sync, race guards, and cross-tab support" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-provider. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function AuthProvider({ children }: AuthProviderProps) {
   const storedUser = readStoredUser()
   const [user, setUser] = useState<User | null>(storedUser)
-  // If we have a stored user, start loading to verify context before rendering routes
   const [isLoading, setIsLoading] = useState(true)
   const isLoggingInRef = useRef(false)
   const userRef = useRef<User | null>(storedUser)
 
-  // Keep ref in sync with state so async callbacks see current value
   useEffect(() => { userRef.current = user }, [user])
 
   const setUserWithStorage = useCallback((u: User | null) => {
@@ -245,8 +290,6 @@ export function AuthProvider({ children }: AuthProviderProps) {
     setAccountId(ctx.account_id)
   }, [setUserWithStorage])
 
-  // ── Login ──────────────────────────────────────────────────────────────────
-
   const login = useCallback(async (email: string, password: string) => {
     isLoggingInRef.current = true
 
@@ -256,76 +299,69 @@ export function AuthProvider({ children }: AuthProviderProps) {
       if (error) throw error
 
       if (data.user) {
-        // Brief pause for session to establish
         await new Promise(resolve => setTimeout(resolve, 100))
 
         const userContext = await fetchUserContext()
         if (userContext) {
           applyUserContext(userContext)
+          return userContext
         } else {
-          // Fallback to minimal user object
-          applyUserContext({
+          const fallback: User = {
             id: data.user.id,
             email: data.user.email || '',
             full_name: data.user.user_metadata?.full_name || data.user.email || 'User',
             account_id: '',
             roles: [],
             permissions: [],
-          })
+          }
+          applyUserContext(fallback)
+          return fallback
         }
       }
+      return null
     } finally {
       isLoggingInRef.current = false
     }
   }, [applyUserContext])
 
-  // ── Logout ─────────────────────────────────────────────────────────────────
-
   const logout = useCallback(async () => {
     await supabase.auth.signOut()
     clearUser()
   }, [clearUser])
 
-  // ── Refresh ────────────────────────────────────────────────────────────────
-
   const refreshUser = useCallback(async () => {
     const { data: { session } } = await getSessionWithTimeout()
 
     if (!session?.user) {
       clearUser()
-      return
+      return null
     }
 
     const userContext = await fetchUserContext()
     if (userContext) {
       applyUserContext(userContext)
+      return userContext
     } else {
       clearUser()
+      return null
     }
   }, [applyUserContext, clearUser])
 
-  // ── Register 401 interceptor ───────────────────────────────────────────────
-
   useEffect(() => {
     const unregister = onUnauthorized(() => {
-      // Session expired — sign out cleanly
       supabase.auth.signOut().then(() => clearUser())
     })
     return unregister
   }, [clearUser])
 
-  // ── Listen for storage events from other tabs ──────────────────────────────
-
   useEffect(() => {
     const handleStorage = (e: StorageEvent) => {
       if (e.key !== STORAGE_KEY) return
       if (e.newValue === null) {
-        // Other tab logged out
         setUser(null)
         userRef.current = null
         setAccountId(null)
       } else {
-        // Other tab logged in or refreshed
         const parsed = readStoredUser()
         if (parsed) {
           setUser(parsed)
@@ -338,8 +374,6 @@ export function AuthProvider({ children }: AuthProviderProps) {
     return () => window.removeEventListener('storage', handleStorage)
   }, [])
 
-  // ── Initial auth check + subscription ──────────────────────────────────────
-
   useEffect(() => {
     let cancelled = false
 
@@ -358,14 +392,12 @@ export function AuthProvider({ children }: AuthProviderProps) {
         if (userContext) {
           applyUserContext(userContext)
         } else if (userRef.current) {
-          // Network issue but we have a stored user — keep it (offline resilience)
           setAccountId(userRef.current.account_id)
         } else {
           clearUser()
         }
       } catch (error) {
         if (!cancelled) {
-          // Network down with stored user — keep going (offline resilience)
           if (userRef.current) {
             setAccountId(userRef.current.account_id)
           } else {
@@ -379,19 +411,14 @@ export function AuthProvider({ children }: AuthProviderProps) {
 
     checkAuth()
 
-    // Listen for auth changes — async work is in the callback body, not
-    // inside a state updater (React anti-pattern)
     const { data: { subscription } } = supabase.auth.onAuthStateChange(
       async (event, session) => {
         if (cancelled) return
 
-        // Don't refresh during login to avoid conflicts
         if (isLoggingInRef.current) return
 
         if (event === 'SIGNED_IN' || event === 'TOKEN_REFRESHED') {
           if (!session?.user) return
-          // Skip re-fetch if user is already loaded — prevents blocking
-          // page fetches when Supabase re-fires SIGNED_IN on browser focus
           if (userRef.current) return
 
           const userContext = await fetchUserContext()
@@ -422,3 +449,4 @@ export function AuthProvider({ children }: AuthProviderProps) {
     </AuthContext.Provider>
   )
 }
+// CIL[END chunk_id="AuthContext_authprovider_1783749485"]

package/.framework/src/hooks/use-mobile.ts

@@ -1,7 +1,52 @@
-import * as React from "react"
 
-const MOBILE_BREAKPOINT = 768
 
+// CIL[BEGIN chunk_id="use-mobile_module_header_1783740744" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React library for mobile detection functionality"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide core React dependency for state management"]
+// CIL[DOC-CONTEXT module="use-mobile" layer="frontend-hook" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React library" errors="none" side_effects="Module imports"]
+// CIL[DOC-MICRO logic_summary="Imports React as namespace for hooks and component functionality" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+import * as React from "react"
+// CIL[END chunk_id="use-mobile_module_header_1783740744"]
+// CIL[BEGIN chunk_id="use-mobile_constants_1783740744" type="constant" identity="MOBILE_BREAKPOINT" parent="none"]
+// CIL[DOC-MACRO purpose="Define mobile screen breakpoint for responsive detection"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the mobile breakpoint threshold value"]
+// CIL[DOC-CONTEXT module="use-mobile" layer="frontend-hook" related_files="[\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="constant value" errors="none" side_effects="Constant definition"]
+// CIL[DOC-MICRO logic_summary="Sets mobile breakpoint at 768px for tablet/mobile boundary" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/pages/admin/IntegrationsPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+const MOBILE_BREAKPOINT = 768
+// CIL[END chunk_id="use-mobile_constants_1783740744"]
+// CIL[BEGIN chunk_id="use-mobile_useismobile_1783740744" type="function" identity="useIsMobile" parent="none"]
+// CIL[DOC-MACRO purpose="Detect mobile screen size with responsive breakpoint tracking"]
+// CIL[DOC-RESPONSIBILITY responsibility="Manage mobile detection state and media query listeners"]
+// CIL[DOC-CONTEXT module="use-mobile" layer="frontend-hook" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/components/ui/dialog.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="boolean mobile flag" errors="none" side_effects="MediaQuery event listeners"]
+// CIL[DOC-MICRO logic_summary="Uses matchMedia API to track screen width changes and update mobile state" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. Direct callers: 1. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/components/ui/dialog.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function useIsMobile() {
   const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
 
@@ -17,3 +62,4 @@ export function useIsMobile() {
 
   return !!isMobile
 }
+// CIL[END chunk_id="use-mobile_useismobile_1783740744"]