Coming from xterm.js

Creation is asynchronous, input events carry bytes, and the main entry writes synchronously. Begin with the quick start, then replace your transport and appearance wiring.

API mapping

This table imports a checked registry. Every instance member below must exist on the built Terminal declaration.

xterm.js	ghostty-webgpu	Behavior
`new Terminal(options)`	`await Terminal.create(options)`	Creation loads wasm asynchronously.
`open(host)`	`open`	Await opening; the host must have a size.
`write(data, callback)`	`write`	Synchronous result on the main entry; promise in the worker.
`writeln(data)`	`writeln`	Write a line through native parsing.
`onData / onBinary`	`onData`	The listener receives Uint8Array bytes.
`onResize`	`onResize`	The event has cols and rows.
`onTitleChange / onBell`	`on`	Subscribe to title and bell events.
`onRender`	`onFrame`	Observe submitted rows.
`FitAddon.fit()`	`setAppearance`	Automatic fit; set appearance.grid for explicit geometry.
`options.theme`	`setTheme`	RGB objects and a 256-entry palette.
`options.fontFamily / fontSize`	`setFont`	A partial native font object.
`options.cursorStyle / cursorBlink`	`setCursor`	A partial native cursor object.
`buffer.active.length`	`lineCount`	Counts retained history and active visible rows.
`buffer.getLine(i)`	`readLines`	Half-open ranges, capped at 1,024 rows.
`getSelection()`	`getSelection`	Choose plain, VT or HTML formatting.
`select / selectAll`	`selectRange`	Native coordinates; selectAll is also available.
`scrollLines`	`scrollBy`	Scroll by a row delta.
`scrollToLine`	`scrollToRow`	Scroll to a retained row.
`loadAddon(addon)`	`use`	Install a native extension.
`registerLinkProvider`	`registerLinkProvider`	URL and OSC 8 detection are built in.
`attachCustomKeyEventHandler`	`connectInput`	Synchronous claim/pass ownership on the main entry.
`focus / blur / dispose`	`dispose`	Focus and blur stay synchronous; dispose returns a promise in the worker.

Use sendInput for generated input, paste for bracketed paste and key for a synthesized key. Named events include title, bell, selection and scroll. The generated reference has their payload types.

Addon mapping

xterm.js addon	Current integration	Status
Fit	The host fits automatically	Built in
WebGL	Automatic WebGL2/WebGPU selection	Built in
Unicode 11 / Unicode graphemes	Native widths and mode 2027	Built in
Web links	URL detection, OSC 8 and link providers	Built in on main entry
Clipboard	Host `clipboardWrite` policy for OSC 52 writes; defaults to deny	Write-only policy
Attach	WebSocket recipe	Guide
Web fonts	Load browser or worker faces	Guide
Serialize	History reads, selection formats and visual viewport capture	Partial; full emulator serialization is planned
Search	Retained-cell search	Planned
Image	Image protocols	Planned
Ligatures	Run shaping	Planned
Progress	Native progress events exposed to the host	Planned

The extension plan tracks the extension model. The terminal roadmap tracks delivery. Worker link providers and keyboard link discovery currently report capability errors.

registerMarker, registerDecoration and the general xterm parser-handler API have no public equivalent today. Custom OSC observation is a session-level capability. Clipboard reads through OSC 52 receive no reply.

Appearance and history

Use appearance.scrollbackLimit and appearance.scrollbackByteLimit. Retention is page-granular. Read lineCount() for the actual retained count. Colors use RGB values, and minimumContrast belongs to the theme. Load the font before opening so the grid uses its measured geometry.

Compare performance on your workload

The benchmark report records the environments, methods, renderer-specific results and losses. Compare WebGL with WebGL and DOM with DOM. Input latency, Unicode output and scrolling are separate workloads.

Next steps

Connect your PTY, apply a theme and check the worker boundaries before moving your host off the main thread.