opentui Documentation

Technical Documentation: anomalyco/opentui

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

OpenTUI is a library to build terminal user interfaces.

• It is written in Zig.
• You write TypeScript directly or through React and Solid.
• You arrange boxes and text with flexbox.
• You add selects, inputs, and scroll boxes with keyboard and mouse controls.
• You can play sounds, show images, and render 3D graphics.

OpenCode uses OpenTUI in production for millions of users.

Website | Documentation | Packages

Packages Copy Chapter

• @opentui/core - Native terminal UI library with TypeScript bindings.
• @opentui/react - React renderer for building terminal user interfaces with OpenTUI Core.
• @opentui/solid - Solid renderer for building terminal user interfaces with OpenTUI Core.
• @opentui/keymap - Key binding and command routing library for terminal and browser applications.
• @opentui/qrcode - QR code encoder and renderable with React and Solid surfaces.
• @opentui/three - Three.js WebGPU renderer for OpenTUI.
• @opentui/ssh - SSH server integration for OpenTUI applications.

Private packages

• @opentui/native - Private workspace with the Zig implementation, native tests, and benchmarks.
• @opentui/examples - Private workspace with example applications and a standalone examples executable.
• @opentui/web - Private workspace with the documentation website and the AI agent skill.

AI agent skill Copy Chapter

Install the OpenTUI documentation as a skill for your AI coding assistant with npx skills:

npx skills add https://opentui.com --skill opentui

Add -g to install the skill globally. The skill matches the latest release, and npx skills update moves it to each
new release. Install from https://opentui.com/docs/next to follow the main branch. A skill installed with
npx skills add anomalyco/opentui follows the main branch; run the command above to switch it to releases.

Development Copy Chapter

Development requires Bun 1.4.1 or later and Zig 0.16.0.

See AGENTS.md for engineering, tooling, and verification conventions.

bun install

Run package scripts from their package directory. Run bun run build from the repository root after you change
native code or cross-package build outputs. Ordinary TypeScript changes do not require a root build.

Run repository tests and static checks from the repository root:

bun run test
bun run fmt:check
bun run lint

To link the source packages into a Bun-managed project, install that project's dependencies, then run
./scripts/link-opentui-dev.sh /path/to/project from the repository root. Add --react or --solid when needed.

Contributing Copy Chapter

OpenTUI is open for contributions.

License Copy Chapter

OpenTUI is licensed under the MIT License.

Overview (`api/README.md`) Copy Section

API history

