docs(21-04): complete chat panel shell plan

- 21-04-SUMMARY.md with task details, deviations, known stubs - STATE.md: advanced to plan 4, updated progress 67%, added decisions - ROADMAP.md: phase 21 updated (4/6 summaries) - REQUIREMENTS.md: INPUT-01 and THEME-01 marked complete
2026-04-01 16:51:15 +00:00 · 2026-04-01 16:51:15 +00:00 · c3c4145f9b
commit c3c4145f9b
parent 6bfabdb701
4 changed files with 134 additions and 13 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@ -29,7 +29,7 @@

 ### Input (7)

- [ ] **INPUT-01** — Multi-line text input with auto-resize: grows with content up to a max height before scrolling
+- [x] **INPUT-01** — Multi-line text input with auto-resize: grows with content up to a max height before scrolling
 - [ ] **INPUT-02** — File/image upload via drag-and-drop or button with inline preview before sending
 - [ ] **INPUT-03** — Paste image from clipboard directly into the chat input
 - [ ] **INPUT-04** — Voice input via Whisper (when local AI is enabled): record button with transcription preview before sending
@ -69,7 +69,7 @@

 ### Theme Integration (3)

- [ ] **THEME-01** — Chat interface respects the Nexus theme system (Catppuccin Mocha, Tokyo Night, Catppuccin Latte)
+- [x] **THEME-01** — Chat interface respects the Nexus theme system (Catppuccin Mocha, Tokyo Night, Catppuccin Latte)
 - [x] **THEME-02** — Code blocks use theme-appropriate syntax highlighting colors
 - [ ] **THEME-03** — Agent avatars/colors are visually distinguishable in all three themes

@ -132,7 +132,7 @@ The following are explicitly deferred:
 | CHAT-12 | Phase 22 | Pending |
 | CHAT-13 | Phase 24 | Pending |
 | CHAT-14 | Phase 24 | Pending |
-| INPUT-01 | Phase 21 | Pending |
+| INPUT-01 | Phase 21 | Complete |
 | INPUT-02 | Phase 25 | Pending |
 | INPUT-03 | Phase 25 | Pending |
 | INPUT-04 | Phase 25 | Pending |
@ -160,7 +160,7 @@ The following are explicitly deferred:
 | PWA-06 | Phase 26 | Pending |
 | PWA-07 | Phase 26 | Pending |
 | PWA-08 | Phase 26 | Pending |
-| THEME-01 | Phase 21 | Pending |
+| THEME-01 | Phase 21 | Complete |
 | THEME-02 | Phase 21 | Complete |
 | THEME-03 | Phase 22 | Pending |
 | PERF-01 | Phase 26 | Pending |
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -31,14 +31,14 @@
  3. Agent messages render with full markdown: code blocks with syntax highlighting and a copy button, tables, lists, headings, links, and inline images
  4. Conversations and all messages are stored in libSQL and survive a server restart
  5. The chat interface applies Catppuccin Mocha, Tokyo Night, and Catppuccin Latte themes correctly; code block highlighting matches the active theme
-**Plans:** 3/6 plans executed
+**Plans:** 4/6 plans executed

 Plans:
 - [x] 21-00-PLAN.md — Wave 0 test stubs (chat-service, chat-routes, ChatMarkdownMessage, ChatInput)
 - [x] 21-01-PLAN.md — DB schema (chat_conversations + chat_messages) and shared types/validators
 - [x] 21-02-PLAN.md — Markdown renderer with rehype-highlight, code block copy button, theme CSS
 - [ ] 21-03-PLAN.md — Server chat service and REST API routes (CRUD + pagination)
- [ ] 21-04-PLAN.md — ChatPanel shell, ChatPanelContext, ChatInput, Layout integration
+- [x] 21-04-PLAN.md — ChatPanel shell, ChatPanelContext, ChatInput, Layout integration
 - [ ] 21-05-PLAN.md — Full UI wiring: API client, conversation list, message thread, infinite scroll

 **UI hint**: yes
@ -189,7 +189,7 @@ All 65 v1 requirements are mapped to exactly one phase. No orphans.

 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
-| 21. Chat Foundation | v1.3 | 2/6 | In Progress|  |
+| 21. Chat Foundation | v1.3 | 4/6 | In Progress|  |
 | 22. Agent Streaming | v1.3 | 0/? | Not started | - |
 | 23. Brainstormer Flow | v1.3 | 0/? | Not started | - |
 | 24. Search, History & Branching | v1.3 | 0/? | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.3
 milestone_name: milestone
 status: executing
