XCTerminal/docs/WASM_BUILD.md

libghostty-vt WASM Build Guide

Prerequisites

1. Zig 0.13.0+ - Required for compiling to WebAssembly

Install Zig

Windows (PowerShell - Admin):

winget install Ziglang.Zig

macOS:

brew install zig

Linux:

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

cd ghostty-web/lib/ghostty

2. Build libghostty-vt WASM

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

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:

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