Field	Type	Description
`linkUri`	`string?`	The resolved URI attached to this cell
`linkId`	`string?`	The explicit OSC 8 `id=` parameter, when provided
`linkKey`	`string?`	An opaque semantic identity used by renderers to group linked cells. Consumers must not interpret its contents.

Method	Description
`getRowMetadata?(row)`	Read a zero-based live row in the active screen.
`getScrollbackRowMetadata?(offset)`	Read retained history; offset zero is the newest row, directly above the live screen.

Field	Type	Description
`wrapsToNext`	`boolean`	The following row continues this logical line without an explicit newline. Merely filling the last column does not set this flag.
`continuesPrevious`	`boolean`	This row continues the preceding row, which may already have been discarded from history.

Type	Key fields	Meaning
`TerminalImageDescriptor`	`imageId` , `version` , `width` , `height`	Intrinsic image metadata. A new version replaces the prior pixels.
`TerminalImagePlacement`	`row` , `col` , offsets, source rectangle, cell size, `z`	Pinned placement in the retained active screen. Row zero is the oldest retained row; coordinates are top-left based.
`TerminalImageData`	`rgba: Uint8Array`	Copied row-major RGBA pixels. Invalid or unavailable data returns `null` .

Option	Type	Default	Description
`cols`	`number`	`80`	Initial column count. Vanilla auto-resizing measures omitted dimensions before initialization; 80 is the fallback.
`rows`	`number`	`24`	Initial row count. Vanilla auto-resizing measures omitted dimensions before initialization; 24 is the fallback.
`core`	`TerminalCore`	—	A pre-constructed terminal core instance. When provided, `wasmUrl` is ignored and this core is used instead of loading the built-in Zig WASM binary. See Ghostty Core for an example.
`wasmUrl`	`string`	—	URL to serve the WASM binary separately. When omitted, the \~49 KB binary is decoded from an inlined base64 string. Ignored when `core` is provided.
`autoResize`	`boolean`	`true` (vanilla) / `false` (React, Vue, Svelte)	Automatically resize the terminal to fit its container using a `ResizeObserver`
`maxImageWidth`	`number`	—	Maximum rendered Kitty image width in CSS pixels. Images are scaled down proportionally and are never enlarged.
`maxImageHeight`	`number`	—	Maximum rendered Kitty image height in CSS pixels. Images are scaled down proportionally and are never enlarged.
`cursorBlink`	`boolean`	Application-controlled	Force blinking on ( `true` ) or off ( `false` ); omit to follow the terminal (initially steady).
`announceOutput`	`boolean`	`false`	Politely announce bounded text changes while terminal input has focus. Mutable in all framework bindings.
`debug`	`boolean`	`false`	Enable debug mode. Exposes a `DebugAdapter` on the `WTerm` instance ( `wt.debug` ) for inspecting escape sequences, cell data, render performance, and unhandled CSI sequences.
`scrollbackLines`	`number`	core default	Lines of history the core keeps; older lines are dropped. The built-in and Ghostty cores keep 1,000 by default. Mutable in all framework bindings.
`renderingPaused`	`boolean`	`false`	Suspend painting for an inactive pane. Parsing, replies, titles, bells, and core resizing continue. Mutable in all framework bindings; see Inactive panes .
`renderer`	`"dom" \| "webgl"`	`"dom"`	Paint live output with WebGL2. DOM text stays current for selection, search, and accessibility. Falls back to `"dom"` without WebGL2. Fixed at mount; see WebGL renderer .	`webmcp`	`false`	Let in-page agents list, read, and type into the terminal through WebMCP. Mutable in all framework bindings; see WebMCP .
`onData`	`(data: string) => void`	—	Called when the terminal produces data (user input or host response). When omitted, input is echoed back automatically.
`onBinary`	`(data: Uint8Array) => void`	—	Called with raw X10 mouse reports when supplied. Forward the bytes unchanged to a binary-capable transport; without it, only ASCII-safe X10 reports reach `onData` .
`onTitle`	`(title: string) => void`	—	Called when the terminal title changes via an escape sequence
`onBell`	`(count: number) => void`	—	Called as output is written with the number of pending BEL controls. The host decides whether to play sound or show a visual alert.
`onClipboardWrite`	`(text: string) => void`	—	Application clipboard-write request from Ghostty. No clipboard access is automatic; see Clipboard requests .
`onShellIntegration`	`(state: ShellIntegrationState) => void`	—	Latest shell-reported prompt, input, running, or completion state. Ghostty with OSC 133; see Shell integration .
`onWorkingDirectory`	`(uri: string) => void`	—	Raw shell-reported OSC 7 URI from Ghostty; empty clears it. Treat as untrusted metadata. See Working directories .
`onResize`	`(cols: number, rows: number) => void`	—	Called with the grid dimensions applied by the core after resize or when initialization changes the requested size. Use these values when resizing a connected PTY.

Prop	Type	Description
`theme`	`string`	Name of a built-in or custom theme (see Themes )
`onReady`	`(wt: WTerm) => void`	Called with the underlying `WTerm` instance after WASM loads and initialization completes
`onError`	`(error: unknown) => void`	Called if WASM loading or initialization fails. When omitted, errors are logged to the console.

Prop	Type	Description
`theme`	`string`	Name of a built-in or custom theme (see Themes ). Applied as a `class on the root element.`

Event	Payload	Description
`data`	`(data: string)`	Emitted when the terminal produces data (user input or host response). When no listener is attached, input is echoed back automatically.
`binary`	`(data: Uint8Array)`	Emitted with raw X10 mouse reports for a binary-capable transport.
`title`	`(title: string)`	Emitted when the terminal title changes via an escape sequence.
`bell`	`(count: number)`	Emitted as output is written with the number of pending BEL controls.
`clipboardWrite`	`(text: string)`	Application clipboard-write request from Ghostty. No clipboard access is automatic; see Clipboard requests .
`shellIntegration`	`(state: ShellIntegrationState)`	Latest shell state from Ghostty. Use `@shell-integration` ; see Shell integration .
`workingDirectory`	`(uri: string)`	Raw OSC 7 URI from Ghostty; empty clears it. Use `@working-directory` ; see Working directories .
`resize`	`(cols: number, rows: number)`	Emitted after the terminal is resized.
`ready`	`(wt: WTerm)`	Emitted once after `WTerm.init()` resolves, carrying the underlying `WTerm` instance.
`error`	`(err: unknown)`	Emitted if WASM loading or initialization fails.

Prop	Type	Description
`theme`	`string`	Name of a built-in or custom theme (see Themes ). Applied as a `class.`
`onData`	`(data: string) => void`	Called for terminal input and host responses. When omitted, input is echoed automatically.
`onBinary`	`(data: Uint8Array) => void`	Called with raw X10 mouse reports for a binary-capable transport.
`onTitle`	`(title: string) => void`	Called when the terminal title changes.
`onBell`	`(count: number) => void`	Called with the pending BEL count as output is written.
`onClipboardWrite`	`(text: string) => void`	Application clipboard-write request from Ghostty. No clipboard access is automatic; see Clipboard requests .
`onShellIntegration`	`(state: ShellIntegrationState) => void`	Latest shell-reported prompt, input, running, or completion state. Ghostty with OSC 133; see Shell integration .
`onWorkingDirectory`	`(uri: string) => void`	Raw OSC 7 URI from Ghostty; empty clears it. Also accepts `onworkingdirectory` ; see Working directories .
`onResize`	`(cols: number, rows: number) => void`	Called after the terminal is resized.
`onReady`	`(wt: WTerm) => void`	Called after WASM loads and initialization completes.
`onError`	`(error: unknown) => void`	Called if WASM loading or initialization fails.

Method	Description
	Load WASM and start rendering
`setThemeColors(colors: TerminalThemeColors \| null): void`	Update host CSS and supported core defaults without parsing input; `null` returns to the CSS theme. See Updating host colors
`write(data: string \| Uint8Array)`	Write data to the terminal
`resize(cols, rows)`	Request a grid size; read `wt.cols` and `wt.rows` afterward for the applied size
`focus()`	Focus the terminal input
`setOutputAnnouncements(enabled)`	Enable or stop polite output announcements without changing focus
`setScrollbackLines(lines)`	Change how many lines of history the core keeps, dropping the oldest. Throws when the core cannot change it.
`setRenderingPaused(paused)`	Pause pane painting or schedule the latest state when resuming. Browser document visibility also gates painting.
`setWebMCP(options)`	Expose the terminal to in-page agents with `true` or WebMCP options , or withdraw it with `false` . Unchanged options are a no-op.
`destroy()`	Clean up event listeners, observers, and DOM
`search(query, options?)`	Start cancellable plain-text search across retained history and the active screen
`findNext()` / `findPrevious()`	Reveal a match with wraparound; return false if there are no matches
`fit(): void`	Resize the grid to the current element content box and font metrics. Hidden or uninitialized terminals stay unchanged. Uses the usual resize callback.
`scrollToPrompt(direction: -1 \| 1): boolean`	Scroll from the viewport top to the previous or next shell prompt without wrapping. Returns whether scrolling moved. Requires Ghostty with OSC 133; see Shell integration for limits and inactive states.
`getSearchState()` / `clearSearch()`	Read a state snapshot, or cancel search and remove highlights
`getSelectionText(): string \| null`	Read selected text with terminal line and cell semantics, or null when unavailable
	Capture retained history and the active screen without changing selection. Accepts an optional `signal` ; see Reading Terminal Output for cancellation and limits.
	Select retained history and the active screen; resolve true when the complete text is ready
`clearSelection(): void`	Clear custom selection and a native selection wholly inside this terminal
`selectWord(position): boolean`	Select the word at a retained-buffer cell, including confirmed soft wraps
`selectLine(row): boolean`	Select the complete logical line containing a retained-buffer row
`selectRectangle(start, end): boolean`	Select inclusive column and row bounds, preserving spaces and physical line breaks

Return	Type	Description
`ref`		Pass to
`write`	`(data: string \| Uint8Array) => void`	Write data to the terminal
`resize`	`(cols: number, rows: number) => void`	Resize the terminal grid
`focus`	`() => void`	Focus the terminal input

Member	Type	Description
`write`	`(data: string \| Uint8Array) => void`	Write data to the terminal. Safe to call after the `ready` event; calls before mount are ignored.
`resize`	`(cols: number, rows: number) => void`	Resize the terminal grid. Calls before mount are ignored.
`focus`	`() => void`	Focus the terminal input.
`instance`	`WTerm \| null`	Underlying `WTerm` instance. `null` until the component has mounted; the WASM bridge is only available after the `ready` event.

Member	Type	Description
`write`	`(data: string \| Uint8Array) => void`	Write data to the terminal. Calls before initialization are ignored.
`resize`	`(cols: number, rows: number) => void`	Resize the terminal grid.
`focus`	`() => void`	Focus the terminal input.

Option	Type	Default	Description
`url`	`string`	—	WebSocket server URL
`reconnect`	`boolean`	`true`	Automatically reconnect on disconnect with exponential backoff
`maxReconnectDelay`	`number`	`30000`	Maximum delay between reconnection attempts (ms)
`maxBufferedBytes`	`number`	`1048576`	Maximum queued bytes, including the current open socket's buffered amount. Positive safe integer.
`maxBufferedMessages`	`number`	`1024`	Maximum messages waiting in the transport queue, including empty messages. Positive safe integer.
`highWaterMark`	`number`	`65536`	Byte threshold for pausing socket writes and reporting pressure. Defaults to the smaller of 64 KiB and the byte cap.
`lowWaterMark`	`number`	`16384`	Resume socket writes at or below this threshold. Defaults to one quarter of the high-water mark.
`onBackpressure`	`(paused: boolean) => void`	—	Called on pressure transitions. Pause producers while true and resume when false.
`onData`	`(data: Uint8Array \| string) => void`	—	Called when data is received from the server
`onOpen`	`() => void`	—	Called when the connection opens
`onClose`	`() => void`	—	Called when the connection closes
`onError`	`(event: Event) => void`	—	Called when a WebSocket error occurs

Method	Description
`connect(url?)`	Open the WebSocket connection. Same-URL calls while connecting/open do nothing. Changing the URL discards unsent data.
`send(data: string \| Uint8Array)`	Accept a complete message for ordered delivery. Throws RangeError before accepting it if either buffer limit would be exceeded. Throws after explicit close until connect is called again.
`close()`	Close the connection, discard unsent data, and stop reconnect and drain timers.

Property	Type	Description
`connected`	`boolean`	Whether the WebSocket is currently open
`bufferedAmount`	`number`	Bytes in the transport queue plus the current open socket's send buffer.
`queuedBytes` / `queuedMessages`	`number`	Bytes/messages not yet handed to the browser socket.
`backpressured`	`boolean`	Whether producers should pause. Clears when buffered bytes reach the low-water mark and the message queue has room.

Method	Description
	Load the WASM binary and return a new bridge instance