Each <version>.txt file records how the API of the published @opentui/* packages and of the C ABI in
packages/native/include/opentui.h changed in that release. The documentation site reads these files to show when
each feature was added, changed, deprecated, or removed.

A file exists for every stable release from the oldest file on. A release without API changes has a file with only
the header.

Format Copy Chapter

base 0.5.14
- @opentui/core: method DiffRenderable.destroyRecursively(): void
+ @opentui/core: protected method DiffRenderable.destroySelf(): void
- @opentui/solid: method SlotRenderable.getSlotChild(parent: BaseRenderable): TextSlotRenderable | LayoutSlotRenderable
+ @opentui/solid: method SlotRenderable.getSlotChild(parent: BaseRenderable): LayoutSlotRenderable | TextSlotRenderable

The first line names the release that the file is relative to: base <version>. Usually the base is the previous
release. A patch of an older line names the release it was made from. The oldest file is a snapshot: base none,
and every feature of its release as a + line.

Each other line adds (+) or removes (-) one feature. A changed signature is a - line and a + line with the
same key. The API of a release is the API of its base, without the - lines, with the + lines.

Lines are sorted by key, then - before +, then by text. A key is <module>: <kind> <name>.

Features Copy Chapter

<module>: [<modifier> ...]<kind> <name><signature>

• <module> is the npm specifier of an entry point, such as @opentui/core or @opentui/core/testing. Each subpath
  of a package's exports map with a types target is an entry point. A feature exported by two entry points has a
  line for each. The module of the C ABI is opentui.h.
• <modifier> is deprecated (JSDoc @deprecated), static, protected, abstract, or readonly, in that order.
• <kind> is class, interface, type, function, const, let, enum, enum-member, namespace,
  constructor, method, property, call, construct, index, or reexport. The C ABI also uses struct and
  field.
• <name> is the export name. A member name includes its owner: CliRenderer.suspend, Yoga.Node.create. A
  constructor, call, construct, or index signature uses the owner's name. A default export is default.
• <signature> is the declaration syntax after the name, from the published .d.ts files. Comments are removed,
  whitespace is collapsed, and import("…").X is written as X.

Members are the own members of a class or interface. Inherited members are not repeated; the extends clause is on
the class line. Private, #private, and @internal members are left out. So are public members whose name starts
with _. Protected members, including _ names, are API because users subclass renderables. Getters and setters
are properties; a getter without a setter is readonly. Each overload has its own line.

An export * as X of a module in the package records namespace X and its members as X.member. An export from
another package records only the export: namespace THREE from "three", reexport createElement from "react", or
reexport * from "react". A renamed export from another package ends with as <original name>.

The C ABI Copy Chapter

opentui.h: function ot_scene_move_node(ot_context *, const ot_handle *node, const ot_handle *parent, uint32_t index): ot_status
opentui.h: type ot_status = int32_t
opentui.h: type ot_scene_measure_callback = void (*)(uint64_t context_id, uint32_t slot, …, float *out_size)
opentui.h: type ot_context = struct ot_context
opentui.h: struct ot_handle
opentui.h: field ot_handle.slot: uint32_t, offset 8
opentui.h: const OT_INVALID_ARGUMENT = -1

The lines of opentui.h record each declaration whose name starts with ot_ or OT_:

• A function is function, with its parameters as the header declares them and its return type after a colon.
• A typedef of a function pointer, an integer, or an incomplete struct is type, with the C type after =.
• A struct is struct, and each of its fields is field <struct>.<field>: <type>, offset . A field that moves
  is a change, so a line shows a layout change even when the field keeps its name and type.
• An object-like macro is const, with its integer value.

Types keep the header's spelling, with whitespace collapsed. The field offsets and macro values come from
packages/core/src/native-abi.generated.ts, which bun run check:abi in packages/core derives from the header with
the C compiler.

A release's C ABI is its commit's header: the C ABI is used from a source checkout, not from an npm package.

Commands Copy Chapter

Run these from the repository root.

• bun packages/web/scripts/api.ts release <version> writes api/<version>.txt: the difference between the latest
  file's API and the API of the source tree. scripts/release.ts runs it in the release commit. It does not
  overwrite a file with different contents. Pass --base <version> for a patch of an older line.
• bun packages/web/scripts/api.ts verify <version> compares the API that the files record for a release with its
  packages on npm. The release workflow runs it after npm serves the release. The C ABI is not on npm, so it is left
  out.
• bun packages/web/scripts/api.ts diff prints the file that a release of the source tree would add.
• bun packages/web/scripts/api.ts current prints every feature of the source tree.
• bun packages/web/scripts/api.ts check validates the files.
• bun packages/web/scripts/api.ts backfill [--from <version>] [--to <version>] writes the files of published
  releases from their npm tarballs and the header at their tags, from the oldest file on. It rewrites only files that
  changed. Run it after a change to the extractor. A release without a tag has no C ABI.
• bun packages/web/scripts/api.ts squash <version> starts the history at a release: its file becomes a snapshot,
  and the files of older releases go. The API that the files record for the kept releases stays the same; the site
  stops listing the older releases and the versions that added their features. Run it when nobody uses the older
  lines.

The source commands run tsc declaration emit for each package into a temporary directory, with the exports map that
the package's scripts/build.ts publishes. They do not run the package builds. The extractor reads those
declarations in the same way as a tarball, so a source tree at a release tag gives the API of that release. They read
the source tree's header for the C ABI.

Overview (`packages/core/README.md`) Copy Section

OpenTUI is a library to build terminal user interfaces.

• It is written in Zig.
• You write TypeScript directly or through React and Solid.
• You arrange boxes and text with flexbox.
• You add selects, inputs, and scroll boxes with keyboard and mouse controls.
• You can play sounds, show images, and render 3D graphics.

OpenCode uses OpenTUI in production for millions of users.

Website | Documentation | Packages

OpenTUI Core Copy Chapter

@opentui/core supplies the renderer and TypeScript API. You use imperative renderables and events directly. The
TypeScript packages call native Zig through an internal foreign function interface (FFI) boundary.

import { TextRenderable, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer({ exitOnCtrlC: true })

renderer.root.add(new TextRenderable(renderer, { content: "Hello, OpenTUI!" }))

exitOnCtrlC: true calls renderer.destroy() when the user presses Ctrl+C. The code that creates the renderer must
call renderer.destroy() on every other shutdown path.

Install the package:

bun add @opentui/core

Then build your first app with the quickstart.

Runtime and platform support Copy Chapter

@opentui/core runs on Bun 1.3.14 or later, or on Node.js 26.4.0 or later with ECMAScript modules (ESM) and
--experimental-ffi.

Use Bun 1.4.0 or later on native Windows arm64.

The native ABI and the generated platform packages, such as @opentui/core-linux-x64, are internal distribution
surfaces, not application APIs.

AI agent skill Copy Chapter

Install the OpenTUI documentation as a skill for your AI coding assistant with npx skills:

npx skills add https://opentui.com --skill opentui

Add -g to install the skill globally. The skill matches the latest release, and npx skills update moves it to each
new release. Install from https://opentui.com/docs/next to follow the main branch. A skill installed with
npx skills add anomalyco/opentui follows the main branch; run the command above to switch it to releases.

License Copy Chapter

OpenTUI is licensed under the MIT License.

Overview (`packages/keymap/README.md`) Copy Section

@opentui/keymap

A host-agnostic keymap engine for terminal and DOM apps. Same core, multiple adapters.

It models keybindings as priority-ordered, focus-scoped layers attached to targets (terminal renderables or DOM elements). The core is intentionally bare; everything beyond raw key dispatch is opt-in via addons, parsers, expanders, resolvers, and field compilers.

Highlights Copy Chapter

• Host-agnostic core over a small KeymapHost interface with host metadata, focus, parent traversal, target destruction, key press/release, optional raw input, and synthetic command events.
• Target-aware focus routing for global layers plus local focus / focus-within layers that follow the active target's parent chain.
• Layered bindings with priority ordering, newest-first ties, fallthrough, and preventDefault control.
• Branch-aware multi-key sequences over flat compiled bindings, with a public pending-sequence API, synchronous pendingSequence events, active continuation queries, and automatic invalidation on focus changes.
• Programmable exact-vs-prefix disambiguation (e.g. g vs gg) with runExact, continueSequence, clear, and deferred AbortSignal + sleep decisions. Ships a Neovim-style timeout resolver.
• Pluggable binding language: stackable binding parsers, key expanders, layer-binding transformers, binding transformers, command resolvers, command transformers, and ordered event-match resolvers.
• Extensible schema and activation: register custom fields on layers, bindings, and commands. Field compilers can emit attrs; all field kinds can gate activation via require(...) and activeWhen(matcher).
• Reactive matchers with subscription-driven state notifications, plus React store and Solid signal helpers.
• Raw and key intercepts before and after normal binding dispatch, including pre-binding consume({ preventDefault, stopPropagation }), post-dispatch handled/no-match outcomes, and raw input stop() handling.
• Command catalog and dispatch with named commands, inline command handlers, command chains, namespaces, search, visibility tiers (registered / reachable / active), binding queries, runCommand, and focus-aware dispatchCommand.
• Opt-in graph snapshots and diagnostics for layers, commands, bindings, sequence nodes, pending paths, inactive reasons, shadowing, stable warning/error codes, and lint-style layer analyzers.
• Broad key coverage in the default parser, including function keys, navigation/editing keys, numpad keys, media keys, left/right modifiers, super, hyper, and literal + bindings.
• Platform-aware modifier aliases via registerModBindings, resolving mod+... from host metadata while preserving display strings.

Addons Copy Chapter

@opentui/keymap/addons ships ready-made building blocks:

• registerDefaultKeys — ctrl+shift+s style parser and event matching.
• registerLeader, registerTimedLeader — leader tokens with optional timeout.
• registerEmacsBindings — ctrl+x ctrl+s chords.
• registerExCommands — :write-style commands with aliases and nargs.
• registerCommaBindings, registerModBindings, registerAliasesField, registerBindingOverrides.
• registerEnabledFields, registerMetadataFields (desc, group, title, category).
• registerNeovimDisambiguation, registerEscapeClearsPendingSequence, registerBackspacePopsPendingSequence.
• registerDeadBindingWarnings, registerUnresolvedCommandWarnings.

@opentui/keymap/addons/opentui adds OpenTUI-specific pieces: base-layout matching via event.baseCode for non-Latin keys and the digit row (the same rule as Core), and pre-wired textarea / edit-buffer commands. Direct event matches win before fallback matches, even across layers.

Entry Points Copy Chapter

• @opentui/keymap — core API
• @opentui/keymap/addons — universal addons
• @opentui/keymap/addons/opentui — universal + OpenTUI addons
• @opentui/keymap/extras/graph — graph snapshot helpers for debug and graph UIs
• @opentui/keymap/testing — host-agnostic fake keymap host and diagnostics for addon tests
• @opentui/keymap/html — HTML adapter
• @opentui/keymap/opentui — OpenTUI adapter
• @opentui/keymap/react — KeymapProvider, useKeymap, useBindings, useActiveKeys, usePendingSequence, reactiveMatcherFromStore
• @opentui/keymap/solid — KeymapProvider, useKeymap, useKeymapSelector, useBindings, reactiveMatcherFromSignal
• @opentui/keymap/extras — helpers for cheat-sheet UIs (createBindingLookup, commandBindings, formatCommandBindings)

Usage Copy Chapter

import { registerDefaultKeys } from "@opentui/keymap/addons"
import { createOpenTuiKeymap } from "@opentui/keymap/opentui"
import { KeymapProvider } from "@opentui/keymap/react"

const keymap = createOpenTuiKeymap(renderer)
registerDefaultKeys(keymap)

createRoot(renderer).render(
  <KeymapProvider keymap={keymap}>
    <App />
  </KeymapProvider>,
)

Create a keymap, install the addons you want, then pass the configured instance to your app. The React and Solid entrypoints consume a pre-created OpenTUI keymap through context.

Keymap is the core runtime. Pass feature factories to its constructor when you need graph snapshots or layer analyzers.

Adapters Copy Chapter

Adapters implement a small KeymapHost interface (metadata, rootTarget, getFocusedTarget, getParentTarget, onKeyPress, onKeyRelease, onFocusChange, onTargetDestroy, ...). The HTML adapter normalizes DOM key names (Escape → escape, ArrowUp → up, Meta → super, Alt → meta) and tracks targets via MutationObserver. The OpenTUI adapter hooks CliRenderer keypress, keyrelease, focus, destroy, target destroy, and raw input events.

Formatting Keys Copy Chapter

Use keymap.formatKey when displaying raw binding strings. It runs them through the keymap's parsers and tokens before stringifying.

keymap.formatKey("<leader>s", { separator: " " }) // "space s"
keymap.formatKey("<leader>s", { preferDisplay: true }) // "<leader>s"

Re-entry Copy Chapter

Runtime/data re-entry is supported during dispatch: command handlers, intercepts, and pending-sequence listeners may read or write runtime data and pending-sequence state.

Structural re-entry is not supported. Do not register or unregister layers, tokens, parsers, or resolvers while a dispatch is in flight.

Installation Copy Chapter

bun install @opentui/keymap

Development Copy Chapter

bun run build
bun run test
bun src/keymap-benchmark.ts

The HTML demo lives in the docs app at /demos/keymap-html/ under packages/web.

Overview (`packages/native/README.md`) Copy Section

Native API

OpenTUI uses Context-owned scenes and Sessions for production rendering, including
text, editors, custom paint hooks, images, detached surfaces, and split output.
Standalone resources use the same checked ownership model without a terminal.

Read Resources and ownership for
resource bindings, text copy units, and scoped framebuffer access.
Frames and output defines mutation
admission, painted drafts, and transport completion.
How Core uses native explains TypeScript
staging and resource ownership.
Host I/O and time defines Context
file operations, Session deadlines, and native diagnostic clocks.

API surfaces Copy Chapter

• src/opentui.zig is the public Zig module. It exports the
  checked Context API and raw Zig primitives, including CliRenderer,
  NativeRenderable, OptimizedBuffer, text buffers, and pools. Callers manage
  the lifetimes of raw primitives. Importing a raw primitive does not add Context
  checks to it.
• include/opentui.h defines the checked ot_* C ABI for
  Contexts, Sessions, scenes, drawing, text, editors, styles, leases, clipboard,
  and diagnostics.
  The ABI is experimental and at version 1. Core renders through it.
• ../core/src/zig.ts supplies TypeScript wrappers over that
  checked ABI. Its checked signatures, callbacks, constants, and record layouts come
  from native-abi.generated.ts.

ABI generation and builds Copy Chapter

Use C headers and libraries from the same revision. Set each versioned record's
exact struct_size and abi_version, and leave unused flags and reserved fields
zero. Follow the output and failure contract of each operation in the header.

From packages/core:

bun run generate:abi
bun run check:abi
bun run test:abi

scripts/native-abi.ts uses Zig Translate-C and
scripts/native-abi.zig reflection to derive scalar
widths, signatures, callback types, constants, record sizes, alignment, and field
offsets from the header. Pointer nullability, retention, address fields, and portable
buffer/ptr policy live in
scripts/native-abi-pointers.ts, because C
types cannot prove lifetimes. Review that metadata when ownership contracts change.
Do not edit generated bindings. check:abi detects stale output. Use
bun run check:abi --all-targets to also compare the layouts of all supported targets.
An unsupported record shape or calling convention fails the script. It does not
produce partial metadata. C compiler assertions also check complete function and
callback prototypes, record layouts, field types, and constant values. Translate-C
alone is not enough, because it can drop callback calling-convention attributes and
ignore #pragma pack.

From packages/native, bun run build installs the header and libraries under
lib/<target>/ for the host target. Linux and macOS produce libopentui.a beside
the shared library. Windows produces opentui-static.lib, opentui.lib for DLL
imports, and opentui.dll. Static linkage also needs the platform and C++ runtime
libraries. zig build -Dall builds all supported targets.
zig build -Dlibrary-target=<target> builds one target.

zig build test-abi --summary all

This command runs the C fixture against the static and shared libraries on the host.
On a glibc Linux host, the fixture targets glibc 2.17. check:abi --all-targets
checks layouts for all eight supported targets. It does not test macOS or Windows
runtime linkage or terminal behavior.

The external examples/hello package imports the public Zig module
without JavaScript.

Overview (`packages/qrcode/README.md`) Copy Section

@opentui/qrcode

QR code encoder and renderable for OpenTUI.

import { createCliRenderer } from "@opentui/core"
import { QRCodeRenderable } from "@opentui/qrcode"

const renderer = await createCliRenderer()
renderer.root.add(
  new QRCodeRenderable(renderer, {
    content: "https://opentui.com",
    quietZone: 4,
    scale: 2,
  }),
)

React JSX support is registered explicitly:

import { registerQRCode } from "@opentui/qrcode/react"

registerQRCode()

Solid JSX support is registered explicitly:

import { registerQRCode } from "@opentui/qrcode/solid"

registerQRCode()

Overview (`packages/react/README.md`) Copy Section

@opentui/react

A React renderer for OpenTUI Core. Build terminal user interfaces with React components, hooks, and state.

Installation Copy Chapter

Quick start with bun and create-tui:

bun create tui --template react

Manual installation:

bun install @opentui/react @opentui/core react

Quick Start Copy Chapter

import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function App() {
  return <text>Hello, world!</text>
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)

TypeScript Configuration Copy Chapter

Configure your tsconfig.json:

{
  "compilerOptions": {
    "lib": ["ESNext", "DOM"],
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "@opentui/react",
    "strict": true,
    "skipLibCheck": true
  }
}

Table of Contents Copy Chapter

• Core Concepts
  • Components
  • Styling
• API Reference
  • createRoot(renderer)
  • render(element, config?)
  • Hooks
    • useRenderer()
    • useKeyboard(handler, options?)
    • usePaste(handler)
    • useFocus(handler)
    • useBlur(handler)
    • useSelectionHandler(handler)
    • useOnResize(callback)
    • useTerminalDimensions()
    • useTimeline(options?)
• Components
  • Layout & Display Components
    • Text Component
    • Box Component
    • Scrollbox Component
    • ASCII Font Component
  • Input Components
    • Input Component
    • Textarea Component
    • Select Component
  • Code & Diff Components
    • Code Component
    • Line Number Component
    • Diff Component
• Examples
  • Login Form
  • Counter with Timer
  • System Monitor Animation
  • Styled Text Showcase
• Component Extension
• Using React DevTools

Core Concepts Copy Chapter

Components Copy Section

OpenTUI React includes these built-in components. Each component maps to an OpenTUI Core renderable:

Layout & Display:

• <text> - Display text with styling
• `` - Container with borders and layout
• <scrollbox> - A scrollable box
• <ascii-font> - Display ASCII art text with different font styles

For QR codes, call registerQRCode() from @opentui/qrcode/react. It registers the <qr-code> element.

Input Components:

• `` - Text input field
• <textarea> - Multi-line text input field
• <select> - Vertical list of options
• <tab-select> - Tab-based selection

Code & Diff Components:

• <code> - Code block with syntax highlighting
• <line-number> - Code display with line numbers, diff highlights, and diagnostics
• <diff> - Unified or split diff viewer with syntax highlighting

Helpers:

• , , , , , , ``, <a> - Text modifiers (use them only inside a <text> component)

Styling Copy Section

Style a component with props or with the style prop:

// Direct props
<box backgroundColor="blue" padding={2}>
  <text>Hello, world!</text>
</box>

// Style prop
<box style={{ backgroundColor: "blue", padding: 2 }}>
  <text>Hello, world!</text>
</box>

API Reference Copy Chapter

`createRoot(renderer)` Copy Section

Creates a root for rendering a React tree with the given CLI renderer.

import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

const renderer = await createCliRenderer({
  // Optional renderer configuration
  exitOnCtrlC: false,
})
createRoot(renderer).render(<App />)

Parameters:

• renderer: A CliRenderer instance (typically created with createCliRenderer())

Returns: A root with a render(node) method and an unmount() method. render(node) accepts a React element.
unmount() removes the React tree and keeps the renderer active. renderer.destroy() also unmounts the root.

`render(element, config?)` (Removed) Copy Section

Removed: @opentui/react does not export render(). Use createRoot(renderer).render(node) instead.

Hooks Copy Section

`useRenderer()`

Access the OpenTUI renderer instance.

import { useRenderer } from "@opentui/react"
import { useEffect } from "react"

function App() {
  const renderer = useRenderer()

  useEffect(() => {
    renderer.console.show()
    console.log("Hello, from the console!")
  }, [])

  return <box />
}

`useKeyboard(handler, options?)`

Handle keyboard events.

import { useKeyboard } from "@opentui/react"

function App() {
  useKeyboard((key) => {
    if (key.name === "escape") {
      process.exit(0)
    }
  })

  return <text>Press ESC to exit</text>
}

Parameters:

• handler: Callback function that receives a KeyEvent object
• options?: Optional configuration object:
  • release?: Boolean to include key release events (default: false)

By default, the handler gets press events only. Press events include key repeats with repeated: true. Set options.release to true to also get release events.

Example with release events:

import { useKeyboard } from "@opentui/react"
import { useState } from "react"

function App() {
  const [pressedKeys, setPressedKeys] = useState<Set<string>>(new Set())

  useKeyboard(
    (event) => {
      setPressedKeys((keys) => {
        const newKeys = new Set(keys)
        if (event.eventType === "release") {
          newKeys.delete(event.name)
        } else {
          newKeys.add(event.name)
        }
        return newKeys
      })
    },
    { release: true },
  )

  return (
    <box>
      <text>Currently pressed: {Array.from(pressedKeys).join(", ") || "none"}</text>
    </box>
  )
}

`usePaste(handler)`

Handle terminal paste events (bracketed paste).

import { decodePasteBytes } from "@opentui/core"
import { usePaste } from "@opentui/react"

function App() {
  usePaste((event) => {
    const text = decodePasteBytes(event.bytes)
    console.log("Pasted text:", text)
  })

  return <text>Paste something into the terminal</text>
}

Parameters:

• handler: Callback function that receives a PasteEvent object with bytes: Uint8Array (decode with decodePasteBytes from @opentui/core)

`useFocus(handler)`

Subscribe to terminal window focus events. The handler runs when the terminal window gains focus.

import { useFocus } from "@opentui/react"

function App() {
  useFocus(() => {
    console.log("Terminal gained focus")
  })

  return <text>Focus-aware component</text>
}

Parameters:

• handler: Callback function invoked when the terminal gains focus

`useBlur(handler)`

Subscribe to terminal window blur events. The handler runs when the terminal window loses focus.

import { useBlur } from "@opentui/react"

function App() {
  useBlur(() => {
    console.log("Terminal lost focus")
  })

  return <text>Blur-aware component</text>
}

Parameters:

• handler: Callback function invoked when the terminal loses focus

`useSelectionHandler(handler)`

Handle text selection events, such as a mouse drag selection.

import { useSelectionHandler } from "@opentui/react"

function App() {
  useSelectionHandler((selection) => {
    const text = selection.getSelectedText()
    console.log("Selected:", text)
  })

  return <text selectable>Select this text with your mouse</text>
}

Parameters:

• handler: Callback function that receives a Selection object with methods like getSelectedText()

`useOnResize(callback)`

Handle terminal resize events.

import { useOnResize, useRenderer } from "@opentui/react"
import { useEffect } from "react"

function App() {
  const renderer = useRenderer()

  useEffect(() => {
    renderer.console.show()
  }, [renderer])

  useOnResize((width, height) => {
    console.log(`Terminal resized to ${width}x${height}`)
  })

  return <text>Resize-aware component</text>
}

`useTerminalDimensions()`

Get the current terminal dimensions. The hook updates them when the terminal resizes.

import { useTerminalDimensions } from "@opentui/react"

function App() {
  const { width, height } = useTerminalDimensions()

  return (
    <box>
      <text>
        Terminal dimensions: {width}x{height}
      </text>
      <box style={{ width: Math.floor(width / 2), height: Math.floor(height / 3) }}>
        <text>Half-width, third-height box</text>
      </box>
    </box>
  )
}

Returns: An object with width and height properties representing the current terminal dimensions.

`useTimeline(options?)`

Create one Timeline for animations. The hook registers the timeline with the animation engine after mount. It pauses and unregisters the timeline during React effect cleanup.

import { useTimeline } from "@opentui/react"
import { useEffect, useState } from "react"

function App() {
  const [width, setWidth] = useState(0)

  const timeline = useTimeline({
    duration: 2000,
    loop: false,
  })

  useEffect(() => {
    timeline.add(
      {
        width,
      },
      {
        width: 50,
        duration: 2000,
        ease: "linear",
        onUpdate: (animation) => {
          setWidth(animation.targets[0].width)
        },
      },
    )
  }, [])

  return <box style={{ width, backgroundColor: "#6a5acd" }} />
}

Parameters:

• options?: Optional TimelineOptions object with properties:
  • duration?: Animation duration in milliseconds (default: 1000)
  • loop?: Whether the timeline should loop (default: false)
  • autoplay?: Whether to automatically start the timeline (default: true)
  • onComplete?: Callback when the timeline completes
  • onPause?: Callback when the timeline pauses

Returns: A Timeline instance with methods:

• add(target, properties, startTime): Add animation to timeline
• play(): Start the timeline
• pause(): Pause the timeline
• restart(): Restart the timeline from beginning

Components Copy Chapter

Layout & Display Components Copy Section

Text Component

Display text with rich formatting.

function App() {
  return (
    <box>
      {/* Simple text */}
      <text>Hello World</text>

      {/* Rich text with children */}
      <text>
        <span fg="red">Red Text</span>
      </text>

      {/* Text modifiers */}
      <text>
        <strong>Bold</strong>, <em>Italic</em>, and <u>Underlined</u>
      </text>
    </box>
  )
}

