> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetunnel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan

# VibeTunnel Mobile Terminal UI/UX Redesign Plan

## Executive Summary

The current VibeTunnel mobile terminal experience suffers from viewport overlap issues, complex keyboard handling, and poor space utilization. This plan outlines a comprehensive redesign to create a mobile-first terminal experience that is intuitive, efficient, and respects device constraints.

### Key Goals

* Eliminate all viewport overlaps on mobile devices
* Simplify keyboard input to a single, coherent system
* Ensure navigation remains accessible at all times
* Optimize screen real estate for terminal content
* Provide seamless transition between keyboard and non-keyboard states

## Current Architecture Analysis

### Component Hierarchy

```
SessionView (Grid Container)
├── SessionHeader (Navigation/Controls)
├── Terminal Area
│   ├── TerminalRenderer
│   └── VibeTunnel Terminal (xterm.js)
└── QuickKeys Area (Conditional)
```

### Mobile Input Systems

1. **Direct Keyboard Mode** (Default)
   * Hidden input element for focus
   * Quick keys toolbar above keyboard
   * Complex focus retention logic

2. **Mobile Input Mode** (Legacy)
   * Full-screen textarea overlay
   * Manual toggle button
   * Less efficient screen usage

### State Management

* `UIStateManager` handles multiple overlapping states
* Complex boolean flags: `showQuickKeys`, `showCtrlAlpha`, `showFileBrowser`
* Race conditions between keyboard animations and state updates

## Identified Problems

### 1. Viewport Overlap Issues

* Fixed positioning elements don't respect safe areas consistently
* Terminal transform (`translateY(-110px)`) causes content to move off-screen
* Header can be obscured when keyboard is active
* Z-index layering conflicts between overlays

### 2. Complex Keyboard Handling

* Two separate keyboard systems confuse users
* Focus management requires intervals and timeouts
* Keyboard height calculations are inconsistent
* Quick keys toolbar adds unnecessary complexity

### 3. Poor Space Utilization

* Multiple toolbars and overlays reduce terminal visibility
* Redundant UI elements (custom keyboard + native keyboard)
* Inefficient use of limited mobile screen space

### 4. Navigation Accessibility

* Header can become inaccessible when keyboard is active
* No clear way to dismiss keyboard in some states
* Sidebar toggle conflicts with keyboard overlays

## Design Principles

### 1. Mobile-First Approach

* Design for smallest screens first
* Progressive enhancement for larger devices
* Touch-optimized interactions

### 2. Native Platform Integration

* Leverage native keyboard capabilities
* Respect platform conventions (iOS/Android)
* Use system UI where possible

### 3. Simplified State Management

* Single source of truth for keyboard state
* Clear, predictable transitions
* No overlapping or conflicting states

### 4. Maximum Content Visibility

* Terminal content is primary focus
* Minimal chrome and overlays
* Smart hiding of non-essential UI

## Proposed Solutions

### 1. New Layout System

#### Portrait Mode Layout

```
┌─────────────────────────┐
│     Compact Header      │ <- Always visible, 44px
├─────────────────────────┤
│                         │
│                         │
│    Terminal Content     │ <- Flexible height
│                         │
│                         │
├─────────────────────────┤
│    Action Bar (48px)    │ <- Context-sensitive
└─────────────────────────┘

With Keyboard:
┌─────────────────────────┐
│     Compact Header      │
├─────────────────────────┤
│    Terminal Content     │ <- Scrollable
├─────────────────────────┤
│    Action Bar           │
├─────────────────────────┤
│   Native Keyboard       │
└─────────────────────────┘
```

#### Landscape Mode Layout

```
┌─────────────────────────────────────┐
│  Header  │    Terminal Content       │
│          │                           │
│ Sidebar  │                           │
│  Toggle  │                           │
└─────────┴───────────────────────────┘
```

### 2. Simplified Keyboard System

#### Single Input Method

* Use native keyboard exclusively
* Remove custom keyboard overlay
* Integrate special keys into action bar

#### Smart Action Bar

```
┌─────────────────────────────────┐
│ [Esc] [Tab] [↑][↓][←][→] [Ctrl] │ <- Scrollable
└─────────────────────────────────┘
```

* Only shows when keyboard is active
* Horizontally scrollable for more keys
* Sticky positioned above keyboard

### 3. Responsive Header

#### Compact Mobile Header

* Reduce height to 44px (iOS standard)
* Show only essential info: session name + menu
* Move detailed info to collapsible drawer

#### Header States

1. **Default**: Full info display
2. **Keyboard Active**: Minimal mode with just title
3. **Scrolling**: Auto-hide with scroll, show on scroll up

