Chat App (e.g. Messenger)

Conversation metadata (1000 convos × 200B) = ~200KB
Active message windows (30 convos × 100 msgs × 500B) = ~1.5MB
Media thumbnails in DOM (50 visible × 50KB) = ~2.5MB
WebSocket buffers = ~50KB
Zustand/Redux state overhead = ~500KB
IndexedDB offline queue = disk, not RAM
─────────────────────────────────────────────────
Total working memory: ~5–10MB (well within budget)

/chat                    → Conversation list (no conversation selected)
/chat/:conversationId    → Active conversation thread
/chat/:conversationId/info → Conversation details/settings
/chat/new                → New message composer

<ChatApp>
├── <ConversationList>
│   ├── <SearchBar />
│   ├── <ConversationItem />  (virtualized, 1000+)
│   │   ├── <Avatar /> + <PresenceIndicator />
│   │   ├── <LastMessage />
│   │   └── <UnreadBadge />
│   └── <ConversationListSkeleton />
├── <MessageThread>
│   ├── <MessageList />  (virtualized, bidirectional)
│   │   ├── <MessageBubble />
│   │   │   ├── <MessageContent /> (text/media/file)
│   │   │   ├── <MessageReactions />
│   │   │   ├── <MessageStatus /> (sent/delivered/read)
│   │   │   └── <ReplyPreview />
│   │   ├── <DateSeparator />
│   │   └── <SystemMessage />
│   ├── <TypingIndicator />
│   └── <ScrollToBottomFAB />
├── <Composer>
│   ├── <TextInput /> (contenteditable with mentions)
│   ├── <MediaAttachmentPreview />
│   ├── <EmojiPicker />
│   └── <SendButton />
└── <ConnectionStatus />  (offline banner)

// Normalized store shape (conceptual)
interface ChatStore {
  // Entities (normalized by ID)
  conversations: Record<string, Conversation>;
  messages: Record<string, Message>;
  participants: Record<string, Participant>;

  // Real-time state
  presence: Record<string, PresenceState>;
  typing: Record<string, TypingState[]>;

  // UI state
  activeConversationId: string | null;
  messageWindows: Record<string, MessageWindow>;

  // Offline
  outbox: OutboxMessage[];
}

// Core message entity
interface Message {
  id: string; // Server-assigned unique ID
  clientId: string; // Client-generated idempotency key (UUIDv4)
  conversationId: string; // Parent conversation
  senderId: string; // Author user ID
  content: MessageContent; // Text, media, or system message
  replyTo: string | null; // Parent message ID for threading
  reactions: ReactionSummary[]; // Aggregated reactions
  status: MessageStatus; // Client-side delivery status
  serverTimestamp: number; // Server-assigned ordering timestamp (ms)
  clientTimestamp: number; // Client-generated timestamp (for optimistic display)
  editedAt: number | null; // Last edit timestamp
  deletedAt: number | null; // Soft-delete timestamp
}

type MessageContent =
  | { type: "text"; text: string; mentions: Mention[] }
  | { type: "media"; attachments: MediaAttachment[] }
  | { type: "file"; file: FileAttachment }
  | { type: "system"; event: SystemEvent };

type MessageStatus = "pending" | "sent" | "delivered" | "read" | "failed";

interface MediaAttachment {
  id: string;
  url: string; // CDN URL for full resolution
  thumbnailUrl: string; // CDN URL for thumbnail (< 50KB)
  mimeType: string;
  width: number;
  height: number;
  sizeBytes: number;
  blurhash: string; // Placeholder while loading
}

interface FileAttachment {
  id: string;
  url: string;
  filename: string;
  mimeType: string;
  sizeBytes: number;
}

// Conversation entity
interface Conversation {
  id: string;
  type: "direct" | "group";
  name: string | null; // null for 1:1 (derived from participant)
  avatarUrl: string | null;
  participantIds: string[]; // User IDs in this conversation
  lastMessage: MessagePreview | null; // Denormalized for list rendering
  unreadCount: number;
  mutedUntil: number | null; // Mute expiry timestamp
  pinnedAt: number | null; // Pin ordering
  createdAt: number;
  updatedAt: number; // Last activity timestamp (for sort)
}

interface MessagePreview {
  id: string;
  senderId: string;
  text: string; // Truncated to 100 chars
  timestamp: number;
  type: MessageContent["type"];
}