Box Component

Container with borders and layout capabilities.

function App() {
  return (
    <box flexDirection="column">
      {/* Basic box */}
      <box border>
        <text>Simple box</text>
      </box>

      {/* Box with title and styling */}
      <box title="Settings" titleColor="yellow" border borderStyle="double" padding={2} backgroundColor="blue">
        <text>Box content</text>
      </box>

      {/* Styled box */}
      <box
        style={{
          border: true,
          width: 40,
          height: 10,
          margin: 1,
          alignItems: "center",
          justifyContent: "center",
        }}
      >
        <text>Centered content</text>
      </box>
    </box>
  )
}

Scrollbox Component

A scrollable box.

function App() {
  return (
    <scrollbox
      style={{
        rootOptions: {
          backgroundColor: "#24283b",
        },
        wrapperOptions: {
          backgroundColor: "#1f2335",
        },
        viewportOptions: {
          backgroundColor: "#1a1b26",
        },
        contentOptions: {
          backgroundColor: "#16161e",
        },
        scrollbarOptions: {
          showArrows: true,
          trackOptions: {
            foregroundColor: "#7aa2f7",
            backgroundColor: "#414868",
          },
        },
      }}
      focused
    >
      {Array.from({ length: 1000 }).map((_, i) => (
        <box
          key={i}
          style={{ width: "100%", padding: 1, marginBottom: 1, backgroundColor: i % 2 === 0 ? "#292e42" : "#2f3449" }}
        >
          <text content={`Box ${i}`} />
        </box>
      ))}
    </scrollbox>
  )
}

ASCII Font Component

Display ASCII art text with different font styles.

import { useState } from "react"

function App() {
  const text = "ASCII"
  const [font, setFont] = useState<"block" | "shade" | "slick" | "tiny">("tiny")

  return (
    <box style={{ border: true, paddingLeft: 1, paddingRight: 1 }}>
      <box
        style={{
          height: 8,
          border: true,
          marginBottom: 1,
        }}
      >
        <select
          focused
          onChange={(_, option) => setFont(option?.value)}
          showScrollIndicator
          options={[
            {
              name: "Tiny",
              description: "Tiny font",
              value: "tiny",
            },
            {
              name: "Block",
              description: "Block font",
              value: "block",
            },
            {
              name: "Slick",
              description: "Slick font",
              value: "slick",
            },
            {
              name: "Shade",
              description: "Shade font",
              value: "shade",
            },
          ]}
          style={{ flexGrow: 1 }}
        />
      </box>

      <ascii-font text={text} font={font} />
    </box>
  )
}

Input Components Copy Section

Input Component

Text input field with event handling.

import { useState } from "react"

function App() {
  const [value, setValue] = useState("")

  return (
    <box title="Enter your name" style={{ border: true, height: 3 }}>
      <input
        placeholder="Type here..."
        focused
        onInput={setValue}
        onSubmit={(value) => console.log("Submitted:", value)}
      />
    </box>
  )
}

Textarea Component

import type { TextareaRenderable } from "@opentui/core"
import { useKeyboard, useRenderer } from "@opentui/react"
import { useEffect, useRef } from "react"

function App() {
  const renderer = useRenderer()
  const textareaRef = useRef<TextareaRenderable>(null)

  useEffect(() => {
    renderer.console.show()
  }, [renderer])

  useKeyboard((key) => {
    if (key.name === "return") {
      console.log(textareaRef.current?.plainText)
    }
  })

  return (
    <box title="Interactive Editor" style={{ border: true, flexGrow: 1 }}>
      <textarea ref={textareaRef} placeholder="Type here..." focused />
    </box>
  )
}

Select Component

Choose one option from a vertical list.

import type { SelectOption } from "@opentui/core"
import { useState } from "react"

function App() {
  const [selectedIndex, setSelectedIndex] = useState(0)

  const options: SelectOption[] = [
    { name: "Option 1", description: "Option 1 description", value: "opt1" },
    { name: "Option 2", description: "Option 2 description", value: "opt2" },
    { name: "Option 3", description: "Option 3 description", value: "opt3" },
  ]

  return (
    <box style={{ border: true, height: 24 }}>
      <select
        style={{ height: 22 }}
        options={options}
        focused={true}
        onChange={(index, option) => {
          setSelectedIndex(index)
          console.log("Selected:", option)
        }}
      />
    </box>
  )
}

Code & Diff Components Copy Section

Code Component

Create a theme once for its renderer, not during a component render. Release it after you destroy its consumers.

import { createCliRenderer, RGBA, SyntaxStyle } from "@opentui/core"
import { createRoot } from "@opentui/react"

const renderer = await createCliRenderer()
const syntaxStyle = SyntaxStyle.fromStyles(
  {
    keyword: { fg: RGBA.fromHex("#ff6b6b"), bold: true }, // red, bold
    string: { fg: RGBA.fromHex("#51cf66") }, // green
    comment: { fg: RGBA.fromHex("#868e96"), italic: true }, // gray, italic
    number: { fg: RGBA.fromHex("#ffd43b") }, // yellow
    default: { fg: RGBA.fromHex("#ffffff") }, // white
  },
  renderer.nativeScene!,
)

const codeExample = `function hello() {
  // This is a comment

  const message = "Hello, world!"
  const count = 42

  return message + " " + count
}`

function App() {
  return (
    <box style={{ border: true, flexGrow: 1 }}>
      <code content={codeExample} filetype="javascript" syntaxStyle={syntaxStyle} />
    </box>
  )
}

try {
  createRoot(renderer).render(<App />)
  await renderer.closed
} finally {
  renderer.destroy()
  syntaxStyle.destroy()
}

Line Number Component

Display code with line numbers, and optionally add diff highlights or diagnostic indicators.

/* Detailed source-code truncated for AI context efficiency. */

For a more complete example with interactive diff highlights and diagnostics, see examples/line-number.tsx.

Diff Component

Display a unified or split diff with syntax highlighting, line numbers, word wrapping, and custom colors.

For a complete interactive example with theme switching and keybindings, see examples/diff.tsx.

Examples Copy Chapter

Login Form Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Counter with Timer Copy Section

import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"
import { useEffect, useState } from "react"

function App() {
  const [count, setCount] = useState(0)

  useEffect(() => {
    const interval = setInterval(() => {
      setCount((prev) => prev + 1)
    }, 1000)

    return () => clearInterval(interval)
  }, [])

  return (
    <box title="Counter" style={{ padding: 2 }}>
      <text fg="#00FF00">{`Count: ${count}`}</text>
    </box>
  )
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)

System Monitor Animation Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Styled Text Showcase Copy Section

import { createCliRenderer } from "@opentui/core"
import { createRoot } from "@opentui/react"

function App() {
  return (
    <>
      <text>Simple text</text>
      <text>
        <strong>Bold text</strong>
      </text>
      <text>
        <u>Underlined text</u>
      </text>
      <text>
        <span fg="red">Red text</span>
      </text>
      <text>
        <span fg="blue">Blue text</span>
      </text>
      <text>
        <strong fg="red">Bold red text</strong>
      </text>
      <text>
        <strong>Bold</strong> and <span fg="blue">blue</span> combined
      </text>
    </>
  )
}

const renderer = await createCliRenderer()
createRoot(renderer).render(<App />)

Component Extension Copy Chapter

To create a custom component, extend an OpenTUI Core renderable class and register it with extend().
React calls the constructor with { id, ...props }. After construction, React assigns the props to the instance again.
This example overrides the renderSelf() paint hook. The hook uses screen cell coordinates, so it places the label
relative to this.x and this.y:

/* Detailed source-code truncated for AI context efficiency. */

Using React DevTools Copy Chapter

OpenTUI React supports React DevTools for debugging your terminal applications. To enable DevTools integration:

1. Install the optional peer dependency:

bun add --dev react-devtools-core@7

2. Start the standalone React DevTools:

npx react-devtools@7

3. Run your app with the DEV environment variable:

DEV=true bun run your-app.ts

After the app starts, React DevTools shows the component tree. You can inspect and change props while the app runs. The terminal UI shows each change.

Process Exit with DevTools Copy Section

When DevTools is connected, the WebSocket connection can keep your process from exiting on its own.

Overview (`packages/solid/README.md`) Copy Section

@opentui/solid

Solid.js support for OpenTUI.

Installation Copy Chapter

bun install solid-js @opentui/solid

Usage Copy Chapter

1. Add jsx config to tsconfig.json:

{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "@opentui/solid"
  }
}

2. Add preload script to bunfig.toml:

preload = ["@opentui/solid/preload"]

3. Add render function to index.tsx:

import { render } from "@opentui/solid"

render(() => <text>Hello, World!</text>)

4. Run with bun index.tsx.

5. To build use Bun.build (source):

import solidPlugin from "@opentui/solid/bun-plugin"

await Bun.build({
  entrypoints: ["./index.tsx"],
  target: "bun",
  outdir: "./build",
  plugins: [solidPlugin],
  compile: {
    target: "bun-darwin-arm64",
    outfile: "app-macos",
  },
})

Table of Contents Copy Chapter

• Core Concepts
  • Components
• API Reference
  • render(node, rendererOrConfig?)
  • testRender(node, options?)
  • extend(components)
  • getComponentCatalogue()
  • Hooks
  • Portal
  • Dynamic
• Components
  • Layout & Display
  • Input
  • Code & Diff
  • Text Modifiers

Core Concepts Copy Chapter

Components Copy Section

OpenTUI Solid exposes intrinsic JSX elements that map to OpenTUI renderables:

• Layout & Display: text, box, scrollbox, ascii_font
• Input: input, textarea, select, tab_select
• Code & Diff: code, line_number, diff
• Text Modifiers: span, strong, b, em, i, u, br, a

API Reference Copy Chapter

`render(node, rendererOrConfig?)` Copy Section

Render a Solid component tree into a CLI renderer. If you omit rendererOrConfig, render() creates a renderer with default options. render() returns a promise that resolves after the initial mount. Destroying the renderer disposes the Solid root.

import { render } from "@opentui/solid"

render(() => <App />)

Parameters:

• node: Function returning a JSX element.
• rendererOrConfig?: CliRenderer instance or CliRendererConfig.

`testRender(node, options?)` Copy Section

Create a test renderer for snapshots and interaction tests.

import { testRender } from "@opentui/solid"

const testSetup = await testRender(() => <App />, { width: 40, height: 10 })

`extend(components)` Copy Section

Register custom renderables as JSX intrinsic elements.

import { extend } from "@opentui/solid"

extend({ customBox: CustomBoxRenderable })

Solid calls the constructor with { id } only. After construction, Solid applies each JSX prop to the instance. A class
that reads a value only from its constructor options does not get that value from JSX.

`getComponentCatalogue()` Copy Section

Returns the current component catalogue that powers JSX tag lookup.

Hooks Copy Section

• useRenderer()
• onResize(callback)
• onFocus(callback)
• onBlur(callback)
• useTerminalDimensions()
• useKeyboard(handler, options?)
• usePaste(handler)
• useSelectionHandler(handler)
• useTimeline(options?)

`Portal` Copy Section

Render children into a different mount node. Use it for overlays and tooltips.

import { Portal } from "@opentui/solid"
;<Portal mount={renderer.root}>
  <box border>Overlay</box>
</Portal>

`Dynamic` Copy Section

Render arbitrary intrinsic elements or components dynamically.

import { Dynamic } from "@opentui/solid"
;<Dynamic component={isMultiline() ? "textarea" : "input"} />

Components Copy Chapter

Layout & Display Copy Section

• text: styled text container
• box: layout container with borders, padding, and flex settings
• scrollbox: scrollable container
• ascii_font: ASCII art text renderer

For QR codes, call registerQRCode() from @opentui/qrcode/solid. It registers the qr_code element.

Input Copy Section

• input: single-line text input
• textarea: multi-line text input
• select: list selection
• tab_select: tab-based selection

Code & Diff Copy Section

• code: syntax-highlighted code blocks
• line_number: line-numbered code display with diff/diagnostic helpers
• diff: unified or split diff viewer

Text Modifiers Copy Section

Use these only inside a text component:

• span: inline styled text
• strong/b: bold text
• em/i: italic text
• u: underline text
• br: line break
• a: link text with href

Overview (`packages/ssh/README.md`) Copy Section

@opentui/ssh

Serve OpenTUI apps over SSH.

@opentui/ssh gives each incoming SSH shell its own OpenTUI
CliRenderer. The renderer reads input from the SSH channel, writes
output to it, and tracks the size of the client's PTY. You choose what to render.
The package depends only on @opentui/core, not on @opentui/react or
@opentui/solid, so the same server works with all three.

import { createServer } from "@opentui/ssh"
import { BoxRenderable, TextRenderable } from "@opentui/core"

const server = createServer({
  hostKey: { path: "./host_key" }, // auto-generated & persisted on first run
  auth: { publicKey: "any" }, // accepts any verified key, so every client gets an identity
}).serve((session) => {
  const { renderer, identity } = session
  const box = new BoxRenderable(renderer, { width: "100%", height: "100%", border: true })
  box.add(new TextRenderable(renderer, { content: `Hello, ${identity.username}!` }))
  renderer.root.add(box)
  // the server destroys the renderer when the session closes. Use onClose only for your own cleanup.
})

