feat(web): chat UI with conversations, messages, and WebSocket streaming

Build the primary chat interface with conversation list sidebar,
message display area, streaming assistant responses via socket.io,
and auto-scrolling. Supports creating new conversations, sending
messages with optimistic updates, and real-time text streaming
from the agent via WebSocket events.

Components: ConversationList, MessageBubble, ChatInput, StreamingMessage
Libs: socket.io client singleton, shared types for Conversation/Message

Refs #28

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

apps/web/package.json

@@ -17,6 +17,7 @@
     "next": "^16.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "socket.io-client": "^4.8.0",
     "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {

apps/web/src/app/(dashboard)/chat/page.tsx

@@ -1,8 +1,179 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { api } from '@/lib/api';
+import { getSocket } from '@/lib/socket';
+import type { Conversation, Message } from '@/lib/types';
+import { ConversationList } from '@/components/chat/conversation-list';
+import { MessageBubble } from '@/components/chat/message-bubble';
+import { ChatInput } from '@/components/chat/chat-input';
+import { StreamingMessage } from '@/components/chat/streaming-message';
+
 export default function ChatPage(): React.ReactElement {
+  const [conversations, setConversations] = useState<Conversation[]>([]);
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [streamingText, setStreamingText] = useState('');
+  const [isStreaming, setIsStreaming] = useState(false);
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+
+  // Load conversations on mount
+  useEffect(() => {
+    api<Conversation[]>('/api/conversations')
+      .then(setConversations)
+      .catch(() => {});
+  }, []);
+
+  // Load messages when active conversation changes
+  useEffect(() => {
+    if (!activeId) {
+      setMessages([]);
+      return;
+    }
+    api<Message[]>(`/api/conversations/${activeId}/messages`)
+      .then(setMessages)
+      .catch(() => {});
+  }, [activeId]);
+
+  // Auto-scroll to bottom
+  useEffect(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [messages, streamingText]);
+
+  // Socket.io setup
+  useEffect(() => {
+    const socket = getSocket();
+    socket.connect();
+
+    socket.on('agent:text', (data: { conversationId: string; text: string }) => {
+      setStreamingText((prev) => prev + data.text);
+    });
+
+    socket.on('agent:start', () => {
+      setIsStreaming(true);
+      setStreamingText('');
+    });
+
+    socket.on('agent:end', (data: { conversationId: string }) => {
+      setIsStreaming(false);
+      setStreamingText('');
+      // Reload messages to get the final persisted version
+      api<Message[]>(`/api/conversations/${data.conversationId}/messages`)
+        .then(setMessages)
+        .catch(() => {});
+    });
+
+    socket.on('error', (data: { error: string }) => {
+      setIsStreaming(false);
+      setStreamingText('');
+      setMessages((prev) => [
+        ...prev,
+        {
+          id: `error-${Date.now()}`,
+          conversationId: '',
+          role: 'system',
+          content: `Error: ${data.error}`,
+          createdAt: new Date().toISOString(),
+        },
+      ]);
+    });
+
+    return () => {
+      socket.off('agent:text');
+      socket.off('agent:start');
+      socket.off('agent:end');
+      socket.off('error');
+      socket.disconnect();
+    };
+  }, []);
+
+  const handleNewConversation = useCallback(async () => {
+    const conv = await api<Conversation>('/api/conversations', {
+      method: 'POST',
+      body: { title: 'New conversation' },
+    });
+    setConversations((prev) => [conv, ...prev]);
+    setActiveId(conv.id);
+    setMessages([]);
+  }, []);
+
+  const handleSend = useCallback(
+    async (content: string) => {
+      let convId = activeId;
+
+      // Auto-create conversation if none selected
+      if (!convId) {
+        const conv = await api<Conversation>('/api/conversations', {
+          method: 'POST',
+          body: { title: content.slice(0, 50) },
+        });
+        setConversations((prev) => [conv, ...prev]);
+        setActiveId(conv.id);
+        convId = conv.id;
+      }
+
+      // Optimistic user message
+      const userMsg: Message = {
+        id: `temp-${Date.now()}`,
+        conversationId: convId,
+        role: 'user',
+        content,
+        createdAt: new Date().toISOString(),
+      };
+      setMessages((prev) => [...prev, userMsg]);
+
+      // Persist user message
+      await api<Message>(`/api/conversations/${convId}/messages`, {
+        method: 'POST',
+        body: { role: 'user', content },
+      });
+
+      // Send to WebSocket for streaming response
+      const socket = getSocket();
+      socket.emit('message', { conversationId: convId, content });
+    },
+    [activeId],
+  );
+
   return (
-    <div>
-      <h1 className="text-2xl font-semibold">Chat</h1>
-      <p className="mt-2 text-text-secondary">Conversations will appear here.</p>
+    <div className="-m-6 flex h-[calc(100vh-3.5rem)]">
+      <ConversationList
+        conversations={conversations}
+        activeId={activeId}
+        onSelect={setActiveId}
+        onNew={handleNewConversation}
+      />
+
+      <div className="flex flex-1 flex-col">
+        {activeId ? (
+          <>
+            <div className="flex-1 space-y-4 overflow-y-auto p-6">
+              {messages.map((msg) => (
+                <MessageBubble key={msg.id} message={msg} />
+              ))}
+              {isStreaming && <StreamingMessage text={streamingText} />}
+              <div ref={messagesEndRef} />
+            </div>
+            <ChatInput onSend={handleSend} disabled={isStreaming} />
+          </>
+        ) : (
+          <div className="flex flex-1 items-center justify-center">
+            <div className="text-center">
+              <h2 className="text-lg font-medium text-text-secondary">Welcome to Mosaic Chat</h2>
+              <p className="mt-1 text-sm text-text-muted">
+                Select a conversation or start a new one
+              </p>
+              <button
+                type="button"
+                onClick={handleNewConversation}
+                className="mt-4 rounded-lg bg-blue-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-blue-700"
+              >
+                Start new conversation
+              </button>
+            </div>
+          </div>
+        )}
+      </div>
     </div>
   );
 }

