OpenTUI

https://opentui.com/docs/
Admin
OpenTUI is a TypeScript library for building terminal user interfaces with components, layout...
Tokens:841,717
Snippets:6,570
Trust Score:5.7
Update:1 hour ago
Show doc for...
Tokens:
Raw
### Prepare Zig dependencies with Bun

Source: https://opentui.com/docs/native/zig/

Run from the repository root to install dependencies and prepare the Zig native workspace. Requires Bun; the finished program does not need Bun.

```bash
bun install
(cd packages/native && bun run prepare:zig)
```

--------------------------------

### Install OpenTUI example browser with curl

Source: https://opentui.com/docs/

Runs the OpenTUI example browser without cloning the repository. Supports macOS x64 and arm64, Linux x64, and Windows x64 (including x64 WSL and Git Bash). On Windows, download the latest release from GitHub Releases instead.

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

--------------------------------

### Copy hello example files to a new Zig project

Source: https://opentui.com/docs/native/zig/

Creates a native-zig-demo project by copying the build files and sources from the native workspace's examples/hello package. After copying, adjust the opentui dependency path in build.zig.zon.

```bash
mkdir -p native-zig-demo/src
cp packages/native/examples/hello/build.zig native-zig-demo/
cp packages/native/examples/hello/build.zig.zon native-zig-demo/
cp packages/native/examples/hello/src/*.zig native-zig-demo/src/
```

--------------------------------

### Install OpenTUI skill with npx skills

Source: https://opentui.com/docs/

Installs the OpenTUI skill for AI coding assistants. Add -g to install globally for every project. Use npx skills update to move to the newest release. For the main branch, install from https://opentui.com/docs/next instead.

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

--------------------------------

### Run the Zig test suite

Source: https://opentui.com/docs/native/zig/

Runs the test suite from the project directory, showing all results. This executes the acceptance test defined in `src/acceptance_test.zig`.

```bash
zig build test --summary all
```

--------------------------------

### Create project and add OpenTUI

Source: https://opentui.com/docs/getting-started/quickstart/

Sets up an empty Bun project and installs @opentui/core. Run these commands in a terminal before creating the app.

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

--------------------------------

### sceneFrameStepWithRecording

Source: https://opentui.com/docs/native/zig/

Advances the frame rendering process by processing a work quota. Call repeatedly until it returns a DONE draft, then commit the draft with sceneFrameCommit.

```APIDOC
## sceneFrameStepWithRecording

### Description
Advances the frame rendering process by processing a work quota. Call repeatedly until it returns a DONE draft, then commit the draft with sceneFrameCommit.

### Method
Function call

### Parameters
- **max_work_items** (work quota) - Required - The maximum number of work items to process in this call.
- **recording** (optional) - Required for RECORD requests - A recording for the slots that sceneFramePaintSlots returns. Pass null for every other request.

### Returns
- A draft status (e.g., DONE) indicating the current state of the frame.
```

--------------------------------

### Run the Zig build

Source: https://opentui.com/docs/native/zig/

Builds and runs the project from the new project directory. The program creates or replaces `hello.ansi` and `ready.ansi` in that directory; `ready.ansi` updates the first frame and is not a standalone screen. The build defaults to the native CPU and OS with musl on Linux and accepts standard `-Dtarget` and `-Doptimize` options.

```bash
zig build run
```

--------------------------------

### sceneFramePaintSlots

Source: https://opentui.com/docs/native/zig/

Returns the slots that need to be recorded for a RECORD request. Use the returned slots to provide a recording to sceneFrameStepWithRecording.

```APIDOC
## sceneFramePaintSlots

### Description
Returns the slots that need to be recorded for a RECORD request. Use the returned slots to provide a recording to sceneFrameStepWithRecording.

### Method
Function call

### Returns
- A list of slots that require recording.
```

--------------------------------

### src/main.zig: Create scene, render two frames, and write ANSI output

Source: https://opentui.com/docs/native/zig/

Initializes an OpenTUI Context and Session, builds a scene with a root, box, and label, then renders two frames ('hello.ansi' and 'ready.ansi') via the write_frame helper. Requires a valid allocator and std.Io; errdefer cancels the session on failure and defer releases the context. The program uses remote mode with an empty forwarded environment.

```zig
const std = @import("std");
const opentui = @import("opentui");

var io_threaded: std.Io.Threaded = .init_single_threaded;
pub const io = io_threaded.io();

pub fn main(init: std.process.Init) !void {
    const context = try opentui.Context.init(init.gpa, io, .{
        .object_capacity = 8,
        .render_cells_max = 36,
    });
    defer context.deinit() catch unreachable;

    const session = try context.createSession(.{
        .chunk_size = 4096,
        .chunk_count = 2,
        .span_capacity = 2,
    });
    errdefer context.cancelSession(session) catch unreachable;
    try context.attachSessionRenderer(session, 12, 3, .{
        .remote_mode = .remote,
        .forwarded_env = &.{},
    });

    const root = try context.sceneCreateNode(session, 0, 1);
    const box = try context.sceneCreateNode(session, 1, 2);
    const label = try context.sceneCreateNode(session, 2, 3);
    try context.sceneSetPaint(box, .{ .borderSides = 15 });
    try context.sceneSetText(label, "Hello");
    try context.sceneMoveNode(box, root, 0);
    try context.sceneMoveNode(label, box, 0);

    try write_frame(context, session, "hello.ansi");
    try context.sceneSetText(label, "Ready");
    try write_frame(context, session, "ready.ansi");
    try context.beginSessionClose(session);
}

fn write_frame(context: *opentui.Context, session: opentui.context.Handle, path: []const u8) !void {
    const file = try std.Io.Dir.cwd().createFile(io, path, .{});
    defer file.close(io);

    const frame = try context.scenePaint(session, .{ 0, 0, 0, 255 }, false, 0);
    switch (try context.sceneFrameCommit(session, frame, false)) {
        .pending, .presented => {},
        .skipped, .failed => return error.FrameNotAccepted,
    }
    var bytes: [512]u8 = undefined;
    while (try context.readOutput(session, &bytes)) |ticket| {
        file.writeStreamingAll(io, bytes[0..ticket.len]) catch |err| {
            try context.completeOutput(session, ticket, .failed);
            return err;
        };
        try context.completeOutput(session, ticket, .written);
    }
}
```