`init(cols, rows)`	Initialize the terminal grid
`writeString(str, afterChunk?)`	Write a UTF-8 string and optionally run a callback after each internal chunk
`writeRaw(data, afterChunk?)`	Write raw bytes and optionally run a callback after each 8192-byte internal chunk
`resize(cols, rows)`	Resize the terminal grid
`getCell(row, col): CellData`	Get cell data at a grid position
`getCursor(): CursorState`	Get current cursor position and visibility
`getCols() / getRows()`	Get current grid dimensions
`isDirtyRow(row): boolean`	Check if a row has changed since last `clearDirty()`
`getRowId(row): number \| null`	Optional. Live row identity that follows scrolling; null when unavailable
`isRowContentDirty(row): boolean`	Optional. Whether the row's content changed since `clearDirty()` , ignoring movement
`clearDirty()`	Reset all dirty-row flags
`getTitle(): string \| null`	Get pending title change (via OSC escape), or `null` if unchanged
`getWorkingDirectory?(): string \| null`	Consume a raw OSC 7 URI from a supporting core. Empty clears it; null means unchanged or unsupported. See Working directories .
`getBellCount?(): number`	Read and clear pending BEL controls. Optional for custom cores; the built-in and Ghostty cores return `0` when none are pending.
`getShellIntegrationState?(): ShellIntegrationState \| null`	Consume the latest shell-reported state change. The caller-owned snapshot has phase and exitCode; null means unchanged or unsupported. See Shell integration .
`findPrompt?(row: number, direction: -1 \| 1): number \| null`	Optional Ghostty lookup for the previous/next prompt start. Row zero is the oldest retained row; the origin must be in range. Skips continuation rows when moving forwards and returns null for unsupported cores, alternate screens, invalid inputs, or missing prompts. Does not move the cursor or consume shell state.
`getClipboardWrite?(): string \| null`	Consume the latest application clipboard-write request. Empty text requests a clear; null means none. Ghostty only; the host owns acceptance.
`getResponse(): string \| null`	Dequeue one pending host response (e.g. DSR), or `null` .
`getResourceState?(): TerminalResourceState`	Get optional core resource state. The built-in core reports hyperlink identity capacity, usage, capacity-rejected opens, and saturation.
`getScrollbackCount(): number`	Number of lines in the scrollback buffer
`getScrollbackDiscardedCount?(): number`	Cumulative rows discarded from the oldest end. Optional for third-party cores; WTerm uses it to preserve history position through rollover.
`setScrollbackLines?(lines): void`	Keep this many lines of history, dropping the oldest. Optional for third-party cores; required by the `scrollbackLines` option.
`getScrollbackCell(offset, col): CellData`	Get cell data from a scrollback line
`getScrollbackLineLen(offset): number`	Get the length of a scrollback line
`cursorKeysApp(): boolean`	Whether cursor keys are in application mode
`bracketedPaste(): boolean`	Whether bracketed paste mode is active
`usingAltScreen(): boolean`	Whether the alternate screen buffer is active
`mouseTracking(): number`	Active mouse tracking mode ( `0` , `1000` , `1002` , or `1003` )
`mouseSgr(): boolean`	Whether cell-coordinate SGR mouse encoding (mode 1006) is active
`mouseEncoding(): MouseEncoding \| null`	Active mouse wire format: `x10` , `utf8` , `sgr` , `urxvt` , or `sgr-pixels` . Optional for custom cores. The DOM layer sends all five formats; `sgr-pixels` uses 1-based CSS-pixel coordinates.
`focusEvents(): boolean`	Whether focus reporting (mode 1004) is active
`synchronizedOutput(): boolean`	Whether synchronized output mode (2026) is active
`synchronizedOutputGeneration(): number`	Monotonic generation for synchronized output blocks
`kittyKeyboardFlags?(): number`	Active Kitty keyboard protocol flags. Optional for third-party cores; omission keeps legacy keyboard encoding.
`modifyOtherKeys?(): 0 \| 2`	2 while xterm modifyOtherKeys level 2 is active. Optional for third-party cores; omission keeps legacy keyboard encoding.

Marker	Phase	Exit code
OSC 133 A, N, or P	`prompt`	Retains the previous result
OSC 133 B or I	`input`	Retains the previous result
OSC 133 C	`running`	Cleared to `null`
OSC 133 D	`complete`	Signed 32-bit code, or `null` if missing or invalid
Terminal reset (RIS)	`unknown`	Cleared to `null`

` via the default `inheritAttrs` behavior. See [Vue-Only Props](/api-reference#vue-only-props) and [Vue Events](/api-reference#vue-events) for details. ### Svelte-only The Svelte `Terminal` component adds the `theme` prop and forwards standard `