apps/web/src/components/chat/chat-input.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+import { useRef, useState } from 'react';
+
+interface ChatInputProps {
+  onSend: (content: string) => void;
+  disabled?: boolean;
+}
+
+export function ChatInput({ onSend, disabled }: ChatInputProps): React.ReactElement {
+  const [value, setValue] = useState('');
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+
+  function handleSubmit(e: React.FormEvent): void {
+    e.preventDefault();
+    const trimmed = value.trim();
+    if (!trimmed || disabled) return;
+    onSend(trimmed);
+    setValue('');
+    textareaRef.current?.focus();
+  }
+
+  function handleKeyDown(e: React.KeyboardEvent<HTMLTextAreaElement>): void {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      handleSubmit(e);
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="border-t border-surface-border bg-surface-card p-4">
+      <div className="flex items-end gap-3">
+        <textarea
+          ref={textareaRef}
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onKeyDown={handleKeyDown}
+          disabled={disabled}
+          rows={1}
+          placeholder="Type a message... (Enter to send, Shift+Enter for newline)"
+          className="max-h-32 min-h-[2.5rem] flex-1 resize-none rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+        />
+        <button
+          type="submit"
+          disabled={disabled || !value.trim()}
+          className="rounded-lg bg-blue-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-blue-700 disabled:opacity-50"
+        >
+          Send
+        </button>
+      </div>
+    </form>
+  );
+}

