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

# Ios spec

# VibeTunnel iOS/iPadOS Native App Specification

## Overview

VibeTunnel iOS is a native SwiftUI application that provides a beautiful, native interface to the VibeTunnel terminal multiplexer backend. The app allows users to create, manage, and interact with terminal sessions on their Mac from their iOS/iPadOS devices.

## Target Platform

* **iOS/iPadOS**: 18.0+
* **Universal App**: Single app that adapts to iPhone and iPad
* **SwiftUI**: Modern declarative UI framework
* **Terminal Engine**: ghostty-web (WASM + canvas)

## Core Features

### 1. Connection Management

* **Initial Setup Dialog**:
  * Server URL/IP input field
  * Port configuration (default: 3000)
  * Connection testing with status feedback
  * Saved connections list (stored in UserDefaults/KeyChain)
  * Auto-reconnection on app launch

### 2. Session Management

* **Session List View**:
  * Display all active and exited sessions
  * Real-time status updates (auto-refresh every 3 seconds)
  * Session cards showing:
    * Session name/command
    * Working directory
    * Status (running/exited)
    * PID (if running)
    * Exit code (if exited)
    * Started time
    * Last modified time
  * Pull-to-refresh functionality
  * Search/filter capabilities

* **Session Actions**:
  * Create new session
  * Kill running session
  * Clean up exited session files
  * Clean up all exited sessions
  * Tap to view terminal

### 3. Terminal View

* **ghostty-web Integration**:
  * Full terminal emulation using ghostty-web
  * Support for ANSI escape sequences
  * 256-color and true color support
  * VS Code dark theme colors
  * Font: SF Mono or custom monospace fonts
  * Adjustable font size

* **Input/Output**:
  * Native iOS keyboard integration
  * Special keys toolbar (arrows, escape, tab, ctrl)
  * Optional OpenAI BYOK voice transcription that inserts text without executing it
  * Copy/paste support
  * URL detection and tap-to-open
  * Smooth scrolling with momentum
  * Pinch-to-zoom font sizing

* **Real-time Updates**:
  * WebSocket buffer streaming for terminal output
  * Efficient buffer management
  * Auto-scroll to bottom on new output
  * Scroll position indicator

### 4. Session Creation

* **New Session Form**:
  * Command input (default: zsh)
  * Working directory picker
  * Session name (optional)
  * Terminal dimensions (auto-calculated based on device)
  * Recent commands/directories

### 5. iPad-Specific Features

* **Split View Support**:
  * Session list in sidebar
  * Terminal in main view
  * Multiple terminal tabs
  * Drag and drop support

* **Keyboard Support**:
  * Hardware keyboard shortcuts
  * Command+T for new session
  * Command+W to close session
  * Command+K to clear terminal

* **Multitasking**:
  * Slide Over support
  * Split View with other apps
  * Stage Manager compatibility

## Technical Architecture

### 1. Project Structure

```
ios/
├── VibeTunnel/
│   ├── App/
│   │   ├── VibeTunnelApp.swift
│   │   └── ContentView.swift
│   ├── Models/
│   │   ├── Session.swift
│   │   ├── ServerConfig.swift
│   │   └── TerminalData.swift
│   ├── Views/
│   │   ├── Connection/
│   │   │   ├── ConnectionView.swift
│   │   │   └── ServerConfigForm.swift
│   │   ├── Sessions/
│   │   │   ├── SessionListView.swift
│   │   │   ├── SessionCardView.swift
│   │   │   └── SessionCreateView.swift
│   │   ├── Terminal/
│   │   │   ├── TerminalView.swift
│   │   │   ├── GhosttyWebView.swift
│   │   │   ├── TerminalBufferRenderer.swift
│   │   │   └── TerminalToolbar.swift
│   │   └── Common/
│   │       ├── LoadingView.swift
│   │       └── ErrorView.swift
│   ├── Services/
│   │   ├── APIClient.swift
│   │   ├── SessionService.swift
│   │   ├── TerminalService.swift
│   │   └── BufferWebSocketClient.swift
│   ├── Utils/
│   │   ├── KeychainHelper.swift
│   │   ├── ColorTheme.swift
│   │   └── Extensions/
│   └── Resources/
│       ├── Assets.xcassets
│       └── Info.plist
└── VibeTunnel.xcodeproj
```

### 2. Data Models

```swift theme={null}
// Session Model
struct Session: Codable, Identifiable {
    let id: String
    let command: String
    let workingDir: String
    let name: String?
    let status: SessionStatus
    let exitCode: Int?
    let startedAt: Date
    let lastModified: Date
    let pid: Int?
    let waiting: Bool?
    let width: Int?
    let height: Int?
}

enum SessionStatus: String, Codable {
    case running
    case exited
}

// Server Configuration
struct ServerConfig: Codable {
    let host: String
    let port: Int
    let name: String?
    
    var baseURL: URL {
        URL(string: "http://\(host):\(port)")!
    }
}

// Terminal Event
struct TerminalEvent {
    let timestamp: Double
    let type: EventType
    let data: String
    
    enum EventType: String {
        case output = "o"
        case input = "i"
        case resize = "r"
        case marker = "m"
    }
}
```

