# libghostty-vt WASM Build Guide

## Prerequisites

1. **Zig 0.13.0+** - Required for compiling to WebAssembly

### Install Zig

**Windows (PowerShell - Admin):**
```powershell
winget install Ziglang.Zig
```

**macOS:**
```bash
brew install zig
```

**Linux:**
```bash
wget https://github.com/ziglang/zig/releases/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
tar -xf zig-linux-x86_64-0.13.0.tar.xz
sudo mv zig-linux-x86_64-0.13.0 /opt/zig
export PATH=$PATH:/opt/zig
```

## Build Steps

### 1. Navigate to ghostty directory
```bash
cd ghostty-web/lib/ghostty
```

### 2. Build libghostty-vt WASM
```bash
zig build lib-vt -Dtarget=wasm32-freestanding
```

This will produce:
- `lib/ghostty-vt.wasm` - The WASM binary
- Headers for C integration

### 3. Alternative: Build with custom options
```bash
zig build lib-vt \
    -Dtarget=wasm32-freestanding \
    -Doptimize=ReleaseSmall \
    -Dwasm_shared=true
```

## Build Options

| Option | Description | Default |
|--------|-------------|---------|
| `-Dtarget` | Target architecture | `wasm32-freestanding` |
| `-Doptimize` | Optimization level | `ReleaseSmall` |
| `-Dwasm_shared` | Enable shared memory | `false` |

## Output Files

After building, the following files are generated:
- `zig-out/lib/` - Library files
- `zig-out/include/` - C headers

## Integration with Web Frontend

The WASM module exports C ABI functions. To use in browser:

1. Load the WASM module in JavaScript
2. Use WebAssembly.instantiate()
3. Call exported functions for VT parsing
4. Send parsed output to xterm.js for rendering

## Architecture

```
┌─────────────────────────────────────────────┐
│               Browser                        │
│  ┌─────────────┐    ┌──────────────────┐   │
│  │ JavaScript  │◄──►│  ghostty-vt.wasm  │   │
│  │             │    │  (VT Parser)       │   │
│  └──────┬──────┘    └──────────────────┘   │
│         │                                    │
│         ▼                                    │
│  ┌─────────────────────────────────────┐    │
│  │  xterm.js (Rendering)              │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘
         ▲
         │ WebSocket
┌────────┴────────────────────────────────────┐
│              Backend Server                   │
│  ┌──────────────┐    ┌──────────────────┐   │
│  │ WebSocket    │───►│ PTY (shell)       │   │
│  └──────────────┘    └──────────────────┘   │
└─────────────────────────────────────────────┘
```

## Troubleshooting

### "wasm32-freestanding is not a valid target"
Make sure you have Zig 0.13.0 or later:
```bash
zig version
```

### "Unable to find wasm-rt"
The WASM runtime is included in `src/os/wasm.zig`. Make sure you're using the correct build command.

### Build succeeds but browser fails to load WASM
- Check that the WASM file is served with correct MIME type (`application/wasm`)
- Ensure CORS headers are set if loading from different origin