stack/docs/scratchpads/42-jarvis-chat-overlay.md

# Issue #42: Jarvis Chat Overlay

## Objective

Implement a persistent Jarvis chat overlay accessible from any view in the HUD. The chat should maintain state across navigation, support markdown rendering, integrate with ClawdBot via WebSocket, and be context-aware of the current view.

## Requirements Summary

### UI Components

- Chat overlay with 3 states: Minimized (icon), Collapsed (header), Expanded (full chat)
- Message history with markdown rendering and code syntax highlighting
- Input field with send button
- Typing indicator
- Message timestamps
- PDA-friendly response formatting
- Responsive design (sidebar for desktop, drawer for mobile)

### Backend Integration

- WebSocket connection to ClawdBot gateway
- POST /api/chat/message endpoint
- GET /api/chat/history endpoint
- WebSocket /ws/chat endpoint

### Features

- Context awareness (current view, entity type, entity ID)
- Deep linking from Jarvis responses
- Keyboard shortcuts:
  - Cmd/Ctrl + K: Focus chat input
  - Escape: Minimize chat
  - Cmd/Ctrl + Shift + J: Toggle chat panel
- Chat history persistence
- State persistence across navigation

## Approach

### Phase 1: Frontend Components

1. Create ChatOverlay component (apps/web)
2. Create ChatMessage component for rendering messages
3. Create ChatInput component
4. Implement state management (React Context or Zustand)
5. Add keyboard shortcuts
6. Implement responsive design

### Phase 2: Backend API

1. Create chat module in apps/api
2. Implement POST /api/chat/message endpoint
3. Implement GET /api/chat/history endpoint
4. Set up WebSocket gateway for /ws/chat
5. Integrate with ClawdBot

### Phase 3: Integration & Polish

1. Connect frontend to backend WebSocket
2. Implement context awareness
3. Add markdown rendering
4. Add code syntax highlighting
5. Implement chat history persistence
6. Add loading states and error handling

## Codebase Structure

### Frontend (apps/web/)

- `app/` - Next.js 16 App Router
  - `layout.tsx` - Root layout with providers
  - `(authenticated)/layout.tsx` - Authenticated layout (where overlay will be added)
- `components/` - React components
  - `chat/` - Existing chat components (Chat, ChatInput, MessageList, ConversationSidebar)
  - `hud/` - HUD widgets
  - `ui/` - Shadcn/ui components
- `hooks/` - Custom hooks
  - `useChat.ts` - Chat state management
  - `useWebSocket.ts` - WebSocket connection
- `lib/` - Utilities and shared logic

### Backend (apps/api/)

- `src/` - NestJS application
  - `brain/` - Brain query service (already exists)
  - `websocket/` - WebSocket gateway (already exists)
  - Chat endpoints already exist via brain module

## Key Findings

✅ Chat component already fully implemented
✅ WebSocket connection already exists
✅ Backend API already exists (brain module)
✅ Message rendering with markdown already works

**What needs to be built:**

1. ChatOverlay wrapper component with minimize/expand/collapse states
2. useChatOverlay hook for global state management
3. Integration into authenticated layout
4. Keyboard shortcuts (Cmd+K, Escape, Cmd+Shift+J)
5. Responsive design (sidebar for desktop, drawer for mobile)
6. Context awareness (pass current view/entity to chat)

## Implementation Plan

### Phase 1: State Management Hook

Create `apps/web/src/hooks/useChatOverlay.ts`:

- State: isOpen, isMinimized, isExpanded
- Methods: open, close, minimize, expand, toggle
- Persist state to localStorage
- **TDD: Write tests first**

### Phase 2: ChatOverlay Component

Create `apps/web/src/components/chat/ChatOverlay.tsx`:

- Wrap existing Chat component
- Add minimize/expand/collapse UI controls
- Responsive design (sidebar vs drawer)
- Use useChatOverlay hook for state
- **TDD: Write tests first**

### Phase 3: Keyboard Shortcuts

Add global keyboard listener:

- Cmd/Ctrl + K: Focus chat input (already exists in Chat.tsx, update to also open overlay)
- Escape: Minimize chat
- Cmd/Ctrl + Shift + J: Toggle chat panel
- **TDD: Write tests first**

### Phase 4: Integration

- Add ChatOverlay to authenticated layout
- Add context awareness (pass current route/view)
- Test across different pages

### Phase 5: Polish

- Animations for expand/collapse
- Ensure PDA-friendly design
- Add loading states
- Error handling

## Progress

- [x] Create scratchpad
- [x] Explore current codebase structure
- [x] Identify existing chat implementation
- [x] Identify backend WebSocket infrastructure
- [x] Plan component architecture
- [x] Write tests for useChatOverlay hook (14 tests)
- [x] Implement useChatOverlay hook (all tests passing)
- [x] Write tests for ChatOverlay component (18 tests)
- [x] Implement ChatOverlay component (all tests passing)
- [x] Add keyboard shortcuts (Cmd+K, Escape, Cmd+Shift+J)
- [x] Write tests for keyboard shortcuts (included in component tests)
- [x] Integrate into authenticated layout
- [ ] Test context awareness (will be added later as enhancement)
- [x] Test responsive design (basic responsive classes added)
- [ ] Add animations (basic transitions added, can enhance later)
- [ ] Run quality checks (test, lint, build)
- [ ] Create PR

## Implementation Notes

### Files Created

1. `apps/web/src/hooks/useChatOverlay.ts` - State management hook
2. `apps/web/src/hooks/useChatOverlay.test.ts` - Hook tests (14 tests, all passing)
3. `apps/web/src/components/chat/ChatOverlay.tsx` - Overlay component
4. `apps/web/src/components/chat/ChatOverlay.test.tsx` - Component tests (18 tests, all passing)

### Files Modified

1. `apps/web/src/components/chat/index.ts` - Added ChatOverlay export
2. `apps/web/src/app/(authenticated)/layout.tsx` - Integrated ChatOverlay

### Features Implemented

✅ Persistent chat overlay accessible from any authenticated view
✅ Three states: Closed (floating button), Open (full panel), Minimized (header only)
✅ Keyboard shortcuts:

- Cmd/Ctrl + K: Open chat (when closed)
- Escape: Minimize chat (when open)
- Cmd/Ctrl + Shift + J: Toggle chat panel
  ✅ State persistence via localStorage
  ✅ Responsive design (full-width on mobile, sidebar on desktop)
  ✅ Wraps existing Chat component (reuses all chat functionality)
  ✅ PDA-friendly design with calm colors
  ✅ Accessibility labels and ARIA attributes

### Features Not Yet Implemented (Future Enhancements)

- Context awareness (passing current view/entity to chat) - Can be added later
- Enhanced animations (current implementation has basic transitions)
- Deep linking from Jarvis responses - Requires backend changes

## Testing

- Unit tests for chat components
- Integration tests for API endpoints
- E2E tests for chat overlay interaction
- WebSocket connection tests
- Keyboard shortcut tests
- Responsive design tests

## Notes

- Need to understand existing component patterns in apps/web
- Need to check if WebSocket infrastructure already exists
- Need to verify ClawdBot integration approach
- Should follow PDA-friendly design principles from DESIGN-PRINCIPLES.md