// Participant entity
interface Participant {
  id: string;
  displayName: string;
  avatarUrl: string | null;
  username: string;
}

// Real-time state types
interface PresenceState {
  userId: string;
  status: "online" | "away" | "offline";
  lastSeen: number; // Timestamp of last activity
  device: "web" | "mobile" | "desktop";
}

interface TypingState {
  userId: string;
  conversationId: string;
  startedAt: number; // For timeout calculation
}

interface ReadReceipt {
  userId: string;
  conversationId: string;
  lastReadMessageId: string; // Watermark: all messages up to this ID are read
  timestamp: number;
}

interface ReactionSummary {
  emoji: string;
  count: number;
  includesMe: boolean;
  recentUserIds: string[]; // Last 3 reactors for tooltip
}

// Offline queue
interface OutboxMessage {
  clientId: string; // Matches Message.clientId for reconciliation
  conversationId: string;
  content: MessageContent;
  replyTo: string | null;
  createdAt: number;
  retryCount: number;
  lastRetryAt: number | null;
  status: "queued" | "sending" | "failed";
}

// Normalized store window for message pagination
interface MessageWindow {
  conversationId: string;
  messageIds: string[]; // Ordered by serverTimestamp
  hasOlder: boolean; // More history available above
  hasNewer: boolean; // More messages available below (when scrolled up)
  oldestCursor: string | null; // Pagination cursor for loading older
  newestCursor: string | null; // Pagination cursor for loading newer
  isLoadingOlder: boolean;
  isLoadingNewer: boolean;
}

// Mention in message
interface Mention {
  userId: string;
  offset: number; // Character offset in text
  length: number; // Length of mention text
}

type SystemEvent =
  | { kind: "participant_added"; userId: string; addedBy: string }
  | { kind: "participant_removed"; userId: string; removedBy: string }
  | { kind: "conversation_renamed"; name: string; renamedBy: string }
  | { kind: "avatar_changed"; changedBy: string };

// GET /api/conversations?cursor=<string>&limit=20
// Returns paginated conversation list sorted by last activity
interface ConversationListResponse {
  conversations: Conversation[];
  nextCursor: string | null;
  hasMore: boolean;
}

// GET /api/conversations/:id/messages?cursor=<string>&limit=50&direction=older|newer
// Cursor-based pagination for message history
interface MessageHistoryResponse {
  messages: Message[];
  nextCursor: string | null;
  hasMore: boolean;
}

// POST /api/conversations/:id/messages
// Fallback REST endpoint for message sending (when WebSocket unavailable)
interface SendMessageRequest {
  clientId: string; // Idempotency key — server deduplicates by this
  content: MessageContent;
  replyTo: string | null;
}

interface SendMessageResponse {
  message: Message; // Server-assigned ID and timestamp
}

// POST /api/media/upload
// Multipart form upload with progress
interface MediaUploadResponse {
  id: string;
  url: string;
  thumbnailUrl: string;
  blurhash: string;
  width: number;
  height: number;
  sizeBytes: number;
}

// GET /api/conversations/:id/search?q=<string>&cursor=<string>&limit=20
interface SearchResponse {
  results: SearchResult[];
  nextCursor: string | null;
  hasMore: boolean;
}

interface SearchResult {
  message: Message;
  highlights: { field: string; snippet: string }[];
}

// Client → Server frames
type ClientFrame =
  | { type: "send_message"; payload: SendMessagePayload }
  | { type: "typing_start"; payload: { conversationId: string } }
  | { type: "typing_stop"; payload: { conversationId: string } }
  | {
      type: "mark_read";
      payload: { conversationId: string; messageId: string };
    }
  | { type: "presence_update"; payload: { status: "online" | "away" } }
  | { type: "ping"; payload: { timestamp: number } }
  | { type: "subscribe"; payload: { conversationIds: string[] } }
  | { type: "unsubscribe"; payload: { conversationIds: string[] } };

interface SendMessagePayload {
  clientId: string; // Idempotency key
  conversationId: string;
  content: MessageContent;
  replyTo: string | null;
}