--------------------------------

### sceneFrameCommit

Source: https://opentui.com/docs/native/zig/

Commits a completed draft produced by sceneFrameStepWithRecording. This finalizes the frame for output.

```APIDOC
## sceneFrameCommit

### Description
Commits a completed draft produced by sceneFrameStepWithRecording. This finalizes the frame for output.

### Method
Function call

### Parameters
- **draft** - Required - The draft returned by sceneFrameStepWithRecording when it returns DONE.
```

--------------------------------

### Install @opentui/keymap

Source: https://opentui.com/docs/keymap/overview/

Install the @opentui/keymap package using bun.

```bash
bun add @opentui/keymap
```

--------------------------------

### server.listen(port, host)

Source: https://opentui.com/docs/reference/ssh/

Starts the server and resolves with listener information including host, port, and fingerprints.

```APIDOC
## server.listen(port, host)

### Description
Starts the server and resolves with listener information including host, port, and fingerprints.

### Method
Function

### Signature
`listen(port = 2222, host = "127.0.0.1")`

### Parameters
- **port** (number) - Optional - Port to listen on. Default `2222`. Use `0` for an ephemeral port.
- **host** (string) - Optional - Host to bind. Default `"127.0.0.1"`.

### Returns
- **Promise<ListenInfo>** - Resolves with `{ host, port, fingerprints }`.

### Example
```ts
const info = await server.listen()
```

### Response
#### Success Response
- **host** (string) - The bound host.
- **port** (number) - The bound port.
- **fingerprints** (string[]) - List of host key fingerprints.

#### Response Example
```ts
interface ListenInfo {
  host: string
  port: number
  fingerprints: string[]
}
```
```

--------------------------------

### Basic setup with KeymapProvider and useBindings

Source: https://opentui.com/docs/keymap/solid/

Sets up a Solid app with an OpenTUI keymap. Requires `Keymap<Renderable, KeyEvent>` from `@opentui/keymap/opentui`. The default factory installs the parser and standard field addons; the provider does not add features or own renderer cleanup.

```typescript
import { createCliRenderer } from "@opentui/core"
import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
import { KeymapProvider, useBindings } from "@opentui/keymap/solid"
import { render } from "@opentui/solid"

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

function App() {
  useBindings(() => ({
    commands: [
      {
        name: "app.quit",
        run() {
          renderer.destroy()
        },
      },
    ],
    bindings: [{ key: "q", cmd: "app.quit" }],
  }))

  return <text>Press q to quit</text>
}

await render(
  () => (
    <KeymapProvider keymap={keymap}>
      <App />
    </KeymapProvider>
  ),
  renderer,
)
```

--------------------------------

### AudioEngineLib.audioStart

Source: https://opentui.com/docs/releases/0.3.3/

Starts the audio engine with optional start options. Returns a status code.

```APIDOC
## AudioEngineLib.audioStart

### Description
Starts the audio engine with optional start options. Returns a status code.

### Method
Function call

### Signature
`audioStart(engine: AudioEngineHandle, options?: AudioStartOptions | null) => number`

### Parameters
- **engine** (AudioEngineHandle) - Required - The audio engine handle.
- **options** (AudioStartOptions | null) - Optional - Start options.

### Return Value
- **number** - Status code.
```

--------------------------------

### acquireResource(symbol, setup)

Source: https://opentui.com/docs/keymap/core/

Shares reference-counted setup and returns a release function.

```APIDOC
## Method: acquireResource(symbol, setup)

### Description
Shares reference-counted setup and returns a release function.

### Parameters
- `symbol` (symbol) - Required - Resource identifier.
- `setup` (function) - Required - Setup function.

### Returns
A release function.
```

--------------------------------

### useTimeline(options?)

Source: https://opentui.com/docs/bindings/solid/

Creates and returns one Timeline during component setup. It registers the timeline on mount and starts it unless `autoplay` is `false`. Solid pauses and unregisters it during owner cleanup.

```APIDOC
## useTimeline(options?)

### Description
`useTimeline()` creates and returns one `Timeline` during component setup. It registers the timeline on mount and starts it unless `autoplay` is `false`. Solid pauses and unregisters it during owner cleanup.

### Method
Hook

### Endpoint
useTimeline(options?)

### Parameters
#### Parameters
- **options** (object) - Optional - Configuration options. May include `autoplay` (boolean) to control whether the timeline starts automatically.

### Request Example
```tsx
import { useTimeline } from "@opentui/solid"