-stopped_at: Completed 21-chat-foundation-21-02-PLAN.md
-last_updated: "2026-04-01T16:42:00.000Z"
+stopped_at: Completed 21-chat-foundation-21-04-PLAN.md
+last_updated: "2026-04-01T16:50:55.752Z"
 last_activity: 2026-04-01
 progress:
  total_phases: 6
  completed_phases: 0
  total_plans: 6
-  completed_plans: 2
+  completed_plans: 4
  percent: 0
 ---

@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-03-30)
 ## Current Position

 Phase: 21 (chat-foundation) — EXECUTING
-Plan: 3 of 6
+Plan: 4 of 6
 Status: Ready to execute
 Last activity: 2026-04-01

@ -62,6 +62,7 @@ Progress: [░░░░░░░░░░] 0%
 | Phase 21-chat-foundation P02 | ~15min | 2 tasks | 5 files |
 | Phase 21-chat-foundation P01 | 2 | 2 tasks | 8 files |
 | Phase 21-chat-foundation P00 | 2 | 2 tasks | 4 files |
+| Phase 21-chat-foundation P04 | 4min | 2 tasks | 7 files |

 ## Accumulated Context

@ -84,6 +85,8 @@ Recent decisions affecting current work:
 - [Phase 21-chat-foundation]: Minimal imports in test stubs — no service mocks until Plans 01-05 wire up implementations
 - [Phase 21-02]: Use ExtraProps from react-markdown for ChatCodeBlock type signature to satisfy ComponentType constraint
 - [Phase 21-02]: Add hljs CSS as plain rules (not @import) scoped to .dark, .theme-tokyo-night, :root selectors
+- [Phase 21-chat-foundation]: ChatPanelProvider inside PanelProvider so ChatPanel can call setPanelVisible to close PropertiesPanel
+- [Phase 21-chat-foundation]: Chat toggle button in desktop sidebar bottom controls with hidden md:inline-flex

 ### Pending Todos

@ -96,6 +99,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-04-01T16:42:00.000Z
-Stopped at: Completed 21-chat-foundation-21-02-PLAN.md
+Last session: 2026-04-01T16:50:55.749Z
+Stopped at: Completed 21-chat-foundation-21-04-PLAN.md
 Resume file: None