await server.listen(2222)

ssh -p 2222 localhost

Install Copy Chapter

bun add @opentui/ssh
# or
npm install @opentui/ssh

@opentui/core is a peer dependency. Supported runtimes are Bun ≥ 1.3.14 and
Node.js ≥ 26.4.0. CI runs the SSH integration suite with Bun on macOS, Linux,
and Windows. CI also installs the packed ESM packages and runs a real renderer
session with Node.js and Bun. Start Node applications that create renderers
with node --experimental-ffi server.mjs.

Use Bun ≥ 1.4.0 on native Windows arm64.

The shape: `createServer(config).serve(handler)` Copy Chapter

Static setup goes in the createServer({...}) config object. Add cross-cutting
concerns with .use(). serve(handler) seals the chain with the per-session
handler and returns a startable server. The handler goes on serve(), not in
the config. This lets the builder collect the typed context that each use()
adds and pass it to the handler. A server without a handler is a compile error,
because the builder has no listen() until you call serve().

const server = createServer({
  // optional, all with sensible defaults:
  // auth, hostKey, idleTimeout, maxTimeout, limits, startupBanner, onError
})
  .use(logging()) // optional middleware (see "Middleware" below)
  .serve((session) => {
    /* mount your app on session.renderer — REQUIRED */
  })

await server.listen() // defaults to port 2222 on 127.0.0.1; pass (port, host) to change

listen(port = 2222, host = "127.0.0.1") returns { host, port, fingerprints }.
Pass 0 for an ephemeral port. Pass a host like "0.0.0.0" or "::" to listen
on all interfaces, which is common in containers. With no auth, listening on a
host other than localhost, 127.0.0.1, or ::1 logs a warning. It does not
throw, because an intentionally exposed TUI is valid.

`Session` Copy Section

The handler you pass to serve() receives a Session with the live renderer.
Middleware receives a MiddlewareSession without renderer. The server
creates the renderer only after the chain authorizes the session, so a gating
middleware that declines never creates one. Everything else is shared:

Native transport Copy Section

Every shell uses Core's native scene and bounded Session output. Core, React, and
Solid applications use the same renderer attached to the SSH session.

createServer({}).serve((session) => {
  session.renderer.root.add(
    new TextRenderable(session.renderer, {
      content: "Native SSH",
    }),
  )
})

Each shell gets one Core native Session before middleware runs. Middleware
output, terminal setup, frames, raw writes, and restoration share its ordered
output budget. Core's Session driver writes to the SSH channel itself. It counts
bytes as delivered when each write callback runs, not on drain. SSH adds no
second output queue or wrapper stream. Core's production limits allow 8 MiB of retained output and
reserve one 64 KiB chunk of it for terminal control and restoration. One raw
write can therefore be at most 8,323,072 bytes (127 × 64 KiB) when nothing else
is queued. Queued and unacknowledged bytes count against the limit.

session.write() is synchronous and returns void. If the output is temporarily
full, it throws OutputPressureError with code "OUTPUT_PRESSURE", and the call
accepts no bytes. A single write larger than the Session limit throws RangeError
before string encoding. SSH does not queue, drop, or replay rejected writes.
Writes after the session closes do nothing. deny(reason) always closes the
session and throws DenyError, even when it cannot write the reason. The write
error goes to onError. Denial never creates a renderer.

Before the renderer attaches, cols and rows track the requested PTY size.
After it attaches, Core combines window changes while output is pending. The
session dimensions and onResize report only the size Core accepts, and the
renderer is already resized.

end() and onClose mark the logical close, not completed terminal restoration.
Before the renderer attaches, SSH waits for the Session to close before it closes
the channel. After the renderer attaches, SSH waits for renderer.closed. Core
allows one second for that output after the close starts. If output fails or the
time expires, the error goes to onError, Core cancels pending output without
restoration, and renderer.closed rejects. server.close() closes every live
session this way. Connection loss and peer shell close cancel the Session at once,
including during middleware. Cleanup does not wait for the ssh2 channel close
event, which unread input can delay.

The three hand-offs Copy Chapter

The package gives you a CliRenderer. You mount any front-end on
session.renderer. Runnable versions of all three are in
examples/.

Imperative (`@opentui/core`) Copy Section

createServer().serve((session) => {
  const box = new BoxRenderable(session.renderer, { border: true })
  session.renderer.root.add(box)
  // no teardown to wire: the server destroys the renderer when the session closes
})

React (`@opentui/react`) Copy Section

createRoot adopts the existing renderer as it is. See
examples/react.tsx.

import { createRoot } from "@opentui/react"

createServer().serve((session) => {
  const root = createRoot(session.renderer)
  root.render(<App name={session.identity.username} />)
  session.onClose(() => root.unmount()) // your own teardown
})

Solid (`@opentui/solid`) Copy Section

render(node, renderer) checks instanceof CliRenderer and adopts the
renderer you pass. The app draws onto the SSH channel, not the host terminal.
See examples/solid.tsx.

import { render } from "@opentui/solid"

createServer().serve(async (session) => {
  // Solid disposes its root when the renderer is destroyed, so there is nothing to wire.
  await render(() => <App name={session.identity.username} />, session.renderer)
})

@opentui/react and @opentui/solid are not runtime dependencies of this
package. The framework examples use workspace dev dependencies only to show
the hand-off. Run the Solid example with
bun run packages/ssh/examples/solid.tsx. Its launcher registers the required
JSX transform before it loads the app.

Auth & type-flowing identity Copy Chapter

createServer infers the identity type from your auth config.
session.identity covers only the methods you enabled, so you can read only the
fields you required. auth is optional and defaults to "open" (no auth), so
the getting-started snippet works on localhost.

// publickey-only → fingerprint is guaranteed present
createServer({ auth: { publicKey: "any" } }).serve((s) => s.identity.fingerprint) // ✅ string, no null check

// publickey + password → a union; discriminate on .method
createServer({ auth: { publicKey: "any", password: checkPw } }).serve((s) => {
  if (s.identity.method === "publickey") s.identity.fingerprint // ✅ narrowed
})

Supported methods (you can combine them, and the server advertises exactly what
you configure):

@opentui/ssh verifies public-key signatures itself, because ssh2 does not.
So publicKey: "any" proves possession of the private key instead of trusting
a claimed key.

For a restricted public-key server, see examples/authorized-keys.ts.

Middleware (`.use()`) Copy Chapter

.use() wraps your handler with cross-cutting concerns: gating, enrichment, and
logging. Each middleware is one layer of an onion: (session, next) => Handoff.
Call next() to continue, or next({ ... }) to add typed fields to
session.context. Return that hand-off. If you forget, it is a compile error.
To gate, call session.deny(reason). It throws to unwind the chain, so you do
not return it.

1. Registration order is execution order. The first-registered middleware
   is the outermost link.
2. await next() resolves when the session ends. The handler is the innermost
   link. The server wraps it so that it does not resolve until the session closes.
   So the finally block in try { return await next() } finally { ... } runs
   as teardown.
3. Contributions are inferred. next({ tier: "free" }) widens
   session.context by { tier: string } with no generic to declare. Each .use
   adds to the type, so a later link reads earlier links' typed fields and the
   handler reads all of them.

import { createServer, type Middleware } from "@opentui/ssh"

// SETUP/TEARDOWN — author a reusable middleware by typing it as `Middleware`. Before
// next() is setup; the finally (after next() resolves when the session closes) is teardown.
const logging: Middleware = async (session, next) => {
  const start = Date.now()
  try {
    return await next() // resolves when the session closes
  } finally {
    console.log(`${session.identity.username} stayed ${Date.now() - start}ms`)
  }
}

createServer({ auth: "open" })
  .use(logging)
  // GATE — deny() throws to bounce; otherwise continue with next().
  .use((s, next) => {
    if (s.identity.username === "banned") s.deny("no entry")
    return next()
  })
  // ENRICH — next({...}) contributes typed context the handler reads.
  .use((_s, next) => next({ tier: "free" as const }))
  .serve((s) => {
    s.context.tier // "free" — typed, no cast
  })

Those three patterns (setup/teardown, gate, and enrich) cover almost
every case. Inline arrows need no annotation, because their identity and
context types come from the builder. To name and reuse one, type it as
Middleware, or as MiddlewareFunction when it must read upstream context.

A gating middleware's deny() runs before the handler, so the handler never runs
and the server never creates the renderer. If the server can write the reason,
it appears on the main screen, and the alternate screen is never entered. If the
write fails, deny() still closes the session and throws DenyError.
Middleware sees a MiddlewareSession without the renderer. Only the handler's
Session has it. See examples/middleware.ts.

Built-in: `logging` Copy Section

@opentui/ssh includes one ready-made middleware. logging() is a
setup/teardown link. It emits a connect event on entry and a disconnect event
(with duration) on teardown. It only observes. It never reports errors, so
onError stays the single error sink. A throwing handler is logged as a normal
disconnect and still goes to onError.

import { createServer, logging } from "@opentui/ssh"

createServer({ auth: { publicKey: "any" } })
  .use(logging()) // one line per event to console.log…
  .use(logging({ log: (e) => metrics.record(e) })) // …or a structured sink
  .serve((s) => mountApp(s.renderer))

The log sink receives a LogEvent (type, identity, remoteAddress, term,
cols/rows, and durationMs on disconnect). Omit it for a one-line default.

Host key Copy Chapter

hostKey: {
  path: "./host_key"
} // load if present; else generate ed25519 & persist (0600)
hostKey: {
  pem: "..."
} // provide PEM directly
// omit entirely → ephemeral key, regenerated each start (fine for dev)

The first run with a path generates and saves an ed25519 key. listen() prints
its fingerprint so clients can verify it. When you pass several PEMs, listen()
returns and prints every fingerprint in the same order.

Lifecycle, errors & shutdown Copy Chapter

By default, the server allows one shell session per SSH connection and 100
across the server. It rejects excess shell requests without closing the SSH
connection or reporting an error. Adjust both positive-integer limits when an
application needs more concurrency:

const server = createServer({
  limits: {
    session: {
      perConnection: 2,
      global: 200,
    },
  },
}).serve(handler)

A shell counts from the time the server accepts it, before middleware runs. It
keeps its slot until the server closes its SSH channel. These limits bound
application renderers. They do not replace authentication, network access
controls, connection-rate limiting, or process resource limits.

There is no lifecycle event bus and no pluggable logger. The work splits by
verb, with no overlap:

• react to a session → middleware + session.onClose (deny, enrich, tear down)
• observe the connection lifecycle → the logging middleware (connect/disconnect/duration)
• report an error → onError, the single error sink

let live = 0 // server-wide aggregate is just a counter

const server = createServer({
  auth: "open",
  idleTimeout: "10m", // reap a session after no client input ("30s", "500ms", or ms)
  maxTimeout: "1h", // absolute session lifetime, regardless of activity
  startupBanner: true, // set false to silence listen()'s summary
  onError: (err) => console.error(err), // the one error sink; this is the default
}).serve((session) => {
  live++
  session.onClose(() => {
    live-- // your own per-session bookkeeping (the renderer is torn down for you)
  })
})

• The handler and session.onClose are the per-session lifecycle. Set up on
  entry, and tear down when the session closes. Put anything reusable or
  cross-cutting in a middleware.
• onError(err) is the runtime error sink. Contained application and
  transport errors go here: a throwing handler or middleware, a throwing
  onResize or onClose, a throwing auth predicate, Session output failures,
  and connection-level and server-level ssh2 errors. It defaults to
  console.error. It reports errors. To react to a session, use middleware or
  onClose. To observe the lifecycle, use the logging middleware. A bind
  failure rejects listen() instead of going here. The logger ignores its own
  sink failures, so logging cannot affect a session.
• idleTimeout closes a session after that long with no client input.
  Any client input restarts the timer. Only the idle session closes. Other sessions
  and the listener continue. Durations must be between 1ms and 24h.
• maxTimeout closes a session after that absolute lifetime, even when the
  client keeps sending input. Durations must be between 1ms and 24h.
• listen() binds, prints the startup banner (URL, host-key fingerprints,
  auth methods, allowlist fingerprints) to stdout unless startupBanner: false,
  and returns { host, port, fingerprints }.
• close() rejects new shell requests and closes every live session, which
  destroys its renderer. Then it ends every client connection and closes the
  listener.

@opentui/ssh  ▸  ssh://localhost:2222
host key      SHA256:nThbg6kX…0bGQ  (ssh-ed25519, generated ./host_key)
auth          publickey, password
authorized    2 keys  ·  SHA256:abc… SHA256:def…

License Copy Chapter

MIT

Overview (`packages/core/src/testing/README.md`) Copy Section

Testing Utilities

Test utilities for opentui terminal UI testing.

Test Renderer Copy Chapter

import { createTestRenderer } from "@opentui/core/testing"

const { renderer, mockInput, mockMouse, renderOnce, captureCharFrame, resize } = await createTestRenderer({
  width: 80,
  height: 24,
})

// Render once and capture output
await renderOnce()
const output = captureCharFrame()

// Resize terminal
resize(100, 30)

Terminal Capabilities Copy Chapter

import { createTerminalCapabilities, setRendererCapabilities } from "@opentui/core/testing"

const capabilities = createTerminalCapabilities({ kitty_keyboard: true })
setRendererCapabilities(renderer, { notifications: true })

Mock Keyboard Input Copy Chapter

import { createMockKeys, KeyCodes } from "@opentui/core/testing"

const mockInput = createMockKeys(renderer)

// Type text
mockInput.typeText("hello world")
await mockInput.typeText("hello", 10) // 10ms delay between keys

