ghostty-web 0.2.1 → 0.3.0-next.1.ge5f6964

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +46 -102
  2. package/dist/ghostty-vt.wasm +0 -0
  3. package/dist/ghostty-web.js +847 -580
  4. package/dist/ghostty-web.umd.cjs +13 -4
  5. package/dist/index.d.ts +120 -24
  6. package/ghostty-vt.wasm +0 -0
  7. package/package.json +3 -1
package/README.md CHANGED
@@ -1,138 +1,82 @@
1
1
  # ghostty-web
2
2
 
3
- ![ghostty](https://github.com/user-attachments/assets/8ef9161e-135d-4189-a6f6-0a644a82a5de)
3
+ [![NPM Version](https://img.shields.io/npm/v/ghostty-web)](https://npmjs.com/package/ghostty-web) [![NPM Downloads](https://img.shields.io/npm/dw/ghostty-web)](https://npmjs.com/package/ghostty-web) [![license](https://img.shields.io/github/license/coder/ghostty-web)](./LICENSE)
4
4
 
5
- `ghostty-web` is a fully-featured web terminal built on [Ghostty's](https://github.com/ghostty-org/ghostty)
6
- terminal emulation core compiled to WebAssembly. By leveraging Ghostty's production-tested VT100 parser
7
- and state machine, `ghostty-web` delivers fast, robust terminal emulation in the browser. For many use
8
- cases it is a drop-in replacement for xterm.js.
5
+ [Ghostty](https://github.com/ghostty-org/ghostty) for the web with [xterm.js](https://github.com/xtermjs/xterm.js) API compatibility — giving you a proper VT100 implementation in the browser, not a JavaScript approximation of one.
9
6
 
10
- ## Live Demo
7
+ - Migrate from xterm by changing your import: `@xterm/xterm` → `ghostty-web`
8
+ - WASM-compiled parser from Ghostty—the same code that runs the native app
9
+ - Zero runtime dependencies, ~400KB WASM bundle
11
10
 
12
- You can try ghostty-web yourself:
13
-
14
- > [!NOTE]
15
- > Requires Zig and Bun, see [Development](#development)
11
+ ## Try It
16
12
 
17
13
  ```bash
18
- git clone https://github.com/coder/ghostty-web
19
- cd ghostty-web
20
- bun install
21
- bun run build # Builds the WASM module and library
22
-
23
- # Terminal 1: Start PTY Server
24
- cd demo/server
25
- bun install
26
- bun run start
27
-
28
- # Terminal 2: Start web server
29
- bun run start # http://localhost:8000/demo/
14
+ npx @ghostty-web/demo@next
30
15
  ```
31
16
 
32
- ## Getting Started
33
-
34
- Install the module via npm
17
+ This starts a local HTTP server with a real shell on `http://localhost:8080`. Works best on Linux and macOS.
35
18
 
36
- ```bash
37
- npm install ghostty-web
38
- ```
39
-
40
- After install, using `ghostty-web` is as simple as
41
-
42
- ```html
43
- <!doctype html>
44
- <html>
45
- <body>
46
- <div id="terminal"></div>
47
- <script type="module">
48
- import { Terminal } from 'ghostty-web';
49
- const term = new Terminal();
50
- await term.open(document.getElementById('terminal'));
51
- term.write('Hello from \x1B[1;3;31mghostty-web\x1B[0m $ ');
52
- </script>
53
- </body>
54
- </html>
55
- ```
19
+ ![ghostty](https://github.com/user-attachments/assets/aceee7eb-d57b-4d89-ac3d-ee1885d0187a)
56
20
 
57
- ## Features
21
+ ## Comparison with xterm.js
58
22
 
59
- `ghostty-web` compiles Ghostty's core terminal emulation engine (parser, state
60
- machine, and screen buffer) to WebAssembly, providing:
23
+ xterm.js is everywhere—VS Code, Hyper, countless web terminals. But it has fundamental issues:
61
24
 
62
- **Core Terminal:**
25
+ | Issue | xterm.js | ghostty-web |
26
+ | ---------------------------------------- | ------------------------------------------------------------------- | -------------------------- |
27
+ | **RTL languages** | [Broken since 2017](https://github.com/xtermjs/xterm.js/issues/701) | ✓ Works |
28
+ | **Complex scripts** (Devanagari, Arabic) | Rendering issues | ✓ Proper grapheme handling |
29
+ | **XTPUSHSGR/XTPOPSGR** | [Not supported](https://github.com/xtermjs/xterm.js/issues/2570) | ✓ Full support |
63
30
 
64
- - Full VT100/ANSI escape sequence support
65
- - True color (24-bit RGB) + 256 color + 16 ANSI colors
66
- - Text styles: bold, italic, underline, strikethrough, dim, reverse
67
- - Alternate screen buffer (for vim, htop, less, etc.)
68
- - Scrollback buffer with mouse wheel support
31
+ xterm.js reimplements terminal emulation in JavaScript. Every escape sequence, every edge case, every Unicode quirk—all hand-coded. Ghostty's emulator is the same battle-tested code that runs the native Ghostty app.
69
32
 
70
- **Input & Interaction:**
33
+ ## Installation
71
34
 
72
- - Text selection and clipboard integration
73
- - Mouse tracking modes
74
- - Kitty keyboard protocol support
75
- - Custom key/wheel event handlers
76
-
77
- **API & Integration:**
78
-
79
- - xterm.js-compatible API (drop-in replacement for many use cases)
80
- - FitAddon for responsive terminal sizing
81
- - Event system (onData, onResize, onBell, onScroll, etc.)
82
-
83
- **Performance:**
84
-
85
- - Canvas-based rendering at 60 FPS
86
- - Zero runtime dependencies (just ghostty-web + bundled WASM)
87
- - Parser/state machine from Ghostty
88
-
89
- ## Why ghostty-web?
35
+ ```bash
36
+ npm install ghostty-web
37
+ ```
90
38
 
91
- - **Don't reimplement VT100 parsing** – it's thousands of edge cases refined over years. Instead, leverage Ghostty's battle-tested terminal emulator that's proven by thousands of daily users.
92
- - **Drop-in xterm.js replacement** – for many use cases, ghostty-web can replace xterm.js with minimal code changes
93
- - **Modern & maintained** – Built on Ghostty, an actively developed modern terminal emulator, ensuring continued improvements and bug fixes.
39
+ ## Usage
94
40
 
95
- ## Usage Examples
41
+ ghostty-web aims to be API-compatible with the xterm.js API.
96
42
 
97
- ### Basic Terminal
43
+ ```javascript
44
+ import { init, Terminal } from 'ghostty-web';
98
45
 
99
- ```typescript
100
- import { Terminal, FitAddon } from 'ghostty-web';
46
+ await init();
101
47
 
102
48
  const term = new Terminal({
103
- cursorBlink: true,
104
49
  fontSize: 14,
105
50
  theme: {
106
- background: '#1e1e1e',
107
- foreground: '#d4d4d4',
51
+ background: '#1a1b26',
52
+ foreground: '#a9b1d6',
108
53
  },
109
54
  });
110
55
 
111
- const fitAddon = new FitAddon();
112
- term.loadAddon(fitAddon);
113
-
114
- await term.open(document.getElementById('terminal'));
115
- fitAddon.fit();
116
-
117
- // Handle user input
118
- term.onData((data) => {
119
- // Send to backend/PTY
120
- console.log('User typed:', data);
121
- });
56
+ term.open(document.getElementById('terminal'));
57
+ term.onData((data) => websocket.send(data));
58
+ websocket.onmessage = (e) => term.write(e.data);
122
59
  ```
123
60
 
124
- ## Development
125
-
126
- ### Prerequisites
61
+ For a comprehensive client <-> server example, refer to the [demo](./demo/index.html#L141).
127
62
 
128
- - [bun](https://bun.com/docs/installation)
129
- - [zig](https://ziglang.org/download/)
63
+ ## Development
130
64
 
131
- ### Building WASM
65
+ ghostty-web builds from Ghostty's source with a [patch](./patches/ghostty-wasm-api.patch) to expose additional
66
+ functionality.
132
67
 
133
- `ghostty-web` builds a custom WASM binary from Ghostty's source with patches to expose additional
134
- browser-specific functionality
68
+ > Requires Zig and Bun.
135
69
 
136
70
  ```bash
137
71
  bun run build
138
72
  ```
73
+
74
+ Mitchell Hashimoto (author of Ghostty) has [been working](https://mitchellh.com/writing/libghostty-is-coming) on `libghostty` which makes this all possible. The patches are very minimal thanks to the work the Ghostty team has done, and we expect them to get smaller.
75
+
76
+ This library will eventually consume a native Ghostty WASM distribution once available, and will continue to provide an xterm.js compatible API.
77
+
78
+ At Coder we're big fans of Ghostty, so kudos to that team for all the amazing work.
79
+
80
+ ## License
81
+
82
+ [MIT](./LICENSE)
package/dist/ghostty-vt.wasm CHANGED
Binary file