// Server → Client frames
type ServerFrame =
  | { type: "message_new"; payload: Message }
  | { type: "message_updated"; payload: Message }
  | {
      type: "message_deleted";
      payload: { conversationId: string; messageId: string };
    }
  | { type: "message_ack"; payload: { clientId: string; message: Message } }
  | {
      type: "typing";
      payload: { conversationId: string; userId: string; active: boolean };
    }
  | { type: "presence"; payload: PresenceState }
  | { type: "read_receipt"; payload: ReadReceipt }
  | {
      type: "reaction";
      payload: { messageId: string; reactions: ReactionSummary[] };
    }
  | {
      type: "conversation_updated";
      payload: Partial<Conversation> & { id: string };
    }
  | { type: "pong"; payload: { timestamp: number; serverTime: number } }
  | { type: "error"; payload: { code: string; message: string; ref?: string } };

class WebSocketManager {
  private ws: WebSocket | null = null;
  private reconnectAttempt = 0;
  private heartbeatInterval: ReturnType<typeof setInterval> | null = null;
  private pendingAcks: Map<
    string,
    { resolve: Function; timeout: ReturnType<typeof setTimeout> }
  > = new Map();

  connect(token: string): void {
    const url = `wss://chat.example.com/ws?token=${token}`;
    this.ws = new WebSocket(url);

    this.ws.onopen = () => {
      this.reconnectAttempt = 0;
      this.startHeartbeat();
      this.resubscribeConversations();
      this.flushOutbox();
    };

    this.ws.onmessage = (event) => {
      const frame: ServerFrame = JSON.parse(event.data);
      this.routeFrame(frame);
    };

    this.ws.onclose = (event) => {
      this.stopHeartbeat();
      if (!event.wasClean) {
        this.scheduleReconnect();
      }
    };
  }

  private scheduleReconnect(): void {
    const baseDelay = Math.min(
      1000 * Math.pow(2, this.reconnectAttempt),
      30000,
    );
    const jitter = Math.random() * baseDelay * 0.3;
    const delay = baseDelay + jitter;
    this.reconnectAttempt++;

    setTimeout(() => this.connect(this.getToken()), delay);
  }

  private startHeartbeat(): void {
    this.heartbeatInterval = setInterval(() => {
      this.send({ type: "ping", payload: { timestamp: Date.now() } });
    }, 25000); // Every 25s (under typical 30s proxy timeouts)
  }

  send(frame: ClientFrame): void {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(frame));
    } else {
      // Queue for delivery on reconnection
      this.queueOffline(frame);
    }
  }
}

┌─────────────────────────────────────────────────┐
│  Layer 1: In-Memory (Zustand normalized store)  │
│  • Active conversation messages (last 100 each) │
│  • All conversation metadata                     │
│  • Presence & typing state (ephemeral)          │
│  • TTL: session lifetime                         │
├─────────────────────────────────────────────────┤
│  Layer 2: IndexedDB (persistent client cache)   │
│  • Full message history (disk-backed)           │
│  • Conversation list with last messages         │
│  • Offline outbox queue                          │
│  • Media blob cache (thumbnails)                │
│  • TTL: 30 days, LRU eviction at 500MB         │
├─────────────────────────────────────────────────┤
│  Layer 3: CDN (media assets)                    │
│  • Full-resolution images/videos                │
│  • File attachments                              │
│  • Cache-Control: immutable (content-addressed) │
└─────────────────────────────────────────────────┘

const MESSAGE_WINDOW_SIZE = 100; // Messages kept in memory per conversation

function loadMessagesForConversation(conversationId: string): void {
  // 1. Check in-memory store first
  const window = store.getState().messageWindows[conversationId];
  if (window && window.messageIds.length > 0) return;

  // 2. Check IndexedDB for cached messages
  const cached = await messageDb.getRecentMessages(
    conversationId,
    MESSAGE_WINDOW_SIZE,
  );
  if (cached.length > 0) {
    store.getState().hydrateMessages(conversationId, cached);
    return;
  }

  // 3. Fetch from server
  const response = await api.getMessageHistory(conversationId, { limit: 50 });
  store.getState().hydrateMessages(conversationId, response.messages);
  messageDb.cacheMessages(conversationId, response.messages);
}

async function initializeConversationList(): Promise<void> {
  // Render cached list immediately (< 100ms)
  const cached = await conversationDb.getAllConversations();
  store.getState().setConversations(cached);

  // Fetch fresh data in background
  const fresh = await api.getConversations({ limit: 50 });
  store.getState().mergeConversations(fresh.conversations);
  conversationDb.upsertConversations(fresh.conversations);
}

