FrankenTUI (ftui)

███████╗██████╗  █████╗ ███╗   ██╗██╗  ██╗███████╗███╗   ██╗████████╗██╗   ██╗██╗
██╔════╝██╔══██╗██╔══██╗████╗  ██║██║ ██╔╝██╔════╝████╗  ██║╚══██╔══╝██║   ██║██║
█████╗  ██████╔╝███████║██╔██╗ ██║█████╔╝ █████╗  ██╔██╗ ██║   ██║   ██║   ██║██║
██╔══╝  ██╔══██╗██╔══██║██║╚██╗██║██╔═██╗ ██╔══╝  ██║╚██╗██║   ██║   ██║   ██║██║
██║     ██║  ██║██║  ██║██║ ╚████║██║  ██╗███████╗██║ ╚████║   ██║   ╚██████╔╝██║
╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝   ╚═╝    ╚═════╝ ╚═╝

High‑performance terminal UI kernel -- 850K+ lines of Rust across 20 crates, 80+ widget/stateful-widget implementations, 46 interactive demo screens, a Bayesian intelligence layer, resizable pane workspaces, and in-tree web/WASM backends -- focused on correctness, determinism, and clean architecture.

Quick Run (from source)

The primary way to see what the system can do is the demo showcase: cargo run -p ftui-demo-showcase (not the harness).

# Download source with curl (no installer yet)
curl -fsSL https://codeload.github.com/Dicklesworthstone/frankentui/tar.gz/main | tar -xz
cd frankentui-main

# Run the demo showcase (primary way to see what FrankenTUI can do)
cargo run -p ftui-demo-showcase

Or clone with git:

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

TL;DR

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.

The Solution: FrankenTUI is a kernel‑level TUI foundation with a disciplined runtime, diff‑based renderer, and inline‑mode support that preserves scrollback while keeping UI chrome stable.

Why Use FrankenTUI?

Getting Started (Library Consumers)

If you want to embed FrankenTUI in your own Rust app (not just run the demo), start here: docs/getting-started.md.

For web embedding into frankentui_website (Next.js + bun), see the Embedding In frankentui_website section in docs/getting-started.md. It includes:

• in-tree build/check guidance for ftui-web and ftui-showcase-wasm,
• a clear note that FrankenTermWeb is currently adjacent/out-of-tree from this checkout,
• runtime initialization guidance for FrankenTermWeb once that bundle is available,
• and explicit no-xterm.js guidance.

Quick Example

# Demo showcase (primary)
cargo run -p ftui-demo-showcase

# Pick a specific demo view
FTUI_HARNESS_VIEW=dashboard cargo run -p ftui-demo-showcase
FTUI_HARNESS_VIEW=visual_effects cargo run -p ftui-demo-showcase

Demo Showcase Gallery (46 Screens)

The demo showcase (cargo run -p ftui-demo-showcase) ships 46 interactive screens, each demonstrating a different subsystem:

Each screen is also a snapshot test target. BLESS=1 cargo test -p ftui-demo-showcase updates baselines.

Use Cases

• Inline UI for CLI tools where logs must keep scrolling.
• Full-screen dashboards that must never flicker.
• Deterministic rendering harnesses for terminal regressions.
• Libraries that want a strict “kernel” but their own widget layer.

Non-Goals

• Not a full batteries‑included app framework (by design).
• Not a drop‑in replacement for existing widget libraries.
• Not a “best effort” renderer; correctness beats convenience.

Minimal API Example

use ftui_core::event::Event;
use ftui_core::geometry::Rect;
use ftui_render::frame::Frame;
use ftui_runtime::{App, Cmd, Model, ScreenMode};
use ftui_widgets::paragraph::Paragraph;

struct TickApp {
    ticks: u64,
}

#[derive(Debug, Clone)]
enum Msg {
    Tick,
    Quit,
}

impl From<Event> for Msg {
    fn from(e: Event) -> Self {
        match e {
            Event::Key(k) if k.is_char('q') => Msg::Quit,
            _ => Msg::Tick,
        }
    }
}

impl Model for TickApp {
    type Message = Msg;

    fn update(&mut self, msg: Msg) -> Cmd<Msg> {
        match msg {
            Msg::Tick => {
                self.ticks += 1;
                Cmd::none()
            }
            Msg::Quit => Cmd::quit(),
        }
    }

    fn view(&self, frame: &mut Frame) {
        let text = format!("Ticks: {}  (press 'q' to quit)", self.ticks);
        let area = Rect::new(0, 0, frame.width(), 1);
        Paragraph::new(text).render(area, frame);
    }
}

fn main() -> std::io::Result<()> {
    App::new(TickApp { ticks: 0 })
        .screen_mode(ScreenMode::Inline { ui_height: 1 })
        .run()
}

Design Philosophy

1. Correctness over cleverness. Predictable terminal state is non-negotiable.
2. Deterministic output. Buffer diffs and explicit presentation over ad-hoc writes.
3. Inline first. Preserve scrollback while keeping chrome stable.
4. Layered architecture. Core, render, runtime, widgets; no cyclic dependencies.
5. Zero-surprise teardown. RAII cleanup, even when apps crash.

Workspace Overview (20 Crates)

Core Architecture

Backend & Platform

Testing & Verification

Supporting

How FrankenTUI Compares

When to use FrankenTUI: - You want inline + scrollback without flicker. - You care about deterministic rendering and teardown guarantees. - You need resizable pane workspaces with drag, dock, and undo. - You want a single Rust codebase targeting both terminal and web. - You prefer a kernel you can build your own UI framework on top of.

When FrankenTUI might not be ideal: - You need a stable public API today (FrankenTUI is evolving fast). - You want a fully opinionated application framework rather than a kernel.

Installation

Quick Install (Source Tarball)

curl -fsSL https://codeload.github.com/Dicklesworthstone/frankentui/tar.gz/main | tar -xz
cd frankentui-main
cargo build --release

Git Clone

git clone https://github.com/Dicklesworthstone/frankentui.git
cd frankentui
cargo build --release

Use as a Workspace Dependency

# Cargo.toml
[dependencies]
ftui = { path = "../frankentui/crates/ftui" }

Crates.io (Published So Far)

Currently available on crates.io: - ftui-core - ftui-layout - ftui-i18n

The remaining crates are in the publish queue (render/runtime/widgets/etc.). Until those land, prefer workspace path dependencies for the full stack.

Quick Start

1. Install Rust nightly (required by rust-toolchain.toml).
2. Clone the repo and build: bash git clone https://github.com/Dicklesworthstone/frankentui.git cd frankentui cargo build
3. Run the demo showcase (primary way to see the system): bash cargo run -p ftui-demo-showcase

Telemetry (Optional)

Telemetry is opt‑in. Enable the telemetry feature on ftui-runtime and set OTEL env vars (for example, OTEL_EXPORTER_OTLP_ENDPOINT) to export spans.

When the feature is off, telemetry code and dependencies are excluded. When the feature is on but env vars are unset, overhead is a single startup check.

See docs/telemetry.md for integration patterns and trace‑parent attachment.

Feature Flags