const App = () => {
  const timeline = useTimeline({ autoplay: false })
  return <text>{timeline.isPlaying ? "Playing" : "Paused"}</text>
}
```

### Response
#### Success Response
Returns a `Timeline` object with an `isPlaying` property.

```

--------------------------------

### start(options?)

Source: https://opentui.com/docs/core-concepts/audio/

Starts the audio engine with optional low-level start options. Accepts every AudioStartOptions field. An explicit start(options) replaces the construction-time startOptions for that call; it does not merge the two objects.

```APIDOC
## start(options?)

### Description
Starts the audio engine with optional low-level start options. Accepts every AudioStartOptions field. An explicit start(options) replaces the construction-time startOptions for that call; it does not merge the two objects.

### Parameters
#### Optional Parameters
- **options** (AudioStartOptions) - Optional - Start options. Fields include:
  - `periodSizeInFrames` (number) - Optional - Period size in frames.
  - `periodSizeInMilliseconds` (number) - Optional - Period size in milliseconds.
  - `periods` (number) - Optional - Number of periods.
  - `performanceProfile` (number) - Optional - Performance profile; value `1` selects conservative mode, every other packed value selects low latency.
  - `shareMode` (number) - Optional - Share mode; value `1` selects exclusive mode, every other packed value selects shared mode.
  - `noPreSilencedOutputBuffer` (boolean) - Optional - Flag.
  - `noClip` (boolean) - Optional - Flag.
  - `noDisableDenormals` (boolean) - Optional - Flag.
  - `noFixedSizedCallback` (boolean) - Optional - Flag.
  - `wasapiNoAutoConvertSrc` (boolean) - Optional - Flag.
  - `wasapiNoDefaultQualitySrc` (boolean) - Optional - Flag.
  - `alsaNoMMap` (boolean) - Optional - Flag.
  - `alsaNoAutoFormat` (boolean) - Optional - Flag.
  - `alsaNoAutoChannels` (boolean) - Optional - Flag.
  - `alsaNoAutoResample` (boolean) - Optional - Flag.

### Notes
- Native defaults use zero for numeric fields and `false` for flags.
- `AudioSetupOptions.startOptions` also accepts the same fields.
```

--------------------------------

### Build the native library with Bun

Source: https://opentui.com/docs/native/c/

Run these commands from the repository root to install dependencies and build the native workspace. The build outputs the header and libraries to lib/<target>/ inside the native workspace, e.g., lib/x86_64-linux/ on Linux x86_64 with glibc.

```bash
bun install
cd packages/native
bun run build
```

--------------------------------

### start()

Source: https://opentui.com/docs/core-concepts/audio/

Opens the selected playback device and starts the mixer. Returns false when native startup fails.

```APIDOC
## start()

### Description
Opens the selected playback device and starts the mixer. Returns `false` when native startup fails.

### Method
start

### Parameters
None

### Returns
- **boolean** - `true` on success, `false` on native startup failure.

### Notes
- The device stays open until `stop()` or `dispose()` is called.
- Idle voices do not close the device.
```

--------------------------------

### AudioStartOptions

Source: https://opentui.com/docs/api/core/

Options for starting audio playback.

```APIDOC
## AudioStartOptions

### Properties
- **alsaNoAutoChannels** (boolean) - Optional - Disable ALSA auto channel configuration.
- **alsaNoAutoFormat** (boolean) - Optional - Disable ALSA auto format configuration.
- **alsaNoAutoResample** (boolean) - Optional - Disable ALSA auto resampling.
- **alsaNoMMap** (boolean) - Optional - Disable ALSA memory mapping.
- **noClip** (boolean) - Optional - Disable clipping.
- **noDisableDenormals** (boolean) - Optional - Disable denormal handling.
- **noFixedSizedCallback** (boolean) - Optional - Disable fixed-size callbacks.
- **noPreSilencedOutputBuffer** (boolean) - Optional - Disable pre-silenced output buffer.
- **performanceProfile** (number) - Optional - Performance profile identifier.
- **periodSizeInFrames** (number) - Optional - Period size in frames.
- **periodSizeInMilliseconds** (number) - Optional - Period size in milliseconds.
- **periods** (number) - Optional - Number of periods.
- **shareMode** (number) - Optional - Share mode identifier.
- **wasapiNoAutoConvertSrc** (boolean) - Optional - Disable WASAPI auto source conversion.
- **wasapiNoDefaultQualitySrc** (boolean) - Optional - Disable WASAPI default quality source.
```

--------------------------------

### CliRenderer.start(): void

Source: https://opentui.com/docs/api/core/

Starts the renderer.

```APIDOC
## CliRenderer.start(): void

### Description
Starts the renderer.

### Method
start

### Parameters
None

### Returns
void
```

--------------------------------

### Install solid-js and @opentui/solid

Source: https://opentui.com/docs/bindings/solid/

Install the required packages. @opentui/solid requires solid-js 1.9.12 exactly.

```bash
bun install solid-js @opentui/solid
```

--------------------------------

### start()

Source: https://opentui.com/docs/core-concepts/renderer/

Starts continuous rendering. The renderer will render frames at the rate specified by targetFps, with maxFps capping immediate extra frames.

```APIDOC
## start()

### Description
Starts continuous rendering. The renderer will render frames at the rate specified by targetFps, with maxFps capping immediate extra frames.

### Method
start

### Parameters
None

### Example
```
renderer.start()
```

```

--------------------------------

### start(options?)