` attributes such as `class`, `style`, `id`, and ARIA attributes. Svelte 5 applications can use the `onData`, `onTitle`, `onBell`, `onClipboardWrite`, `onShellIntegration`, `onWorkingDirectory`, `onResize`, `onReady`, and `onError` callback props. See [Svelte-only Props](/api-reference#svelte-only-props) for details. ## Imperative Handle (React) When using `useTerminal`, the returned ref exposes an imperative handle: ```tsx import { Terminal, useTerminal } from "@wterm/react"; function App() { const { ref } = useTerminal(); return ( { wt.resize(120, 40); }} /> ); } ``` See the full [Imperative Handle](/api-reference#imperative-handle-react) reference for all returned methods. ## Template Ref (Vue) Access imperative methods on the Vue component via a template ref: ```vue ``` See the full [Template Ref (Vue)](/api-reference#template-ref-vue) reference for all exposed methods. ## Imperative Handle (Svelte) Bind the Svelte component instance to call its imperative methods: ```svelte ``` See the full [Imperative Handle (Svelte)](/api-reference#imperative-handle-svelte) reference for all exposed methods. ## WebSocket Transport For connecting to a remote shell over WebSocket, use the built-in `WebSocketTransport`: ```ts import { WTerm, WebSocketTransport } from "@wterm/dom"; const ws = new WebSocketTransport({ url: "wss://your-server.example/shell", reconnect: true, maxReconnectDelay: 5000, onBackpressure(paused) { console.log(paused ? "Waiting for the connection to drain" : "Send buffer ready"); }, onData(data) { term.write(data); }, onOpen() { console.log("connected"); }, onClose() { console.log("disconnected"); }, }); const term = new WTerm(document.getElementById("terminal"), { onData(data) { try { ws.send(data); } catch (error) { console.error("Input was not sent", error); // Show this in your app's UI. } }, }); await term.init(); ws.connect(); ``` See the full [WebSocketTransport](/api-reference#websockettransport) reference for all options, methods, and properties. The transport buffers sends within configurable byte/message limits and drains them in order. The defaults are 1 MiB across the transport and socket buffers, and 1,024 messages waiting in the transport. Use `onBackpressure` to pause producers and catch `RangeError` to report input that exceeded a limit. Explicit `close()` discards unsent data; reconnect never replays bytes already handed to the browser. See [Buffering and delivery](/api-reference#buffering-and-delivery) for thresholds, lifecycle behavior, and delivery limits. ### Local split panes The [local example](https://github.com/vercel-labs/wterm/tree/main/examples/local) can display up to four shells using **Split right** and **Split down**. Drag a divider, or focus it and use arrow keys, to resize. Home/End move to its bounds; Enter centers it. Panes retain at least 320×220 CSS pixels, with workspace scrolling when needed. Each shell receives its own updated dimensions. Click a terminal to focus it. Command+Option+arrows on macOS or Control+Alt+arrows move from terminal input to the adjacent pane. Find and dialog text fields retain their keyboard behavior. Only the focused terminal receives keyboard input; all visible panes continue rendering. Selecting a hidden sidebar session replaces the focused pane without closing its shell. **Zoom pane** and **Restore panes** temporarily hide and restore the other panes. Closing a session collapses its split while other sessions keep their terminal state and connections. Layout changes preserve history and per-session Find queries. Reloading restores nested splits, divider proportions, the focused terminal, and zoom, including the arrangement behind a zoomed pane. Smaller windows retain the arrangement with minimum pane sizes and workspace scrolling. Hidden sessions remain accessible in the sidebar. ### Local workspace recovery The [local example](https://github.com/vercel-labs/wterm/tree/main/examples/local) uses a paired client/server protocol to resume the same shell after a brief connection interruption. It preserves the existing page's terminal state and replays only output the terminal has not parsed. Detached PTYs pause, retained output stays bounded, and the server expires detached sessions after 30 seconds. The browser retries for up to 25 seconds after detecting an interruption. Input during reconnection is rejected visibly. Sequenced input is acknowledged after the server hands it to the PTY; duplicate accepted messages are ignored. The browser limits unacknowledged input to 64 KiB and 1,024 messages, and keeps only message lengths for tracking. Reattachment confirms the accepted prefix even if an acknowledgment was lost. If any input was not delivered, the workspace reports it and asks you to check the command line before continuing. If recovery fails, unconfirmed delivery remains visible. Input is never retried automatically. An acknowledgment confirms PTY acceptance, not command execution or completion. Reloading the page can restore saved terminal tabs and reconnect to their same shells. The workspace stores exact output, resize and theme events, attachment credentials, and input sequence counters in tab-scoped `sessionStorage`, separately for each engine route. A fresh terminal replays that complete prefix before reattaching; historical replies and clipboard requests are suppressed. Saved output may contain sensitive text and echoed commands. Closing a session removes its records, and closing the browser tab removes its session storage. Pane layout is stored separately in the same tab and engine route. Only sessions in the recovery registry can appear in the restored layout; closed sessions stay closed. Missing, stale, or malformed layout records fall back to a single pane with the first saved session selected. A layout storage failure shows a status without disabling terminal replay or interrupting live input and output. Replay records are capped at 1 MiB of output and 4,096 events per session, subject to browser storage quotas. A limit or storage failure disables refresh recovery with a visible status while the live terminal continues. Invalid or incomplete records, an expired session, an unavailable output range, or a server restart produce an explicit failure without starting a replacement shell. Reload must reattach within the 30-second server grace period. Find queries are not restored; normal navigation and duplicated tabs start independently. This behavior belongs to the local example, not `WebSocketTransport` alone. ## WebMCP Set `webmcp` to `true`, or to `{ name, description, readOnly }`, to let in-page agents list, read, and type into the terminal through [WebMCP](/webmcp). It is off by default and does nothing in browsers without a WebMCP provider. Use `readOnly: true` for terminals agents should only watch. ## Output announcements Opt in with `announceOutput` to announce terminal text changes politely while input has focus. The option defaults to `false`; component prop changes apply without restarting the terminal, and vanilla callers use `term.setOutputAnnouncements(enabled)`. Announcements are batched and stop when focus leaves input. Bursts are bounded to avoid overwhelming the speech queue. See [Output announcements](/api-reference#output-announcements) for capture limits, pause/resume behavior, and redraw semantics. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Core / Advanced url: "https://wterm.dev/core" docs_index: /llms.txt lastUpdated: 2026-11-06 navTitle: "Core / Advanced" --- > For an index of all documentation, see [/llms.txt](/llms.txt). `@wterm/core` provides the headless terminal engine and WebSocket transport. Use it when you need direct access to the WASM bridge for a custom renderer, headless testing, or a server-connected terminal without the DOM layer. With `@wterm/dom`, terminal applications can enable mouse tracking (modes 1000, 1002, and 1003) in X10, UTF-8 (1005), SGR (1006), urxvt (1015), or SGR pixel (1016) encoding, plus focus reporting (mode 1004). UTF-8, SGR, urxvt, SGR pixel, and focus reports reach `onData`; raw X10 reports reach `onBinary` when provided. SGR pixel reports use 1-based CSS pixels relative to the visible grid. Mode 1003 reports unpressed pointer motion once per cell in cell formats and once per CSS pixel in 1016. ## Install ```bash npm install @wterm/core ``` ## WasmBridge Low-level interface to the Zig/WASM terminal state machine. The bridge manages a virtual terminal grid in WASM memory — you write data in and read cells, cursor state, and scrollback out. ### Loading ```ts import { WasmBridge } from "@wterm/core"; // Use the embedded WASM binary (default, zero-config) const bridge = await WasmBridge.load(); // Or fetch from a URL (useful for CDN caching) const bridge = await WasmBridge.load("/wterm.wasm"); ``` When no URL is provided, the \~49 KB WASM binary is decoded from a base64 string inlined in the package. Pass a URL when you want to serve the binary separately for caching or CDN use. The grid grows as needed, up to 1024 columns and 512 rows. See the full [WasmBridge](/api-reference#wasmbridge) reference for all methods, types, and scrollback APIs. The built-in core answers DEC private-mode status queries through `getResponse()`. For example, `\x1b[?2026$p` receives `\x1b[?2026;2$y` when synchronized output is off and `\x1b[?2026;1$y` when it is on. It also reports supported mouse, focus, cursor, bracketed-paste, and alternate-screen modes; unrecognized modes return status `0`. Drain responses and send them back to a connected application. `WTerm` does this through `onData`. The built-in core also answers primary device-attributes queries (`CSI c`, including `CSI 0 c`) with `\x1b[?1;2c`, identifying VT100 advanced-video support. It does not claim secondary or private device attributes. Operating-status queries (`CSI 5 n`) receive `\x1b[0n` when the built-in core is ready. Cursor-position queries (`CSI 6 n`) receive `\x1b[row;colR`. These replies share the `getResponse()` queue with device-attribute replies and preserve query order; unsupported or malformed status requests receive no reply. `getBellCount()` reads and clears pending BEL controls. A BEL used to terminate an OSC sequence does not count. The DOM wrapper forwards the count through `onBell`, leaving the alert behavior to the host. ### Example Headless usage — load the bridge, write data, and read cells back: ```ts import { WasmBridge } from "@wterm/core"; const bridge = await WasmBridge.load(); bridge.init(80, 24); bridge.writeString("Hello, world!\r\n"); bridge.writeString("\x1b[1;31mRed bold text\x1b[0m"); for (let col = 0; col < 13; col++) { const cell = bridge.getCell(0, col); process.stdout.write(String.fromCodePoint(cell.char)); } // → "Hello, world!" const cursor = bridge.getCursor(); // → { row: 1, col: 13, visible: true } ``` Wide single-codepoint characters such as CJK, fullwidth forms, and emoji expose `width: 2` on the leading cell and `width: 0` on the continuation cell. Custom renderers should skip continuation cells. The built-in core also implements the optional `getRowId(row)` and `isRowContentDirty(row)` methods, which let the DOM renderer reuse rows that only scrolled. Custom cores can omit them. Character insertion (`ICH`) and deletion (`DCH`) shift exactly the requested number of columns from the cursor, up to the right edge. If an edit splits a wide character, its remaining cells become spaces with the current background color. With automatic wrapping disabled (`CSI ? 7 l`), a wide character that cannot fit at the right edge leaves the row unchanged. In a one-column terminal, wide characters are consumed as spaces with normal cursor and wrapping behavior. Cores that preserve multi-codepoint graphemes expose the complete string as `chars`. Render `chars` when present and fall back to `String.fromCodePoint(char)` otherwise. ### DEC line drawing The built-in core translates DEC Special Graphics sequences used by tmux and other TUIs into Unicode cells. For example: ```ts bridge.writeString("\x1b(0lqqk\x1b(B"); // ┌──┐ ``` `ESC (` through `ESC +` designate G0 through G3. The supported sets are ASCII (`B`), British (`A`, mapping `#` to `£`), and DEC Special Graphics (`0`). SI/SO select G0/G1; `ESC n` and `ESC o` select G2/G3. `ESC N` and `ESC O` use G2/G3 for the next printed character only. Unsupported designations are ignored. Character-set state is preserved by cursor save/restore and restored when returning from the alternate screen with `CSI ? 1049 l`. Soft and full resets restore the built-in core's default ASCII sets. Mapping changes printable ASCII only; UTF-8 text keeps its original codepoints. Custom renderers receive the translated Unicode characters through `getCell()` and `getScrollbackCell()`. ### Optional terminal graphics The `TerminalCore` contract has optional `getGraphicsState()` and `getGraphicsImage()` methods. A graphics provider returns copied metadata and tightly packed RGBA pixels for direct terminal images, along with pinned placements in retained-row coordinates. Existing cores remain compatible when these methods are absent. The built-in `WasmBridge` consumes unsupported 7-bit Kitty APC payloads safely but does not decode or advertise image data; use the Ghostty core for rendering Kitty PNG/RGB/RGBA output. ## WebSocketTransport Connect to a PTY backend over WebSocket with automatic reconnection and bounded send buffering. Defaults allow 1 MiB across the transport and socket buffers and 1,024 queued messages. `onBackpressure` reports when producers should pause; `send()` throws `RangeError` before accepting a message that would exceed a limit. Report that rejected input to the user. Explicit close discards unsent data, and bytes already handed to the socket are never replayed. See the full [WebSocketTransport](/api-reference#websockettransport) reference for all options, methods, and properties. ### Example Connecting a terminal to a remote shell via WebSocket: ```ts import { WTerm, WebSocketTransport } from "@wterm/dom"; import "@wterm/dom/css"; const term = new WTerm(document.getElementById("terminal"), { cols: 80, rows: 24, }); await term.init(); const ws = new WebSocketTransport({ url: "ws://localhost:8080/pty", onData: (data) => term.write(data), onOpen: () => console.log("connected"), onClose: () => console.log("disconnected"), }); ws.connect(); term.onData = (data) => { try { ws.send(data); } catch (error) { console.error("Input was not sent", error); // Show this in your app's UI. } }; ``` For a full working example with a Node.js PTY server, see the [Local Shell example](https://github.com/vercel-labs/wterm/tree/main/examples/local). It uses its own client/server protocol: binary PTY output plus JSON input, resize, and consumption acknowledgments. A bounded output window pauses the PTY when the browser falls behind, and parsing yields between batches. Small PTY reads are collected into frames up to 16 KiB using a four-millisecond timer, reducing WebSocket message overhead during output bursts. Full frames can send immediately when credit is available; normal exit drains the final batch. Collecting bytes remain subject to the same queue limits. The workspace reports rejected input and connection failures. This protocol requires both halves of the example; it is not built into `WebSocketTransport`. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Get Started url: "https://wterm.dev/get-started" docs_index: /llms.txt lastUpdated: 2026-11-06 navTitle: "Get Started" --- > For an index of all documentation, see [/llms.txt](/llms.txt). ## Install ### React ```bash npm install @wterm/dom @wterm/react ``` ### Vue ```bash npm install @wterm/dom @wterm/vue ``` ### Svelte ```bash npm install @wterm/dom @wterm/svelte svelte ``` ### Vanilla JS ```bash npm install @wterm/dom ``` The WASM binary is embedded in the package — no extra setup required. It is decoded and compiled once per copy of `@wterm/core`, including concurrent loads. Each terminal still gets its own instance and memory. ## Quick Start ### React ```tsx import { Terminal } from "@wterm/react"; import "@wterm/react/css"; function App() { return ; } ``` ### Vue ```vue ``` ### Svelte ```svelte ``` ### Vanilla JS ```js import { WTerm } from "@wterm/dom"; import "@wterm/dom/css"; const term = new WTerm(document.getElementById("terminal")); await term.init(); ``` ## Serving WASM separately By default the \~49 KB WASM binary is embedded in the package and imported when the built-in core is first loaded. Bundlers with code splitting emit it in a separate JavaScript chunk, so deploy all emitted application assets. Ghostty and custom `wasmUrl` loads do not request that chunk. To serve it as a separate static file instead (for caching or CDN), copy it from the package and pass `wasmUrl`: ```bash cp node_modules/@wterm/core/wasm/wterm.wasm public/wterm.wasm ``` ```tsx ``` Loads of the same resolved URL share the download and compiled module. The built-in loader retains up to four recently used URLs per copy of `@wterm/core` in a page or worker, separately from its embedded module. Failed downloads and compilations can be retried. Use versioned or hashed URLs when updating the binary; cached modules remain until eviction or page/worker reload. Serve `Content-Type: application/wasm` to compile during download in supported browsers. Other MIME types, unavailable streaming, or streaming failures fall back to buffered compilation without fetching the file again. ## Building the WASM Binary Requires [Zig](https://ziglang.org/) 0.16.0 ```bash zig build -Doptimize=ReleaseSmall ``` The build writes `zig-out/bin/wterm.wasm` and `web/wterm.wasm`. The packages ship `packages/@wterm/core/wasm/wterm.wasm`. Copy the build there, then run `pnpm --filter @wterm/core build` to regenerate the embedded binary that loads when `wasmUrl` is not set. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Ghostty Core url: "https://wterm.dev/ghostty" docs_index: /llms.txt lastUpdated: 2026-11-08 navTitle: "Ghostty Core" --- > For an index of all documentation, see [/llms.txt](/llms.txt). The `@wterm/ghostty` package provides a full-featured terminal emulation core powered by [libghostty](https://ghostty.org) built directly from upstream source. It implements the same `TerminalCore` interface as wterm's built-in Zig core, so it's a drop-in replacement. When your bundler supports code splitting, Ghostty-backed terminals do not download the built-in core's embedded binary. ## Why use it? wterm ships with a lightweight built-in core (\~49 KB WASM) that covers basic VT100/VT220/xterm escape sequences. For apps that need comprehensive terminal emulation — full Unicode grapheme clusters, all SGR attributes, terminal modes, and more — `@wterm/ghostty` provides all of that via Ghostty's battle-tested VT parser. Ghostty's native OSC 8 metadata is preserved through the active viewport, scrollback, and reflow. The DOM renderer resolves it into safe HTTP and HTTPS anchors without exposing Ghostty's page-local numeric IDs. Ghostty allocates terminal pages as needed, reducing initial memory use for idle terminals and alternate screens. The configured history budget still controls retained output. Freed pages can be reused, but WebAssembly linear memory does not shrink after clearing history or resetting a screen. `getColorOverrides()` exposes application-requested default foreground, background, and cursor colors from OSC 10/11/12. The DOM renderer applies them to live cells, retained history, the terminal background, and cursor shapes. OSC 110/111/112 restores the current CSS theme without rewriting host theme variables. Explicit SGR colors remain unchanged. Serve the current WASM binary; older binaries return an empty snapshot and retain their CSS defaults. Ghostty preserves single, double, curly, dotted, and dashed underlines through `CellData.underlineStyle`, with resolved colors in `underlineRgb`. The DOM renderer displays them in the viewport and scrollback, including after reflow. SGR `4:1` through `4:5` select the styles; `4` selects single and `21` selects double. SGR `58` sets an indexed or RGB underline color, `59` restores the foreground color, and `24` or `4:0` removes the underline. SGR `0` resets both. Strikethrough stays solid and follows the text color. Apps serving an older WASM file retain single underlines; serve the binary shipped with the package to enable the additional styles and colors. Ghostty's cursor shape and blink state also reach the DOM renderer. Applications can switch between block, bar, and underline cursors; the wrapper's optional `cursorBlink` setting can force blinking on or off. See [cursor appearance](/configuration#cursor-appearance) for the shared behavior. Shells and applications can set the window title with OSC 0 or OSC 2. The Ghostty core forwards the latest complete title to `WTerm`'s `onTitle` callback, including an empty title that clears it. As with the built-in core, the callback runs as output is written, including while painting is paused. Several changes within a parsed chunk may coalesce to the latest complete title. Ghostty ignores titles longer than 255 bytes. BEL controls reach the shared `onBell(count)` callback as output is written. The BEL that terminates an OSC title does not count as a bell. With mouse tracking enabled, `mouseEncoding()` exposes Ghostty's active wire format. The DOM layer sends UTF-8 (1005), SGR (1006), urxvt (1015), and SGR pixel (1016) reports through `onData`; X10 reports use `onBinary` when provided. Mode 1003 sends unpressed pointer motion once per cell for cell formats and once per CSS pixel for 1016. Pixel coordinates are 1-based and relative to the visible grid. Ghostty-backed terminals also render direct Kitty Graphics Protocol PNG, RGB, and RGBA data through the optional graphics contract. The DOM layer draws bounded, transient canvas overlays for pinned placements and follows scrollback, resize, and primary/alternate screen changes. Non-direct media is rejected before file, shared-memory, or URL access; Sixel, iTerm2/OSC 1337, animation, virtual Unicode placements, and persistence are outside the supported boundary. The common auto-sized Kitty placement also reserves its rendered height in the visual DOM flow, keeping a following shell prompt below the image. ## Install ```bash npm install @wterm/ghostty ``` ## Usage Load the Ghostty core and pass it to `WTerm` via the `core` option. Everything else stays the same. ### Vanilla JS ```ts import { WTerm } from "@wterm/dom"; import { GhosttyCore } from "@wterm/ghostty"; import "@wterm/dom/css"; const core = await GhosttyCore.load(); const term = new WTerm(document.getElementById("terminal"), { core, onTitle(title) { document.title = title || "Terminal"; }, }); await term.init(); ``` ### React ```tsx import { Terminal } from "@wterm/react"; import { GhosttyCore } from "@wterm/ghostty"; import "@wterm/dom/css"; const core = await GhosttyCore.load(); function App() { return ; } ``` ### Vue ```vue ``` ### Svelte ```svelte {#if core} {/if} ``` For large Kitty images, pass display limits to the terminal wrapper. The limits are CSS pixels, preserve the image aspect ratio, and only scale images down: ```ts const term = new WTerm(document.getElementById("terminal"), { core, maxImageWidth: 640, maxImageHeight: 480, }); ``` The equivalent React, Vue, and Svelte props are `maxImageWidth` and `maxImageHeight`. `WTerm` answers Kitty's pixel geometry queries from the browser viewport, so direct image commands such as `kitten icat --transfer-mode=stream image.png` can negotiate their display size before transferring image data. The [local shell example](https://github.com/vercel-labs/wterm/tree/main/examples/local) forwards the browser's pixel dimensions to its PTY, so `kitten icat --detect-support` also works from that shell. ## Options `GhosttyCore.load()` accepts an optional options object:

Option	Type	Description
`wasmPath`	`string`	Custom path to the ghostty-vt WASM binary. By default it resolves to the committed binary inside the package.
`scrollbackLines`	`number`	Lines of history to keep (default: 1000). Ghostty stores history in pages, so up to a few pages of extra rows stay allocated but are not reported. History memory is capped at twice what plain text needs at the same width, so output dense with distinct colors, graphemes, or hyperlinks can keep fewer lines.
`scrollbackLimit`	`number`	Scrollback budget in bytes instead of lines. Ignored when `scrollbackLines` is set; the retained row count depends on the terminal width.
`foregroundColor`	`string`	Foreground reported by OSC 10 in `#RRGGBB` format. Defaults to `#d4d4d4`.
`backgroundColor`	`string`	Background reported by OSC 11 in `#RRGGBB` format. Defaults to `#1e1e1e`.
`imageStorageLimit`	`number`	Maximum decoded Kitty image bytes per screen (default: 32 MiB). Set to `0` to disable graphics. One image is capped at `MAX\_IMAGE\_BYTES` (32 MiB).

Pass colors matching your CSS theme so terminal applications receive the colors they are actually rendered with: ```ts const core = await GhosttyCore.load({ foregroundColor: "#ededed", backgroundColor: "#0a0a0a", imageStorageLimit: 32 * 1024 * 1024, }); ``` The core rejects malformed, oversized, and non-direct images before they can access a path or shared-memory segment. `getResourceState()` reports graphics bytes used/capacity, image and placement counts, rejection and eviction counters, and saturation. `GhosttyCore.dispose()` is idempotent and releases WASM resources when the application owns the core; `WTerm.destroy()` never disposes a caller-supplied core. The exported `MAX_IMAGE_BYTES` constant documents the hard per-image decoded byte cap. A larger `imageStorageLimit` is still useful for storing several smaller images. Each screen also retains at most 4,096 image descriptors and 4,096 placements; additional unique records fail closed so tiny-image churn cannot grow WASM metadata without bound. The DOM overlay independently caps visible canvas backing stores at 32 MiB and bounds each destination canvas to the terminal pixel area; placements that exceed those browser limits are skipped. ## Updating a running theme Use [`wt.setThemeColors(colors)`](/themes#updating-host-colors) to update browser colors and Ghostty defaults together without restarting the terminal. Headless hosts can call `core.setThemeColors(colors)` with the same `TerminalThemeColors` object. Application overrides and partial parser input are preserved; resets use the latest host defaults. Use the updated bundled WASM asset for this API. ## Bundlers Loads of the same resolved WASM URL share the download and compiled module, including concurrent calls. Each core still has its own instance and memory. The loader retains up to four recently used URLs per copy of the package in a page or worker; failed downloads and compilations can be retried. Use versioned or hashed URLs for new binaries because cached modules are not revalidated on each load. Serve the binary with `Content-Type: application/wasm` to compile while it downloads in supported browsers. Other MIME types or unavailable or failing streaming support fall back to buffered compilation without another fetch. The WASM binary is fetched at runtime rather than inlined, so the default has to resolve to a URL your app serves. `GhosttyCore.load()` resolves it with `new URL("../wasm/ghostty-vt.wasm", import.meta.url)`. Bundlers that implement that asset pattern emit the binary and rewrite the URL. Ones that do not leave `import.meta.url` pointing at the machine that built the bundle, and `load()` throws an error saying so.

Bundler	Default `GhosttyCore.load()`	Verified
Vite (dev and build)	Works, emits a hashed asset.	Yes
Bun dev server	Fails, pass `wasmPath`.	Yes
Others	Untested. Use `wasmPath` if the default throws.	No

When the default cannot work, serve the binary yourself and point at it: ```bash cp node_modules/@wterm/ghostty/wasm/ghostty-vt.wasm public/ghostty-vt.wasm ``` ```ts const core = await GhosttyCore.load({ wasmPath: "/ghostty-vt.wasm" }); ``` The binary is also addressable as `@wterm/ghostty/ghostty-vt.wasm`, so a bundler with a URL import can take it directly. ## How it works `@wterm/ghostty` builds libghostty directly from [ghostty-org/ghostty](https://github.com/ghostty-org/ghostty) source — no third-party npm packages or pre-built binaries from other projects. The architecture: 1. **Zig package dependency**: ghostty v1.3.1 is declared as a URL dependency in `zig/build.zig.zon`. Zig's package manager fetches it automatically. 2. **WASM compatibility patches**: ghostty's `Terminal` uses `posix.mmap` and Mach VM allocators internally, which don't exist on `wasm32-freestanding`. The build script applies small, targeted patches to replace these with `std.heap.wasm_allocator`, expose discarded scrollback rows, forward the per-screen Kitty image limit, bound and compact Kitty image/placement metadata, release tracked page pins during eviction, and make direct PNG decoding work without POSIX time. The patches touch `Terminal.zig`, `kitty/graphics_image.zig`, `kitty/graphics_storage.zig`, `kitty/graphics_exec.zig`, `kitty/graphics_unicode.zig`, `page.zig`, and `PageList.zig`; they also configure Wuffs with the freestanding compatibility headers and source flags in `zig/build.zig`. 3. **Thin WASM export layer**: `zig/src/wasm_api.zig` imports ghostty's `Terminal` and `RenderState` APIs and exports functions to JavaScript. 4. **Committed WASM binary**: The built `wasm/ghostty-vt.wasm` is checked into the repo so consumers never need Zig installed. 5. **TypeScript bindings**: `wasm-bindings.ts` loads the WASM module and provides typed accessors for the exported functions. 6. **TerminalCore adapter**: `ghostty-core.ts` implements the `TerminalCore` interface by calling the WASM bindings, converting ghostty's pre-resolved 24-bit RGB colors to wterm's `CellData` format via the `fgRgb`/`bgRgb` fields. The `TerminalCore` interface means the DOM renderer, input handler, and framework bindings don't need to know which core they're talking to. Ghostty enables grapheme clustering and returns combining sequences and ZWJ emoji through `CellData.chars`. The same complete strings are available from active cells and scrollback. `CellData.spacerHead` identifies empty right-edge filler before a wrapped wide glyph. [Terminal search](/api-reference#terminal-search) omits that filler and width-zero continuations, preserving real spaces and mapping grapheme matches to complete cells. [Selection and Copy](/api-reference#selection-and-copy) uses the same metadata to join soft wraps, omit filler cells, and preserve whole graphemes in copied text while retaining explicit newlines. Ghostty also supplies [tracked cell positions](/api-reference#tracked-cell-positions) through `trackPosition({ row, col })`. WTerm uses these to preserve native selections through output scrolling and reflow, clearing selections if their text changes or their positions become invalid. Serve the current WASM binary to enable tracking; older binaries return `null`. The adapter also reports how many rows Ghostty has discarded from the oldest end of its page-backed history. WTerm uses that count to keep retained rows anchored when the scrollback budget rolls over. For headless row reads, `getRowMetadata(row)` and `getScrollbackRowMetadata(offset)` expose native `wrapsToNext` and `continuesPrevious` flags. They distinguish automatic wrapping from explicit newlines across the live screen and retained history, including after reflow. Live row zero is the top of the screen; history offset zero is the newest retained row. Read metadata again after output, resize, or screen changes. Invalid positions, disposed cores, and older WASM binaries return `null`. See [Row Metadata](/api-reference#row-metadata) for the optional core contract. Terminal applications can query the Ghostty core's foreground and background colors with OSC 10 and OSC 11. Attached to `WTerm`, the core answers with the terminal's CSS theme colors (see [Color queries](/themes#color-queries)); headless, it starts with its configured colors. It tracks later OSC color changes and resets either way. Ghostty also exposes synchronized-output mode (`CSI ? 2026 h/l`) and its generation to the DOM renderer, so updates inside a synchronized block paint as one final frame. Kitty keyboard query and negotiation operate on Ghostty's native active-screen state. Primary and alternate screens have independent flag stacks, DECSTR preserves them, and RIS clears them. The DOM renderer reads those flags directly instead of maintaining a TypeScript shadow state. The bundled binary includes upstream's [WASM page-initialization fix](https://github.com/ghostty-org/ghostty/commit/420de124f04aa322bf250098cc62d7195db94bfd). New and replacement terminal pages are cleared before use, including release builds where the allocator may return memory used by earlier terminal state. If you serve the binary from a public directory, copy the updated package asset when upgrading. ## Application clipboard requests Ghostty exposes OSC 52 writes through `getClipboardWrite()` and WTerm's `onClipboardWrite(text)` callback. The host chooses whether to accept the text; no browser clipboard access is automatic. Reads are unsupported. Requests are limited to 65,536 decoded UTF-8 bytes, with bounded encoded accumulation and only one pending write. See [Clipboard requests](/configuration#clipboard-requests) for selectors, delivery behavior, and browser permission handling. Serve the updated bundled WASM to enable this optional effect. ## Rebuilding the WASM Only needed by maintainers. Requires [Zig 0.15.2](https://ziglang.org/download/), Bash, and Python 3. This is separate from the built-in core's Zig 0.16 toolchain. ```bash pnpm --filter @wterm/ghostty rebuild-wasm ``` Each build verifies the exact compiler version and upstream content hash, patches a fresh dependency tree, checks patch idempotence, and compiles in isolated caches under `/tmp`. Temporary files are removed on exit; the shared Zig cache is never read or patched. Set `WTERM_GHOSTTY_ZIG=/path/to/zig` to select a compiler explicitly. Zig 0.15.2 cannot link its native build runner on macOS 26. Use the Linux container build when the host toolchain cannot build: ```bash pnpm --filter @wterm/ghostty rebuild-wasm:docker ``` Docker and CI download the pinned compiler and verify its SHA-256 before extraction. Check the committed artifact without replacing it with: ```bash pnpm --filter @wterm/ghostty check-wasm # Linux container with a read-only checkout: pnpm --filter @wterm/ghostty check-wasm:docker ``` CI requires a byte-for-byte match on every PR and push to `main`. If it reports drift, rebuild and commit `packages/@wterm/ghostty/wasm/ghostty-vt.wasm` alongside the source changes. Consumers do not need Zig or Docker. ## Comparison

	Built-in (default)	`@wterm/ghostty`
WASM binary size	\~49 KB WASM (inlined)	\~580 KB WASM (fetched)
VT compliance	Basic VT100/VT220/xterm	Comprehensive
Unicode	Single codepoints with wide-cell support	Full grapheme clusters
Color model	256-color palette indices	Pre-resolved 24-bit RGB
Dependencies	None	None (WASM built from source)
Setup	Zero-config	Requires `@wterm/ghostty` install

## Shell integration OSC 7 directory reports reach `onWorkingDirectory(uri)`, or `GhosttyCore.getWorkingDirectory()` for headless consumers. Empty strings clear the value; `null` from the core means unchanged. See [Working directories](/configuration#working-directories) for URI handling, resource limits, shell setup, and workspace display behavior. With Ghostty and a shell emitting OSC 133, `onShellIntegration` receives the latest prompt, input, running, or completion state and the last reported exit code. Delivery continues while painting is paused; markers in one parser chunk coalesce into current state. See [Shell integration](/configuration#shell-integration) for the contract, shell setup, and workspace indicators. Use the underlying `WTerm` instance’s `scrollToPrompt(-1)` and `scrollToPrompt(1)` methods to navigate previous and next prompts in retained history. See [Shell integration](/configuration#shell-integration) for viewport behavior, unsupported cores, and inactive states. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: A terminal emulator for the web url: "https://wterm.dev/" docs_index: /llms.txt lastUpdated: 2026-11-04 navTitle: "Introduction" --- > For an index of all documentation, see [/llms.txt](/llms.txt).

wterm ("dub-term") renders to the DOM — native text selection, copy/paste, find, and accessibility come for free. Try the Ghostty-powered terminal below.

wterm ("dub-term") renders to the DOM — native text selection, copy/paste, find, and accessibility come for free. Try the Ghostty-powered terminal above.

The interactive example uses the Ghostty core and just-bash. See also: SSH, local.

## Features - **Pluggable cores** — a lightweight Zig/WASM core or Ghostty VT emulation for richer terminal compatibility - **DOM rendering** — native text selection, clipboard, browser find, screen reader support - **Native hyperlinks** — OSC 8 links remain attached to their exact cells through viewport and scrollback, with safe HTTP(S) anchors - **Dirty-row tracking** — only touched rows are re-rendered each frame via `requestAnimationFrame` - **Synchronized output** — mode 2026 blocks paint atomically with a bounded recovery deadline - **Themes** — CSS custom properties with built-in Default, Solarized Dark, Monokai, and Light themes - **Alternate screen buffer** — `vim`, `less`, `htop` work correctly - **Scrollback history** — configurable ring buffer - **Wide Unicode cells** — CJK, fullwidth, and emoji codepoints stay aligned during cursor-addressed redraws - **IME composition** — tentative text appears at the cursor; only committed text reaches the application - **24-bit color** — full RGB SGR support - **Framework bindings** — React, Vue 3, and Svelte components - **Auto-resize** — `ResizeObserver`-based terminal resizing - **WebSocket transport** — connect to a PTY backend with reconnection --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Just Bash url: "https://wterm.dev/just-bash" docs_index: /llms.txt lastUpdated: 2026-11-04 navTitle: "Just Bash" --- > For an index of all documentation, see [/llms.txt](/llms.txt). Shell adapter for wterm, powered by [just-bash](https://github.com/vercel-labs/just-bash). Provides line editing, tab completion, command history, and a colored prompt — all running in the browser with no backend. ## Install ```bash npm install @wterm/just-bash just-bash ``` `just-bash` 3 is a peer dependency. ## Quick Start ```tsx import { useCallback, useRef } from "react"; import { Terminal, useTerminal } from "@wterm/react"; import { BashShell } from "@wterm/just-bash"; import "@wterm/react/css"; function App() { const { ref, write } = useTerminal(); const shellRef = useRef(null); const handleReady = useCallback(() => { if (shellRef.current) return; const shell = new BashShell({ files: { "/home/user/hello.txt": "Hello, world!\n" }, greeting: "Welcome to wterm!", }); shellRef.current = shell; shell.attach(write); }, [write]); const handleData = useCallback((data: string) => { shellRef.current?.handleInput(data); }, []); return ( ); } ``` Use a ref to hold the `BashShell` instance so it's accessible from both the `onReady` and `onData` callbacks. Each submitted command runs once. After it completes, the shell automatically updates its working directory and prompt from the command's final directory, including when a command exits with a nonzero status. ## Options

Option	Type	Default	Description
`files`			Virtual filesystem (keys are absolute paths, values are file contents)
`env`			Environment variables
`cwd`	`string`	`"/home/user"`	Initial working directory
`greeting`	`string \| string\[]`	—	Lines printed when the shell attaches
`prompt`	`(cwd: string) => string`	colored `user\@wterm:\~$`	Custom prompt function — receives the current working directory
`network`	`NetworkConfig`	—	Network access configuration (see Network Access )

## Methods

Method	Description
	Connect to a terminal write function. Loads just-bash, prints the greeting, and displays the initial prompt.
	Process terminal input (keystrokes, paste). Call this from the terminal's `onData` callback.

## Properties

Property	Type	Description
`cwd`	`string`	Current working directory (updates after `cd` )
`bash`	`Bash \| null`	Underlying just-bash instance ( `null` until `attach` completes)

## Virtual Filesystem The `files` option populates an in-memory filesystem. Keys are absolute paths, values are file contents: ```ts const shell = new BashShell({ files: { "/home/user/README.md": "# My Project\n\nHello, world!\n", "/home/user/src/main.zig": 'const std = @import("std");\n', "/home/user/data/config.json": '{ "key": "value" }\n', }, }); ``` Directories are created implicitly from file paths. Commands like `ls`, `cat`, `cd`, and `pwd` work against this virtual filesystem. ## Network Access By default, the shell runs fully offline. To enable network access (for commands like `curl` or `fetch`), pass the `network` option from `just-bash`: ```ts const shell = new BashShell({ network: { dangerouslyAllowFullInternetAccess: true, }, }); ``` The `NetworkConfig` type is re-exported from `just-bash`. See the [just-bash documentation](https://github.com/vercel-labs/just-bash) for all available network options. ## Keyboard Shortcuts The command line accepts pasted Unicode text and treats emoji and combining sequences as whole characters when moving or deleting. Cursor movement uses terminal columns, keeping wide characters aligned.

Key	Action
`Tab`	Autocomplete files and commands at the cursor, including when editing earlier words in a command
`Up` / `Down`	Navigate command history; returning to the newest entry restores your unfinished command and cursor position
`Ctrl+R`	Search command history from newest to oldest as you type; press again to find an older match. Enter runs the match, Escape accepts it for editing, and Ctrl+G restores your unfinished command.
`Ctrl+S` during history search	Find a newer matching command. Typing continues the search toward newer commands until you press Ctrl+R again.
`Left` / `Right`	Move cursor within the current line
`Backspace` / `Delete`	Remove the character before / at the cursor
`Option/Alt+Left` / `Option/Alt+Right` , `Ctrl+Left` / `Ctrl+Right` , or `Alt+B` / `Alt+F`	Move the cursor by word
`Option/Alt+Backspace` / `Ctrl+W`	Remove the word before the cursor
`Home` / `Ctrl+A`	Jump to start of line
`End` / `Ctrl+E`	Jump to end of line
`Ctrl+U` / `Command+Backspace` (macOS)	Remove text before the cursor
`Ctrl+K`	Remove text after the cursor
`Ctrl+Y`	Restore text removed with Option/Alt+Backspace, Ctrl+W, Ctrl+U, or Ctrl+K; consecutive erasures restore together
`Ctrl+C`	Cancel current input or interrupt a running command when it reaches a cancellation point
`Ctrl+L`	Clear screen
`\\` at end of line	Line continuation (multi-line input)

--- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Markdown url: "https://wterm.dev/markdown" docs_index: /llms.txt lastUpdated: 2026-11-04 navTitle: "Markdown" --- > For an index of all documentation, see [/llms.txt](/llms.txt). Streaming Markdown-to-ANSI renderer for terminals. Designed for rendering LLM output in real time — push text chunks as they arrive and get styled terminal output back. ## Install ```bash npm install @wterm/markdown ``` ## Quick Start ### Vanilla JS ```js import { WTerm } from "@wterm/dom"; import { MarkdownRenderer } from "@wterm/markdown"; import "@wterm/dom/css"; const term = new WTerm(document.getElementById("terminal")); await term.init(); const md = new MarkdownRenderer(); const response = await fetch("/api/chat", { method: "POST" }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const rendered = md.push(decoder.decode(value)); if (rendered) term.write(rendered); } term.write(md.flush()); ``` ### React ```tsx import { useCallback, useRef } from "react"; import { Terminal, useTerminal } from "@wterm/react"; import { MarkdownRenderer } from "@wterm/markdown"; import "@wterm/react/css"; function App() { const { ref, write } = useTerminal(); const mdRef = useRef(new MarkdownRenderer()); const handleReady = useCallback(async () => { const response = await fetch("/api/chat", { method: "POST" }); const reader = response.body!.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const rendered = mdRef.current.push(decoder.decode(value)); if (rendered) write(rendered); } write(mdRef.current.flush()); }, [write]); return ; } ``` ## Options

Option	Type	Default	Description
`width`	`number`	`80`	Terminal width in columns (used for horizontal rules)

## Methods

Method	Description
`push(delta: string): string`	Feed a chunk of Markdown text. Returns rendered ANSI output for any complete lines. Buffers incomplete lines internally.
`flush(): string`	Flush remaining buffered content. Call this when the stream ends to render any trailing text and close open code blocks.

## Supported Syntax

Syntax	Rendering
`# Heading` through `### Heading`	Bold, bright white for h1–h2; bold for h3+
`bold` or `bold`	Bold text
`italic` or `italic`	Italic text
`code`	Cyan inline code
`[text](url)`	Underlined green link text with dimmed URL
Fenced code blocks ( \`\`\` )	Indented with dimmed borders
`- item` , `\* item` , `+ item`	Unordered list with indented bullets
`1. item` or `1) item`	Ordered list with numbered items
`> quote`	Blockquote with dimmed vertical bar
`---` , `\\\*` , `\_\_\_`	Dimmed horizontal rule

## Streaming LLM Output The renderer is designed for the streaming pattern common with LLM APIs. Here's a complete walkthrough: ```ts import { MarkdownRenderer } from "@wterm/markdown"; const md = new MarkdownRenderer(); async function streamChat( write: (data: string) => void, prompt: string, ) { const response = await fetch("/api/chat", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt }), }); const reader = response.body!.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value, { stream: true }); const rendered = md.push(chunk); if (rendered) write(rendered); } const remaining = md.flush(); if (remaining) write(remaining); } ``` **How it works:** 1. Create a `MarkdownRenderer` instance before the stream starts 2. As each chunk arrives, call `push(chunk)` — it buffers incomplete lines and only returns output for complete lines 3. When the stream ends, call `flush()` to render any remaining buffered content and close open code blocks 4. Write each non-empty result to the terminal with `write()` --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: React url: "https://wterm.dev/react" docs_index: /llms.txt lastUpdated: 2026-11-04 navTitle: "React" --- > For an index of all documentation, see [/llms.txt](/llms.txt). The `@wterm/react` package provides a `` component and a `useTerminal` hook for integrating wterm into React applications. ## Install ```bash npm install @wterm/dom @wterm/react ``` ## Basic Usage ```tsx import { Terminal } from "@wterm/react"; import "@wterm/react/css"; function App() { return ; } ``` ## Custom Input Handling By default, typed input is echoed back to the terminal. Use `onData` with `useTerminal` when you need control over input — for example, sending it to a server: ```tsx import { Terminal, useTerminal } from "@wterm/react"; import "@wterm/react/css"; function App() { const { ref, write } = useTerminal(); return ( { socket.send(data); }} /> ); } ``` ## Props The `` component accepts all [shared terminal options](/api-reference#terminal-options) (`cols`, `rows`, `core`, `wasmUrl`, `autoResize`, `maxImageWidth`, `maxImageHeight`, `cursorBlink`, `announceOutput`, `renderingPaused`, `webmcp`, `onData`, `onBinary`, `onTitle`, `onBell`, `onClipboardWrite`, `onShellIntegration`, `onWorkingDirectory`, `onResize`) plus [React-only props](/api-reference#react-only-props) (`theme`, `onReady`, `onError`). Pass a [`TerminalCore`](/ghostty) instance to the `core` prop to use an alternative emulation backend. Standard `div` props (`className`, `style`, `id`, etc.) are forwarded to the container element. Use `` to name and describe the actual input. Label attributes stay synchronized when props change. The wrapper is a group; input is the single editable control. `tabIndex={-1}` removes input from page tab entry. Press Escape, then Tab to move focus out of the terminal, or Escape, then Shift+Tab to move backward. Use `readText()` on the WTerm instance to present a stable snapshot of retained output in a labelled, read-only text area; see [Reading Terminal Output](/api-reference#reading-terminal-output). See [Input Accessibility](/api-reference#input-accessibility). The React wrapper delegates rendering to `@wterm/dom`, so a graphics-capable core such as `@wterm/ghostty` automatically renders direct Kitty PNG/RGB/RGBA images. Set `maxImageWidth` and/or `maxImageHeight` to constrain their rendered size in CSS pixels; images preserve their aspect ratio and are never enlarged. Image canvases are decorative (`aria-hidden`, non-focusable, and pointer-transparent); text remains the accessible terminal surface. The underlying DOM terminal also answers Kitty pixel geometry queries from the rendered viewport, so direct image clients can negotiate their display size. ## useTerminal Hook Returns a ref and imperative helpers: ```tsx const { ref, write, resize, focus } = useTerminal(); ``` See the full [Imperative Handle](/api-reference#imperative-handle-react) reference for all returned methods and the `TerminalHandle` interface. ## Themes Import the stylesheet and switch themes via the `theme` prop: ```tsx import "@wterm/react/css"; ; ``` Built-in themes: `solarized-dark`, `monokai`, `light`. Define custom themes with CSS custom properties (`--term-fg`, `--term-bg`, `--term-color-0` through `--term-color-15`). ## Next.js For Next.js, add `@wterm/dom` and `@wterm/react` to `transpilePackages` in your config: ```js // next.config.mjs const nextConfig = { transpilePackages: ["@wterm/dom", "@wterm/react"], }; ``` ## Terminal Search The underlying WTerm instance exposes full-history `search`, `findNext`, `findPrevious`, `getSearchState`, and `clearSearch`. Set its `onSearchChange` callback to keep Find controls current. Use `onReady` or `ref.current.instance`. See [Terminal Search](/api-reference#terminal-search) for Unicode behavior, progress, and limits. ## Selection and Copy Native Copy preserves terminal line breaks and complete Unicode cells, joining confirmed Ghostty soft wraps. Call `getSelectionText()` on the underlying WTerm instance to read that text without writing the clipboard. See [Selection and Copy](/api-reference#selection-and-copy) for whitespace behavior, return values, and native-selection limits. With Ghostty's current WASM binary, selections also follow output scrolling and resize/reflow while their text remains intact. Overwritten or discarded text, resets, and screen switches clear them. The same reference covers preservation limits and pending-frame behavior. Use `await wt.selectAll()` on the WTerm instance to select all retained history and the active screen without mounting extra rows, then read `wt.getSelectionText()`. Cmd+A or Ctrl+Shift+A invokes the same action from terminal input. `wt.clearSelection()` cancels it. See [Select All](/api-reference#select-all) for capture limits, shortcuts, and when selection clears. Double-click words or paths, or triple-click logical lines. The WTerm methods `selectWord({ row, col })` and `selectLine(row)` create the same native selection, including confirmed Ghostty soft wraps and unmounted history. See [Words and Logical Lines](/api-reference#words-and-logical-lines) for coordinates, boundaries, and limits. Alt/Option-drag selects rectangular columns; Shift+Alt selects inside mouse-reporting applications. Call `selectRectangle(start, end)` on the WTerm instance with inclusive retained-row/cell corners. Rectangles preserve selected spaces and physical row breaks and clear on output or resize. See [Rectangular Selection](/api-reference#rectangular-selection) for copy shortcuts, coordinates, and limits. ## Output announcements Opt in with `announceOutput` to announce terminal text changes politely while input has focus. The option defaults to `false`; component prop changes apply without restarting the terminal, and vanilla callers use `term.setOutputAnnouncements(enabled)`. Announcements are batched and stop when focus leaves input. Bursts are bounded to avoid overwhelming the speech queue. See [Output announcements](/api-reference#output-announcements) for capture limits, pause/resume behavior, and redraw semantics. ## Inactive panes Use `renderingPaused` for panes that are not visible. Parsing and terminal effects continue, and resuming paints the latest state without restarting. In vanilla code, call `term.setRenderingPaused(paused)`; framework props are reactive. Browser document visibility also pauses painting. See [Inactive panes](/configuration#inactive-panes) for focus and capture behavior. Application clipboard writes require an explicit host policy; see [Clipboard requests](/configuration#clipboard-requests). ## Shell integration With Ghostty, the `onWorkingDirectory` prop receives raw OSC 7 URI reports, including while rendering is paused. An empty string clears the value. Treat the URI as untrusted metadata; see [Working directories](/configuration#working-directories). With Ghostty and a shell emitting OSC 133, `onShellIntegration` receives the latest prompt, input, running, or completion state and the last reported exit code. Delivery continues while painting is paused; markers in one parser chunk coalesce into current state. See [Shell integration](/configuration#shell-integration) for the contract, shell setup, and workspace indicators. Use the underlying `WTerm` instance’s `scrollToPrompt(-1)` and `scrollToPrompt(1)` methods to navigate previous and next prompts in retained history. See [Shell integration](/configuration#shell-integration) for viewport behavior, unsupported cores, and inactive states. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Svelte url: "https://wterm.dev/svelte" docs_index: /llms.txt lastUpdated: 2026-11-04 navTitle: "Svelte" --- > For an index of all documentation, see [/llms.txt](/llms.txt). The `@wterm/svelte` package provides a `` component for Svelte 5 applications. It re-exports the DOM and core APIs from `@wterm/dom` so the component and terminal types can come from one import. Use `` to name and describe the actual input. Label attributes stay synchronized when they change. The wrapper is a group; input is the single editable control. `tabindex={-1}` removes input from page tab entry. Press Escape, then Tab to move focus out of the terminal, or Escape, then Shift+Tab to move backward. Use `readText()` on the WTerm instance to present a stable snapshot of retained output in a labelled, read-only text area; see [Reading Terminal Output](/api-reference#reading-terminal-output). See [Input Accessibility](/api-reference#input-accessibility). ## Install ```bash npm install @wterm/dom @wterm/svelte svelte ``` ## Basic Usage ```svelte ``` The WASM binary is embedded in the package — no extra setup is required. To serve it separately, pass `wasmUrl`. ## Custom Input Handling Typed input is echoed back by default. In Svelte 5, pass `onData` when input should be sent to a PTY or another backend: ```svelte ``` `onBinary` receives raw X10 mouse bytes. Forward its `Uint8Array` unchanged when the terminal input transport accepts binary data. The other callback props are `onTitle`, `onBell`, `onClipboardWrite`, `onShellIntegration`, `onWorkingDirectory`, `onResize`, `onReady`, and `onError`. `onReady` receives the underlying `WTerm` instance. ## Props The component accepts the shared terminal options `cols`, `rows`, `core`, `wasmUrl`, `autoResize`, `maxImageWidth`, `maxImageHeight`, `cursorBlink`, `announceOutput`, `renderingPaused`, `webmcp`, and `debug`, plus the `theme` prop. Standard `

