58 lines
3.9 KiB
Markdown
58 lines
3.9 KiB
Markdown
# `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`**.
|