// Press single keys
mockInput.pressKey("a")
mockInput.pressKey(KeyCodes.ENTER)

// Press keys with modifiers
mockInput.pressKey("a", { ctrl: true })
mockInput.pressKey("f", { meta: true })
mockInput.pressKey("z", { ctrl: true, shift: true })
mockInput.pressKey(KeyCodes.ARROW_LEFT, { meta: true })

// Press multiple keys
mockInput.pressKeys(["h", "e", "l", "l", "o"])
await mockInput.pressKeys(["a", "b"], 10) // with delay

// Convenience methods
mockInput.pressEnter()
mockInput.pressEnter({ meta: true })
mockInput.pressEscape()
mockInput.pressTab()
mockInput.pressBackspace()
mockInput.pressArrow("up" | "down" | "left" | "right")
mockInput.pressArrow("left", { meta: true })
mockInput.pressCtrlC()
mockInput.pasteBracketedText("paste content")

KeyCodes Copy Section

Special keycodes available: RETURN, LINEFEED, TAB, BACKSPACE, DELETE, HOME, END, ESCAPE, ARROW_UP, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, F1-F12

Modifiers Copy Section

All pressKey(), pressEnter(), pressEscape(), pressTab(), pressBackspace(), and pressArrow() methods support an optional modifiers object:

{ ctrl?: boolean; shift?: boolean; meta?: boolean }

Mock Mouse Input Copy Chapter

import { createMockMouse, MouseButtons } from "@opentui/core/testing"

const mockMouse = createMockMouse(renderer)

// Click
await mockMouse.click(x, y)
await mockMouse.click(x, y, MouseButtons.RIGHT)
await mockMouse.click(x, y, MouseButtons.LEFT, {
  modifiers: { ctrl: true, shift: true, alt: true },
  delayMs: 10,
})

// Double click
await mockMouse.doubleClick(x, y)

// Press and release
await mockMouse.pressDown(x, y, MouseButtons.MIDDLE)
await mockMouse.release(x, y, MouseButtons.MIDDLE)

// Move
await mockMouse.moveTo(x, y)
await mockMouse.moveTo(x, y, { modifiers: { shift: true } })

// Drag
await mockMouse.drag(startX, startY, endX, endY)
await mockMouse.drag(startX, startY, endX, endY, MouseButtons.RIGHT, {
  modifiers: { alt: true },
})

// Scroll
await mockMouse.scroll(x, y, "up" | "down" | "left" | "right")
await mockMouse.scroll(x, y, "up", { modifiers: { shift: true } })

// State
const pos = mockMouse.getCurrentPosition() // { x, y }
const buttons = mockMouse.getPressedButtons() // MouseButton[]

MouseButtons Copy Section

LEFT (0), MIDDLE (1), RIGHT (2)

WHEEL_UP (64), WHEEL_DOWN (65), WHEEL_LEFT (66), WHEEL_RIGHT (67)

Spy Copy Chapter

Simple function spy for testing callbacks.

import { createSpy } from "@opentui/core/testing"

const spy = createSpy()

// Use as callback
someFunction(spy)

// Assertions
spy.callCount() // number
spy.calledWith(arg1, arg2) // boolean
spy.calls // any[][]
spy.reset()

Test Recorder Copy Chapter

Record frames during rendering for testing or analysis.

import { TestRecorder } from "@opentui/core/testing"

const { renderer, renderOnce } = await createTestRenderer({ width: 80, height: 24 })
const recorder = new TestRecorder(renderer)

// Start recording
recorder.rec()

// Add content and trigger renders
const text = new TextRenderable(renderer, { content: "Hello" })
renderer.root.add(text)
await Bun.sleep(1) // Wait for automatic render from add()

text.content = "World"
await Bun.sleep(1) // Wait for automatic render from content change

// Stop recording
recorder.stop()

// Access recorded frames
const frames = recorder.recordedFrames
console.log(`Recorded ${frames.length} frames`)

frames.forEach((frame) => {
  console.log(`Frame ${frame.frameNumber} at ${frame.timestamp}ms:`)
  console.log(frame.frame)
})

// Clear and start new recording
recorder.clear()
recorder.rec()

TestRecorder API Copy Section

• rec() - Start recording frames
• stop() - Stop recording frames
• clear() - Clear all recorded frames
• isRecording - Check if currently recording
• recordedFrames - Get array of recorded frames (returns a copy)

RecordedFrame Copy Section

Each frame contains:

• frame: string - The captured frame content
• timestamp: number - Time in milliseconds since recording started
• frameNumber: number - Sequential frame number (0-indexed)

Example Copy Chapter

import { test, expect } from "bun:test"
import { createTestRenderer } from "@opentui/core/testing"

test("button click", async () => {
  const { renderer, mockMouse, renderOnce, captureCharFrame } = await createTestRenderer({ width: 80, height: 24 })

  const clicked = createSpy()
  const button = new Button("btn", { text: "Click me", onClick: clicked })

  renderer.add(button)
  await renderOnce()

  await mockMouse.click(10, 5)
  expect(clicked.callCount()).toBe(1)
})

Overview (`packages/examples/src/magick/README.md`) Copy Section

Magick Arena

Magick Arena renders a Three.js scene through a two-slot NativeImagePool and ImageRenderable.
The demo requires Bun and WebGPU.

Controls Copy Chapter

Pause stops continuous GPU readbacks, but pending or reset frames can still render.
Diagnostics remain available. Movement stops while the console is open or the terminal
loses focus. Legacy keyboard input uses approximate movement pulses instead of key-release events.

Rendering Copy Chapter

The framebuffer defaults to 640x360 and stays fixed when the terminal resizes. Press T
to cycle transport without restarting the scene, including while paused. The status line
shows the requested and effective Kitty transport, or marks it inactive for other image
protocols. File and zlib modes can fall back to raw output. C shows the full transport
status. Returning to the selector restores its previous transport setting.

The demo reads GPU pixels into CPU memory. File transport sends a temporary file path,
not a shared GPU image.

The private GPU adapter is experimental and uses pinned bun-webgpu internals. It releases
per-frame GPU objects. Repeated GPU renderer creation still has a separate provider issue,
so the selector reuses one renderer across visits. It releases that renderer when the
terminal renderer closes. Each return to the selector releases scene resources, images,
and input listeners.

Overview (`packages/native/src/bench/README.md`) Copy Section

OpenTUI Benchmarks

This directory contains benchmarks for the OpenTUI core library.

Running Benchmarks Copy Chapter

From the packages/core directory:

bun run bench:native

# Include memory statistics
bun run bench:native --mem

# Or from packages/native:
bun run bench
bun run bench --mem

Adding New Benchmarks Copy Chapter

To add a new benchmark:

1. Create a new *_bench.zig file in the bench/ directory
2. Import shared types from bench-utils.zig:
   zig Copy

   const bench_utils = @import("../bench-utils.zig");
   const BenchResult = bench_utils.BenchResult;
   const MemStats = bench_utils.MemStats;

3. Implement a pub fn run(allocator: std.mem.Allocator, show_mem: bool) ![]BenchResult function:
   • Set up any benchmark-specific dependencies (grapheme pool, Unicode data, etc.)
   • Run your benchmarks and collect results
   • Return a slice of BenchResult (caller will free it)
   • The show_mem flag indicates whether to include memory statistics
4. Import it in bench.zig:
   zig Copy

   const my_new_bench = @import("bench/my_new_bench.zig");

5. Call it and print results in main():
   zig Copy

   const my_results = try my_new_bench.run(allocator, show_mem);
   defer allocator.free(my_results);
   try bench_utils.printResults(stdout, my_results);

Each benchmark manages its own dependencies, so you only set up what you need.

See bench/text-buffer-view_bench.zig for a complete example.

Overview (`packages/native/src/tests/README.md`) Copy Section

Test Suite

This directory contains the test suite for the OpenTUI Zig components.

Run All Tests Copy Section

Run this command from packages/core:

bun run test:native

It checks the vendored Zig dependency checksums, runs zig build test, then
tests and runs examples/hello.

Measure-target lifetime Copy Section

The default suite already checks that destroying a view or buffer clears
matching Yoga measure targets, then layouts again. For allocator accounting on
that same C export path, run:

bun run test:native:lifetime

That Debug probe turns on GPA leak checks and fails if requested bytes grow
across teardown cycles. Use it after Yoga ownership or measure-target lifetime
changes.

Adding New Test Files Copy Chapter

1. Create a new *_test.zig file in this directory
2. Import it in ../test.zig:
   zig Copy

   const new_tests = @import("tests/new_test.zig");

3. Reference it in the test block at the end of ../test.zig, or Zig skips its tests:
   zig Copy

   _ = new_tests;

4. Update the build system if needed to include any new dependencies

Overview (`packages/web/public/recordings/README.md`) Copy Section

Terminal Illustration Recordings

The files in this directory contain terminal recordings for <TerminalIllustration>.

The recording tools are in scripts/recordings/. They convert an asciinema .cast file to a story .json file.

Install asciinema on your PATH before you use the tools. The package supplies @xterm/headless as a development dependency.

Player Options Copy Chapter

Each story can set these options:

• tone="inherit" recolors cells from their luminance. It uses the component color or the ink overrides.
• tone="recorded" uses the recorded foreground colors.
• background="transparent" does not paint cell backgrounds.
• background="recorded" paints recorded backgrounds and restores the recorded default foreground.
• padding={false} removes the terminal-colored margin added around a recorded background.
• fadeTop, fadeRight, fadeBottom, and fadeLeft set an edge fade from 0 to 1.
• title and caption supply text for the controls.

The default values are tone="inherit" and background="transparent".

Use tone="recorded" for content in which color conveys information. Use a recorded background when foreground contrast depends on it.

The player calculates fades from cell opacity to keep glyphs sharp. Horizontal fades use the midpoint of each styled run.

Do not use a horizontal fade for prose with long runs. Set fadeLeft and fadeRight to 0.

Multiple stories and chapters play in order and repeat. The controls option accepts these values:

• hidden: Do not show controls. This is the default.
• hover: Show overlay controls on hover or focus.
• visible: Always show overlay controls.
• below: Show controls and captions below the recording.

The player loads a recording when it is within 800px of the viewport.

See StoryConfig and Props in src/components/TerminalIllustration.astro for all options and defaults.

Use In Scrollback Copy Chapter

Use the Scrollback wrapper in an .mdx post:

import ScrollbackRecording from "../../components/ScrollbackRecording.astro"

<ScrollbackRecording
  label="OpenTUI terminal recording"
  stories={[
    {
      src: "/recordings/anomaly.json",
      title: "OpenTUI",
      tone: "inherit",
    },
  ]}
/>

Use controls="below" when chapter captions are part of the article.

Record A Cast Copy Chapter

Run the record tool from packages/web:

scripts/recordings/bin/record out.cast
scripts/recordings/bin/record out.cast -- node demo.mjs
scripts/recordings/bin/record --headless out.cast -- node demo.mjs
scripts/recordings/bin/record --window-size 100x56 out.cast -- bun src/app.ts

The tool is also available as bun run recordings:record.

If the application uses another working directory, store the absolute tool path first:

record="$PWD/scripts/recordings/bin/record"

Automatic Applications Copy Section

Use --headless for an application that needs no input. Use timeout to set the duration.

cd ~/src/tuiexperiments/some-headless-app
"$record" --headless --window-size 210x42 /tmp/my-recording.cast \
  -- timeout 16 bun src/app.ts

Use a wide, short window for a recording that fills a wide media area.

Applications With Setup Input Copy Section

Use tmux when an application needs a small amount of setup input:

tmux new-session -d -s rec -x 200 -y 46
tmux send-keys -t rec -l "cd ~/src/tuiexperiments/some-app && $record /tmp/my-recording.cast -- bun start"
tmux send-keys -t rec Enter
sleep 3
tmux send-keys -t rec -l 's'
sleep 30
tmux send-keys -t rec -l 'q'
tmux kill-session -t rec

Make sure that setup keys changed the application before you keep a long recording.

Use tmux capture-pane -e -p to examine colors and escape sequences. Plain-text output cannot confirm a color change.

Interactive Applications Copy Section

Record continuous interaction directly:

cd ~/src/tuiexperiments/some-app
"$record" /tmp/my-recording.cast -- bun src/app.ts

Use ctrl+x to add chapter markers. Use many small inputs when motion must appear continuous.

The build tool keeps only changed frames. A few large inputs produce only a few frames.

Build A Story Copy Chapter

Copy the cast to the tool directory and build it:

cp /tmp/my-recording.cast scripts/recordings/my-recording.cast
bun run recordings:build scripts/recordings/my-recording.cast

The first build creates scripts/recordings/my-recording.story.config.json. It also writes public/recordings/my-recording.json.

Edit the generated config to set chapter boundaries, captions, and durations. Then build from the config:

bun run recordings:build scripts/recordings/my-recording.story.config.json

Commit the config and the generated story. The repository ignores the cast.

Check The Story Copy Chapter

Check these items before you ship the story:

• Set atMs after transient shell output and before the first useful frame.
• Remove persistent title bars, borders, labels, and instructions that do not belong in the composition.
• Set durationMs to one cycle for a deterministic animation. The player repeats the story.
• Make sure that setup keys changed the recorded mode. Examine rows when you must confirm cell colors.
• Use a recorded tone for prose, tables, and other content that must remain legible.
• Check the final aspect ratio after each crop.

The fit="cover" mode sets the font size from the available height. A narrow recording can leave horizontal empty space.

Use this minimum ratio for a full-width composition:

cols / rows >= (boxWidth / boxHeight) * (lineToEm / chToEm)

For OpenTUI Mono, chToEm is approximately 0.6 and lineToEm is approximately 1.1.

A media-area ratio from 1.2 to 1.3 usually needs a recording ratio from approximately 2.2 to 2.4.

