alex
6c8cfe9157
Implements a resilient, responsive web terminal that survives network blips, provides instant typing feedback, and restores scrollback on reconnect. Backend changes: - Add heartbeat tracking (15s ping interval, 60s idle timeout) - Add message batching (16ms flush window) for efficient I/O - Add termios echo detection and set_echo_state control messages - Add graceful session_ended notification before close - Add ping/pong protocol support Frontend changes: - Rewrite TerminalComponent with status bar, connection indicator, session-ended overlay, reconnect banner, and ResizeObserver - Add useTerminalConnection hook with: - Exponential backoff auto-reconnect (1s → 30s max, 10 attempts) - Heartbeat/ping-pong with latency tracking - Local echo for printable ASCII with server deduplication - Resize debounce (200ms) + throttle (500ms) - Scrollback serialization via xterm-addon-serialize - Ctrl+Shift+R manual reconnect shortcut - Add WebSocket protocol types and encoding utilities - Add xterm-addon-serialize dependency Tests: - 16 backend unit tests (TerminalSession + TerminalManager) - 13 frontend hook tests (connection lifecycle, reconnect, resize, scrollback, callbacks) Quality gates: - Frontend typecheck: clean - Frontend lint: clean - Frontend tests: 48 passed - Backend unit tests: 101 passed - Backend ruff: clean SDD artifacts: openspec/changes/responsive-terminal/
78 lines
3.6 KiB
Markdown
78 lines
3.6 KiB
Markdown
# Proposal: Responsive Web Terminal
|
|
|
|
## Problem Statement
|
|
|
|
The web terminal in Headquarter feels sluggish and fragile compared to a local terminal session. Users experience high input latency (every keystroke round-trips to the server before appearing), lose their session on any network blip, and have no visibility into connection health. This makes the terminal the weakest part of the workspace experience, especially for users on slower or unstable networks.
|
|
|
|
## User Stories
|
|
|
|
### US-1: Network Resilience
|
|
> As a developer working on a laptop with WiFi,
|
|
> I want the terminal to survive brief disconnections (up to ~30 seconds),
|
|
> so that a network hiccup does not kill my running process and scrollback.
|
|
|
|
### US-2: Responsive Typing
|
|
> As a developer typing commands or code in the terminal,
|
|
> I want keystrokes to appear on screen instantly,
|
|
> so that the terminal feels like a local TTY and not a remote typewriter.
|
|
|
|
### US-3: Session Continuity
|
|
> As a developer who accidentally refreshed the page,
|
|
> I want my terminal scrollback and state to be restored on reconnect,
|
|
> so that I do not lose context of what I was doing.
|
|
|
|
### US-4: Connection Health Visibility
|
|
> As a developer on a slow or congested network,
|
|
> I want to see clear feedback about connection quality and reconnection attempts,
|
|
> so that I understand whether lag is from the server, the container, or my network.
|
|
|
|
### US-5: Graceful Container Exit
|
|
> As a developer whose container process has finished,
|
|
> I want to see a clear message explaining what happened and options to reconnect or go back,
|
|
> so that I am not confused by a generic "Connection closed" error.
|
|
|
|
## Success Metrics
|
|
|
|
| Metric | Current | Target |
|
|
|--------|---------|--------|
|
|
| Time-to-reconnect after disconnect | ∞ (must navigate away) | < 5 seconds |
|
|
| Typing latency (median) | ~100-300ms | < 50ms perceived |
|
|
| Scrollback lost on reconnect | 100% | 0% (restored from serialization) |
|
|
| Silent connection stalls detected | 0% | 100% within 10 seconds |
|
|
| User confusion on container exit | High | Low (clear messaging) |
|
|
|
|
## Scope
|
|
|
|
### In Scope
|
|
- WebSocket auto-reconnection with exponential backoff
|
|
- Heartbeat/ping-pong protocol between client and server
|
|
- Local echo for printable characters (with server authoritative sync)
|
|
- Resize debouncing to avoid server spam
|
|
- Scrollback serialization via xterm-addon-serialize on disconnect
|
|
- Scrollback restoration on reconnect
|
|
- Connection quality indicator (latency, status) in terminal chrome
|
|
- Graceful container exit handling with user-friendly messaging
|
|
- Backend message batching for large output bursts
|
|
|
|
### Out of Scope (for this change)
|
|
- Full terminal session recording/playback
|
|
- Multi-user collaborative terminal sessions
|
|
- Terminal session persistence across server restarts
|
|
- Clipboard integration improvements (separate feature)
|
|
- Terminal search/find (separate feature)
|
|
|
|
## Risks & Mitigations
|
|
|
|
| Risk | Likelihood | Impact | Mitigation |
|
|
|------|-----------|--------|------------|
|
|
| Heartbeat increases server load with many terminals | Medium | Medium | Use 15s heartbeat interval; skip during idle periods |
|
|
| Local echo breaks password prompts | Medium | High | Disable local echo when terminal is in "no echo" mode; server sends echo-state control messages |
|
|
| Scrollback serialization is large for long sessions | Low | Medium | Cap serialization at 10,000 lines; compress before send |
|
|
| Reconnect spawns new docker exec = new shell | Certain | Low | Accept as limitation; focus on scrollback continuity and clear messaging |
|
|
| Cross-stack changes introduce regressions | Medium | High | Comprehensive test coverage; fresh review before merge |
|
|
|
|
## Approval
|
|
|
|
- [ ] Approved
|
|
- [ ] Needs revision
|