apps/web/src/components/chat/conversation-list.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import { cn } from '@/lib/cn';
+import type { Conversation } from '@/lib/types';
+
+interface ConversationListProps {
+  conversations: Conversation[];
+  activeId: string | null;
+  onSelect: (id: string) => void;
+  onNew: () => void;
+}
+
+export function ConversationList({
+  conversations,
+  activeId,
+  onSelect,
+  onNew,
+}: ConversationListProps): React.ReactElement {
+  return (
+    <div className="flex h-full w-64 flex-col border-r border-surface-border bg-surface-card">
+      <div className="flex items-center justify-between p-3">
+        <h2 className="text-sm font-medium text-text-secondary">Conversations</h2>
+        <button
+          type="button"
+          onClick={onNew}
+          className="rounded-md px-2 py-1 text-xs text-blue-400 transition-colors hover:bg-surface-elevated"
+        >
+          + New
+        </button>
+      </div>
+
+      <div className="flex-1 overflow-y-auto">
+        {conversations.length === 0 && (
+          <p className="px-3 py-2 text-xs text-text-muted">No conversations yet</p>
+        )}
+        {conversations.map((conv) => (
+          <button
+            key={conv.id}
+            type="button"
+            onClick={() => onSelect(conv.id)}
+            className={cn(
+              'w-full px-3 py-2 text-left text-sm transition-colors',
+              activeId === conv.id
+                ? 'bg-blue-600/20 text-blue-400'
+                : 'text-text-secondary hover:bg-surface-elevated',
+            )}
+          >
+            <span className="block truncate">{conv.title ?? 'Untitled'}</span>
+            <span className="block text-xs text-text-muted">
+              {new Date(conv.updatedAt).toLocaleDateString()}
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

apps/web/src/components/chat/message-bubble.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { cn } from '@/lib/cn';
+import type { Message } from '@/lib/types';
+
+interface MessageBubbleProps {
+  message: Message;
+}
+
+export function MessageBubble({ message }: MessageBubbleProps): React.ReactElement {
+  const isUser = message.role === 'user';
+
+  return (
+    <div className={cn('flex', isUser ? 'justify-end' : 'justify-start')}>
+      <div
+        className={cn(
+          'max-w-[75%] rounded-xl px-4 py-3 text-sm',
+          isUser
+            ? 'bg-blue-600 text-white'
+            : 'border border-surface-border bg-surface-elevated text-text-primary',
+        )}
+      >
+        <div className="whitespace-pre-wrap break-words">{message.content}</div>
+        <div
+          className={cn('mt-1 text-right text-xs', isUser ? 'text-blue-200' : 'text-text-muted')}
+        >
+          {new Date(message.createdAt).toLocaleTimeString([], {
+            hour: '2-digit',
+            minute: '2-digit',
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}

apps/web/src/components/chat/streaming-message.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+/** Renders an in-progress assistant message from streaming text. */
+interface StreamingMessageProps {
+  text: string;
+}
+
+export function StreamingMessage({ text }: StreamingMessageProps): React.ReactElement | null {
+  if (!text) return null;
+
+  return (
+    <div className="flex justify-start">
+      <div className="max-w-[75%] rounded-xl border border-surface-border bg-surface-elevated px-4 py-3 text-sm text-text-primary">
+        <div className="whitespace-pre-wrap break-words">{text}</div>
+        <div className="mt-1 flex items-center gap-1 text-xs text-text-muted">
+          <span className="inline-block h-2 w-2 animate-pulse rounded-full bg-blue-500" />
+          Thinking...
+        </div>
+      </div>
+    </div>
+  );
+}

apps/web/src/lib/socket.ts

@@ -0,0 +1,15 @@
+import { io, type Socket } from 'socket.io-client';
+
+const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:4000';
+
+let socket: Socket | null = null;
+
+export function getSocket(): Socket {
+  if (!socket) {
+    socket = io(`${GATEWAY_URL}/chat`, {
+      withCredentials: true,
+      autoConnect: false,
+    });
+  }
+  return socket;
+}

apps/web/src/lib/types.ts

@@ -0,0 +1,19 @@
+/** Conversation returned by the gateway API. */
+export interface Conversation {
+  id: string;
+  userId: string;
+  title: string | null;
+  projectId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Message within a conversation. */
+export interface Message {
+  id: string;
+  conversationId: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}

docs/TASKS.md

@@ -30,8 +30,8 @@
 | P2-006 | done        | Phase 2   | Agent session management — tmux + monitoring                  | #78 | #24   |
 | P2-007 | done        | Phase 2   | Verify Phase 2 — multi-provider routing works                 | #79 | #25   |
 | P3-001 | done        | Phase 3   | apps/web scaffold — Next.js 16 + BetterAuth + Tailwind        | #82 | #26   |
-| P3-002 | in-progress | Phase 3   | Auth pages — login, registration, SSO redirect                | —   | #27   |
-| P3-003 | not-started | Phase 3   | Chat UI — conversations, messages, streaming                  | —   | #28   |
+| P3-002 | done        | Phase 3   | Auth pages — login, registration, SSO redirect                | #83 | #27   |
+| P3-003 | in-progress | Phase 3   | Chat UI — conversations, messages, streaming                  | —   | #28   |
 | P3-004 | not-started | Phase 3   | Task management — list view + kanban board                    | —   | #29   |
 | P3-005 | not-started | Phase 3   | Project & mission views — dashboard + PRD viewer              | —   | #30   |
 | P3-006 | not-started | Phase 3   | Settings — provider config, profile, integrations             | —   | #31   |

pnpm-lock.yaml

@@ -156,6 +156,9 @@ importers:
       react-dom:
         specifier: ^19.0.0
         version: 19.2.4(react@19.2.4)
+      socket.io-client:
+        specifier: ^4.8.0
+        version: 4.8.3
       tailwind-merge:
         specifier: ^3.5.0
         version: 3.5.0