FrankenTUI: a Rust terminal UI kernel built around diff rendering and inline mode

The problem FrankenTUI targets: correct terminal output, not more widgets

The README states the problem directly: 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. That is a narrower claim than "a better widget library." It is about what happens between your application state and the bytes on the terminal.

Three failure modes sit behind that framing. Flicker, when a full repaint is emitted where a partial update would do. Scrollback loss, when a full-screen alternate buffer swallows the log lines a user wanted to keep. And leftover terminal state, when a program exits abnormally and leaves the cursor hidden, the alternate screen active, or raw mode enabled.

FrankenTUI is for Rust developers who already accept that they are writing a terminal application and want the runtime layer to enforce discipline. The README's non-goals are as informative as its goals: it is not a full batteries-included app framework, it is not a drop-in replacement for existing widget libraries, and it is not a best-effort renderer, because correctness beats convenience.

How the rendering pipeline works: Buffer, Diff, Presenter, ANSI

The README describes the pipeline as Buffer to Diff to Presenter to ANSI, with no hidden I/O. Each frame is composed into a buffer, compared against the previous buffer to produce a diff, passed to a presenter, and only then serialized to ANSI escape sequences.

The named entry point for the diff step is `BufferDiff::compute(&prev, &next)`. Because the diff is a value computed from two buffers rather than a side effect of drawing, the same inputs should produce the same escape output. That is what makes the determinism claims testable rather than aspirational.

Output serialization is governed by a one-writer rule: a `TerminalWriter` owns all stdout writes. This is the mechanism that prevents two subsystems from interleaving escape sequences and corrupting the display. If you have ever debugged a TUI where a background task printed to stdout mid-frame, this rule is the answer to that class of bug.

Cleanup is handled by RAII. `TerminalSession` in `ftui-core` restores terminal state even on panic, which is the practical difference between a crash that leaves your shell usable and one that does not. The README does not document rollback behaviour for a partially written frame, so treat mid-frame failure semantics as something to inspect in the source rather than something the documentation promises.

Inline mode: a fixed UI block while logs keep scrolling

Inline mode is the feature most likely to decide whether you want this project. The README describes it as a stable UI at the top or bottom while logs scroll above, configured through `ScreenMode::Inline { ui_height: 10 }` in the runtime.

The trade-off is explicit. Inline mode gives up the alternate screen, so you do not get a clean full-screen canvas that vanishes on exit. What you get instead is preserved scrollback plus stable chrome. For a long-running CLI that prints progress or log lines while showing a status panel, that is usually the right trade. For a full-screen editor or dashboard, it is the wrong one, and the README's own use-case list separates these: inline UI for CLI tools where logs must keep scrolling, full-screen dashboards that must never flicker.

The demo screen `inline_mode_story` exists specifically to show this behaviour, and the README notes that each demo screen is also a snapshot test target. That pairing is the interesting part: inline mode is not just demonstrated, it is pinned by snapshot baselines.

Installing FrankenTUI from source and running the demo application

There is no installer and no published binary. The README says to download the source, and the primary way to see what the system does is the demo application, which the README distinguishes from the harness. The curl path fetches the tarball and unpacks it:

curl -fsSL https://codeload.github.com/Dicklesworthstone/frankentui/tar.gz/main | tar -xz
cd frankentui-main
cargo run -p ftui-demo-showcase

Cloning with git is the equivalent route:

git clone https://github.com/Dicklesworthstone/frankentui.git
cd frankentui
cargo run -p ftui-demo-showcase

You should see the 46-screen demo application start. To open a specific view instead of the default, the README gives the `FTUI_HARNESS_VIEW` environment variable with view names:

FTUI_HARNESS_VIEW=dashboard cargo run -p ftui-demo-showcase
FTUI_HARNESS_VIEW=visual_effects cargo run -p ftui-demo-showcase

If you intend to embed the library rather than run the demo, the README points to `docs/getting-started.md` for library consumers. One caution from that document: the web embedding section notes that `FrankenTermWeb` is currently adjacent and out-of-tree from this checkout, so the WASM story is not a single-command experience yet.