Source: https://opentui.com/docs/core-concepts/audio/

Starts the mixer and a playback device. Returns a boolean indicating success.

```APIDOC
## start(options?)

### Description
Starts the mixer and a playback device.

### Method
start

### Parameters
- **options** (object) - Optional - Configuration options.

### Returns
- **boolean** - True if the mixer and playback device started successfully.
```

--------------------------------

### Test drawing into an owned buffer (acceptance_test.zig)

Source: https://opentui.com/docs/native/zig/

Offscreen drawing test that uses only a Context and a cell buffer (no Session or terminal). Draws `Hello` into five cells, borrows the cell storage, and releases it before destroying the buffer. Save as `src/acceptance_test.zig` (the test root of the copied build) to replace the copied acceptance tests. The character comparison works for ASCII; other text may use pooled graphemes and continuation cells. Use drawing methods to change cells, not raw character entries.

```zig
const std = @import("std");
const opentui = @import("opentui");

test "draw and inspect an owned buffer" {
    const context = try opentui.Context.init(std.testing.allocator, std.testing.io, .{
        .object_capacity = 2,
        .render_cells_max = 5,
    });
    defer context.deinit() catch unreachable;

    const buffer = try context.createBuffer(5, 1, .{});
    try context.drawBufferText(buffer, "Hello", 0, 0, opentui.rgbColor(255, 255, 255, 255), null, 0);

    {
        const lease = try context.acquireOwnedBufferLease(buffer);
        defer context.releaseBufferLease(lease) catch unreachable;
        const cells = try context.bufferLeaseSnapshot(lease);
        try std.testing.expectEqualSlices(u32, &.{ 'H', 'e', 'l', 'l', 'o' }, cells.buffer.char);
    }
    try context.destroy(buffer);
}
```

--------------------------------

### Audio.startMixer(): boolean

Source: https://opentui.com/docs/api/core/

Starts the audio mixer.

```APIDOC
## Audio.startMixer(): boolean

### Description
Starts the audio mixer.

### Method
startMixer

### Parameters
None

### Returns
- **boolean** - True if the mixer started successfully.
```

--------------------------------

### Install @opentui/qrcode package

Source: https://opentui.com/docs/components/qr-code/

Install the QR code package separately before using QRCodeRenderable or the React/Solid components.

```bash
bun add @opentui/qrcode
```

--------------------------------

### acquireResource(symbol, setup)

Source: https://opentui.com/docs/keymap/custom-addons/

Shares a resource among addon registrations on one keymap. The first holder runs setup() and stores its disposer; later holders increment the reference count. Each holder receives its own release function.

```APIDOC
## acquireResource(symbol, setup)

### Description
Shares a resource among addon registrations on one keymap. The first holder runs `setup()` and stores its disposer; later holders increment the reference count. Each holder receives its own release function.

### Method
`acquireResource`

### Parameters
- **symbol** (symbol) - Required - A module-private symbol identifying the shared resource.
- **setup** (function) - Required - A function that initializes the resource and returns a disposer.

### Behavior
- The first holder runs `setup()` and stores its disposer.
- Later holders for the same symbol increment the reference count.
- Each holder receives its own release function.
- The resource disposer runs after the last release.
- Host destruction disposes every retained resource.
- A thrown setup is not stored.

### Returns
- **release** (function) - A function to release the resource for the current holder.
```

--------------------------------

### ot_session_setup_terminal

Source: https://opentui.com/docs/native/frames/

Requests terminal setup. Must be called after creating a Session with reserved control capacity and attaching its renderer. Setup does not wait for terminal capability replies.

```APIDOC
## ot_session_setup_terminal

### Description
Requests terminal setup. Must be called after creating a Session with reserved control capacity and attaching its renderer. Setup does not wait for terminal capability replies.

### Method
C function

### Signature
`ot_session_setup_terminal(session)`

### Parameters
- **session** (opaque) - Required - The Session to set up.

### Notes
- After calling, pump and deliver setup output until the terminal state is active.
- The host must still read input and forward complete capability replies with `ot_session_control` and `OT_CONTROL_CAPABILITY_RESPONSE`.
```

--------------------------------

### useTimeline(options?) - Create and manage a timeline

Source: https://opentui.com/docs/bindings/solid/

Creates and returns one Timeline during component setup. Registers on mount and starts unless autoplay is false. The example shows a timeline with autoplay disabled.

```tsx
import { useTimeline } from "@opentui/solid"

const App = () => {
  const timeline = useTimeline({ autoplay: false })
  return <text>{timeline.isPlaying ? "Playing" : "Paused"}</text>
}
```

--------------------------------

### useTerminalDimensions() - Get reactive terminal dimensions

Source: https://opentui.com/docs/bindings/solid/

Get reactive terminal dimensions as a Solid signal. The example displays the current width and height.

```tsx
import { useTerminalDimensions } from "@opentui/solid"

const App = () => {
  const dimensions = useTerminalDimensions()

  return (
    <text>
      Terminal: {dimensions().width}x{dimensions().height}
    </text>
  )
}
```

--------------------------------

### Side-effect installer for runtime plugin support

Source: https://opentui.com/docs/extend/runtime-plugins/

Use the side-effect installer when the default runtime module map is complete. It must be imported before any dynamic import of the plugin. This example is Bun-only and uses the React installer.

```javascript
import "@opentui/react/runtime-plugin-support"

const loaded = await import(pluginUrl)
```

--------------------------------