Record a wider grid or crop rows if the recording does not meet the minimum ratio.

Ship The Story Copy Chapter

Reference the generated file from a page or a Scrollback post:

<TerminalIllustration
  label="OpenTUI terminal recording"
  stories={[{ src: "/recordings/my-recording.json", tone: "inherit" }]}
  controls="visible"
/>

The build writes the file to public/recordings/. Do not copy it after the build.

Overview (`packages/web/src/font/README.md`) Copy Section

OpenTUI Mono

OpenTUI Mono is the typeface for the site. Iosevka compiles
private-build-plans.toml into static WOFF2 files. Iosevka does not write
an OpenType variable font.

The live files are Regular, Bold, Italic, and Bold Italic in
public/fonts/. /lab/font compares those files with the next compile in
public/fonts/candidate/.

Plan Copy Chapter

The plan sets glyphs, metrics, weights (100 to 900), and widths (Normal +
SemiCondensed). Ligatures are off. The plan makes one web-subset family.
Change keys in the plan. Do not start from a blank UFO or FontForge file.

Identity glyphs: a g l I 1 0 8 6 9 @ { } ( ) _ *.

These keys change the look first: sb, width shape, xHeight,
archDepth, and the identity keys in variants.design.

Compile Copy Chapter

You need Node 18+ and a clone of Iosevka
at v34.4.0. You do not need ttfautohint for webfont-unhinted.

git clone --depth 1 --branch v34.4.0 https://github.com/be5invis/Iosevka.git
cp packages/web/src/font/private-build-plans.toml Iosevka/
cd Iosevka && npm install
npm run build -- --jCmd=4 webfont-unhinted::OpenTUIMono

Copy the next compile into packages/web/public/fonts/candidate/ as
OpenTUIMono-{Regular,Bold,Italic,BoldItalic}.woff2. Compare it with
the live files at /lab/font. When you accept the next compile, copy those
four files to packages/web/public/fonts/.

Overview (`packages/core/src/renderables/composition/README.md`) Copy Section

Composition Exploration

This is a simple exploration of how to compose renderables into a tree.

It's not react and not reactive, it's just a way to compose renderables
and mount them into a parent container.

It's a work in progress and not in any way meant to be a replacement for react.

Overview (`packages/core/src/lib/tree-sitter/assets/README.md`) Copy Section

Tree-sitter Assets

This directory contains downloaded tree-sitter language parsers and highlight queries for the default parsers used by OpenTUI.
They are included in the repository to avoid downloading them every time the project is built or tests are run.

Asset Management Copy Chapter

Parser definitions are configured in ../parsers-config.ts for OpenTUI's built-in parser set.

Update Script Copy Section

The update.ts script downloads parsers and queries from the configured URLs and generates the ../default-parsers.ts file.

Usage

For OpenTUI Core Development (using default paths):

# Run from this directory
bun update.ts

# Or from the project root
bun packages/core/src/lib/tree-sitter/assets/update.ts

For Application Developers (using custom paths):

# CLI usage with custom paths
bun update.ts \
  --config ./my-parsers-config.json \
  --assets ./src/tree-sitter/assets \
  --output ./src/tree-sitter/parsers.ts

# Show help
bun update.ts --help

Programmatic Usage:

import { updateAssets } from "@opentui/core/tree-sitter/update-assets"

await updateAssets({
  configPath: "./my-parsers-config.json",
  assetsDir: "./src/tree-sitter/assets",
  outputPath: "./src/tree-sitter/parsers.ts",
})

What it does

1. Downloads Language Parsers: Downloads .wasm files from GitHub releases
2. Downloads Query Files: Downloads .scm highlight query files from repositories
3. Combines Queries: For languages like TypeScript, combines multiple query files (JS base + TS extensions)
4. Generates Imports: Creates a TypeScript file with proper file imports using Bun's with { type: "file" } syntax

Adding New Parsers Copy Chapter

For Application Developers Copy Section

If you're using OpenTUI in your application and want to add support for additional languages:

1. Create a parsers configuration file

Create a parsers-config.json file in your project with the structure:

{
  "parsers": [
    {
      "filetype": "python",
      "wasm": "https://github.com/tree-sitter/tree-sitter-python/releases/download/v0.20.4/tree-sitter-python.wasm",
      "queries": {
        "highlights": [
          "https://raw.githubusercontent.com/tree-sitter/tree-sitter-python/refs/heads/master/queries/highlights.scm"
        ]
      }
    }
  ]
}

2. Add to your build pipeline

Add the update script to your package.json:

{
  "scripts": {
    "prebuild": "bun node_modules/@opentui/core/lib/tree-sitter/update-assets.js --config ./parsers-config.json --assets ./src/parsers --output ./src/parsers.ts",
    "build": "bun build ./src/index.ts"
  }
}

3. Use the generated parsers

import { getTreeSitterClient } from "@opentui/core"
import { getParsers } from "./parsers"

const client = getTreeSitterClient()

// Register your custom parsers
for (const parser of getParsers()) {
  client.addFiletypeParser(parser)
}

For more information about using Tree-Sitter in your application, see the Tree-Sitter guide.

For OpenTUI Core Developers Copy Section

To add a new default parser to OpenTUI Core:

1. Update Configuration: Add the new parser to ../parsers-config.ts
2. Run Update Script: Execute bun update.ts to download assets and regenerate imports
3. Commit Generated Assets: Include the downloaded parser/query files and regenerated ../default-parsers.ts

Packages Web Src Content Docs Getting Started (`packages/web/src/content/docs/getting-started.mdx`) Copy Section

title: Getting started skill: entry: true intents: [getting-started, intro, examples, agent-skill] Copy Chapter

Getting started

OpenTUI is a native terminal UI core written in Zig with TypeScript bindings.

It renders a component tree, lays it out with Flexbox, handles terminal input, and updates the cells that changed.
OpenTUI's TypeScript packages call the Zig library through its native interface. OpenTUI powers OpenCode in production.

Start with the quickstart Copy Chapter

Build your first app in the quickstart. In the quickstart, you create a project
from an empty directory, compose a small interface, handle keyboard input, and run it in your terminal.

The quickstart uses @opentui/core directly to teach the renderer, component tree, input, and layout model once. You
do not need to choose a framework before you complete it.

Check Runtime and platform support before you use Node.js, cross-compile, or
deploy to another target.

Choose a framework Copy Chapter

• @opentui/core uses imperative renderables and events directly.
• @opentui/react uses React components, hooks, and state.
• @opentui/solid uses Solid components, signals, and effects.

If you use Core, read Renderables after the quickstart.

Find a topic Copy Chapter

• Components compares component availability across Core, React, and Solid.
• Renderer covers terminal setup, the root, scheduling, and central events.
• Layout covers Yoga-based sizing and positioning.
• Interaction, focus, and selection explains shared pointer and focus behavior.
• Testing renders apps in memory for assertions and snapshots.
• Package entry points lists supported import paths.
• Lifecycle and cleanup owns terminal restoration and resource release.
• Native rendering explains the scene model and native C and Zig interfaces.

Explore the examples Copy Chapter

Run the OpenTUI example browser without cloning the repository. Release executables support macOS x64 and arm64,
Linux x64, and Windows x64. On those targets, including x64 WSL and Git Bash:

curl -fsSL https://raw.githubusercontent.com/anomalyco/opentui/main/packages/examples/install.sh | sh

On Windows, download the latest release from GitHub Releases.

Give an agent the docs Copy Chapter

OpenTUI includes a skill that teaches AI coding assistants its APIs and patterns. It holds these docs and the release
notes. Install the skill of the latest release with npx skills:

npx skills add https://opentui.com --skill opentui

Add -g to install the skill globally for every project. OpenCode uses the same install command. npx skills update
moves the skill to the newest release. For the main branch, install from https://opentui.com/docs/next instead.

A skill installed with npx skills add anomalyco/opentui follows the main branch. Run the command above to switch it
to releases.

Versions Copy Chapter

These docs describe one release. The site header names it, and next beside it opens the docs of the main branch,
which include unreleased changes. Releases lists what changed in each release, and the API reference
names the release that added each export. Above its previous and next links, a page lists its changes in recent
releases.

Packages Web Src Content Docs Components Overview (`packages/web/src/content/docs/components/overview.mdx`) Copy Section

title: Components skill: entry: true intents: [components, component, component-support, support-matrix, react-components, solid-components] Copy Chapter

Components

The tables compare each component's availability across Core, React, and Solid.

An automatic framework element needs no component-specific registration. Separately registered elements require the package setup shown on their component page. Unavailable means that the shipped API does not expose that surface.

Display and layout Copy Chapter

• Text displays labels, prose, and styled text. Choose Code for parsed source or Markdown for documents.
• Box lays out children and can draw a background, border, and title. Choose ScrollBox when the children must scroll.

Inline text elements Copy Section

React and Solid also register , , , , , , ``, and <a>. These elements are
built-in text children, not standalone layout components. Use them only inside <text>. The <a> element accepts
href and creates terminal hyperlink metadata.

Input and selection Copy Chapter

• Input edits one line of text. Choose Textarea for multi-line editing.
• Textarea edits multiple lines with cursor and selection support. Choose Input for one line.
• Select shows discrete choices in a vertical list. Choose TabSelect for a horizontal strip or Slider for a continuous value.
• TabSelect shows peer choices in a horizontal tab strip. Choose Select for a vertical list.
• Slider selects a continuous value with a draggable thumb. Choose Select for discrete choices.

Scrolling Copy Chapter

• ScrollBox owns scrollable children, clipping, and scrollbars. Use it for normal scrolling containers.
• ScrollBar controls an external scroll position. Use it when another model owns the scroll state.

Rich content Copy Chapter

• Code displays syntax-highlighted source. Choose Markdown for documents or Diff for patches.
• Markdown renders document structure and fenced code. Choose Code when all content is source code.
• Line number gutter adds numbers and signs to line-aware content. Diff manages its own gutters.
• Diff displays the first file patch in unified or split form. Create one instance for each file patch.
• TextTable lays out styled cell data. Choose Markdown when the table starts as Markdown source.

OpenTUI bundles parsers for JavaScript and JSX, TypeScript and TSX, Markdown and Markdown inline, and Zig. Other grammars require Tree-sitter configuration.

Graphics and media Copy Chapter

• ASCIIFont draws short text with bundled ASCII art fonts. Choose Text for labels and prose.
• FrameBuffer exposes direct cell drawing. Choose Image when you only need to display an image source.
• Image displays encoded images or a NativeImage. Use the NativeImage API to decode or transform pixels.
• QR code displays text as a scannable symbol. Use the QR encoder for matrices and serialized output.
• Embedded terminal parses VT output and draws a child terminal. It does not start a process.

Use the Buffer API for low-level OptimizedBuffer ownership and drawing operations.

Diagnostics Copy Chapter

TimeToFirstDraw is a diagnostic, not a general display component. See Rendering diagnostics for its timestamp behavior.

Packages Web Src Content Docs Getting Started Quickstart (`packages/web/src/content/docs/getting-started/quickstart.mdx`) Copy Section

title: Quickstart skill: entry: true intents: [installation, quickstart] Copy Chapter

{/* docs-lint-disable mdx-esm-import */}
import ScrollbackRecording from "../../../components/ScrollbackRecording.astro"

Quickstart

Build a small counter controlled by the arrow keys. The finished app uses layout, text, keyboard input, live updates,
and explicit cleanup.

Prerequisite Copy Chapter

This guide uses Bun to run TypeScript source. See Runtime and platform support
for other runtime and platform requirements.

Create an empty project and add OpenTUI:

mkdir my-tui && cd my-tui
bun init -y
bun add @opentui/core

Create the app Copy Chapter

Create index.ts:

import { BoxRenderable, TextRenderable, createCliRenderer } from "@opentui/core"

const renderer = await createCliRenderer({
  exitOnCtrlC: true,
  backgroundColor: "#1131E9",
})

let count = 0
const counter = new TextRenderable(renderer, {
  id: "counter",
  content: "Count  0",
  fg: "#FFFFFF",
})

const panel = new BoxRenderable(renderer, {
  width: 42,
  height: 9,
  backgroundColor: "#1131E9",
  alignItems: "center",
  justifyContent: "center",
})
const content = new BoxRenderable(renderer, {
  width: 38,
  height: 7,
  backgroundColor: "#2947F0",
  padding: 1,
  flexDirection: "column",
  gap: 1,
  alignItems: "center",
})

content.add(new TextRenderable(renderer, { content: "Hello, OpenTUI!", fg: "#DCE3FF" }))
content.add(counter)
content.add(new TextRenderable(renderer, { content: "left/right change | q quit", fg: "#AEBBFF" }))
panel.add(content)
renderer.root.add(panel)

renderer.keyInput.on("keypress", (key) => {
  if (key.name === "q") {
    renderer.destroy()
    return
  }

  if (key.name === "left") count--
  else if (key.name === "right") count++
  else return

  counter.content = `Count  ${count}`
})

createCliRenderer() takes control of the terminal and returns a CliRenderer. Its root property is the root of the
component tree. BoxRenderable and TextRenderable are imperative tree nodes. The event handler updates the counter's
content property directly.

The renderer emits parsed keyboard events through keyInput. The handler changes counter.content, which schedules a
new frame.

Run it Copy Chapter

bun index.ts

Press the Left and Right arrow keys. The count updates in place.

The application creates and owns the renderer. It must call renderer.destroy() on every shutdown path to release
resources and restore the terminal. This example calls it when you press q. exitOnCtrlC: true handles the Ctrl+C
path.

{/* docs-lint-disable mdx-component-node */}

<ScrollbackRecording
label="The quickstart app changing a count with arrow keys, then returning to the shell"
controls="hidden"
stories={[
{
src: "/recordings/quickstart.json",
tone: "recorded",
background: "recorded",
padding: false,
},
]}
/>

