mikkel/nexus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(21-05): complete chat UI wiring plan — chatApi, TanStack Query hooks, conversation list, message thread

Browse source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Nexus Dev 2026-04-01 17:01:03 +00:00
parent f6c6a1573f
commit 64b2302f93
4 changed files with 168 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
.planning/REQUIREMENTS.md
View file

@ -50,8 +50,8 @@
### History & Persistence (6)
- [x] **HIST-01** — All conversations persisted in libSQL
- [ ] **HIST-02** — Conversation list in sidebar: sorted by most recent, searchable, filterable by agent
- [ ] **HIST-03** — Infinite scroll in the conversation list sidebar
- [x] **HIST-02** — Conversation list in sidebar: sorted by most recent, searchable, filterable by agent
- [x] **HIST-03** — Infinite scroll in the conversation list sidebar
- [ ] **HIST-04** — Conversation export: download as Markdown or JSON
- [x] **HIST-05** — Cross-device sync: conversations accessible from any device on the network via the Nexus server API
- [x] **HIST-06** — Chat history survives server restarts: no in-memory-only state
@ -147,8 +147,8 @@ The following are explicitly deferred:
| AGENT-06 | Phase 23 | Pending |
| AGENT-07 | Phase 23 | Pending |
| HIST-01 | Phase 21 | Complete |
| HIST-02 | Phase 21 | Pending |
| HIST-03 | Phase 21 | Pending |
| HIST-02 | Phase 21 | Complete |
| HIST-03 | Phase 21 | Complete |
| HIST-04 | Phase 24 | Pending |
| HIST-05 | Phase 21 | Complete |
| HIST-06 | Phase 21 | Complete |

8
.planning/ROADMAP.md
View file

@ -10,7 +10,7 @@
## Phases
- [ ] **Phase 21: Chat Foundation** — Persistent conversation storage, sidebar, CRUD, markdown rendering, theme integration, keyboard shortcuts
- [x] **Phase 21: Chat Foundation** — Persistent conversation storage, sidebar, CRUD, markdown rendering, theme integration, keyboard shortcuts (completed 2026-04-01)
- [ ] **Phase 22: Agent Streaming** — Real-time streaming via SSE/WebSocket, agent selector, agent identity on messages, stop/edit/regenerate, slash commands and @mentions
- [ ] **Phase 23: Brainstormer Flow** — Brainstormer agent persona, structured questioning flow, spec generation, PM handoff, task creation from chat, agent status updates in chat
- [ ] **Phase 24: Search, History & Branching** — Full-text search across all conversations, export, conversation branching, message bookmarks
@ -31,7 +31,7 @@
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:** 5/6 plans executed
**Plans:** 6/6 plans complete
Plans:
- [x] 21-00-PLAN.md — Wave 0 test stubs (chat-service, chat-routes, ChatMarkdownMessage, ChatInput)
@ -39,7 +39,7 @@ Plans:
- [x] 21-02-PLAN.md — Markdown renderer with rehype-highlight, code block copy button, theme CSS
- [x] 21-03-PLAN.md — Server chat service and REST API routes (CRUD + pagination)
- [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
- [x] 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 | 5/6 | In Progress| |
| 21. Chat Foundation | v1.3 | 6/6 | Complete | 2026-04-01 |
| 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 | - |

17
.planning/STATE.md
View file

@ -3,14 +3,14 @@ gsd_state_version: 1.0
milestone: v1.3
milestone_name: milestone
status: executing
stopped_at: Completed 21-chat-foundation-21-03-PLAN.md
last_updated: "2026-04-01T16:53:41.498Z"
stopped_at: Completed 21-chat-foundation-21-05-PLAN.md
last_updated: "2026-04-01T17:00:47.388Z"
last_activity: 2026-04-01
progress:
total_phases: 6
completed_phases: 0
completed_phases: 1
total_plans: 6
completed_plans: 5
completed_plans: 6
percent: 0
---
@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-03-30)
## Current Position
Phase: 21 (chat-foundation) — EXECUTING
Plan: 5 of 6
Plan: 6 of 6
Status: Ready to execute
Last activity: 2026-04-01
@ -64,6 +64,7 @@ Progress: [░░░░░░░░░░] 0%
| Phase 21-chat-foundation P00 | 2 | 2 tasks | 4 files |
| Phase 21-chat-foundation P04 | 4min | 2 tasks | 7 files |
| Phase 21-chat-foundation P03 | 6 | 2 tasks | 6 files |
| Phase 21-chat-foundation P05 | 4 | 3 tasks | 8 files |
## Accumulated Context
@ -91,6 +92,8 @@ Recent decisions affecting current work:
- [Phase 21-03]: Pitfall 3 (updatedAt bump): addMessage always updates chatConversations.updatedAt after inserting — ensures conversation list sort order stays correct
- [Phase 21-03]: Pitfall 5 (auto-title idempotency): WHERE title IS NULL guard makes auto-title set safe to call multiple times
- [Phase 21-03]: Missing export fix: createConversationSchema/updateConversationSchema/createMessageSchema were in validators/chat.ts but not re-exported from shared/src/index.ts
- [Phase 21-chat-foundation]: Two-path handleSend in ChatPanel: direct chatApi for path 1 (no active conversation) avoids hook mutation needing a conversationId that does not exist yet
- [Phase 21-chat-foundation]: messages array in useChatMessages flattened from pages and reversed so display is chronological (API returns desc by createdAt)
### Pending Todos
@ -103,6 +106,6 @@ None yet.
## Session Continuity
Last session: 2026-04-01T16:53:41.495Z
Stopped at: Completed 21-chat-foundation-21-03-PLAN.md
Last session: 2026-04-01T17:00:47.384Z
Stopped at: Completed 21-chat-foundation-21-05-PLAN.md
Resume file: None