### sceneGetSliderThumb

Source: https://opentui.com/docs/api/core/

Gets the slider thumb size and start position for a scene node.

```APIDOC
## sceneGetSliderThumb

### Description
Gets the slider thumb size and start position for a scene node.

### Method
sceneGetSliderThumb

### Signature
FFIRenderLib.sceneGetSliderThumb(context: NativeContextHandle, node: SceneNodeHandle): { size: number; start: number; }

### Parameters
- **context** (NativeContextHandle) - Required - The native context handle.
- **node** (SceneNodeHandle) - Required - The scene node handle.

### Returns
- **{ size: number; start: number; }** - The thumb size and start position.
```

--------------------------------

### Install @opentui/ssh and @opentui/core

Source: https://opentui.com/docs/reference/ssh/

Install the SSH package and its peer dependency. Requires Bun >=1.3.14 or Node.js >=26.4.0; use Bun >=1.4.0 on native Windows arm64.

```bash
bun add @opentui/ssh @opentui/core
```

--------------------------------

### server.serve(handler)

Source: https://opentui.com/docs/reference/ssh/

Starts the server and invokes the provided handler for each session.

```APIDOC
## server.serve(handler)

### Description
Starts the server and invokes the provided handler for each session.

### Method
N/A (SDK method)

### Endpoint
N/A

### Parameters
#### Handler
- **handler** (function) - Required - A function that receives a `session` object and can access `session.context` and `session.identity`.

### Request Example
```typescript
server.serve((session) => {
  console.log(session.context.tier)
})
```

### Response
Starts the server. No return value is documented.
```

--------------------------------

### NativeSession.setupTerminal(options?)

Source: https://opentui.com/docs/api/core/

Sets up the terminal. Returns a Promise that resolves when setup is complete.

```APIDOC
## NativeSession.setupTerminal(options?)

### Description
Sets up the terminal.

### Method
setupTerminal

### Parameters
- **options** (NativeSessionTerminalOptions) - Optional - Terminal options.

### Returns
- **Promise<void>** - Resolves when setup is complete.

### Availability
0.6.0
```

--------------------------------

### Audio.start(options?: AudioStartOptions): boolean

Source: https://opentui.com/docs/api/core/

Starts the audio system with optional options.

```APIDOC
## Audio.start(options?: AudioStartOptions): boolean

### Description
Starts the audio system with optional options.

### Method
start

### Parameters
- **options** (AudioStartOptions) - Optional - Options for starting the audio system.

### Returns
- **boolean** - True if the audio system started successfully.
```

--------------------------------

### Welcome screen example

Source: https://opentui.com/docs/components/ascii-font/

Builds a centered welcome screen with a huge cyan 'OPENTUI' ASCII font, a subtitle, and a prompt. Uses BoxRenderable for layout and TextRenderable for regular text.

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

const renderer = await createCliRenderer()

const welcomeScreen = new BoxRenderable(renderer, {
  width: "100%",
  height: "100%",
  flexDirection: "column",
  alignItems: "center",
  justifyContent: "center",
})
welcomeScreen.add(
  new ASCIIFontRenderable(renderer, {
    text: "OPENTUI",
    font: "huge",
    color: "#00FFFF",
  }),
)
welcomeScreen.add(
  new TextRenderable(renderer, {
    content: "Terminal UI Framework",
    fg: "#888888",
  }),
)
welcomeScreen.add(
  new TextRenderable(renderer, {
    content: "Press any key to continue...",
    fg: "#444444",
  }),
)

renderer.root.add(welcomeScreen)
```

--------------------------------

### Play a URL with Audio.playStreamUrl and error handling

Source: https://opentui.com/docs/application-apis/audio-streaming/

Creates an Audio instance with autoStart disabled, starts a playback device, and plays a stream URL with an AbortController timeout and reconnect options. Attach the Audio error listener before start() and the AudioStream error listener immediately after setup resolves; setup errors reject the entry-method promise, while later stream errors emit asynchronously and can throw if unhandled.

```TypeScript
import { Audio, AudioStreamError, type AudioStream } from "@opentui/core"

const audio = Audio.create({ autoStart: false })
const controller = new AbortController()
const stopTimer = setTimeout(() => controller.abort(), 30_000)
let stream: AudioStream | null = null

function reportSetupError(error: unknown): void {
  if (error instanceof AudioStreamError) {
    console.error(`${error.context.action}: ${error.message}`)
  } else if (!(error instanceof DOMException && error.name === "AbortError")) {
    throw error
  }
}

audio.on("error", (error, context) => {
  console.error(`${context.action}: ${error.message}`)
})

try {
  if (!audio.start()) throw new Error("No playback device is available")

  stream = await audio.playStreamUrl("https://localhost/radio", {
    signal: controller.signal,
    reconnect: { maxRetries: 5 },
  })

  stream.on("error", (error, context) => {
    console.error(`${context.action}: ${error.message}`)
  })

  await stream.closed
} catch (error) {
  reportSetupError(error)
} finally {
  clearTimeout(stopTimer)
  if (stream != null && stream.state !== "ended" && stream.state !== "errored" && stream.state !== "disposed") {
    stream.dispose()
  }
  await stream?.closed
  audio.dispose()
}

```

--------------------------------

### CliRenderer.setupTerminal(): Promise<void>

Source: https://opentui.com/docs/api/core/

Sets up the terminal. Returns a promise that resolves when setup is complete.

```APIDOC
## CliRenderer.setupTerminal(): Promise<void>

