chore: archive 15 completed OpenSpec changes

Move the following audited-and-implemented changes into openspec/changes/archive/2026-06-12-completed-changes-archive/: - backend-frontend-refactoring - config-profile-git-mounts - config-profile-includes-ui - config-profile-multi-repo-mounts - container-monitoring-notifications - git-mount-url-validation - home-path-expansion - mobile-terminal-ux - mount-specificity-ordering - notification-center - persistent-terminal-sessions - session-list-overhaul - ssh-key-mounting - terminal-fullscreen-unified-header - tool-session-progress-and-updates Also regenerated .pi-map*.md files for openspec/changes so the remaining active changes (multi-session-terminal-ux, reorganize-long-files, working-copies, workspace-first-ui) reflect the new layout.
2026-06-12 14:26:55 +00:00
parent 30549f4863
commit caadd59441
493 changed files with 3563 additions and 3490 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-24
@@ -0,0 +1,24 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux (index)
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux
+
+## role
+Contains archived design documents and planning artifacts for a mobile-friendly web terminal UX enhancement that was completed on 2026-06-12.
+## parent
+index: archive/2026-06-12-completed-changes-archive/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/.pi-map.md
+## children
+- archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs
+  index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.index.md
+  map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.md
+## files
+- .openspec.yaml
+- design.md
+- proposal.md
+- tasks.md
+## links
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,22 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux
+
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/.pi-map.index.md
+
+## role
+Contains archived design documents and planning artifacts for a mobile-friendly web terminal UX enhancement that was completed on 2026-06-12.
+## files
+- .openspec.yaml | Defines an OpenSpec configuration file with schema version and creation date metadata
+- design.md | Design document for making a web-based terminal mobile-friendly by addressing virtual keyboard handling, maximizing screen real estate, and providing special key access without adding new dependencies. | dep: React, xterm.js, browser APIs (Visual Viewport API, Clipboard API, WebSocket)
+- proposal.md | Proposes a mobile-optimized terminal interface with special keys toolbar, dynamic viewport handling, and touch gestures to make terminal sessions usable on mobile devices. | dep: xterm.js, React, visualViewport API
+- tasks.md | Task tracking checklist for implementing a mobile-responsive terminal interface with WebSocket connectivity, touch-friendly controls, and virtual keyboard handling. | dep: React, Visual Viewport API, WebSocket, Visibility API, localStorage, CSS transitions, npm
+## arch
+Documentation-driven specification pattern using OpenSpec schema with phased design-proposal-tasks workflow covering viewport management, touch gesture handling, and zero-dependency progressive enhancement.
+## tags
+terminal, mobile, design, handling, react, .openspec, friendly, virtual
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,108 @@
+## Context
+
+The current terminal implementation (`apps/web/src/components/terminal.tsx`) uses xterm.js with a fixed header and minimal mobile considerations. The terminal page (`apps/web/src/pages/terminal.tsx`) renders inside the standard AppShell layout (`apps/web/src/components/app-shell.tsx`), which consumes significant viewport space on mobile devices.
+
+On mobile devices (viewport < 768px):
+- The virtual keyboard covers 40-50% of the screen
+- xterm.js touch events conflict with browser touch behavior
+- Special keys (Ctrl, Esc, Tab, Arrows) are not available on mobile keyboards
+- The AppShell header and sidebar waste precious screen real estate
+- No mechanism exists to handle virtual keyboard appearance/disappearance
+
+## Goals / Non-Goals
+
+**Goals:**
+- Make terminal sessions practical on mobile devices for occasional use
+- Provide access to special terminal keys without external keyboard
+- Maximize terminal screen real estate on mobile
+- Handle virtual keyboard gracefully
+- Support full terminal functionality (vim, tmux, etc.)
+
+**Non-Goals:**
+- Native mobile app (stays web-based)
+- Command palette / quick commands (future enhancement)
+- Offline terminal access
+- Mobile-first redesign of the entire application (terminal pages only)
+- Gesture-based text selection (use xterm.js native)
+
+## Decisions
+
+### Decision: Collapsible AppShell, Not Hidden
+
+**Choice**: Collapse AppShell to a minimal auto-hiding header instead of completely hiding it.
+
+**Rationale**: Users need a way to navigate back and access the menu. Complete removal would trap users in the terminal page.
+
+**Alternative considered**: Fullscreen mode with swipe-from-edge to reveal nav. Rejected because it's not discoverable and conflicts with browser gestures.
+
+### Decision: Auto-Hide Header and Keys Strip
+
+**Choice**: Both header and special keys strip auto-hide after 3 seconds of inactivity.
+
+**Rationale**: Maximizes terminal space while keeping controls accessible. Tap to toggle visibility is intuitive.
+
+**Alternative considered**: Always-visible fixed bars. Rejected because they permanently reduce terminal height by ~20%.
+
+### Decision: Hidden Input for Keyboard Management
+
+**Choice**: Use a hidden/transparent input element to maintain virtual keyboard focus.
+
+**Rationale**: xterm.js handles keyboard input directly, but mobile browsers need a focused input to show the virtual keyboard. A hidden input bridges this gap without interfering with xterm.js rendering.
+
+**Alternative considered**: Custom on-screen keyboard. Rejected because native virtual keyboards provide better UX (autocorrect, swipe typing, user's preferred keyboard layout).
+
+### Decision: Special Keys as Bottom Strip, Not Floating
+
+**Choice**: Fixed bottom strip that slides up, not floating action buttons.
+
+**Rationale**: Bottom placement is thumb-friendly and doesn't obscure terminal content. Fixed position makes it always accessible.
+
+**Alternative considered**: Floating action button that expands to a menu. Rejected because it requires two taps for every special key.
+
+### Decision: Debounced Resize (250ms)
+
+**Choice**: 250ms debounce for resize events.
+
+**Rationale**: Mobile keyboard animation is slow and produces multiple resize events. 250ms catches the final state without being sluggish.
+
+**Alternative considered**: No debounce (immediate resize). Rejected because it causes excessive xterm.js refits and WebSocket resize messages.
+
+### Decision: No New Dependencies
+
+**Choice**: Implement using existing React, xterm.js, and browser APIs.
+
+**Rationale**: All required functionality (touch events, viewport API, clipboard) is available natively. Adding libraries increases bundle size for a feature used occasionally.
+
+**Alternative considered**: `react-use` hooks, `xterm-addon-webgl`. Rejected to keep bundle size down.
+
+## Risks / Trade-offs
+
+**[Risk] Visual Viewport API unreliability** → **Mitigation**: Implement fallback using `window.innerHeight` comparison and focus-based detection. Accept imperfect behavior on older browsers.
+
+**[Risk] xterm.js touch conflicts** → **Mitigation**: Use `touch-action: none` on terminal container. Let xterm.js handle its own touch events. Disable browser zoom to prevent pinch conflicts.
+
+**[Risk] WebSocket drops on network change/backgrounding** → **Mitigation**: Implement reconnect logic with exponential backoff. Show clear status to user. Document that mobile networks may cause disconnections.
+
+**[Risk] Clipboard API restrictions on mobile Safari** → **Mitigation**: Use both modern Clipboard API and `document.execCommand('copy')` fallback. Show user feedback on failure.
+
+**[Risk] Screen rotation causes layout flicker** → **Mitigation**: Debounced resize. CSS transitions on layout changes. Consider `orientation` lock prompt for landscape preference.
+
+**[Trade-off] Touch targets vs terminal density** → Larger touch targets mean fewer terminal cells visible. Compromise: 16px minimum font size provides readable text while keeping reasonable cell count.
+
+## Migration Plan
+
+No migration needed. This is a purely additive frontend change that doesn't affect data models, APIs, or existing desktop behavior. Desktop terminal experience remains unchanged.
+
+**Deployment:**
+1. Merge changes to dev branch
+2. Verify on actual mobile devices (iOS Safari, Android Chrome)
+3. Monitor for any desktop regressions
+
+**Rollback:** Revert frontend commit. No database or API changes involved.
+
+## Open Questions
+
+1. Should we implement a landscape orientation prompt? ("Rotate for better experience")
+2. Should font size preference sync across devices (via backend user config) or stay local?
+3. What's the maximum number of special keys to show in the primary strip before requiring "More"?
+4. Should the header show connection status, or is the terminal's own status dot sufficient?
@@ -0,0 +1,30 @@
+## Why
+
+Terminal sessions are currently desktop-optimized and become practically unusable on mobile devices due to virtual keyboard conflicts, lack of touch gestures, missing special keys, and poor screen utilization. Users occasionally need to access terminal sessions from mobile devices to check logs, run quick commands, or monitor running processes, but the current experience is frustrating.
+
+## What Changes
+
+- **Mobile terminal page layout**: Fullscreen terminal experience with collapsible AppShell chrome on mobile viewports
+- **Special keys toolbar**: Bottom-accessible strip with Esc, Tab, Ctrl, Alt, Arrow keys, and an expandable "More" panel with Home/End/PgUp/PgDn/Ctrl+C/etc
+- **Dynamic viewport handling**: Resize terminal container based on virtual keyboard presence using `visualViewport` API
+- **Touch gesture support**: Disable browser zoom, intercept touch events for terminal interaction
+- **Auto-hiding chrome**: Header and special keys strip auto-hide after inactivity, tap/swipe to reveal
+- **Orientation handling**: Debounced resize for screen rotation
+- **Font scaling**: Responsive font size based on viewport dimensions
+
+## Capabilities
+
+### New Capabilities
+- `mobile-terminal-ux`: Mobile-optimized terminal interface with special keys, dynamic sizing, and touch-friendly interactions
+
+### Modified Capabilities
+- `tool-terminal`: Add mobile-specific requirements for terminal resize, touch handling, and virtual keyboard awareness
+- `frontend-foundation`: Add mobile layout behavior for terminal pages (collapsible AppShell, fullscreen mode)
+
+## Impact
+
+- Frontend: New components (`MobileTerminalHeader`, `SpecialKeysStrip`, `useMobileViewport` hook), modifications to `terminal.tsx`, `terminal-page.tsx`, `app-shell.tsx`
+- Styles: New mobile terminal CSS, touch-action overrides
+- Dependencies: No new dependencies (uses existing xterm.js, React)
+- Browser support: Requires `visualViewport` API (modern browsers)
+- Breaking: None
@@ -0,0 +1,26 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs (index)
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs
+
+## role
+Contains archived mobile terminal user experience specification documents from a completed project snapshot dated June 12, 2026.
+## parent
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/.pi-map.md
+## children
+- archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation
+  index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation/.pi-map.index.md
+  map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation/.pi-map.md
+- archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux
+  index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux/.pi-map.index.md
+  map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux/.pi-map.md
+- archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal
+  index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal/.pi-map.index.md
+  map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal/.pi-map.md
+## files
+## links
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,18 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs
+
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.index.md
+
+## role
+Contains archived mobile terminal user experience specification documents from a completed project snapshot dated June 12, 2026.
+## files
+## arch
+Document archive storage with date-based versioning and hierarchical categorization (mobile-terminal-ux/specs) for historical reference and audit trail preservation.
+## tags
+-
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation (index)
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation
+
+## role
+Defines frontend foundation specifications for responsive application layouts with desktop/mobile adaptations and mobile terminal-specific minimal headers.
+## parent
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.md
+## children
+-
+## files
+- spec.md
+## links
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation
+
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/frontend-foundation/.pi-map.index.md
+
+## role
+Defines frontend foundation specifications for responsive application layouts with desktop/mobile adaptations and mobile terminal-specific minimal headers.
+## files
+- spec.md | Defines modified requirements for a responsive application layout component with desktop/mobile adaptations and a specialized minimal header for mobile terminal pages.
+## arch
+Requirements-driven specification pattern with responsive design breakpoints, device-specific component variants, and conditional rendering logic for mobile terminal contexts.
+## tags
+mobile, spec, defines, modified, requirements, responsive, application, layout
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,23 @@
+## MODIFIED Requirements
+
+### Requirement: Layout Component
+
+The system SHALL provide a consistent application layout for authenticated screens across desktop and mobile sizes.
+
+#### Scenario: Application shell
+- **GIVEN** the frontend application
+- **THEN** a Layout component SHALL:
+  - Display a header with user info and logout
+  - Display sidebar navigation on desktop
+  - Show main content area
+  - Collapse sidebar into a mobile menu toggle on small viewports
+  - **AND** on mobile terminal pages, provide a minimal collapsible header instead of the full AppShell
+
+#### Scenario: Terminal page mobile layout
+- **GIVEN** a user on a terminal page on a mobile device
+- **WHEN** the page loads
+- **THEN** the full AppShell is replaced with a minimal header
+- **AND** the header contains: back button, menu toggle, instance name, close button
+- **AND** the header auto-hides after 3 seconds of inactivity
+- **AND** tapping the terminal area toggles header visibility
+- **AND** the sidebar navigation is accessible via the menu toggle
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux (index)
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux
+
+## role
+Defines UI/UX specifications for mobile terminal interface ensuring responsive, touch-friendly terminal experience on mobile devices.
+## parent
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.md
+## children
+-
+## files
+- spec.md
+## links
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux
+
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/mobile-terminal-ux/.pi-map.index.md
+
+## role
+Defines UI/UX specifications for mobile terminal interface ensuring responsive, touch-friendly terminal experience on mobile devices.
+## files
+- spec.md | Specifies mobile terminal UI/UX requirements including responsive layout, special keys toolbar, virtual keyboard handling, touch gestures, screen orientation, copy/paste, and font scaling for a web-based terminal application. | dep: WebSocket, xterm.js, Visual Viewport API, localStorage
+## arch
+Specification-driven design with requirements documentation pattern covering layout, input methods, gestures, and accessibility concerns for cross-platform mobile web terminal.
+## tags
+terminal, spec, specifies, mobile, requirements, including, responsive, layout
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,121 @@
+## ADDED Requirements
+
+### Requirement: Mobile Terminal Layout
+
+The system SHALL provide a fullscreen terminal experience on mobile devices.
+
+#### Scenario: Mobile terminal page
+- **WHEN** a user navigates to an instance terminal page on a mobile device (viewport width < 768px)
+- **THEN** the AppShell chrome is collapsed to a minimal header
+- **AND** the terminal occupies the full viewport below the header
+- **AND** the header auto-hides after 3 seconds of inactivity
+- **AND** tapping the terminal area toggles header visibility
+
+#### Scenario: Collapsed AppShell header
+- **WHEN** the terminal is in mobile mode
+- **THEN** the header displays:
+  - A back button
+  - A hamburger menu toggle (reveals navigation)
+  - The instance name
+  - A close button
+- **AND** the sidebar navigation is hidden by default
+
+### Requirement: Special Keys Toolbar
+
+The system SHALL provide access to special terminal keys on mobile devices.
+
+#### Scenario: Special keys strip
+- **WHEN** a user is on a mobile terminal
+- **THEN** a strip of special keys is available at the bottom of the screen
+- **AND** the strip contains: Esc, Tab, Ctrl, Alt, Up, Down, Left, Right
+- **AND** the strip auto-hides after 3 seconds of inactivity
+- **AND** swiping up from the bottom reveals the strip
+- **AND** tapping the terminal area hides the strip
+
+#### Scenario: Expanded special keys panel
+- **WHEN** a user taps the "More" button on the special keys strip
+- **THEN** an expanded panel appears with additional keys:
+  - Home, End, Page Up, Page Down
+  - Ctrl+C, Ctrl+D, Ctrl+Z
+  - F1 through F12
+- **AND** tapping outside the panel closes it
+
+#### Scenario: Sending special keys
+- **WHEN** a user taps a special key
+- **THEN** the corresponding escape sequence is sent via WebSocket
+- **AND** the key press is visually acknowledged (brief highlight)
+
+### Requirement: Virtual Keyboard Handling
+
+The system SHALL handle virtual keyboard appearance on mobile devices.
+
+#### Scenario: Keyboard-aware resizing
+- **WHEN** the virtual keyboard appears on a mobile device
+- **THEN** the terminal container resizes to fit the remaining viewport
+- **AND** the special keys strip remains visible above the virtual keyboard
+
+#### Scenario: Visual viewport detection
+- **WHEN** the browser supports the Visual Viewport API
+- **THEN** the system uses `visualViewport` events to detect keyboard height
+- **AND** falls back to `window.innerHeight` comparison if API is unavailable
+
+#### Scenario: Focus management
+- **WHEN** a user taps on the terminal area
+- **THEN** focus is maintained on a hidden input element to keep the virtual keyboard open
+- **AND** terminal input continues to work normally
+
+### Requirement: Touch Gestures
+
+The system SHALL support touch interactions in the terminal.
+
+#### Scenario: Disable browser zoom
+- **WHEN** a user is on a mobile terminal page
+- **THEN** browser zoom is disabled via `meta viewport` tag with `user-scalable=no`
+- **AND** pinch gestures do not zoom the page
+
+#### Scenario: Terminal scroll
+- **WHEN** a user performs a two-finger swipe in the terminal
+- **THEN** the terminal scrollback buffer scrolls
+- **AND** the browser page does not scroll
+
+#### Scenario: Text selection
+- **WHEN** a user long-presses in the terminal
+- **THEN** xterm.js native selection behavior is used
+- **AND** browser native text selection UI is suppressed
+
+### Requirement: Screen Orientation
+
+The system SHALL handle device orientation changes gracefully.
+
+#### Scenario: Orientation change
+- **WHEN** a user rotates their device
+- **THEN** the terminal recalculates dimensions after a 250ms debounce
+- **AND** the new dimensions are sent to the backend via WebSocket resize message
+
+### Requirement: Copy and Paste
+
+The system SHALL provide copy and paste functionality on mobile devices.
+
+#### Scenario: Copy button
+- **WHEN** a user selects text in the terminal
+- **THEN** a "Copy" button appears in the header
+- **AND** tapping it copies the selection to clipboard
+
+#### Scenario: Paste button
+- **WHEN** a user taps a "Paste" button in the header or special keys panel
+- **THEN** the system attempts to read from the clipboard
+- **AND** pastes the content into the terminal
+
+### Requirement: Font Scaling
+
+The system SHALL provide readable font sizes on mobile devices.
+
+#### Scenario: Mobile font size
+- **WHEN** the terminal is displayed on a mobile device
+- **THEN** the font size is at least 16px
+- **AND** the font size scales proportionally with viewport width (min 16px, max 24px)
+
+#### Scenario: Font size preference
+- **WHEN** a user changes the font size
+- **THEN** the preference is persisted in localStorage
+- **AND** applied on subsequent terminal sessions
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal (index)
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal
+
+## role
+Defines functional and UX requirements for a mobile-optimized terminal interface with touch-native interactions and adaptive responsive design.
+## parent
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/.pi-map.md
+## children
+-
+## files
+- spec.md
+## links
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal/.pi-map.index.md
+map: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal/.pi-map.md
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,19 @@
+# archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal
+dir: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal
+
+index: archive/2026-06-12-completed-changes-archive/mobile-terminal-ux/specs/tool-terminal/.pi-map.index.md
+
+## role
+Defines functional and UX requirements for a mobile-optimized terminal interface with touch-native interactions and adaptive responsive design.
+## files
+- spec.md | Specifies requirements for a mobile-responsive WebSocket terminal application with touch gestures, special keys, and adaptive layout | dep: xterm.js, WebSocket, browser clipboard API, localStorage, viewport meta tag
+## arch
+Specification-driven requirements document using structured markdown with sections for features, gestures, layout modes, and special key handling; no implementation code present.
+## tags
+websocket, spec, specifies, requirements, mobile, responsive, terminal, application
+## symbols
+-
+## workflows
+-
+## dirty
+-
@@ -0,0 +1,123 @@
+## MODIFIED Requirements
+
+### Requirement: Terminal Resize
+
+The system SHALL support terminal resize events.
+
+#### Scenario: Resize terminal
+- **GIVEN** an active terminal session
+- **WHEN** the browser window is resized
+- **THEN** the terminal dimensions (COLS, ROWS) are updated
+- **AND** the shell receives the new size
+- **AND** on mobile devices, the resize is debounced by 250ms
+
+#### Scenario: Mobile keyboard resize
+- **GIVEN** an active terminal session on a mobile device
+- **WHEN** the virtual keyboard appears or disappears
+- **THEN** the terminal container height adjusts to fit the visible viewport
+- **AND** the terminal is refitted with new dimensions
+
+### Requirement: WebSocket Terminal
+
+The system SHALL provide terminal sessions via WebSocket.
+
+#### Scenario: Mobile reconnection
+- **GIVEN** a terminal session on a mobile device
+- **WHEN** the WebSocket disconnects due to network change or backgrounding
+- **THEN** the terminal shows a "Reconnecting..." status
+- **AND** attempts to reconnect automatically
+- **AND** if reconnection fails after 3 attempts, shows an error with a manual reconnect option
+
+## ADDED Requirements
+
+### Requirement: Mobile Terminal Layout
+
+The system SHALL provide a fullscreen terminal experience on mobile devices.
+
+#### Scenario: Mobile terminal page
+- **WHEN** a user navigates to an instance terminal page on a mobile device (viewport width < 768px)
+- **THEN** the AppShell chrome is collapsed to a minimal header
+- **AND** the terminal occupies the full viewport below the header
+- **AND** the header auto-hides after 3 seconds of inactivity
+- **AND** tapping the terminal area toggles header visibility
+
+#### Scenario: Collapsed AppShell header
+- **WHEN** the terminal is in mobile mode
+- **THEN** the header displays:
+  - A back button
+  - A hamburger menu toggle (reveals navigation)
+  - The instance name
+  - A close button
+- **AND** the sidebar navigation is hidden by default
+
+### Requirement: Special Keys Toolbar
+
+The system SHALL provide access to special terminal keys on mobile devices.
+
+#### Scenario: Special keys strip
+- **WHEN** a user is on a mobile terminal
+- **THEN** a strip of special keys is available at the bottom of the screen
+- **AND** the strip contains: Esc, Tab, Ctrl, Alt, Up, Down, Left, Right
+- **AND** the strip auto-hides after 3 seconds of inactivity
+- **AND** swiping up from the bottom reveals the strip
+- **AND** tapping the terminal area hides the strip
+
+#### Scenario: Expanded special keys panel
+- **WHEN** a user taps the "More" button on the special keys strip
+- **THEN** an expanded panel appears with additional keys:
+  - Home, End, Page Up, Page Down
+  - Ctrl+C, Ctrl+D, Ctrl+Z
+  - F1 through F12
+- **AND** tapping outside the panel closes it
+
+#### Scenario: Sending special keys
+- **WHEN** a user taps a special key
+- **THEN** the corresponding escape sequence is sent via WebSocket
+- **AND** the key press is visually acknowledged (brief highlight)
+
+### Requirement: Touch Gestures
+
+The system SHALL support touch interactions in the terminal.
+
+#### Scenario: Disable browser zoom
+- **WHEN** a user is on a mobile terminal page
+- **THEN** browser zoom is disabled via `meta viewport` tag with `user-scalable=no`
+- **AND** pinch gestures do not zoom the page
+
+#### Scenario: Terminal scroll
+- **WHEN** a user performs a two-finger swipe in the terminal
+- **THEN** the terminal scrollback buffer scrolls
+- **AND** the browser page does not scroll
+
+#### Scenario: Text selection
+- **WHEN** a user long-presses in the terminal
+- **THEN** xterm.js native selection behavior is used
+- **AND** browser native text selection UI is suppressed
+
+### Requirement: Copy and Paste
+
+The system SHALL provide copy and paste functionality on mobile devices.
+
+#### Scenario: Copy button
+- **WHEN** a user selects text in the terminal
+- **THEN** a "Copy" button appears in the header
+- **AND** tapping it copies the selection to clipboard
+
+#### Scenario: Paste button
+- **WHEN** a user taps a "Paste" button in the header or special keys panel
+- **THEN** the system attempts to read from the clipboard
+- **AND** pastes the content into the terminal
+
+### Requirement: Font Scaling
+
+The system SHALL provide readable font sizes on mobile devices.
+
+#### Scenario: Mobile font size
+- **WHEN** the terminal is displayed on a mobile device
+- **THEN** the font size is at least 16px
+- **AND** the font size scales proportionally with viewport width (min 16px, max 24px)
+
+#### Scenario: Font size preference
+- **WHEN** a user changes the font size
+- **THEN** the preference is persisted in localStorage
+- **AND** applied on subsequent terminal sessions
@@ -0,0 +1,57 @@
+## 1. Mobile Detection and Hooks
+
+- [x] 1.1 Create `useMobileViewport` hook for detecting mobile viewport (< 768px)
+- [x] 1.2 Create `useVirtualKeyboard` hook using Visual Viewport API with fallback
+- [x] 1.3 Create `useAutoHide` hook for managing auto-hide visibility with tap/swipe detection
+- [x] 1.4 Create `useSpecialKeys` hook for mapping special keys to escape sequences
+
+## 2. Mobile Terminal Components
+
+- [x] 2.1 Create `MobileTerminalHeader` component with back button, menu toggle, instance name, close button
+- [x] 2.2 Create `SpecialKeysStrip` component with primary keys (Esc, Tab, Ctrl, Alt, Arrows)
+- [x] 2.3 Create `SpecialKeysPanel` expanded component with Home/End/PgUp/PgDn/Ctrl combos/F-keys
+- [x] 2.4 Create `MobileTerminalWrapper` component that composes header, terminal, and keys strip
+- [x] 2.5 Add hidden input element for maintaining virtual keyboard focus
+
+## 3. Terminal Component Modifications
+
+- [x] 3.1 Update `TerminalComponent` to accept mobile mode prop and adjust font size
+- [x] 3.2 Add dynamic font scaling based on viewport width (16px min, 24px max)
+- [x] 3.3 Add localStorage persistence for font size preference
+- [x] 3.4 Implement debounced resize handler (250ms) for orientation changes
+- [x] 3.5 Add touch-action: none and disable browser zoom on mobile
+- [x] 3.6 Add copy/paste buttons to terminal header for mobile
+
+## 4. AppShell and Page Integration
+
+- [x] 4.1 Update `AppShell` to detect terminal routes and render minimal header on mobile
+- [x] 4.2 Update `TerminalPage` to use `MobileTerminalWrapper` when on mobile viewport
+- [x] 4.3 Add CSS transitions for header show/hide animations
+- [x] 4.4 Ensure desktop terminal experience is unchanged
+
+## 5. WebSocket and Reconnection
+
+- [x] 5.1 Implement WebSocket reconnection with exponential backoff (max 3 attempts)
+- [x] 5.2 Add "Reconnecting..." status indicator in terminal header
+- [x] 5.3 Add manual reconnect button on connection failure
+- [x] 5.4 Use Visibility API to reconnect when app returns from background
+
+## 6. Styling
+
+- [x] 6.1 Add mobile terminal CSS variables and layout styles
+- [x] 6.2 Style special keys strip with touch-friendly targets (min 44px height)
+- [x] 6.3 Style expanded keys panel as bottom sheet
+- [x] 6.4 Add dark theme support for mobile terminal chrome
+- [x] 6.5 Ensure proper z-index layering (terminal content above keys strip above keyboard)
+
+## 7. Testing and Verification
+
+- [x] 7.1 Run `npm run typecheck` and fix errors
+- [x] 7.2 Run `npm run lint` and fix warnings
+- [x] 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)
+- [x] 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