Workspace Layout
FrankenTUI is organized as a Cargo workspace of 20 crates. Each crate owns one well-scoped concern — terminal I/O, layout, rendering, text, widgets, and so on — and depends only on crates below it in the layer stack. There are no cyclic dependencies.
This page is a directory map plus a per-crate status table. If you want to know where to put a change, or which crate to import, or what’s currently Reserved vs Implemented, this is the reference page.
Two bundles — frankenterm-core and frankenterm-web — appear in some
specs and integration docs but are not vendored in this workspace. They
are adjacent projects. The in-tree web surface is ftui-web plus the
ftui-showcase-wasm target.
Directory tree
- Cargo.toml
- rust-toolchain.toml
Per-crate status
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 | Implemented |
ftui-widgets | 80+ direct Widget / StatefulWidget implementations | 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, DPR/zoom handling | Implemented |
ftui-showcase-wasm | WASM build of the demo showcase | Implemented |
Testing & verification
| Crate | Purpose | Status |
|---|---|---|
ftui-harness | Shadow-run comparison, benchmark gate, rollout scorecard, determinism fixtures | Implemented |
ftui-pty | PTY-based test utilities (integrates with external frankenterm-core) | Implemented |
ftui-demo-showcase | 46 interactive demo screens + snapshot tests | Implemented |
doctor_frankentui | Integrated TUI capture, seeding, suite reporting, coverage gating | Implemented |
Supporting
| Crate | Purpose | Status |
|---|---|---|
ftui-a11y | Accessibility tree and node structures | Implemented |
ftui-i18n | Internationalization support | Implemented |
ftui-simd | SIMD acceleration | Reserved |
ftui-simd is Reserved. The crate exists as a workspace member but
its public API is not yet settled. Treat any usage as experimental until
it is marked Implemented.
Adjacent crates — NOT in this workspace
The following crates appear in some FrankenTerm-related specs and integration docs, but are not vendored in this workspace:
| Crate | Status in this workspace | Where it actually lives |
|---|---|---|
frankenterm-core | Not vendored | External dependency (used by ftui-pty via an external crate reference) |
frankenterm-web | Not vendored | Adjacent project — the browser-facing FrankenTermWeb bundle |
Treat frankenterm-core and frankenterm-web as adjacent / external.
The in-tree browser surface is ftui-web + ftui-showcase-wasm. If you
see docs referring to crates/frankenterm-core in this repo, those
references are historical — the code does not live here.
Publishing status
| Crate | crates.io | Version policy |
|---|---|---|
ftui-core | Published | Tracking workspace |
ftui-layout | Published | Tracking workspace |
ftui-i18n | Published | Tracking workspace |
| All other 17 crates | In publish queue | Pending |
Until the remaining crates reach crates.io, prefer workspace path dependencies for the full stack. See project setup for Cargo.toml patterns.
Release profile
The workspace release build optimizes for size:
# Cargo.toml (workspace root)
[profile.release]
opt-level = "z" # Optimize for size
lto = true # Link-time optimization
codegen-units = 1 # Better cross-module inlining
panic = "abort" # Smaller binary, no unwinding overhead
strip = true # Remove debug symbols
# Exception: the VFX rasterizer benefits from SIMD, loop unrolling,
# and aggressive inlining far more than from binary size.
[profile.release.package.ftui-extras]
opt-level = 3Do not change opt-level = 3 for ftui-extras. The VFX rasterizer
inner loops are written assuming autovectorization and aggressive
inlining; opt-level = "z" loses roughly an order of magnitude on
per-frame cost. See design decisions.
Key files per crate
This is a quick “where is X implemented” map for the hottest files:
| Crate | Key file | What’s in it |
|---|---|---|
doctor_frankentui | src/doctor.rs | Verification harness orchestration |
doctor_frankentui | src/intent_inference.rs | Intent inference engine |
doctor_frankentui | src/semantic_contract.rs | Semantic contracts and assertions |
ftui-a11y | src/node.rs | Accessibility node types, roles, states |
ftui-a11y | src/tree.rs | Accessibility tree builder + diff |
ftui-core | src/terminal_session.rs | RAII terminal lifecycle |
ftui-render | src/buffer.rs | 2D cell buffer with scissor stacks |
ftui-render | src/cell.rs | 16-byte cache-optimized Cell |
ftui-render | src/diff.rs | Efficient buffer diff computation |
ftui-render | src/presenter.rs | State-tracked ANSI emitter |
ftui-runtime | src/program.rs | Main event loop (13K+ lines) |
ftui-runtime | src/terminal_writer.rs | One-writer rule enforcement |
ftui-layout | src/pane.rs | Pane workspace system (9K+ lines) |
ftui-layout | src/egraph.rs | E-graph layout optimizer |
ftui-widgets | src/lib.rs | Widget traits + core library |
ftui-demo-showcase | src/app.rs | Demo application model |
Pitfalls
Don’t add a new top-level crate unless it can’t reasonably live in an existing one. The bar is incredibly high. Look at the 20 existing crates and find the right home first — see project philosophy and the “No File Proliferation” rule.
Don’t re-introduce references to crates/frankenterm-core or
crates/frankenterm-web in this workspace. They are not here. If you
see such a reference in a spec file, treat it as a doc bug.