​

VibeTunnel Mobile Terminal UI/UX Redesign Plan

​

Executive Summary

​

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

// 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

.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)

interface UIState {
  showQuickKeys: boolean;
  keyboardHeight: number;
  hiddenInputFocused: boolean;
  showCtrlAlpha: boolean;
  // ... many more
}

​

After (Simple)

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