NomadArch/dev-docs/user-interface.md

# User Interface Specification

## Overview

The CodeNomad interface consists of a two-level tabbed layout with instance tabs at the top and session tabs below. Each session displays a message stream and prompt input.

## Layout Structure

```
┌──────────────────────────────────────────────────────────────┐
│ File  Edit  View  Window  Help                    ● ○ ◐     │ ← Native menu bar
├──────────────────────────────────────────────────────────────┤
│ [~/project-a] [~/project-a (2)] [~/api-service] [+]         │ ← Instance tabs (Level 1)
├──────────────────────────────────────────────────────────────┤
│ [Main] [Fix login] [Write tests] [Logs] [+]                 │ ← Session tabs (Level 2)
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Messages Area                                          │ │
│  │                                                        │ │
│  │ User: How do I set up testing?                        │ │
│  │                                                        │ │
│  │ Assistant: To set up testing, you'll need to...       │ │
│  │ → bash: npm install vitest                     ✓      │ │
│  │   Output: added 50 packages                           │ │
│  │                                                        │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│ Agent: Build ▼        Model: Claude 3.5 Sonnet ▼            │ ← Controls
├──────────────────────────────────────────────────────────────┤
│ [@file.ts] [@api.ts] [×]                                    │ ← Attachments
│ ┌────────────────────────────────────────────────────────┐  │
│ │ Type your message or /command...                       │  │ ← Prompt input
│ │                                                        │  │
│ └────────────────────────────────────────────────────────┘  │
│                                                          [▶] │ ← Send button
└──────────────────────────────────────────────────────────────┘
```

## Components Specification

### 1. Instance Tabs (Level 1)

**Visual Design:**

- Horizontal tabs at top of window
- Each tab shows folder name
- Icon: Folder icon (🗂️)
- Close button (×) on hover
- Active tab: Highlighted with accent color
- Inactive tabs: Muted background

**Tab Label Format:**

- Single instance: `~/project-name`
- Multiple instances of same folder: `~/project-name (2)`, `~/project-name (3)`
- Max width: 200px with ellipsis for long paths
- Tooltip shows full path on hover

**Actions:**

- Click: Switch to that instance
- Close (×): Stop server and close instance (with confirmation)
- Drag: Reorder tabs (future)

**New Instance Button (+):**

- Always visible at right end
- Click: Opens folder picker dialog
- Keyboard: Cmd/Ctrl+N

**States:**

- Starting: Loading spinner + "Starting..."
- Ready: Normal appearance
- Error: Red indicator + error icon
- Stopped: Grayed out (should not be visible, tab closes)

### 2. Session Tabs (Level 2)

**Visual Design:**

- Horizontal tabs below instance tabs
- Smaller than instance tabs
- Each tab shows session title or "Untitled"
- Active tab: Underline or bold
- Parent-child relationship: No visual distinction (all siblings)

**Tab Types:**

**Session Tab:**

- Label: Session title (editable on double-click)
- Icon: Chat bubble (💬) or none
- Close button (×) on hover
- Max width: 150px with ellipsis

**Logs Tab:**

- Label: "Logs"
- Icon: Terminal (⚡)
- Always present per instance
- Non-closable
- Shows server stdout/stderr

**Actions:**

- Click: Switch to that session
- Double-click label: Rename session
- Close (×): Delete session (with confirmation if has messages)
- Right-click: Context menu (Share, Export, Delete)

**New Session Button (+):**

- Click: Creates new session with default agent
- Keyboard: Cmd/Ctrl+T

### 3. Messages Area

**Container:**

- Scrollable viewport
- Auto-scroll to bottom when new messages arrive
- Manual scroll up: Disable auto-scroll
- "Scroll to bottom" button appears when scrolled up

**Message Layout:**

**User Message:**

```
┌──────────────────────────────────────────┐
│ You                            10:32 AM  │
│ How do I set up testing?                │
│                                          │
│ [@src/app.ts] [@package.json]           │ ← Attachments if any
└──────────────────────────────────────────┘
```

