What is FrankenTUI?

FrankenTUI is a kernel-level terminal UI framework for Rust — roughly 850,000 lines of code across 20 workspace crates, 80+ direct widget implementations, 46 interactive demo screens, an in-tree web/WASM backend, and a Bayesian intelligence layer that replaces ad-hoc heuristics with principled statistics.

This page is an orientation piece for people deciding whether FrankenTUI is worth their time. If you’re already sold and want to run something, jump to the quick run. If you want to compare it to Ratatui or raw crossterm, see the comparison page.

It is not a drop-in replacement for Ratatui or a finished application framework. It is a disciplined kernel plus a broad widget library, optimized for correctness, determinism, and a clean separation of concerns across the terminal I/O, runtime, rendering, and widget layers.

The problem

Most TUI stacks make it easy to draw widgets, but hard to build correct, flicker-free, inline UIs with strict terminal cleanup and deterministic rendering. Typical failure modes:

• A crash leaves the terminal in raw mode — the user has to reset.
• A window resize during a drag glitches the screen because resize events flood.
• Inline UIs stomp on scrollback, or scrollback stomps on the UI.
• Flicker from partial frame writes — the terminal paints an inconsistent state.
• Ad-hoc threshold tuning that works on the author’s laptop and nowhere else.

These failure modes are not inherent to terminal UIs; they are artifacts of treating terminal I/O as a write-only side channel instead of a stateful protocol with a lifecycle.

The solution

FrankenTUI is a kernel with three core commitments:

1. Deterministic output. The rendering pipeline is Frame → Buffer → BufferDiff → Presenter → ANSI with no hidden I/O. Given the same model state and viewport size, the byte stream emitted to stdout is bit-for-bit identical.
2. RAII terminal lifecycle. TerminalSession owns raw mode, alt-screen, and cursor state. On any drop path — including panic — the terminal is restored to the shape it was in before the program ran.
3. Inline-mode first. Instead of ripping the scrollback away from the user, inline mode keeps a fixed UI region stable while log output scrolls naturally above it. Three strategies (scroll region, overlay redraw, and a hybrid) are selected automatically based on terminal capability.

Everything else — the 80+ widgets, the pane workspace system, the web/WASM backend, the Bayesian intelligence layer — is built on top of those three commitments.

What you get

• A disciplined Elm/Bubbletea runtime in Rust: init, update, view, subscriptions.
• A cache-optimized 16-byte Cell with four cells per 64-byte line and SIMD-friendly equality comparison.
• BufferDiff with dirty-row tracking, dirty-span intervals, and a summed-area table for tile-skip scans on large viewports.
• A state-tracked Presenter that picks between cursor positioning strategies (CUP vs CHA) per row based on a byte-level cost model.
• The ftui-layout pane workspace system (9,000+ lines) with drag-to-resize, magnetic docking, inertial throw, and a replayable operation timeline.
• An in-tree web/WASM backend (ftui-web, ftui-showcase-wasm) that renders the same Rust core in the browser with pointer/touch parity.
• An evidence-emitting intelligence layer. Every threshold has a principled statistical model behind it — Bayesian online change-point detection (BOCPD) for resize regimes, conformal prediction (distribution-free risk bounds) for frame-budget gating, value-of-information (VOI) sampling for expensive measurements, and e-processes (anytime-valid tests) for continuous monitoring. Each decision is logged to a JSONL evidence sink so you can jq your way back to why the runtime made a call. See intelligence layer.

Status

FrankenTUI is work in progress. APIs evolve quickly. The table below summarizes the headline status:

See the workspace layout for a per-crate status table and the design decisions page for the non-negotiable invariants.

Should you use this?

Use FrankenTUI if:

• You want inline-mode UI that coexists with log output and scrollback.
• You need deterministic rendering for snapshot testing or replay debugging.
• You want resizable pane workspaces with drag, dock, and undo.
• You want a single Rust codebase that targets both terminal and web.
• You are comfortable working off a workspace path dependency while APIs settle.

Avoid FrankenTUI if:

• You need a stable public API today — come back after v1.
• You want a fully opinionated application framework rather than a kernel.
• You need official Windows support — it is tracked but deferred.

Pitfalls

Where next