User opens chat → spinner → GET /api/chats/{id}?limit=50 → render messages
User switches to another chat → clear all messages → spinner → full fetch again
User switches back → clear again → spinner → same 50 messages re-fetched

                    ┌─────────────────────────┐
                    │     React Component      │
                    │   useChatMessages hook   │
                    └────────┬────────────────┘
                             │ reads from
                    ┌────────▼────────────────┐
                    │     React Query Cache    │
                    │  (in-memory, per-chat)   │
                    │  staleTime: 2 min        │
                    │  gcTime: 30 min          │
                    └────────┬────────────────┘
                             │ hydrates from / persists to
                    ┌────────▼────────────────┐
                    │      IndexedDB           │
                    │  (idb-keyval or Dexie)   │
                    │  per-chat message store  │
                    │  survives tab close      │
                    └────────┬────────────────┘
                             │ revalidates against
                    ┌────────▼────────────────┐
                    │     API + SSE            │
                    │  GET /api/chats/{id}     │
                    │  SSE new_message events  │
                    └─────────────────────────┘

// apps/web/src/hooks/useChatMessages.ts — new approach

import { useQuery, useQueryClient } from '@tanstack/react-query';

const MESSAGES_STALE_TIME = 2 * 60 * 1000;  // 2 min — overrides global 1 min default
const MESSAGES_GC_TIME = 30 * 60 * 1000;    // 30 min — keep old chats in memory

interface ChatMessagesData {
  messages: ChatMessage[];
  hasMore: boolean;
  nextCursor: string | null;
}

// The query fetches initial messages from the API
const query = useQuery<ChatMessagesData>({
  queryKey: ['chat-messages', chatId],
  queryFn: async ({ signal }) => {
    const token = await getSafeAccessToken();
    const response = await fetch(
      `/api/chats/${chatId}?limit=${CHAT_PAGE_SIZE}`,
      { headers: { Authorization: `Bearer ${token}` }, signal }
    );
    const data = await response.json();
    const formatted = (data.messages as RawApiMessage[]).map((msg) =>
      formatMessage(msg, chatId!)
    );
    return {
      messages: formatted,
      hasMore: data.pagination?.hasMore ?? false,
      nextCursor: data.pagination?.nextCursor ?? null,
    };
  },
  enabled: !!chatId,
  staleTime: MESSAGES_STALE_TIME,
  gcTime: MESSAGES_GC_TIME,
  // Show previous chat's data while loading new chat (prevents flash)
  placeholderData: (prev) => prev,
});

const queryClient = useQueryClient();

function handleNewMessage(newMessage: ChatMessage) {
  queryClient.setQueryData<ChatMessagesData>(
    ['chat-messages', chatId],
    (old) => {
      if (!old) return old;
      // Dedup / replace optimistic
      const updatedMessages = replaceOptimisticMessage(old.messages, newMessage);
      return { ...old, messages: updatedMessages };
    }
  );
}

function addOptimisticMessage(message: ChatMessage) {
  queryClient.setQueryData<ChatMessagesData>(
    ['chat-messages', chatId],
    (old) => {
      if (!old) return { messages: [message], hasMore: false, nextCursor: null };
      return { ...old, messages: [...old.messages, message] };
    }
  );
}

setChatDetails({ ...data, chat: data.chat, messages: data.messages, participants: data.participants });

setChatDetails({ ...data, chat: data.chat, messages: [], participants: data.participants });
// messages are managed by useChatMessages via React Query — don't duplicate

