# `ctx.tui` / `ctx.sdk` API

First-party guest TUI attached by **`bare-os-booter`** after `createKernelReplSession`. Framework semver is **`ctx.tui.version`** (independent of **`bareOsCtxApiVersion`**). Added on ctx API **1.56.0**. Disable with **`BARE_OS_TUI=0`**.

Narrative: [developer-guide ch.20](../../developer-guide/20-tui-and-sdk.md). Inspector: **`man tui`**.

## Session

| Member                                | Role                                                     |
| ------------------------------------- | -------------------------------------------------------- |
| `isTTY(opts?)`                        | False when `bareOsStdoutCaptured` or streams are not TTY |
| `size(opts?)`                         | `{ width, height }` from stdout / `COLUMNS` / `LINES`    |
| `run(model, opts?)`                   | TEA loop; owns Fish + alt-screen until quit              |
| `create(model, opts?)`                | `Program` with `.run()` / `.send()` / `.quit()`          |
| `send(msg)`                           | Enqueue on the active program                            |
| `acquire` / `release` / `withSession` | Refcounted Fish suspend + raw mode                       |
| `screen.enter` / `leave`              | Alt-screen, cursor, mouse, paste                         |

`run` / `create` options: `input`, `output`, `isTTY`, `width`, `height`, `fps` (0 = sync), `altScreen`, `mouse`, `bracketedPaste`, `theme`, `signal`, `allowDumb`, **`buffer: 'line' | 'cell'`**.

Stock TTY utilities **`dhttop`**, **`swarmmap`**, **`routeview`**, **`holepunch-view`**, **`swarmtop`**, **`chat`**, **`edit`**, **`nano`**, **`baretop`**, **`btop`**, **`irc`**, and **`summon`** call **`ctx.tui.run`** when this API is attached (`edit`/`nano`/`baretop`/`irc`/`summon` use **`buffer: 'cell'`**). **`agent`** setup uses **`ctx.tui.form`**. `BARE_OS_TUI=0` keeps the pre-SDK loops. **`irc`**: [irc-client.md](irc-client.md). **`summon`**: [summon.md](summon.md).

**`buffer: 'cell'`** paints a fixed-size cell grid and blits overlays without inserting lines (modals / dropdowns). Models may implement **`overlay(size)`** or **`overlays(size)`**. Program: **`setOverlay(id, spec)`** / **`clearOverlay(id)`**. Helpers: **`ctx.tui.buffer.create/fill/blit/plain`**.

## Style, theme, input

- **`style()`** — chainable Lip Gloss helper (`bold`, `foreground`, `padding`, `border`, `render`). Helpers: `style.width`, `height`, `truncate`, `stripAnsi`, `joinHorizontal`, `joinVertical`, `borders`, `position`.
- **`theme()`** — `{ name, noColor, depth, tokens }` from `BARE_OS_THEME` / `NO_COLOR` / `BARE_OS_COLOR_DEPTH`.
- **`key.matches(msg, ...chords)`**, **`key.binding({ keys, help })`**
- **`decode(bytes)`**, **`createDecoder()`** — keys, SGR mouse, bracketed paste

## Commands

`quit`, `tick(ms, fn)`, `every(ms, fn)`, `batch(...)`, `sequence(...)`, `suspend(fn)`.

## Widgets

`spinner`, `textinput`, `textarea`, `autocomplete`, `checkbox`, `radio`, `select`, `list`, `table`, `viewport`, `paginator`, `progress`, `help`, `focus`, `stopwatch`, `timer`, `filepicker` (VFS or `filepicker.mock(tree)`), `tabs`, `modal`, `dialog`, `tree`, `statusbar`, `split`, `toast`, `markdown`.

Each is `{ create(opts) }` except **`markdown.render(src)`**.

## One-shots and forms

- `confirm({ title, body, ok, cancel })` → `Promise<boolean>`
- `prompt({ label, placeholder, echoMode })` → `Promise<string|null>`
- `choose({ title, options })` → `Promise<unknown>`
- `form.create({ title, fields })` / `form.run(form)` / `form.text` / `textarea` / `number` / `select` / `radio` / `confirm`

Form keys: tab / shift-tab, enter advances (or submits on last text field), **ctrl+s** submits, **ctrl+c** cancels.

## `ctx.sdk`

`sdk.tui` is `ctx.tui`. Also: `tty`, `theme` (`apply`), `env`, `vfs`, `proc.read`, `ipc`, `app`.

## Not this API

`ctx.bare.bareTui*` drive bundles remain experimental host/Holepunch packages. Guest apps should use **`ctx.tui`**.