FrankenTUI (ftui)

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

High‑performance terminal UI kernel -- 850K+ lines of Rust across 20 crates, 106 widget implementations, 46 interactive demo screens, a Bayesian intelligence layer, resizable pane workspaces, and a web/WASM backend -- 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?

| Feature | What It Does | Example | |---------|--------------|---------| | Inline mode | Stable UI at top/bottom while logs scroll above | ScreenMode::Inline { ui_height: 10 } in the runtime | | Deterministic rendering | Buffer → Diff → Presenter → ANSI, no hidden I/O | BufferDiff::compute(&prev, &next) | | One‑writer rule | Serializes output for correctness | TerminalWriter owns all stdout writes | | RAII cleanup | Terminal state restored even on panic | TerminalSession in ftui-core | | Composable crates | Layout, text, style, runtime, widgets | Add only what you need | | 106 widgets | Block, Paragraph, Table, Input, Tree, Modal, Command Palette, etc. | 50 widget source files across ftui-widgets | | Pane workspaces | Drag‑to‑resize, docking, magnetic snap, inertial throw, undo/redo | PaneTree + PaneDragResizeMachine in ftui-layout | | Web/WASM backend | Same Rust core renders to browser canvas | ftui-web + frankenterm-web crates | | Bayesian intelligence | Statistical diff strategy, resize coalescing, capability detection | BOCPD, VOI, conformal prediction, e‑processes | | Shadow‑run validation | Prove rendering determinism across runtime migrations | ShadowRun::compare() in ftui-harness | | 46 demo screens | Dashboard, visual effects, widget gallery, layout lab, and more | cargo run -p ftui-demo-showcase |

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:

exact build commands for ftui-web and frankenterm-web,
expected wasm/js output locations in the website repo,
runtime initialization using FrankenTermWeb,
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:

| Category | Screens | What They Show | |----------|---------|----------------| | Overview | dashboard, widget_gallery, advanced_features | Full-system demos with animated panels, sparklines, markdown streaming | | Layout | layout_lab, layout_inspector, intrinsic_sizing, responsive_demo | Flex/Grid solvers, pane workspaces, constraint visualization | | Text | shakespeare, markdown_rich_text, markdown_live_editor, advanced_text_editor | Rope editor, syntax highlighting, streaming markdown | | Data | table_theme_gallery, data_viz, virtualized_search, log_search | Themed tables, charts, Fenwick-backed virtualization | | Input | forms_input, form_validation, command_palette_lab, mouse_playground | Bayesian fuzzy search, gesture recognition, focus management | | Visual FX | visual_effects, theme_studio, mermaid_showcase, mermaid_mega_showcase | Gray-Scott reaction-diffusion, metaballs, Clifford attractors, fractal zooms | | System | terminal_capabilities, performance, performance_hud, determinism_lab | Capability probing, frame budgets, conformal risk gating | | Diagnostics | explainability_cockpit, voi_overlay, snapshot_player, accessibility_panel | Evidence ledgers, VOI sampling visualization, a11y tree | | Workflow | file_browser, kanban_board, async_tasks, notifications, drag_drop | File picker, task boards, notification toasts, drag handles | | Advanced | inline_mode_story, hyperlink_playground, i18n_demo, macro_recorder, quake | Inline scrollback, OSC 8 links, locale switching, event recording | | 3D / Code | 3d_data, code_explorer, widget_builder, action_timeline | 3D data views, AST browsing, widget composition, timeline aggregation |

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

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

Workspace Overview (20 Crates)

Core Architecture

| Crate | Purpose | Status | |------|---------|--------| | ftui | Public facade + prelude | Implemented | | ftui-core | Terminal lifecycle, events, capabilities, animation, input parsing, gestures | Implemented | | ftui-render | Buffer, diff, ANSI presenter, frame, grapheme pool, budget system | Implemented | | ftui-style | Style + theme system with CSS‑like cascading | Implemented | | ftui-text | Spans, segments, rope editor, cursor, BiDi, shaping, normalization | Implemented | | ftui-layout | Flex + Grid solvers, pane workspace system (9K+ lines), e‑graph optimizer | Implemented | | ftui-runtime | Elm/Bubbletea runtime, effect system, subscriptions, rollout policy, telemetry schema (13K+ line program.rs) | Implemented | | ftui-widgets | 106 widget implementations across 50 source files | Implemented | | ftui-extras | Feature‑gated add‑ons, VFX rasterizer (opt‑level=3) | Implemented |

Backend & Platform

| Crate | Purpose | Status | |------|---------|--------| | ftui-backend | Backend abstraction layer | Implemented | | ftui-tty | TTY terminal backend | Implemented | | ftui-web | Web/WASM adapter with pointer/touch parity | Implemented | | ftui-showcase-wasm | WASM build of the demo showcase | Implemented |

Testing & Verification

| Crate | Purpose | St

Frankentui

Install / Use

README