feat: make wasmPath optional with smart auto-detection (#21)

- Make Ghostty.load() wasmPath parameter optional with intelligent fallback logic
- Try multiple default paths: import.meta.url, relative, and root paths
- Update Terminal class to remove hardcoded wasmPath default
- Simplify test code to use auto-detection
- Fix build-wasm.sh to reference coder/ghostty repository
- Improve error messages with helpful guidance

Follows TensorFlow.js pattern for better developer experience.

Author: sreya

bun.lock

@@ -1,5 +1,6 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "@cmux/ghostty-terminal",

lib/ghostty.ts

@@ -55,39 +55,69 @@ export class Ghostty {
 
   /**
    * Load Ghostty WASM from URL or file path
+   * If no path is provided, attempts to load from common default locations
    */
-  static async load(wasmPath: string): Promise<Ghostty> {
-    let wasmBytes: ArrayBuffer;
+  static async load(wasmPath?: string): Promise<Ghostty> {
+    // Default WASM paths to try (in order)
+    const defaultPaths = [
+      // When running in Node/Bun (resolve to file path)
+      new URL('../ghostty-vt.wasm', import.meta.url).href.replace('file://', ''),
+      // When published as npm package (browser)
+      new URL('../ghostty-vt.wasm', import.meta.url).href,
+      // When used from CDN or local dev
+      './ghostty-vt.wasm',
+      '/ghostty-vt.wasm',
+    ];
+
+    const pathsToTry = wasmPath ? [wasmPath] : defaultPaths;
+    let lastError: Error | null = null;
+
+    for (const path of pathsToTry) {
+      try {
+        let wasmBytes: ArrayBuffer;
+
+        // Try loading as file first (for Node/Bun environments)
+        try {
+          const fs = await import('fs/promises');
+          const buffer = await fs.readFile(path);
+          wasmBytes = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+        } catch (e) {
+          // Fall back to fetch (for browser environments)
+          const response = await fetch(path);
+          if (!response.ok) {
+            throw new Error(`Failed to fetch WASM: ${response.status} ${response.statusText}`);
+          }
+          wasmBytes = await response.arrayBuffer();
+          if (wasmBytes.byteLength === 0) {
+            throw new Error(`WASM file is empty (0 bytes). Check path: ${path}`);
+          }
+        }
 
-    // Try loading as file first (for Node/Bun environments)
-    try {
-      const fs = await import('fs/promises');
-      const buffer = await fs.readFile(wasmPath);
-      wasmBytes = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
-    } catch (e) {
-      // Fall back to fetch (for browser environments)
-      const response = await fetch(wasmPath);
-      if (!response.ok) {
-        throw new Error(`Failed to fetch WASM: ${response.status} ${response.statusText}`);
-      }
-      wasmBytes = await response.arrayBuffer();
-      if (wasmBytes.byteLength === 0) {
-        throw new Error(`WASM file is empty (0 bytes). Check path: ${wasmPath}`);
+        // Successfully loaded, instantiate and return
+        const wasmModule = await WebAssembly.instantiate(wasmBytes, {
+          env: {
+            log: (ptr: number, len: number) => {
+              const instance = (wasmModule as any).instance;
+              const bytes = new Uint8Array(instance.exports.memory.buffer, ptr, len);
+              const text = new TextDecoder().decode(bytes);
+              console.log('[ghostty-wasm]', text);
+            },
+          },
+        });
+
+        return new Ghostty(wasmModule.instance);
+      } catch (e) {
+        lastError = e instanceof Error ? e : new Error(String(e));
+        // Try next path
       }
     }
 
-    const wasmModule = await WebAssembly.instantiate(wasmBytes, {
-      env: {
-        log: (ptr: number, len: number) => {
-          const instance = (wasmModule as any).instance;
-          const bytes = new Uint8Array(instance.exports.memory.buffer, ptr, len);
-          const text = new TextDecoder().decode(bytes);
-          console.log('[ghostty-wasm]', text);
-        },
-      },
-    });
-
-    return new Ghostty(wasmModule.instance);
+    // All paths failed
+    throw new Error(
+      `Failed to load ghostty-vt.wasm. Tried paths: ${pathsToTry.join(', ')}. ` +
+        `Last error: ${lastError?.message}. ` +
+        `You can specify a custom path with: new Terminal({ wasmPath: './path/to/ghostty-vt.wasm' })`
+    );
   }
 }
 

lib/input-handler.test.ts

@@ -129,8 +129,8 @@ describe('InputHandler', () => {
 
   beforeAll(async () => {
     // Load WASM once for all tests (expensive operation)
-    const wasmPath = new URL('../ghostty-vt.wasm', import.meta.url).href;
-    ghostty = await Ghostty.load(wasmPath);
+    // wasmPath is now optional - auto-detected
+    ghostty = await Ghostty.load();
   });
 
   beforeEach(() => {

lib/interfaces.ts

@@ -12,7 +12,7 @@ export interface ITerminalOptions {
   fontSize?: number; // Default: 15
   fontFamily?: string; // Default: 'monospace'
   allowTransparency?: boolean;
-  wasmPath?: string; // Default: '../ghostty-vt.wasm' (relative to examples/)
+  wasmPath?: string; // Optional: custom WASM path (auto-detected by default)
 }
 
 export interface ITheme {

lib/terminal.ts

@@ -37,7 +37,9 @@ export class Terminal implements ITerminalCore {
   public textarea?: HTMLTextAreaElement;
 
   // Options
-  private options: Required<ITerminalOptions>;
+  private options: Required<Omit<ITerminalOptions, 'wasmPath'>> & {
+    wasmPath?: string;
+  };
 
   // Components (created on open())
   private ghostty?: Ghostty;
@@ -79,7 +81,7 @@ export class Terminal implements ITerminalCore {
       fontSize: options.fontSize ?? 15,
       fontFamily: options.fontFamily ?? 'monospace',
       allowTransparency: options.allowTransparency ?? false,
-      wasmPath: options.wasmPath ?? '../ghostty-vt.wasm',
+      wasmPath: options.wasmPath, // Optional - Ghostty.load() handles defaults
     };
 
     this.cols = this.options.cols;

scripts/build-wasm.sh

@@ -21,7 +21,7 @@ echo "✓ Found Zig $ZIG_VERSION"
 GHOSTTY_DIR="/tmp/ghostty-for-wasm"
 if [ ! -d "$GHOSTTY_DIR" ]; then
     echo "📦 Cloning Ghostty..."
-    git clone --depth=1 https://github.com/ghostty-org/ghostty.git "$GHOSTTY_DIR"
+    git clone --depth=1 https://github.com/coder/ghostty.git "$GHOSTTY_DIR"
 else
     echo "📦 Updating Ghostty..."
     cd "$GHOSTTY_DIR"