FrankenTUI

The FrankenTUI project maintains a comprehensive vision checklist tracking the implementation status of its core architectural goals. The status legend used is:

• WORKING: Feature is implemented and reachable in production.
• PARTIAL: Feature exists but is incomplete or has limitations.
• DEAD: Feature exists in code but is unreachable in production or unreferenced.
• OPT-IN: Feature is available but disabled by default.
• WRONG_API: Feature exists, but the public API or documentation shape is incorrect.
• NOT_STARTED: Feature has not been implemented.
• UNPROVEN: Feature implementation is not yet verified.
• UNREFERENCED: Code exists but is not used by the main application.

Key working features include deterministic buffer-to-ANSI rendering, the 'one-writer' rule for terminal output, RAII cleanup on panics, and a pane workspace system with drag/dock/snap capabilities. Some advanced features like BOCPD resize coalescing and Conformal frame-time gating are currently OPT-IN.

As of the September 2026 assessment, FrankenTUI is a published native terminal UI framework. While the core kernel and many features are functional, certain high-level visions and specific user journeys are still in development.

What is currently functional:

• Native kernel and facade startup.
• Inline log presentation.
• Substantial widget library.
• Subscriptions.
• Headless simulation and live pane interactions.
• Version 0.7.0 availability (native binaries, crates, and docs.rs pages).

Known limitations and incomplete features:

• Doctor Coverage: The doctor verification gate still has coverage deficits.
• Browser/Web: While Mac browser rendering works in specific paths, the complete browser/GPU/IME/mobile matrix is not yet fully proven. Linux SwiftShader may produce a blank viewport.
• Accessibility: The accessibility tree does not yet automatically reach an OS screen reader.
• Subprocess Streaming: The flagship interactive subprocess example is currently absent; the underlying streaming boundary is currently unbounded.
• Other incomplete areas: Full editor support, widget/focus management, RTL/formatting, and certain supported-host commitments.

To understand how data flows through the system or where to implement changes, follow the runtime pipeline from the backend to the terminal writer:

TerminalSession/backend $\rightarrow$ Event $\rightarrow$ Program/Model $\rightarrow$ Frame/Buffer $\rightarrow$ BufferDiff $\rightarrow$ Presenter $\rightarrow$ TerminalWriter.

High-signal entry points

• Terminal lifecycle (RAII, raw mode, cleanup): crates/ftui-core/src/terminal_session.rs (Native backend: crates/ftui-tty/src/lib.rs)
• Canonical events: crates/ftui-core/src/event.rs
• Runtime loop (Elm-style) & command execution: crates/ftui-runtime/src/program.rs
• Output coordination (screen modes, one-writer rule, diff selection, ANSI emission): crates/ftui-runtime/src/terminal_writer.rs
• Render kernel: crates/ftui-render/src/{cell.rs,buffer.rs,frame.rs,diff.rs,presenter.rs}

Crate Boundaries

• ftui: Public facade
• ftui-core: Input, capabilities, and lifecycle
• ftui-render: Render kernel
• ftui-runtime: Runtime
• ftui-widgets: Widgets
• ftui-backend: Traits for backends
• ftui-tty: Native (Unix-first) backend
• ftui-web: Web/WASM primitives
• ftui-harness / ftui-pty: Snapshot and PTY utilities
• ftui-demo-showcase: Reference app and snapshots

As of the 0.7.0 release (September 2026), FrankenTUI provides a set of verified features and experimental modules. Developers should note the following status of core architectural promises:

Working Features (Verified)

• Inline scrollback/stable chrome: Supported via terminal_writer/inline_mode and PTY suites.
• Deterministic buffer/diff/presentation: Verified via render kernel and harness property tests.
• Single Terminal Writer: Provided by TerminalWriter with sanitized log paths.
• Composable runnable facade: Default/slim registry consumers pass real PTY journeys.
• State persistence: Supported via registry/runtime load-save.
• Input macro record/replay: Integrated via input_macro.
• Headless simulator: Available via simulator/deterministic test corpus.
• Elm runtime/subscriptions: Includes task/tick/fs-watch helpers.
• No unsafe implementation: Follows a strict crate policy (with governance FFI exceptions).
• Hyperlinks: Supported via link registry and OSC 8 presenter.
• Modals: Supported via widget/focus stack.
• Rope text: Integrated with rope/editor.
• Animation: Supported via widget animation code and tests.
• Effect queue/backpressure: Supported via effects runtime.

Partial or Experimental Features (Use with caution)

• Accessibility/live regions: Runtime tree and ten widget implementations exist, but real Assistive Technology (AT) journeys are not yet demonstrated.
• i18n/RTL/formatting: Catalogs and plurals are present, but directionality and formatting are incomplete.
• Focus management: The manager is functional, but the accessibility connection is incomplete.
• Windows support: MSVC native binaries/builds pass, but the full interactive console/lifecycle matrix is still being verified.
• Advanced UI: Pane drag/dock/snap/throw, Table themes, and Stylesheets are currently in development or incomplete.

FrankenTUI (ftui) is a high-performance, minimal terminal UI kernel designed for building robust, flicker-free terminal applications. It is specifically optimized for 'agent-ergonomic' use cases, such as AI agent harnesses (e.g., Claude Code style), where streaming logs must coexist with a stable UI chrome without sacrificing native terminal scrollback.

The project follows a Three-Ring Architecture to ensure stability and rapid evolution:

1. Kernel (Sacred): The stable, minimal core containing primitives like Frame, Buffer, Cell, the diff engine, the ANSI presenter, and input parsing.
2. Widgets (Reusable): Components built on kernel primitives, such as Panels, Lists, Tables, and Inputs.
3. Extras (Feature-gated): Higher-level features like Markdown support, syntax highlighting, and SSH/PTY integration.

Key design goals include being inline-first (preserving native scrollback), flicker-free (using diffed, buffered output), and deterministic (rendering is a pure function of model state, terminal size, and theme).

The doctor_frankentui crate (located at crates/doctor_frankentui) is a Rust-based port of the legacy tui_inspector tool. It is designed to provide deterministic TUI capture workflows, profile-driven orchestration, and automated reporting. It replaces fragile shell scripts with typed configurations and metadata schemas, making it suitable for both local diagnostics and CI environments.

Key capabilities include:

• Profile-driven capture orchestration: Running specific TUI scenarios based on defined profiles.
• VHS tape generation: Creating .tape files from key-token sequences.
• JSON-RPC seeding: Optional live seeding of data via JSON-RPC.
• Suite execution: Running multiple profiles in sequence.
• Report generation: Producing both JSON and HTML reports.
• Doctor checks: Verifying environment dependencies and wiring.
• Deterministic artifacts: Generating consistent outputs including run_meta.json, run_summary.txt, logs, tapes, and media.