# Quick Start Guide

## xterm.js 5.5.0 Upgrade - Quick Start

This guide will get you up and running with the upgraded xterm.js terminal in minutes.

## Prerequisites

- Rust and Cargo installed
- Node.js and npm installed
- A terminal/command line

## Installation & Running

### Step 1: Install npm Dependencies

```bash
npm install
```

This installs:
- `@xterm/xterm` v5.5.0 (the main terminal library)
- `@xterm/addon-fit` v0.10.0 (auto-sizing addon)

### Step 2: Copy Custom Addon

```bash
cp static/terminado-addon.js node_modules/
```

This makes our custom Terminado WebSocket addon available to the server.

### Step 3: Build the Rust Backend

```bash
cargo build
```

### Step 4: Run the Server

```bash
cargo run
```

The server will start on `http://127.0.0.1:8082` (localhost:8082)

### Step 5: Open in Browser

Navigate to: **http://localhost:8082/**

You should see:
- A terminal that auto-launches `socktop -P local`
- A properly sized terminal that fits the window
- A responsive terminal that resizes with the browser window

## Verify the Upgrade

Run the verification script to ensure everything is set up correctly:

```bash
./verify_upgrade.sh
```

All checks should pass with green checkmarks ✓

## Command Line Options

The server supports several command-line options:

```bash
# Run on a different port
cargo run -- --port 8080

# Run on all interfaces (0.0.0.0)
cargo run -- --host 0.0.0.0

# Use a different command
cargo run -- --command /bin/bash

# Combine options
cargo run -- --host 0.0.0.0 --port 8080 --command /bin/zsh
```

## Testing the Terminal

Open the standalone test page to verify xterm.js is working:

```bash
# Start a simple HTTP server
python3 -m http.server 8000

# Open in browser
# http://localhost:8000/test_xterm.html
```

This test page verifies:
- xterm.js 5.5.0 loads correctly
- FitAddon works
- Terminal accepts input
- Modern API is functional

## What Changed from 3.14.5 to 5.5.0?

### Package Names
- Old: `xterm`
- New: `@xterm/xterm` (scoped package)

### Addon System
- Old: `Terminal.applyAddon(fit)` → `term.fit()`
- New: `term.loadAddon(new FitAddon())` → `fitAddon.fit()`

### File Locations
- Old: `xterm/dist/xterm.js`
- New: `@xterm/xterm/lib/xterm.js`

### Custom Terminado Addon
We created a modern `TerminadoAddon` class that implements the new `ITerminalAddon` interface to handle WebSocket communication with the backend.

## Architecture

```
┌─────────────────┐
│   Browser       │
│  (JavaScript)   │
│                 │
│  ┌───────────┐  │
│  │ xterm.js  │  │
│  │  v5.5.0   │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ FitAddon  │  │
│  └───────────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ Terminado │  │
│  │   Addon   │  │
│  └─────┬─────┘  │
└────────┼────────┘
         │ WebSocket
         │ (JSON messages)
┌────────▼────────┐
│  Rust Backend   │
│                 │
│  ┌───────────┐  │
│  │ actix-web │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ Terminado │  │
│  │  Protocol │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │    PTY    │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │  socktop  │  │
│  └───────────┘  │
└─────────────────┘
```

## Troubleshooting

### Terminal doesn't display
- Check browser console for JavaScript errors
- Verify WebSocket connection in DevTools Network tab
- Ensure server is running on the correct port

### Resources fail to load (404 errors)
- Run `npm install` to ensure packages are installed
- Verify `terminado-addon.js` is in `node_modules/`
- Check file paths in `templates/term.html`

### Terminal doesn't fit window
- FitAddon may not be loading correctly
- Check that `fitAddon.fit()` is called after terminal is opened
- Verify container has non-zero dimensions

### Rust compile errors
- Update Rust: `rustup update`
- Clean build: `cargo clean && cargo build`

### WebSocket connection fails
- Check firewall settings
- Try binding to `127.0.0.1` instead of `localhost`
- Verify port 8082 is not in use

## Next Steps

Now that xterm.js is upgraded, you can:

1. **Customize the terminal appearance**
   - Modify colors in `templates/term.html`
   - Change font size and family
   - Adjust terminal dimensions

2. **Add more features**
   - Install additional xterm addons
   - Implement search functionality
   - Add web link support

3. **Build your website**
   - Use this as a foundation for your socktop website
   - Add navigation and branding
   - Implement user authentication

4. **Deploy to production**
   - Set up HTTPS (required for secure WebSockets)
   - Configure proper firewall rules
   - Consider adding authentication

## Additional Resources

- **Full Documentation**: See `XTERM_UPGRADE.md`
- **Upgrade Details**: See `UPGRADE_SUMMARY.md`
- **Verification**: Run `./verify_upgrade.sh`
- **Test Page**: Open `test_xterm.html` in browser

## Getting Help

If you run into issues:

1. Run the verification script: `./verify_upgrade.sh`
2. Check the browser console for errors
3. Review server logs for backend issues
4. Consult the detailed documentation in `XTERM_UPGRADE.md`

---

**Status**: ✅ Upgrade Complete  
**xterm.js Version**: 5.5.0  
**FitAddon Version**: 0.10.0  
**Backend**: Rust + actix-web (no changes required)