### Description
Sets up the terminal.

### Method
setupTerminal

### Parameters
None

### Returns
Promise<void>
```

--------------------------------

### audio.recordToFile

Source: https://opentui.com/docs/application-apis/audio-capture/

Starts recording audio to a WAV file. Returns an AudioRecorder instance. Setup errors reject this method.

```APIDOC
## audio.recordToFile(filePath, options?)

### Description
Starts recording audio to a WAV file. Returns an AudioRecorder instance. Setup errors reject this method.

### Method
`audio.recordToFile(filePath, options?)`

### Parameters
- `filePath` (string) - Required - Destination file path. Must be a nonempty string without NUL bytes. Parent directory must exist.
- `options` (object) - Optional - Recording options. Supported fields: `channels` (number) - Optional - Number of audio channels. Default is 1.

### Returns
- `Promise<AudioRecorder>` - A promise that resolves to an AudioRecorder instance.

### Example
```typescript
const activeRecorder = await audio.recordToFile(recording, { channels: 1 })
```
```

--------------------------------

### setupAudio(options?)

Source: https://opentui.com/docs/core-concepts/audio/

Wrapper for Audio.create that initializes the audio engine synchronously. Throws AudioInitializationError if initialization fails.

```APIDOC
## setupAudio(options?)

### Description
Wrapper for `Audio.create` that initializes the audio engine synchronously. Throws `AudioInitializationError` if initialization fails.

### Method
`setupAudio`

### Parameters
#### Options (`AudioSetupOptions`)
- **autoStart** (boolean) - Optional - Default `false` - Opens and starts the playback device during construction.
- **sampleRate** (number) - Optional - Default `48000` - Sets the engine and capture sample rate.
- **playbackChannels** (number) - Optional - Default `2` - Requests the playback device channel count.
- **startOptions** (object) - Optional - Native defaults - Supplies defaults for `autoStart` and later `start()` calls.

### Errors
Throws `AudioInitializationError` with one of the following `action` values:
- `resolveRenderLib` - Failed to resolve and load the native OpenTUI library.
- `createAudioEngine` - Failed to create the native audio engine.
- `start` - Failed to apply `startOptions` and complete automatic playback startup.

### Notes
- Initializes synchronously.
- A failed automatic start destroys the partial native engine.
- Successful automatic startup emits no `started` event because listeners cannot exist during construction.
```

--------------------------------

### setupAudio(options?): Audio

Source: https://opentui.com/docs/api/core/

Sets up audio with optional options. This function is part of the Audio module.

```APIDOC
## setupAudio(options?): Audio

### Description
Sets up audio with optional options.

### Signature
`function setupAudio(options?: AudioSetupOptions): Audio`

### Parameters
- **options** (AudioSetupOptions) - Optional - The audio setup options.

### Returns
- **Audio** - The audio instance.
```

--------------------------------

### destroyTreeSitterClient()

Source: https://opentui.com/docs/core-concepts/lifecycle/

Releases the process singleton. Destruction of the last tracked renderer starts singleton cleanup, but does not await that promise.

```APIDOC
## destroyTreeSitterClient()

### Description
Releases the process singleton. Destruction of the last tracked renderer starts singleton cleanup, but does not await that promise.

### Method
Function

### Signature
`destroyTreeSitterClient()`

### Parameters
None

### Returns
- Promise that resolves when the singleton is released.

### Usage Example
```js
await destroyTreeSitterClient()
```
```

--------------------------------

### RenderLib.setupTerminal

Source: https://opentui.com/docs/releases/0.3.3/

Sets up the terminal with the option to use an alternate screen buffer.

```APIDOC
## RenderLib.setupTerminal

### Description
Sets up the terminal with the option to use an alternate screen buffer.

### Method
property

### Signature
`setupTerminal(renderer: RendererHandle, useAlternateScreen: boolean) => void`

### Parameters
- **renderer** (RendererHandle) - Required - The renderer handle.
- **useAlternateScreen** (boolean) - Required - Whether to use the alternate screen buffer.

### Returns
void
```

--------------------------------

### FFIRenderLib.audioStart

Source: https://opentui.com/docs/api/core/

Starts the audio engine. Returns a status code.

```APIDOC
## FFIRenderLib.audioStart

### Description
Starts the audio engine. Returns a status code.

### Method
FFIRenderLib.audioStart

### Parameters
- **engine** (AudioEngineHandle) - Required - The audio engine handle.
- **options** (AudioStartOptions | null) - Optional - Start options.

### Returns
- **number** - Status code.
```

--------------------------------

### NativeSession.startKittyFileProbe()

Source: https://opentui.com/docs/api/core/

Starts a Kitty file probe. Returns void.

```APIDOC
## NativeSession.startKittyFileProbe()

### Description
Starts a Kitty file probe.

### Method
startKittyFileProbe

### Returns
- **void**

### Availability
0.6.0
```

--------------------------------

### AudioSetupOptions

Source: https://opentui.com/docs/api/core/

Configuration options for setting up the audio system.

```APIDOC
## AudioSetupOptions

