research(terminal): evaluate xterm.js alternatives for AI CLI tool hosting

[Fldicoahkiin]

Context

2code's primary use case is hosting AI CLI tools (Claude Code, Codex, etc.). xterm.js has several limitations for this use case:

• Scroll jumping with TUI apps (bug(terminal): scroll jumps to top when running AI CLI tools (Claude Code, Codex) #144)
• Kitty keyboard protocol implementation bugs (feat(terminal): adopt Kitty keyboard protocol for proper modifier key handling #139)
• IME composition handling issues (xtermjs/xterm.js#1939)

This issue tracks research into alternative terminal rendering architectures.

Architecture Comparison

Current: xterm.js

Pipeline: PTY bytes → JS VT parser (DFA) → CircularList grid → DOM/WebGL renderer

• Pros: most mature web terminal, huge ecosystem, VS Code uses it
• Cons: JS parsing bottleneck, no native Kitty protocol, scroll-jump bug
• Rendering: DOM (default), WebGL addon, Canvas 2D (deprecated)

Option A: ghostty-web (Ghostty VT → WASM)

Pipeline: PTY bytes → WASM VT parser (Ghostty/Zig SIMD) → Canvas 2D renderer

Source: coder/ghostty-web

• Pros: Kitty protocol native, no scroll-jump issue (Canvas rendering), faster VT parsing
• Cons:
  • WASM memory corruption (#141) — free() after emoji causes all subsequent terminals to crash. Blocking for multi-tab apps
  • Maintenance stalled (v0.4.0, 2025-12-09, 5 months no release)
  • Korean IME broken, no image protocol, no search, no WebGL renderer
  • Zero Tauri integration examples
  • Scrollback unit bug (#140) + viewport corruption (#139)
• Status: NOT VIABLE currently. Monitor fix(build): handle empty array expansion under bash nounset mode #141 and perf: reuse file tree path collator #162 (Ghostty 1.3 upgrade)

Option B: alacritty_terminal (Rust backend + WebView rendering)

Pipeline: PTY bytes → Rust VT parser → Grid model + damage tracking → IPC → WebGL/Canvas in WebView

Source: alacritty_terminal crate + egui_term embedding example

• Pros: battle-tested VT parser, damage tracking reduces IPC overhead, full control
• Cons:
  • No existing WebView integration — GitHub search "alacritty_terminal webview" returns 0 results
  • All Tauri terminal projects use xterm.js (hermes-ide, kerminal, Terminal-64)
  • IPC overhead: incremental updates 1-5KB/frame OK, full redraws 46-384KB/frame problematic with JSON
  • Estimated 2000-4000 lines of bridge code
  • Need to build WebGL renderer from scratch
• Status: Technically feasible but high effort, no precedent

Option C: libghostty (Zig/C library)

Pipeline: PTY bytes → libghostty (SIMD VT parser + grid + damage tracking) → C API → Rust FFI → IPC → WebView

Source: libghostty announcement, awesome-libghostty

• Pros: fastest VT parser (SIMD), native Kitty protocol, growing ecosystem (browstty, obsidian-ghostty-terminal, vscode-bootty)
• Cons:
  • Zig → C → Rust FFI chain
  • Still alpha, official WASM distribution not published
  • Same WebView rendering challenge as Option B
• Status: Most promising long-term, too early now
• Notable: xterm.js itself considering adopting libghostty — but no consensus among maintainers

Option D: Stay on xterm.js, upgrade to 7.0

Pipeline: Same as current, but with upstream fixes

• xterm.js 7.0 milestone includes:
  • PR #5770 — DEC 2026 viewport fix (eliminates scroll jump)
  • Potentially libghostty adoption (per #5686, but no timeline)
• Combine with:
  • Tabby-style pinnedToBottom scroll fix (PR #11102)
  • Claude Code environment variables for immediate relief
  • Kitty protocol workarounds (feat(terminal): adopt Kitty keyboard protocol for proper modifier key handling #139)
• Status: Most pragmatic path

Not viable

• termwiz: Not a terminal emulator. Surface/Change model is for building TUI apps, cannot process bash/vim escape sequences.
• Kitty rendering code: Tightly coupled to window management, no library form, no API.
• Warp terminal code: WarpUI not independently published, AGPL-3.0 license.
• Tauri native terminal view: Tauri 2 doesn't support embedding non-WebView native components without per-platform plugin work.

How Other Terminals Handle AI CLI Tools

Terminal	Architecture	AI CLI scroll issue?	Solution
Warp	Block model + Metal/wgpu	No	Each command is isolated block
Kitty	OpenGL + C parser	No	GPU rendering, no DOM scroll
Ghostty	Metal/GL + Zig SIMD parser	No	Same as Kitty
VS Code	xterm.js	Yes	Same issue, no fix yet
Tabby	xterm.js	Yes → Fixed	pinnedToBottom flag (PR #11102)
Hyper	xterm.js	Yes	Unfixed since 2023 (#7065)
iTerm2	Native Cocoa	Partial	Native rendering helps, but Ink layer still flickers
WezTerm	termwiz + wgpu	Has issues	#7531, limited info

Recommendation

Short-term (now): Stay on xterm.js. Inject Claude Code env vars + implement Tabby-style scroll fix.

Medium-term (xterm.js 7.0): Upgrade when 7.0 releases with PR #5770 (DEC 2026 viewport fix).

Long-term (watch):

• ghostty-web: monitor fix(build): handle empty array expansion under bash nounset mode #141 (WASM memory corruption) — if fixed, it becomes a viable drop-in replacement
• libghostty: monitor ecosystem growth and official WASM distribution
• xterm.js #5686: if xterm.js adopts libghostty internally, we benefit automatically

Related

• feat(terminal): adopt Kitty keyboard protocol for proper modifier key handling #139 — Kitty keyboard protocol
• bug(terminal): scroll jumps to top when running AI CLI tools (Claude Code, Codex) #144 — Scroll jump bug with AI CLI tools

[Fldicoahkiin]

Deep Dive: Native Terminal View in Tauri (Option E)

Architecture

Bypass WebView for terminal rendering. WebView handles UI (sidebar, settings, file tree), a native child view handles terminal with GPU rendering.

NSWindow (Tauri owns)
├── WKWebView (resized via Webview::set_bounds())
│   └── Renders: sidebar, settings, project management, file tree
└── NSView / HWND / GTK Widget (new native child view)
    └── wgpu Surface → terminal rendering (GPU accelerated)

Why this fixes everything

Problem	Root cause with WebView	Native view solution
Scroll jump	xterm.js DOM scrollTop reset	GPU render, no DOM scroll
Kitty protocol	xterm.js flag 1 encodes Ctrl+C as CSI u	alacritty_terminal handles natively
IME	Browser compositionstart/end event model	macOS NSTextInputClient, Windows ImmSetCompositionWindow
Performance	JS VT parsing bottleneck	Rust VT parsing + GPU rendering

Reference implementations

All three terminals we want to align with use this exact approach:

Warp (Rust, source):

• wgpu 29.0.1 for cross-platform GPU (Metal/Vulkan/DX12)
• font-kit (custom fork) + core-text for text
• pathfinder_simd for vector geometry
• winit 0.30.1 (custom fork) for windowing
• VT parsing: vte (custom fork) + Alacritty-derived grid model

Ghostty (Zig, source):

• Metal (macOS) / OpenGL (Linux) for rendering
• CoreText for font shaping on macOS
• libghostty separates VT parsing from rendering
• Swift/AppKit SurfaceView for macOS integration with NSTextInputClient for IME

Zed Editor's terminal (Rust, source):

• alacritty_terminal for VT parsing + PTY management
• GPUI framework: metal crate + core-text on macOS, wgpu + cosmic-text on Linux/Windows
• Most relevant reference — same pattern (terminal library + GPU rendering in a larger app)

Recommended tech stack for 2code

Component	Crate	Used by
VT parsing + PTY	alacritty_terminal	Zed, egui_term
GPU abstraction	wgpu	WezTerm, Zed (Linux/Win), Warp
Text shaping	cosmic-text	Zed (Linux/Win)
Text rendering on wgpu	glyphon	Built on cosmic-text + wgpu
Window handle	raw-window-handle 0.6	All of the above

Tauri integration proof

• Webview::set_bounds() can resize WebView to make room for native terminal view
• Window::ns_window() / Window::gtk_window() provides native window handle
• raw-window-handle 0.6 AppKitWindowHandle stores NSView pointer (not NSWindow), wgpu can render to child views
• tauri-wgpu-test demonstrates Tauri + wgpu rendering in same window

Platform-specific work

Platform	Window	GPU	Text	IME
macOS	NSView child of contentView	wgpu (Metal backend)	cosmic-text or CoreText via core-text crate	NSTextInputClient protocol (ref: Ghostty SurfaceView_AppKit.swift)
Windows	HWND child window	wgpu (DX12/Vulkan backend)	cosmic-text	ImmSetCompositionWindow / TSF
Linux	GTK widget	wgpu (Vulkan backend)	cosmic-text	GTK IMContext

Effort estimate

Component	Weeks (1 person)	Notes
Platform integration (NSView/HWND/GTK child view)	2-3	macOS most mature, Linux GTK hardest
wgpu terminal renderer (glyph atlas + grid + cursor + selection)	4-6	Zed's GPUI terminal_view is reference
Text shaping (cosmic-text/glyphon)	2-3	Monospace font simpler, CJK + emoji is the hard part
alacritty_terminal integration	1-2	VT parsing + grid state + PTY
Input handling (keyboard/mouse/IME)	2-3	IME is biggest challenge, per-platform code
Tauri bridge (events/commands)	1-2	WebView ↔ native view communication
Scrollback + selection + clipboard	1-2
Total	13-21	Single developer estimate

Key risks

1. IME per-platform: macOS NSTextInputClient, Windows TSF/IMM, Linux GTK IMContext — three separate implementations. Ghostty's SurfaceView_AppKit.swift and Warp's host_view.m are the best references.
2. View synchronization: WebView and native view must coordinate layout on window resize. Tauri's set_bounds() API helps but edge cases exist.
3. Focus routing: Keyboard events need to route correctly between WebView (for UI shortcuts) and native view (for terminal input).
4. Multi-terminal: One wgpu surface per tab, or shared surface with viewport scissoring? Shared is more efficient but harder.

Alternative: Use Zed's approach directly

Zed already solved "alacritty_terminal + wgpu rendering in a larger app". Their crates/terminal/ and crates/terminal_view/ could be studied line-by-line as implementation reference:

• terminal/src/terminal.rs — alacritty_terminal wrapper
• terminal_view/src/terminal_view.rs — GPUI rendering of terminal grid
• terminal_view/src/terminal_element.rs — actual paint commands

Conclusion

This is the only path that truly aligns with Kitty/Ghostty/Warp quality. The WebView terminal (xterm.js or ghostty-web) will always be limited by the browser's input handling and rendering model. The investment is significant (13-21 weeks) but eliminates an entire class of problems permanently.

Suggested phasing:

1. Phase 1: PoC — render a static terminal grid via wgpu in a Tauri child view (2-3 weeks)
2. Phase 2: Integration — connect alacritty_terminal, handle input, basic rendering (4-6 weeks)
3. Phase 3: Polish — IME, themes, selection, clipboard, multi-tab (4-6 weeks)
4. Phase 4: Parity — match current xterm.js feature set (2-4 weeks)

Related: #139, #144