**Assistant Message:**

````
┌──────────────────────────────────────────┐
│ Assistant • Build              10:32 AM  │
│ To set up testing, you'll need to        │
│ install Vitest and configure it.         │
│                                          │
│ ▶ bash: npm install vitest        ✓     │ ← Tool call (collapsed)
│                                          │
│ ▶ edit src/vitest.config.ts      ✓     │
│                                          │
│ Here's the configuration I added:        │
│ ```typescript                            │
│ export default {                         │
│   test: { globals: true }                │
│ }                                        │
│ ```                                      │
└──────────────────────────────────────────┘
````

**Tool Call (Collapsed):**

```
▶ bash: npm install vitest                    ✓
  ^   ^                                       ^
  |   |                                       |
Icon Tool name + summary                   Status
```

**Tool Call (Expanded):**

```
▼ bash: npm install vitest                    ✓

  Input:
  {
    "command": "npm install vitest"
  }

  Output:
  added 50 packages, and audited 51 packages in 2s
  found 0 vulnerabilities
```

**Status Icons:**

- ⏳ Pending (spinner)
- ✓ Success (green checkmark)
- ✗ Error (red X)
- ⚠ Warning (yellow triangle)

**File Change Display:**

```
▶ edit src/vitest.config.ts                   ✓
  Modified: src/vitest.config.ts
  +12 lines, -3 lines
```

Click to expand: Show diff inline

### 4. Controls Bar

**Agent Selector:**

- Dropdown button showing current agent
- Click: Opens dropdown with agent list
- Shows: Agent name + description
- Grouped by category (if applicable)

**Model Selector:**

- Dropdown button showing current model
- Click: Opens dropdown with model list
- Shows: Provider icon + Model name
- Grouped by provider
- Displays: Context window, capabilities icons

**Layout:**

```
┌────────────────────────────────────────────┐
│ Agent: Build ▼    Model: Claude 3.5 ▼     │
└────────────────────────────────────────────┘
```

### 5. Prompt Input

**Input Field:**

- Multi-line textarea
- Auto-expanding (max 10 lines)
- Placeholder: "Type your message or /command..."
- Supports keyboard shortcuts

**Features:**

**Slash Commands:**

- Type `/` → Autocomplete dropdown appears
- Shows: Command name + description
- Filter as you type
- Enter to execute

**File Mentions:**

- Type `@` → File picker appears
- Search files by name
- Shows: File icon + path
- Enter to attach

**Attachments:**

- Display as chips above input
- Format: [@filename] [×]
- Click × to remove
- Drag & drop files onto input area

**Send Button:**

- Icon: Arrow (▶) or paper plane
- Click: Submit message
- Keyboard: Enter (without Shift)
- Disabled when: Empty input or server busy

**Keyboard Shortcuts:**

- Enter: New line
- Cmd+Enter (macOS) / Ctrl+Enter (Windows/Linux): Send message
- Cmd/Ctrl+K: Clear input
- Cmd/Ctrl+V: Paste (handles files)
- Cmd/Ctrl+L: Focus input
- Up/Down: Navigate message history (when input empty)

## Overlays & Modals

### Session Picker (Startup)

Appears when instance starts:

```
┌────────────────────────────────────────┐
│  OpenCode • ~/project-a                │
├────────────────────────────────────────┤
│  Resume a session:                     │
│                                        │
│  > Fix login bug            2h ago     │
│    Add dark mode            5h ago     │
│    Refactor API             Yesterday  │
│                                        │
│  ────────────── or ──────────────      │
│                                        │
│  Start new session:                    │
│  Agent: [Build ▼]  [Start]             │
│                                        │
│  [Cancel]                              │
└────────────────────────────────────────┘
```

**Actions:**

- Click session: Resume that session
- Click "Start": Create new session with selected agent
- Click "Cancel": Close instance
- Keyboard: Arrow keys to navigate, Enter to select

### Confirmation Dialogs

