react-xterm-shell 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noah Wardlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# react-xterm-shell
+
+> **Beta** — under active development; the API may change between minor versions until 1.0.
+
+A small React shell around [xterm.js](https://xtermjs.org/). It is a **React shell around xterm, not a React renderer for terminal cells** — xterm owns the grid, parsing, and rendering; this gives you the lifecycle, a stable imperative controller, automatic fitting, and opt-in addons as ordinary React.
+
+- `useXTerm()` — creates and owns the xterm instance behind a stable controller.
+- `<XTerm />` — the DOM mount point.
+- `TerminalProvider` / `useTerminalController()` — drive the terminal from chrome (toolbars) without prop drilling.
+- Automatic sizing via `FitAddon` + `ResizeObserver`.
+- Opt-in `webgl` (with DOM fallback), `web-links`, and `unicode11` addons, on by default.
+
+It does **not** include a transport — wire `onData`/`onResize` to your own WebSocket/PTY backend. That keeps the wrapper reusable across rosbridge, a PTY service, SSH, or a local shell.
+
+## Install
+
+```bash
+npm install react-xterm-shell @xterm/xterm react@^19
+```
+
+React 19 and `@xterm/xterm` are peer dependencies. Import the xterm stylesheet once in your app:
+
+```ts
+import "@xterm/xterm/css/xterm.css";
+```
+
+## Quick start
+
+```tsx
+import { useXTerm, XTerm } from "react-xterm-shell";
+import "@xterm/xterm/css/xterm.css";
+
+function TerminalPanel({ socket }: { socket: WebSocket }) {
+  const terminal = useXTerm({
+    onData: (data) => socket.send(JSON.stringify({ type: "input", data })),
+    onResize: ({ cols, rows }) =>
+      socket.send(JSON.stringify({ type: "resize", cols, rows })),
+    theme: { background: "#1a1b26", foreground: "#a9b1d6" }
+  });
+
+  // Stream server output into the terminal:
+  socket.onmessage = (e) => terminal.write(e.data);
+
+  return <XTerm terminal={terminal} style={{ width: "100%", height: 420 }} />;
+}
+```
+
+## Composition
+
+`useXTerm` returns a stable controller, so a toolbar can drive it imperatively
+without re-rendering as bytes stream:
+
+```tsx
+import { useXTerm, XTerm, TerminalProvider, useTerminalController } from "react-xterm-shell";
+
+function Toolbar() {
+  const term = useTerminalController();
+  return <button onClick={term.clear}>Clear</button>;
+}
+
+function Panel() {
+  const terminal = useXTerm({ onData: send });
+  return (
+    <TerminalProvider value={terminal}>
+      <Toolbar />
+      <XTerm terminal={terminal} className="h-[420px]" />
+    </TerminalProvider>
+  );
+}
+```
+
+## API
+
+### `useXTerm(options?) => XTermHandle`
+
+| Option | Type | Default | Notes |
+|--------|------|---------|-------|
+| `onData` | `(data: string) => void` | — | User keystrokes (xterm `onData`). |
+| `onResize` | `(size: { cols, rows }) => void` | — | Fires when the grid resizes. |
+| `theme` | `ITheme` | — | xterm color theme. |
+| `fontSize` | `number` | `13` | |
+| `scrollback` | `number` | `1000` | |
+| `cursorBlink` | `boolean` | `true` | |
+| `webgl` | `boolean` | `true` | GL renderer; falls back to DOM on context loss. |
+| `webLinks` | `boolean` | `true` | Clickable URLs. |
+| `unicode11` | `boolean` | `true` | Correct width for box-drawing / emoji. |
+| `options` | `ITerminalOptions` | — | Merged over the above. |
+| `addons` | `ITerminalAddon[]` | — | Extra addons (e.g. a search addon). |
+
+The returned `XTermHandle` has `attach` (the callback ref for `<XTerm>`), a live
+`term` getter, and `write` / `clear` / `focus` / `fit`. The handle is stable
+across renders; callbacks are read through refs, so passing fresh `onData` /
+`onResize` each render does not remount the terminal.
+
+### `<XTerm terminal={handle} className? style? />`
+
+Renders the mount element. The `terminal.attach` callback ref is the whole
+integration surface.
+
+## Addon notes
+
+`@xterm/addon-fit`, `-web-links`, `-unicode11`, and `-webgl` are bundled as
+dependencies and pinned to the xterm-5 line. WebGL loads after `open()` and is
+guarded: if the GL context is unavailable or lost, it disposes and the DOM
+renderer takes over. Disable any of them via the `webgl` / `webLinks` /
+`unicode11` options.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+import { Terminal, ITheme, ITerminalOptions, ITerminalAddon } from '@xterm/xterm';
+export { ITheme, Terminal } from '@xterm/xterm';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface UseXTermOptions {
+    /** Called with user keystrokes (xterm `onData`). Wire this to your transport. */
+    onData?: (data: string) => void;
+    /** Called when the rendered grid resizes (xterm `onResize`). */
+    onResize?: (size: {
+        cols: number;
+        rows: number;
+    }) => void;
+    /** xterm color theme. */
+    theme?: ITheme;
+    /** Font size in px. Default 13. */
+    fontSize?: number;
+    /** Scrollback lines retained. Default 1000. */
+    scrollback?: number;
+    /** Whether the cursor blinks. Default true. */
+    cursorBlink?: boolean;
+    /**
+     * Built-in addons, all enabled by default:
+     * - `webgl`: GL renderer with automatic DOM-renderer fallback on context loss.
+     * - `webLinks`: clickable URLs in output.
+     * - `unicode11`: correct width for box-drawing, spinners, and emoji.
+     */
+    webgl?: boolean;
+    webLinks?: boolean;
+    unicode11?: boolean;
+    /** Extra xterm options merged over the ones above. */
+    options?: ITerminalOptions;
+    /** Additional addons to load (e.g. a search addon). */
+    addons?: ITerminalAddon[];
+}
+/**
+ * Imperative controller for the terminal. Stable across renders, so passing it
+ * around (or into a context) never re-renders consumers as output streams. `term`
+ * is a live getter that returns the instance once attached, `null` before.
+ */
+interface TerminalController {
+    readonly term: Terminal | null;
+    write: (data: string | Uint8Array) => void;
+    clear: () => void;
+    focus: () => void;
+    fit: () => void;
+}
+type XTermHandle = TerminalController & {
+    /**
+     * Callback ref for the mount element. Creates the terminal on mount and
+     * disposes it when React clears the ref on unmount.
+     */
+    attach: (el: HTMLDivElement | null) => void;
+};
+
+/**
+ * A React shell around xterm.js. xterm owns the terminal grid and rendering;
+ * this hook owns the instance lifecycle and exposes a stable imperative
+ * controller so the surrounding tree can drive it without re-rendering as
+ * output streams.
+ *
+ * The instance is created lazily in the `attach` callback ref and disposed by
+ * the cleanup it returns. Sizing is automatic via a `ResizeObserver` + `FitAddon`.
+ *
+ * Import the stylesheet once in your app: `import "@xterm/xterm/css/xterm.css"`.
+ */
+declare function useXTerm(opts?: UseXTermOptions): XTermHandle;
+
+interface XTermProps {
+    /** The handle returned by `useXTerm`. */
+    terminal: XTermHandle;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Thin DOM mount point for an xterm instance. The `useXTerm` callback ref is the
+ * entire integration surface; this component just renders the host element.
+ */
+declare function XTerm({ terminal, className, style }: Readonly<XTermProps>): react.JSX.Element;
+
+/**
+ * Provides a terminal controller to descendants so chrome (toolbars, buttons)
+ * can drive the terminal imperatively without prop drilling.
+ */
+declare function TerminalProvider({ value, children }: Readonly<{
+    value: TerminalController;
+    children: ReactNode;
+}>): react.JSX.Element;
+/** Read the terminal controller from the nearest `TerminalProvider`. */
+declare function useTerminalController(): TerminalController;
+
+export { type TerminalController, TerminalProvider, type UseXTermOptions, XTerm, type XTermHandle, type XTermProps, useTerminalController, useXTerm };

package/dist/index.js

@@ -0,0 +1,125 @@
+import { createContext, useRef, useEffect, useCallback, useMemo, useContext } from 'react';
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import { WebLinksAddon } from '@xterm/addon-web-links';
+import { Unicode11Addon } from '@xterm/addon-unicode11';
+import { WebglAddon } from '@xterm/addon-webgl';
+import { jsx } from 'react/jsx-runtime';
+
+// src/use-xterm.ts
+var DEFAULT_FONT_SIZE = 13;
+var DEFAULT_SCROLLBACK = 1e3;
+function useXTerm(opts = {}) {
+  const {
+    onData,
+    onResize,
+    theme,
+    fontSize,
+    scrollback,
+    cursorBlink,
+    webgl = true,
+    webLinks = true,
+    unicode11 = true,
+    options,
+    addons
+  } = opts;
+  const termRef = useRef(null);
+  const fitRef = useRef(null);
+  const cleanupRef = useRef(null);
+  const onDataRef = useRef(onData);
+  const onResizeRef = useRef(onResize);
+  useEffect(() => {
+    onDataRef.current = onData;
+    onResizeRef.current = onResize;
+  }, [onData, onResize]);
+  const extraAddons = useRef(addons);
+  extraAddons.current = addons;
+  const attach = useCallback(
+    (el) => {
+      if (!el) {
+        cleanupRef.current?.();
+        cleanupRef.current = null;
+        return;
+      }
+      if (termRef.current) return;
+      const term = new Terminal({
+        cursorBlink: cursorBlink ?? true,
+        fontSize: fontSize ?? DEFAULT_FONT_SIZE,
+        theme,
+        scrollback: scrollback ?? DEFAULT_SCROLLBACK,
+        allowProposedApi: true,
+        ...options
+      });
+      const fit = new FitAddon();
+      term.loadAddon(fit);
+      if (webLinks) term.loadAddon(new WebLinksAddon());
+      if (unicode11) {
+        term.loadAddon(new Unicode11Addon());
+        term.unicode.activeVersion = "11";
+      }
+      for (const addon of extraAddons.current ?? []) {
+        term.loadAddon(addon);
+      }
+      term.open(el);
+      if (webgl) {
+        try {
+          const webglAddon = new WebglAddon();
+          webglAddon.onContextLoss(() => webglAddon.dispose());
+          term.loadAddon(webglAddon);
+        } catch {
+        }
+      }
+      fit.fit();
+      const disposables = [
+        term.onData((data) => onDataRef.current?.(data)),
+        term.onResize((size) => onResizeRef.current?.(size))
+      ];
+      const resizeObserver = new ResizeObserver(() => fit.fit());
+      resizeObserver.observe(el);
+      termRef.current = term;
+      fitRef.current = fit;
+      cleanupRef.current = () => {
+        resizeObserver.disconnect();
+        disposables.forEach((d) => d.dispose());
+        term.dispose();
+        termRef.current = null;
+        fitRef.current = null;
+      };
+    },
+    [theme, fontSize, scrollback, cursorBlink, webgl, webLinks, unicode11, options]
+  );
+  return useMemo(
+    () => ({
+      get term() {
+        return termRef.current;
+      },
+      write: (data) => termRef.current?.write(data),
+      clear: () => termRef.current?.clear(),
+      focus: () => termRef.current?.focus(),
+      fit: () => fitRef.current?.fit(),
+      attach
+    }),
+    [attach]
+  );
+}
+function XTerm({ terminal, className, style }) {
+  return /* @__PURE__ */ jsx("div", { ref: terminal.attach, className, style });
+}
+var TerminalContext = createContext(null);
+function TerminalProvider({
+  value,
+  children
+}) {
+  return /* @__PURE__ */ jsx(TerminalContext.Provider, { value, children });
+}
+function useTerminalController() {
+  const ctx = useContext(TerminalContext);
+  if (!ctx) {
+    throw new Error("useTerminalController must be used within a <TerminalProvider>");
+  }
+  return ctx;
+}
+
+export { TerminalProvider, XTerm, useTerminalController, useXTerm };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/use-xterm.ts","../src/xterm.tsx","../src/context.tsx"],"names":["jsx"],"mappings":"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","file":"index.js","sourcesContent":["import { useCallback, useEffect, useMemo, useRef } from \"react\";\nimport { Terminal } from \"@xterm/xterm\";\nimport { FitAddon } from \"@xterm/addon-fit\";\nimport { WebLinksAddon } from \"@xterm/addon-web-links\";\nimport { Unicode11Addon } from \"@xterm/addon-unicode11\";\nimport { WebglAddon } from \"@xterm/addon-webgl\";\n\nimport type { UseXTermOptions, XTermHandle } from \"./types\";\n\nconst DEFAULT_FONT_SIZE = 13;\nconst DEFAULT_SCROLLBACK = 1000;\n\n/**\n * A React shell around xterm.js. xterm owns the terminal grid and rendering;\n * this hook owns the instance lifecycle and exposes a stable imperative\n * controller so the surrounding tree can drive it without re-rendering as\n * output streams.\n *\n * The instance is created lazily in the `attach` callback ref and disposed by\n * the cleanup it returns. Sizing is automatic via a `ResizeObserver` + `FitAddon`.\n *\n * Import the stylesheet once in your app: `import \"@xterm/xterm/css/xterm.css\"`.\n */\nexport function useXTerm(opts: UseXTermOptions = {}): XTermHandle {\n  const {\n    onData,\n    onResize,\n    theme,\n    fontSize,\n    scrollback,\n    cursorBlink,\n    webgl = true,\n    webLinks = true,\n    unicode11 = true,\n    options,\n    addons\n  } = opts;\n\n  const termRef = useRef<Terminal | null>(null);\n  const fitRef = useRef<FitAddon | null>(null);\n  const cleanupRef = useRef<(() => void) | null>(null);\n\n  // Latest callbacks live in refs so `attach` does not depend on their identity.\n  // Otherwise a parent passing fresh callbacks each render would change `attach`,\n  // and the callback ref would dispose and recreate the terminal (wiping\n  // scrollback). The xterm handlers read the refs, so no stale-closure risk.\n  const onDataRef = useRef(onData);\n  const onResizeRef = useRef(onResize);\n  useEffect(() => {\n    onDataRef.current = onData;\n    onResizeRef.current = onResize;\n  }, [onData, onResize]);\n\n  // Snapshot the addon set + extra addons so identity churn does not remount.\n  const extraAddons = useRef(addons);\n  extraAddons.current = addons;\n\n  const attach = useCallback(\n    (el: HTMLDivElement | null) => {\n      if (!el) {\n        cleanupRef.current?.();\n        cleanupRef.current = null;\n        return;\n      }\n      if (termRef.current) return;\n\n      const term = new Terminal({\n        cursorBlink: cursorBlink ?? true,\n        fontSize: fontSize ?? DEFAULT_FONT_SIZE,\n        theme,\n        scrollback: scrollback ?? DEFAULT_SCROLLBACK,\n        allowProposedApi: true,\n        ...options\n      });\n\n      const fit = new FitAddon();\n      term.loadAddon(fit);\n\n      if (webLinks) term.loadAddon(new WebLinksAddon());\n      if (unicode11) {\n        term.loadAddon(new Unicode11Addon());\n        term.unicode.activeVersion = \"11\";\n      }\n      for (const addon of extraAddons.current ?? []) {\n        term.loadAddon(addon);\n      }\n\n      term.open(el);\n\n      // WebGL must load after open(); fall back to the DOM renderer if the GL\n      // context is unavailable or lost.\n      if (webgl) {\n        try {\n          const webglAddon = new WebglAddon();\n          webglAddon.onContextLoss(() => webglAddon.dispose());\n          term.loadAddon(webglAddon);\n        } catch {\n          // No WebGL (headless/software GL); the DOM renderer remains active.\n        }\n      }\n\n      fit.fit();\n\n      const disposables = [\n        term.onData((data) => onDataRef.current?.(data)),\n        term.onResize((size) => onResizeRef.current?.(size))\n      ];\n\n      const resizeObserver = new ResizeObserver(() => fit.fit());\n      resizeObserver.observe(el);\n\n      termRef.current = term;\n      fitRef.current = fit;\n\n      cleanupRef.current = () => {\n        resizeObserver.disconnect();\n        disposables.forEach((d) => d.dispose());\n        term.dispose();\n        termRef.current = null;\n        fitRef.current = null;\n      };\n    },\n    [theme, fontSize, scrollback, cursorBlink, webgl, webLinks, unicode11, options]\n  );\n\n  // One stable handle. `term` is a live getter — spreading it into a static\n  // object would freeze it to the null it holds before attach. Methods read the\n  // refs, so the handle is stable while the instance comes and goes.\n  return useMemo<XTermHandle>(\n    () => ({\n      get term() {\n        return termRef.current;\n      },\n      write: (data) => termRef.current?.write(data),\n      clear: () => termRef.current?.clear(),\n      focus: () => termRef.current?.focus(),\n      fit: () => fitRef.current?.fit(),\n      attach\n    }),\n    [attach]\n  );\n}\n","import type { XTermHandle } from \"./types\";\n\nexport interface XTermProps {\n  /** The handle returned by `useXTerm`. */\n  terminal: XTermHandle;\n  className?: string;\n  style?: React.CSSProperties;\n}\n\n/**\n * Thin DOM mount point for an xterm instance. The `useXTerm` callback ref is the\n * entire integration surface; this component just renders the host element.\n */\nexport function XTerm({ terminal, className, style }: Readonly<XTermProps>) {\n  return <div ref={terminal.attach} className={className} style={style} />;\n}\n","import { createContext, useContext } from \"react\";\nimport type { ReactNode } from \"react\";\n\nimport type { TerminalController } from \"./types\";\n\nconst TerminalContext = createContext<TerminalController | null>(null);\n\n/**\n * Provides a terminal controller to descendants so chrome (toolbars, buttons)\n * can drive the terminal imperatively without prop drilling.\n */\nexport function TerminalProvider({\n  value,\n  children\n}: Readonly<{ value: TerminalController; children: ReactNode }>) {\n  return (\n    <TerminalContext.Provider value={value}>{children}</TerminalContext.Provider>\n  );\n}\n\n/** Read the terminal controller from the nearest `TerminalProvider`. */\nexport function useTerminalController(): TerminalController {\n  const ctx = useContext(TerminalContext);\n  if (!ctx) {\n    throw new Error(\"useTerminalController must be used within a <TerminalProvider>\");\n  }\n  return ctx;\n}\n"]}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "react-xterm-shell",
+  "version": "0.1.0",
+  "description": "A small React shell around xterm.js: a useXTerm hook + XTerm component with a stable imperative controller, automatic fitting, and opt-in webgl/web-links/unicode11 addons.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "xterm",
+    "xterm.js",
+    "react",
+    "terminal",
+    "pty",
+    "webgl",
+    "hook",
+    "component"
+  ],
+  "license": "MIT",
+  "author": "Noah Wardlow",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/noah-wardlow/react-xterm-shell"
+  },
+  "bugs": {
+    "url": "https://github.com/noah-wardlow/react-xterm-shell/issues"
+  },
+  "homepage": "https://github.com/noah-wardlow/react-xterm-shell#readme",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "release": "semantic-release",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run typecheck && pnpm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@xterm/xterm": ">=5",
+    "react": ">=19"
+  },
+  "dependencies": {
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-unicode11": "^0.8.0",
+    "@xterm/addon-web-links": "^0.11.0",
+    "@xterm/addon-webgl": "^0.18.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/react": "^19.0.0",
+    "@xterm/xterm": "^5.5.0",
+    "react": "^19.2.0",
+    "semantic-release": "^25.0.3",
+    "tsup": "^8.4.0",
+    "typescript": "~5.8.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.30.0"
+}

