SuperCharged-Claude-Code-Upgrade/docs/plans/2025-01-19-landing-page-workflow-design.md

# 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