The Makefile adds a step worth knowing about. Its `sync-refs` target runs `./scripts/pull_latest_reference_library_repos.sh`, and `build`, `check`, `test` and `clippy` all depend on it, so a plain `make build` pulls reference repositories before compiling. If you want a build that touches only this checkout, use `cargo` directly rather than the Makefile targets.

Where FrankenTUI is the wrong choice

The clearest limitation is stated by the project itself: it is not a drop-in replacement for existing widget libraries. If your codebase is already built on another Rust TUI library, adopting FrankenTUI means rewriting the rendering and runtime layers, not swapping a dependency. The 80+ widgets are an argument for starting fresh with it, not for migrating to it cheaply.

The second limitation is structural. The workspace has 20 members, and the README frames the value as composable crates: layout, text, style, runtime, widgets, add only what you need. That composability is real, but it also means the project does not hand you one obvious entry point. You have to decide which crates you need, and the README's own guidance separates demo running from library embedding because those are different starting paths.

Third, the release profile is tuned for size rather than speed: `opt-level = "z"`, `lto = true`, `codegen-units = 1` and `panic = "abort"`. The workspace also defines a separate `release-perf` profile with `opt-level = 3` and thin LTO. If you benchmark the default release build and find it slower than expected, the profile is the first thing to check rather than the renderer.

Finally, the licence is not determinable from the repository metadata, which reports NOASSERTION. The LICENSE file exists at the top level, but nothing in the README explains the terms. That is a verification task before adoption, not a detail to assume.

How FrankenTUI differs from ratatui and crossterm

The obvious comparison is ratatui for widgets and crossterm for terminal control, which is the combination most Rust TUI projects reach for. The difference in approach is where the strictness lives.

In that combination, the immediate-mode widget layer draws into a buffer and the backend writes it. Correctness properties such as "only one thing writes to stdout" and "terminal state is restored on panic" are conventions you maintain in your own code. FrankenTUI moves them into the kernel: `TerminalWriter` owns all stdout writes, `BufferDiff::compute(&prev, &next)` makes the diff an inspectable value, and `TerminalSession` ties restoration to a lifetime.

That is a heavier commitment. You are adopting a runtime and a screen-mode model, not just a widget set. The payoff the README claims is determinism you can validate: `ShadowRun::compare()` in `ftui-harness` is described as proving rendering determinism across runtime migrations, and the `determinism_lab` demo screen exists alongside it. If you do not need that property, the extra structure is cost without benefit, and a lighter widget library will get you to a working UI faster.

Maintenance, release cadence and licence questions

The repository is not archived, and the last push was on 2026-08-24, the same day as the v0.6.0 release. Before that, v0.5.0 landed on 2026-07-05 and v0.4.1 on 2026-06-13. The gaps are roughly seven weeks and three weeks, which is a steady cadence rather than a burst, and the workspace version in Cargo.toml is 0.8.0, ahead of the most recent tag. That gap between the manifest version and the released tag is worth noting if you pin by version.

Upgrade cost is shaped by the workspace layout. Because the project is 20 separate crates, a breaking change in `ftui-core` or `ftui-render` propagates to anything depending on them, but a change confined to `ftui-extras` or `ftui-widgets` does not force a rewrite of your runtime integration. Depending on individual crates rather than the umbrella `ftui` crate is the lever here.

The edition is 2024 and `rust-toolchain.toml` is present at the top level, so the toolchain is pinned by the repository. Check that pin against your own CI before you start.

On licence: the repository metadata reports NOASSERTION, which means the automated classifier could not determine terms. A LICENSE file is present at the top level. Read it, and read the licence fields of each crate you depend on, before shipping anything. This is a factual gap in the metadata, not a legal opinion.

Editorial conclusion

Adopt FrankenTUI if you are building a Rust CLI that must keep scrollback intact while a stable UI block sits at the top or bottom, or if you need a renderer whose output can be compared frame by frame. Do not adopt it if you want a batteries-included application framework or a drop-in replacement for an existing widget library; the README lists both as non-goals. Before committing, verify the licence text in the LICENSE file, since the repository metadata reports NOASSERTION, and confirm that the crates you depend on are the ones you actually need rather than the whole workspace.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes