lit-shell.js 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2025-02-01
+
+### Changed
+
+- Comprehensive README update with full documentation
+- Added Tabbed Terminals section with Tab API and use cases
+- Added Built-in Connection Panel section
+- Added Session Multiplexing diagram
+- Added Docker Compose quick start instructions
+- Added Examples section with local development guide
+- Added Client-Side CDN loading instructions
+
+## [1.2.0] - 2025-02-01
+
+### Added
+
+- **Mobile Support**: Auto-detect mobile devices and show touch keyboard
+  - Termux-style layout: ESC, arrows, HOME/END, PGUP/PGDN, TAB
+  - Sticky CTRL and ALT modifiers
+  - Collapsible extra row with common control sequences (^C, ^D, ^Z, ^L, ^A, ^E, ^R)
+  - Hide/show toggle for entire keyboard
+  - Responsive viewport detection with media query listener
+- **Reconnect Dialog**: After WebSocket reconnection, shows dialog to rejoin previous session
+  - Saves session ID on disconnect
+  - Checks if session still exists after reconnect
+  - Option to rejoin with history or start fresh
+- **Session Persistence Options**: Connection panel now includes
+  - Configurable orphan timeout (1 min to 1 week)
+  - Tmux integration checkbox for permanent persistence
+- **Updated Font Stack**: Terminal now uses Cascadia Mono as primary font for better cross-platform consistency
+
+### Changed
+
+- Improved README documentation with all new features
+- Updated feature list to include Docker, multiplexing, mobile, and persistence
+
 ## [1.1.0] - 2025-01-09
 
 ### Added

package/README.md

@@ -9,17 +9,65 @@ A plug-and-play terminal solution for web applications. Includes a server compon
 - **Server**: WebSocket server with node-pty for real shell sessions
 - **Client**: Lightweight WebSocket client with auto-reconnection
 - **UI**: `<lit-shell-terminal>` Lit web component with xterm.js
+- **Tabbed Terminals**: Multiple terminal tabs in a single component
+- **Docker Exec**: Connect to Docker containers via `docker exec`
+- **Docker Attach**: Connect to a container's main process (PID 1)
+- **Session Multiplexing**: Multiple clients can share the same terminal session
+- **Session Persistence**: Sessions survive client disconnects with configurable timeout
+- **History Replay**: New clients receive recent terminal output when joining
+- **Mobile Support**: Touch keyboard with Termux-style layout for mobile devices
 - **Themes**: Built-in dark/light/auto theme support
-- **Security**: Configurable shell and path allowlists
+- **Security**: Configurable shell, path, and container allowlists
 - **Framework Agnostic**: Works with React, Vue, Angular, Svelte, or vanilla JS
 
 ## Installation
 
 ```bash
-npm install lit-shell.js node-pty
+npm install lit-shell.js
 ```
 
-Note: `node-pty` requires native compilation. See [node-pty docs](https://github.com/microsoft/node-pty) for platform-specific requirements.
+### Server-Side Requirements (node-pty)
+
+The server component requires `node-pty` for spawning terminal processes. Install it as a dev dependency:
+
+```bash
+npm install node-pty --save-dev
+```
+
+**Important:** `node-pty` requires native compilation. If you encounter installation issues:
+
+```bash
+# Linux - install build essentials
+sudo apt-get install build-essential python3
+
+# macOS - install Xcode command line tools
+xcode-select --install
+
+# If npm install fails, try:
+npm install node-pty --save-dev --legacy-peer-deps
+
+# Or rebuild native modules:
+npm rebuild node-pty
+```
+
+See [node-pty docs](https://github.com/microsoft/node-pty) for platform-specific requirements.
+
+### Client-Side (Browser)
+
+The UI component can be loaded directly from a CDN - no build step required:
+
+```html
+<!-- Using unpkg -->
+<script type="module" src="https://unpkg.com/lit-shell.js/dist/ui/browser-bundle.js"></script>
+
+<!-- Or using jsDelivr -->
+<script type="module" src="https://cdn.jsdelivr.net/npm/lit-shell.js/dist/ui/browser-bundle.js"></script>
+
+<!-- Pin to a specific version -->
+<script type="module" src="https://unpkg.com/lit-shell.js@1.2.0/dist/ui/browser-bundle.js"></script>
+```
+
+The bundle includes the `<lit-shell-terminal>` web component with xterm.js built-in.
 
 ## Quick Start
 
@@ -51,9 +99,6 @@ server.listen(3000, () => {
 ### Client Usage (Web Component)
 
 ```html
-<!-- Load xterm.js CSS -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/xterm@5.3.0/css/xterm.css">
-
 <!-- Load lit-shell.js UI bundle -->
 <script type="module" src="https://unpkg.com/lit-shell.js/dist/ui/browser-bundle.js"></script>
 
@@ -94,6 +139,94 @@ client.write('ls -la\n');
 client.resize(120, 40);
 ```
 
+## Tabbed Terminals
+
+Enable multiple terminal tabs within a single component using the `show-tabs` attribute:
+
+```html
+<lit-shell-terminal
+  url="ws://localhost:3000/terminal"
+  show-tabs
+  show-connection-panel
+  show-settings
+  show-status-bar
+></lit-shell-terminal>
+```
+
+### Features
+
+- **Independent Sessions**: Each tab has its own WebSocket connection and terminal session
+- **Tab Bar**: Shows all open tabs with status indicators
+- **Dynamic Labels**: Tabs automatically update their label to show the shell or container name
+- **Session Joining**: Create a tab and join an existing session from another tab
+- **Easy Management**: Click "+" to add tabs, "×" to close, click tab to switch
+
+### Tab API
+
+```javascript
+const terminal = document.querySelector('lit-shell-terminal');
+
+// Create a new tab
+const tab = terminal.createTab('My Terminal');
+// Returns: { id: 'tab-1', label: 'My Terminal', ... }
+
+// Switch to a specific tab
+terminal.switchTab('tab-1');
+
+// Close a tab (resources are cleaned up automatically)
+terminal.closeTab('tab-1');
+
+// Access tab state
+// Each tab maintains its own: client, terminal, sessionInfo, etc.
+```
+
+### Use Cases
+
+**1. Multi-Environment Development**
+```html
+<!-- Open tabs for different containers -->
+<lit-shell-terminal show-tabs show-connection-panel></lit-shell-terminal>
+```
+- Tab 1: Local shell for git operations
+- Tab 2: Docker container for backend
+- Tab 3: Docker container for frontend
+
+**2. Session Sharing**
+- Create a session in Tab 1
+- Create Tab 2, select "Join Existing Session"
+- Both tabs now mirror the same terminal
+
+**3. Monitoring Multiple Processes**
+- Open multiple tabs
+- Each tab connects to a different running session
+- Monitor all processes from a single interface
+
+## Built-in Connection Panel
+
+When `show-connection-panel` is enabled, the terminal component provides a built-in UI for:
+
+- **Mode Selection**: Switch between local shell, Docker exec, Docker attach, and join existing session modes
+- **Container Picker**: Dropdown of running containers (when Docker is enabled on server)
+- **Shell Selection**: Choose from server-allowed shells
+- **Session Timeout**: Configure orphan timeout (1 min to 1 week)
+- **Tmux Integration**: Option for permanent session persistence
+- **Connect/Disconnect**: One-click session management
+
+The connection panel automatically queries the server for:
+- Docker availability and allowed containers
+- Allowed shells and default configuration
+- Available sessions for joining
+
+```html
+<!-- Full-featured terminal with all UI panels -->
+<lit-shell-terminal
+  url="ws://localhost:3000/terminal"
+  show-connection-panel
+  show-settings
+  show-status-bar
+></lit-shell-terminal>
+```
+
 ## API Reference
 
 ### Server
@@ -127,6 +260,18 @@ const server = new TerminalServer({
 
   // Enable verbose logging
   verbose: false,
+
+  // Session multiplexing options
+  maxClientsPerSession: 10,     // Max clients per session (default: 10)
+  orphanTimeout: 60000,         // Ms before orphaned sessions close (default: 60000)
+  historySize: 50000,           // History buffer size in chars (default: 50000)
+  historyEnabled: true,         // Enable history replay (default: true)
+  maxSessionsTotal: 100,        // Max concurrent sessions (default: 100)
+
+  // Docker configuration
+  allowDockerExec: false,
+  allowedContainerPatterns: ['.*'],
+  defaultContainerShell: '/bin/sh',
 });
 
 // Attach to HTTP server
@@ -138,6 +283,10 @@ server.listen(3001);
 // Get active sessions
 const sessions = server.getSessions();
 
+// Get session statistics
+const stats = server.getStats();
+// { sessionCount: 5, clientCount: 12, orphanedCount: 1 }
+
 // Close server
 server.close();
 ```
@@ -166,6 +315,11 @@ const sessionInfo = await client.spawn({
   env: { TERM: 'xterm-256color' },
   cols: 80,
   rows: 24,
+  container: 'optional-container-name',
+  orphanTimeout: 3600000,
+  useTmux: false,
+  label: 'my-session',      // Optional label for identification
+  allowJoin: true,          // Allow others to join (default: true)
 });
 
 // Write to terminal
@@ -193,6 +347,26 @@ client.isConnected();      // boolean
 client.hasActiveSession(); // boolean
 client.getSessionId();     // string | null
 client.getSessionInfo();   // SessionInfo | null
+
+// Session multiplexing
+const sessions = await client.listSessions();  // List all sessions
+const session = await client.join({            // Join existing session
+  sessionId: 'term-123...',
+  requestHistory: true,
+  historyLimit: 50000,
+});
+client.leave(sessionId);                       // Leave without killing
+
+// Multiplexing event handlers
+client.onClientJoined((sessionId, count) => console.log(`${count} clients`));
+client.onClientLeft((sessionId, count) => console.log(`${count} clients`));
+client.onSessionClosed((sessionId, reason) => console.log(reason));
+// reason: 'orphan_timeout' | 'owner_closed' | 'process_exit' | 'error'
+
+// Reconnection with session recovery
+client.onReconnectWithSession((sessionId) => {
+  // Previous session is still available after reconnect
+});
 ```
 
 ### UI Component
@@ -206,12 +380,16 @@ client.getSessionInfo();   // SessionInfo | null
   cwd="/home/user"
   theme="dark"
   font-size="14"
-  font-family="Menlo, Monaco, monospace"
+  font-family="Cascadia Mono, Consolas, monospace"
   cols="80"
   rows="24"
   auto-connect
   auto-spawn
   no-header
+  show-connection-panel
+  show-settings
+  show-status-bar
+  show-tabs
 ></lit-shell-terminal>
 ```
 
@@ -222,14 +400,22 @@ client.getSessionInfo();   // SessionInfo | null
 | `url` | string | `''` | WebSocket URL |
 | `shell` | string | `''` | Shell to use |
 | `cwd` | string | `''` | Working directory |
+| `container` | string | `''` | Docker container name |
+| `container-shell` | string | `''` | Shell inside container |
+| `container-user` | string | `''` | User in container |
+| `container-cwd` | string | `''` | Working directory in container |
 | `theme` | `'dark'` \| `'light'` \| `'auto'` | `'dark'` | Color theme |
 | `font-size` | number | `14` | Terminal font size |
-| `font-family` | string | `'Menlo, Monaco, ...'` | Terminal font |
+| `font-family` | string | `'Cascadia Mono, ...'` | Terminal font |
 | `cols` | number | `80` | Initial columns |
 | `rows` | number | `24` | Initial rows |
 | `auto-connect` | boolean | `false` | Connect on mount |
 | `auto-spawn` | boolean | `false` | Spawn on connect |
 | `no-header` | boolean | `false` | Hide header bar |
+| `show-connection-panel` | boolean | `false` | Show connection panel with container/shell selector |
+| `show-settings` | boolean | `false` | Show settings dropdown (theme, font size) |
+| `show-status-bar` | boolean | `false` | Show status bar with connection info and errors |
+| `show-tabs` | boolean | `false` | Enable tabbed terminal interface |
 
 **Methods:**
 
@@ -244,6 +430,15 @@ terminal.clear();             // Clear display
 terminal.write('text');       // Write to display
 terminal.writeln('line');     // Write line to display
 terminal.focus();             // Focus terminal
+
+// Session multiplexing
+await terminal.join(sessionId);  // Join existing session
+terminal.leave();                // Leave without killing
+
+// Tab methods (when show-tabs is enabled)
+terminal.createTab('label');  // Create new tab
+terminal.switchTab('tab-id'); // Switch to tab
+terminal.closeTab('tab-id');  // Close tab
 ```
 
 **Events:**
@@ -254,8 +449,184 @@ terminal.addEventListener('disconnect', () => {});
 terminal.addEventListener('spawned', (e) => console.log(e.detail.session));
 terminal.addEventListener('exit', (e) => console.log(e.detail.exitCode));
 terminal.addEventListener('error', (e) => console.log(e.detail.error));
+terminal.addEventListener('theme-change', (e) => console.log(e.detail.theme));
+```
+
+## Docker Container Support
+
+lit-shell.js can connect to Docker containers, allowing you to exec into running containers directly from the browser.
+
+### Server Configuration
+
+```javascript
+const server = new TerminalServer({
+  // Enable Docker exec feature
+  allowDockerExec: true,
+
+  // Restrict which containers can be accessed (regex patterns)
+  allowedContainerPatterns: [
+    '^myapp-',           // Containers starting with 'myapp-'
+    '^dev-container$',   // Exact match
+    'backend',           // Contains 'backend'
+  ],
+
+  // Default shell for containers
+  defaultContainerShell: '/bin/bash',
+
+  // Path to Docker CLI (default: 'docker')
+  dockerPath: '/usr/bin/docker',
+
+  verbose: true,
+});
 ```
 
+### Client Usage
+
+```javascript
+// Connect to a Docker container
+await client.spawn({
+  container: 'my-container-name',  // Container ID or name
+  containerShell: '/bin/sh',       // Shell inside container
+  containerUser: 'root',           // User to run as
+  containerCwd: '/app',            // Working directory in container
+  env: { DEBUG: 'true' },          // Environment variables
+});
+```
+
+### Web Component
+
+```html
+<lit-shell-terminal
+  url="ws://localhost:3000/terminal"
+  container="my-container-name"
+  container-shell="/bin/bash"
+  container-user="node"
+  container-cwd="/app"
+  theme="dark"
+  auto-connect
+  auto-spawn
+></lit-shell-terminal>
+```
+
+### Docker Attach Mode
+
+Docker attach connects to a container's main process (PID 1) instead of spawning a new shell. This is useful for:
+- Interacting with interactive containers started with `docker run -it`
+- Debugging container startup issues
+- Sharing a session with `docker attach` from another terminal
+
+```javascript
+// Client: Attach to container's main process
+await client.spawn({
+  container: 'my-container',
+  attachMode: true,  // Use docker attach instead of docker exec
+});
+```
+
+**Important:** Docker attach connects to whatever is running as PID 1. If the container was started with a non-interactive command (like a web server), attach may not provide useful interaction.
+
+## Session Multiplexing
+
+Session multiplexing allows multiple clients to connect to the same terminal session. This enables:
+- **Collaboration**: Multiple users can share a terminal
+- **Session Persistence**: Sessions survive client disconnects
+- **History Replay**: New clients receive recent output when joining
+- **Monitoring**: Watch others' terminal sessions in real-time
+
+### How It Works
+
+```
+┌──────────┐     ┌─────────────────────────────────────────┐     ┌──────────┐
+│ Client A │◄────┤           SessionManager                 ├────►│   PTY    │
+└──────────┘     │  ┌─────────────────────────────────────┐ │     │ Process  │
+                 │  │         SharedSession                │ │     └──────────┘
+┌──────────┐     │  │  - clients: [A, B, C]               │ │
+│ Client B │◄────┼──┤  - historyBuffer (50KB)             │ │
+└──────────┘     │  │  - orphanedAt: null                 │ │
+                 │  └─────────────────────────────────────┘ │
+┌──────────┐     │                                         │
+│ Client C │◄────┼─────────────────────────────────────────┘
+└──────────┘              (broadcast output)
+```
+
+### Client API
+
+```javascript
+// List available sessions
+const sessions = await client.listSessions();
+
+// Create a shareable session
+await client.spawn({
+  shell: '/bin/bash',
+  label: 'dev-session',      // Optional label for identification
+  allowJoin: true,           // Allow others to join (default: true)
+  orphanTimeout: 3600000,    // Keep alive 1 hour after last client leaves
+});
+
+// Join an existing session
+const session = await client.join({
+  sessionId: 'term-abc123...',
+  requestHistory: true,      // Request output history
+  historyLimit: 50000,       // Max history chars to receive
+});
+// session.history contains recent output
+
+// Leave session without killing it
+client.leave(sessionId);
+// Session survives if other clients connected
+// Or waits orphanTimeout before closing
+
+// Kill session
+client.kill();
+```
+
+### Use Cases
+
+**1. Pair Programming**
+```javascript
+// Developer A creates session
+await client.spawn({ label: 'pair-session' });
+// Share session ID with Developer B
+// Developer B joins with history
+await client.join({ sessionId, requestHistory: true });
+```
+
+**2. Session Persistence**
+```javascript
+// Start long-running task
+await client.spawn({ shell: '/bin/bash', orphanTimeout: 86400000 });
+client.write('npm run build\n');
+client.disconnect(); // Session survives!
+
+// Later, reconnect
+await client.connect();
+const sessions = await client.listSessions();
+await client.join({ sessionId: sessions[0].sessionId, requestHistory: true });
+// See build output that happened while disconnected
+```
+
+**3. Monitoring**
+```javascript
+// Admin joins session in read-only mode
+await client.join({ sessionId, requestHistory: true });
+// Watch activity without interfering
+```
+
+## Mobile Support
+
+On mobile devices, lit-shell automatically shows a touch keyboard with common terminal keys:
+
+```
+Row 1: [ESC] [/] [-] [HOME] [↑] [END] [PGUP]
+Row 2: [TAB] [CTRL] [ALT] [←] [↓] [→] [PGDN]
+Row 3: [^C] [^D] [^Z] [^L] [^A] [^E] [^R]  (expandable)
+```
+
+- **Auto-detection**: Detects mobile via touch capability + viewport size
+- **Sticky modifiers**: CTRL and ALT are toggle keys (tap to activate, applies to next key)
+- **Collapsible**: Extra row can be expanded/collapsed for more screen space
+- **Hide/show toggle**: Entire keyboard can be hidden when not needed
+
 ## Theming
 
 The component uses CSS custom properties for theming:
@@ -291,14 +662,72 @@ const server = new TerminalServer({
   // Restrict working directories
   allowedPaths: ['/home/app', '/var/www'],
 
+  // Restrict Docker containers
+  allowDockerExec: true,
+  allowedContainerPatterns: ['^myapp-'],
+
   // Limit sessions per client
   maxSessionsPerClient: 2,
 
   // Set idle timeout
-  idleTimeout: 10 * 60 * 1000, // 10 minutes
+  idleTimeout: 10 * 60 * 1000,
 });
 ```
 
+## Examples
+
+See the [examples](./examples) directory for complete working examples:
+
+- [**docker-container**](./examples/docker-container) - Connect to Docker containers from the browser
+- [**multiplexing**](./examples/multiplexing) - Session multiplexing with multiple clients sharing terminals
+
+### Running Locally (Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/lsadehaan/lit-shell.git
+cd lit-shell
+
+# Install dependencies (including node-pty)
+npm install
+npm install node-pty --save-dev --legacy-peer-deps
+
+# Build the project
+npm run build
+
+# Start a test container (optional, for Docker exec testing)
+docker run -d --name test-container alpine sleep infinity
+
+# Run the example server
+node examples/docker-container/server.js
+
+# Open http://localhost:3000 in your browser
+```
+
+### Quick Start with Docker Compose
+
+Run the full demo with Docker Compose (no local node-pty installation required):
+
+```bash
+cd docker
+docker compose up -d
+```
+
+This starts:
+- lit-shell server on http://localhost:3000
+- Two test containers (Alpine and Ubuntu) to exec into
+
+Open http://localhost:3000 and use the connection panel to:
+1. Select "Docker Container" mode
+2. Choose a container from the dropdown
+3. Click "Start Session"
+
+Stop the demo:
+
+```bash
+docker compose down
+```
+
 ## License
 
 MIT

package/dist/client/browser-bundle.js

@@ -1,3 +1,6 @@
+// src/version.ts
+var VERSION = "1.2.1";
+
 // src/client/terminal-client.ts
 var TerminalClient = class {
   constructor(config) {
@@ -8,6 +11,8 @@ var TerminalClient = class {
     this.serverInfo = null;
     this.reconnectAttempts = 0;
     this.reconnectTimeout = null;
+    this.previousSessionId = null;
+    this.isReconnecting = false;
     // Event handlers
     this.connectHandlers = [];
     this.disconnectHandlers = [];
@@ -24,6 +29,7 @@ var TerminalClient = class {
     this.clientJoinedHandlers = [];
     this.clientLeftHandlers = [];
     this.sessionClosedHandlers = [];
+    this.reconnectWithSessionHandlers = [];
     // Promise resolvers for spawn/join
     this.spawnResolve = null;
     this.spawnReject = null;
@@ -58,17 +64,25 @@ var TerminalClient = class {
         this.state = "connected";
         this.reconnectAttempts = 0;
         this.connectHandlers.forEach((handler) => handler());
+        if (this.isReconnecting && this.previousSessionId) {
+          this.checkPreviousSessionAndNotify();
+        }
+        this.isReconnecting = false;
         resolve();
       };
       this.ws.onclose = () => {
         const wasConnected = this.state === "connected";
         this.state = "disconnected";
+        if (this.sessionId) {
+          this.previousSessionId = this.sessionId;
+        }
         this.sessionId = null;
         this.sessionInfo = null;
         if (wasConnected) {
           this.disconnectHandlers.forEach((handler) => handler());
         }
         if (this.config.reconnect && this.reconnectAttempts < this.config.maxReconnectAttempts) {
+          this.isReconnecting = true;
           this.scheduleReconnect();
         }
       };
@@ -543,8 +557,54 @@ var TerminalClient = class {
   getServerInfo() {
     return this.serverInfo;
   }
+  /**
+   * Get previous session ID (available after disconnect)
+   */
+  getPreviousSessionId() {
+    return this.previousSessionId;
+  }
+  /**
+   * Clear previous session ID (call after user declines to rejoin)
+   */
+  clearPreviousSessionId() {
+    this.previousSessionId = null;
+  }
+  /**
+   * Called when reconnected and previous session is available
+   */
+  onReconnectWithSession(handler) {
+    this.reconnectWithSessionHandlers.push(handler);
+  }
+  /**
+   * Check if previous session exists and notify handlers
+   */
+  async checkPreviousSessionAndNotify() {
+    if (!this.previousSessionId)
+      return;
+    try {
+      const sessions = await this.listSessions();
+      const previousSession = sessions.find(
+        (s) => s.sessionId === this.previousSessionId
+      );
+      if (previousSession && previousSession.accepting) {
+        this.reconnectWithSessionHandlers.forEach((handler) => {
+          try {
+            handler(this.previousSessionId);
+          } catch (e) {
+            console.error("[lit-shell] Error in reconnectWithSession handler:", e);
+          }
+        });
+      } else {
+        this.previousSessionId = null;
+      }
+    } catch (e) {
+      console.error("[lit-shell] Failed to check previous session:", e);
+      this.previousSessionId = null;
+    }
+  }
 };
 export {
-  TerminalClient
+  TerminalClient,
+  VERSION
 };
 //# sourceMappingURL=browser-bundle.js.map