` attributes such as `class`, `style`, `id`, and ARIA attributes are forwarded to the root element. See the [Terminal Options](/api-reference#terminal-options) and [Svelte-only Props](/api-reference#svelte-only-props) reference sections for details. The Svelte wrapper delegates rendering to `@wterm/dom`, so a graphics-capable core such as `@wterm/ghostty` automatically renders direct Kitty PNG/RGB/RGBA images. Set `maxImageWidth` and/or `maxImageHeight` to constrain rendered images while preserving their aspect ratio. ## Imperative Control Bind the component instance to call `write`, `resize`, and `focus`: ```svelte ``` To access the underlying `WTerm`, bind the `instance` prop: ```svelte ``` ## Themes Import the stylesheet and pass the theme name: ```svelte ``` Built-in themes are `solarized-dark`, `monokai`, and `light`. Define custom themes with CSS custom properties. The component initializes in `onMount`, so it is safe to render from an SSR application. ## Terminal Search The underlying WTerm instance exposes full-history `search`, `findNext`, `findPrevious`, `getSearchState`, and `clearSearch`. Set its `onSearchChange` callback to keep Find controls current. Use `onReady` or `bind:instance`. See [Terminal Search](/api-reference#terminal-search) for Unicode behavior, progress, and limits. ## Selection and Copy Native Copy preserves terminal line breaks and complete Unicode cells, joining confirmed Ghostty soft wraps. Call `getSelectionText()` on the underlying WTerm instance to read that text without writing the clipboard. See [Selection and Copy](/api-reference#selection-and-copy) for whitespace behavior, return values, and native-selection limits. With Ghostty's current WASM binary, selections also follow output scrolling and resize/reflow while their text remains intact. Overwritten or discarded text, resets, and screen switches clear them. The same reference covers preservation limits and pending-frame behavior. Use `await wt.selectAll()` on the WTerm instance to select all retained history and the active screen without mounting extra rows, then read `wt.getSelectionText()`. Cmd+A or Ctrl+Shift+A invokes the same action from terminal input. `wt.clearSelection()` cancels it. See [Select All](/api-reference#select-all) for capture limits, shortcuts, and when selection clears. Double-click words or paths, or triple-click logical lines. The WTerm methods `selectWord({ row, col })` and `selectLine(row)` create the same native selection, including confirmed Ghostty soft wraps and unmounted history. See [Words and Logical Lines](/api-reference#words-and-logical-lines) for coordinates, boundaries, and limits. Alt/Option-drag selects rectangular columns; Shift+Alt selects inside mouse-reporting applications. Call `selectRectangle(start, end)` on the WTerm instance with inclusive retained-row/cell corners. Rectangles preserve selected spaces and physical row breaks and clear on output or resize. See [Rectangular Selection](/api-reference#rectangular-selection) for copy shortcuts, coordinates, and limits. ## Output announcements Opt in with `announceOutput` to announce terminal text changes politely while input has focus. The option defaults to `false`; component prop changes apply without restarting the terminal, and vanilla callers use `term.setOutputAnnouncements(enabled)`. Announcements are batched and stop when focus leaves input. Bursts are bounded to avoid overwhelming the speech queue. See [Output announcements](/api-reference#output-announcements) for capture limits, pause/resume behavior, and redraw semantics. ## Inactive panes Use `renderingPaused` for panes that are not visible. Parsing and terminal effects continue, and resuming paints the latest state without restarting. In vanilla code, call `term.setRenderingPaused(paused)`; framework props are reactive. Browser document visibility also pauses painting. See [Inactive panes](/configuration#inactive-panes) for focus and capture behavior. Application clipboard writes require an explicit host policy; see [Clipboard requests](/configuration#clipboard-requests). ## Shell integration With Ghostty, `onWorkingDirectory` (or `onworkingdirectory`) receives raw OSC 7 URI reports, including while rendering is paused. An empty string clears the value. Treat the URI as untrusted metadata; see [Working directories](/configuration#working-directories). With Ghostty and a shell emitting OSC 133, `onShellIntegration` receives the latest prompt, input, running, or completion state and the last reported exit code. Delivery continues while painting is paused; markers in one parser chunk coalesce into current state. See [Shell integration](/configuration#shell-integration) for the contract, shell setup, and workspace indicators. Use the underlying `WTerm` instance’s `scrollToPrompt(-1)` and `scrollToPrompt(1)` methods to navigate previous and next prompts in retained history. See [Shell integration](/configuration#shell-integration) for viewport behavior, unsupported cores, and inactive states. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Themes url: "https://wterm.dev/themes" docs_index: /llms.txt lastUpdated: 2026-11-04 navTitle: "Themes" --- > For an index of all documentation, see [/llms.txt](/llms.txt). wterm uses CSS custom properties for all visual styling, making it easy to switch between built-in themes or create your own. On this site's homepage, **Default** follows your site theme: light, dark, or system. The greeting and interactive terminal use the same colors, including in fullscreen. Selecting Solarized, Monokai, or Light keeps that terminal preset independent of the site theme. This site-specific Default does not change the package's default dark palette described below. The [local shell workspace](https://github.com/vercel-labs/wterm/tree/main/examples/local) has an **Appearance** dialog with System, Dark, and Light choices and a 10–32 px font-size control. Settings apply to all panes and persist in the same browser. System follows OS changes; switching appearance preserves existing shells. ## Using a Theme ### React Pass the theme name via the `theme` prop: ```tsx ``` ### Vue Same `theme` prop: ```vue ``` ### Svelte Pass the theme name through the `theme` prop: ```svelte ``` ### Vanilla JS Add the theme class to the terminal element: ```js const term = new WTerm(document.getElementById("terminal")); term.element.classList.add("theme-monokai"); await term.init(); ``` ## Built-in Themes ### Default The default dark theme, inspired by VS Code's Dark+ palette.

Property	Value
Background	`#1e1e1e`
Foreground	`#d4d4d4`
Cursor	`#aeafad`