### Properties
- **autoStart** (boolean) - Optional - Whether to start audio automatically.
- **playbackChannels** (number) - Optional - Number of playback channels.
- **sampleRate** (number) - Optional - Sample rate in Hz.
- **startOptions** (AudioStartOptions) - Optional - Options for starting audio.
```

--------------------------------

### Create panel with detail and next children

Source: https://opentui.com/docs/core-concepts/renderables/

Sets up a BoxRenderable panel with a detail child and a next child, then adds both to the panel and the panel to the renderer root. This is the starting state for the hide/detach example.

```javascript
const panel = new BoxRenderable(renderer, {
  width: 12,
  height: 4,
  border: true,
  borderColor: foreground,
})
const detail = new BoxRenderable(renderer, { height: 1, backgroundColor: fill })
detail.add(new TextRenderable(renderer, { content: "Detail", fg: foreground }))
const next = new TextRenderable(renderer, { content: "Next", fg: foreground })
panel.add(detail)
panel.add(next)
renderer.root.add(panel)
```

--------------------------------

### ScrollBox list after scrollTo(5)

Source: https://opentui.com/docs/components/scrollbox/

Example output showing the scrollbox list after calling scrollTo(5). The offset is 5 out of 7, and the visible items start from line 06.

```text
offset: 5 / 7                   ┌──────────────────────────────┐│06  src/input.ts              ││07  src/scroll.ts             ││08  src/render.ts             ││09  src/state.ts             ▀││10  src/config.ts             │└──────────────────────────────┘
```

--------------------------------

### sessionStartKittyFileProbe

Source: https://opentui.com/docs/api/core/

Starts a Kitty file probe for a session.

```APIDOC
## sessionStartKittyFileProbe

### Description
Starts a Kitty file probe for a session.

### Method
sessionStartKittyFileProbe

### Parameters
- **context** (NativeContextHandle) - Required - The native context handle.
- **session** (SessionHandle) - Required - The session handle.

### Returns
void
```

--------------------------------

### Basic setup with KeymapProvider and useBindings

Source: https://opentui.com/docs/keymap/react/

Sets up a React app with an OpenTUI keymap using KeymapProvider and registers a layer with useBindings. The default OpenTUI factory installs the parser and standard field addons; the provider does not add features or own renderer cleanup.

```jsx
/** @jsxImportSource @opentui/react */

import { createCliRenderer } from "@opentui/core"
import { createDefaultOpenTuiKeymap } from "@opentui/keymap/opentui"
import { KeymapProvider, useBindings } from "@opentui/keymap/react"
import { createRoot } from "@opentui/react"

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

function App() {
  useBindings(() => ({
    commands: [
      {
        name: "app.quit",
        run() {
          renderer.destroy()
        },
      },
    ],
    bindings: [{ key: "q", cmd: "app.quit" }],
  }))

  return <text>Press q to quit</text>
}

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

--------------------------------

### Audio.create(options?: AudioSetupOptions): Audio

Source: https://opentui.com/docs/api/core/

Static factory method to create an Audio instance. This is the entry point for audio functionality.

```APIDOC
## Audio.create(options?: AudioSetupOptions): Audio

### Description
Static factory method to create an Audio instance. This is the entry point for audio functionality.

### Method
create

### Parameters
- **options** (AudioSetupOptions) - Optional - Setup options for the audio system.

### Returns
- **Audio** - The created Audio instance.
```

--------------------------------

### Rotating cube example using ThreeRenderable

Source: https://opentui.com/docs/reference/three/

Shows a complete rotating-cube setup using the THREE namespace re-export. Requires @opentui/core and @opentui/three. Creates a CLI renderer at 60 FPS, adds a cube with lighting and camera, and rotates it via setFrameCallback.

```typescript
import { RGBA, createCliRenderer } from "@opentui/core"
import { THREE, ThreeRenderable } from "@opentui/three"

const renderer = await createCliRenderer({ targetFps: 60 })
renderer.start()

const scene = new THREE.Scene()
scene.add(new THREE.AmbientLight(new THREE.Color(0.35, 0.35, 0.35), 1))

const light = new THREE.DirectionalLight(new THREE.Color(1, 0.95, 0.9), 1.2)
light.position.set(2.5, 2, 3)
scene.add(light)

const cube = new THREE.Mesh(
  new THREE.BoxGeometry(1, 1, 1),
  new THREE.MeshPhongMaterial({ color: new THREE.Color(0.25, 0.8, 1) }),
)
scene.add(cube)

const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100)
camera.position.set(0, 0, 3)

const view = new ThreeRenderable(renderer, {
  width: "100%",
  height: "100%",
  scene,
  camera,
  renderer: {
    focalLength: 8,
    alpha: true,
    backgroundColor: RGBA.fromValues(0, 0, 0, 0),
  },
})

renderer.root.add(view)
renderer.setFrameCallback(async (deltaMs) => {
  cube.rotation.x += 0.6 * (deltaMs / 1000)
  cube.rotation.y += 0.4 * (deltaMs / 1000)
})
```

--------------------------------

### React handoff with @opentui/react and @opentui/ssh

Source: https://opentui.com/docs/reference/ssh/

Install the React binding and pass the existing session renderer to createRoot. Create one React root per session and unmount the app-owned React tree in onClose; the SSH package independently owns and destroys the CliRenderer.

```tsx
import { createRoot } from "@opentui/react"
import { createServer } from "@opentui/ssh"

const App = ({ name }: { name: string }) => <text>Hello, {name}!</text>

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

--------------------------------

### Audio.create(options?)

Source: https://opentui.com/docs/application-apis/audio-capture/

Creates an Audio instance. The options object can include `autoStart` to control whether playback starts automatically.

```APIDOC
## Audio.create(options?)