const outboxStore = {
  async enqueue(message: OutboxMessage): Promise<void> {
    await db.put("outbox", message);
  },

  async dequeue(clientId: string): Promise<void> {
    await db.delete("outbox", clientId);
  },

  async getAll(): Promise<OutboxMessage[]> {
    return db.getAllFromIndex("outbox", "by-created-at");
  },

  async markFailed(clientId: string): Promise<void> {
    const msg = await db.get("outbox", clientId);
    if (msg) {
      msg.status = "failed";
      msg.retryCount++;
      msg.lastRetryAt = Date.now();
      await db.put("outbox", msg);
    }
  },
};

// Bidirectional virtualized list implementation strategy
interface VirtualizedMessageListProps {
  messageIds: string[];
  hasOlder: boolean;
  hasNewer: boolean;
  isAtBottom: boolean;
  onLoadOlder: () => void;
  onLoadNewer: () => void;
}

function VirtualizedMessageList({
  messageIds,
  hasOlder,
  hasNewer,
  isAtBottom,
  onLoadOlder,
  onLoadNewer,
}: VirtualizedMessageListProps) {
  const listRef = useRef<VirtualizerHandle>(null);
  const [scrollAnchor, setScrollAnchor] = useState<'bottom' | 'position'>('bottom');

  // Pin to bottom when new messages arrive and user hasn't scrolled up
  useEffect(() => {
    if (scrollAnchor === 'bottom' && listRef.current) {
      listRef.current.scrollToEnd({ behavior: 'instant' });
    }
  }, [messageIds.length, scrollAnchor]);

  // Prepend scroll position maintenance
  const prevMessageCount = useRef(messageIds.length);
  useLayoutEffect(() => {
    if (messageIds.length > prevMessageCount.current && scrollAnchor === 'position') {
      // Messages were prepended (loaded older) — maintain viewport position
      const addedCount = messageIds.length - prevMessageCount.current;
      listRef.current?.adjustScrollBy(addedCount);
    }
    prevMessageCount.current = messageIds.length;
  }, [messageIds.length]);

  return (
    <Virtualizer
      ref={listRef}
      count={messageIds.length}
      estimateSize={() => 72} // Average message height estimate
      overscan={10}
      onScrollTopReached={hasOlder ? onLoadOlder : undefined}
      onScrollBottomReached={hasNewer ? onLoadNewer : undefined}
      onScrollAwayFromBottom={() => setScrollAnchor('position')}
      onScrollToBottom={() => setScrollAnchor('bottom')}
    >
      {(index) => <MessageBubble messageId={messageIds[index]} />}
    </Virtualizer>
  );
}

// Progressive image loading for chat media
function ChatImage({ attachment }: { attachment: MediaAttachment }) {
  const [loaded, setLoaded] = useState(false);

  // Calculate aspect ratio container to prevent CLS
  const aspectRatio = attachment.width / attachment.height;

  return (
    <div
      className="relative overflow-hidden rounded-lg"
      style={{ aspectRatio, maxWidth: Math.min(attachment.width, 400) }}
    >
      {/* Blurhash placeholder — renders instantly */}
      {!loaded && <BlurhashCanvas hash={attachment.blurhash} className="absolute inset-0" />}

      {/* Thumbnail (< 50KB, loads fast) */}
      <img
        src={attachment.thumbnailUrl}
        srcSet={`${attachment.thumbnailUrl} 1x, ${attachment.url} 2x`}
        alt=""
        loading="lazy"
        onLoad={() => setLoaded(true)}
        className={cn('w-full h-full object-cover', !loaded && 'opacity-0')}
      />
    </div>
  );
}

Time    0ms    200ms    500ms    1000ms    1500ms    2000ms
         │       │        │        │         │         │
         ├─ HTML shell (cached service worker)
         │       ├─ JS bundle (< 200KB gzip, code-split)
         │       │        ├─ IndexedDB conversation cache read
         │       │        │   ├─ Render conversation list (LCP)
         │       │        │        ├─ WebSocket connect
         │       │        │        │    ├─ Fresh data merge
         │       │        │        │         ├─ Active conversation messages load
         │       │        │        │         │    ├─ Full interactive (TTI)