### Solarized Dark The classic Solarized Dark color scheme by Ethan Schoonover. ```tsx ```

Property	Value
Background	`#002b36`
Foreground	`#839496`
Cursor	`#93a1a1`

### Monokai Based on the Monokai color scheme. ```tsx ```

Property	Value
Background	`#272822`
Foreground	`#f8f8f2`
Cursor	`#f8f8f0`

### Light A clean light theme inspired by Atom's One Light. ```tsx ```

Property	Value
Background	`#fafafa`
Foreground	`#383a42`
Cursor	`#526eff`

## Custom Themes Create a custom theme by defining a CSS class that overrides the wterm custom properties: ```css .wterm.theme-tokyo-night { --term-bg: #1a1b26; --term-fg: #c0caf5; --term-cursor: #f7768e; --term-color-0: #15161e; --term-color-1: #f7768e; --term-color-2: #9ece6a; --term-color-3: #e0af68; --term-color-4: #7aa2f7; --term-color-5: #bb9af7; --term-color-6: #7dcfff; --term-color-7: #a9b1d6; --term-color-8: #414868; --term-color-9: #f7768e; --term-color-10: #9ece6a; --term-color-11: #e0af68; --term-color-12: #7aa2f7; --term-color-13: #bb9af7; --term-color-14: #7dcfff; --term-color-15: #c0caf5; } ``` Then apply it the same way as a built-in theme: ```tsx ``` ## CSS Custom Properties Reference