Continue Copy Chapter

• Return to the OpenTUI introduction for the documentation map.
• React bindings apply the shared model through React.
• Solid bindings apply the shared model through Solid.
• Components compares component availability across Core, React, and Solid.
• Renderables covers imperative tree creation and mutation.
• Lifecycle and cleanup covers shutdown paths and resource ownership.

Packages Web Src Content Docs Keymap Overview (`packages/web/src/content/docs/keymap/overview.mdx`) Copy Section

title: Keymap skill: entry: true intents: [keymap, keybindings, shortcuts, commands, leader, ex-commands] Copy Chapter

Keymap

@opentui/keymap is an independent, host-agnostic package for layered key bindings, commands, and key sequences.

The package lets an app register an action once and resolve it from the current focus. An editor can save from every
view, close only the focused dialog, and show its current shortcuts.

Install Copy Chapter

bun add @opentui/keymap

The engine is JavaScript. The OpenTUI adapter connects it to terminal input from CliRenderer.
The HTML adapter connects the same engine to browser keyboard events.

Create an OpenTUI keymap Copy Chapter

Create the renderer first. Then create a default OpenTUI keymap and register an application layer.

import { createCliRenderer } from "@opentui/core"
import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"

const renderer = await createCliRenderer()
const keymap = createDefaultOpenTuiKeymap(renderer)

keymap.registerLayer({
  commands: [
    {
      name: "file.save",
      run() {
        console.log("save")
      },
    },
    {
      name: "app.quit",
      run() {
        renderer.destroy()
      },
    },
  ],
  bindings: [
    { key: "ctrl+s", cmd: "file.save" },
    { key: "q", cmd: "app.quit" },
  ],
})

createDefaultOpenTuiKeymap() installs the default parser, event matcher, enabled fields, and metadata fields.
Each registration returns a disposer. Destroying the renderer also ends the host lifecycle and releases keymap resources.
See Lifecycle and cleanup for application shutdown.

ctrl+s  file.save
q       app.quit

Register, dispatch, and query Copy Chapter

Keymap uses one short model:

A layer can be global or attached to a host target. Higher priority values run first.
Newer layers run first when priorities match. A focused target controls which local layers are active.

A key sequence stays pending until another key completes it, rejects it, or clears it.
Queries use that pending state, so a shortcut view can show only the next reachable keys.

The Core keymap API defines key syntax, field compilation, runtime data, command queries,
dispatch results, ordering, errors, and sequence limits.

Choose the input level Copy Chapter

Use direct keyboard events when one owner needs the original KeyEvent.
Examples include a global Ctrl+C handler or terminal-protocol diagnostics.

Use a component's local key binding options for behavior that belongs only to that component.
Examples include cursor movement in an input or selection movement in a list.

Move to Keymap when the same application command has more than one owner or context. Keymap is useful when you need:

• focus-scoped or priority-ordered layers
• user-configurable key bindings
• multi-key sequences or leader keys
• named commands for palettes and help
• one command model across Core, React, and Solid code

Keymap does not replace component text input. The OpenTUI textarea addon can route editing commands through Keymap when
an application needs to manage those key bindings centrally.

Hosts and framework state Copy Chapter

The Hosts page defines KeymapHost and the built-in OpenTUI and HTML adapters.
Hosts supply focus, hierarchy, key events, metadata, and lifecycle signals.

React and Solid do not create a keymap. Their providers consume a pre-created OpenTUI keymap and expose reactive state:

• React keymap integration supplies React context and hooks.
• Solid keymap integration supplies Solid context, selectors, and hooks.

Add features Copy Chapter

The bare engine has no fixed key language. Addons install parsers, field compilers, sequence behavior, diagnostics, and
OpenTUI integrations through public registration APIs.

• Built-in keymap addons lists every shipped universal and OpenTUI addon.
• Custom keymap addons explains addon callbacks, ordering, cleanup, and tests.

Next Copy Chapter

• Hosts
• Core keymap API
• React keymap integration
• Solid keymap integration
• Built-in keymap addons
• Custom keymap addons

Packages Web Src Content Docs Native Overview (`packages/web/src/content/docs/native/overview.mdx`) Copy Section

title: Native rendering skill: entry: true intents: [native, native-rendering, native-scene, native-api] Copy Chapter

Native rendering

OpenTUI's native library turns a tree of UI nodes into terminal output.
You can call it from C or Zig without JavaScript.

This walkthrough follows one small interface: a bordered box containing the label Hello.
Its drawing area is 12 columns wide and three rows high:

┌──────────┐
│Hello     │
└──────────┘

Your program describes the box and label. The native library calculates their positions, draws their cells, and produces terminal output.
The program then delivers that output to its destination.

After the first frame, you will change the label to Ready and render again without rebuilding the tree.

Describe the interface as a tree Copy Chapter

The box and label need three native nodes. Each node stores one part of the interface:

┌─ Scene ─────────────────────────┐
│ root                            │
│ └─ box: single-line border      │
│    └─ label: "Hello"            │
└─────────────────────────────────┘

The root is the top of the tree. The box contains the label.
Adding the label to the box establishes that relationship. It does not specify where to draw the first character.

Nodes store layout properties, such as width and padding, and drawing properties, such as background color and borders.
A text node also stores its content. Node creation, property changes, and parent-child relationships are native API operations.

The native library keeps this tree, or scene, between frames.
This is the retained scene model: change the nodes you already have, then render them again.
You do not submit a fresh list of drawing commands for each frame.

Calculate positions and sizes Copy Chapter

Layout turns the tree's relationships and size rules into positions and dimensions.
The scene uses Yoga, a flexbox layout engine, with one Yoga node for each scene node.
Dimensions count terminal cells, not pixels.

The root fills the drawing area, and the box stretches across it.
The border takes one cell on each side, leaving ten cells for the label.
That places Hello at column 1, row 1, just inside the border.
Coordinates start at zero.

You did not calculate the text position yourself. The border and parent-child relationship determine it.
The same layout rules also handle padding, alignment, flexible sizes, and nested containers.

When you change a layout property, the next layout pass calculates the result.
Layout queries read stored geometry. They do not start a new pass.

Draw a grid of cells Copy Chapter

After layout, the scene paints into an in-memory grid called the framebuffer.
The box draws its border, then the label draws Hello inside it.
Each cell stores character information, foreground and background colors, and attributes such as bold or underline.

The H in Hello occupies one cell. Other text can occupy several cells or combine several code points into one displayed character.
Text drawing APIs handle that conversion. A UTF-8 byte count is not a terminal-cell width.

Painting changes the framebuffer, not the terminal. No terminal connection is necessary at this stage.

Send the result to an output destination Copy Chapter

A terminal accepts bytes, not a node tree or a framebuffer.
The native renderer encodes the cells as text, cursor movement, colors, and other control sequences.
It compares cells with its existing encoding state, so an update need not send the entire screen again.

The bytes wait in an output queue until your program delivers them.
Your program can copy them out and write them itself.
It can also let the native library write them to standard output or pass them to a writer function that your program supplies.
The delivery path is the transport. You can write to a file, a local terminal, or a connection.
The diagram shows the copy path:

┌─ Native library ────────────────┐
│ Scene nodes                     │
│   ↓ layout and painting         │
│ Grid of terminal cells          │
│   ↓ terminal encoding           │
│ Queued output bytes             │
└────────────────┬────────────────┘
                 ↓ copy
┌─ Your program ──────────────────┐
│ Write bytes to the destination  │
│ Report completed delivery       │
└─────────────────────────────────┘

A slow connection can still be sending a frame after painting finishes.
The program reports delivery as bytes reach the transport. Once delivery covers the frame's output, the native library marks that frame as presented.
This does not prove that a remote terminal visibly displayed it.

Change the label, not the tree Copy Chapter

After the first frame completes, set the label's text to Ready and repeat painting, encoding, and delivery:

┌──────────┐
│Ready     │
└──────────┘

The root, box, and label are the same nodes. Their relationships and border settings did not change.
Only the label's content changed. The retained scene produces the new frame.

Layout, painting, and encoding still have a cost.
Retaining the scene means your program describes changes instead of directing every node's drawing on every frame.

Build the program around the scene Copy Chapter

Your program is the host. It owns application state and decides when to render.
The native library does not start an application event loop or a rendering worker.

An interactive host reads input, changes nodes, and requests frames.
The programs in the language guides create this box and label, render Hello, then change it to Ready.
They write both frames to files, using the same operations as a terminal application.

Continue with Resources and ownership for object lifetimes, then Frames and output for drawing and delivery.

The C application binary interface (ABI) is experimental. Use the native library, headers, and bindings from the same revision.

Core provides a TypeScript application API over this library through Renderable and CliRenderer, not the native frame protocol.
How Core uses native explains that integration separately.

Read Host I/O and time before connecting a terminal transport.
Then choose the C or Zig guide to build and run the box-and-label program.

Packages Web Src Content Docs Reference Api Index (`packages/web/src/content/docs/reference/api-index.mdx`) Copy Section

title: API and symbol index skill: entry: true intents: [api, symbols, exports, public-api, api-index, lookup] Copy Chapter

API and symbol index

Use this page to find every published OpenTUI entry point and named export. The tables come from the generated publish maps and source barrels. They include runtime values and type-only exports.

The API reference lists the same exports with their signatures and the release that added each one. Releases lists the API changes of each release.

Support classes Copy Chapter

A row can have more than one class. Read Runtime and platform support for the supported Bun and Node.js versions.

Entry point index Copy Chapter

The runtime column describes the published target. A Node stub throws during import for each Bun-only support entry point.

See Package entry points for each entry point's role and import constraints.

`@opentui/core` Copy Chapter

The root works in Bun and supported Node.js releases. A class in these tables applies to every symbol in its row.

Renderer and render tree Copy Section

Input and selection Copy Section

Text, color, links, and clipboard Copy Section

Tree-sitter and syntax styles Copy Section

Plugins, console, and process services Copy Section

Components and component helpers Copy Section

Buffers, editing, animation, and effects Copy Section

Images, audio, and native span output Copy Section

Low-level native binding exports Copy Section

These names expose the TypeScript side of the native binding. Use the higher-level API unless a low-level guide requires one of them.

Start with Native rendering for the scene model.
The C and Zig guides cover their native interfaces, which are separate from npm entry points.

Other `@opentui/core` entry points Copy Chapter

Testing Copy Section

@opentui/core/testing works in Bun and Node.js.

Runtime plugin support Copy Section

These entry points are Bun-only. Their Node.js targets are stubs that throw during import.

Yoga Copy Section

@opentui/core/yoga works in Bun and Node.js. The root Yoga namespace exposes this module. See Yoga API for methods and ownership.

Tree-sitter assets, worker, and Node assets Copy Section

`@opentui/react` Copy Chapter

The root and compiler-selected JSX entry points work in Bun and Node.js.

Root exports Copy Section

Other React entry points Copy Section

The generated React map points /renderer runtime imports to index.js. Its declaration path points to reconciler/renderer.d.ts. Treat root values outside the four declared names as a build leak.

`@opentui/solid` Copy Chapter

The root, /components, and compiler-selected JSX entry points work in Bun and Node.js.

Root exports Copy Section

Other Solid entry points Copy Section

`@opentui/keymap` Copy Chapter

Root engine Copy Section

The root engine is host-agnostic. Use an adapter entry point to connect it to a browser or OpenTUI renderer.

Extras and graph Copy Section

Addons Copy Section

Testing and hosts Copy Section

Frameworks and runtime modules Copy Section

The runtimeModules map contains the root, both extras paths, both addon paths, and both host adapters. It loads the React and Solid paths lazily. It does not contain /testing or /runtime-modules.

`@opentui/qrcode` Copy Chapter

The package root works in Bun and Node.js. Each framework path re-exports the full root and adds its registration function.

`@opentui/ssh` Copy Chapter

The package supports Bun 1.3.14 or later and Node.js 26.4.0 or later. Use Bun 1.4.0 or later on native Windows arm64.
It has one public entry point.

`@opentui/three` Copy Chapter

Both entry points are Bun-only.

The THREE namespace exposes the installed Three.js module. The runtimeModules map contains only the @opentui/three root.

Native distribution packages Copy Chapter

The build generates eight platform packages:

• @opentui/core-darwin-x64
• @opentui/core-darwin-arm64
• @opentui/core-linux-x64
• @opentui/core-linux-arm64
• @opentui/core-linux-x64-musl
• @opentui/core-linux-arm64-musl
• @opentui/core-win32-x64
• @opentui/core-win32-arm64

Each package has one default export that resolves the native library path. These packages are internal distribution surfaces, not application APIs. Let @opentui/core select the correct package. See Runtime and platform support.

`opentui.h` Copy Chapter

The npm API and the native application binary interface (ABI) are separate surfaces. opentui.h declares the experimental C ABI. See C. The C ABI reference lists every declaration with the release that added it.

OpenTUI's TypeScript packages call the native library through internal bindings that can change with them. Use the TypeScript exports indexed above for application code.

These rows name the declarations that the native guides document. The comments in opentui.h document every declaration.

Changes since 0.5.14 Copy Chapter

Layout, hit testing, and painting now run in a native scene. Native resources belong to an owner Context.
This section lists each 0.5.14 API and behavior that was removed or changed, and what to use instead.
Each item names the changed API or behavior first. New APIs are in the tables above.

Renderer Copy Section