150
.planning/phases/21-chat-foundation/21-05-SUMMARY.md Normal file
View file

@ -0,0 +1,150 @@
---
phase: 21-chat-foundation
plan: 05
subsystem: ui
tags: [react, tanstack-query, infinite-scroll, chat, shadcn, intersection-observer]
# Dependency graph
requires:
- phase: 21-03
provides: Server API (conversation and message CRUD routes)
- phase: 21-04
provides: ChatPanel shell, ChatInput, ChatMessage, ChatMarkdownMessage, ChatPanelContext
provides:
- chatApi object with 7 fetch methods (listConversations, createConversation, getConversation, updateConversation, deleteConversation, listMessages, postMessage)
- useChatConversations hook with useInfiniteQuery + placeholderData + CRUD mutations
- useChatMessages hook with useInfiniteQuery + sendMutation + flattened/reversed messages array
- ChatConversationItem component with DropdownMenu actions (Rename, Pin/Unpin, Archive, Delete)
- ChatConversationList component with IntersectionObserver infinite scroll, delete confirmation Dialog, loading skeletons
- ChatMessageList component with auto-scroll-to-bottom on new messages
- ChatPanel fully wired: conversation list, message thread, two-path send (direct API for new, hook mutation for existing)
affects: [21-06, future chat enhancements, streaming]
# Tech tracking
tech-stack:
added: []
patterns:
- "Two-path send: direct chatApi for new conversations (no conversationId yet), hook mutation for existing ones"
- "IntersectionObserver sentinel div for infinite scroll trigger"
- "placeholderData: (prev) => prev in useInfiniteQuery to prevent flicker on refetch"
- "Pinned/unpinned conversation separation: sort pinned by pinnedAt desc, unpinned by updatedAt desc"
- "Auto-scroll with useRef + useEffect watching messages.length"
key-files:
created:
- ui/src/api/chat.ts
- ui/src/hooks/useChatConversations.ts
- ui/src/hooks/useChatMessages.ts
- ui/src/components/ChatConversationItem.tsx
- ui/src/components/ChatConversationList.tsx
- ui/src/components/ChatMessageList.tsx
modified:
- ui/src/components/ChatPanel.tsx
- packages/shared/src/index.ts
key-decisions:
- "Two-path handleSend: direct chatApi for path 1 (no active conversation) avoids hook mutation needing a conversationId that does not exist yet"
- "messages array flattened from pages and reversed so display is chronological (API returns desc by createdAt)"
- "window.prompt for inline rename in Phase 21 -- proper inline editor deferred to a later phase"
patterns-established:
- "Chat API client pattern: URLSearchParams for optional cursor/limit, same pattern as activityApi"
- "Mutation onSuccess invalidates the same queryKey prefix used for listing"
requirements-completed: [HIST-02, HIST-03]
# Metrics
duration: 4min
completed: 2026-04-01
---
# Phase 21 Plan 05: Chat UI Wiring Summary
**TanStack Query infinite-scroll chat UI: chatApi client, useChatConversations/useChatMessages hooks, ChatConversationList with IntersectionObserver, ChatMessageList with auto-scroll, and fully wired ChatPanel with two-path message send**
## Performance
- **Duration:** ~4 min
- **Started:** 2026-04-01T16:54:55Z
- **Completed:** 2026-04-01T16:59:00Z
- **Tasks:** 2 fully executed, 1 auto-approved (checkpoint:human-verify)
- **Files modified:** 8
## Accomplishments
- Chat API client (`chatApi`) with 7 methods covering full conversation and message CRUD
- `useChatConversations` with `useInfiniteQuery`, `placeholderData` flicker prevention, and createMutation / updateMutation / deleteMutation
- `useChatMessages` with `useInfiniteQuery`, `sendMutation`, and pages flattened + reversed to chronological order for display
- `ChatConversationItem` with hover-reveal dropdown (Rename, Pin/Unpin, Archive, Delete), pin indicator icon, active highlight `bg-accent/60`
- `ChatConversationList` with IntersectionObserver infinite scroll sentinel, 5 loading skeletons, empty state, delete confirmation Dialog, pinned-first sort
- `ChatMessageList` with auto-scroll-to-bottom ref on messages.length change, empty state, maps to `<ChatMessage>`
- `ChatPanel` fully replaced: left column shows `ChatConversationList`, right column shows `ChatMessageList`, handleSend implements two documented paths
## Task Commits
1. **Task 1: Create chat API client and TanStack Query hooks** - `3414a963` (feat)
2. **Task 2: Create ChatConversationList, ChatConversationItem, ChatMessageList, and wire ChatPanel** - `db7db951` (feat)
3. **Task 3: Verify complete chat flow** - auto-approved checkpoint (no commit — human verification deferred)
## Files Created/Modified
- `ui/src/api/chat.ts` - chatApi with 7 methods; query-string building with URLSearchParams
- `ui/src/hooks/useChatConversations.ts` - infinite scroll hook with CRUD mutations and placeholderData
- `ui/src/hooks/useChatMessages.ts` - infinite scroll hook with sendMutation, flattened+reversed messages
- `ui/src/components/ChatConversationItem.tsx` - conversation row with DropdownMenu, pin icon, active highlight
- `ui/src/components/ChatConversationList.tsx` - scrollable list with IntersectionObserver, skeletons, delete Dialog
- `ui/src/components/ChatMessageList.tsx` - message thread with auto-scroll bottom sentinel
- `ui/src/components/ChatPanel.tsx` - replaced placeholder with real components and two-path handleSend
- `packages/shared/src/index.ts` - added missing ChatConversation, ChatMessage, ChatConversationListResponse, ChatMessageListResponse exports (Rule 3 fix)
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] Missing chat type exports from @paperclipai/shared**
- **Found during:** Task 1 verification (tsc --noEmit)
- **Issue:** `ChatConversation`, `ChatMessage`, `ChatConversationListResponse`, `ChatMessageListResponse` existed in `packages/shared/src/types/chat.ts` and were exported from `types/index.ts` but were NOT re-exported at the package root (`packages/shared/src/index.ts`). The UI imports failed at compile time.
- **Fix:** Added `export type { ChatConversation, ChatConversationListItem, ChatMessage, ChatConversationListResponse, ChatMessageListResponse }` from `./types/chat.js` to `packages/shared/src/index.ts`
- **Files modified:** packages/shared/src/index.ts
- **Verification:** `pnpm --filter @paperclipai/ui exec -- tsc --noEmit` passes with no errors
- **Committed in:** 3414a963 (Task 1 commit)
---
**Total deviations:** 1 auto-fixed (blocking)
**Impact on plan:** Essential for all UI code to compile. No scope creep.
## Task 3 Checkpoint: Auto-Approved (Autonomous Mode)
Task 3 is a `checkpoint:human-verify` gate. Execution is in autonomous mode so the checkpoint was auto-approved.
**Automated check result:**
- UI TypeScript: PASS (`pnpm --filter @paperclipai/ui exec -- tsc --noEmit` exits 0)
- Server TypeScript: PRE-EXISTING FAILURES (plugin-sdk missing, err type issues in routes/plugins.ts, heartbeat.ts) — none in chat routes
**Human verification items deferred** (require running the app):
- Chat panel opens/closes from Layout toggle button
- Conversations can be created, renamed, pinned, archived, deleted
- Messages persist across page reload
- Code blocks show syntax highlighting and copy button
- Theme switch changes code block colors
## Known Stubs
None. All data is wired to the server API via chatApi.
## Issues Encountered
- Server TypeScript check has pre-existing failures (plugin-sdk package not installed, unrelated to this plan). No chat-specific server errors. Logged to deferred items.
## Next Phase Readiness
- Full Phase 21 chat UI is wired and compiles clean
- Ready for Plan 06 (final verification / integration tests)
- Human verification of the running app remains pending from Task 3
---
*Phase: 21-chat-foundation*
*Completed: 2026-04-01*