Property	Description
`--term-bg`	Terminal background color
`--term-fg`	Default text color
`--term-cursor`	Cursor color
`--term-font-family`	Font stack (default: Menlo, Consolas, DejaVu Sans Mono, Courier New, monospace)
`--term-font-size`	Font size (default: `14px`)
`--term-line-height`	Line height multiplier (default: `1.2`)
`--term-color-0` … `--term-color-7`	Standard ANSI colors (black, red, green, yellow, blue, magenta, cyan, white)
`--term-color-8` … `--term-color-15`	Bright ANSI colors

Colors beyond the 16-color palette (indices 16–255 and true-color RGB) are computed by the renderer and do not use custom properties. ## Updating host colors Use `wt.setThemeColors(colors)` to update a running terminal's foreground, background, cursor, and 16 ANSI colors together. The method sets the corresponding CSS custom properties and forwards the defaults to a supporting core. It repaints live and retained rows without writing escape sequences, restarting the parser, or clearing application color overrides. Painting still respects synchronized output, hidden pages, and paused panes. ```ts wt.setThemeColors({ foreground: 0x383a42, background: 0xfafafa, cursor: 0x526fff, palette: [ 0x383a42, 0xe45649, 0x50a14f, 0xc18401, 0x4078f2, 0xa626a4, 0x0184bc, 0xa0a1a7, 0x4f525e, 0xe45649, 0x50a14f, 0xc18401, 0x4078f2, 0xa626a4, 0x0184bc, 0xffffff, ], }); ``` `TerminalThemeColors` uses opaque integer RGB values from `0` to `0xffffff` and exactly 16 palette entries; invalid values throw `RangeError` before changes are applied. Values are copied and can be set before `init()`. Indices 16–255 and explicit RGB cell colors are unchanged. Application overrides take precedence; OSC resets return to the latest host defaults. The inline properties set by this method take precedence over theme classes; call it again to change those colors. Pass `null` to remove them and return to the CSS theme. With Ghostty, use the updated bundled WASM asset to synchronize indexed colors and foreground/background query replies. Older WASM assets retain their existing engine defaults. Custom cores may implement the optional `TerminalCore.setThemeColors()` hook; without it only the CSS defaults update. Framework users can call the same method on the WTerm instance from `onReady` or their imperative handle's `instance`. ## Application color changes Ghostty applications can set the default foreground, background, and cursor colors with OSC `10`, `11`, and `12`. OSC `110`, `111`, and `112` reset the corresponding color to the current CSS theme, including theme changes made while an override was active. Explicit SGR cell colors are unaffected. Inverse cells swap the actual foreground/background, including default colors, in both cores. Application overrides are separate from `--term-fg`, `--term-bg`, and `--term-cursor`; the renderer never overwrites these host theme properties. Updates follow normal rendering, including synchronized output and paused panes. Destroying the terminal removes its overrides. The built-in core and older Ghostty WASM binaries retain CSS theme defaults. ## Color queries Applications ask for the default foreground and background with OSC `10` and `11` (`printf '\e]11;?\a'`). Both cores answer with the colors the terminal element's CSS resolves to when the query arrives: `--term-fg` and `--term-bg`, including theme classes, `prefers-color-scheme` rules and colors written in any CSS color space. Replies end with the query's own terminator, BEL or ST. Colors set with `setThemeColors()` take precedence until it is called with `null`. A Ghostty application's own OSC `10`/`11` color changes are reported until it resets them. A query split across two `write()` calls is answered with the colors read at the previous query or at `init()`. Headless Ghostty cores, which have no CSS, answer with their `foregroundColor` and `backgroundColor` options. See [Ghostty options](/ghostty). ## Font and cell alignment Choose a monospace font with `--term-font-family` and set its size with `--term-font-size`. wterm measures the font's cell width and uses it for text, backgrounds, and cursors. Braille, box drawing, and other fallback glyphs stay within their assigned columns even when the fallback font has wider glyphs. Wide characters occupy two cells; oversized glyphs are clipped to their cells. Common light, heavy, and rounded box-drawing characters connect across cell edges even when the font's glyphs fall short. They remain selectable as text. Cell widths update when fonts load or the font size changes, including when `autoResize` is disabled. Native selection and OSC 8 link text are preserved. This behavior is shared by both cores and all framework components. ## Cell backgrounds Colored and reversed cells keep their backgrounds within their columns, including the last column and rows in scrollback. A complete row with one shared, opaque background extends that color to the container's right edge, keeping full-width status bars filled. Mixed, dim, or hidden cells do not repaint neighboring cells or other rows. This behavior is shared by both cores and all framework components. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Vanilla JS url: "https://wterm.dev/vanilla" docs_index: /llms.txt lastUpdated: 2026-11-06 navTitle: "Vanilla JS" --- > For an index of all documentation, see [/llms.txt](/llms.txt). The `@wterm/dom` package provides a framework-free terminal that works with plain HTML/CSS/JS. ## Install ```bash npm install @wterm/dom ``` ## Usage ```html