const loadMore = useCallback(async () => {
  const currentData = queryClient.getQueryData<ChatMessagesData>(['chat-messages', chatId]);
  if (!chatId || !currentData?.nextCursor || isLoadingMore) return;

  setIsLoadingMore(true);
  const token = await getSafeAccessToken();
  const response = await fetch(
    `/api/chats/${chatId}?cursor=${currentData.nextCursor}&limit=${CHAT_PAGE_SIZE}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  const data = await response.json();
  const formatted = (data.messages as RawApiMessage[]).map((msg) => formatMessage(msg, chatId));

  queryClient.setQueryData<ChatMessagesData>(['chat-messages', chatId], (old) => {
    if (!old) return old;
    return {
      messages: [...formatted, ...old.messages], // prepend older messages
      hasMore: data.pagination?.hasMore ?? false,
      nextCursor: data.pagination?.nextCursor ?? null,
    };
  });
  setIsLoadingMore(false);
}, [chatId, isLoadingMore, getSafeAccessToken, queryClient]);

refetchInterval: isConnected ? false : 15_000, // Only poll when SSE is disconnected

cd apps/web && bun add idb-keyval

// apps/web/src/lib/chat/message-store.ts

import { get, set, del } from 'idb-keyval';

const MAX_CACHED_MESSAGES_PER_CHAT = 100; // Keep last 100 messages per chat
const MAX_CACHED_CHATS = 50;              // Limit total stored chats

interface CachedChatMessages {
  chatId: string;
  messages: ChatMessage[];
  hasMore: boolean;
  nextCursor: string | null;
  cachedAt: number; // timestamp for LRU eviction
}

const STORE_KEY_PREFIX = 'chat-msgs:';
const INDEX_KEY = 'chat-msgs-index'; // tracks which chats are cached

export async function getCachedMessages(
  chatId: string
): Promise<CachedChatMessages | null> {
  const cached = await get<CachedChatMessages>(`${STORE_KEY_PREFIX}${chatId}`);
  return cached ?? null;
}

export async function setCachedMessages(
  chatId: string,
  data: CachedChatMessages
): Promise<void> {
  // Trim to max messages
  const trimmed = {
    ...data,
    messages: data.messages.slice(-MAX_CACHED_MESSAGES_PER_CHAT),
    cachedAt: Date.now(),
  };
  await set(`${STORE_KEY_PREFIX}${chatId}`, trimmed);

  // Update index and evict old chats if over limit
  const index = (await get<string[]>(INDEX_KEY)) ?? [];
  const updated = [chatId, ...index.filter((id) => id !== chatId)];
  if (updated.length > MAX_CACHED_CHATS) {
    const evicted = updated.splice(MAX_CACHED_CHATS);
    await Promise.all(evicted.map((id) => del(`${STORE_KEY_PREFIX}${id}`)));
  }
  await set(INDEX_KEY, updated);
}

export async function appendCachedMessages(
  chatId: string,
  newMessages: ChatMessage[]
): Promise<void> {
  const existing = await getCachedMessages(chatId);
  if (!existing) return;

  const existingIds = new Set(existing.messages.map((m) => m.id));
  const deduped = newMessages.filter((m) => !existingIds.has(m.id));
  if (deduped.length === 0) return;

  await setCachedMessages(chatId, {
    ...existing,
    messages: [...existing.messages, ...deduped],
  });
}

// apps/web/src/lib/chat/hydrateChatCache.ts
// Called once during app startup (e.g., in Providers.tsx or a layout effect)

import { QueryClient } from '@tanstack/react-query';
import { getCachedMessages } from './message-store';
import { get } from 'idb-keyval';

const INDEX_KEY = 'chat-msgs-index';

export async function hydrateChatCacheFromIndexedDB(queryClient: QueryClient) {
  const index = await get<string[]>(INDEX_KEY);
  if (!index || index.length === 0) return;

  // Hydrate the 10 most recent chats (don't block startup with all 50)
  const recentChatIds = index.slice(0, 10);
  await Promise.all(
    recentChatIds.map(async (chatId) => {
      const cached = await getCachedMessages(chatId);
      if (!cached) return;
      queryClient.setQueryData(['chat-messages', chatId], {
        messages: cached.messages,
        hasMore: cached.hasMore,
        nextCursor: cached.nextCursor,
      });
      // Mark as stale so React Query revalidates in background
      queryClient.invalidateQueries({
        queryKey: ['chat-messages', chatId],
        refetchType: 'none', // don't trigger refetch, just mark stale
      });
    })
  );
}

// In Providers.tsx, after QueryClient creation:
const [queryClient] = useState(() => {
  const client = new QueryClient({ /* ... */ });
  // Fire-and-forget — doesn't block render
  void hydrateChatCacheFromIndexedDB(client);
  return client;
});

// In useChatMessages, after the useQuery:
useEffect(() => {
  if (chatId && query.data && query.data.messages.length > 0) {
    // Fire-and-forget — don't block renders
    void setCachedMessages(chatId, {
      chatId,
      ...query.data,
      cachedAt: Date.now(),
    });
  }
}, [chatId, query.data]);

1. User opens Chat A:
   → IndexedDB has 80 cached messages from last session
   → Render immediately (no spinner)
   → React Query fetches latest 50 from API in background
   → Merge: keep cached history + append any new messages
   → User sees seamless conversation with no loading state

2. User closes tab, reopens next day:
   → Same flow — IndexedDB still has the messages
   → API fetch brings in messages since last visit
   → Old messages are already rendered, new ones appear at bottom

// New query parameter alongside existing cursor/limit (around line 105)
const after = searchParams.get('after'); // ISO timestamp

// New code path — MUTUALLY EXCLUSIVE with cursor pagination
if (after) {
  const afterDate = new Date(after);
  // Validate the date
  if (isNaN(afterDate.getTime())) {
    return NextResponse.json({ error: 'Invalid after timestamp' }, { status: 400 });
  }

  // Fetch messages AFTER the given timestamp, ordered ASC (oldest first)
  // Cap at limit to prevent unbounded result sets
  messagesList = await db
    .select()
    .from(messages)
    .where(
      and(
        eq(messages.chatId, chatId),
        gt(messages.createdAt, afterDate)
      )
    )
    .orderBy(asc(messages.createdAt))
    .limit(effectiveLimit);

  // No pagination trick needed — we want all new messages up to limit
  hasMore = false; // caller should re-fetch if they got exactly `limit` results
  nextCursor = null;

  // Response includes a flag so the client knows this is a sync response
  // and should APPEND rather than REPLACE
} else if (cursor) {
  // ... existing cursor pagination code unchanged ...
}

// Called by refetchInterval callback or SSE reconnect
async function syncNewMessages(chatId: string) {
  const currentData = queryClient.getQueryData<ChatMessagesData>(['chat-messages', chatId]);
  const lastMessage = currentData?.messages?.at(-1);
  if (!lastMessage) return; // no cache = do a full refetch instead

  const token = await getSafeAccessToken();
  const response = await fetch(
    `/api/chats/${chatId}?after=${encodeURIComponent(lastMessage.createdAt)}&limit=${CHAT_PAGE_SIZE}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  if (!response.ok) return;

  const data = await response.json();
  const newMessages = (data.messages as RawApiMessage[]).map((msg) =>
    formatMessage(msg, chatId)
  );

  if (newMessages.length === 0) return; // nothing new

  queryClient.setQueryData<ChatMessagesData>(['chat-messages', chatId], (old) => {
    if (!old) return old;
    // Dedup: skip any messages already in cache
    const existingIds = new Set(old.messages.map((m) => m.id));
    const deduped = newMessages.filter((m) => !existingIds.has(m.id));
    if (deduped.length === 0) return old;
    return { ...old, messages: [...old.messages, ...deduped] };
  });
}

// Only when SSE is disconnected
useEffect(() => {
  if (isConnected || !chatId) return;
  const interval = setInterval(() => syncNewMessages(chatId), 15_000);
  return () => clearInterval(interval);
}, [isConnected, chatId]);

import { useQuery, useQueryClient } from '@tanstack/react-query';

const chatListQuery = useQuery({
  queryKey: ['chat-list'],
  queryFn: async () => {
    const token = await getAccessToken();
    const response = await fetch('/api/chats', {
      headers: { Authorization: `Bearer ${token}` },
    });
    const data = await response.json();
    return [
      ...(data.groupChats || []),
      ...(data.directChats || []),
    ].sort((a, b) => {
      const aTime = a.lastMessage?.createdAt || a.updatedAt;
      const bTime = b.lastMessage?.createdAt || b.updatedAt;
      return new Date(bTime).getTime() - new Date(aTime).getTime();
    });
  },
  staleTime: 30_000,  // 30s — chat list changes when new messages arrive
  gcTime: 10 * 60_000, // 10 min
  refetchOnWindowFocus: true,
});

// In the SSE handler for the current chat:
queryClient.setQueryData<Chat[]>(['chat-list'], (old) => {
  if (!old) return old;
  return old
    .map((chat) =>
      chat.id === incomingMessage.chatId
        ? { ...chat, lastMessage: { content: incomingMessage.content, createdAt: incomingMessage.createdAt, senderId: incomingMessage.senderId } }
        : chat
    )
    .sort((a, b) => {
      const aTime = a.lastMessage?.createdAt || a.updatedAt;
      const bTime = b.lastMessage?.createdAt || b.updatedAt;
      return new Date(bTime).getTime() - new Date(aTime).getTime();
    });
});

refetchInterval: isConnected ? false : 15_000,

// In useSSEChannel reconnect handler:
useEffect(() => {
  if (isConnected && chatId) {
    // SSE just reconnected — sync any missed messages
    queryClient.invalidateQueries({ queryKey: ['chat-messages', chatId] });
  }
}, [isConnected, chatId]);

Phase 1 (Core — eliminates chat-switch spinners):
  WI-M1: React Query for in-memory message caching
    ↓
Phase 2 (Persistence + Efficiency):
  WI-M2: IndexedDB for cross-session persistence  ← parallel
  WI-M3: Incremental sync (since parameter)       ← parallel
    ↓
Phase 3 (Polish):
  WI-M4: Cache conversation list
  WI-M5: Smart polling (SSE-aware)

# Quality gate
bun run check && bun run typecheck && bun run lint

# Tests
bun run test:unit

# Build
bun run build

# Manual validation
# 1. Open Chat A → spinner on first load → messages appear
# 2. Switch to Chat B → spinner (first visit)
# 3. Switch back to Chat A → INSTANT (React Query cache, no spinner)
# 4. Send a message in Chat A → appears immediately (optimistic)
# 5. Receive a message via SSE → appears in real-time
# 6. Close the browser tab completely
# 7. Reopen, navigate to Chat A → INSTANT (IndexedDB) + background sync
# 8. Check Network tab: background revalidation uses ?since= parameter
# 9. Disconnect SSE (throttle network) → polling starts at 15s
# 10. Reconnect SSE → immediate sync of missed messages, polling stops
# 11. Open chat page (inbox) → INSTANT on second visit (cached list)
# 12. Receive message in Chat B while viewing Chat A → Chat B moves to top of list