### 4. Improved Focus Management

#### Native Focus Handling

```typescript theme={null}
// Simplified focus management
class MobileTerminalInput {
  private input: HTMLInputElement;
  
  focus() {
    // Direct focus, no timeouts
    this.input.focus();
    this.input.click(); // Trigger keyboard on iOS
  }
  
  blur() {
    this.input.blur();
    // Let native behavior handle keyboard dismissal
  }
}
```

### 5. Viewport Management

#### CSS-Only Solution

```css theme={null}
.mobile-terminal-container {
  height: 100vh;
  height: 100dvh; /* Dynamic viewport height */
  display: flex;
  flex-direction: column;
}

.terminal-header {
  flex-shrink: 0;
  position: sticky;
  top: 0;
  z-index: 10;
}

.terminal-content {
  flex: 1;
  overflow-y: auto;
  -webkit-overflow-scrolling: touch;
}

.action-bar {
  flex-shrink: 0;
  position: sticky;
  bottom: 0;
}

/* No transforms, just natural flow */
```

## Implementation Phases

### Phase 1: Foundation (Week 1)

1. Create new mobile layout components
2. Implement CSS-only viewport solution
3. Remove terminal transform logic
4. Ensure header always visible

### Phase 2: Keyboard Simplification (Week 2)

1. Remove custom keyboard overlay
2. Implement native-only input
3. Create smart action bar
4. Simplify focus management

### Phase 3: Header Optimization (Week 3)

1. Design compact mobile header
2. Implement collapsible info drawer
3. Add scroll-based auto-hide
4. Test on various devices

### Phase 4: Polish & Testing (Week 4)

1. Fine-tune animations
2. Optimize performance
3. Cross-device testing
4. User feedback integration

## Technical Requirements

### 1. Component Changes

#### New Components

* `MobileTerminalLayout` - Manages mobile-specific layout
* `SmartActionBar` - Context-sensitive action buttons
* `CompactSessionHeader` - Mobile-optimized header

#### Modified Components

* `SessionView` - Use mobile layout on small screens
* `TerminalRenderer` - Remove transform logic
* `UIStateManager` - Simplify state management

### 2. CSS Architecture

#### Remove

* Terminal transforms
* Complex height calculations
* Fixed positioning for overlays

#### Add

* Flexbox/Grid mobile layouts
* Sticky positioning for header/action bar
* CSS containment for performance

### 3. State Simplification

#### Before (Complex)

```typescript theme={null}
interface UIState {
  showQuickKeys: boolean;
  keyboardHeight: number;
  hiddenInputFocused: boolean;
  showCtrlAlpha: boolean;
  // ... many more
}
```

#### After (Simple)

```typescript theme={null}
interface MobileUIState {
  keyboardVisible: boolean;
  actionBarExpanded: boolean;
  headerCompact: boolean;
}
```

## Testing Strategy

### 1. Device Testing Matrix

* iPhone 13/14/15 (Standard)
* iPhone 13/14 Pro Max (Large)
* iPhone SE (Small)
* iPad (Tablet)
* Android devices (Various)

### 2. Scenario Testing

* [ ] Keyboard appears without overlap
* [ ] Header remains accessible
* [ ] Terminal content scrolls properly
* [ ] Action bar functions correctly
* [ ] Landscape/portrait transitions smooth
* [ ] Safe areas respected on all devices

### 3. Performance Metrics

* Layout shift score \< 0.1
* No janky animations (60fps)
* Keyboard appear/dismiss \< 300ms
* Memory usage stable

## Risk Mitigation

### 1. Browser Compatibility

* **Risk**: Visual Viewport API not supported
* **Mitigation**: Fallback to resize events

### 2. iOS Keyboard Quirks

* **Risk**: Keyboard doesn't appear on focus
* **Mitigation**: Use click event as backup

### 3. Performance Issues

* **Risk**: Scroll performance degrades
* **Mitigation**: Use CSS containment, minimize reflows

### 4. User Adoption

* **Risk**: Users confused by changes
* **Mitigation**: Gradual rollout, feature flags

## Success Metrics

1. **Zero viewport overlaps** on all tested devices
2. **50% reduction** in keyboard-related bug reports
3. **Improved usability scores** in user testing
4. **Faster keyboard interactions** (\< 300ms response)
5. **Increased mobile session duration** by 25%

## Conclusion

This redesign prioritizes simplicity, native platform integration, and maximum content visibility. By removing complexity and focusing on core functionality, we can deliver a superior mobile terminal experience that just works.