``` ## Input Accessibility Give the host an `aria-label` or `aria-labelledby`, with an optional `aria-describedby` or `aria-description`. WTerm applies these to the actual input and keeps changes synchronized. The input defaults to the name **Terminal**; the host defaults to a group. Host `tabindex="-1"` excludes input from page tab entry, while `term.focus()` still focuses it programmatically. Press Escape, then Tab to move focus out of the terminal, or Escape, then Shift+Tab to move backward. Use `readText()` on the WTerm instance to present a stable snapshot of retained output in a labelled, read-only text area; see [Reading Terminal Output](/api-reference#reading-terminal-output). See [Input Accessibility](/api-reference#input-accessibility) for tab-order ownership and output limits. ## Custom Input Handling By default, typed input is echoed back to the terminal. Pass `onData` when you need control over input — for example, sending it to a server: ```js const term = new WTerm(document.getElementById("terminal"), { onData(data) { socket.send(data); }, }); await term.init(); ``` ## Options and Methods The `WTerm` constructor accepts all [shared terminal options](/api-reference#terminal-options) (`cols`, `rows`, `core`, `wasmUrl`, `autoResize`, `maxImageWidth`, `maxImageHeight`, `cursorBlink`, `announceOutput`, `renderingPaused`, `webmcp`, `onData`, `onBinary`, `onTitle`, `onBell`, `onClipboardWrite`, `onShellIntegration`, `onWorkingDirectory`, `onResize`). Pass a [`TerminalCore`](/ghostty) instance to the `core` option to use an alternative emulation backend. When auto-resizing, omitted dimensions are measured before core initialization, avoiding an unnecessary initial resize. Explicit dimensions are preserved at initialization. Hidden containers fall back to 80×24 until measurable. Read `wt.cols` and `wt.rows` after `await wt.init()` when starting a PTY. See [WTerm Methods](/api-reference#wterm-methods) for all instance methods, including [full-history Find](/api-reference#terminal-search): `search`, `findNext`, `findPrevious`, `getSearchState`, and `clearSearch`. Use the `onSearchChange` WTerm option or instance callback for progress and match counts. When a terminal application enables mouse tracking, UTF-8 (1005), SGR (1006), urxvt (1015), and SGR pixel (1016) reports reach `onData` with keyboard input and focus reports. Forward `onData` strings through a UTF-8 transport. Mode 1016 uses 1-based CSS-pixel coordinates relative to the visible grid, independent of device pixel ratio. Mode 1003 sends unpressed pointer motion once per cell in cell formats and once per CSS pixel in 1016. X10 mouse reports go to `onBinary` as raw bytes when that callback is supplied. Without `onBinary`, ASCII-safe X10 reports reach `onData`; coordinates requiring non-ASCII bytes are skipped. Hold Shift for native text selection. When mouse tracking is active, clicks and wheel gestures on scrollback rows stay with the browser. If you are reading history, the wheel scrolls it until you reach the bottom; hold Shift and scroll to move through history from the live viewport. A drag begun on the live grid still reports its release after leaving the grid. When an application rings BEL, `onBell(count)` receives the number of bells as output is written. WTerm does not play sound automatically; your application can choose an audible or visual notification. When the active core negotiates the Kitty keyboard protocol, WTerm encodes key presses, repeats, and available releases from the core's current flags, including disambiguated escape codes and all-key reporting when the application requests them. The built-in and Ghostty cores keep separate primary and alternate-screen flag stacks. Third-party cores without Kitty state retain legacy keyboard behavior. The built-in core answers DEC private-mode status queries such as `CSI ?2026$p` for synchronized output. A response of `CSI ?2026;1$y` means the mode is set; `CSI ?2026;2$y` means it is reset. WTerm forwards the response through `onData` to your connected application. Printable AltGr input uses the browser's committed text path even in Kitty mode, so layouts that use AltGr can enter characters. This includes Control+Alt text with the right Alt key when the browser does not report AltGraph state. Control+Alt chords without either AltGr signal keep their Kitty encoding. Outside Kitty keyboard mode, modified arrow, Home/End, Insert/Delete, Page Up/Down, and F1–F12 keys use xterm-style CSI modifier sequences. For example, Control+Left sends `CSI 1;5D` instead of an unmodified Left arrow. Unmodified arrows still honor application cursor mode. Browser-reserved shortcuts may not reach the terminal. While the terminal is focused, handled key presses do not bubble to page-level shortcut listeners. Control+K can reach the terminal instead of opening docs search. When Kitty keyboard mode is not negotiated, Control+Space sends NUL, Control+/ sends US, Control+? sends DEL, and Control+Backspace sends BS. Browsers may reserve some shortcuts. Control+Alt printable input remains on the native text path in this mode for keyboard layouts that use AltGr. When an application enables xterm `modifyOtherKeys` level 2 (`CSI > 4 ; 2 m`) and Kitty keyboard mode is not negotiated, keys whose legacy encoding loses a modifier are sent as `CSI 27 ; modifier ; code ~`: Control and Alt with characters, including Control+letter, Shift with letters and Space, Shift+Tab, Alt+Tab, Alt+Enter, and Backspace with any modifier except Control alone. Other keys keep their legacy encoding, and Meta shortcuts stay with the browser. `CSI ? 4 m` reports the level, other `CSI > Pp m` changes return to legacy input, and RIS resets it. Vim enables this mode for xterm terminals to map keys such as Control+Shift+E apart from Control+E. Browsers do not expose every native keyboard field. WTerm uses `KeyboardEvent.code` for functional and modifier identity, `KeyboardEvent.key` for text, and reports shifted alternates when available. It does not invent a base-layout alternate, synthesize missing release events, or retain associated text beyond the current press. IME composition displays tentative text at the terminal cursor and sends only the committed text to `onData`. If you are viewing scrollback when composition starts, WTerm returns to the live viewport so the browser's candidate window appears by the current input. On touch-first devices, the transparent input target stays at the cursor for soft-keyboard focus and the native paste menu. Holding Backspace sends repeated deletions, and pasted text follows the application's bracketed-paste mode. Application-provided OSC 8 hyperlinks render as native anchors across both the active viewport and scrollback. Only absolute HTTP and HTTPS URIs become clickable; invalid, relative, and executable schemes remain ordinary terminal text. Partial row redraws reuse matching cell spans when most of the row is unchanged. When span styles and column widths stay the same, text changes update existing text nodes without reparsing HTML. Cell widths, selection, links, and text decorations remain intact. Glyph ink can overhang its cell without shifting later columns, so italic and fallback characters retain their complete shape. The viewport still clips output at its edges. Fractional `--term-row-height` values are preserved during initialization, allowing the live grid to match a host's typography. While hovering an anchor, holding Command on macOS or Control on Windows and Linux reveals its underline and pointer cursor. Plain clicks remain terminal interaction. Command-click, Control-click, or native keyboard activation when an anchor receives focus opens the link. Modified link activation remains available while SGR mouse tracking is active and is not forwarded to the terminal application. Scrollback normally uses a bounded DOM window around the visible rows. Up to 1,000 selected history rows stay mounted separately from a distant viewport, leaving gaps virtualized. Native browser find and accessibility inspect mounted rows, not every retained history row. If the terminal is already at the bottom, new output keeps it at the exact bottom; reading older history does not enable auto-follow, and terminal input returns to the bottom. With the built-in and Ghostty cores, small scrolls reuse the mounted overscan window until the viewport approaches its edge. When the window moves, overlapping history rows keep their content without rereading their cells. Output, theme changes, resize, and history changes refresh the content. Custom cores without a discarded-history count refresh mounted history on every render. Copying a terminal selection preserves complete Unicode cells and explicit newlines; Ghostty soft wraps join without artificial line breaks. Block glyphs are included as text. Use `term.getSelectionText()` to read the same plain text without touching the clipboard. See [Selection and Copy](/api-reference#selection-and-copy) for whitespace behavior and native-selection limits. With Ghostty's current WASM binary, selections also follow output scrolling and resize/reflow. Overwritten or discarded text, resets, and screen switches clear the selection. See the same reference for preservation limits and behavior while a frame is pending. Use `await wt.selectAll()` on the WTerm instance to select all retained history and the active screen without mounting extra rows, then read `wt.getSelectionText()`. Cmd+A or Ctrl+Shift+A invokes the same action from terminal input. `wt.clearSelection()` cancels it. See [Select All](/api-reference#select-all) for capture limits, shortcuts, and when selection clears. Double-click words or paths, or triple-click logical lines. The WTerm methods `selectWord({ row, col })` and `selectLine(row)` create the same native selection, including confirmed Ghostty soft wraps and unmounted history. See [Words and Logical Lines](/api-reference#words-and-logical-lines) for coordinates, boundaries, and limits. Alt/Option-drag selects rectangular columns; Shift+Alt selects inside mouse-reporting applications. Call `selectRectangle(start, end)` on the WTerm instance with inclusive retained-row/cell corners. Rectangles preserve selected spaces and physical row breaks and clear on output or resize. See [Rectangular Selection](/api-reference#rectangular-selection) for copy shortcuts, coordinates, and limits. ### Terminal images When the supplied core exposes the optional graphics methods, `WTerm` renders visible pinned Kitty image placements in a separate canvas overlay. The overlay is pointer-transparent, non-focusable, `aria-hidden`, and does not change scroll height, so ordinary text selection, copy, keyboard input, and screen reader behavior remain row-based. Image pixels are decorative; provide text context separately when the image carries meaning. For browser safety, every destination canvas is bounded by the active terminal pixel area and all visible canvas backing stores share a 32 MiB budget. An oversized or otherwise unmaterializable placement is skipped without changing the text or scrollback surface. The default lightweight core safely consumes unsupported Kitty APC data but does not render it. Pass a Ghostty core for direct PNG/RGB/RGBA support. Images are transient, bounded per-screen state; file/shared-memory/URL media, Sixel, iTerm2, animation, and virtual placements are unsupported. Use `maxImageWidth` and/or `maxImageHeight` in the `WTerm` options to constrain oversized rendered images. The limits are CSS pixels, preserve aspect ratio, and only scale images down. The DOM wrapper answers Kitty pixel geometry queries (`CSI 14 t` and `CSI 16 t`) from the rendered terminal element, allowing Kitty graphics clients such as `kitten icat --transfer-mode=stream image.png` to negotiate image size. Queries can span text and byte writes, including while rendering is paused. Ordinary byte output is scanned directly without creating a decoded string copy. ## Themes Import the stylesheet and apply a theme class to the terminal element: ```js import "@wterm/dom/css"; ``` Built-in themes: `theme-solarized-dark`, `theme-monokai`, `theme-light`: ```js element.classList.add("theme-monokai"); ``` All colors use CSS custom properties (`--term-fg`, `--term-bg`, `--term-color-0` through `--term-color-15`) so you can define your own theme with plain CSS. ## WebSocket Transport Connect to a PTY backend over WebSocket: ```js import { WTerm, WebSocketTransport } from "@wterm/dom"; const term = new WTerm(el, { cols: 80, rows: 24 }); await term.init(); const ws = new WebSocketTransport({ url: "ws://localhost:8080/pty", onData: (data) => term.write(data), }); ws.connect(); term.onData = (data) => { try { ws.send(data); } catch (error) { console.error("Input was not sent", error); // Show this in your app's UI. } }; ``` See the full [WebSocketTransport](/api-reference#websockettransport) reference for all options, methods, and properties. Sends are bounded to 1 MiB and 1,024 queued messages by default. Observe `onBackpressure` and catch buffer-limit `RangeError` to show input that was not accepted. Explicit close discards unsent input. See [Buffering and delivery](/api-reference#buffering-and-delivery) before wiring shell input or implementing reconnect behavior. ## Output announcements Opt in with `announceOutput` to announce terminal text changes politely while input has focus. The option defaults to `false`; component prop changes apply without restarting the terminal, and vanilla callers use `term.setOutputAnnouncements(enabled)`. Announcements are batched and stop when focus leaves input. Bursts are bounded to avoid overwhelming the speech queue. See [Output announcements](/api-reference#output-announcements) for capture limits, pause/resume behavior, and redraw semantics. ## Inactive panes Use `renderingPaused` for panes that are not visible. Parsing and terminal effects continue, and resuming paints the latest state without restarting. In vanilla code, call `term.setRenderingPaused(paused)`; framework props are reactive. Browser document visibility also pauses painting. See [Inactive panes](/configuration#inactive-panes) for focus and capture behavior. ## Shell integration With Ghostty, `onWorkingDirectory(uri)` receives raw OSC 7 directory reports, including while rendering is paused. An empty string clears the value. Treat the URI as untrusted metadata; see [Working directories](/configuration#working-directories). With Ghostty and a shell emitting OSC 133, `onShellIntegration` receives the latest prompt, input, running, or completion state and the last reported exit code. Delivery continues while painting is paused; markers in one parser chunk coalesce into current state. See [Shell integration](/configuration#shell-integration) for the contract, shell setup, and workspace indicators. Use the underlying `WTerm` instance’s `scrollToPrompt(-1)` and `scrollToPrompt(1)` methods to navigate previous and next prompts in retained history. See [Shell integration](/configuration#shell-integration) for viewport behavior, unsupported cores, and inactive states. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: Vue url: "https://wterm.dev/vue" docs_index: /llms.txt lastUpdated: 2026-11-04 navTitle: "Vue" --- > For an index of all documentation, see [/llms.txt](/llms.txt). The `@wterm/vue` package provides a `` component for integrating wterm into Vue 3 applications. It re-exports everything from `@wterm/dom`, so a single import covers both the component and its types. With Ghostty, `@working-directory="onDirectory"` receives raw OSC 7 URI reports, including while rendering is paused. An empty string clears the value. Treat the URI as untrusted metadata; see [Working directories](/configuration#working-directories). Use `` to name and describe the actual input. Label attributes stay synchronized when they change. The wrapper is a group; input is the single editable control. `:tabindex="-1"` removes input from page tab entry. Press Escape, then Tab to move focus out of the terminal, or Escape, then Shift+Tab to move backward. Use `readText()` on the WTerm instance to present a stable snapshot of retained output in a labelled, read-only text area; see [Reading Terminal Output](/api-reference#reading-terminal-output). See [Input Accessibility](/api-reference#input-accessibility). ## Install ```bash npm install @wterm/dom @wterm/vue ``` ## Basic Usage ```vue ``` ## Custom Input Handling By default, typed input is echoed back to the terminal. Listen to the `data` event when you need control over input — for example, sending it to a server: ```vue ``` ## Props The `` component accepts all [shared terminal options](/api-reference#terminal-options) (`cols`, `rows`, `core`, `wasmUrl`, `autoResize`, `maxImageWidth`, `maxImageHeight`, `cursorBlink`, `announceOutput`, `renderingPaused`, `webmcp`) plus [Vue-only props](/api-reference#vue-only-props) (`theme`). Pass a [`TerminalCore`](/ghostty) instance to the `core` prop to use an alternative emulation backend. Because `inheritAttrs` is enabled, standard DOM attributes (`class`, `style`, `id`, ARIA props, etc.) are forwarded to the root `

`. The Vue wrapper delegates rendering to `@wterm/dom`, so a graphics-capable core such as `@wterm/ghostty` automatically renders direct Kitty PNG/RGB/RGBA images. Set `maxImageWidth` and/or `maxImageHeight` to constrain their rendered size in CSS pixels; images preserve their aspect ratio and are never enlarged. Image canvases are decorative (`aria-hidden`, non-focusable, and pointer-transparent); text remains the accessible terminal surface. The underlying DOM terminal also answers Kitty pixel geometry queries from the rendered viewport, so direct image clients can negotiate their display size. ## Events Input callbacks are exposed as Vue events rather than `onXxx` props: ```vue ``` See the full [Vue Events](/api-reference#vue-events) reference for payload types. The `binary` event carries raw X10 mouse bytes as a `Uint8Array`. Forward it unchanged when the terminal input transport accepts binary data. ## Template Ref Access imperative methods via a template ref: ```vue ``` The exposed methods are `write`, `resize`, `focus`, and `instance` (the underlying `WTerm`, or `null` before mount). See the full [Template Ref](/api-reference#template-ref-vue) reference. ## Themes Import the stylesheet and switch themes via the `theme` prop: ```vue ``` Built-in themes: `solarized-dark`, `monokai`, `light`. Define custom themes with CSS custom properties (`--term-fg`, `--term-bg`, `--term-color-0` through `--term-color-15`). See [Themes](/themes) for details. ## Nuxt The component mounts in `onMounted`, so it is SSR-safe out of the box. If you need to guarantee client-only rendering (e.g. for debugging or to skip hydration entirely), wrap it in ``: ```vue ``` ## Terminal Search The underlying WTerm instance exposes full-history `search`, `findNext`, `findPrevious`, `getSearchState`, and `clearSearch`. Set its `onSearchChange` callback to keep Find controls current. Use the `ready` event or template ref’s `instance`. See [Terminal Search](/api-reference#terminal-search) for Unicode behavior, progress, and limits. ## Selection and Copy Native Copy preserves terminal line breaks and complete Unicode cells, joining confirmed Ghostty soft wraps. Call `getSelectionText()` on the underlying WTerm instance to read that text without writing the clipboard. See [Selection and Copy](/api-reference#selection-and-copy) for whitespace behavior, return values, and native-selection limits. With Ghostty's current WASM binary, selections also follow output scrolling and resize/reflow while their text remains intact. Overwritten or discarded text, resets, and screen switches clear them. The same reference covers preservation limits and pending-frame behavior. Use `await wt.selectAll()` on the WTerm instance to select all retained history and the active screen without mounting extra rows, then read `wt.getSelectionText()`. Cmd+A or Ctrl+Shift+A invokes the same action from terminal input. `wt.clearSelection()` cancels it. See [Select All](/api-reference#select-all) for capture limits, shortcuts, and when selection clears. Double-click words or paths, or triple-click logical lines. The WTerm methods `selectWord({ row, col })` and `selectLine(row)` create the same native selection, including confirmed Ghostty soft wraps and unmounted history. See [Words and Logical Lines](/api-reference#words-and-logical-lines) for coordinates, boundaries, and limits. Alt/Option-drag selects rectangular columns; Shift+Alt selects inside mouse-reporting applications. Call `selectRectangle(start, end)` on the WTerm instance with inclusive retained-row/cell corners. Rectangles preserve selected spaces and physical row breaks and clear on output or resize. See [Rectangular Selection](/api-reference#rectangular-selection) for copy shortcuts, coordinates, and limits. ## Output announcements Opt in with `announceOutput` to announce terminal text changes politely while input has focus. The option defaults to `false`; component prop changes apply without restarting the terminal, and vanilla callers use `term.setOutputAnnouncements(enabled)`. Announcements are batched and stop when focus leaves input. Bursts are bounded to avoid overwhelming the speech queue. See [Output announcements](/api-reference#output-announcements) for capture limits, pause/resume behavior, and redraw semantics. ## Inactive panes Use `renderingPaused` for panes that are not visible. Parsing and terminal effects continue, and resuming paints the latest state without restarting. In vanilla code, call `term.setRenderingPaused(paused)`; framework props are reactive. Browser document visibility also pauses painting. See [Inactive panes](/configuration#inactive-panes) for focus and capture behavior. Application clipboard writes require an explicit host policy; see [Clipboard requests](/configuration#clipboard-requests). ## Shell integration With Ghostty and a shell emitting OSC 133, `@shell-integration` receives the latest prompt, input, running, or completion state and the last reported exit code. Delivery continues while painting is paused; markers in one parser chunk coalesce into current state. See [Shell integration](/configuration#shell-integration) for the contract, shell setup, and workspace indicators. Use the underlying `WTerm` instance’s `scrollToPrompt(-1)` and `scrollToPrompt(1)` methods to navigate previous and next prompts in retained history. See [Shell integration](/configuration#shell-integration) for viewport behavior, unsupported cores, and inactive states. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) --- title: WebMCP url: "https://wterm.dev/webmcp" docs_index: /llms.txt lastUpdated: 2026-11-09 navTitle: "WebMCP" --- > For an index of all documentation, see [/llms.txt](/llms.txt). [WebMCP](https://github.com/webmachinelearning/webmcp) lets agents running in the browser call tools that a page registers. Turn on `webmcp` and agents can find the page's terminals, read them, type commands, and press keys. They don't have to scrape the DOM or fake keyboard events. WebMCP is off by default. In browsers without a WebMCP provider, the option does nothing. ## Try it The terminal on the [wterm.dev](https://wterm.dev) homepage is registered as `demo`. It runs a sandboxed bash in the page with [just-bash](/just-bash), so an agent can type into it without touching a real machine. With [agent-browser](https://github.com/vercel-labs/agent-browser), which turns on WebMCP in the Chrome it launches: ```bash agent-browser open https://wterm.dev agent-browser webmcp invoke type_in_terminal --params '{"terminal":"demo","text":"ls","submit":true}' agent-browser webmcp invoke read_terminal --params '{"terminal":"demo","waitForIdleMs":300}' ``` ## Enabling Pass `webmcp: true`, or an options object, when you create the terminal: ```ts import { WTerm } from "@wterm/dom"; const term = new WTerm(element, { webmcp: { name: "shell", description: "Project shell" }, onData: (data) => socket.send(data), }); await term.init(); ``` The framework components take the same value as a prop, and changes apply without restarting the terminal: ```tsx ``` ```vue ``` ```svelte ``` In vanilla JavaScript, call `term.setWebMCP(options)` to change the options later, or `term.setWebMCP(false)` to withdraw the terminal. Tools are registered once the terminal initializes and removed when it is destroyed. Withdrawing or destroying a terminal also ends any call still in progress for it, so a waiting `read_terminal` cannot return output written afterwards.

Option	Type	Default	Description
`name`	`string`	`"terminal"`	Name agents use to address the terminal. If another terminal on the page already uses it, a suffix is added ( `terminal-2` , `terminal-3` ) and a warning is logged.
`description`	`string`	—	What the terminal is for, returned by `list\_terminals` . It helps agents pick the right terminal.
`readOnly`	`boolean`	`false`	Agents can read the terminal but cannot type into it or press keys.

## Tools

Tool	Input	Description
`list\_terminals`	—	Every registered terminal with its name, description, `readOnly` , `focused` , size, cursor, alternate-screen state, scrollback row count, and, when reported, title, working directory, and shell integration state.
`read\_terminal`	`terminal?` , `lines?` , `waitFor?` , `waitForIdleMs?` , `timeoutMs?`	Plain text of the visible screen, or the last `lines` rows (up to 10,000), ending at the cursor or the last line of text and reaching into scrollback, plus the same state as `list\_terminals` . It can wait first; see below.
`type\_in\_terminal`	`terminal?` , `text` , `submit?`	Types text as if the user typed it, then presses Enter if `submit` is true. Enter comes 150 ms after the text, so programs that detect pastes by input speed, such as agent CLIs, don't treat it as a pasted newline. Multi-line text is pasted with bracketed paste when the program has enabled it. Otherwise, newlines are sent as Enter.
`press\_terminal\_keys`	`terminal?` , `keys`	Presses up to 64 keys in order, such as `"Ctrl+C"` , `"Enter"` , `"Shift+Tab"` , `"ArrowUp"` , `"F5"` , or a single character. Modifiers are `Ctrl` , `Alt` , `Shift` , and `Meta` . Keys are encoded for the program's current modes, including application cursor keys and the Kitty keyboard protocol. If any key name is unknown, nothing is pressed.

Input from agents follows the same path as keyboard input. It reaches `onData`, or is echoed locally when `onData` is not set, and it scrolls the terminal to the bottom. `type_in_terminal` and `press_terminal_keys` are registered only while at least one terminal accepts input. ### Waiting for output Programs answer asynchronously, so `read_terminal` can wait before it reads: - `waitFor`: wait until this exact text appears in the rows being read. Text that is already on screen counts, so pick text that only the new output will contain. - `waitForIdleMs`: wait until no output has arrived for this many milliseconds. With `waitFor`, the idle period starts once the text appears. - `timeoutMs`: the longest wait, 10,000 by default and at most 120,000. When it expires, the tool returns the current text with `timedOut: true` instead of failing. A typical agent turn types a command and then waits for it to finish: ```json { "tool": "type_in_terminal", "input": { "terminal": "shell", "text": "npm test", "submit": true } } { "tool": "read_terminal", "input": { "terminal": "shell", "waitFor": "Tests:", "waitForIdleMs": 500, "timeoutMs": 60000 } } ``` ### Results and errors Every tool returns a JSON string. When a call fails, for example because a terminal name is unknown, the terminal is read-only, or an argument is invalid, the result is `{"error": "..."}` and the tool does not throw. Browser providers drop the messages of thrown errors, so an in-band result like MCP's `isError` is the only way an agent can see what went wrong and fix its call. A wait that the agent cancels still rejects with the cancellation reason. ## Several terminals All terminals in a document share one set of tools, and each tool takes a `terminal` name. You can leave the name out when the page has one terminal, or when one terminal has focus. Otherwise the error lists the available names. Give each terminal a `name` and `description` so agents can tell them apart without trial and error. ## Security An agent that can call `type_in_terminal` can do anything the person at the keyboard can do. If the terminal is connected to a shell, a submitted command really runs. Enable `webmcp` only on terminals you want agents to drive, and use `readOnly: true` for terminals they should only watch, such as logs or build output. Terminal output comes from the programs running in it, so it can contain text written to mislead an agent. `list_terminals` and `read_terminal` set the `untrustedContentHint` annotation so agents treat their results as data, not instructions. ## Browser support wterm registers tools with `document.modelContext` or `navigator.modelContext`, whichever provides `registerTool`. It checks for a provider when the terminal initializes, so load any WebMCP polyfill before that. Earlier drafts of the API return a handle with `unregister()` from `registerTool`, and wterm supports those as well. ## Testing with agent-browser [agent-browser](https://github.com/vercel-labs/agent-browser) runs Chrome with WebMCP enabled and can call page tools directly: ```bash agent-browser open https://my-app.localhost agent-browser webmcp list agent-browser --json webmcp invoke type_in_terminal --params '{"text":"echo hello","submit":true}' agent-browser --json webmcp invoke read_terminal --params '{"waitFor":"hello","waitForIdleMs":200}' ``` --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt)

Build shell