**Close Instance:**

```
┌────────────────────────────────────────┐
│  Stop OpenCode instance?               │
├────────────────────────────────────────┤
│  This will stop the server for:        │
│  ~/project-a                           │
│                                        │
│  Active sessions will be lost.         │
│                                        │
│  [Cancel]  [Stop Instance]             │
└────────────────────────────────────────┘
```

**Delete Session:**

```
┌────────────────────────────────────────┐
│  Delete session?                       │
├────────────────────────────────────────┤
│  This will permanently delete:         │
│  "Fix login bug"                       │
│                                        │
│  This cannot be undone.                │
│                                        │
│  [Cancel]  [Delete]                    │
└────────────────────────────────────────┘
```

## Empty States

### No Instances

```
┌──────────────────────────────────────────┐
│                                          │
│           [Folder Icon]                  │
│                                          │
│        Start Coding with AI        │
│                                          │
│  Select a folder to start coding with AI │
│                                          │
│     [Select Folder]                      │
│                                          │
│  Keyboard shortcut: Cmd/Ctrl+N           │
│                                          │
└──────────────────────────────────────────┘
```

### No Messages (New Session)

```
┌──────────────────────────────────────────┐
│                                          │
│     Start a conversation                 │
│                                          │
│  Type a message below or try:            │
│  • /init-project                         │
│  • Ask about your codebase               │
│  • Attach files with @                   │
│                                          │
└──────────────────────────────────────────┘
```

### Logs Tab (No Logs Yet)

```
┌──────────────────────────────────────────┐
│  Waiting for server output...            │
└──────────────────────────────────────────┘
```

## Visual Styling

### Color Scheme

**Light Mode:**

- Background: #FFFFFF
- Secondary background: #F5F5F5
- Border: #E0E0E0
- Text: #1A1A1A
- Muted text: #666666
- Accent: #0066FF

**Dark Mode:**

- Background: #1A1A1A
- Secondary background: #2A2A2A
- Border: #3A3A3A
- Text: #E0E0E0
- Muted text: #999999
- Accent: #0080FF

### Typography

- **Main text**: 14px, system font
- **Headers**: 16px, medium weight
- **Labels**: 12px, regular weight
- **Code**: Monospace font (Consolas, Monaco, Courier)
- **Line height**: 1.5

### Spacing

- **Padding**: 8px, 12px, 16px, 24px (consistent scale)
- **Margins**: Same as padding
- **Tab height**: 40px
- **Input height**: 80px (auto-expanding)
- **Message spacing**: 16px between messages

### Icons

- Use consistent icon set (Lucide, Heroicons, or similar)
- Size: 16px for inline, 20px for buttons
- Stroke width: 2px

## Responsive Behavior

### Minimum Window Size

- Width: 800px
- Height: 600px

### Behavior When Small

- Instance tabs: Scroll horizontally
- Session tabs: Scroll horizontally
- Messages: Always visible, scroll vertically
- Input: Fixed at bottom

## Accessibility

- All interactive elements keyboard-navigable
- ARIA labels for screen readers
- Focus indicators visible
- Color contrast WCAG AA compliant
- Tab trap in modals
- Escape key closes overlays

## Animation & Transitions

- Tab switching: Instant (no animation)
- Message appearance: Fade in (100ms)
- Tool expand/collapse: Slide (200ms)
- Dropdown menus: Fade + slide (150ms)
- Loading states: Spinner or skeleton

## Context Menus

### Session Tab Right-Click

- Rename
- Duplicate
- Share
- Export
- Delete
- Close Other Tabs

### Message Right-Click

- Copy message
- Copy code block
- Edit & regenerate
- Delete message
- Quote in reply

## Status Indicators

### Instance Tab

- Green dot: Server running
- Yellow dot: Server starting
- Red dot: Server error
- No dot: Server stopped

### Session Tab

- Blue pulse: Assistant responding
- No indicator: Idle

### Connection Status

- Bottom right corner: "Connected" or "Reconnecting..."