package/src/context.tsx

@@ -0,0 +1,28 @@
+import { createContext, useContext } from "react";
+import type { ReactNode } from "react";
+
+import type { TerminalController } from "./types";
+
+const TerminalContext = createContext<TerminalController | null>(null);
+
+/**
+ * Provides a terminal controller to descendants so chrome (toolbars, buttons)
+ * can drive the terminal imperatively without prop drilling.
+ */
+export function TerminalProvider({
+  value,
+  children
+}: Readonly<{ value: TerminalController; children: ReactNode }>) {
+  return (
+    <TerminalContext.Provider value={value}>{children}</TerminalContext.Provider>
+  );
+}
+
+/** Read the terminal controller from the nearest `TerminalProvider`. */
+export function useTerminalController(): TerminalController {
+  const ctx = useContext(TerminalContext);
+  if (!ctx) {
+    throw new Error("useTerminalController must be used within a <TerminalProvider>");
+  }
+  return ctx;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { useXTerm } from "./use-xterm";
+export { XTerm } from "./xterm";
+export type { XTermProps } from "./xterm";
+export { TerminalProvider, useTerminalController } from "./context";
+export type {
+  UseXTermOptions,
+  TerminalController,
+  XTermHandle
+} from "./types";
+
+// Convenience re-export so consumers can type a theme without a direct
+// @xterm/xterm import.
+export type { ITheme, Terminal } from "@xterm/xterm";

package/src/types.ts

@@ -0,0 +1,55 @@
+import type {
+  ITheme,
+  ITerminalOptions,
+  ITerminalAddon,
+  Terminal
+} from "@xterm/xterm";
+
+export interface UseXTermOptions {
+  /** Called with user keystrokes (xterm `onData`). Wire this to your transport. */
+  onData?: (data: string) => void;
+  /** Called when the rendered grid resizes (xterm `onResize`). */
+  onResize?: (size: { cols: number; rows: number }) => void;
+  /** xterm color theme. */
+  theme?: ITheme;
+  /** Font size in px. Default 13. */
+  fontSize?: number;
+  /** Scrollback lines retained. Default 1000. */
+  scrollback?: number;
+  /** Whether the cursor blinks. Default true. */
+  cursorBlink?: boolean;
+  /**
+   * Built-in addons, all enabled by default:
+   * - `webgl`: GL renderer with automatic DOM-renderer fallback on context loss.
+   * - `webLinks`: clickable URLs in output.
+   * - `unicode11`: correct width for box-drawing, spinners, and emoji.
+   */
+  webgl?: boolean;
+  webLinks?: boolean;
+  unicode11?: boolean;
+  /** Extra xterm options merged over the ones above. */
+  options?: ITerminalOptions;
+  /** Additional addons to load (e.g. a search addon). */
+  addons?: ITerminalAddon[];
+}
+
+/**
+ * Imperative controller for the terminal. Stable across renders, so passing it
+ * around (or into a context) never re-renders consumers as output streams. `term`
+ * is a live getter that returns the instance once attached, `null` before.
+ */
+export interface TerminalController {
+  readonly term: Terminal | null;
+  write: (data: string | Uint8Array) => void;
+  clear: () => void;
+  focus: () => void;
+  fit: () => void;
+}
+
+export type XTermHandle = TerminalController & {
+  /**
+   * Callback ref for the mount element. Creates the terminal on mount and
+   * disposes it when React clears the ref on unmount.
+   */
+  attach: (el: HTMLDivElement | null) => void;
+};

package/src/use-xterm.ts

@@ -0,0 +1,142 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { Terminal } from "@xterm/xterm";
+import { FitAddon } from "@xterm/addon-fit";
+import { WebLinksAddon } from "@xterm/addon-web-links";
+import { Unicode11Addon } from "@xterm/addon-unicode11";
+import { WebglAddon } from "@xterm/addon-webgl";
+
+import type { UseXTermOptions, XTermHandle } from "./types";
+
+const DEFAULT_FONT_SIZE = 13;
+const DEFAULT_SCROLLBACK = 1000;
+
+/**
+ * A React shell around xterm.js. xterm owns the terminal grid and rendering;
+ * this hook owns the instance lifecycle and exposes a stable imperative
+ * controller so the surrounding tree can drive it without re-rendering as
+ * output streams.
+ *
+ * The instance is created lazily in the `attach` callback ref and disposed by
+ * the cleanup it returns. Sizing is automatic via a `ResizeObserver` + `FitAddon`.
+ *
+ * Import the stylesheet once in your app: `import "@xterm/xterm/css/xterm.css"`.
+ */
+export function useXTerm(opts: UseXTermOptions = {}): XTermHandle {
+  const {
+    onData,
+    onResize,
+    theme,
+    fontSize,
+    scrollback,
+    cursorBlink,
+    webgl = true,
+    webLinks = true,
+    unicode11 = true,
+    options,
+    addons
+  } = opts;
+
+  const termRef = useRef<Terminal | null>(null);
+  const fitRef = useRef<FitAddon | null>(null);
+  const cleanupRef = useRef<(() => void) | null>(null);
+
+  // Latest callbacks live in refs so `attach` does not depend on their identity.
+  // Otherwise a parent passing fresh callbacks each render would change `attach`,
+  // and the callback ref would dispose and recreate the terminal (wiping
+  // scrollback). The xterm handlers read the refs, so no stale-closure risk.
+  const onDataRef = useRef(onData);
+  const onResizeRef = useRef(onResize);
+  useEffect(() => {
+    onDataRef.current = onData;
+    onResizeRef.current = onResize;
+  }, [onData, onResize]);
+
+  // Snapshot the addon set + extra addons so identity churn does not remount.
+  const extraAddons = useRef(addons);
+  extraAddons.current = addons;
+
+  const attach = useCallback(
+    (el: HTMLDivElement | null) => {
+      if (!el) {
+        cleanupRef.current?.();
+        cleanupRef.current = null;
+        return;
+      }
+      if (termRef.current) return;
+
+      const term = new Terminal({
+        cursorBlink: cursorBlink ?? true,
+        fontSize: fontSize ?? DEFAULT_FONT_SIZE,
+        theme,
+        scrollback: scrollback ?? DEFAULT_SCROLLBACK,
+        allowProposedApi: true,
+        ...options
+      });
+
+      const fit = new FitAddon();
+      term.loadAddon(fit);
+
+      if (webLinks) term.loadAddon(new WebLinksAddon());
+      if (unicode11) {
+        term.loadAddon(new Unicode11Addon());
+        term.unicode.activeVersion = "11";
+      }
+      for (const addon of extraAddons.current ?? []) {
+        term.loadAddon(addon);
+      }
+
+      term.open(el);
+
+      // WebGL must load after open(); fall back to the DOM renderer if the GL
+      // context is unavailable or lost.
+      if (webgl) {
+        try {
+          const webglAddon = new WebglAddon();
+          webglAddon.onContextLoss(() => webglAddon.dispose());
+          term.loadAddon(webglAddon);
+        } catch {
+          // No WebGL (headless/software GL); the DOM renderer remains active.
+        }
+      }
+
+      fit.fit();
+
+      const disposables = [
+        term.onData((data) => onDataRef.current?.(data)),
+        term.onResize((size) => onResizeRef.current?.(size))
+      ];
+
+      const resizeObserver = new ResizeObserver(() => fit.fit());
+      resizeObserver.observe(el);
+
+      termRef.current = term;
+      fitRef.current = fit;
+
+      cleanupRef.current = () => {
+        resizeObserver.disconnect();
+        disposables.forEach((d) => d.dispose());
+        term.dispose();
+        termRef.current = null;
+        fitRef.current = null;
+      };
+    },
+    [theme, fontSize, scrollback, cursorBlink, webgl, webLinks, unicode11, options]
+  );
+
+  // One stable handle. `term` is a live getter — spreading it into a static
+  // object would freeze it to the null it holds before attach. Methods read the
+  // refs, so the handle is stable while the instance comes and goes.
+  return useMemo<XTermHandle>(
+    () => ({
+      get term() {
+        return termRef.current;
+      },
+      write: (data) => termRef.current?.write(data),
+      clear: () => termRef.current?.clear(),
+      focus: () => termRef.current?.focus(),
+      fit: () => fitRef.current?.fit(),
+      attach
+    }),
+    [attach]
+  );
+}

package/src/xterm.tsx

@@ -0,0 +1,16 @@
+import type { XTermHandle } from "./types";
+
+export interface XTermProps {
+  /** The handle returned by `useXTerm`. */
+  terminal: XTermHandle;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+/**
+ * Thin DOM mount point for an xterm instance. The `useXTerm` callback ref is the
+ * entire integration surface; this component just renders the host element.
+ */
+export function XTerm({ terminal, className, style }: Readonly<XTermProps>) {
+  return <div ref={terminal.attach} className={className} style={style} />;
+}