• addToHitGrid(), pushHitGridScissorRect(), popHitGridScissorRect(), and clearHitGridScissorRects(): removed from the renderer and RenderContext. Native code adds a hit area for each visible node and clips it to overflow ancestors. Use renderer.hitTest(x, y) to query the hit grid.
• dumpBuffers() and dumpOutputBuffer(): removed. Use test frame capture, renderer.currentRenderBuffer.withBuffers(), or a custom stdout. dumpHitGrid() remains.
• renderer.useThread and the useThread option of createCliRenderer() and createTestRenderer(): removed. Core writes output on the JavaScript thread. Remove the option.
• renderer.rendererPtr: removed, with no replacement.
• OTUI_NO_NATIVE_RENDER environment variable: removed. Use createTestRenderer().
• suspend() and resume(): now return a Promise<void>. Await them. They throw when the terminal is not set up (also after destroy()) or a transition is pending. resume() also throws when the renderer is not suspended.
• useMouse, enableKittyKeyboard(), and disableKittyKeyboard(): now throw during terminal setup, suspend, or resume, and while the renderer is suspended. screenMode now throws during setup, suspend, or resume. Change them after the transition completes.
• enableKittyKeyboard(flags): now throws RangeError when flags is not an integer from 0 to 31.
• Output stream error event: now closes the renderer and rejects renderer.closed. Handle the rejection of closed. In 0.5.14, the renderer handled the event only while Kitty file transport was active. It cancelled file transport and kept running. A failed Kitty temporary-file write still falls back to inline transport.
• Renderer methods after destroy(): setTerminalTitle(), resetTerminalBgColor(), copyToClipboardOSC52(), clearClipboardOSC52(), isOsc52Supported(), setCursorPosition(), setCursorStyle(), setCursorColor(), setMousePointer(), getCursorState(), getStats(), getNativeStats(), configureDebugOverlay(), toggleDebugOverlay(), dumpHitGrid(), hitTest(), and console.show() (also through console.toggle()) throw. getPalette() rejects. requestRender(), resize(), triggerNotification(), and getLinkAt() do nothing. Check renderer.isDestroyed first.
• getPalette(): now rejects before the terminal is set up, for example on a createTestRenderer() renderer. It also rejects while a setup, suspend, or resume is pending. Its size must be an integer from 1 to 256.
• Renderable constructors and engine.attach(): now throw for a destroyed renderer. Create renderables before you destroy the renderer.
• destroy(): restores the terminal and releases the streams asynchronously. Await renderer.closed before you reuse the streams.
• Scrollback snapshots and commits: one snapshot or commit larger than the output capacity divided by 24 bytes (about 349,000 cells by default) throws. A rowColumns value that is not an integer from 0 to the snapshot width throws RangeError. In 0.5.14, Core truncated and clamped rowColumns.

Renderables and layout Copy Section

• RootRenderable.calculateLayout(): removed. Layout runs in the native frame step. Read getLayout() after renderOnce() or await renderer.idle().
• Renderable.getLayoutNode() and the protected yogaNode: removed. Use layout properties, setMeasureProvider(), invalidateIntrinsicSize(), and getLayout(). Replace a style read such as getLayoutNode().getMaxWidth() with the renderable method of the same name, getMaxWidth(). Replace markDirty() with invalidateIntrinsicSize(), and the computed position and size getters with getLayout(). Computed padding, margin, and border have no replacement. Renderables cannot use Display.Contents. The standalone Yoga API remains.
• render(), updateLayout(), updateFromLayout(), canReuseRenderCommandList(), and the RenderCommand type: removed. Override renderSelf(buffer, deltaTime), or use the renderBefore and renderAfter paint hooks. In a subclass of TextBufferRenderable or EditBufferRenderable, the override has one parameter: renderSelf(buffer).
• Protected _x, _y, _widthValue, _heightValue, _childrenInZIndexOrder, _getVisibleChildren(), _hasVisibleChildFilter(), and getScissorRect(): removed. Use x, y, width, height, screenX, and screenY. For child culling, use the viewportCulling option of ScrollBox.
• Protected renderCursor() of edit buffer renderables: removed. Use the cursor options.
• Protected updateViewportOffset(): TextRenderable no longer calls it when it scrolls or resizes. Native code applies the viewport.
• Protected color fields of ASCIIFontRenderable: now hold RGBA values.
• Custom RenderContext: must now implement nativeScene, requestAnimationFrame(), and cancelAnimationFrame().
• Paint hooks (renderBefore, renderSelf, and renderAfter): now receive a recording buffer. buffers, withBuffers(), getRealCharBytes(), and getSpanLines() throw in a hook. Draw into a buffer that you own and compose it, or use a post-process function. A buffered: true custom renderable is different: its hooks receive its own frame buffer.
• Changes made in a paint hook: a layout, position, visibility, child, or zIndex change takes effect in the next frame. Color and text changes paint in the same frame.
• on("resized") and on("layout-changed"): now throw on a renderable that is not the root. These listeners never ran in 0.5.14. Use onSizeChange.
• Geometry after destroy(): x, y, screenX, screenY, width, and height of a renderable that is not selectable return 0 or the styled size, not the last layout. Read them before you destroy the renderable.
• RenderContext.getLifecyclePasses(): now contains only renderables whose lifecycle pass is active.
• Box customBorderChars: wide, combining, or control characters now throw.

Buffers Copy Section

• OptimizedBuffer.create(width, height, widthMethod, options): now requires options.owner. Pass renderer.nativeScene or a ResourceContext.
• buffer.buffers: works only in a post-process function. Use buffer.withBuffers(callback) elsewhere.
• Drawing into renderer.nextRenderBuffer: works only in a post-process function. renderer.currentRenderBuffer does not accept drawing. In 0.5.14, frame callbacks could draw into nextRenderBuffer, for example with ThreeCliRenderer.drawScene(). Draw into a FrameBufferRenderable instead.
• encodeUnicode(text): now returns { data } and never null. Its char values are opaque tokens for drawChar() on a buffer with the same owner. A tab encodes as two one-cell spaces.
• buffer.ptr and getNativeId(): removed. Keep the buffer object. buffer.id is only a label.
• Drawing methods: now throw RangeError for fractional, NaN, or infinite coordinates and sizes. Round them first.
• drawText() and box titles: now throw RangeError for text larger than 64 KiB of UTF-8.
• pushOpacity() and color-matrix strength: a non-finite value now throws.
• Composing a buffer into itself now throws. setRespectAlpha() on a renderer buffer throws.
• setCell(), setCellWithAlphaBlending(), drawChar(), and drawText(): now reject attribute bits 8 to 31. Pass only text attributes. Use the styled-text link() helper for hyperlinks.

Text and editing Copy Section

• SyntaxStyle.create(), fromStyles(styles), and fromTheme(theme): now create(owner), fromStyles(styles, owner), and fromTheme(theme, owner). Pass renderer.nativeScene, or a ResourceContext for standalone use.
• TextBuffer.create(widthMethod) and EditBuffer.create(widthMethod): now create(widthMethod, owner).
• .ptr on TextBuffer, TextBufferView, EditBuffer, EditorView, and SyntaxStyle: removed. Their constructors take Context handles. Use the create() factories.
• EditBuffer.setText(), insertText(), and replaceText(), the same Textarea and Input methods, Textarea initialValue, Input.value, and the placeholder of both: now show control characters other than tab, carriage return, and line feed as notation, such as ^L or <85>. In 0.5.14, the cursor could not move past or delete them, and the terminal received them.
• TextBuffer.loadFile(): now rejects invalid UTF-8.
• Text buffer and text view offsets: must be integers. Other values throw RangeError.
• Highlight priority above 255 or hlRef above 65535: now throws. In 0.5.14, the value wrapped.
• Color getters of text, text table, ASCII font, Markdown, Diff, line number, and QR code renderables, and the SyntaxStyle style getters: now return copies. Change a color through its setter. ASCIIFont.color returns an RGBA.

Resources and native bindings Copy Section

• Minimum Bun version: now 1.3.14 (was 1.3.0), the tested minimum. Bun 1.3.0 to 1.3.3 convert some FFI pointer arguments to wrong addresses. Bun 1.3.4 to 1.3.6 can crash after a Worker exits. Bun 1.3.7 intermittently hangs while it loads modules.
• Clipboard class: removed. Use renderer.copyToClipboardOSC52() and clearClipboardOSC52(), or createClipboard() with createHostClipboard() and createRendererClipboardAdapter(renderer).
• Native resources: each resource now belongs to one owner Context. Resources from different owners cannot be used together. Drawing a NativeImage into a renderer copies it into the renderer's Context.
• Images that ImageRenderable loads: belong to the renderer's Context and throw after renderer.destroy(). To keep an image, load it yourself, for example with NativeImage.load(), and pass it as source.
• getAllocatorStats(): does not count Context memory. getArenaAllocatedBytes() always returns 0. Use process.memoryUsage().rss for total memory.
• Handle types RendererHandle, OptimizedBufferHandle, TextBufferHandle, TextBufferViewHandle, EditBufferHandle, EditorViewHandle, SyntaxStyleHandle, EventSinkHandle, NativeRenderableHandle, EmbeddedTerminalHandle, NativeMeasureTargetHandle, NativeMeasureTargetKind, NativeRenderOperationResult, and NativeRendererCreateOptions: removed. Use the Context*Handle types, SessionHandle, and SceneNodeHandle. ImageHandle is now an alias of ContextImageHandle.
• Pointer-based RenderLib methods, such as createRenderer, createOptimizedBuffer, bufferDrawText, setUseThread, and nativeRenderableSetMeasureTarget: removed. Use the public classes. Standalone Yoga nodes measure only with JavaScript measure functions.
• Standalone Yoga: Config.free() now throws while nodes from that config remain. Invalid arguments, such as an out-of-range child index or enum value, throw YogaError. Measure and dirtied functions must return synchronously and must not change Yoga nodes. See Yoga API.

SSH Copy Section

• @opentui/ssh session.write(): can now throw OutputPressureError or RangeError. cols and rows hold the requested size until the renderer attaches. onClose runs at logical close, before the renderer finishes closing.

Native libraries Copy Section

• Legacy native exports, such as createRenderer and bufferDrawText: removed. Use the ot_* C ABI in opentui.h. See C.
• Zig GraphemePool.alloc(), GraphemePool.allocUnowned(), and LinkPool.alloc(): replaced by acquire(). It copies the bytes and returns an ID that holds one reference. Call decref() to release it. alloc() returned an ID with no references, and allocUnowned() did not copy.
• Zig GraphemePool.freeUnreferenced() and the global pools (initGlobalPool(), initGlobalPoolWithOptions(), deinitGlobalPool(), initGlobalLinkPool(), and deinitGlobalLinkPool()): removed. Use explicit pools or opentui.Context. See Zig.
• Zig UnifiedTextBuffer.setStyledText() and StyledChunk: removed. Use replaceOwnedStyledText() with OwnedStyledChunk. clear() and reset() can now return errors.
• Zig CliRenderer.dumpBuffers() and dumpOutputBuffer(): removed.

Packages React Docs EXTEND (`packages/react/docs/EXTEND.md`) Copy Section

OpenTUI React Component Extension

The extend function adds custom renderable classes to the component catalogue of the OpenTUI React reconciler. It works like extend in @react-three/fiber, which adds Three.js objects.

Basic Usage Copy Chapter

Extending Components Copy Section

import { BoxRenderable, OptimizedBuffer, RGBA, type BoxOptions, type RenderContext } from "@opentui/core"
import { extend } from "@opentui/react"

class ConsoleButton extends BoxRenderable {
  public label: string = "Button"

  constructor(ctx: RenderContext, options: BoxOptions & { label: string }) {
    super(ctx, options)
    // Custom initialization

    this.height = 3
    this.width = 24
  }

  protected renderSelf(buffer: OptimizedBuffer): void {
    super.renderSelf(buffer)

    const centerX = this.x + Math.floor(this.width / 2 - this.label.length / 2)
    const centerY = this.y + Math.floor(this.height / 2)

    buffer.drawText(this.label, centerX, centerY, RGBA.fromInts(255, 255, 255, 255))
  }
}

declare module "@opentui/react" {
  interface OpenTUIComponents {
    consoleButton: typeof ConsoleButton
  }
}

// Extend components
extend({
  consoleButton: ConsoleButton,
})

// Now you can use them in JSX
function App() {
  return <consoleButton label="Click me!" />
}

React calls the constructor with { id, ...props }. After construction, React assigns each prop to the instance again. In this example, React sets label after the class field sets it to "Button".

renderSelf() is a paint hook. It uses screen cell coordinates, so the example places the label relative to this.x and this.y.

TypeScript Support Copy Chapter

For full TypeScript support, declare your extended components with module augmentation:

// In your component file or declaration file
declare module "@opentui/react" {
  interface OpenTUIComponents {
    consoleButton: typeof ConsoleButton
  }
}

// Then extend and use with full type safety
extend({
  consoleButton: ConsoleButton,
})

// TypeScript will now know about these components
<consoleButton label="Typed!" />

API Reference Copy Chapter

`extend(components)` Copy Section

Adds renderable components to the component catalogue.

Parameters:

• components: Object mapping component names to renderable constructors

Returns:

• void

`getComponentCatalogue()` Copy Section

Returns the current component catalogue. The reconciler uses it to find the class for each JSX element.

Best Practices Copy Chapter

1. Declare types with module augmentation: TypeScript then completes and checks the props of each custom element.

2. Call requestRender(): Call requestRender() in each property setter that changes what the component draws.

3. Extend from appropriate base classes: Use BoxRenderable for containers, TextRenderable for text, and so on.

Limitations Copy Chapter

• Extended components must extend from OpenTUI's core renderable classes
• extend() replaces an existing entry with the same name, including a built-in component. Use unique names.
• TypeScript support requires manual module augmentation declarations

Packages Core Src Benchmark Docs Ffi Fast Path (`packages/core/src/benchmark/docs/ffi-fast-path.md`) Copy Section

FFI Fast Path Benchmarks

Purpose Copy Chapter

This suite measures OpenTUI FFI wrapper overhead in Bun and Node without changing native behavior. It exists because an optimization can help one runtime and regress the other.

Constraints Copy Chapter