### 3. API Integration

```swift theme={null}
// API Client Protocol
protocol APIClientProtocol {
    func getSessions() async throws -> [Session]
    func createSession(_ data: SessionCreateData) async throws -> String
    func killSession(_ sessionId: String) async throws
    func cleanupSession(_ sessionId: String) async throws
    func cleanupAllExitedSessions() async throws -> [String]
    func sendInput(sessionId: String, text: String) async throws
    func resizeTerminal(sessionId: String, cols: Int, rows: Int) async throws
}

// Buffer WebSocket client for terminal streaming
class BufferWebSocketClient: NSObject {
    func connect()
    func subscribe(to sessionId: String, handler: @escaping (TerminalWebSocketEvent) -> Void)
    func disconnect()
}
```

### 4. ghostty-web Integration

```swift theme={null}
// Terminal View Controller
class TerminalViewController: UIViewController {
    private let terminal: GhosttyWebView
    private let sessionId: String
    private let bufferClient: BufferWebSocketClient
    
    // Configure terminal with VS Code theme
    // Handle input/output
    // Manage resize events
    // Stream terminal data via WebSocket buffer updates
}
```

### 5. State Management

* Use SwiftUI's `@StateObject` and `@ObservedObject` for view models
* Combine framework for reactive updates
* AsyncStream/Task for WebSocket handling
* UserDefaults for connection preferences
* Keychain for secure credential storage

## UI/UX Design

### 1. Design System

* **Colors**: Match VS Code dark theme
  * Background: #1e1e1e
  * Foreground: #d4d4d4
  * Accent: System blue
  * Success: System green
  * Error: System red

* **Typography**:
  * System fonts for UI
  * SF Mono for terminal
  * Dynamic Type support

* **Components**:
  * Native SwiftUI components
  * Consistent padding and spacing
  * Smooth animations and transitions

### 2. Navigation Flow

```
ConnectionView (if not connected)
    ↓
SessionListView (main screen)
    ├→ SessionCreateView (modal)
    └→ TerminalView (push/detail)
         └→ TerminalToolbar (overlay)
```

### 3. Responsive Design

* Adaptive layouts for different device sizes
* Compact/Regular size class handling
* Landscape optimization
* Dynamic terminal sizing

## Implementation Phases

### Phase 1: Foundation (Tasks 2-4)

* Set up Xcode project with SwiftUI
* Create basic navigation structure
* Implement connection dialog
* Build data models and API client
* Store server configuration

### Phase 2: Session Management (Task 5, 8)

* Session list view with real-time updates
* Session card components
* Create new session form
* Kill and cleanup actions
* Pull-to-refresh

### Phase 3: Terminal Integration (Tasks 6-7, 9)

* Integrate ghostty-web resources
* Terminal view wrapper
* WebSocket buffer streaming client
* Input handling
* Resize support

### Phase 4: Polish & iPad (Task 10)

* iPad-specific layouts
* Keyboard shortcuts
* Settings view
* Connection management
* Performance optimization

## Testing Strategy

### Unit Tests

* API client methods
* Data model parsing
* Session state management
* URL construction

### UI Tests

* Connection flow
* Session creation
* Terminal interaction
* Error handling

### Integration Tests

* End-to-end session lifecycle
* WebSocket streaming reliability
* Terminal command execution

## Security Considerations

* Use HTTPS when possible (with option for HTTP in local network)
* Store credentials in Keychain
* Validate server certificates
* Sanitize terminal output
* Handle authentication if backend requires it

## Performance Optimization

* Lazy loading of session list
* Efficient terminal buffer management
* Debounced resize events
* Background session updates
* Memory-efficient buffer streaming

## Future Enhancements

1. **Multiple Connections**: Support multiple VibeTunnel servers
2. **Session Sharing**: Share terminal sessions with others
3. **Recording**: Record and playback terminal sessions
4. **Themes**: Additional color themes beyond VS Code
5. **Shortcuts**: Customizable keyboard shortcuts
6. **File Transfer**: Upload/download files through the app
7. **Notifications**: Background notifications for session events

## Dependencies

* **ghostty-web**: Terminal emulator engine
* **Alamofire** (optional): For networking (or use URLSession)
* **KeychainSwift**: Secure credential storage

## App Store Considerations

* Ensure compliance with App Store guidelines
* Proper error handling and user feedback
* Privacy policy for network usage
* Export compliance for encryption

## Conclusion

This specification outlines a comprehensive native iOS/iPadOS client for VibeTunnel that leverages SwiftUI and ghostty-web to provide a superior terminal experience compared to the web interface. The app will be fast, responsive, and take full advantage of native iOS features while maintaining feature parity with the web frontend.