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

• Create scratchpad
• Explore current codebase structure
• Identify existing chat implementation
• Identify backend WebSocket infrastructure
• Plan component architecture
• Write tests for useChatOverlay hook (14 tests)
• Implement useChatOverlay hook (all tests passing)
• Write tests for ChatOverlay component (18 tests)
• Implement ChatOverlay component (all tests passing)
• Add keyboard shortcuts (Cmd+K, Escape, Cmd+Shift+J)
• Write tests for keyboard shortcuts (included in component tests)
• Integrate into authenticated layout
• Test context awareness (will be added later as enhancement)
• 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