feat: Build WASM from ghostty-org/ghostty submodule with patches

Major architectural change to build WASM from source instead of committing
the binary to the repository.

Changes:
- Add ghostty-org/ghostty as root-level submodule (pinned to 0f64b9a8e)
- Add patches/ghostty-wasm-api.patch (33KB, 1006 lines)
  - Exposes 16 C API functions for terminal integration
  - Based on coder/ghostty fork commit bfd067d
- Rewrite scripts/build-wasm.sh:
  - Initialize submodule if needed
  - Apply patch, build WASM with Zig, revert patch
  - Keeps submodule clean for easy updates
- Update CI workflow:
  - Add Zig 0.15.2 installation to test and build jobs
  - Build WASM before running tests/build
  - Add WASM size check (512KB limit)
- Update package.json:
  - Add build:wasm script
  - Integrate WASM build into main build process
- Update .gitignore:
  - Ignore ghostty-vt.wasm (built locally and in CI)
  - Ignore ghostty/zig-out/ and ghostty/zig-cache/
- Remove committed ghostty-vt.wasm binary (404KB)
- Update README.md and INSTALL.md with new build instructions

Benefits:
- Transparent build process (exact Ghostty version + patches visible)
- Easier to update upstream Ghostty
- Smaller git history (no binary commits)
- WASM still included in npm package (built during prepublishOnly)

Build time: ~20 seconds for WASM, adds ~30 seconds to CI test/build jobs

Author: sreya

.github/workflows/ci.yml

@@ -60,11 +60,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
       - uses: oven-sh/setup-bun@v1
         with:
           bun-version: latest
 
+      - name: Install Zig 0.15.2
+        run: |
+          curl -L -o zig.tar.xz https://ziglang.org/download/0.15.2/zig-linux-x86_64-0.15.2.tar.xz
+          tar xf zig.tar.xz
+          sudo mv zig-linux-x86_64-0.15.2 /usr/local/zig-0.15.2
+          sudo ln -s /usr/local/zig-0.15.2/zig /usr/local/bin/zig
+
+      - name: Build WASM
+        run: ./scripts/build-wasm.sh
+
       - name: Install dependencies
         run: bun install
 
@@ -76,11 +88,32 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
       - uses: oven-sh/setup-bun@v1
         with:
           bun-version: latest
 
+      - name: Install Zig 0.15.2
+        run: |
+          curl -L -o zig.tar.xz https://ziglang.org/download/0.15.2/zig-linux-x86_64-0.15.2.tar.xz
+          tar xf zig.tar.xz
+          sudo mv zig-linux-x86_64-0.15.2 /usr/local/zig-0.15.2
+          sudo ln -s /usr/local/zig-0.15.2/zig /usr/local/bin/zig
+
+      - name: Build WASM
+        run: ./scripts/build-wasm.sh
+
+      - name: Check WASM size
+        run: |
+          SIZE=$(stat -c%s ghostty-vt.wasm)
+          echo "WASM size: $SIZE bytes"
+          if [ "$SIZE" -gt 524288 ]; then
+            echo "❌ Error: WASM exceeds 512 KB limit"
+            exit 1
+          fi
+
       - name: Install dependencies
         run: bun install
 

.gitignore

@@ -3,3 +3,10 @@ dist/
 .DS_Store
 *.log
 .vite/
+
+# WASM build output (built locally and in CI)
+ghostty-vt.wasm
+
+# Ghostty submodule build artifacts
+ghostty/zig-out/
+ghostty/zig-cache/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ghostty"]
+	path = ghostty
+	url = https://github.com/ghostty-org/ghostty.git

INSTALL.md

@@ -91,7 +91,18 @@ ws.onmessage = (event) => {
 
 ## WASM File Handling
 
-The library requires the `ghostty-vt.wasm` file at runtime. Most bundlers handle this automatically.
+The library requires the `ghostty-vt.wasm` file at runtime. When installing from npm, the WASM is pre-built and included. When installing from git, it's built during `postinstall`.
+
+### Local Development
+
+After cloning:
+
+```bash
+git submodule update --init --recursive
+./scripts/build-wasm.sh
+```
+
+The WASM file is generated locally and gitignored.
 
 ### Vite (Recommended)
 

README.md

@@ -218,30 +218,48 @@ WebSocket Server (server/file-browser-server.ts)
 └── ghostty-vt.wasm       - Ghostty VT100 parser (122 KB)
 ```
 
-## Building
+## Building WASM
 
-Requires:
+The WASM binary is built from source, not committed to the repo.
 
-- **Zig 0.15.2+** (to build WASM)
-- **Ghostty source** (from GitHub)
+**Requirements:**
+
+- Zig 0.15.2+
+- Git submodules initialized
+
+**Build:**
 
 ```bash
-# Install Zig 0.15.2
-curl -L -o zig-0.15.2.tar.xz \
-  https://ziglang.org/download/0.15.2/zig-x86_64-linux-0.15.2.tar.xz
-tar xf zig-0.15.2.tar.xz
-sudo cp -r zig-x86_64-linux-0.15.2 /usr/local/zig-0.15.2
-sudo ln -sf /usr/local/zig-0.15.2/zig /usr/local/bin/zig
-
-# Clone Ghostty
-git clone https://github.com/ghostty-org/ghostty.git
-cd ghostty
+# Initialize submodule (first time only)
+git submodule update --init --recursive
 
-# Build WASM (~20 seconds)
-zig build lib-vt -Dtarget=wasm32-freestanding -Doptimize=ReleaseSmall
-# Output: zig-out/bin/ghostty-vt.wasm (122 KB)
+# Build WASM
+./scripts/build-wasm.sh
+# or
+bun run build:wasm
 ```
 
+**What it does:**
+
+1. Initializes `ghostty/` submodule (ghostty-org/ghostty)
+2. Applies patches from `patches/ghostty-wasm-api.patch`
+3. Builds WASM with Zig (takes ~20 seconds)
+4. Outputs `ghostty-vt.wasm` (404 KB)
+5. Reverts patch to keep submodule clean
+
+**Updating Ghostty:**
+
+```bash
+cd ghostty
+git fetch origin
+git checkout <commit-or-tag>
+cd ..
+./scripts/build-wasm.sh
+# Test, then commit the updated submodule pointer
+```
+
+**CI:** The WASM is built as part of the `test` and `build` jobs.
+
 ## Testing
 
 Run the test suite:

ghostty

@@ -46,7 +46,8 @@
   },
   "scripts": {
     "dev": "vite --port 8000",
-    "build": "bun run clean && bun run build:lib && bun run build:wasm-copy",
+    "build": "bun run clean && bun run build:wasm && bun run build:lib && bun run build:wasm-copy",
+    "build:wasm": "./scripts/build-wasm.sh",
     "build:lib": "vite build",
     "build:wasm-copy": "cp ghostty-vt.wasm dist/",
     "clean": "rm -rf dist",