### Description
Creates an Audio instance. The options object can include `autoStart` to control whether playback starts automatically.

### Parameters
#### Options (optional)
- **autoStart** (boolean) - Optional - If false, playback does not start automatically.

### Usage
```typescript
const audio = Audio.create({ autoStart: false })
```
```

--------------------------------

### Configure exitSignals for createCliRenderer

Source: https://opentui.com/docs/core-concepts/lifecycle/

Replace the default signal handlers by setting `exitSignals` on `createCliRenderer`. Use an empty list when the application or a server owns process shutdown. The built-in handlers call `renderer.destroy()` and cannot await asynchronous cleanup; disable them and install application handlers when shutdown must await those resources.

```javascript
const renderer = await createCliRenderer({
  exitSignals: ["SIGINT", "SIGTERM"],
})

const managedRenderer = await createCliRenderer({
  exitOnCtrlC: false,
  exitSignals: [],
})
```

--------------------------------

### Animate a renderable with createTimeline

Source: https://opentui.com/docs/application-apis/animation/

Creates a registered timeline for a renderer, adds a BoxRenderable, and animates its left property over 600ms with an outQuad ease. The engine calls renderer.requestLive() and renderer.dropLive() as registered timelines start and stop; do not call requestLive() for a registered timeline. The example awaits completion, then pauses, unregisters, and destroys the renderer.

```typescript
import { BoxRenderable, createCliRenderer, createTimeline, getTimelineEngine } from "@opentui/core"

const renderer = await createCliRenderer()
const engine = getTimelineEngine(renderer)
const root = renderer.root

const box = new BoxRenderable(renderer, {
  id: "moving-box",
  position: "absolute",
  left: 0,
  top: 1,
  width: 8,
  height: 3,
  backgroundColor: "blue",
})
root.add(box)

let finish!: () => void
const finished = new Promise<void>((resolve) => {
  finish = resolve
})

const timeline = createTimeline(
  {
    duration: 600,
    autoplay: false,
    onComplete: finish,
  },
  renderer,
)

timeline.add(box, {
  left: 30,
  duration: 600,
  ease: "outQuad",
})

timeline.play()

try {
  await finished
} finally {
  timeline.pause()
  engine.unregister(timeline)
  renderer.destroy()
  await renderer.closed
}
```

--------------------------------

### createClipboard({ host, terminal })

Source: https://opentui.com/docs/core-concepts/lifecycle/

Adopts the host service and calls `host.dispose()` from its own `dispose()` method.

```APIDOC
## createClipboard({ host, terminal })

### Description
Adopts the host service and calls `host.dispose()` from its own `dispose()` method.

### Method
Function

### Signature
`createClipboard({ host, terminal })`

### Parameters
- **host** (Host) - Required - The host service to adopt.
- **terminal** (Terminal) - Required - The terminal instance.

### Returns
- **clipboard** (Clipboard) - The clipboard service.

### Usage Example
```js
const clipboard = createClipboard({ host, terminal })
```
```

--------------------------------

### registerModeField addon example

Source: https://opentui.com/docs/keymap/custom-addons/

Shows the canonical shape of a custom addon: a function that accepts a Keymap, registers behavior through public methods, and returns a disposer. It registers a binding field 'mode' that requires 'app.mode' and sets it, and intercepts the 'key' event to reset 'app.mode' to 'normal' on Escape. The disposer removes both registrations in reverse setup order.

```typescript
import type { Keymap, KeymapEvent } from "@opentui/keymap"

export function registerModeField<TTarget extends object, TEvent extends KeymapEvent>(
  keymap: Keymap<TTarget, TEvent>,
): () => void {
  const offField = keymap.registerBindingFields({
    mode(value, ctx) {
      ctx.require("app.mode", value)
      ctx.attr("mode", value)
    },
  })

  const offIntercept = keymap.intercept("key", ({ event, setData }) => {
    if (event.name === "escape") {
      setData("app.mode", "normal")
    }
  })

  return () => {
    offIntercept()
    offField()
  }
}

```

--------------------------------

### Basic renderer cleanup with renderer.destroy()

Source: https://opentui.com/docs/core-concepts/lifecycle/

Call renderer.destroy() in a finally block on normal shutdown and on application failure. createCliRenderer() destroys a constructed renderer if asynchronous terminal setup fails; after it resolves, your code owns the renderer. If construction throws, no renderer handle is returned and no public rollback handle exists, so validate configuration before creation.

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

const renderer = await createCliRenderer()

try {
  renderer.root.add(new TextRenderable(renderer, { content: "Ready" }))
  await renderer.idle()
} finally {
  renderer.destroy()
}
```

--------------------------------

### Audio.isStarted(): boolean

Source: https://opentui.com/docs/api/core/

Checks if the audio system is started.

```APIDOC
## Audio.isStarted(): boolean

### Description
Checks if the audio system is started.

### Method
isStarted

### Parameters
None

### Returns
- **boolean** - True if the audio system is started.
```

--------------------------------

### Start React DevTools

Source: https://opentui.com/docs/bindings/react/

Launch the React DevTools server with npx.

```bash
npx react-devtools@7
```

--------------------------------

### Run C acceptance test with zig build test-abi

Source: https://opentui.com/docs/native/c/

Run from the native workspace to test the host's shared and static libraries. Use --summary all to show the build summary.

```bash
zig build test-abi --summary all
```
Tokens:
Raw