// NEVER use dangerouslySetInnerHTML for message content
function MessageText({ text, mentions }: { text: string; mentions: Mention[] }) {
  // Build safe React elements from plain text + mentions
  const segments = buildSegments(text, mentions);

  return (
    <p className="message-text whitespace-pre-wrap break-words">
      {segments.map((segment, i) => {
        if (segment.type === 'text') {
          // React automatically escapes text content — XSS-safe
          return <span key={i}>{segment.value}</span>;
        }
        if (segment.type === 'mention') {
          return (
            <span key={i} className="text-blue-500 font-medium">
              @{segment.displayName}
            </span>
          );
        }
        if (segment.type === 'link') {
          // Only allow http/https protocols
          const url = sanitizeUrl(segment.value);
          return url ? (
            <a key={i} href={url} target="_blank" rel="noopener noreferrer nofollow">
              {segment.value}
            </a>
          ) : (
            <span key={i}>{segment.value}</span>
          );
        }
        return null;
      })}
    </p>
  );
}

function sanitizeUrl(url: string): string | null {
  try {
    const parsed = new URL(url);
    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
      return parsed.href;
    }
    return null; // Block javascript:, data:, etc.
  } catch {
    return null;
  }
}

Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' https://cdn.chat.example.com;
  media-src 'self' https://cdn.chat.example.com;
  connect-src 'self' wss://chat.example.com https://api.chat.example.com;
  frame-src 'none';
  object-src 'none';
  base-uri 'self';

// Token refresh flow for WebSocket
class AuthTokenManager {
  private accessToken: string | null = null;
  private refreshTimer: ReturnType<typeof setTimeout> | null = null;

  async getWsToken(): Promise<string> {
    // WS tokens are short-lived (5 min) to limit exposure if intercepted
    if (this.accessToken && !this.isExpired(this.accessToken)) {
      return this.accessToken;
    }

    // Refresh via httpOnly cookie (CSRF-protected REST call)
    const response = await fetch("/api/auth/ws-token", {
      method: "POST",
      credentials: "include", // Sends httpOnly refresh cookie
      headers: { "X-CSRF-Token": getCsrfToken() },
    });

    const { token, expiresIn } = await response.json();
    this.accessToken = token;

    // Schedule refresh at 80% of TTL
    this.refreshTimer = setTimeout(
      () => this.getWsToken(),
      expiresIn * 0.8 * 1000,
    );

    return token;
  }
}

// Server assigns monotonically increasing sequence IDs per conversation
// Client uses these for ordering, NOT arrival order

function insertMessageInOrder(
  window: MessageWindow,
  messages: Record<string, Message>,
  newMessage: Message,
): string[] {
  const ids = [...window.messageIds];

  // Binary search for correct insertion position by serverTimestamp
  let low = 0;
  let high = ids.length;

  while (low < high) {
    const mid = (low + high) >>> 1;
    const existing = messages[ids[mid]];
    if (existing.serverTimestamp < newMessage.serverTimestamp) {
      low = mid + 1;
    } else {
      high = mid;
    }
  }

  // Deduplicate: if message with same ID exists, replace (update case)
  const existingIndex = ids.indexOf(newMessage.id);
  if (existingIndex !== -1) {
    ids[existingIndex] = newMessage.id; // Same ID, potentially updated content
    return ids;
  }

  ids.splice(low, 0, newMessage.id);
  return ids;
}

class OfflineOutbox {
  private processing = false;

  async enqueue(
    message: Omit<OutboxMessage, "retryCount" | "lastRetryAt" | "status">,
  ): Promise<void> {
    const outboxMsg: OutboxMessage = {
      ...message,
      retryCount: 0,
      lastRetryAt: null,
      status: "queued",
    };

    // Persist to IndexedDB immediately
    await outboxStore.enqueue(outboxMsg);

    // Add optimistic message to in-memory store
    store.getState().addOptimisticMessage(outboxMsg);

    // Attempt send if online
    if (navigator.onLine && wsManager.isConnected()) {
      this.processQueue();
    }
  }

