# FrankenTUI (ftui)
```
███████╗██████╗ █████╗ ███╗ ██╗██╗ ██╗███████╗███╗ ██╗████████╗██╗ ██╗██╗
██╔════╝██╔══██╗██╔══██╗████╗ ██║██║ ██╔╝██╔════╝████╗ ██║╚══██╔══╝██║ ██║██║
█████╗ ██████╔╝███████║██╔██╗ ██║█████╔╝ █████╗ ██╔██╗ ██║ ██║ ██║ ██║██║
██╔══╝ ██╔══██╗██╔══██║██║╚██╗██║██╔═██╗ ██╔══╝ ██║╚██╗██║ ██║ ██║ ██║██║
██║ ██║ ██║██║ ██║██║ ╚████║██║ ██╗███████╗██║ ╚████║ ██║ ╚██████╔╝██║
╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚═════╝ ╚═╝
```
<div align="center">
<img src="frankentui_illustration.webp" alt="FrankenTUI - Minimal, high-performance terminal UI kernel">
</div>
Minimal, high‑performance terminal UI kernel 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).
```bash
# 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:**
```bash
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 |
---
## Quick Example
```bash
# 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
```
---
## 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
```rust
use ftui_core::event::Event;
use ftui_core::geometry::Rect;
use ftui_render::frame::Frame;
use ftui_runtime::{Cmd, Model, Program};
use ftui_widgets::paragraph::Paragraph;
struct App {
ticks: u64,
}
#[derive(Debug, Clone)]
enum Msg {
Tick,
Quit,
}
impl From<Event> for Msg {
fn from(_: Event) -> Self {
Msg::Tick
}
}
impl Model for App {
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: {}", self.ticks);
let area = Rect::new(0, 0, frame.width(), 1);
Paragraph::new(text).render(area, frame);
}
}
fn main() -> std::io::Result<()> {
let mut program = Program::new(App { ticks: 0 })?;
program.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
| Crate | Purpose | Status |
|------|---------|--------|
| `ftui` | Public facade + prelude | Implemented |
| `ftui-core` | Terminal lifecycle, events, capabilities | Implemented |
| `ftui-render` | Buffer, diff, ANSI presenter | Implemented |
| `ftui-style` | Style + theme system | Implemented |
| `ftui-text` | Spans, segments, rope editor | Implemented |
| `ftui-layout` | Flex + Grid solvers | Implemented |
| `ftui-runtime` | Elm/Bubbletea runtime | Implemented |
| `ftui-widgets` | Core widget library | Implemented |
| `ftui-extras` | Feature‑gated add‑ons | Implemented |
| `ftui-harness` | Reference app + snapshots | Implemented |
| `ftui-pty` | PTY test utilities | Implemented |
| `ftui-simd` | Optional safe optimizations | Reserved |
---
## How FrankenTUI Compares
| Feature | FrankenTUI | Ratatui | tui-rs (legacy) | Raw crossterm |
|---------|------------|---------|-----------------|---------------|
| Inline mode w/ scrollback | ✅ First‑class | ⚠️ App‑specific | ⚠️ App‑specific | ❌ Manual |
| Deterministic buffer diff | ✅ Kernel‑level | ✅ | ✅ | ❌ |
| One‑writer rule | ✅ Enforced | ⚠️ App‑specific | ⚠️ App‑specific | ❌ |
| RAII teardown | ✅ TerminalSession | ⚠️ App‑specific | ⚠️ App‑specific | ❌ |
| Snapshot/time‑travel harness | ✅ Built‑in | ❌ | ❌ | ❌ |
**When to use FrankenTUI:**
- You want inline + scrollback without flicker.
- You care about deterministic rendering and teardown guarantees.
- You prefer a kernel you can build your own UI framework on top of.
**When FrankenTUI might not be ideal:**
- You need a huge widget ecosystem today (FrankenTUI is still early stage).
- You want a fully opinionated application framework rather than a kernel.
---
## Installation
### Quick Install (Source Tarball)
```bash
curl -fsSL https://codeload.github.com/Dicklesworthstone/frankentui/tar.gz/main | tar -xz
cd frankentui-main
cargo build --release
```
### Git Clone
```bash
git clone https://github.com/Dicklesworthstone/frankentui.git
cd frankentui
cargo build --release
```
### Use as a Workspace Dependency
```toml
# 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
| Crate | Feature | What It Enables |
|------|---------|------------------|
| `ftui-core` | `tracing` | Structured spans for terminal lifecycle |
| `ftui-core` | `tracing-json` | JSON output via tracing-subscriber |
| `ftui-render` | `tracing` | Performance spans for diff/presenter |
| `ftui-runtime` | `tracing` | Runtime loop instrumentation |
| `ftui-runtime` | `telemetry` | OpenTelemetry export (OTLP) |
Enable features per-crate in your `Cargo.toml` as needed.
---
## Evidence Logs (JSONL Diagnostics)
FrankenTUI can emit structured, deterministic evidence logs for diff strategy
decisions, resize coalescing, and budget alerts. The log sink is shared and
configured at the runtime level.
```rust
use ftui_runtime::{EvidenceSinkConfig, EvidenceSinkDestination, Program, ProgramConfig};
let config = ProgramConfig::default().with_evidence_sink(
EvidenceSinkConfig::enabled_file("evidence.jsonl")
.with_destination(EvidenceSinkDestination::file("evidence.jsonl"))
.with_flush_on_write(true),
);
let mut program = Program::with_config(model, config)?;
program.run()?;
```
Example event line:
```json
{"event":"diff_decision","run_id":"diff-4242","event_idx":12,"strategy":"DirtyRows","cost_full":1.230000,"cost_dirty":0.410000,"cost_redraw":0.000000,"posterior_mean":0.036000,"posterior_variance":0.000340,"alpha":3.500000,"beta":92.500000,"dirty_rows":4,"total_rows":40,"total_cells":3200,"span_count":2,"span_coverage_pct":6.250000,"max_span_len":12,"fallback_reason":"none","scan_cost_estimate":200,"bayesian_enabled":true,"dirty_rows_enabled":true}
```
---
## Commands
### Run the Demo Showcase (Primary)
```bash
cargo run -p ftui-demo-showcase
```
### Run Harness Examples (tests and reference behavior)
```bash
cargo run -p ftui-harness --example minimal
cargo run -p ftui-harness --example streaming
```
### Tests
```bash
cargo test
BLESS=1 cargo test -p ftui-harness # update snapshot baselines
```
### Deterministic E2E Runs
Use deterministic fixtures for stable hashes and reproducible logs:
```bash
# Full E2E suite with deterministic seeds/time
E2E_DETERMINISTIC=1 E2E_SEED=0 E2E_TIME_STEP_MS=100 ./scripts/e2e_test.sh
# Demo showcase E2E with an explicit seed
E2E_DETERMINISTIC=1 E2E_SEED=42 ./scripts/demo_showcase_e2e.sh
```
### Format + Lint
```bash
cargo fmt
cargo clippy --all-targets -- -D warnings
```
### E2E Scripts
```bash
./scripts/e2e_test.sh
./scripts/widget_api_e2e.sh
```
---
## Configuration
FrankenTUI is configuration‑light. The harness is configured via environment variables:
```bash
# .env (example)
FTUI_HARNESS_SCREEN_MODE=inline # inline | alt
FTUI_HARNESS_UI_HEIGHT=12 # rows reserved for UI
FTUI_HARNESS_VIEW=layout-grid # view selector
FTUI_HARNESS_ENABLE_MOUSE=true
FTUI_HARNESS_ENABLE_FOCUS=true
FTUI_HARNESS_LOG_LINES=25
FTUI_HARNESS_LOG_MARKUP=true
FTUI_HARNESS_LOG_FILE=/path/to/log.txt
FTUI_HARNESS_EXIT_AFTER_MS=0 # 0 disables auto-exit
```
Terminal capability detection uses standard environment variables (`TERM`, `COLORTERM`, `NO_COLOR`, `TMUX`, `ZELLIJ`, `KITTY_WINDOW_ID`).
---
## Architecture
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ INPUT LAYER │
├──────────────────────────────────────────────────────────────────────────────┤
│ TerminalSession (crossterm) │
│ └─ raw terminal events → Event (ftui-core) │
└──────────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ RUNTIME LOOP │
├──────────────────────────────────────────────────────────────────────────────┤
│ Program / Model (ftui-runtime) │
│ update(Event) → (Model', Cmd) │
│ Cmd → Effects │
│ Subscriptions → Event stream (tick / io / resize / ...) │
└──────────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ RENDER KERNEL │
├──────────────────────────────────────────────────────────────────────────────┤
│ view(Model) → Frame → Buffer → BufferDiff → Presenter → ANSI │
│ (cell grid) (minimal) (encode bytes) │
└──────────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ OUTPUT LAYER │
├──────────────────────────────────────────────────────────────────────────────┤
│ TerminalWriter │
│ inline mode (scrollback-friendly) | alt-screen mode (classic) │
└──────────────────────────────────────────────────────────────────────────────┘
```
---
## Frame Pipeline (Step-by-Step)
1. **Input** → `TerminalSession` reads `Event`.
2. **Model** → `update()` returns `Cmd` for side effects.
3. **View** → `view()` renders into `Frame`.
4. **Buffer** → `Frame` writes cells into a 2D `Buffer`.
5. **Diff** → `BufferDiff` computes minimal changes.
6. **Presenter** → emits ANSI with state tracking.
7. **Writer** → enforces one‑writer rule, flushes output.
This is the core loop that ensures determinism and flicker‑free output.
---
## "Alien Artifact" Quality Algorithms
FrankenTUI employs mathematically rigorous algorithms that go far beyond typical TUI implementations—what we call "alien artifact" quality engineering.
### Bayesian Fuzzy Scoring (Command Palette)
The command palette uses a **Bayesian evidence ledger** for match scoring, not simple string distance:
```
Score = P(relevant | evidence) computed via posterior odds:
P(relevant | evidence) / P(not_relevant | evidence)
= [P(relevant) / P(not_relevant)] × Π_i BF_i
where BF_i = Bayes Factor for evidence type i
= P(evidence_i | relevant) / P(evidence_i | not_relevant)
```
**Prior odds by match type:**
| Match Type | Prior Odds | P(relevant) | Intuition |
|------------|------------|-------------|-----------|
| Exact | 99:1 | 99% | Almost always what user wants |
| Prefix | 9:1 | 90% | Very likely relevant |
| Word-start | 4:1 | 80% | Probably relevant |
| Substring | 2:1 | 67% | Possibly relevant |
| Fuzzy | 1:3 | 25% | Needs additional evidence |
**Evidence factors that update posterior:**
- **Word boundary bonus** (BF ≈ 2.0): Match at start of word
- **Position bonus** (BF ∝ 1/position): Earlier matches stronger
- **Gap penalty** (BF < 1.0): Gaps between matched chars reduce confidence
- **Tag match bonus** (BF ≈ 3.0): Query matches command tags
- **Length factor** (BF ∝ 1/length): Shorter, more specific titles preferred
**Result:** Every search result includes an explainable evidence ledger showing exactly why it ranked where it did.
### Bayesian Hint Ranking (Keybinding Hints)
Keybinding hints are ranked by **expected utility minus display cost**, with a VOI exploration bonus and hysteresis for stability:
```
Utility posterior:
U_i ~ Beta(α_i, β_i)
E[U_i] = α_i / (α_i + β_i)
VOI_i = sqrt(Var(U_i))
Net value:
V_i = E[U_i] + w_voi × VOI_i - λ × C_i
Hysteresis:
swap only if V_i - V_j > ε
```
**Result:** the UI surfaces the most valuable shortcuts without flicker, while still exploring uncertain hints.
### Bayesian Diff Strategy Selection
The renderer adaptively chooses between diff strategies using a **Beta posterior over change rates**:
```
Change-rate model:
p ~ Beta(α, β)
Prior: α₀ = 1, β₀ = 19 → E[p] = 5% (expect sparse changes)
Per-frame update:
α ← α × decay + N_changed
β ← β × decay + (N_scanned - N_changed)
where decay = 0.95 (exponential forgetting for non-stationary workloads)
```
**Strategy cost model:**
```
Cost = c_scan × cells_scanned + c_emit × cells_emitted
Full Diff: Cost = c_row × H + c_scan × D × W + c_emit × p × N
Dirty-Row: Cost = c_scan × D × W + c_emit × p × N
Full Redraw: Cost = c_emit × N
Decision: argmin { E[Cost_full], E[Cost_dirty], E[Cost_redraw] }
```
**Conservative mode:** Uses 95th percentile of p (not mean) when posterior variance is high—the system knows when it's uncertain.
### Bayesian Capability Detection (Terminal Caps Probe)
Terminal capability detection uses **log Bayes factors as evidence weights** to combine noisy signals (env vars, DA1/DA2, DECRPM):
```
log BF = ln(P(data | feature) / P(data | ¬feature))
log-odds posterior:
logit P(feature | evidence) = logit P(feature) + Σ log BF_i
probability:
P = 1 / (1 + exp(-logit))
```
**Result:** robust capability detection even when individual probes are flaky.
### Dirty-Span Interval Union (Sparse Diff Scans)
For sparse updates, each row tracks **dirty spans** and the diff scans only the union of those spans:
```
Row y spans:
S_y = union_k [x0_k, x1_k)
Scan cost:
sum_y |S_y|
```
**Result:** scan work scales with the *actual changed area*, not full row width.
### Summed-Area Table (Tile-Skip Diff)
To skip empty tiles on large screens, a **summed-area table** (2D prefix sum) allows O(1) tile density checks:
```
SAT(x,y) = A(x,y)
+ SAT(x-1,y) + SAT(x,y-1) - SAT(x-1,y-1)
```
Tile sum queries over any rectangle become constant time, so empty tiles are skipped deterministically.
### Fenwick Tree (Prefix Sums for Virtualized Lists)
Variable-height virtualized lists use a **Fenwick tree** (Binary Indexed Tree) for fast prefix sums:
```
sum(i) = sum_{k=1..i} a_k
update(i, Δ): for (j=i; j<=n; j+=j&-j) tree[j]+=Δ
query(i): for (j=i; j>0; j-=j&-j) sum+=tree[j]
```
**Result:** O(log n) height lookup and scroll positioning without scanning all rows.
### Bayesian Height Prediction + Conformal Bounds (Virtualized Lists)
Virtualized lists predict unseen row heights to avoid scroll jumps, using a **Normal-Normal** conjugate update plus conformal bounds:
```
Prior: μ ~ N(μ₀, σ₀²/κ₀)
Posterior: μ_n = (κ₀·μ₀ + n·x̄) / (κ₀ + n)
Conformal interval:
[μ_n - q_{1-α}, μ_n + q_{1-α}]
```
Variance is tracked online with Welford’s algorithm, and `q` is the empirical quantile of |residuals|.
### BOCPD: Online Change-Point Detection
Resize coalescing uses **Bayesian Online Change-Point Detection** to detect regime transitions:
```
Observation model (inter-arrival times):
Steady: x_t ~ Exponential(λ_steady) where μ_steady ≈ 200ms
Burst: x_t ~ Exponential(λ_burst) where μ_burst ≈ 20ms
Run-length posterior (recursive update):
P(r_t = 0 | x_1:t) ∝ Σᵣ P(r_{t-1} = r) × H(r) × P(x_t | r)
P(r_t = r+1 | x_1:t) ∝ P(r_{t-1} = r) × (1 - H(r)) × P(x_t | r)
Hazard function (geometric prior):
H(r) = 1/λ_hazard where λ_hazard = 50
Complexity: O(K) per update with K=100 run-length truncation
```
**Regime posterior:**
```
P(burst | observations) = Σᵣ P(burst | r, x_1:t) × P(r | x_1:t)
Decision thresholds:
p_burst > 0.7 → Burst regime (aggressive coalescing)
p_burst < 0.3 → Steady regime (responsive)
otherwise → Transitional (interpolate delay)
```
### Bayes-Factor Evidence Ledger (Resize Coalescer)
Resize coalescing decisions are explained with a **log10 Bayes factor** ledger:
```
LBF = log10(P(evidence | apply_now) / P(evidence | coalesce))
Interpretation:
LBF > 0 → apply now
LBF < 0 → coalesce
|LBF| > 1 strong, |LBF| > 2 decisive
```
**Result:** coalescing is transparent and audit‑friendly, not heuristic black magic.
### Value-of-Information (VOI) Sampling
Expensive operations (height remeasurement, full diff) use **VOI analysis** to decide when to sample:
```
Beta posterior over violation probability:
p ~ Beta(α, β)
VOI computation:
variance_before = αβ / ((α+β)² × (α+β+1))
variance_after = (α+1)β / ((α+β+2)² × (α+β+3)) [if success]
VOI = variance_before - E[variance_after]
Decision:
sample iff (max_interval exceeded) OR (VOI × value_scale ≥ sample_cost)
```
**Tuned defaults for TUI:**
- `prior_alpha=1.0, prior_beta=9.0` (expect 10% violation rate)
- `max_interval_ms=1000` (latency bound)
- `min_interval_ms=100` (prevent over-sampling)
- `sample_cost=0.08` (moderately expensive)
### E-Process: Anytime-Valid Testing
All statistical thresholds use **e-processes** (wealth-based sequential tests):
```
Wealth process:
W_t = W_{t-1} × (1 + λ_t × (X_t - μ₀))
where λ_t is the betting fraction from GRAPA (General Random Adaptive Proportion Algorithm)
Key guarantee:
P(∃t: W_t ≥ 1/α) ≤ α under null hypothesis
This holds at ANY stopping time—no peeking penalty!
```
**Applications in FrankenTUI:**
- Budget degradation decisions
- Flake detection in tests
- Allocation budget alerts
- Conformal prediction thresholds
### Conformal Alerting
Budget and performance alerts use **distribution-free conformal prediction**:
```
Nonconformity score:
R_t = |observed_t - predicted_t|
Threshold (finite-sample guarantee):
q = quantile_{(1-α)(n+1)/n}(R_1, ..., R_n)
Coverage guarantee:
P(R_{n+1} ≤ q) ≥ 1 - α for any distribution!
E-process layer (anytime-valid):
e_t = exp(λ × (z_t - μ₀) - λ²σ²/2)
```
**Why conformal?** No distributional assumptions required—works for any data pattern.
### Mondrian Conformal Frame-Time Risk Gating
Frame-time risk gating uses **bucketed (Mondrian) conformal prediction** keyed by screen mode, diff strategy, and size:
```
Residuals: r_t = y_t - ŷ_t
Upper bound: ŷ_t^+ = ŷ_t + q_{1-α}(|r|)
Risk if: ŷ_t^+ > budget
```
Buckets fall back from (mode, diff, size) → (mode, diff) → (mode) → global default,
preserving coverage even when data is sparse.
### CUSUM Control Charts
Allocation budget tracking uses **CUSUM** (Cumulative Sum) for fast change detection:
```
One-sided CUSUM:
S_t = max(0, S_{t-1} + (X_t - μ₀) - k)
Alert when:
S_t > h (threshold)
Parameters:
k = allowance (typically σ/2)
h = threshold (controls sensitivity vs false alarms)
Dual detection:
Alert iff (CUSUM detects AND e-process confirms)
OR (e-process alone exceeds 1/α)
```
**Why dual?** CUSUM is fast but can false-alarm; e-process is slower but anytime-valid. Intersection gives speed with guarantees.
### CUSUM Hover Stabilizer (Mouse Jitter)
Hover target flicker is suppressed with a **CUSUM change‑point detector** on boundary‑crossing distance:
```
S_t = max(0, S_{t-1} + d_t - k)
switch if S_t > h
```
where `d_t` is signed distance to the current target boundary, `k` is drift allowance, and `h` is the switch threshold.
**Result:** single‑cell jitter doesn’t cause hover flicker, but intentional crossings still switch within a couple frames.
### Damped Spring Dynamics (Animation System)
Animation transitions use a **damped harmonic oscillator** for natural motion:
```
F = -k(x - x*) - c v
⇒ x'' + c x' + k(x - x*) = 0
```
Critical damping (fastest convergence without overshoot) is:
```
c_crit = 2√k
```
We integrate with **semi‑implicit Euler** and clamp large `dt` by subdividing
into small steps for stability. The result is deterministic, smooth motion
without frame‑rate sensitivity.
### Easing Curves + Stagger Distributions
Base animations use analytic easing curves:
```
ease_in(t) = t²
ease_out(t) = 1 - (1 - t)²
ease_in_out(t) =
2t² (t < 0.5)
1 - (-2t + 2)²/2 (t ≥ 0.5)
```
Staggered lists distribute start offsets by applying easing to normalized
indices:
```
offset_i = D · ease(i / (n - 1))
```
Optional deterministic jitter is added with a xorshift PRNG and clamped,
so cascades feel organic but remain reproducible in tests.
### Sine Pulse Sequences (Attention Cues)
Attention pulses are a single **half‑cycle sine**:
```
p(t) = sin(πt), t ∈ [0, 1]
```
This produces a smooth 0→1→0 emphasis without sharp edges or flicker.
### Perceived Luminance (Terminal Background Probe)
Background probing converts RGB to perceived luminance:
```
Y = 0.299R + 0.587G + 0.114B
```
That classification feeds capability detection for dark/light defaults.
### Jain's Fairness Index (Input Guard)
Input fairness monitoring uses **Jain's Fairness Index**:
```
F(x₁, ..., xₙ) = (Σxᵢ)² / (n × Σxᵢ²)
Properties:
F = 1.0 → Perfect fairness (all equal)
F = 1/n → Complete unfairness (one dominates)
Intervention:
if input_latency > threshold OR F < 0.8:
force_coalescer_yield()
```
**Why Jain's?** Scale-independent, bounded [1/n, 1], interpretable.
---
## Troubleshooting
### "terminal is corrupted after crash"
FrankenTUI uses RAII cleanup via `TerminalSession`. If you see a broken terminal, make sure you are not force‑killing the process.
```bash
# Reset terminal state
reset
```
### “error: the option `-Z` is only accepted on the nightly compiler”
FrankenTUI requires nightly. Install and use nightly or let `rust-toolchain.toml` select it.
```bash
rustup toolchain install nightly
```
### “raw mode not restored”
Ensure your app exits normally (or panics) and does not call `process::exit()` before `TerminalSession` drops.
### “no mouse events”
Mouse must be enabled in the session and supported by your terminal.
```bash
FTUI_HARNESS_ENABLE_MOUSE=true cargo run -p ftui-harness
```
### “output flickers”
Inline mode uses synchronized output where supported. If you’re in a very old terminal or multiplexer, expect reduced capability.
---
## Limitations
### What FrankenTUI Doesn’t Do (Yet)
- **Stable public API**: APIs are evolving quickly.
- **Full widget ecosystem**: Core widgets exist, but the ecosystem is still growing.
- **Guaranteed behavior on every terminal**: Capability detection is conservative; older terminals may degrade.
### Known Limitations
| Capability | Current State | Planned |
|------------|---------------|---------|
| Stable API | ❌ Not yet | Yes (post‑v1) |
| Full widget ecosystem | ⚠️ Partial | Expanding |
| Formal compatibility matrix | ⚠️ In progress | Yes |
---
## FAQ
### Why “FrankenTUI”?
It’s a modular kernel assembled from focused, composable parts — a deliberate, engineered “monster.”
### Is this a full framework?
Not yet. It’s a kernel plus core widgets. You can build a framework on top, but expect APIs to evolve.
### Does it work on Windows?
Windows support is tracked in `docs/WINDOWS.md` and is still being validated.
### Can I embed it in an existing CLI tool?
Yes. Inline mode is designed for CLI + UI coexistence.
### How do I update snapshot tests?
```bash
BLESS=1 cargo test -p ftui-harness
```
---
## Key Docs
- `docs/operational-playbook.md`
- `docs/risk-register.md`
- `docs/glossary.md`
- `docs/adr/README.md`
- `docs/concepts/screen-modes.md`
- `docs/spec/state-machines.md`
- `docs/telemetry.md`
- `docs/spec/telemetry.md`
- `docs/spec/telemetry-events.md`
- `docs/testing/coverage-matrix.md`
- `docs/testing/coverage-playbook.md`
- `docs/one-writer-rule.md`
- `docs/ansi-reference.md`
- `docs/WINDOWS.md`
- `docs/testing/e2e-playbook.md`
---
## Core Algorithms & Data Structures
FrankenTUI isn't just another widget library—it's built on carefully chosen algorithms and data structures optimized for terminal rendering constraints.
## Math-Driven Performance
FrankenTUI deliberately uses “heavy” math where it buys real-world speed or determinism. The core idea is: spend a little compute on principled decisions that prevent expensive work later.
### Bayesian Match Scoring (Command Palette)
Instead of raw string distance, the palette asks “how likely is this the right command?” Each clue (word start, tags, position) is a multiplier on confidence.
$$
\frac{P(R\mid E)}{P(\neg R\mid E)} = \frac{P(R)}{P(\neg R)} \prod_i BF_i, \quad
BF_i = \frac{P(E_i\mid R)}{P(E_i\mid \neg R)}
$$
Intuition: add a few strong clues and the right command jumps to the top without expensive rescoring passes.
### Evidence Ledger (Explainable Bayes)
Every probabilistic decision records its “why” as a ledger of factors. Internally this is just log‑odds arithmetic:
$$
\log \frac{P(R\mid E)}{P(\neg R\mid E)} = \log \frac{P(R)}{P(\neg R)} + \sum_i \log BF_i
$$
Intuition: you can read a human‑friendly list of reasons instead of debugging a black‑box score.
### Bayesian Cost Models (Diff Strategy)
The renderer learns the change rate instead of guessing. It keeps a **Beta posterior** and chooses the cheapest strategy (full diff vs dirty rows vs redraw).
$$
p \sim \mathrm{Beta}(\alpha,\beta), \quad
\alpha \leftarrow \alpha\cdot\gamma + k, \quad
\beta \leftarrow \beta\cdot\gamma + (n-k)
$$
$$
E[\text{cost}] = c_{scan}\,N_{scan} + c_{emit}\,N_{emit}
$$
Intuition: when the screen is stable we avoid scanning; when it’s noisy we switch to the cheapest path.
### Presenter Cost Modeling (Cursor/Byte Economy)
Even after diffing, there are multiple ways to emit ANSI. We compute a cheap byte‑level cost for cursor moves vs merged runs.
$$
\text{cost} = c_{scan}\,N_{scan} + c_{emit}\,N_{emit}
$$
Intuition: fewer cursor moves and shorter sequences means less output and lower latency.
### BOCPD for Resize Regimes
Resize storms are handled by **Bayesian Online Change‑Point Detection**. It detects when the stream changes from steady to burst, and only then coalesces aggressively.
$$
H(r)=\frac{1}{\lambda}, \quad
P(r_t=0\mid x_{1:t}) \propto \sum_r P(r_{t-1}=r)\,H(r)\,P(x_t\mid r)
$$
Intuition: no brittle thresholds; the model smoothly adapts to drag vs pause behavior.
### Run‑Length Posterior + Hazard Function (BOCPD Core)
BOCPD’s main state is the **run‑length posterior**—how long the current regime has lasted.
$$
P(r_t=r\mid x_{1:t}) \propto P(r_{t-1}=r-1)\,(1-H(r-1))\,P(x_t\mid r)
$$
Intuition: long steady streaks increase confidence; a sudden timing change collapses the posterior and triggers coalescing.
### Conformal Prediction (Risk Bounds)
Alerts are not hard‑coded. The threshold is learned from recent residuals so false‑alarm rates stay stable under distribution shifts.
$$
q = \text{Quantile}_{\lceil(1-\alpha)(n+1)\rceil}(R_1,\dots,R_n)
$$
Intuition: the system learns what “normal” looks like and updates the bar automatically.
### E‑Processes + GRAPA (Anytime‑Valid Monitoring)
We can check alerts continuously without “peeking penalties” using a test‑martingale (e‑process). GRAPA tunes the betting fraction.
$$
W_t = W_{t-1}\bigl(1 + \lambda_t (X_t-\mu_0)\bigr)
$$
Intuition: we can look after every frame, and the false‑alarm guarantees still hold.
### GRAPA (Adaptive Betting Fraction)
GRAPA adjusts the betting fraction to keep the e‑process sensitive but stable.
$$
\lambda_{t+1} = \lambda_t + \eta\,\nabla_{\lambda}\,\log W_t
$$
Intuition: it auto‑tunes how aggressively we test, instead of locking a single sensitivity.
### CUSUM (Fast Drift Detection)
CUSUM accumulates small deviations until they add up, catching sustained drift quickly.
$$
S_t = \max\bigl(0,\,S_{t-1} + (X_t-\mu_0) - k\bigr)
$$
Intuition: small problems that persist trigger quickly, while isolated noise is ignored.
### Value‑of‑Information (VOI) Sampling
Expensive measurements are taken only when the expected information gain is worth the cost.
$$
\mathrm{Var}(p)=\frac{\alpha\beta}{(\alpha+\beta)^2(\alpha+\beta+1)},\quad
\mathrm{VOI}=\mathrm{Var}(p)-\mathbb{E}[\mathrm{Var}(p\mid 1\ \text{sample})]
$$
Intuition: if a measurement won’t change our decision, we skip it and stay fast.
### Jain’s Fairness Index (Input Guarding)
We watch whether rendering is starving input processing.
$$
F=\frac{(\sum x_i)^2}{n\sum x_i^2}
$$
Intuition: a single metric tells us when to yield so the UI feels responsive.
### PID / PI Control (Frame Pacing)
Frame‑time control is classic feedback control.
$$
u_t = K_p e_t + K_i \sum e_t + K_d \Delta e_t
$$
Intuition: if we’re too slow, dial down; if we’re too fast, allow more detail. PI is the default because it’s robust and cheap.
### MPC (Model Predictive Control) Evaluation
We test MPC vs PI to prove we’re not leaving performance on the table.
$$
\min_{u_{t:t+H}} \sum_{k=0}^H \|y_{t+k}-y^*\|^2 + \rho\,\|u_{t+k}\|^2
$$
Intuition: MPC looks ahead but costs more; the tests show PI is already good enough for TUI pacing.
### Count‑Min Sketch (Approximate Counts)
We track hot items with a probabilistic sketch, then tighten error bounds with PAC‑Bayes.
$$
\hat f(x)=\min_j C_{j,h_j(x)},\quad
$$
Intuition: a tiny data structure gives you “close enough” frequencies at huge scale.
### PAC‑Bayes Calibration (Error Tightening)
We tighten sketch error bounds using PAC‑Bayes.
$$
\mathbb{E}[\text{err}] \le \bar e + \sqrt{\frac{\mathrm{KL}(q\|\|p)}{2n}}
$$
Intuition: the bound shrinks as we observe more data, without assuming a specific distribution.
### Scheduling Math (Smith’s Rule + Aging)
Background work is ordered by “importance per remaining time,” with aging to prevent starvation.
$$
\text{priority}=\frac{w}{r}+a\cdot\text{wait}
$$
Intuition: short, important jobs finish quickly, but long‑waiting jobs still rise.
These aren’t academic decorations—they’re directly tied to throughput, latency, and determinism under real terminal workloads.
### Visual FX Math At a Glance
The visual effects screen is deterministic math, not “random shader noise.” Each effect is a concrete dynamical system or PDE with explicit time‑stepping.
| Effect | Core Equation (MathJax) | What It Produces |
|--------|--------------------------|------------------|
| **Metaballs** | $F(x,y)=\sum_i \frac{r_i^2}{(x-x_i)^2+(y-y_i)^2}$, render iso‑surface $F\ge \tau$ | Smooth, organic blob fields |
| **Plasma** | $v=\frac{1}{6}\sum_{k=1}^6 \sin(\phi_k(x,y,t))$ (wave interference in 2D) | Psychedelic interference bands |
| **Gray‑Scott** | $\partial_t u = D_u\nabla^2u - uv^2 + F(1-u)$; $\partial_t v = D_v\nabla^2v + uv^2 - (F+k)v$ | Reaction‑diffusion morphogenesis |
| **Clifford Attractor** | $x_{t+1}=\sin(a y_t)+c\cos(a x_t)$; $y_{t+1}=\sin(b x_t)+d\cos(b y_t)$ | Chaotic strange‑attractor filaments |
| **Mandelbrot / Julia** | $z_{n+1}=z_n^2+c$ (escape‑time coloring) | Fractal boundaries + deep zooms |
| **Lissajous / Harmonograph** | $x=A\sin(a t+\delta)$, $y=B\sin(b t+\phi)$ (optionally $e^{-\gamma t}$ damping) | Elegant phase‑locked curves |
| **Flow Field** | $\vec v(x,y)=(\cos 2\pi N,\ \sin 2\pi N)$; $p_{t+1}=p_t+\vec v\,\Delta t$ | Particle ribbons through a vector field |
| **Wave Interference** | $I(x,t)=\sum_i \sin(k_i\|x-s_i\|-\omega_i t)$ | Multi‑source ripple patterns |
| **Spiral Galaxy** | $r=a e^{b\theta}$ with $\theta(t)=\theta_0+\omega t$ | Logarithmic spiral starfields |
| **Spin Lattice (LLG)** | $\frac{d\vec S}{dt}=-\vec S\times \vec H-\alpha\,\vec S\times(\vec S\times\vec H)$ | Magnetic domain dynamics |
### Math At a Glance
| Technique | Where It’s Used | Core Formula / Idea (MathJax) | Performance Impact |
|----------|------------------|-------------------------------|--------------------|
| **Bayes Factors** | Command palette scoring | $\frac{P(R\mid E)}{P(\neg R\mid E)}=\frac{P(R)}{P(\neg R)}\prod_i BF_i$ | Better ranking with fewer re‑sorts |
| **Evidence Ledger** | Explanations for probabilistic decisions | $\log\frac{P(R\mid E)}{P(\neg R\mid E)}=\log\frac{P(R)}{P(\neg R)}+\sum_i\log BF_i$ | Debuggable, auditable scoring |
| **Log‑BF Capability Probe** | Terminal caps detection | $\log BF=\log \frac{P(data\mid H)}{P(data\mid \neg H)}$ | Robust detection from noisy probes |
| **Log10‑BF Coalescer** | Resize scheduler evidence ledger | $LBF=\log_{10}\frac{P(E\mid apply)}{P(E\mid coalesce)}$ | Explainable, stable resize decisions |
| **Bayesian Hint Ranking** | Keybinding hint ordering | $V_i=E[U_i]+w_{voi}\sqrt{Var(U_i)}-\lambda C_i$ | Stable, utility‑aware hints |
| **Conformal Rank Confidence** | Command palette stability | $p_i=\frac{1}{n}\sum_j \mathbf{1}[g_j\le g_i]$ (gap‑based p‑value) | Deterministic tie‑breaks + stable top‑k |
| **Beta-Binomial** | Diff strategy selection | $p\sim\mathrm{Beta}(\alpha,\beta)$ with binomial updates | Avoids slow strategies as workload shifts |
| **Interval Union** | Dirty-span diff scan | $S_y=\bigcup_k [x_{0k},x_{1k})$ | Scan proportional to changed segments |
| **Summed-Area Table** | Tile-skip diff | $SAT(x,y)=A(x,y)+SAT(x-1,y)+SAT(x,y-1)-SAT(x-1,y-1)$ | Skip empty tiles on large screens |
| **Fenwick Tree** | Virtualized lists | Prefix sums with $i\pm (i\&-i)$ | O(log n) scroll + height queries |
| **Bayesian Height Predictor** | Virtualized list preallocation | $\mu_n=\frac{\kappa_0\mu_0+n\bar{x}}{\kappa_0+n}$ + conformal $q_{1-\alpha}$ | Fewer scroll jumps |
| **BOCPD** | Resize coalescing | Run‑length posterior + hazard $H(r)$ | Fewer redundant renders during drags |
| **Run‑Length Posterior** | BOCPD core | $P(r_t=r\mid x_{1:t})$ recursion | Fast regime switches without thresholds |
| **E‑Process** | Budget alerts, throttle | $W_t=W_{t-1}(1+\lambda_t(X_t-\mu_0))$ | Safe early exits under continuous monitoring |
| **GRAPA** | Adaptive e‑process | $\lambda_{t+1}=\lambda_t+\eta\nabla_{\lambda}\log W_t$ | Self‑tuning sensitivity |
| **Conformal Prediction** | Risk bounds | $q=\text{Quantile}_{\lceil(1-\alpha)(n+1)\rceil}(R)$ | Stable thresholds without tuning |
| **Mondrian Conformal** | Frame‑time risk gating | $\hat y^+=\hat y+q_{1-\alpha}(|r|)$ per bucket | Safe budget gating with sparse data |
| **CUSUM** | Budget change detection | $S_t=\max(0,S_{t-1}+X_t-\mu_0-k)$ | Fast drift detection |
| **CUSUM Hover Stabilizer** | Mouse hover jitter | $S_t=\max(0,S_{t-1}+d_t-k)$ | Stable hover targets without lag |
| **Damped Spring** | Animation transitions | $x''+c x' + k(x-x^*)=0$ | Natural motion without frame‑rate artifacts |
| **Easing Curves** | Fade/slide timing | $t^2$, $1-(1-t)^2$, cubic variants | Predictable velocity shaping |
| **Staggered Cascades** | List animations | $offset_i=D\cdot ease(i/(n-1))$ | Coordinated, non‑uniform entrances |
| **Sine Pulse** | Attention pulses | $p(t)=\sin(\pi t)$ | Smooth 0→1→0 emphasis |
| **Perceived Luminance** | Dark/light probe | $Y=0.299R+0.587G+0.114B$ | Reliable theme defaults |
| **PID / PI** | Degradation control | $u_t=K_pe_t+K_i\sum e_t+K_d\Delta e_t$ | Smooth frame‑time stabilization |
| **MPC** | Control evaluation | $\min_{u_{t:t+H}}\sum\|y_{t+k}-y^*\|^2+\rho\|u_{t+k}\|^2$ | Confirms PI is sufficient |
| **VOI Sampling** | Expensive measurements | $\mathrm{VOI}=\mathrm{Var}-\mathbb{E}[\mathrm{Var}\mid\text{sample}]$ | Lower overhead in steady state |
| **Jain’s Fairness** | Input guard | $F=(\sum x_i)^2/(n\sum x_i^2)$ | Prevents UI render from starving input |
| **Count‑Min Sketch** | Width cache + timeline aggregation | $\hat f(x)=\min_j C_{j,h_j(x)}$ | Fast approximate counts |
| **W‑TinyLFU Admission** | Width cache admission | admit if $\hat f(x)\ge \hat f(y)$ (Doorkeeper → CMS) | Higher cache hit‑rate, fewer width recomputes |
| **PAC‑Bayes** | Sketch calibration | $\bar e+\sqrt{\mathrm{KL}(q\|\|p)/(2n)}$ | Tighter error bounds |
| **Smith’s Rule + Aging** | Queueing scheduler | $priority=\frac{w}{r}+a\cdot\text{wait}$ | Fair throughput under load |
| **Cost Modeling** | Presenter decisions | $cost=c_{scan}N_{scan}+c_{emit}N_{emit}$ | Minimizes cursor bytes |
### The Cell: A 16-Byte Cache-Optimized Unit
Every terminal cell is exactly **16 bytes**, fitting 4 cells per 64-byte cache line:
```
┌─────────────────────────────────────────────────────────────────┐
│ Cell (16 bytes) │
├─────────────┬─────────────┬─────────────┬─────────────┬────────┤
│ CellContent │ fg │ bg │ attrs │ link_id│
│ (4 bytes) │ PackedRgba │ PackedRgba │ CellAttrs │ (2B) │
│ char/gid │ (4 bytes) │ (4 bytes) │ (2 bytes) │ │
└─────────────┴─────────────┴─────────────┴─────────────┴────────┘
```
**Why 16 bytes?**
- **Cache efficiency:** 4 cells per cache line means sequential row scans hit L1 cache optimally
- **SIMD comparison:** Single 128-bit comparison via `bits_eq()` for cell equality
- **No heap allocation:** 99% of cells store their character inline; only complex graphemes (emoji, ZWJ sequences) use the grapheme pool
### Block-Based Diff Algorithm
The diff engine processes cells in **4-cell blocks** (64 bytes) for autovectorization:
```
for each row:
if rows_equal(old[y], new[y]): ← Fast path: skip unchanged rows
continue
for each 4-cell block:
compare 4 × 128-bit cells ← SIMD-friendly
if any changed:
coalesce into ChangeRun ← Minimize cursor positioning
```
**Key optimizations:**
- **Row-skip fast path:** Unchanged rows detected with single comparison, no cell iteration
- **Dirty row tracking:** Mathematical invariant ensures only mutated rows are checked
- **Change coalescing:** Adjacent changed cells become single `ChangeRun` (one cursor move vs many)
### Presenter Cost Model
The ANSI presenter dynamically chooses the cheapest cursor positioning strategy:
```rust
// CUP (Cursor Position): CSI {row+1};{col+1}H
fn cup_cost(row, col) → 4 + digits(row+1) + digits(col+1) // e.g., "\x1b[12;45H" = 9 bytes
// CHA (Column Absolute): CSI {col+1}G
fn cha_cost(col) → 3 + digits(col+1) // e.g., "\x1b[45G" = 6 bytes
// Per-row decision: sparse runs vs merged write-through
strategy = argmin(sparse_cost, merged_cost)
```
This ensures expensive operations (like full diff computation) only run when the information gain justifies the cost.
---
## Bayesian Intelligence Layer
FrankenTUI uses principled statistical methods—not ad-hoc heuristics—for runtime decisions.
### BOCPD: Bayesian Online Change-Point Detection
The resize coalescer uses BOCPD to detect regime changes (steady typing vs burst resizing):
```
Observation Model:
inter-arrival times ~ Exponential(λ_steady) or Exponential(λ_burst)
Run-Length Posterior:
P(r_t | x_1:t) with truncation at K=100 for O(K) complexity
Regime Decision:
P(burst | observations) → coalescing delay selection
```
**Why Bayesian?**
- **No magic thresholds:** Prior beliefs updated with evidence
- **Smooth transitions:** Probability-weighted decisions, not binary switches
- **Principled uncertainty:** Knows when it doesn't know
### E-Process: Anytime-Valid Statistical Testing
Budget decisions and alert thresholds use **e-processes** (betting-based sequential tests):
```
Wealth Process:
W_t = W_{t-1} × (1 + λ_t(X_t - μ₀))
Guarantee:
P(∃t: W_t ≥ 1/α) ≤ α under null hypothesis
Key Property:
Valid at ANY stopping time (not just fixed sample sizes)
```
**Practical benefit:** You can check the e-process after every frame without inflating false positive rates.
### VOI Sampling: Value of Information
The runtime decides when to sample expensive metrics using VOI:
```
Beta posterior over violation probability:
p ~ Beta(α, β)
VOI computation:
variance_before = αβ / ((α+β)² × (α+β+1))
variance_after = (α+1)β / ((α+β+2)² × (α+β+3)) [if success]
VOI = variance_before - E[variance_after]
Decision:
sample iff (max_interval exceeded) OR (VOI × value_scale ≥ sample_cost)
```
This ensures expensive operations (like full diff computation) only run when the information gain justifies the cost.
---
## Performance Engineering
### Dirty Row Tracking
Every buffer mutation marks its row dirty in O(1):
```rust
fn set(&mut self, x: u16, y: u16, cell: Cell) {
self.cells[y as usize * self.width as usize + x as usize] = cell;
self.dirty_rows.set(y as usize, true); // O(1) bitmap write
}
```
**Invariant:** If `is_row_dirty(y) == false`, row y is guaranteed unchanged since last clear.
**Cost:** O(height) space, <2% runtime overhead, but enables skipping 90%+ of cells in typical frames.
### Grapheme Pooling
Complex graphemes (emoji, ZWJ sequences) are reference-counted in a pool:
```
GraphemeId (4 bytes):
┌────────────────────────────────────────┐
│ [31-25: width] [24-0: pool slot index] │
└────────────────────────────────────────┘
Capacity: 16M slots, display widths 0-127
Lookup: O(1) via HashMap deduplication
```
**Why pooling?**
- Most cells are ASCII (stored inline, no pool lookup)
- Complex graphemes deduplicated (same emoji = same GraphemeId)
- Width embedded in ID (no pool lookup for width queries)
### Synchronized Output
Frames are wrapped in DEC 2026 sync brackets for atomic display:
```
CSI ? 2026 h ←Begin synchronized update
[all frame output]
CSI ? 2026 l ← End synchronized update (terminal displays atomically)
```
**Guarantee:** No partial frames ever visible, eliminating flicker even on slow terminals.
---
## The Elm Architecture in Rust
FrankenTUI implements the **Elm/Bubbletea** architecture with Rust's type system:
### The Model Trait
```rust
pub trait Model: Sized {
type Message: From<Event> + Send + 'static;
fn init(&mut self) -> Cmd<Self::Message>;
fn update(&mut self, msg: Self::Message) -> Cmd<Self::Message>;
fn view(&self, frame: &mut Frame);
fn subscriptions(&self) -> Vec<Box<dyn Subscription<Self::Message>>>;
}
```
### Update/View Loop
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Event │───▶│ Message │───▶│ Update │───▶│ View │
│ (input) │ │ (enum) │ │ (model) │ │ (frame) │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Cmd │ │ Render │
│ (async) │ │ (diff) │
└─────────┘ └─────────┘
```
### Commands & Side Effects
```rust
Cmd::none() // No side effect
Cmd::perform(future, mapper) // Async operation → Message
Cmd::quit() // Exit program
Cmd::batch(vec![...]) // Multiple commands
```
### Subscriptions
Declarative, long-running event sources:
```rust
fn subscriptions(&self) -> Vec<Box<dyn Subscription<Message>>> {
vec![
tick_every(Duration::from_millis(16)), // 60fps timer
file_watcher("/path/to/watch"), // FS events
]
}
```
Subscriptions are automatically started/stopped based on what `subscriptions()` returns each frame.
---
## Safety & Correctness Guarantees
### Zero Unsafe Code Policy
```rust
// ftui-render/src/lib.rs
#![forbid(unsafe_code)]
// ftui-runtime/src/lib.rs
#![forbid(unsafe_code)]
// ftui-layout/src/lib.rs
#![forbid(unsafe_code)]
```
The entire render pipeline, runtime, and layout engine contain **zero `unsafe` blocks**.
### Integer Overflow Protection
All coordinate arithmetic uses saturating or checked operations:
```rust
// Cursor positioning (saturating)
let next_x = current_x.saturating_add(width as u16);
// Bounds checking (checked)
let Some(target_x) = x.checked_add(offset) else { continue };
// Intentional wrapping (PRNG only)
seed.wrapping_mul(6364136223846793005).wrapping_add(1)
```
### Flicker-Free Proof Sketch
The codebase includes formal proof sketches in `no_flicker_proof.rs`:
**Theorem 1 (Sync Bracket Completeness):** Every byte emitted by Presenter is wrapped in DEC 2026 sync brackets.
**Theorem 2 (Diff Completeness):** `BufferDiff::compute(old, new)` produces exactly `{(x,y) | old[x,y] ≠ new[x,y]}`.
**Theorem 3 (Dirty Tracking Soundness):** If any cell in row y was mutated, `is_row_dirty(y) == true`.
**Theorem 4 (Diff-Dirty Equivalence):** `compute()` and `compute_dirty()` produce identical output when dirty invariants hold.
---
## Test Infrastructure
### Property-Based Testing
```rust
#[test]
fn prop_diff_soundness() {
proptest!(|(
width in 10u16..200,
height in 5u16..100,
change_pct in 0.0f64..1.0
)| {
// Generate random buffers with controlled change percentage
// Verify diff output matches actual differences
});
}
```
### Snapshot Testing
```bash
# Run tests, auto-update baselines
BLESS=1 cargo test -p ftui-harness
# Snapshots stored as .txt files for easy diff review
tests/snapshots/
├── layout_flex_horizontal.txt
├── layout_grid_spanning.txt
└── widget_table_styled.txt
```
### Formal Verification Patterns
```rust
// Proof by counterexample: if this test fails, the theorem is false
#[test]
fn counterexample_dirty_soundness() {
let mut buf = Buffer::new(10, 10);
buf.set(5, 5, Cell::from_char('X'));
assert!(buf.is_row_dirty(5), "Theorem 3 violated: mutation without dirty flag");
}
```
### Benchmark Suite
```bash
cargo bench -p ftui-render
# Output:
# diff/identical_100x50 time: [1.2 µs] throughput: [4.2 Mcells/s]
# diff/sparse_5pct_100x50 time: [8.3 µs] throughput: [602 Kcells/s]
# diff/dense_100x50 time: [45 µs] throughput: [111 Kcells/s]
```
---
## Runtime Systems
### Resize Coalescing
Rapid resize events (e.g., window drag) are coalesced to prevent render thrashing:
```
Event Stream: R1 ─ R2 ─ R3 ─ R4 ─ R5 ─ [gap] ─ R6
└───────────────────┘ │
coalesced applied
(only R5 rendered)
Regimes:
Steady (200ms delay) ← Responsive to deliberate resizes
Burst (20ms delay) ← Aggressive coalescing during drag
```
### Budget-Based Degradation
Frame time is regulated with a PID controller:
```
Error: e_t = target_ms - actual_ms
Control: u_t = Kp·e_t + Ki·Σe + Kd·Δe
Degradation: Full → SimpleBorders → NoColors → TextOnly
Gains: Kp=0.5, Ki=0.05, Kd=0.2 (tuned for 16ms / 60fps)
```
When frames exceed budget, the renderer automatically degrades visual fidelity to maintain responsiveness.
### Input Fairness Guard
Prevents render work from starving input processing:
```
Fairness Index: F = (Σx_i)² / (n × Σx_i²) ← Jain's Fairness Index
Intervention: if input_latency > threshold OR F < 0.8:
force_resize_coalescer_yield()
```
---
## Widget System
### Core Widgets
| Widget | Description | Key Feature |
|--------|-------------|-------------|
| `Block` | Container with borders/title | 9 border styles, title alignment |
| `Paragraph` | Text with wrapping | Word/char wrap, scroll |
| `List` | Selectable items | Virtualized, custom highlight |
| `Table` | Columnar data | Column constraints, row selection |
| `Input` | Text input | Cursor, selection, history |
| `Textarea` | Multi-line input | Line numbers, syntax hooks |
| `Tabs` | Tab bar | Closeable, reorderable |
| `Progress` | Progress bars | Determinate/indeterminate |
| `Sparkline` | Inline charts | Min/max markers |
| `Tree` | Hierarchical data | Expand/collapse, lazy loading |
### Widget Composition
```rust
// Widgets compose via Frame's render method
fn view(&self, frame: &mut Frame) {
let chunks = Layout::horizontal([
Constraint::Percentage(30),
Constraint::Percentage(70),
]).split(frame.area());
frame.render_widget(sidebar, chunks[0]);
frame.render_widget(main_content, chunks[1]);
}
```
### Stateful Widgets
```rust
// State lives in your Model, widget borrows it
struct MyModel {
list_state: ListState,
}
fn view(&self, frame: &mut Frame) {
frame.render_stateful_widget(
List::new(items),
area,
&mut self.list_state,
);
}
```
---
## Advanced Features
### Hyperlink Support
```rust
let link_id = frame.link_registry().register("https://example.com");
cell.link_id = link_id;
// Emits OSC 8 hyperlink sequences for supporting terminals
```
### Focus Management
```rust
// Declarative focus graph
focus_manager.register("input1", FocusNode::new());
focus_manager.register("input2", FocusNode::new());
focus_manager.set_next("input1", "input2"); // Tab order
// Navigation
focus_manager.focus_next(); // Tab
focus_manager.focus_prev(); // Shift+Tab
```
### Modal System
```rust
modal_stack.push(ConfirmDialog::new("Delete file?"));
// Modals capture input, render above main content
// Escape or button press pops the stack
```
### Time-Travel Debugging
```rust
// Record frames for debugging
let mut recorder = TimeTravel::new();
recorder.record(frame.clone());
// Replay
recorder.seek(frame_index);
let historical_frame = recorder.current();
```
---
## About Contributions
*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
---
## License
MIT © 2026 Jeffrey Emanuel. See `LICENSE`.