headquarter/openspec/changes/mobile-terminal-ux/tasks.md

1. Mobile Detection and Hooks

• 1.1 Create useMobileViewport hook for detecting mobile viewport (< 768px)
• 1.2 Create useVirtualKeyboard hook using Visual Viewport API with fallback
• 1.3 Create useAutoHide hook for managing auto-hide visibility with tap/swipe detection
• 1.4 Create useSpecialKeys hook for mapping special keys to escape sequences

2. Mobile Terminal Components

• 2.1 Create MobileTerminalHeader component with back button, menu toggle, instance name, close button
• 2.2 Create SpecialKeysStrip component with primary keys (Esc, Tab, Ctrl, Alt, Arrows)
• 2.3 Create SpecialKeysPanel expanded component with Home/End/PgUp/PgDn/Ctrl combos/F-keys
• 2.4 Create MobileTerminalWrapper component that composes header, terminal, and keys strip
• 2.5 Add hidden input element for maintaining virtual keyboard focus

3. Terminal Component Modifications

• 3.1 Update TerminalComponent to accept mobile mode prop and adjust font size
• 3.2 Add dynamic font scaling based on viewport width (16px min, 24px max)
• 3.3 Add localStorage persistence for font size preference
• 3.4 Implement debounced resize handler (250ms) for orientation changes
• 3.5 Add touch-action: none and disable browser zoom on mobile
• 3.6 Add copy/paste buttons to terminal header for mobile

4. AppShell and Page Integration

• 4.1 Update AppShell to detect terminal routes and render minimal header on mobile
• 4.2 Update TerminalPage to use MobileTerminalWrapper when on mobile viewport
• 4.3 Add CSS transitions for header show/hide animations
• 4.4 Ensure desktop terminal experience is unchanged

5. WebSocket and Reconnection

• 5.1 Implement WebSocket reconnection with exponential backoff (max 3 attempts)
• 5.2 Add "Reconnecting..." status indicator in terminal header
• 5.3 Add manual reconnect button on connection failure
• 5.4 Use Visibility API to reconnect when app returns from background

6. Styling

• 6.1 Add mobile terminal CSS variables and layout styles
• 6.2 Style special keys strip with touch-friendly targets (min 44px height)
• 6.3 Style expanded keys panel as bottom sheet
• 6.4 Add dark theme support for mobile terminal chrome
• 6.5 Ensure proper z-index layering (terminal content above keys strip above keyboard)

7. Testing and Verification

• 7.1 Run npm run typecheck and fix errors
• 7.2 Run npm run lint and fix warnings
• 7.3 Run npm run build successfully
• 7.4 Test on actual mobile device (iOS Safari)
• 7.5 Test on actual mobile device (Android Chrome)
• 7.6 Verify desktop terminal is unchanged
• 7.7 Test screen rotation handling
• 7.8 Test virtual keyboard appearance/disappearance
• 7.9 Verify copy/paste functionality