Terminal UI, without the runtime tax.
A renderer-neutral terminal application runtime with React Ink compatibility.
tuil combines a renderer-neutral application runtime, React Ink compatibility, deterministic cell rendering, typed forms and routes, focus and hotkey management, cancellable operations, persistent workflows, plugins, themes, source-owned components, portable stories, and semantic testing. Applications share one set of runtime contracts across interactive terminals, redirected output, tests, documentation, and Storybook.
| Capability | What it provides |
|---|---|
| Application runtime | Explicit services, lifecycle, capabilities, typed events, and teardown |
| Terminal-native UX | Focus scopes, hotkey sequences, overlays, forms, routing, and responsive layouts |
| Deterministic output | Interactive, static, text, silent, and JSON modes from the same application |
| Portable stories | One catalog for live previews, Storybook, snapshots, and generated documentation |
| Semantic testing | Query roles and labels instead of brittle terminal coordinates |
| Source ownership | Install inspectable components and blocks through the registry CLI |
| Live composition | Observable plugin extensions and capability-normalized theme switching |
Install the framework, Ink adapter, renderer, and React:
npm install @mwillbanks/tuil @mwillbanks/tuil-ink ink react
Create a project with the self-hosted initializer:
npx @mwillbanks/tuil init
The initializer validates the destination before writing and can install registry components and bundled Agent Skills alongside the generated application.
@mwillbanks/tuil— application creation, runtime services, and the CLI@mwillbanks/tuil-ink— Ink rendering, input, semantics, and overlays@mwillbanks/tuil-form— typed forms, validation, and controlled fields@mwillbanks/tuil-router— typed routes, guards, history, and layouts@mwillbanks/tuil-operations— observable asynchronous work and cancellation@mwillbanks/tuil-workflow— persistent, resumable multi-step workflows@mwillbanks/tuil-plugin— dependency-aware plugin lifecycle@mwillbanks/tuil-theme— tokens, variants, utilities, and theme registries@mwillbanks/tuil-testing— portable stories and semantic assertions@mwillbanks/tuil-testing-ink— Ink-backed application test rendering@mwillbanks/tuil-story— browser, Storybook, snapshot, and docs adapters
The complete package map, architecture, component registry, examples, skills, and migration guidance live in the documentation.
Bun 1.3.14 or newer is required.
bun install --frozen-lockfile
bun run check
bun run docs
bun run check validates formatting and types, runs coverage-gated tests,
builds every publication artifact, and audits the project with Fallow. Run the
dependency security gate separately:
bun run security
See CONTRIBUTING.md for the complete workflow and pull request expectations. Usage questions and maintenance expectations are in SUPPORT.md; community participation is governed by the Code of Conduct.
Do not report vulnerabilities in a public issue. Follow SECURITY.md to submit a private GitHub Security Advisory.
MIT