  async processQueue(): Promise<void> {
    if (this.processing) return;
    this.processing = true;

    try {
      const pending = await outboxStore.getAll();

      for (const msg of pending) {
        if (msg.retryCount >= 5) {
          // Mark as permanently failed after 5 retries
          await outboxStore.markFailed(msg.clientId);
          store.getState().markMessageFailed(msg.clientId);
          continue;
        }

        try {
          wsManager.send({
            type: "send_message",
            payload: {
              clientId: msg.clientId,
              conversationId: msg.conversationId,
              content: msg.content,
              replyTo: msg.replyTo,
            },
          });

          // Wait for ACK with timeout
          await this.waitForAck(msg.clientId, 5000);
          await outboxStore.dequeue(msg.clientId);
        } catch {
          msg.retryCount++;
          msg.lastRetryAt = Date.now();
          await outboxStore.enqueue(msg);
        }
      }
    } finally {
      this.processing = false;
    }
  }

  private waitForAck(clientId: string, timeoutMs: number): Promise<Message> {
    return new Promise((resolve, reject) => {
      const timeout = setTimeout(() => {
        unsubscribe();
        reject(new Error("ACK timeout"));
      }, timeoutMs);

      const unsubscribe = store.subscribe(
        (state) => state.messages,
        (messages) => {
          // Find message where clientId matches and has server-assigned ID
          const acked = Object.values(messages).find(
            (m) => m.clientId === clientId && m.status !== "pending",
          );
          if (acked) {
            clearTimeout(timeout);
            unsubscribe();
            resolve(acked);
          }
        },
      );
    });
  }
}

// Exponential backoff with jitter — prevents thundering herd on server recovery
const RECONNECT_CONFIG = {
  baseDelay: 1000, // 1s initial delay
  maxDelay: 30000, // 30s cap
  jitterFactor: 0.3, // ±30% randomization
  maxAttempts: Infinity, // Never stop trying (user expectation)
};

function calculateReconnectDelay(attempt: number): number {
  const exponential = Math.min(
    RECONNECT_CONFIG.baseDelay * Math.pow(2, attempt),
    RECONNECT_CONFIG.maxDelay,
  );
  const jitter =
    exponential * RECONNECT_CONFIG.jitterFactor * (Math.random() * 2 - 1);
  return Math.max(0, exponential + jitter);
}

// On reconnection: replay missed messages
async function onReconnect(): Promise<void> {
  const lastReceived = store.getState().lastServerTimestamp;

  // Server replays all messages since lastReceived for subscribed conversations
  wsManager.send({
    type: "subscribe",
    payload: {
      conversationIds: store.getState().activeConversationIds,
      since: lastReceived, // Extension: server uses this for replay
    },
  });

  // Flush offline outbox
  offlineOutbox.processQueue();
}

// Problem: typing indicators for 1000 members would flood the client
// Solution: server-side fan-out limiting

// Client subscribes to typing for active conversation only
// Server limits typing indicator broadcasts to first 5 concurrent typers
// Presence is batched — server sends deltas every 5s, not per-user

interface GroupPresenceBatch {
  conversationId: string;
  online: string[]; // User IDs currently online (truncated to 50)
  onlineCount: number; // Total count for "47 online" display
  recentlyActive: string[]; // Last 10 users who sent messages
}

// Client renders: "Alice, Bob, and 3 others are typing..."
function formatTypingIndicator(
  typing: TypingState[],
  participants: Record<string, Participant>,
): string {
  const names = typing
    .slice(0, 3)
    .map((t) => participants[t.userId]?.displayName ?? "Someone");

  if (typing.length === 1) return `${names[0]} is typing...`;
  if (typing.length === 2) return `${names[0]} and ${names[1]} are typing...`;
  if (typing.length === 3)
    return `${names[0]}, ${names[1]}, and ${names[2]} are typing...`;
  return `${names[0]}, ${names[1]}, and ${typing.length - 2} others are typing...`;
}

function MessageList({ messages }: { messages: Message[] }) {
  const lastAnnouncedRef = useRef<string | null>(null);

  return (
    <>
      {/* Polite live region — announces new messages without interrupting */}
      <div
        role="log"
        aria-live="polite"
        aria-atomic={false}
        aria-relevant="additions"
        className="sr-only"
      >
        {messages.slice(-1).map((msg) => {
          if (msg.id === lastAnnouncedRef.current) return null;
          lastAnnouncedRef.current = msg.id;
          return (
            <p key={msg.id}>
              {getParticipantName(msg.senderId)} says: {getMessageTextContent(msg.content)}
            </p>
          );
        })}
      </div>

      {/* Visual message list */}
      <div role="list" aria-label="Messages">
        {messages.map((msg) => (
          <MessageBubble key={msg.id} message={msg} />
        ))}
      </div>
    </>
  );
}

