FrankenTUI (ftui)

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

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).

# 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?

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

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::{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

How FrankenTUI Compares

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)

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:

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

3. Run the demo showcase (primary way to see the system):

   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

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.

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:

{"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)

cargo run -p ftui-demo-showcase

Run Harness Examples (tests and reference behavior)

cargo run -p ftui-harness --example minimal
cargo run -p ftui-harness --example streaming

Tests

cargo test
BLESS=1 cargo test -p ftui-harness  # update snapshot baselines

Deterministic E2E Runs

Use deterministic fixtures for stable hashes and reproducible logs:

# 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

cargo fmt
cargo clippy --all-targets -- -D warnings

E2E Scripts

./scripts/e2e_test.sh
./scripts/widget_api_e2e.sh

Configuration

FrankenTUI is configuration‑light. The harness is configured via environment variables:

# .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:

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.

# 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.

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.

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

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?

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.

Math At a Glance

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:

// 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):

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

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

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:

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

// 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:

// 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

#[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

# 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

// 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

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 Composition

// 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

// 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

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

// 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

modal_stack.push(ConfirmDialog::new("Delete file?"));
// Modals capture input, render above main content
// Escape or button press pops the stack

Time-Travel Debugging

// 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.