Initial commit: Obsidian Web Interface for Claude Code
- Full IDE with terminal integration using xterm.js - Session management with local and web sessions - HTML preview functionality - Multi-terminal support with session picker Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
uroma
247
docs/plans/2025-01-19-landing-page-workflow-design.md
Normal file
247
docs/plans/2025-01-19-landing-page-workflow-design.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# Landing Page Workflow Design
|
||||
|
||||
**Date:** 2025-01-19
|
||||
**Status:** Approved
|
||||
**Author:** Claude (with user collaboration)
|
||||
|
||||
## Overview
|
||||
|
||||
Enhance the `/claude/` landing page to provide a streamlined "Create New Project" or "Load Existing Project" workflow with improved UX while maintaining fast navigation to the IDE.
|
||||
|
||||
**Design Philosophy:** Speed and simplicity - minimize friction for developers who want to get from idea → code as quickly as possible.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Component Structure
|
||||
|
||||
```
|
||||
SessionsPage
|
||||
├── SessionsGrid (main container)
|
||||
│ └── SessionCard (enhanced with metadata)
|
||||
├── QuickStartGrid
|
||||
│ ├── TemplateCard (React, Node.js, etc.)
|
||||
│ └── BlankProjectCard (with inline name input)
|
||||
└── NavigationManager (handles transitions)
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
Page Load → Fetch sessions → Cache locally → Render grid
|
||||
↓
|
||||
User clicks card → Show loading overlay → Navigate to /claude/ide
|
||||
```
|
||||
|
||||
### State Management
|
||||
|
||||
```javascript
|
||||
{
|
||||
sessions: Map<sessionId, sessionData>,
|
||||
loading: boolean,
|
||||
error: string | null,
|
||||
isNavigating: boolean
|
||||
}
|
||||
```
|
||||
|
||||
## UI/UX Design
|
||||
|
||||
### Enhanced Session Cards
|
||||
|
||||
**Layout:**
|
||||
- **Left**: Icon (💬 active, 📁 historical)
|
||||
- **Middle**:
|
||||
- Project name (bold, 20px) - **inline editable**
|
||||
- Working directory (monospace, 13px, gray)
|
||||
- Last message preview (14px, truncated to 100 chars)
|
||||
- File count badge (📄 N files)
|
||||
- Relative time ("5 min ago")
|
||||
- **Right**:
|
||||
- **Continue** button (primary CTA)
|
||||
- ⋮ menu (Duplicate, Delete)
|
||||
|
||||
**Interactions:**
|
||||
- Hover: Lift effect (translateY: -4px), border highlight
|
||||
- Click project name → inline edit mode
|
||||
- Click Continue → loading overlay → navigate to IDE
|
||||
|
||||
### Inline Name Editing
|
||||
|
||||
- Click name → transforms to input field
|
||||
- Save on blur or Enter
|
||||
- Revert on Escape
|
||||
- Show spinner while saving
|
||||
- Validation: Max 50 chars, no special characters
|
||||
|
||||
### Blank Project Card
|
||||
|
||||
- Shows input field instead of static text
|
||||
- Placeholder: "Enter project name..."
|
||||
- Start button active when name entered
|
||||
- Creates session with `metadata.project` = name
|
||||
|
||||
### Loading States
|
||||
|
||||
- Full-page overlay with spinner
|
||||
- Message: "Opening workspace..." or "Creating project..."
|
||||
- Duration: 300-800ms minimum for smooth UX
|
||||
|
||||
### Quick Actions (Card Menu)
|
||||
|
||||
- **Continue**: Navigate to IDE chat with this session
|
||||
- **Duplicate**: Create new session with same dir/metadata
|
||||
- **Delete**: Remove session with confirmation
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Existing (to be enhanced)
|
||||
|
||||
**GET `/claude/api/claude/sessions`**
|
||||
- Enhancement: Include `lastMessage` and `fileCount` in response
|
||||
- Calculate from `outputBuffer` server-side
|
||||
|
||||
**POST `/claude/api/claude/sessions`**
|
||||
- Enhancement: Accept `metadata.project` for custom naming
|
||||
|
||||
### New Endpoints
|
||||
|
||||
**PATCH `/claude/api/claude/sessions/:id`**
|
||||
- Update session metadata
|
||||
- Body: `{ metadata: { project: "New Name" } }`
|
||||
- Returns: Updated session object
|
||||
|
||||
**POST `/claude/api/claude/sessions/:id/duplicate`**
|
||||
- Create new session with same working directory and metadata
|
||||
- Returns: `{ success: true, session: { id, ... } }`
|
||||
|
||||
**DELETE `/claude/api/claude/sessions/:id`**
|
||||
- Delete session file from disk
|
||||
- Returns: `{ success: true }`
|
||||
|
||||
## Data Handling
|
||||
|
||||
### File Count Calculation
|
||||
|
||||
```javascript
|
||||
function getFileCount(session) {
|
||||
const writeTags = session.outputBuffer.filter(entry =>
|
||||
entry.content.includes('<dyad-write')
|
||||
);
|
||||
return writeTags.length;
|
||||
}
|
||||
```
|
||||
|
||||
### Relative Time Format
|
||||
|
||||
```javascript
|
||||
function getRelativeTime(date) {
|
||||
const seconds = Math.floor((new Date() - date) / 1000);
|
||||
if (seconds < 60) return 'just now';
|
||||
if (seconds < 3600) return `${Math.floor(seconds/60)} min ago`;
|
||||
if (seconds < 86400) return `${Math.floor(seconds/3600)} hours ago`;
|
||||
return `${Math.floor(seconds/86400)} days ago`;
|
||||
}
|
||||
```
|
||||
|
||||
### Session Cache
|
||||
|
||||
- Use Map for O(1) lookups
|
||||
- Invalidate on explicit refresh or error
|
||||
- Serve stale data with error banner on fetch failure
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Network Failures
|
||||
|
||||
1. **Session fetch fails**
|
||||
- Show: "Failed to load sessions. 🔄 Retry"
|
||||
- Keep stale data if cached
|
||||
- Auto-retry after 30s (exponential backoff)
|
||||
|
||||
2. **Session creation fails**
|
||||
- Hide loading overlay
|
||||
- Toast: "Failed to create project: [error]"
|
||||
- Stay on landing page
|
||||
|
||||
3. **Name update fails**
|
||||
- Revert to original name
|
||||
- Toast: "Failed to save name"
|
||||
|
||||
### Empty States
|
||||
|
||||
**No sessions:**
|
||||
```
|
||||
📁 No projects yet
|
||||
|
||||
Create your first project to start building with AI
|
||||
[Templates below...]
|
||||
```
|
||||
|
||||
**No active sessions:**
|
||||
- Show: "No active projects"
|
||||
- CTA: "Create New Project"
|
||||
- Still show historical sessions
|
||||
|
||||
### Validation Rules
|
||||
|
||||
- Project name: Max 50 chars, no `/ \ < > : " | ? *`
|
||||
- Trim whitespace
|
||||
- Show character count: "23/50"
|
||||
|
||||
### Race Conditions
|
||||
|
||||
- **Rapid clicking**: `isNavigating` flag, disable clicks during navigation
|
||||
- **Edit while deleted**: On save failure, refresh list, show "Session no longer exists"
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Backend Enhancements (1-2 hours)
|
||||
- [ ] Add `PATCH /sessions/:id` endpoint
|
||||
- [ ] Add `POST /sessions/:id/duplicate` endpoint
|
||||
- [ ] Add `DELETE /sessions/:id` endpoint
|
||||
- [ ] Enhance session list with `lastMessage` and `fileCount`
|
||||
|
||||
### Phase 2: Frontend Components (2-3 hours)
|
||||
- [ ] Refactor `sessions-landing.js` with state management
|
||||
- [ ] Create `SessionCard` class/component
|
||||
- [ ] Implement inline name editing
|
||||
- [ ] Add loading overlays
|
||||
|
||||
### Phase 3: Quick Start Enhancement (1 hour)
|
||||
- [ ] Add project name input to blank project card
|
||||
- [ ] Pass name to API on creation
|
||||
|
||||
### Phase 4: Polish (1 hour)
|
||||
- [ ] Relative time formatting
|
||||
- [ ] Card hover effects
|
||||
- [ ] Error toasts and retry
|
||||
- [ ] End-to-end testing
|
||||
|
||||
**Total Estimate:** 5-7 hours
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Create blank project with custom name
|
||||
- [ ] Create project from template
|
||||
- [ ] Edit project name inline
|
||||
- [ ] Continue to IDE chat
|
||||
- [ ] Duplicate session
|
||||
- [ ] Delete session
|
||||
- [ ] View empty session
|
||||
- [ ] View session with files
|
||||
- [ ] Network failure handling
|
||||
- [ ] Empty state display
|
||||
- [ ] Rapid clicking (race conditions)
|
||||
- [ ] Historical vs active display
|
||||
- [ ] Mobile responsive
|
||||
|
||||
**Browsers:** Chrome, Firefox, Safari
|
||||
**Screen Sizes:** Desktop (1920px), Tablet (768px), Mobile (375px)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. ✅ Users can create/load projects in 1-2 clicks
|
||||
2. ✅ Navigation to IDE takes < 1 second perceived time
|
||||
3. ✅ All error states handled gracefully
|
||||
4. ✅ Project names are editable and persist
|
||||
5. ✅ Mobile-responsive design
|
||||
6. ✅ No data loss on network failures
|
||||
Reference in New Issue
Block a user