wterm

Core / Advanced

@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.

Install

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

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 ~12 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.

See the full WasmBridge reference for all methods, types, and scrollback APIs.

Example

Headless usage — load the bridge, write data, and read cells back:

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 }

WebSocketTransport

Connect to a PTY backend over WebSocket with automatic reconnection and send buffering.

See the full WebSocketTransport reference for all options, methods, and properties.

Example

Connecting a terminal to a remote shell via WebSocket:

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) => ws.send(data);

For a full working example with a Node.js PTY server, see the Local Shell example.