function ConversationList({ conversations }: { conversations: Conversation[] }) {
  const [focusIndex, setFocusIndex] = useState(0);
  const itemRefs = useRef<(HTMLElement | null)[]>([]);

  const handleKeyDown = (e: KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        setFocusIndex((i) => Math.min(i + 1, conversations.length - 1));
        break;
      case 'ArrowUp':
        e.preventDefault();
        setFocusIndex((i) => Math.max(i - 1, 0));
        break;
      case 'Enter':
        e.preventDefault();
        openConversation(conversations[focusIndex].id);
        break;
    }
  };

  useEffect(() => {
    itemRefs.current[focusIndex]?.focus();
  }, [focusIndex]);

  return (
    <nav
      role="listbox"
      aria-label="Conversations"
      onKeyDown={handleKeyDown}
    >
      {conversations.map((convo, i) => (
        <div
          key={convo.id}
          ref={(el) => { itemRefs.current[i] = el; }}
          role="option"
          aria-selected={i === focusIndex}
          tabIndex={i === focusIndex ? 0 : -1}
        >
          <ConversationItem conversation={convo} />
        </div>
      ))}
    </nav>
  );
}

function MessageStatus({ status }: { status: MessageStatus }) {
  const labels: Record<MessageStatus, string> = {
    pending: 'Sending',
    sent: 'Sent',
    delivered: 'Delivered',
    read: 'Read',
    failed: 'Failed to send',
  };

  return (
    <span className="message-status" aria-label={labels[status]}>
      {status === 'pending' && <ClockIcon size={12} aria-hidden />}
      {status === 'sent' && <CheckIcon size={12} aria-hidden />}
      {status === 'delivered' && <CheckCheckIcon size={12} aria-hidden />}
      {status === 'read' && <CheckCheckIcon size={12} className="text-blue-500" aria-hidden />}
      {status === 'failed' && <AlertCircleIcon size={12} className="text-red-500" aria-hidden />}
      <span className="sr-only">{labels[status]}</span>
    </span>
  );
}

// When a new conversation opens, focus moves to the composer
// When a message fails, focus moves to the retry button
// When search opens, focus moves to the search input

function useConversationFocus(activeConversationId: string | null) {
  const composerRef = useRef<HTMLTextAreaElement>(null);

  useEffect(() => {
    if (activeConversationId) {
      // Small delay to allow render to complete
      requestAnimationFrame(() => {
        composerRef.current?.focus();
      });
    }
  }, [activeConversationId]);

  return composerRef;
}

class ChatMetrics {
  private deliveryTimers: Map<string, number> = new Map();

  // Track message delivery latency
  onMessageSend(clientId: string): void {
    this.deliveryTimers.set(clientId, performance.now());
  }

  onMessageAck(clientId: string): void {
    const sendTime = this.deliveryTimers.get(clientId);
    if (sendTime) {
      const latency = performance.now() - sendTime;
      this.deliveryTimers.delete(clientId);
      this.report("message_delivery_latency", latency);
    }
  }

  // Track WebSocket health
  onConnectionStateChange(
    state: "connected" | "disconnected" | "reconnecting",
  ): void {
    this.report("ws_connection_state", { state, timestamp: Date.now() });
  }

  // Track scroll performance
  onScrollFrame(frameTime: number): void {
    if (frameTime > 16.67) {
      // Dropped frame (below 60fps)
      this.report("scroll_frame_drop", { frameTime });
    }
  }

  private report(event: string, data: unknown): void {
    // Batch and send to analytics endpoint every 30s
    navigator.sendBeacon(
      "/api/metrics",
      JSON.stringify({ event, data, ts: Date.now() }),
    );
  }
}

// Structured error reporting for chat-specific failures
type ChatError =
  | { kind: "ws_connection_failed"; attempt: number; code: number }
  | { kind: "message_send_failed"; clientId: string; reason: string }
  | {
      kind: "media_upload_failed";
      conversationId: string;
      size: number;
      mimeType: string;
    }
  | { kind: "message_parse_failed"; rawFrame: string }
  | { kind: "indexeddb_quota_exceeded"; usedBytes: number };

function reportChatError(error: ChatError): void {
  console.error("[Chat]", error.kind, error);
  metrics.report("chat_error", error);
}