--- a/.planning/phases/21-chat-foundation/21-04-SUMMARY.md
+++ b/.planning/phases/21-chat-foundation/21-04-SUMMARY.md
@ -0,0 +1,118 @@
+---
+phase: 21-chat-foundation
+plan: "04"
+subsystem: ui
+tags: [chat, context, components, layout, tdd]
+dependency_graph:
+  requires: ["21-00", "21-02"]
+  provides: [ChatPanelContext, ChatPanel, ChatInput, ChatMessage]
+  affects: [Layout, main.tsx]
+tech_stack:
+  added: []
+  patterns: [Context + hook pattern with localStorage persistence, TDD with jsdom+createRoot]
+key_files:
+  created:
+    - ui/src/context/ChatPanelContext.tsx
+    - ui/src/components/ChatPanel.tsx
+    - ui/src/components/ChatInput.tsx
+    - ui/src/components/ChatMessage.tsx
+  modified:
+    - ui/src/components/ChatInput.test.tsx
+    - ui/src/components/Layout.tsx
+    - ui/src/main.tsx
+decisions:
+  - ChatPanelProvider inserted inside PanelProvider so ChatPanel can call setPanelVisible to close PropertiesPanel on open
+  - Chat toggle button placed in desktop sidebar bottom controls with hidden md:inline-flex (same cluster as settings and theme)
+  - ChatMessage uses plain text for user role (no markdown) and ChatMarkdownMessage for assistant role
+metrics:
+  duration: "~4 minutes"
+  completed: "2026-04-01"
+  tasks_completed: 2
+  files_created: 4
+  files_modified: 3
+---
+
+# Phase 21 Plan 04: Chat Panel Shell and Context Summary
+
+**One-liner:** Chat drawer shell with ChatPanelProvider (localStorage persistence), auto-resize ChatInput (Enter/Shift+Enter/Escape), ChatMessage bubbles, and Layout integration toggling PropertiesPanel closed on open.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | Create ChatPanelContext, ChatInput, ChatMessage (TDD) | acfe2a7a | ChatPanelContext.tsx, ChatInput.tsx, ChatMessage.tsx, ChatInput.test.tsx |
+| 2 | Create ChatPanel shell and wire into Layout + main.tsx | b1c9dbfb | ChatPanel.tsx, Layout.tsx, main.tsx |
+
+## What Was Built
+
+### ChatPanelContext (ui/src/context/ChatPanelContext.tsx)
+
+Mirrors PanelContext pattern:
+- `STORAGE_KEY = "nexus:chat-panel-open"` — localStorage persistence
+- Default state: `false` (chat starts closed, unlike PropertiesPanel which defaults to visible)
+- Exports `ChatPanelProvider` and `useChatPanel`
+- Tracks `chatOpen`, `activeConversationId`, `setChatOpen`, `toggleChat`, `setActiveConversationId`
+
+### ChatInput (ui/src/components/ChatInput.tsx)
+
+- `<textarea>` with `[field-sizing:content]` for modern auto-resize + `useEffect` fallback via `scrollHeight`
+- `max-h-[160px] min-h-[40px]` constraints
+- `onKeyDown`: Enter (no Shift, no composing) → submit; Escape → clear; Shift+Enter → native newline
+- Send `Button variant="ghost" size="icon"` with `aria-label="Send message"`
+- Shows `Loader2 animate-spin` when `isSubmitting=true`; button disabled when empty or submitting
+
+### ChatMessage (ui/src/components/ChatMessage.tsx)
+
+- User role: right-aligned bubble with `bg-secondary px-3 py-2` — plain text (no markdown)
+- Assistant/system role: full-width, rendered via `ChatMarkdownMessage`
+
+### ChatPanel (ui/src/components/ChatPanel.tsx)
+
+- `<aside aria-label="Chat">` with `hidden md:flex` (desktop only)
+- Width animation: `style={{ width: chatOpen ? 380 : 0 }}` + `transition-[width] duration-100 ease-out`
+- `min-w-[380px]` on inner containers prevents content collapse during animation
+- Two-column: 160px conversation list placeholder (Plan 05) + flex thread area with `ScrollArea` + `ChatInput`
+- Header with X close button (`setChatOpen(false)`)
+
+### Layout.tsx Changes
+
+- Added imports: `MessageSquare` from lucide, `ChatPanel`, `useChatPanel`
+- `const { chatOpen, toggleChat } = useChatPanel()` in `Layout()`
+- `useEffect` closes `PropertiesPanel` when `chatOpen` becomes true via `setPanelVisible(false)`
+- Chat toggle `Button` with `aria-label="chat open/close"` in desktop sidebar bottom controls
+- `<ChatPanel />` rendered before `<PropertiesPanel />` in the flex row
+
+### main.tsx Changes
+
+- `ChatPanelProvider` wraps app inside `PanelProvider` (ordering ensures ChatPanel can access PanelContext)
+
+## Verification Results
+
+- TypeScript: `pnpm --filter @paperclipai/ui exec -- tsc --noEmit` — passes (no errors)
+- Tests: `pnpm vitest run ui/src/components/ChatInput.test.tsx` — 6/6 passing
+- Acceptance criteria: all verified via grep checks
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed createRoot warning in tests**
+- **Found during:** Task 1 (TDD RED→GREEN)
+- **Issue:** The afterEach cleanup was calling `createRoot(container)` on an already-rooted container, producing a React warning
+- **Fix:** Track the root in a `let root` variable in the describe scope, unmount it in afterEach rather than creating a new root to unmount
+- **Files modified:** ui/src/components/ChatInput.test.tsx
+- **Commit:** acfe2a7a
+
+None of the original plan tasks required architectural changes.
+
+## Known Stubs
+
+| File | Location | Description | Resolved by |
+|------|----------|-------------|-------------|
+| ui/src/components/ChatPanel.tsx | onSend handler | `console.log("send:", content)` — not wired to API | Plan 05 |
+| ui/src/components/ChatPanel.tsx | Conversation list column | "No conversations yet" placeholder | Plan 05 |
+| ui/src/components/ChatPanel.tsx | Message thread area | "Send a message to start this conversation." placeholder | Plan 05 |
+
+These stubs are intentional — Plan 04 is the shell/skeleton. Plan 05 wires the API.
+
+## Self-Check: PASSED