FrankenTUI (ftui)
███████╗██████╗ █████╗ ███╗ ██╗██╗ ██╗███████╗███╗ ██╗████████╗██╗ ██╗██╗
██╔════╝██╔══██╗██╔══██╗████╗ ██║██║ ██╔╝██╔════╝████╗ ██║╚══██╔══╝██║ ██║██║
█████╗ ██████╔╝███████║██╔██╗ ██║█████╔╝ █████╗ ██╔██╗ ██║ ██║ ██║ ██║██║
██╔══╝ ██╔══██╗██╔══██║██║╚██╗██║██╔═██╗ ██╔══╝ ██║╚██╗██║ ██║ ██║ ██║██║
██║ ██║ ██║██║ ██║██║ ╚████║██║ ██╗███████╗██║ ╚████║ ██║ ╚██████╔╝██║
╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚═════╝ ╚═╝
High‑performance terminal UI kernel -- 1.1M+ lines of Rust across 20 crates, 70 widget/stateful-widget implementations across 55 widget types in ftui-widgets (93 across the workspace), 45 interactive demo screens, a Bayesian intelligence layer, resizable pane workspaces, and in-tree web/WASM backends -- focused on correctness, determinism, and clean architecture.
Try It in Your Browser
All 45 screens run as WASM at frankentui.com/web — no install, no toolchain. It renders through WebGPU where that exists and falls back to canvas2d, so Chrome, Edge, Safari and Firefox all work.
Phones too: swipe in from either edge to change screens, and the bar along the bottom carries a button for every key the current screen uses. Press and hold to drag; a divider drags straight away.
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 (or grab prebuilt showcase binaries + SHA256SUMS from GitHub Releases)
|
# Run the demo showcase (primary way to see what FrankenTUI can do)
Or clone with git:
Toolchain. This checkout builds only with nightly Rust: rust-toolchain.toml
pins a dated nightly, and .cargo/config.toml passes nightly-only -Z flags.
You don't need to change your default toolchain. With rustup, every cargo
command inside the checkout uses the pin even when your default is stable, and
rustup installs it on first use. If automatic installs are off
(RUSTUP_AUTO_INSTALL=0), run rustup toolchain install in the checkout first.
Two settings outrank the pin: a RUSTUP_TOOLCHAIN environment variable and a
rustup override for the directory. Run rustup show active-toolchain in the
checkout to see which toolchain is in effect and why. If it names stable, unset
whichever setting it reports, or name the pinned nightly explicitly. The date is
the channel value in rust-toolchain.toml:
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 the bottom while logs scroll into real scrollback above it, including inside tmux, screen and zellij | 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 |
| 70 widget impls | Block, Paragraph, Table, Input, Tree, Modal, Command Palette, etc. | 70 direct Widget / StatefulWidget implementations across 55 widget types in ftui-widgets (93 workspace-wide) |
| Pane workspaces | Drag‑to‑resize, docking, magnetic snap, inertial throw, undo/redo | PaneTree + PaneDragResizeMachine in ftui-layout |
| Web/WASM backend | Same Rust core renders in browser-oriented environments | In-tree ftui-web + ftui-showcase-wasm |
| Bayesian intelligence | Statistical diff strategy, resize coalescing, capability detection | BOCPD, VOI, conformal prediction, e‑processes |
| Shadow‑run validation | Prove rendering determinism across runtime migrations | ShadowRun::compare() in ftui-harness |
| 45 demo screens | Dashboard, visual effects, widget gallery, layout lab, and more | cargo run -p ftui-demo-showcase |
Getting Started (Library Consumers)
If you want to embed FrankenTUI in your own Rust app (not just run the demo), start here: docs/getting-started.md.
For web embedding into frankentui_website (Next.js + bun), see the
Embedding In frankentui_website section in
docs/getting-started.md. It includes:
- in-tree build/check guidance for
ftui-webandftui-showcase-wasm, - a clear note that
FrankenTermWebis currently adjacent/out-of-tree from this checkout, - runtime initialization guidance for
FrankenTermWebonce that bundle is available, - and explicit no-
xterm.jsguidance.
Quick Example
# Demo showcase (primary)
# Pick a specific showcase screen
FTUI_DEMO_SCREEN=18
# Agent shell with a real child process
# The child on a pseudo-terminal (isatty, own process group; Unix)
Run cargo run -p ftui-demo-showcase -- --help for screen numbers and options.
Press 1–9/0 to select screens 1–10, or Tab/Shift+Tab to cycle through screens.
Demo Showcase Gallery (45 Screens)
The demo showcase (cargo run -p ftui-demo-showcase) ships 45 interactive screens, each demonstrating a different subsystem:
| Category | Screens | What They Show |
|---|---|---|
| Overview | dashboard, widget_gallery, advanced_features |
Full-system demos with animated panels, sparklines, markdown streaming |
| Layout | layout_lab, layout_inspector, intrinsic_sizing, responsive_demo |
Flex/Grid solvers, pane workspaces, constraint visualization |
| Text | shakespeare, markdown_rich_text, markdown_live_editor, advanced_text_editor |
Rope editor, syntax highlighting, streaming markdown |
| Data | table_theme_gallery, data_viz, virtualized_search, log_search |
Themed tables, charts, Fenwick-backed virtualization |
| Input | forms_input, form_validation, command_palette_lab, mouse_playground |
Bayesian fuzzy search, gesture recognition, focus management |
| Visual FX | visual_effects, theme_studio, mermaid_showcase, mermaid_mega_showcase |
Gray-Scott reaction-diffusion, metaballs, Clifford attractors, fractal zooms |
| System | terminal_capabilities, performance, performance_hud, determinism_lab |
Capability probing, frame budgets, conformal risk gating |
| Diagnostics | explainability_cockpit, voi_overlay, snapshot_player, accessibility_panel |
Evidence ledgers, VOI sampling visualization, a11y tree |
| Workflow | file_browser, kanban_board, async_tasks, notifications, drag_drop |
File picker, task boards, notification toasts, drag handles |
| Advanced | inline_mode_story, hyperlink_playground, i18n_demo, macro_recorder, quake_easter_egg |
Inline scrollback, OSC 8 links, locale switching, event recording, a depth-buffered E1M1 |
| Code | code_explorer, widget_builder, action_timeline |
AST browsing, widget composition, timeline aggregation |
| Tour | guided_tour |
Cinematic auto-play tour across key screens |
Each screen is also a snapshot test target. BLESS=1 cargo test -p ftui-demo-showcase updates baselines.
Use Cases
- Inline UI for CLI tools and agent harnesses where logs must keep scrolling (see the agent harness tutorial).
- 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
This example targets FrankenTUI 0.10.0 with the default features enabled. See installation for version and local checkout dependencies.
use *;
use Paragraph;
Design Philosophy
- Correctness over cleverness. Predictable terminal state is non-negotiable.
- Deterministic output. Buffer diffs and explicit presentation over ad-hoc writes.
- Inline first. Preserve scrollback while keeping chrome stable.
- Layered architecture. Core, render, runtime, widgets; no cyclic dependencies.
- Zero-surprise teardown. RAII cleanup, even when apps crash.
Workspace Overview (20 Crates)
Core Architecture
| Crate | Purpose | Status |
|---|---|---|
ftui |
Public facade + prelude | Implemented |
ftui-core |
Terminal lifecycle, events, capabilities, animation, input parsing, gestures | Implemented |
ftui-render |
Buffer, diff, ANSI presenter, frame, grapheme pool, budget system | Implemented |
ftui-style |
Style + theme system with CSS‑like cascading | Implemented |
ftui-text |
Spans, segments, rope editor, cursor, BiDi, shaping, normalization | Implemented |
ftui-layout |
Flex + Grid solvers, pane workspace system, e‑graph optimizer | Implemented |
ftui-runtime |
Elm/Bubbletea runtime, effect system, subscriptions, rollout policy, telemetry schema (program.rs) |
Implemented |
ftui-widgets |
70 direct Widget / StatefulWidget implementations across 55 widget types in the library (93 workspace-wide) |
Implemented |
ftui-extras |
Feature‑gated add‑ons, VFX rasterizer (opt‑level=3) | Implemented |
Backend & Platform
| Crate | Purpose | Status |
|---|---|---|
ftui-backend |
Backend abstraction layer | Implemented |
ftui-tty |
TTY terminal backend | Implemented |
ftui-web |
Web/WASM adapter with pointer/touch parity | Implemented |
ftui-showcase-wasm |
WASM build of the demo showcase | Implemented |
Testing & Verification
| Crate | Purpose | Status |
|---|---|---|
ftui-harness |
Test harness, shadow‑run comparison, benchmark gate, rollout scorecard, determinism fixtures | Implemented |
ftui-pty |
PTY‑based test utilities | Implemented |
ftui-demo-showcase |
45 interactive demo screens + snapshot tests | Implemented |
doctor_frankentui |
Integrated TUI capture, seeding, suite reporting, diagnostics, and coverage gating (9 default core subcommands + 4 aliases across 23 core modules; 23 experimental product subcommands behind --features experimental) |
Implemented |
Supporting
| Crate | Purpose | Status |
|---|---|---|
ftui-a11y |
Accessibility tree and node structures | Implemented |
ftui-i18n |
Internationalization support | Implemented |
ftui-simd |
Portable-SIMD ASCII detection and row compare (opt-in simd feature) |
Implemented |
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 | ❌ |
| Pane workspaces (drag/resize/dock) | ✅ Built‑in | ❌ | ❌ | ❌ |
| Web/WASM backend | ✅ Shared Rust core | ❌ | ❌ | ❌ |
| Bayesian diff strategy | ✅ Adaptive | ❌ Fixed | ❌ Fixed | ❌ N/A |
| Shadow‑run validation harness | ✅ Harness workflow (ShadowRun) |
❌ | ❌ | ❌ |
| Snapshot/time‑travel harness | ✅ Built‑in | ❌ | ❌ | ❌ |
| Widget count | 70 direct impls (55 types; 93 workspace-wide) | ~20 | ~12 | 0 |
| Demo screens | 45 | ~5 | ~5 | 0 |
When to use FrankenTUI:
- You want inline + scrollback without flicker.
- You care about deterministic rendering and teardown guarantees.
- You need resizable pane workspaces with drag, dock, and undo.
- You want a single Rust codebase targeting both terminal and web.
- You prefer a kernel you can build your own UI framework on top of.
When FrankenTUI might not be ideal:
- You need a stable public API today (FrankenTUI is evolving fast).
- You want a fully opinionated application framework rather than a kernel.
Installation
Quick Install (Source Tarball)
|
Git Clone
Use as a Workspace Dependency
# Cargo.toml
[]
= { = "../frankentui/crates/ftui" }
Crates.io Dependency
The workspace provides 17 library crates (the ftui facade plus
ftui-core, ftui-render, ftui-style, ftui-text, ftui-layout,
ftui-runtime, ftui-widgets, ftui-extras, ftui-backend, ftui-tty,
ftui-web, ftui-harness, ftui-pty, ftui-a11y, ftui-i18n,
ftui-simd):
[]
= "=0.10.0"
These dependency examples target 0.10.0. To work from a local checkout, use the path dependency above instead.
The default features are runtime, extras, and backend. App::run() selects
native ftui-tty on Unix and Crossterm elsewhere; ftui::DEFAULT_BACKEND
reports the selected backend. Headless, WASM, or custom-backend consumers can
disable the defaults:
[]
= { = "=0.10.0", = false, = ["runtime"] }
Without a compiled terminal backend, App::run() returns an Unsupported
error naming the feature to enable. The doctor, demo, and WASM showcase targets
are repository-only applications. Maintainers cutting a new version follow
docs/release-checklist.md.
Quick Start
- Install Rust with rustup. The checkout selects its pinned nightly from
rust-toolchain.toml(see Toolchain above). - Clone the repo and build:
- Run the demo showcase (primary way to see the system):
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 |
bidi |
Bidirectional text reordering via unicode-bidi (default) |
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) |
ftui-widgets |
bidi |
BiDi (UAX#9) visual reordering for Paragraph; editable widgets keep logical order |
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 EvidenceSinkConfig;
new
.with_evidence_sink
.run
Example event line:
{"schema_version":"ftui-evidence-v1","event":"diff_decision","run_id":"diff-521820","event_idx":0,"screen_mode":"altscreen","cols":100,"rows":30,"strategy":"DirtyRows","cost_full":5311.417405,"cost_dirty":5308.417405,"cost_redraw":18000.0,"posterior_mean":0.05,"posterior_variance":0.002262,"alpha":1.0,"beta":19.0,"guard_reason":"uncertainty_variance","hysteresis_applied":false,"hysteresis_ratio":0.05,"dirty_rows":30,"total_rows":30,"total_cells":3000,"span_count":0,"span_coverage_pct":100.0,"max_span_len":100,"fallback_reason":"none","scan_cost_estimate":3000,"tile_used":false,"tile_fallback":"none","tile_w":0,"tile_h":0,"tile_size":0,"tiles_x":0,"tiles_y":0,"dirty_tiles":0,"dirty_tile_count":0,"dirty_cells":0,"dirty_tile_ratio":0.0,"dirty_cell_ratio":0.0,"scanned_tiles":0,"skipped_tiles":0,"skipped_tile_count":0,"tile_scan_cells_estimate":0,"sat_build_cost_est":0,"skipped_tile_rows":0,"sat_queries":0,"bayesian_enabled":true,"dirty_rows_enabled":true,"regime":"sparse"}
Commands
Run the Demo Showcase (Primary)
Run Harness Examples (tests and reference behavior)
agent_shell is the flagship inline child-streaming demo (streams a child
process into terminal scrollback under a compact 3-row status/input/hint UI).
minimal is a 45-line inline hello world with a tick counter; q, Escape or
Ctrl-C quits. streaming demonstrates the 15-row widget-region LogViewer
with generated logs or an optional child command (see the
agent harness tutorial).
Tests
BLESS=1
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
# Demo showcase E2E with an explicit seed
E2E_DETERMINISTIC=1 E2E_SEED=42
Format + Lint
E2E Scripts
DSR runs ./scripts/e2e_test.sh --quick and ./scripts/pane_e2e.sh --mode smoke as direct acceptance checks via frankentui-render-pane-e2e in .config/dsr-quality.yaml with strict JSONL validation (validate_jsonl.py --strict); the full suites (./scripts/e2e_test.sh and ./scripts/pane_e2e.sh --mode full) run in scheduled extended sweeps.
Performance Gates
doctor_frankentui Verification
doctor_frankentui ships a default 23-module verification core exposing 9 core subcommands and 4 aliases (replay/capture, seed-demo, migrate/suite, report, certify/doctor, plan/import, list-profiles, performance-diff, visual-diff), while the 23 migration/graveyard/gates product subcommands (101 modules) are gated behind --features experimental (see docs/doctor-frankentui-products.md). DSR runs the canonical verification stack via the frankentui-doctor-verification tool in .config/dsr-quality.yaml.
Run the full doctor_frankentui verification stack locally:
Prerequisites:
cargopython3jqrg(ripgrep)vhs,ffmpeg, andffprobe(required bydoctor_frankentui_happy_e2e.shanddoctor_frankentui_failure_e2e.shfor real VHS/frame media capture)cargo-llvm-cov(cargo install cargo-llvm-cov)- Python TOML parser support:
- Python
3.11+(built-intomllib), or python3 -m pip install tomlifor Python<3.11
- Python
# Unit + integration tests (default core) and core test-time budget (< 300s)
# Workflow-level E2E + replay triage
# Determinism soak (3 iterations, 0 non-volatile divergences)
# Coverage gate + retained artifact bundle/JSONL schema validation
Artifact contract (DSR and local, retained under /tmp/doctor_frankentui_ci/):
.../artifact_map.txt: retained artifact index and paths..../happy/meta/summary.json: happy-path pass/fail and per-step timing..../happy/meta/artifact_manifest.json: checksums, sizes, and mtimes for expected outputs..../failure/meta/summary.json: failure-matrix pass/fail counts..../failure/meta/case_results.json: per-case expected vs actual exits and key artifacts..../failure/meta/replay_triage_report.json: deterministic failure signal triage and replay commands..../determinism/meta/determinism_report.jsonand.../determinism/meta/determinism_report.txt: multi-run determinism comparison results (total_divergences == 0)..../coverage/coverage_gate_report.json: machine-readable threshold decision (overall,core_engine,full_stack_orchestration,diagnostics_and_contracts)..../coverage/coverage_gate_report.txt: human-readable coverage gate details.
Troubleshooting map:
doctor/capture/suite/reportchain failures: inspect.../happy/logs/*.stderr.logand.../happy/meta/command_manifest.txt.- failure-case assertion mismatches: inspect
.../failure/meta/case_results.jsonand.../failure/cases/<case_id>/logs/. - JSON contract regressions: inspect
json_*case stdout logs under.../failure/cases/. - coverage regressions: inspect
.../coverage/coverage_gate_report.jsonfor failing group + threshold delta.
Release Publishing (Maintainers)
Releases use DSR on native build hosts with the channel in rust-toolchain.toml.
GitHub Actions stays disabled. Run the registry helper from a clean candidate
checkout inside the native DSR job:
bash scripts/release_publish_crates.sh VERSION NEW_OUTPUT_DIR --dry-run
bash scripts/release_publish_crates.sh VERSION NEW_OUTPUT_DIR --publish
Each invocation requires a fresh output directory outside the checkout.
The dry run verifies all 17 packages without a registry token once their sibling
dependency versions are available in the registry; unpublished siblings can
block a prepublication dry run. Publication
follows dependency order, verifies registry checksums and Git provenance, and
retains archives for safe retries. Repeating publication with a new output
directory verifies and skips already-published versions. Keep the structured
release_log.jsonl, Cargo logs, registry responses, and retained archives.
Configuration
The following variables configure the reference harness binary,
cargo run -p ftui-harness. Export them in your shell or prefix the command
with assignments; the binary does not load a .env file automatically.
# inline | alt
# rows reserved for UI
# harness fixture selector
# enable mouse events
# enable focus events
# generate this many startup log lines
# parse markup in loaded log lines
# read lines into the log viewer
# 0 disables auto-exit
# Optional controls (uncomment only those you need):
# export FTUI_HARNESS_AUTO_UI_HEIGHT=true # grow inline UI above its minimum height
# export FTUI_HARNESS_ENABLE_KITTY_KEYBOARD=true # request enhanced keyboard reporting
# export FTUI_HARNESS_LOCALE=en-US # runtime locale context
# export FTUI_HARNESS_SUPPRESS_WELCOME=true # omit startup welcome lines
# export FTUI_HARNESS_LOG_KEYS=true # log received key events
# export FTUI_HARNESS_DIFF_BAYESIAN=true # Bayesian diff strategy selection
# export FTUI_HARNESS_BOCPD=true # change-point resize coalescing
# export FTUI_HARNESS_CONFORMAL=true # conformal frame-budget prediction
# export FTUI_HARNESS_FRAME_BUDGET_US=16667 # total frame budget, microseconds
# export FTUI_HARNESS_RENDER_BUDGET_US=8000 # render budget; may raise total budget
# export FTUI_HARNESS_EVIDENCE_JSONL=/path/to/harness.jsonl # rendering evidence output
Harness view names include default, layout-flex-row, layout-flex-col,
layout-grid, layout-nested, widget-block, widget-paragraph, widget-table,
widget-list, widget-input, widget-inspector, widget-budget, tile-skip,
span-diff, selector-storm, and locale-context. Unknown names select the
default view. Harness examples have their own options: of these harness settings,
minimal uses only auto-exit, rounded up to its 250 ms tick interval.
The showcase, cargo run -p ftui-demo-showcase, has separate controls.
Command-line flags take precedence over environment defaults.
# --screen=N; 1-indexed
# --screen-mode=alt|inline|inline-auto
# --mouse=on|off|auto
# 0 disables auto-exit
# deterministic fixtures and time
# fixture seed
# write rendering evidence
# Optional controls:
# export FTUI_DEMO_UI_HEIGHT=20 # --ui-height; inline rows
# export FTUI_DEMO_UI_MIN_HEIGHT=12 # --ui-min-height; inline-auto minimum
# export FTUI_DEMO_UI_MAX_HEIGHT=40 # --ui-max-height; inline-auto maximum
# export FTUI_DEMO_TOUR=true # --tour; guided tour on launch
# export FTUI_DEMO_TOUR_SPEED=1.0 # --tour-speed; speed multiplier
# export FTUI_DEMO_TOUR_START_STEP=1 # --tour-start-step; 1-indexed
# export FTUI_DEMO_PANE_WORKSPACE=/path/to/panes.json # --pane-workspace; persisted layout
For the full showcase CLI and environment list, including tour and VFX controls,
run cargo run -p ftui-demo-showcase -- --help.
Fixture and diagnostic controls are listed with their purposes in
docs/env-internal-allowlist.txt.
python3 -B scripts/check_env_docs.py checks binary attribution and the
environment-variable inventory in the harness main and showcase CLI entry points.
Terminal capability detection uses standard environment variables (TERM, COLORTERM, NO_COLOR, TMUX, ZELLIJ, KITTY_WINDOW_ID).
Architecture
┌──────────────────────────────────────────────────────────────────────────────┐
│ INPUT LAYER │
├──────────────────────────────────────────────────────────────────────────────┤
│ ftui-tty (Unix) / 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 │
├──────────────────────────────────────────────────────────────────────────────┤
│ BackendPresenter (TerminalPresenter over TerminalWriter; WebPresenter) │
│ inline mode (scrollback-friendly) | alt-screen mode (classic) │
└──────────────────────────────────────────────────────────────────────────────┘
Frame Pipeline (Step-by-Step)
- Input →
TerminalSessionreadsEvent. - Model →
update()returnsCmdfor side effects. - View →
view()renders intoFrame. - Buffer →
Framewrites cells into a 2DBuffer. - Diff →
BufferDiffcomputes minimal changes. - Presenter → emits ANSI with state tracking.
- Writer → enforces one‑writer rule, flushes output.
This is the core loop that ensures determinism and flicker‑free output.
Pane Workspace System
FrankenTUI includes a full pane workspace system (ftui-layout/src/pane.rs) that goes far beyond simple split layouts:
- Drag‑to‑resize via splitter handles with cell‑level hit‑testing
- Drag‑to‑move with magnetic docking fields and live ghost preview targets
- Inertial throw: release mid-drag and panes coast with momentum via
PaneInertialThrow - Pressure-sensitive snap: snap strength derived from drag speed and direction changes via
PanePressureSnapProfile - Multi‑pane selection via Shift+Click with
PaneSelectionState - Intelligence modes: Focus, Compare, Monitor, Compact layout presets via
PaneLayoutIntelligenceMode - Persistent interaction timeline with full undo/redo/replay via
PaneInteractionTimeline - Right‑click mode cycling through all four intelligence modes
- Scroll-wheel magnetic field tuning: adjust snap strength without leaving the pane
- Terminal + Web parity: same pane interactions work in both backends via
PaneTerminalAdapterandPanePointerCaptureAdapter
The pane system is integrated into three of the 45 demo screens (Dashboard, Widget Gallery, Layout Lab) and has dedicated E2E tests (scripts/pane_e2e.sh).
Pane Architecture
PaneTree ← Spatial layout tree (HSplit / VSplit / Leaf)
└── PaneOperation ← Atomic layout mutation (resize, swap, split, close)
└── PaneInteractionTimeline ← Undo/redo/replay history of operations
└── PaneDragResizeMachine ← State machine for pointer gesture lifecycle
└── PaneSemanticInputEvent ← High‑level input abstraction
Runtime Migration & Rollout Infrastructure
FrankenTUI is migrating its execution substrate through three lanes:
| Lane | Description | Status |
|---|---|---|
Legacy |
Thread‑based subscriptions with manual stop coordination | Available |
Structured |
CancellationToken‑backed subscriptions (current default) | Active |
Asupersync |
Asupersync blocking task pool with CancellationToken-backed subscriptions | Available with ftui-runtime/asupersync-executor |
Selecting asupersync without that feature emits a warning and resolves to
Structured. An explicit task backend in EffectQueueConfig takes precedence
over the lane default. Subscriptions retain their structured cancellation;
the lane selects how Cmd::Task closures execute.
Rollout Policy
Runtime lane transitions are managed through a shadow‑run comparison system to prevent regressions:
// Operator workflow: Off → Shadow → Evaluate → Enable → Monitor → Rollback
let config = default
.with_lane // Current execution backend
.with_rollout_policy // Shadow‑compare before enabling
.with_env_overrides; // FTUI_RUNTIME_LANE, FTUI_ROLLOUT_POLICY
When RolloutPolicy::Shadow is active alongside an EvidenceSink, Program emits one shadow_frame JSONL line per presented frame containing the 64-bit FNV-1a cell buffer checksum (checksum), frame index (frame), resolved runtime lane (lane), and task executor backend (task_backend). Two recorded shadow runs can be compared offline via ftui_harness::ShadowRun::compare_recorded(&a, &b) or the CLI tool cargo run -p ftui-harness --bin shadow_compare -- a.jsonl b.jsonl, and live dual-lane runs (with external effects recorded once via ShadowEffectLog and replayed on the candidate lane) can be compared via ShadowRun::compare_lanes.
| Environment Variable | Values | Default | Purpose |
|---|---|---|---|
FTUI_RUNTIME_LANE |
legacy, structured, asupersync |
structured |
Select execution backend |
FTUI_ROLLOUT_POLICY |
off, shadow, enabled |
off |
Control rollout behavior |
Shadow‑Run Validation
Prove rendering determinism across runtime migrations by running the same model through two independent execution paths and comparing frame checksums:
use ;
let config = new.viewport;
let result = compare;
assert_eq!;
Rollout Scorecard & Evidence Bundle
Combine shadow evidence + benchmark results into a single go/no‑go release decision:
use ;
let mut scorecard =
new;
for shadow_result in shadow_results
assert_eq!;
// Machine-readable JSON evidence for CI gates
let bundle = RolloutEvidenceBundle ;
println!; // Self-contained release decision artifact
Effect Queue Telemetry & Backpressure
The effect executor tracks queue health with monotonic counters and enforces backpressure:
// Configure backpressure bounds
let config = default.with_effect_queue;
// Monitor queue health at runtime
let snap = queue_telemetry;
// snap.enqueued, snap.processed, snap.dropped, snap.high_water, snap.in_flight
Unified Telemetry Schema
All runtime telemetry uses canonical targets and event names defined in ftui_runtime::telemetry_schema:
| Target | Purpose |
|---|---|
ftui.runtime |
Startup, shutdown, lane resolution |
ftui.effect |
Command/subscription execution, queue drops |
ftui.process |
Process subscription lifecycle |
ftui.decision.resize |
Resize coalescer decisions |
ftui.voi |
Value‑of‑information sampling |
ftui.bocpd |
Change‑point detection |
ftui.eprocess |
E‑process throttle decisions |
ftui.guardrails |
Frame guardrails: soft memory trims and emergency frame drops |
ftui.a11y |
Accessibility tree diffs and screen‑reader announcements (only with ProgramConfig::with_accessibility) |
Web/WASM Backend
FrankenTUI targets both native terminals and web browsers from a single Rust codebase. ftui-web is a host-driven, deterministic-time patch producer implementing the ftui-backend traits (WebBackend, WebPresenter, WebEventSource, DeterministicClock); ftui-showcase-wasm exports ShowcaseRunner via wasm-bindgen; rendering and DPR/zoom measurement are performed by a browser host (either crates/ftui-showcase-wasm/frankentui_showcase_demo.html paired with the pinned FrankenTermWeb renderer built by build-wasm.sh and the verified DOM text bridge crates/ftui-showcase-wasm/accessibility.mjs, or the lightweight in-tree DOM <pre> text host crates/ftui-showcase-wasm/sdk/showcase-host.js):
| Crate | Purpose |
|---|---|
ftui-web |
Host-driven web backend with pointer/touch parity (DPR/zoom handling in the JS browser hosts) |
ftui-showcase-wasm |
WASM build target (ShowcaseRunner) for the demo showcase |
The web adapter translates browser pointer events into the same PaneSemanticInputEvent stream used by the terminal backend, ensuring interaction parity across platforms, and treats every ShowcaseRunner::resize(cols, rows) call (including same-geometry DPR/zoom transitions) as a full-repaint boundary.
This checkout does not currently vendor local crates/frankenterm-core or
crates/frankenterm-web workspace members. Those names still appear in specs and
adjacent integration docs, but the in-tree browser surface today is ftui-web
plus the ftui-showcase-wasm target. ftui-pty integrates with an external
frankenterm-core dependency rather than a local workspace crate.
FrankenTerm Integration
FrankenTUI shares contracts and backend primitives with the broader FrankenTerm effort, but this repository currently contains the ftui-side integration pieces rather than a vendored local browser-terminal crate.
What is in-tree right now:
ftui-webbackend primitives, patch formats, and deterministic host-driven runtime supportftui-showcase-wasmas the WASM demo/showcase targetftui-ptyintegration against the externalfrankenterm-corecrate
What remains adjacent/out-of-tree from this checkout:
- a browser-facing
FrankenTermWebbundle/package - the local
crates/frankenterm-core/crates/frankenterm-weblayout still referenced by some specs
The adjacent terminal-emulator design target still includes:
- CSI/OSC/DCS sequences for cursor control, colors, and window operations
- Alternate screen buffer switching (like vim/less)
- Mouse reporting protocols (X10, SGR, URXVT)
- Scrollback with configurable history depth
- Selection/copy with Unicode-aware grapheme boundaries
"Alien Artifact" Quality Algorithms
FrankenTUI employs mathematically rigorous algorithms that go far beyond typical TUI implementations. We call this "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.
Where it runs: ftui_widgets::hint_ranker::HintRanker and ftui_widgets::help::Help (Help::register_with_ranker, Help::apply_ranking, Help::record_used, and Help::record_shown), exercised live in the showcase's CommandPaletteEvidenceLab screen.
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 × min(D × W, N)
Dirty-Row: Cost = c_scan × scan_cells + c_emit × p × scan_cells
Full Redraw: Cost = c_emit × N
Decision: argmin { E[Cost_full], E[Cost_dirty], E[Cost_redraw] }
Here scan_cells is Buffer::dirty_span_stats().span_coverage_cells — the exact cell count that the default certified dirty-span scan (BufferDiff::compute_certified_into) compares. Because observe() trains p as changes per scanned cell, the expected-emission term multiplies p by each path's own scanned region (min(D × W, N) for Full, scan_cells for DirtyRows) rather than total screen cells N.
Uncertainty guard & conservative mode: conservative defaults to false; when conservative == true or posterior variance exceeds uncertainty_guard_variance = 0.002, p uses the conservative_quantile = 0.95 upper quantile via a normal approximation (ChangeRateEstimator::upper_quantile).
Bayesian Capability Detection (Terminal Caps Probe)
Runtime capability upgrades are decided by a log-Bayes-factor ledger (ftui_core::caps_probe::ledger_for): every signal contributes a fixed log-odds weight and an upgrade is applied when the posterior clears 0.8 (DECISION_THRESHOLD):
log-odds = Σ log BF_i
environment/identity +3.0 present / −0.4 absent
XTGETTCAP RGB reply ±4.6 (truecolor)
DECRPM ?2026 reply ±4.6 (synchronized output)
probe timeout −0.7
multiplexer detected −0.5
FTUI_* operator switch ±9.2 (saturates: no heuristic outvotes it)
P = 1 / (1 + exp(−log-odds)) → upgrade when P ≥ 0.8
In code: ftui_core::caps_probe::CapabilityLedger with weights, threshold $P \ge 0.8$, upgrade-only refinement (refine_from_ledgers), evidence event capability_decision per capability at startup, feature caps-probe (enabled by the showcase; consumers enable it on ftui-core), and the probe preconditions (currently: native backend, stdin is a TTY, color depth Ansi256 for the truecolor probe; G05 extends to DECRPM 2026 on all non-mux terminals).
| Constant | Value | Description |
|---|---|---|
ENV_POSITIVE |
+3.0 |
Environment variable explicitly indicates support (e.g. COLORTERM=truecolor) |
ENV_ABSENT |
-0.4 |
Environment variable absent but not definitive |
DA2_KNOWN_TERMINAL |
+1.8 |
DA2 terminal type matches known-good terminal |
DA1_CONFIRMED |
+3.5 |
DA1 attribute code confirms feature (e.g. Sixel) |
DECRPM_CONFIRMED |
+4.6 |
DECRPM confirms mode is recognized (status 1–4) |
DECRPM_DENIED |
-4.6 |
DECRPM denies mode (status 0) |
TIMEOUT |
-0.7 |
Probe timed out — weak negative evidence |
MUX_PENALTY |
-0.5 |
Multiplexer detected — slight negative for passthrough features |
The ledger is upgrade-only: a capability the environment or the allowlist already granted is never removed by a negative or absent reply (terminfo under-reports truecolor over ssh; the allowlist knows terminals that ignore DECRPM). The startup probe sends only the two bounded queries above (300 ms, fail-open, FTUI_CAPS_PROBE=0 disables it); DA1/DA2 weights exist for the asynchronous CapabilityProber used by the showcase's capability screen. Every session writes one capability_decision evidence row per capability (truecolor, synchronized output, scroll region) carrying exactly the rows that decided.
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|
Where it runs (default path): TerminalWriter defaults to certified_skips: true. Under DiffStrategy::DirtyRows, evaluate_render_certificate_for_buffers verifies in a single pass that new's dirty state was cleared against old's mutation generation and that dirty_rows and dirty_spans agree, then BufferDiff::compute_certified_into walks each dirty row's DirtySpanRow directly (scan_row_changes_spans). Measured in docs/perf/certified_vs_dirty_scan_2026-10-14.md: spinner_tick p50 68 ns (80×24), 126 ns (200×60), 193 ns (300×100); overmarked_chrome (widgets redrawing border/header/status chrome while 4 cells change) 166 ns (80×24) and 536 ns (300×100) — 4.7× to 16.2× faster than whole-row slice scanning.
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)
Where it runs: BufferDiff::compute_dirty_into (used when certified_skips: false, or when calling BufferDiff::compute_dirty directly). The SAT is queried per tile row (one subtraction) to skip whole rows of clean tiles before per-tile checks; tiles engage at $\ge 12,000$ cells (200×60 by default; diff/sparse_5pct_rows/200x60 p50 28 µs → 21 µs in docs/perf/sat_tile_skip_2026-09.md). On the default certified_skips: true path (compute_certified_into), the renderer skips clean rows via dirty_rows and scans dirty spans directly without building the whole-screen SAT, which is 1.8×–10.8× faster at 200×60 and 300×100 (docs/perf/certified_vs_dirty_scan_2026-10-14.md).
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|.
Where it runs (crates/ftui-widgets/src/virtualized.rs, crates/ftui-widgets/src/height_predictor.rs, crates/ftui-widgets/src/fenwick.rs):
- Widget (
VirtualizedList): Opt in withVirtualizedList::new(&items).variable_heights()andVirtualizedListState::variable(default_height).with_predictor(PredictorConfig::default()).with_remeasure_policy(RemeasurePolicy::default()). Each item supplies its rendered height (RenderItem::height) and category (RenderItem::category); as visible items render, their heights are recorded in the state'sFenwickHeightTracker(or updated explicitly viaVirtualizedListState::measure), unmeasured items pre-allocate their category's posterior mean (HeightPredictor), andRemeasurePolicyschedules Beta-VOI remeasurement checks that emitvoi_sampleevidence (source: "virtualized_list") viaFrame::request_remeasure. - Container (
Virtualized<T>):Virtualized::with_variable_heights(default_height)selectsFenwickHeightTrackeras the default variable-height tracker (with_variable_heights_fenwicktakes an explicit capacity;ItemHeight::Variable(HeightCache)is the legacy linear-scan cache), followingpush,trim_front,clear, andset_external_len. Attach the predictor with.with_height_prediction(PredictorConfig)(measure(idx, height, category)updates both the Fenwick tree and category posterior) and VOI remeasurement with.with_remeasure_policy(RemeasurePolicy::default()). - Measured scroll-jump improvement: On a 100k-row 4-category heavy-tail corpus (
docs/perf/virtualized_scroll_jump_2026-09.md, measured 2026-10-16),Virtualized::scroll_toruns in 16.63 ns (virtualized_scroll_to_100k), and cumulative scroll correction across 50 viewport jumps dropped from 48,250 cells with a fixed default of1(27,896 cells with global mean2) to 2,497 cells with per-category Bayesian height prediction (a 94.8% reduction vs default1and 91.0% vs global mean2). - Demo screens: Three showcase screens use Fenwick variable-height virtualization in production:
widget_gallery(.variable_heights()),virtualized_search(VirtualizedList::new(&items).variable_heights()withVirtualizedListState::variable(1).with_predictor(PredictorConfig::default()).with_remeasure_policy(..)and multi-line previews toggled byp), andlog_search(LogViewerswitches itsVirtualizedstorage to Fenwick variable heights when line wrapping is toggled withw, tracking wrapped visual rows per log line).
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)
The delays those regimes select, and the two numbers most easily confused with them:
| Value | Where | |
|---|---|---|
| Steady coalescing delay | 16 ms | CoalescerConfig::steady_delay_ms |
| Burst coalescing delay | 40 ms | CoalescerConfig::burst_delay_ms |
| Hard deadline | 100 ms | CoalescerConfig::hard_deadline_ms |
| Steady observation mean μ_steady | 200 ms | BocpdConfig::mu_steady_ms |
| Burst observation mean μ_burst | 20 ms | BocpdConfig::mu_burst_ms |
The first three are how long a resize is held; the last two are how far apart resizes are expected to arrive in each regime, and are what the exponential observation model above is written in terms of. An earlier version of this section reported 200 ms and 20 ms as the coalescing delays, which is the one confusion this table exists to prevent. The hard deadline outranks both: a pending resize is applied at 100 ms whatever the posterior thinks, so a drag cannot be coalesced indefinitely.
default_config_matches_readme_constants (bocpd.rs) and
steady_regime_delay_is_16ms_and_burst_is_40ms (resize_coalescer.rs) fail if
any number above stops matching the code.
Does it beat the rate heuristic it replaced? Measured 2026-09-19: no. Both
detectors were driven over identical resize-storm schedules on a virtual clock
(docs/perf/resize_differential_2026-09.md):
| Pattern | repaints during drag (heuristic → BOCPD) | final apply ms |
|---|---|---|
burst_50 |
6 → 7 | 33 → 49 |
burst_200 |
26 → 27 | 24 → 0 |
sweep_80x24_to_200x60 |
10 → 12 | 40 → 24 |
oscillate_10 |
4 → 7 | 52 → 52 |
mixed_100 |
25 → 33 | 45 → 45 |
pathological_50 |
20 → 22 | 51 → 19 |
BOCPD draws more repaints during the drag on every pattern, and both detectors
land outside the 40 ms settling budget on three of six, so it is worse on one
criterion and no better on the other. It is not the transitional-band
interpolation: committing to the 40 ms burst hold there left every frame
count unchanged. The traces put the extra frames at burst onset and in pauses,
as unforced 0–18 ms applies made while the posterior still says Steady. The
heuristic, by contrast, holds every drag frame to the 100 ms deadline. The
observation model is why the posterior lingers: with μ_steady = 200 ms and
μ_burst = 20 ms, a 30–60 ms gap is nearly equally likely under both (at 50 ms,
0.0041 vs 0.0039), and these storms are full of such gaps (bd-i25qn).
That decision was made on 2026-09-23: the default went back to
enable_bocpd = false, which is the rule the plan set for this outcome
(bd-h8l3d). The rate heuristic ships. Use
CoalescerConfig::default().with_bocpd() to opt the posterior back in;
everything below describes that mode.
Where it runs: opt-in. CoalescerConfig::default() carries enable_bocpd = false and heuristic_fallback = true, so the rate heuristic is the detector until with_bocpd() turns the posterior on. With it on, ResizeCoalescer feeds every resize event's inter‑arrival to the posterior and reads the regime and the recommended delay from it. The 10/5 events‑per‑second rate heuristic decides only when the posterior is undefined: the first event of a session, an inter‑arrival outside [min_observation_ms, max_observation_ms] (1 ms to 10 s by default, which the posterior would otherwise see clamped), or a non‑finite posterior. While the heuristic decides it also owns the Burst exit (cooldown on ticks, rate check on the immediate path). The posterior itself only moves on events, so in BOCPD mode a Burst regime returns to Steady on a frame tick once the silence reaches mu_steady_ms (200 ms; reason code bocpd_idle_exit, confidence 1 − exp(−idle/μ_burst)). Every decision and regime_transition evidence row carries detector (bocpd or heuristic) and p_burst, the config row carries both flags, budget_decision carries resize_detector, and CoalescerStats::detector_decisions counts decisions per detector. CoalescerConfig::without_bocpd() returns to the heuristic alone; with_heuristic_fallback(false) hands even the first event to the posterior.
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
Inline-auto height remeasurement and variable-height virtualized list remeasurement use VOI analysis to decide when to take another height measurement:
Beta posterior over violation probability:
p ~ Beta(α, β)
VOI computation:
n = α + β
p_hat = α / n
variance_before = αβ / (n² × (n+1))
variance_if_violation = (α+1)β / ((n+1)² × (n+2))
variance_if_no_violation = α(β+1) / ((n+1)² × (n+2))
expected_after = p_hat × variance_if_violation
+ (1-p_hat) × variance_if_no_violation
VOI = variance_before - expected_after
= αβ / (n² × (n+1)²)
Decision:
score = VOI × value_scale × (1 + boundary_weight × boundary_score)
forced = an enabled maximum time/event interval has been reached
blocked = after the first sample, an enabled minimum interval is unmet
sample iff forced OR (NOT blocked AND score ≥ sample_cost)
boundary_score measures proximity to the sampler's e-value threshold. Initial
height measurement runs whenever the runtime has no height estimate, independently
of this sampling decision.
VOI configuration defaults across the three consumers:
| Config | Where | prior_alpha / prior_beta |
sample_cost |
Interval gating |
|---|---|---|---|---|
InlineAutoRemeasureConfig::default() |
crates/ftui-runtime/src/program.rs:4623 |
1.0 / 9.0 (10% violation prior) |
0.08 |
min_interval_ms = 100, max_interval_ms = 1000, max_interval_events = 0 |
VoiConfig::default() |
crates/ftui-runtime/src/voi_sampling.rs:220 |
1.0 / 1.0 (uniform prior) |
0.01 |
min_interval_ms = 0, max_interval_ms = 250, max_interval_events = 20 |
RemeasurePolicy::default() |
crates/ftui-widgets/src/virtualized.rs:73 |
1.0 / 9.0 (BetaPosterior::new(1.0, 9.0)) |
0.08 |
min_interval_frames = 6 |
InlineAutoRemeasureConfig::default() relies on forced intervals: since n ≥ 10 and boundary_score ≤ 1,
the VOI score is at most 1/242 ≈ 0.00413, below sample_cost = 0.08. Standalone VoiConfig::default()
uses a permissive Beta(1, 1) prior and sample_cost = 0.01 that actively samples between forced intervals.
In variable-height lists (RemeasurePolicy), observing an interval violation updates BetaPosterior and triggers a sample once min_interval_frames has elapsed (or whenever beta_voi(α, β) ≥ sample_cost). Both the inline-auto sampler and VirtualizedList emit structured voi_sample JSONL evidence records carrying source: "inline_auto" | "virtualized_list", widget_id, index, alpha, beta, voi, sample_cost, and decision: "sample" | "skip".
E-Process: Anytime-Valid Testing
Several monitors accumulate multiplicative e-values (sequential test wealth processes):
Sub-Gaussian exponential form (ftui_render::budget::EProcessState, conformal_alert):
E_t = E_{t-1} × exp(λ_{t-1} · r_t − λ_{t-1}² · σ₀² / 2)
Bernoulli wealth form (experimental ftui_runtime::eprocess_throttle, voi_sampling):
W_t = W_{t-1} × (1 + λ_t · (X_t − μ₀))
Ville's inequality (when E[e_t | F_{t-1}] ≤ 1 with predictable λ_{t-1} and no lower-floor bias):
P(∃t: E_t ≥ 1/α | H₀) ≤ α at any stopping time
Production vs. formal supermartingale distinction:
- Render-path budget gate (
ftui_render::budget::EProcessState) runs predictable Gaussian GRAPA over an EMA plug-in scale: By default (EProcessConfig::default():adaptive_lambda = true,grapa_eta = 0.1,lambda_min = 0.05,lambda_max = 2.0, initiallambda = 0.5), each frame computes $E_t = E_{t-1}\exp(\lambda_{t-1} r_t - \lambda_{t-1}^2 / 2)$ using the $\mathcal{F}{t-1}$-measurable betting fraction $\lambda{t-1}$ and then updates $\lambda_t = \mathrm{clamp}(\lambda_{t-1} + \eta(r_t - \lambda_{t-1}), \lambda_{\min}, \lambda_{\max})$ after warmup (holding $\lambda_t \ge \lambda_0$ while draining post-burst overload wealth $E_t > 1$ on recovery frames $r_t < 0$). When fed standardized zero-mean unit-variance Gaussian residuals directly, the predictable GRAPA bet preserves the exact supermartingale property $\mathbb{E}[E_t \mid \mathcal{F}{t-1}] = E{t-1}$ under $H_0$. On live frame times, residuals are standardized by an EMA of mean absolute deviation (σ̂_MAD ≈ 0.8σfor Gaussian noise, floored atsigma_floor_ms = 1.0) andE_tis clamped to[0.01, 1e10], soalpha = 0.05acts as a fail-safe sensitivity calibration that errs toward earlier degradation rather than a formal finite-sample false-positive bound. - Other adaptive $\lambda_t$ (GRAPA) implementations:
ftui_runtime::eprocess_throttle(experimental) adapts $\lambda_t$ on the Bernoulli wealth process via $\lambda_{t+1} = \mathrm{clamp}(\lambda_t + \eta \frac{X_t - \mu_0}{1 + \lambda_t(X_t - \mu_0)})$.ftui_runtime::conformal_alert(experimental) adapts $\lambda_t$ on the sub-Gaussian exponential process via the matching log-wealth gradient $\lambda_{t+1} = \mathrm{clamp}(\lambda_t + \eta ((z_t - \mu_0) - \lambda_t \sigma_0^2), \epsilon, 1 - \epsilon)$.
Applications in FrankenTUI:
- Budget degradation decisions (
ftui_render::budget::BudgetControllerwith predictable Gaussian GRAPA) - Allocation leak alerts (
ftui_render::frame_guardrails::FrameGuardrailsviaAllocLeakDetector) - VOI boundary-proximity weighting (
ftui_runtime::voi_sampling, clamped[1e-12, 1e12]Bernoulli wealth) - Flake detection in tests (experimental
flake_detector) - Standalone throttle / conformal alert calibration (experimental
eprocess_throttle,conformal_alert)
Not the Mondrian conformal frame-time gate described below, which is the conformal path that is on by default: it calibrates from residual quantiles and carries no e-process.
Where it runs: ftui-render::budget (EProcessState with predictable Gaussian GRAPA on the default frame-budget path, emitted as eprocess_lambda in budget_decision evidence rows) and ftui-render::frame_guardrails (AllocLeakDetector on the default guardrail path); ftui-runtime::eprocess_throttle and ftui-runtime::conformal_alert are experimental and not constructed by Program or TerminalWriter.
Conformal Alerting
Status: experimental (see Experimental modules)
Where it runs: nowhere in production. This describes ftui-runtime's
conformal_alert, whose only consumers are other experimental modules
(timeline_aggregator, alpha_investing, resize_sla) and a proptest — a
quarantined cluster wired to itself, not to the runtime. The conformal path that
is on by default is the Mondrian frame-time gate above, which has no e-process
layer.
Budget and performance alerts in that module combine exchangeable conformal prediction with a sequential sub-Gaussian e-process:
Nonconformity score:
R_t = |observed_t - predicted_t|
Threshold (finite-sample guarantee when (1-α)(n+1) ≤ n):
q = quantile_{⌈(1-α)(n+1)⌉ / n}(R_1, ..., R_n)
Exchangeable coverage guarantee:
P(R_{n+1} ≤ q) ≥ 1 - α for exchangeable (R_1, ..., R_{n+1})
Sub-Gaussian e-process layer (with predictable λ_t updated by ∂ℓ_t/∂λ = (z_t - μ₀) - λ_t σ₀²):
e_t = exp(λ_t × (z_t - μ₀) - λ_t² σ₀² / 2)
Scope & assumptions: The conformal quantile requires exchangeability of calibration and test residuals (non-stationary drift requires recalibration or sliding windows); the combined OR trigger (conformal_alert || eprocess_alert) with empirical $(\hat{\mu}, \hat{\sigma})$ standardization and post-alert resets is a hybrid detector rather than a single-threshold α-test.
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.
Where it runs: on by default (ProgramConfig::default() carries ConformalConfig::default(): α = 0.05, min_samples = 20, window 256, q_default = 10 ms). Every frame the runtime predicts ŷ_t^+ for its bucket before rendering and, when the bound exceeds the frame budget, steps the render degradation level down; the frame's measured time is fed back as the next residual. Warm-up rule: a verdict is only acted on once the level it rests on has at least min_samples residuals, so the q_default prior can never degrade a fresh program (it is still written to the budget_decision evidence row as risk with n_b < 20). ProgramConfig::without_conformal() turns the gate off; with_conformal_config(..) tunes it.
CUSUM Control Charts
Allocation budget tracking in FrameGuardrails via AllocLeakDetector 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.
Where it runs: on every rendered frame inside ftui_render::frame_guardrails::FrameGuardrails via ftui_render::alloc_budget::AllocLeakDetector (reset after soft memory trims and emitted as leak_e_value, leak_cusum_upper, leak_mean_bytes, and leak_alert in guardrail_snapshot evidence rows).
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.
Where it runs: ListState::default().with_hover_stabilizer(HoverStabilizerConfig::default()) routes the list's mouse-move hover through the stabilizer (default: 1-cell hysteresis band, drift allowance 0.5, threshold 2.0, 500 ms hold); without it hovered follows the raw hit test. The showcase's mouse playground uses the same type directly. TableState::hovered tracks raw mouse-move row hits (Table renders TableTheme.row_hover when set) without routing through HoverStabilizer yet.
Gesture Recognition State Machine
The GestureRecognizer in ftui-core transforms raw terminal events into semantic events via a multi-phase state machine:
Raw Events Semantic Events
───────── ───────────────
MouseDown(x,y) ─┬─ idle ──→ Click
MouseDown(x,y) │ DoubleClick
MouseDown(x,y) ─┤ TripleClick (select word / line)
MouseMove(x,y) ─┤─ armed ─→ DragStart
MouseMove(x,y) ─┤ DragMove
MouseUp(x,y) ─┤─ drag ──→ DragEnd
│
Key(a) ─┤ Chord (multi-key sequences)
Key(Ctrl+x) ─┘ ModifiedKey
Dead zone: drag is only recognized after the pointer moves beyond a configurable threshold (GestureConfig::drag_threshold, default: 3 cells of Manhattan distance), preventing accidental drags from jittery mice.
Multi-click timing: double/triple clicks use a configurable interval window (multi_click_timeout, default: 300 ms; click_tolerance 1 cell) with a click_count counter that resets on timeout or position change. A stationary press becomes a LongPress after long_press_threshold (default: 500 ms).
Chord recognition: multi-key sequences like g g (vim-style) use Chord and KeyDispatcher with a configurable chord timeout (default: 1,000 ms), enabling complex keybinding schemes without blocking single-key shortcuts.
Where it runs: opt in with ProgramConfig::default().with_gestures(GestureConfig::default()) and implement Model::on_gesture(&mut self, SemanticEvent) -> Cmd<Msg>. The runtime feeds every input event through the recognizer, then hands the raw event to the ordinary update() call (raw events are never swallowed), then delivers each recognized gesture to on_gesture. Long presses are checked on every loop iteration and the loop wakes at the long-press deadline, so they fire without a Cmd::tick rate. Mouse gestures need mouse capture enabled.
TextArea handles the mouse itself with the same thresholds, so a host only forwards events through handle_event. A left press places the cursor, a double click selects the word under it (Unicode word boundaries), a triple click selects the line, and dragging extends the selection. Presses outside the area it last rendered are ignored, and so is a drag that started outside it. The showcase's forms, advanced text editor and live Markdown screens forward their mouse events to it.
Input Parser
The InputParser in ftui-core handles the full complexity of terminal input encoding:
- ANSI escape sequences: CSI, SS3, OSC, and DCS (captured via
TerminalResponse::Dcs, bounded at 8 KiB) with timeout-based ESC disambiguation; APC/SOS/PM are treated as Alt-modified keys unlessInputParser::set_capture_apc(true)opts intoTerminalResponse::Apccapture - Kitty keyboard protocol: repeat/release events, modifier encoding, functional key disambiguation
- Bracketed paste: captures pasted text as a single
Pasteevent, preventing paste injection attacks - Mouse protocols: X10, SGR (
1006), legacy numeric fallback (1015), and SGR-Pixels (1016, viaInputParser::set_pixel_mouse(true)andMouseEvent::pixel) with pixel-to-cell conversion from the terminal's reported cell size (CSI 6 ; height ; width t/InputParser::set_cell_size_px); the active protocol is selected by the session (SessionOptions::pixel_mouse/ProgramConfig::with_pixel_mouse), not sniffed - UTF-8 streaming: multi-byte character assembly across partial reads
- Ambiguous prefix handling:
ESCalone vsESC [(Alt+key vs CSI) resolved by timing
Keybinding System
The Keybinding module supports:
- Declarative binding maps (
KeyMap,Binding) with priority levels (Priority::{Global, Mode, Widget}) - Chord sequences (
Chord:g g,Ctrl+x Ctrl+s) with configurable timeout (1,000 ms default, clamped to 200..=5,000 ms) - Context-sensitive activation (
ContextId): bindings active only in specific modes/focus states - Conflict detection (
KeyMap::conflicts()): warns when bindings shadow, duplicate, or prefix-collide with each other - Serialization (
KeyMap::to_toml/from_tomlandto_json/from_jsonunderftui-core/ftuifeatureserde):KeyMap<A>serializes as a file with chords as text, contexts by name andchord_timeout_ms, sotoml::from_str::<KeyMap<Msg>>(&text)reads a hand-edited keymap and a bad chord is reported with its binding index
let mut map = new;
let editor = map.context;
map.bind;
map.bind_in;
Where it runs: ftui_core::keybinding::{KeyCombo, Chord, KeyMap, KeyDispatcher, Priority, ContextId} (also in ftui::prelude). KeyMap::bind(Chord::parse("g g")?, Msg::GoTop) and bind_in(chord, action, Priority::Widget, Some(ctx)) declare bindings; KeyMap::conflicts() returns the shadow/prefix/duplicate report with one warning line per item; KeyDispatcher::feed(&key_event, now) and tick(now) return Dispatch::{Action, Pending, Expired, Unbound, Esc}. Resolution order: an active-context binding beats a context-free one, then higher priority, then the most recent binding. A key that is both bound alone and a chord prefix (g with g g) waits for the chord timeout (1,000 ms default, 200 ms to 5,000 ms) or a non-extending key, then fires; single-key shortcuts are never swallowed. Esc and Esc Esc go through the same 250 ms SequenceDetector window the rest of the runtime uses; a key typed inside that window resolves the lone Esc first, in the same feed call, then is dispatched itself (ActionMapper::map likewise returns the Esc's action, then the key's). The pane keyboard controller (ftui_runtime::pane_keymap) is routed through a KeyMap: pane_keymap() builds it from one binding table, PaneKeyboardController::handle_key resolves keys against it (with_keymap swaps in a host map), and pane_keyboard_hints() is generated from the same table, so hints and behaviour cannot drift. The showcase's global keys (?, q, Ctrl+C, Tab/Shift+Tab, /, Ctrl+K, ...) and screen chords (g g in LogSearch, Ctrl+x Ctrl+s in AdvancedTextEditor) also dispatch through KeyMap and KeyDispatcher, and Help::from_keymap / KeybindingHints::from_keymap render directly from KeyMap::entries_for_help (in LogSearch, scrolling to the top uses the g g chord rather than a single g).
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.
Where it runs: standalone library in ftui_core::animation::Spring (exercised by crates/ftui-core/tests/animation_test.rs; no widget or showcase screen drives ftui_core::animation in production today).
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.
Where it runs: standalone library in ftui_core::animation (EasingFn, StaggerMode, stagger_offsets, stagger_offsets_with_jitter; exercised by crates/ftui-core/tests/animation_test.rs, with no production widget or showcase caller).
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.
Where it runs: standalone library in ftui_core::animation::Pulse (exercised by crates/ftui-core/tests/animation_test.rs, with no production widget or showcase caller).
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 >= 50ms OR resize_dominance >= 3 OR F < 0.8:
defer_pending_resize() // Program::process_resize_coalescer yields to input
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
“error: the option -Z is only accepted on the nightly compiler”
This error means a stable compiler is building the checkout, which needs the
dated nightly pinned in rust-toolchain.toml. Run this inside the checkout:
- If it names stable because of a
RUSTUP_TOOLCHAINvariable or a directory override, that setting outranks the pin. Unset it, or runcargo +nightly-YYYY-MM-DD ...with the pinned date. - If
rustupis not installed, yourcargocomes from a system package that ignoresrust-toolchain.toml. Install Rust through rustup.
Installing the latest nightly does not help, because the pin names a
specific date. If the pinned nightly is merely missing, rustup says so (rather
than printing this error); run rustup toolchain install in the checkout.
“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
FTUI_DEMO_MOUSE=on
For tmux, enable mouse forwarding with set -g mouse on in your tmux configuration.
“Ctrl-Z does nothing” / suspending with kill -TSTP
On both backends, native and crossterm, kill -TSTP (and SIGTTIN/SIGTTOU)
hands the terminal back before the process stops: input modes off, alternate screen left, cooked
mode restored, so the shell works. After fg, the program re-arms raw mode and
repaints the whole screen. ProgramConfig::with_job_control(false) turns this
off.
Ctrl-Z is not a suspend key by default: raw mode delivers it as an ordinary key
event, and it is undo in TextArea and the showcase editors. Opt in with
ProgramConfig::default().with_ctrl_z_suspend(true). Design and limits:
docs/spec/suspend-resume.md.
“output flickers”
Inline mode uses synchronized output where supported: allowlisted terminals get
it immediately and any terminal that answers the DECRPM 2026 probe gets it at
startup. Inside tmux/screen/zellij and under WezTerm identities it is off by
policy. If you know your terminal handles CSI ? 2026 h/l correctly, set
FTUI_SYNC_OUTPUT=1 (and FTUI_SCROLL_REGION=1 for the inline scroll-region
strategy); set them to 0 to force the conservative path.
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.
- No SSH or remote-session extra: The plan once listed one; it was dropped on 2026-09-01 (see
docs/planning/reality-check-2026-09-01.mdG38). Run the remote side over your own transport and stream it throughProcessSubscription.
Known Limitations
| Capability | Current State | Planned |
|---|---|---|
| Stable API | ❌ Not yet | Yes (post‑v1) |
| Widget ecosystem | ✅ 70 direct widget implementations (55 types; 93 workspace-wide) | Expanding |
| Formal compatibility matrix | ⚠️ In progress | Yes |
| Asupersync execution lane | ✅ Blocking task pool with ftui-runtime/asupersync-executor; otherwise falls back to Structured |
Structured subscription cancellation retained |
| crates.io publishing | ✅ 17 of 20 crates (all libraries) | Showcase targets stay workspace-local |
FAQ
Why “FrankenTUI”?
A modular kernel assembled from focused, composable parts. A deliberate, engineered “monster.”
Is this a full framework?
It’s a kernel plus a large widget library plus a demo showcase with 45 screens plus a full pane workspace system. You can build a framework on top, but expect APIs to evolve.
Does it work on Windows?
Yes, with documented v1 limitations: on Windows, the ftui facade selects the Crossterm backend (crossterm-compat) by default (ftui-tty is Unix-only and returns Unsupported on non-Unix targets). Windows Terminal and ConHost are supported for raw-mode lifecycle, key/mouse/resize events, and 16/256/TrueColor output (DEC 2026 synchronized output and Kitty keyboard protocol are disabled on Windows). DSR frankentui-windows-cross validates --target x86_64-pc-windows-gnu workspace Clippy (-D warnings), example builds, and cross-platform capability/input/simulator tests; see docs/WINDOWS.md, docs/adr/ADR-004-windows-v1-scope.md, and docs/spec/frankenterm-architecture.md (Section 13.5).
Can I embed it in an existing CLI tool?
Yes. Inline mode is designed for CLI + UI coexistence.
Can it run in a browser?
Yes, reproducibly from this repository: run bash build-wasm.sh /absolute/new-browser-build && python3 -m http.server --directory /absolute/new-browser-build/site 8080 to build and serve the complete showcase bundle (or mount ShowcaseRunner directly in the lightweight in-tree DOM <pre> text host crates/ftui-showcase-wasm/sdk/showcase-host.js). ftui-web provides the deterministic, host-driven WASM backend and ftui-showcase-wasm exports ShowcaseRunner.
How do I update snapshot tests?
BLESS=1
How many lines of code is it?
1,110,000+ lines of Rust across 20 crates, with 70 direct widget implementations across 55 widget types in ftui-widgets (93 workspace-wide), 45 demo screens, and a broad PTY/scripted E2E surface.
What's the performance like?
The 16‑byte cell design puts 4 cells per cache line. On an 80×24 grid at 5% change (opt-level = "z"), the full diff + present pipeline runs in 17.74 µs (emitting 169 B of ANSI against an 832 B budget), certified diff takes 90.7 ns on a spinner tick at 120×40 (52.9 Gcells/s), InputParser::parse takes 152 ns/event, S3-FIFO cached grapheme width lookup takes 25.6 ns, and FrameArena reduces steady-state heap allocations to 0 allocs/frame on an 80×24 ASCII dashboard (3 allocs/frame / 42 B on Unicode, down 99.5% from 661 allocs). All 27 SLO thresholds in tests/baseline.json are enforced by ./scripts/perf_regression_gate.sh; see docs/perf/baseline_2026-10-19.md.
How does the rollout system work?
The runtime supports three execution lanes (Legacy, Structured, Asupersync) with a shadow‑run comparison system that proves determinism before enabling a new lane. The RolloutScorecard combines shadow evidence with benchmark results into a machine‑readable go/no‑go verdict. See the "Runtime Migration & Rollout Infrastructure" section above.
Key Docs
docs/planning/reality-check-2026-09-01.md— evidence-backed codebase audit and gap trackerdocs/claims-ledger.md— machine-checked claims and vision proof ledgerdocs/perf/README.md— performance baseline & differential benchmark index (docs/perf/baseline_2026-10-19.md)docs/main-todo-bead-map.md— plan A–K execution tracker (generated byscripts/render_todo_bead_map.py)docs/reports/deep-codebase-review-final.md— historical review report (superseded bydocs/planning/reality-check-2026-09-01.md)docs/ACCESSIBILITY.md— accessibility tree / proxy notes (relocated from repo root)docs/planning/UPGRADE_LOG.md— upgrade history (relocated from repo root)docs/operational-playbook.mddocs/risk-register.mddocs/glossary.mddocs/adr/README.mddocs/concepts/screen-modes.mddocs/spec/state-machines.mddocs/spec/frankenterm-correctness.mddocs/telemetry.mddocs/spec/telemetry.mddocs/spec/telemetry-events.mddocs/testing/coverage-matrix.mddocs/testing/coverage-playbook.mddocs/one-writer-rule.mddocs/ansi-reference.mddocs/WINDOWS.mddocs/testing/e2e-playbook.md
Pane workspace:
docs/guides/pane-101.md— getting started with panesdocs/guides/pane-showcase-scenarios.md— demo scenarios + regression-test mapdocs/cookbook/panes.md— task-oriented pane recipesdocs/api/pane-stability-contract.md— supported surface, schema versions, deprecation policydocs/migration/flex-to-pane-and-versioning.md— Flex/Grid → panes + persisted-workspace versioningdocs/spec/pane-parity-contract-and-program.md— terminal/web parity guaranteedocs/pane-release-gate-policy.md— go/no-go release gate clauses + staged rolloutdocs/pane-operational-runbook.md— incident response + emergency rollback
E-Graph Layout Optimizer
The layout engine includes an equality saturation optimizer (ftui-layout/src/egraph.rs) that finds optimal constraint solutions through algebraic rewriting:
Expression Language:
Expr ::= Num(u16) -- concrete pixel value
| Var(NodeId) -- widget reference
| Add(Expr, Expr) -- constraint arithmetic
| Sub(Expr, Expr)
| Max(Expr, Expr) -- competing constraints
| Min(Expr, Expr) -- bounded constraints
Rewrite Rules (equality saturation):
Add(a, Num(0)) → a -- identity
Add(Num(x), Num(y)) → Num(x + y) -- constant folding
Max(a, a) → a -- idempotence
Add(a, b) = Add(b, a) -- commutativity
...plus ~20 more domain-specific rules
How it works: rather than applying rewrites greedily (which can miss global optima), the e-graph compactly represents all equivalent forms simultaneously. After saturation, the cheapest expression is extracted using a cost model that penalizes deep nesting and prefers constant propagation.
Where it runs: nowhere on the layout path, by measurement. ftui_layout::egraph::solve_layout is a complete, tested alternative solver, but Flex/Grid do not call it and should not: benchmarked against Flex::split over the same constraint sets it is 4x to 19x slower — 233 ns vs 1.99 µs for a typical three-way split, and 5.2 µs vs 99.8 µs for a pathological 200-constraint layout (cargo bench -p ftui-layout --bench layout_bench -- layout/egraph, numbers in docs/perf/egraph_vs_flex_2026-09-18.md).
Equality saturation buys a globally optimal expression, and for this problem that optimum is not worth its price: the constraint counts a terminal layout produces are small enough that the direct solver wins outright. The module stays because the saturation engine is a sound piece of work and the comparison is worth keeping honest, not because it is on a path to being switched on.
Text Engine
The ftui-text crate provides a full text processing stack:
Rope-Backed Storage
Large text buffers (e.g., the advanced text editor demo) use a rope data structure for efficient editing:
Rope (balanced tree of chunks):
┌──────┐
│ Node │ ← weight = total chars in left subtree
├──┬───┤
│ │ │
┌┴┐ ┌┴┐
│A│ │B│ ← leaf chunks (typically 512–2048 chars)
└─┘ └─┘
Insert at position i: O(log n) — split + rebalance
Delete range [i,j): O(log n) — split + drop + rebalance
Index by position: O(log n) — walk tree using weights
Why rope? For a 100K-line log viewer, inserting at the cursor is O(log n) vs O(n) for a flat String. The rope also enables efficient line-index lookups and range extraction.
Text Editor Core
The ftui_text::Editor provides:
- Cursor model with visual position (column) vs byte offset tracking
- Selection with anchor/head semantics (Shift+Arrow;
TextAreamouse input does not extend a selection with Shift+Click) - Word movement through
move_word_left()/move_word_right(), with Unicode word-boundary detection; paragraph movement throughmove_paragraph_up()/move_paragraph_down(), landing on separating blank lines. - Grouped undo/redo joins adjacent typing runs. A new word after whitespace, a change in deletion direction, navigation, paste, or
break_undo_group()starts a separate group.set_coalesce_idle()configures the idle interval (500 ms by default); callers supply monotonic milliseconds throughEditor::tick(), so the editor does not read a wall clock itself. - Native clipboard commands through
Cmd::set_clipboard(text)/Cmd::get_clipboard(): the runtime writes OSC 52 throughTerminalWriter, and terminal replies arrive asEvent::Clipboard. The encoded payload limit is 74,994 base64 bytes (at most 56,244 input bytes).
Clipboard output follows terminal capability policy. Multiplexer sessions default
to disabled; FTUI_OSC52_CLIPBOARD=1 explicitly enables output while preserving
tmux/screen wrapping, and FTUI_OSC52_CLIPBOARD=0 disables it. The terminal and
multiplexer must also permit clipboard access and passthrough. A query does not
guarantee a reply. Browser clipboard access requires host JavaScript integration;
native OSC 52 commands do not grant browser clipboard permissions.
BiDi & Shaping
- BiDi (
bidi.rs): Unicode Bidirectional Algorithm for mixed LTR/RTL text (featurebidi, used byParagraphrendering and the opt-inCursorNavigator::with_visual_bidicaret mode) - Shaping (
shaping.rs): standalone script/run segmentation and ligature/fallback helpers inftui-text(not invoked by the default widget render path) - Normalization (
normalization.rs): opt-in NFC/NFD/NFKC/NFKD Unicode normalization helpers (featurenormalizationinftui-text)
Width Calculation
Every width in the render path goes through ftui_core::text_width. Printable
ASCII strings and graphemes are answered inline (ascii_width, SIMD-accelerated
when simd is enabled); in grapheme_width and display_width, every
non-ASCII grapheme cluster (<= 128 bytes) is looked up in a per-thread
S3-FIFO cache in front of the Unicode width tables (unicode-display-width,
unicode-width, VS16 stripping, zero-width scans), while char_width (single
scalar) and grapheme_width_with_cjk (explicit caller-chosen CJK policy)
compute directly without caching:
display_width(text) / grapheme_width(cluster)
ASCII? → byte length, no cache
cache hit → width (S3-FIFO, 4096 entries, keyed by a 64-bit hash)
miss → Unicode tables, then insert
Width Embedding:
GraphemeId packs the display width (4 bits) next to the pool slot, so cells
never consult the pool for width
S3-FIFO is scan-resistant: a stream of one-off emoji in a log viewer cannot
evict the hot CJK labels of the table above it. FTUI_WIDTH_CACHE=0 disables
the cache; text_width::width_cache_stats() reports hits and occupancy. The
W-TinyLFU and LRU caches in ftui-text are benchmark subjects only and are
not on the render path. Measured numbers (cached vs uncached, cold vs warm) are
in docs/perf/text_width_cache_2026-09-02.md.
Degradation Cascade
When frame rendering exceeds its time budget, FrankenTUI executes a principled degradation cascade that preserves correctness while shedding visual fidelity:
Mondrian Conformal Risk Gate (ConformalPredictor)
│ "frame upper bound ŷ_t^+ exceeds budget (after 20-sample bucket warmup)"
▼
Budget Controller (PID + E-Process Gate in ftui_render::budget)
│ computes control signal from normalized frame-time error (after 10-frame warmup)
▼
Degradation Level Selection
│ Full → SimpleBorders → NoStyling → EssentialOnly → Skeleton → SkipFrame
│ (default controller/conformal floor: SimpleBorders; deeper levels via floor config or guardrails)
▼
Per-Widget Degradation Shedding (frame.buffer.degradation)
│ 34 widget modules shed borders/styling/non-essential work according to the active level
▼
Evidence Emission
structured JSONL documenting every decision (budget_decision / guardrail_snapshot)
Key properties:
- Recoverable: when load drops, the cascade automatically restores visual fidelity
- Observable: every degradation event is logged with conformal prediction context
- Widget-aware: critical widgets (input fields, status bars) degrade last;
BudgetControllerConfig::default()setsdegradation_floor = DegradationLevel::SimpleBorders(honored by both the PID/e-process controller and the conformal risk gate) so routine frame-time spikes simplify borders without stripping styling or widgets unless a deeper floor is configured or hard memory/queueFrameGuardrailsintervene - Deterministic over frame-time traces:
BudgetController::update(frame_time)is a pure state machine — feeding the sameDurationsequence (viarecord_frame_timeorDeterministicClock) always produces the exact same degradation path (liveProgramruns feed measured wall-clockelapsed()durations)
Where it runs: on by default through ftui_render::budget::BudgetController + ftui_runtime::conformal_predictor::ConformalPredictor + Program (frame.set_degradation(..) and frame.buffer.degradation, checked by 34 widget modules). Do not confuse this production path with the standalone ftui_runtime::degradation_cascade (DegradationCascade) and ftui_runtime::conformal_frame_guard (ConformalFrameGuard) modules, which are quarantined under --features experimental with no production consumer.
Formal Cost Models
Status: experimental (see Experimental modules)
The cost_model module provides closed-form cost models for three subsystems:
Where it runs: nowhere. Nothing in any crate's src/ imports ftui_runtime::cost_model; the formulas below are a library you can call, not a model the runtime consults when sizing caches or scheduling. (ftui-render/src/presenter.rs has a private mod cost_model for ANSI cursor-move costs — same name, unrelated code.)
Cache Cost Model
Loss function:
L(h, m) = c_miss × (1 - h) + c_memory × m
Optimal cache size (LRU under Zipf workload):
m* = argmin_m { c_miss × (1 - h(m)) + c_memory × m }
where h(m) is the hit-rate function derived from the characteristic time approximation.
Pipeline Scheduling Model
M/G/1 queue model:
ρ = λ × E[S] -- utilization
W = (λ × E[S²]) / (2 × (1 - ρ)) -- Pollaczek-Khinchine waiting time
T = W + E[S] -- mean response time
Applies to: effect queue, render pipeline, subscription dispatch
Batching Cost Model
Batch-and-process cost:
C(b) = c_setup / b + c_per_item × b -- amortized setup vs holding cost
Optimal batch size:
b* = √(c_setup / c_per_item) -- square root law
Applies to: ANSI emission, change run coalescing, event drain bursts
Flake Detection & Sequential FDR Control
Anytime-Valid Flake Detector
Status: experimental (see Experimental modules)
The design is for E2E timing tests to use an e-process to detect flaky regressions without inflating false positives across the hundreds of frames tested:
Sub-Gaussian e-value:
e_t = exp(λ × r_t − λ²σ²/2)
Cumulative evidence:
E_t = ∏ᵢ eᵢ
Reject H₀ when E_t ≥ 1/α, valid at ANY stopping time.
Why this matters: traditional significance tests become unreliable when you check p-values after every frame (the "peeking problem"). E-processes eliminate this entirely.
Where it runs: nowhere. No E2E test uses flake_detector. Nothing in any crate's src/ imports it, and its only exercisers are a proptest over the module itself and the quarantine compile check. The detector is implemented and tested; nothing feeds it E2E timings.
Alpha-Investing (Sequential FDR Control)
Status: experimental (see Experimental modules)
When many monitors fire sequentially (budget alerts, degradation triggers, capability decisions), testing each at a fixed alpha inflates expected false discoveries. ftui_runtime::alpha_investing implements a multiplicative alpha-spending rule with partial refund:
Wealth process (as implemented in AlphaInvestor):
W₀ = initial_wealth (default 0.5)
Per-test (while W ≥ min_wealth):
αᵢ = clamp(investment_fraction × W, 0, W) -- default investment_fraction = 0.1
W ← W - αᵢ -- deduct αᵢ upfront
if pᵢ ≤ αᵢ (rejected):
W ← W + reward_fraction × αᵢ -- partial refund (default ψ = 0.5)
Guarantees under conditionally super-uniform null p-values (P(pᵢ ≤ αᵢ | Fᵢ₋₁) ≤ αᵢ):
Total alpha spent: Σ αᵢ ≤ W₀ / (1 - ψ)
Expected false discoveries: E[V] ≤ W₀ / (1 - ψ · α_max) ≤ W₀ / (1 - ψ)
Stabilized modified FDR: mFDR_η = E[V] / (E[R] + η) ≤ W₀ / (η · (1 - ψ · α_max))
(Note: Foster & Stine (2008) charge $\alpha_i / (1 - \alpha_i)$, grant an additive payout $\omega$ on rejection, and control the stabilized $\mathrm{mFDR}_\eta = E[V]/(E[R]+\eta)$ with $\eta > 0$; AlphaInvestor::discovery_rate() reports the raw rejection rate $R / m$, not $\mathrm{FDP} = V / \max(R, 1)$.)
Where it runs: nowhere. Nothing in any crate's src/ imports ftui_runtime::alpha_investing, so the one monitor that is on by default — the Mondrian conformal frame-time gate — does not spend from a shared alpha budget. BOCPD would have been the second, but it is opt-in as of 2026-09-23 (bd-h8l3d). One monitor, not dozens, which is why this has not bitten; the accounting exists for a future where it would.
Rough-Path Signatures
Status: experimental (see Experimental modules)
The rough_path module implements truncated rough-path signatures for piecewise-linear sequential traces:
Given a d-dimensional path X: [0,T] → ℝᵈ, the signature is:
S(X)^{i₁,...,iₖ} = ∫₀<t₁<...<tₖ<T dX^{i₁}_{t₁} ⊗ ... ⊗ dX^{iₖ}_{tₖ}
Piecewise-linear increment Δx_t = x_{t+1} - x_t via Chen's identity:
S(X_{[0,t+1]}) = S(X_{[0,t]}) ⊗ exp(Δx_t), exp(Δx_t) = Σ_{m=0}^K Δx_t^{⊗m} / m!
Truncated at depth K:
S_K(X) = (1, S¹(X), S²(X), ..., Sᴷ(X)) with Σ_{k=1}^K d^k terms
Properties & scope:
- Reparametrization & subdivision invariance: Using the segment tensor exponential $\exp(\Delta x_t)$ in Chen's identity makes $S_K(X)$ invariant under monotone time reparametrization and arbitrary subdivision of linear segments.
- Tree-like equivalence vs. finite truncation: The full infinite signature ($K = \infty$) characterizes continuous bounded-variation paths up to tree-like equivalence (Hambly & Lyons, 2010; retraced segments cancel). A truncated signature at depth $K < \infty$ is a finite-dimensional projection and does not uniquely separate all non-tree-equivalent paths.
- Incremental complexity: Chen's identity updates the depth-$K$ signature in $O(K \cdot dK)$ time per step ($O(n \cdot K \cdot dK)$ across $n$ observations).
Intended applications in FrankenTUI — none of these are wired; no crate imports ftui_runtime::rough_path:
- Workload characterization: time-augmented
(t, frame_ms)series → signature → anomaly detection - Trace comparison: compare two execution traces without aligning timestamps
- Regression detection: signature distance between baseline and candidate runs
Where it runs: nowhere. The signature computation is implemented and unit/property-tested; nothing feeds it a frame time series.
Core Algorithms & Data Structures
FrankenTUI is 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.
Where it runs: opt-in via CoalescerConfig::default().with_bocpd() in ftui_runtime::resize_coalescer (enable_bocpd = false by default so the rate heuristic runs unless opted in; see BOCPD: Online Change-Point Detection).
Run‑Length Posterior + Hazard Function (BOCPD Core)
BOCPD’s main state is the run‑length posterior, which tracks 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.
Where it runs: opt-in via CoalescerConfig::default().with_bocpd() in ftui_runtime::bocpd::BocpdDetector (enable_bocpd = false by default).
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 sub‑Gaussian test‑martingale (e‑process):
$$ E_t = E_{t-1}\exp\bigl(\lambda_{t-1} r_t - \lambda_{t-1}^2/2\bigr) $$
Intuition: we can look after every frame, and the false‑alarm guarantees still hold.
Where it runs: ftui_render::budget::EProcessState runs on the render path inside BudgetController (warmup_frames = 10, $\alpha = 0.05$, $\beta = 0.5$, adaptive_lambda = true with predictable Gaussian GRAPA) and AllocLeakDetector runs on the guardrail path inside ftui_render::frame_guardrails::FrameGuardrails; standalone experimental variants remain in ftui_runtime::conformal_alert and ftui_runtime::eprocess_throttle.
GRAPA (Adaptive Betting Fraction)
GRAPA adjusts the betting fraction to keep an e‑process sensitive but stable:
$$ \lambda_t = \mathrm{clamp}\bigl(\lambda_{t-1} + \eta(r_t - \lambda_{t-1}),,\lambda_{\min},,\lambda_{\max}\bigr) \quad\text{(Gaussian)},\qquad \lambda_{t+1} = \mathrm{clamp}!\left(\lambda_t + \eta,\frac{z_t}{1 + \lambda_t z_t}\right) \quad\text{(Bernoulli)} $$
Intuition: it auto‑tunes how aggressively a test martingale bets instead of locking a single sensitivity.
Where it runs: predictable Gaussian GRAPA runs on the default render path inside ftui_render::budget::EProcessState (adaptive_lambda = true, grapa_eta = 0.1, lambda_min = 0.05, lambda_max = 2.0, emitted as eprocess_lambda in budget_decision evidence rows); Bernoulli and conformal-alert variants remain in the quarantined experimental modules ftui_runtime::eprocess_throttle and ftui_runtime::conformal_alert.
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
The sampler weighs expected variance reduction against measurement cost, with minimum and maximum sampling intervals.
$$ \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: sample when uncertainty reduction is worth the configured cost, or when the maximum interval forces a measurement.
Jain’s Fairness Index (Input Guarding)
We watch whether rendering is starving input processing.
$$ F=\frac{(\sum x_i)2}{n\sum x_i2} $$
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 over normalized error $e_t = (\text{frame_ms} - \text{target_ms}) / \text{target_ms}$:
$$ 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. Production BudgetController uses full 3-term PID gains by default (Kp = 0.5, Ki = 0.05, Kd = 0.2) gated by an anytime-valid e-process (warmup_frames = 10, where degradation is suppressed during cold-start calibration while upgrades remain permitted).
MPC (Model Predictive Control) Evaluation
We benchmark 3-step receding-horizon MPC against a stripped 2-term PI baseline (Kp = 0.5, Ki = 0.05, Kd = 0) in mpc_vs_pi_evaluation to verify whether lookahead control is worth its per-frame solver cost.
$$ \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 evaluation suite shows single-loop PID/PI control is already sufficient for TUI pacing.
Count‑Min Sketch (Approximate Counts)
A probabilistic frequency sketch estimates item counts in bounded memory:
$$ \hat f(x)=\min_j C_{j,h_j(x)},\quad $$
Intuition: a tiny data structure gives you “close enough” frequencies at huge scale.
Where it runs: ftui_text::width_cache::CountMinSketch backs the benchmark-only TinyLfuWidthCache (production width caching uses S3FifoWidthCache in ftui_core::text_width), and ftui_runtime::countmin_sketch (experimental) provides a Count-Min sketch with PAC-Bayes error budgeting used by TimelineAggregator; the showcase action_timeline screen exercises it when built with --features experimental (no consumer in the default runtime/render path).
PAC‑Bayes Calibration (Error Tightening)
PAC‑Bayes tightens empirical sketch error bounds from observed residuals:
$$ \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.
Where it runs: Implemented in ftui_runtime::countmin_sketch (experimental), used by ftui_runtime::timeline_aggregator, and exercised by the showcase action_timeline screen when built with --features experimental (not in the default runtime/render path).
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.
Where it runs: opt-in via EffectQueueConfig { scheduler_enabled: true, .. } in ftui_runtime::queueing_scheduler::QueueingScheduler (EffectQueueConfig::default() sets scheduler_enabled: false, using FIFO order unless enabled).
Every one of these is 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\nabla2u - uv2 + F(1-u)$; $\partial_t v = D_v\nabla2v + uv2 - (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 (Help + HintRanker) |
$V_i=E[U_i]+w_{voi}\sqrt{Var(U_i)}-\lambda C_i$ | Stable, utility‑aware hints |
| Conformal Rank Confidence | Command palette tie-break utility (conformal_rank_confidence, opt-in helper) |
$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)$ | Row-level clean-tile skip on large screens (200x60: 28→21 µs) |
| 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 (opt-in via with_bocpd()) |
Run‑length posterior + hazard $H(r)$ | Regime-aware delay selection when enabled |
| Run‑Length Posterior | BOCPD core (opt-in via with_bocpd()) |
$P(r_t=r\mid x_{1:t})$ recursion | Regime switches without static rate thresholds |
| E‑Process | Budget controller gate (ftui_render::budget, adaptive $\lambda_{t-1}$, plug‑in $\hat{\sigma}_{\text{MAD}}$) & leak detector (FrameGuardrails) |
$E_t=\mathrm{clamp}(E_{t-1}\exp(\lambda_{t-1} r_t-\lambda_{t-1}^2/2))$ | Early overload & leak gating ([0.01, 1e10] clamp) |
| GRAPA | Budget controller (ftui_render::budget::EProcessState, adaptive_lambda = true) + experimental conformal_alert / eprocess_throttle |
$\lambda_t=\mathrm{clamp}(\lambda_{t-1}+\eta(r_t-\lambda_{t-1}),\lambda_{\min},\lambda_{\max})$ | Predictable self‑tuning betting 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 |
| CUSUM | Budget change detection (FrameGuardrails via AllocLeakDetector) |
$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 library (ftui_core::animation, standalone) |
$x''+c x' + k(x-x^*)=0$ | Natural motion without frame‑rate artifacts |
| Easing Curves | Animation library (ftui_core::animation, standalone) |
$t^2$, $1-(1-t)^2$, cubic variants | Predictable velocity shaping |
| Staggered Cascades | Animation library (ftui_core::animation, standalone) |
$offset_i=D\cdot ease(i/(n-1))$ | Coordinated, non‑uniform entrances |
| Sine Pulse | Animation library (ftui_core::animation, standalone) |
$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$ (Kp=0.5, Ki=0.05, Kd=0.2) |
Smooth frame‑time stabilization |
| MPC | Control evaluation | $\min_{u_{t:t+H}}\sum|y_{t+k}-y^*|^2+\rho|u_{t+k}|^2$ | Confirms PID/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_i2)$ | Prevents UI render from starving input |
| Count‑Min Sketch | Benchmark width cache (TinyLfuWidthCache) + experimental countmin_sketch |
$\hat f(x)=\min_j C_{j,h_j(x)}$ | Fast approximate counts (production width cache uses S3-FIFO) |
| W‑TinyLFU Admission | Width cache admission (benchmark-only TinyLfuWidthCache; production uses S3-FIFO) |
admit if $\hat f(x)\ge \hat f(y)$ (Doorkeeper → CMS) | Benchmark comparison against S3-FIFO |
| PAC‑Bayes | Sketch calibration (experimental countmin_sketch) |
$\bar e+\sqrt{\mathrm{KL}(q||p)/(2n)}$ | Tighter error bounds in experimental sketch |
| Smith’s Rule + Aging | Queueing scheduler (opt-in via EffectQueueConfig::scheduler_enabled) |
$priority=\frac{w}{r}+a\cdot\text{wait}$ | Fair throughput under load when enabled |
| 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:
┌──────────────┬──────────────┬──────────────┬───────────────────────┐
│ │ │ │ CellAttrs (4 bytes) │
│ CellContent │ fg │ bg ├───────────┬───────────┤
│ (4 bytes) │ PackedRgba │ PackedRgba │StyleFlags │ link_id │
│ char/gid │ (4 bytes) │ (4 bytes) │ bits 31-24│ bits 23-0 │
│ │ │ │ (8 bits) │ (24 bits) │
└──────────────┴──────────────┴──────────────┴───────────┴───────────┘
Cell (16 bytes)
4 cells per 64-byte cache line. SIMD-friendly 128-bit equality via bits_eq().
Four fields, not five: the hyperlink id has no field of its own, it lives in the
low 24 bits of CellAttrs alongside 8 bits of StyleFlags. That is why the API
is cell.attrs = cell.attrs.with_link(id) rather than cell.link_id = id, and
why a link id is capped at LINK_ID_MAX = 0x00FF_FFFF with 0 reserved as the
"no hyperlink" sentinel. const _: () = assert!(size_of::<Cell>() == 16); in
cell.rs makes the 16 bytes a compile error to break.
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
That 128-bit comparison is the compiler's, not a hand-written kernel's, and
measurement says to leave it that way: explicit std::simd row compares in
ftui-simd run 3–4× slower, because safe code cannot view &[Cell] as lanes
and has to build each vector with shifts and masks, while bits_eq() already
lowers to one 128-bit compare. The simd feature therefore accelerates only the
printable-ASCII width fast path, where the same kernels win by 5–44×. Numbers in
docs/perf/simd_kernels_2026-09-18.md.
Block-Based Diff Algorithm
The diff engine provides two scan strategies selected per frame by DiffStrategySelector:
Default narrow scan (compute_certified_into under DiffStrategy::DirtyRows):
for each certified dirty row y:
for each dirty span [x0, x1) in new.dirty_span_row(y):
compare 128-bit cells in [x0, x1) via bits_eq()
coalesce adjacent changes into ChangeRun
Full scan (compute_into under DiffStrategy::Full):
for each row y:
for each 32-cell block:
if block_all_unchanged (4-cell chunks via bits_eq()):
continue ← Skip unchanged 32-cell block
scan cells in block and coalesce into ChangeRun
Key optimizations:
- Certified dirty-row & span skipping (
DirtyRowsdefault): Clean rows are skipped in O(1) viadirty_rows[y] == false, and within dirty rows only the mutated column spans (dirty_spans[y]) are compared (scan_row_changes_spans). - 32-cell block skip (
Fullscan):compute_intodoes not pre-check whole rows; instead it tests 32-cell blocks (BLOCK_SIZE = 32) in 4-cell chunks (bits_eq) and scans individual cells only inside blocks that differ. - Change coalescing: Adjacent changed cells become a 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
→ 4 + digits + digits // e.g., "\x1b[12;45H" = 8 bytes
// CHA (Column Absolute): CSI {col+1}G
→ 3 + digits // e.g., "\x1b[45G" = 5 bytes
// Per-row decision: sparse runs vs merged write-through
strategy = argmin
cheapest_move_cost(from, to) returns 0 when the cursor is already in place, and on the same row prefers CHA over CUP because CUP always pays the extra row field. The costs are byte counts, so the choice is exact rather than estimated: cup_cost(0, 0) == 6 is pinned against the six bytes of \x1b[1;1H.
Bayesian Intelligence Layer
FrankenTUI uses principled statistical methods for runtime decisions, replacing ad-hoc heuristics with Bayesian inference.
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
The defaults, the 16/40/100 ms delays, the fallback rule and the evidence fields are stated once, in BOCPD: Online Change-Point Detection. This section is the motivation; that one is the contract. Restating the numbers here is how they drifted apart before.
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 (sequential test wealth processes):
Sub-Gaussian / Bernoulli E-Process:
True conditional supermartingale (fixed known σ₀ or p₀, predictable λ_{t-1}, unclamped):
P(∃t: E_t ≥ 1/α) ≤ α under H₀ (Ville's inequality)
Production render-path gate (ftui_render::budget::EProcessState):
E_t = clamp(E_{t-1} × exp(λ_{t-1}·r_t − λ_{t-1}²/2), 0.01, 1e10)
λ_t = clamp(λ_{t-1} + η·(r_t − λ_{t-1}), λ_min, λ_max)
with EMA plug-in variance and sub-threshold decay
Where it runs: ftui_render::budget::EProcessState runs on the render path with predictable Gaussian GRAPA (adaptive_lambda = true by default in EProcessConfig, updating $\lambda_t$ from $\mathcal{F}{t-1}$-measurable residuals after warmup); quarantined experimental variants remain in conformal_alert (sub-Gaussian gradient $z{\text{centered}} - \lambda_t \sigma_0^2$) and eprocess_throttle (Bernoulli GRAPA gradient $r_t / (1 + \lambda_t r_t)$).
Practical benefit: Sequential wealth accumulates overload evidence across frames without fixed sample-size windows.
VOI Sampling: Value of Information
The runtime's inline-auto height policy uses the VOI sampling rule above.
For a uniform Beta(1,1) prior, one Bernoulli observation gives this exact check:
variance_before = 1/12
variance_after_violation = Var[Beta(2,1)] = 1/18
variance_after_no_violation = Var[Beta(1,2)] = 1/18
expected_after = (1/2) × (1/18) + (1/2) × (1/18) = 1/18
VOI = 1/12 - 1/18 = 1/36
Both possible observations contribute to the expectation. The sampler compares the scaled gain with cost, subject to its minimum and maximum sampling intervals.
Experimental modules
These modules compile only with --features experimental on the crate that owns them. APIs may change or be removed without notice.
Read experimental here as "quarantined", not "unstable but working". These are research code with unit tests and no production consumer: nothing in the render path, the runtime loop, or the widget library constructs any of them. The workspace's own compile check is named all_quarantined_modules_are_nameable (ftui-runtime/tests/experimental_feature_matrix.rs) and does exactly what the name says — it binds each type to None to prove the module still compiles. Enabling the feature makes the code available to you; it does not switch anything on inside FrankenTUI.
Sections below that describe an experimental module each carry a Where it runs line, so you do not have to cross-reference this table to find out whether a feature is connected. Checked 2026-09-19 by resolving use ftui_runtime::<module> across every crate's src/. (One trap if you check this yourself: ftui-render/src/presenter.rs declares its own private mod cost_model for ANSI cursor-move costs, which is unrelated to ftui_runtime::cost_model and makes a bare grep for cost_model:: look like a hit.)
= { = "0.10", = ["experimental"] }
| Crate | Module | What it is | Status |
|---|---|---|---|
ftui-render |
roaring_bitmap |
Minimal Roaring Bitmap for cell-level dirty region tracking | experimental |
ftui-runtime |
alpha_investing |
Sequential FDR control for multiple simultaneous statistical monitors | experimental |
ftui-runtime |
conformal_alert |
Conformal alert threshold calibration with anytime-valid e-process control | experimental |
ftui-runtime |
conformal_frame_guard |
Conformal frame guard for frame timing with explicit unavailable bounds | experimental |
ftui-runtime |
conformal_stages |
Multi-stage Mondrian conformal prediction for render pipeline timing | experimental |
ftui-runtime |
cost_model |
Formal mathematical cost models for caches, scheduling, and batching | experimental |
ftui-runtime |
countmin_sketch |
Count-Min Sketch with PAC-Bayes error budgeting for timeline aggregation (exercised in showcase action_timeline under --features experimental) |
experimental |
ftui-runtime |
degradation_cascade |
Cascade from conformal frame guard risk detection through budget controller to widget priority | superseded by ftui_render::budget + program.rs (experimental) |
ftui-runtime |
eprocess_throttle |
Anytime-valid adaptive recompute throttle using GRAPA test martingales | superseded by ftui_render::budget::EProcessState (experimental) |
ftui-runtime |
evidence_bridges |
Convert domain-specific decision types into unified evidence ledger records | experimental |
ftui-runtime |
flake_detector |
Anytime-valid test martingale detector for flaky timing regressions in E2E tests | experimental |
ftui-runtime |
flat_combine |
Caller-driven flat combining for batched operation dispatch | experimental |
ftui-runtime |
ivm |
Incremental View Maintenance (IVM) signed-tuple delta algebra, DAG topology, and view operators (no propagation engine) | experimental |
ftui-runtime |
lens |
Bidirectional algebraic lenses for state-widget binding | experimental |
ftui-runtime |
policy_config |
Policy-as-data configuration capturing tunable parameters across the decision stack | experimental |
ftui-runtime |
policy_registry |
Thread-safe registry of named policy configurations with lock-free reads and atomic hot-swap | experimental |
ftui-runtime |
resize_sla |
Resize SLA monitoring with conformal alerting | experimental |
ftui-runtime |
reversible |
Reversible computing primitives where mutations know their own inverses for undo | experimental |
ftui-runtime |
rough_path |
Rough-path signatures for sequential trace feature extraction | experimental |
ftui-runtime |
schedule_trace |
Deterministic golden trace infrastructure for async task manager testing | experimental |
ftui-runtime |
slo |
Machine-readable SLO definitions, breach detection, and safe-mode enforcement | experimental |
ftui-runtime |
sos_barrier |
Sum-of-squares (SOS) polynomial barrier certificate evaluator for frame-budget admissibility | experimental |
ftui-runtime |
timeline_aggregator |
Bounded-memory action timeline event aggregation and change-point alerting (exercised in showcase action_timeline under --features experimental) |
experimental |
ftui-runtime |
validation_pipeline |
Expected-cost validation ordering with Bayesian online learning | experimental |
ftui-runtime |
wasm_runner |
Step-based synchronous program runner driving a Model without background threads | experimental |
Performance Engineering
Dirty Row Tracking
Every buffer mutation marks its row dirty in O(1):
// ftui-render/src/buffer.rs
Buffer::set calls this after bounds, scissor, opacity and wide-grapheme handling — it is not a bare index-and-assign, and an out-of-bounds or fully clipped write marks nothing.
Invariant: If is_row_dirty(y) == false, row y is guaranteed unchanged since last clear.
Three levels, not one. dirty_rows is a Vec<bool> (one byte per row) for row-granularity skipping; dirty_spans is a per-row SmallVec<[DirtySpan; 4]> that keeps sparse edits to a few ranges before overflowing to whole-row; and dirty_bits is a per-cell Vec<u8> — one byte per cell, not one bit — backing tile-based skipping.
Cost: dirty_bits dominates at width × height bytes, so dirty tracking adds roughly 6% to the memory of a 16-byte-per-Cell buffer; dirty_rows and dirty_spans are O(height). In exchange the diff skips clean rows entirely and clean spans within dirty rows.
Grapheme Pooling
Complex graphemes (emoji, ZWJ sequences) are reference-counted in a pool:
GraphemeId (4 bytes):
┌─────────────────────────────────────────────────────────────┐
│ [30-27: width] [26-16: generation] [15-0: pool slot index] │
└─────────────────────────────────────────────────────────────┘
Capacity: 65,536 slots, display widths 0-15; the generation counter
detects stale ids after a slot is recycled
Lookup: O(1) via hash-map 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: while sync output is enabled, no partial frame is ever visible, eliminating flicker even on slow terminals. It is enabled when either:
- the terminal identity is on the allowlist (kitty, Ghostty, Alacritty via
TERM_PROGRAMorTERM=alacritty, Contour), or - the terminal answers the DECRPM probe (
CSI ? 2026 $ p) at startup saying it recognizes mode 2026. This is how plainxterm-256color, iTerm2, VS Code, and any terminal reached oversshget flicker-free frames; the probe is bounded (300 ms), fail-open, and upgrade-only.
It is deliberately off inside tmux, screen, and zellij, and for WezTerm
identities (WezTerm multiplexer sessions were observed to misbehave around
?2026 h/l, and the markers that would distinguish a mux session from a local
window do not survive every launch path). Operators can override policy without
rebuilding: FTUI_SYNC_OUTPUT=1|0 and FTUI_SCROLL_REGION=1|0 force the
setting (an explicit 1 also lifts the WezTerm gate, never real multiplexer
evidence), and FTUI_CAPS_PROBE=0 disables startup probing. The matrix in
scripts/pty_identity_matrix.py runs the showcase under a real PTY per
identity and asserts exactly which of these outcomes occur; the measured
results are in docs/compat-matrix.md.
The Elm Architecture in Rust
FrankenTUI implements the Elm/Bubbletea architecture with Rust's type system:
The Model Trait
Update/View Loop
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Event │───▶│ Message │───▶│ Update │───▶│ View │
│ (input) │ │ (enum) │ │ (model) │ │ (frame) │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Cmd │ │ Render │
│ (async) │ │ (diff) │
└─────────┘ └─────────┘
Commands & Side Effects
none // No side effect
task // Background work on a worker → Message
tick // Set a recurring tick: Event::Tick every 50 ms (replaces the rate)
msg // Call update(Msg::Refresh) right away, within this turn
quit // Exit program
batch // Multiple commands; today executed in order, like sequence
sequence // Multiple commands, in order
Cmd::SetClipboard(String) requests a clipboard write; construct it with
Cmd::set_clipboard(text). Cmd::GetClipboard, constructed with
Cmd::get_clipboard(), requests a read whose reply is delivered as
Event::Clipboard. Native execution uses the terminal capability policy and
OSC 52 limits described above.
Subscriptions
Declarative, long-running event sources:
Subscriptions are automatically started/stopped based on what subscriptions() returns each frame; a subscription's id (interval for tick_every, path for file_watcher) is what keeps it running across frames. file_watcher polls metadata (mtime and size, 250 ms by default; FileWatcher::new(..).with_interval(..) to change it), so it works on every platform without a native watcher dependency. The demo's Async Tasks screen uses it: while that screen is shown the app watches $FTUI_DEMO_WATCH_FILE (default: a file in the temp dir), w appends to it, and each event is logged in the Activity panel. tests/e2e/scripts/test_async_tasks.sh drives that in a PTY, including a write and a delete made from outside the app.
Safety & Correctness Guarantees
Zero Unsafe Code Policy
// ftui-render/src/lib.rs
// ftui-runtime/src/lib.rs
// ftui-layout/src/lib.rs
The entire render pipeline, runtime, and layout engine contain zero unsafe blocks.
Integer Overflow Protection
Coordinate arithmetic uses saturating or checked operations (saturating_* and checked_*) across the workspace:
// Cursor positioning (saturating)
let next_x = current_x.saturating_add;
// Bounds checking (checked)
let Some = x.checked_add else ;
// Intentional wrapping (PRNG only)
seed.wrapping_mul.wrapping_add
This is a convention, not a compiler guarantee: no clippy::arithmetic_side_effects lint is enabled, so a bare + on a coordinate would compile. The unsafe ban above is enforced — #![forbid(unsafe_code)] is present in all 20 crates.
Untrusted Output Sanitization (ADR-006)
Agent harnesses and CLI tools routinely display untrusted LLM streams, subprocess logs, and user input. FrankenTUI sanitizes log output by default (ADR-006) so injected CSI/OSC/DCS/APC sequences cannot move the cursor, forge prompts, enter alternate screen, or corrupt terminal state:
// 1. Default (strip): removes all escape sequences and C0/C1 controls except TAB/LF/CR
writer.write_log?; // or LogSink::new(&mut writer) / Cmd::log(..)
// 2. Semi-trusted (SGR-only): keeps bounded SGR color codes (CSI [0-9;:]* m, <= 64 B),
// strips cursor/OSC/mode escapes, and appends \x1b[0m before each newline
writer.write_log_sgr_only?; // or LogSink::sgr_only(&mut writer) / Cmd::log_sgr_only(..)
// 3. Trusted (explicit raw opt-in): no global switch; emits ftui.sanitize debug trace
writer.write_log_raw?; // or LogSink::raw(&mut writer) / Cmd::log_raw(..)
Flicker-Free Proof Sketch
crates/ftui-render/tests/no_flicker_proof.rs tests diff equivalence and DEC 2026 sync-bracket framing in ftui-render (certified_and_dirty_diff_match_full_diff_and_wrap_sync_brackets), while the full 6-theorem proof sketch and adversarial counterexample suite live in crates/ftui-harness/tests/render_no_flicker_proof.rs:
Theorem 1 (Sync Bracket Completeness): When capabilities.sync_output == true (and no I/O error aborts the write), every byte emitted by Presenter::present is enclosed within one DEC 2026 sync bracket pair (\x1b[?2026h … \x1b[?2026l).
Theorem 2 (Diff Completeness): For equal-dimension buffers, 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 since clear_dirty(), is_row_dirty(y) == true, dirty_spans[y] covers the mutated column range, and mutation_gen advances.
Theorem 4 (Diff-Dirty Equivalence): When new was cleared (clear_dirty()) at old's mutation generation (new.dirty_baseline_gen() == Some(old.mutation_gen())) or starts full-dirty (reset_for_frame()), compute_certified_into(), compute_dirty(), and compute() produce identical output; if the baseline generation or row/span witnesses disagree, evaluate_render_certificate_for_buffers falls back to FullDiff (compute_into).
Test Infrastructure
Property-Based Testing
crates/ftui-render/tests/proptest_diff_invariants.rs generates random buffers and change sets and checks the diff against them from both directions:
proptest!
Alongside them: identical_buffers_produce_empty_diff, diff_is_deterministic, compute_and_compute_into_equivalent, runs_cover_all_changes, changes_sorted_row_major, certified_diff_matches_full_diff_and_respects_span_bound, presented_certified_diff_reproduces_the_target_buffer, and the certificate negative controls (negative_control_stale_dirty_bits_refuses_skip_and_recovers_exact_diff, negative_control_corrupted_witness_refuses_narrow_and_recovers_exact_diff).
Snapshot Testing
# Run tests, auto-update baselines
BLESS=1
# Plain-text .snap files, one per case, reviewed as an ordinary diff
The workspace retains 604 plain-text .snap files across ftui-demo-showcase (436), ftui-extras (101), and ftui-harness (67). A .snap file is the rendered frame as text, so a failing snapshot diff shows the actual character grid that changed rather than an opaque blob.
Formal Verification Patterns
Theorem 3 (dirty-tracking soundness) is pinned by set_marks_row_dirty in ftui-render/src/buffer.rs — if it fails, the theorem is false:
Note it clears the initial dirty state first: a fresh Buffer starts with every row dirty (dirty_rows_start_dirty), so a test that skipped clear_dirty() would pass without proving anything. Its siblings cover the other mutation paths — set_raw_marks_row_dirty, get_mut_marks_row_dirty, fill_marks_affected_rows_dirty, clear_marks_all_dirty.
Benchmark Suite
# Run the full 27-threshold SLO + Criterion + byte-budget + allocation gate
# Paired certified vs dirty vs full-scan diff benchmarks (120×40, opt-level="z"):
# diff_paths_paired (certified, spinner_tick 120x40) p50: [90.7 ns] throughput: [52.9 Gcells/s]
# diff_paths_paired (certified, overmarked_chrome 120x40) p50: [251.4 ns] throughput: [19.1 Gcells/s]
# diff_paths_paired (certified, scattered_5pct 120x40) p50: [1.98 µs] throughput: [2.43 Gcells/s]
# diff/sparse_5pct/compute/120x40 (full scan) p50: [7.51 µs] throughput: [639 Mcells/s]
# diff/heavy_50pct/compute/120x40 (full scan) p50: [8.22 µs] throughput: [584 Mcells/s]
# diff/full_100pct/compute/120x40 (full scan) p50: [12.1 µs] throughput: [396 Mcells/s]
| Operation / Metric | Criterion / Scene ID | Observed (Mean, 95% CI) | Enforced Budget |
|---|---|---|---|
| Full frame pipeline (80×24 @ 5%) | pipeline/truecolor/diff_and_present/full/80x24@5% |
17.74 µs ([16.63 µs, 19.69 µs]) |
2.00 ms (+10%) |
| Diff compute (80×24 @ 5% full scan) | diff/sparse_5pct/compute/80x24 |
3.01 µs ([2.56 µs, 3.59 µs]) |
200.00 µs (+10%) |
| Diff compute (200×60 @ 5% dirty rows) | diff/sparse_5pct_rows/compute_dirty/200x60 |
12.12 µs ([11.69 µs, 12.95 µs]) |
84.00 µs (+10%) |
| Presenter ANSI emit (80×24 @ 5%) | present/truecolor/sparse_5pct/present/80x24 |
19.45 µs ([16.47 µs, 23.39 µs]) |
3.00 ms (+10%) |
| Presenter ANSI emit (120×40 @ 5%) | present/truecolor/sparse_5pct/present/120x40 |
39.86 µs ([37.29 µs, 43.55 µs]) |
6.00 ms (+10%) |
| Presenter ANSI emit (200×60 @ 5%) | present/truecolor/sparse_5pct/present/200x60 |
94.43 µs ([91.14 µs, 100.67 µs]) |
18.00 ms (+10%) |
| ANSI bytes emitted (80×24 @ 5%, 96 cells) | bytes:present/bytes/sparse_5pct/80x24 |
169 B (<= 832 B) |
832 B (8*cells+64) |
| Input parse + dispatch (per event) | input/parse_dispatch/mixed_event_stream/per_event |
152.0 ns ([129.4 ns, 188.3 ns]) |
100.00 µs (+10%) |
| Word wrap (200 lines @ 80 cols) | wrap/word/200_lines_80_cols |
829.34 µs ([789.81 µs, 880.56 µs]) |
2.00 ms (+10%) |
| Grapheme width lookup (S3-FIFO cached) | text_width/non_ascii_corpus/cached |
25.6 ns ([21.7 ns, 29.5 ns]) |
30.0 ns (+10%) |
| Flex layout solver (10 constraints) | layout/flex_split/horizontal/10 |
131.7 ns ([118.8 ns, 150.0 ns]) |
20.00 µs (+10%) |
| Virtualized Fenwick scroll (100k items) | virtualized/scroll_to/variable_fenwick/100000 |
16.1 ns ([14.6 ns, 18.2 ns]) |
1.00 µs (+10%) |
Runtime first frame (80×24 headless) |
runtime/first_frame/headless_80x24 |
94.71 µs ([77.36 µs, 111.22 µs]) |
10.00 ms (+10%) |
Runtime Cmd::msg roundtrip |
runtime/command_roundtrip/cmd_msg |
92.1 ns ([83.1 ns, 105.7 ns]) |
500.00 µs (+10%) |
| Runtime shutdown latency | runtime/shutdown_latency/headless |
1.64 µs ([1.41 µs, 1.90 µs]) |
5.00 ms (+10%) |
| Steady-state heap allocs (ASCII 80×24) | allocs:ascii_dashboard_80x24 |
0 allocs (0 B, down from 1397 / 142,688 B) |
0 allocs/frame |
| Steady-state heap allocs (Unicode 80×24) | allocs:unicode_dashboard_80x24 |
3 allocs (42 B, down from 661 / 79,962 B) |
4 allocs/frame |
Full 27-metric table, confidence intervals, byte-efficiency breakdown, and FrameArena allocation report: docs/perf/baseline_2026-10-19.md (generated from docs/perf/regression_report_2026-10-19.jsonl).
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 (16ms delay) ← Responsive to deliberate resizes (μ_steady = 200ms observation prior)
Burst (40ms delay) ← Aggressive coalescing during drag (100ms hard deadline, μ_burst = 20ms prior)
Budget-Based Degradation
Frame time is regulated with a PID controller:
Error: e_t = (actual_ms - target_ms) / target_ms // normalized; POSITIVE = over budget
Control: u_t = Kp·e_t + Ki·Σe + Kd·Δe
Integral: Σe clamped to ±5.0 (anti-windup)
E-Process: warmup_frames = 10 (degradation suppressed during calibration), α = 0.05, β = 0.5
Degradation: Full → SimpleBorders → NoStyling → EssentialOnly → Skeleton → SkipFrame
Floor: degradation_floor = SimpleBorders by default (honored by PID + conformal gate;
raise floor or trigger FrameGuardrails for deeper levels)
Gains: Kp=0.5, Ki=0.05, Kd=0.2 (tuned for 16ms / 60fps)
The error is a fraction of the budget, not milliseconds, and positive means the frame ran long — so a rising u_t degrades. The gains above are tuned for that normalized form; feeding them raw milliseconds would scale the response by the budget. An earlier version of this block had the error as target_ms - actual_ms, which is both un-normalized and the opposite sign, and would have had the controller degrading on fast frames.
When frames exceed budget after the 10-frame e-process warm-up, the renderer degrades visual fidelity up to the configured degradation_floor (SimpleBorders by default, or up to SkipFrame when configured) and recovers automatically once frame times drop.
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 >= 50ms OR resize_dominance >= 3 OR F < 0.8:
defer_pending_resize() // InputFairnessGuard::check_fairness yields to input
Widget System (70 Direct Implementations)
FrankenTUI ships 70 direct Widget and StatefulWidget implementations across 55 widget types in ftui-widgets (93 implementations across the workspace).
Core Widgets
| Widget | Description | Key Feature |
|---|---|---|
Block |
Container with borders/title | 7 named border styles, title alignment |
Paragraph |
Text with wrapping | Word/char wrap, scroll |
List |
Selectable items | Clipped to the viewport, custom highlight (large lists: VirtualizedList) |
Table |
Columnar data | Column constraints, row selection, themed |
Input |
Text input | Cursor, selection, history |
Textarea |
Multi-line input | Line numbers, syntax hooks |
Tabs |
Tab bar | Key/mouse selection; close and reorder through the API (not bound to input) |
Progress |
Progress bars | Determinate/indeterminate |
Sparkline |
Inline charts | Min/max markers |
Tree |
Hierarchical data | Expand/collapse (children supplied up front) |
CommandPalette |
Fuzzy search | Bayesian scoring with evidence ledger |
Modal |
Dialog/overlay system | Stack‑based, focus capture |
JsonView |
JSON tree viewer | Collapse/expand nodes |
FilePicker |
File browser | Directory navigation |
VirtualizedList |
Large lists | Fixed or variable row heights (variable_heights(), Fenwick-tracked, O(log n) scroll, per-category Bayesian height prediction via with_predictor, Beta-VOI remeasurement via with_remeasure_policy); shared with Virtualized<T> |
Toast |
Notifications | Timed, dismissable |
Spinner |
Activity indicator | Multiple styles |
Scrollbar |
Scroll position | Proportional thumb |
Plus: Align, Badge, CachedWidget, Columns, ConstraintOverlay, DebugOverlay, DecisionCard, Draggable, Emoji, ErrorBoundary, Group, Help, HistoryPanel, InspectorOverlay, LogViewer, NotificationQueue, Padding, Paginator, Panel, Pretty, Rule, StatusLine, Stopwatch, Timer, ValidationErrorDisplay, VoiDebugOverlay, DriftVisualization, and more.
Table Theming System
The table widget has a dedicated theme engine (ftui-style/src/table_theme.rs) that goes beyond simple row striping:
| Theme Feature | What It Controls |
|---|---|
| Row striping | Alternating background colors with configurable period |
| Column emphasis | Per-column foreground/background overrides |
| Header styling | Separate style for the header row |
| Selection highlight | Selected-row style merged over the row's style (blend modes apply to theme effect rules, not to selection) |
| Hover state | Hovered-row style from mouse hit-testing (TableState::hovered), applied as-is |
| Border | One border style for the table's block |
| Column gap & cell padding | TableTheme::column_gap sets the default inter-column spacing unless .column_spacing(..) overrides it; TableTheme::padding sets horizontal cell inset in MarkdownRenderer by default and in Table when .use_theme_padding(true) (or .cell_padding(..)) is set |
| Truncation | Ellipsis, clip, or wrap per column (with_column_truncation(col, Truncate::Ellipsis)) |
| Alignment | Left/center/right per column with Unicode-aware width (with_column_alignment(col, Alignment::Right)) |
Themes are composable (with 10 built-in presets); a base theme can be overlaid with per-instance overrides:
// Ten built-in presets (Aurora, Graphite, Neon, Slate, Solar, Orchard, Paper,
// Midnight, TerminalClassic, Modern), each a complete set of header / stripe /
// selection / hover styles
let theme = preset;
let resolver = theme.effect_resolver;
Stylesheet System
Named styles are defined once in a StyleSheet (thread-safe, ftui_style::stylesheet) for consistent theming across widgets:
use PackedRgba;
use StyleSheet;
let sheet = new;
let heading = new.bold.fg;
let error = new.bold.fg;
sheet.define;
sheet.define;
sheet.define;
// Resolve by name anywhere in the widget tree; compose layers left to right
let resolved = sheet.get_or_default;
let loud_error = sheet.compose;
Widget Composition
// Widgets compose via Frame's render helpers (FrameExt, in the prelude)
use ;
Stateful Widgets
// State lives in your Model; `view(&self)` borrows it mutably through a RefCell
Advanced Features
Hyperlink Support
let link_id = frame.register_link;
let mut cell = from_char;
cell.attrs = cell.attrs.with_link;
// Emits OSC 8 hyperlink sequences for supporting terminals
Focus Management
// Declarative focus graph: FocusManager owns a FocusGraph of nodes and nav edges
let graph = focus.graph_mut;
let input1 = graph.insert;
let input2 = graph.insert;
graph.connect; // Tab order
// Navigation
focus.focus_next; // Tab
focus.focus_prev; // Shift+Tab
Modal System
let id = modal_stack.push; // any `StackModal`
// Modals capture input, render above main content
// Escape or button press pops the stack; `pop()` returns the ModalResult
Time-Travel Debugging
// Record frames for debugging (ftui-harness; delta-compressed ring of 256 frames)
let mut history = new;
history.record;
// Replay
let historical_frame = history.get;
Accessibility
The ftui-a11y crate provides an accessibility tree that mirrors the widget render tree:
- Semantic nodes for every interactive widget (button, input, list item)
- Role/state/label properties following WAI-ARIA semantics
- Focus graph with keyboard navigation order (Tab/Shift+Tab)
- Live regions for announcing dynamic content changes to screen readers
- Contrast checking using WCAG 2.1 luminance ratios (
ftui-style/src/color.rs)
Runtime wiring. Widgets that implement ftui_a11y::Accessible (Block, Input, List, Table, Tabs, Paragraph, Progress, Scrollbar, Spinner) push their nodes into the Frame as they render. Enable collection per program:
use ;
let config = default.with_accessibility;
With that set, every rendered frame builds an A11yTree, diffs it against the previous frame and derives bounded screen‑reader announcements (focus changes, live‑region additions and changes). Read them through Program::accessibility_tree / accessibility_announcements / accessibility_dump, or react from the model via Model::on_accessibility, which runs after each frame whose tree changed:
The evidence sink gets a11y_tree and a11y_announcement rows (schema in docs/spec/telemetry-events.md) and the ftui.a11y tracing target carries the same data. Without the config no tree is built and rendering is unchanged.
Not done: there is no operating‑system bridge (AT‑SPI, UIA, NSAccessibility). Announcements are evidence rows, tracing events and hook calls that a host or an app forwards; nothing reaches a screen reader on its own. Containers other than Block do not scope their children yet, and Form has no accessibility nodes. Details and proofs: docs/ACCESSIBILITY.md.
The accessibility_panel demo screen mirrors the live tree (size, leading dump lines) and the latest announcements as you navigate the UI.
Internationalization
The ftui-i18n crate provides locale-aware rendering:
-
Locale context propagated through the runtime (
ProgramConfig::with_locale("fr"),LocaleContext::direction()) -
String catalog with fallback chains and CLDR-style plural rules (
StringCatalog,PluralRule) -
Text direction from locale with per-line, grapheme-cluster-preserving UAX#9 reordering in
Paragraph(featurebidi, on by default inftui).TextInputandTextAreadraw and navigate editable text in logical order;CursorNavigator::with_visual_bidi(true)is an explicit opt-in visual caret for editors that also render in visual order -
Number & date formatting backed by pinned Unicode CLDR v45.0 data for 7 declared locales (
NumberFormatter,DateTimeFormatter,format_number,format_date)
The i18n_demo screen switches live between English, Spanish, French, German, Russian, Arabic and Japanese; Arabic renders right-to-left.
Queueing-Theoretic Scheduler (Deep Dive)
The effect queue scheduler (queueing_scheduler.rs) implements multiple scheduling disciplines from queueing theory.
Where it runs: opt-in via EffectQueueConfig::default().with_backend(TaskExecutorBackend::EffectQueue) and EffectQueueConfig { scheduler_enabled: true, .. }. By default, DEFAULT_TASK_BACKEND is TaskExecutorBackend::Spawned for RuntimeLane::Structured and RuntimeLane::Legacy so blocking polling tasks cannot serialize interactive echo tasks on a single worker thread (see docs/perf/effect_backend_2026-10-19.md).
SRPT (Shortest Remaining Processing Time)
Optimal for minimizing mean response time in M/G/1 queues:
E[T_SRPT] ≤ E[T_FCFS] for any service-time distribution
Selection rule:
next_job = argmin { remaining_time(j) : j ∈ ready_queue }
Problem: can starve long jobs indefinitely.
Smith's Rule (Weighted SRPT)
Maximizes weighted throughput:
priority(j) = weight(j) / remaining_time(j)
next_job = argmax { priority(j) : j ∈ ready_queue }
Aging for Starvation Prevention
Effective priority:
priority_eff(j) = weight(j) / remaining_time(j) + aging_factor × wait_time(j)
Wait time grows linearly, so a waiting job's priority overtakes any single newly
arriving higher-priority competitor within:
τ_overtake = Δ(weight / remaining_time) / aging_factor
Actual service wait still scales with the total work of the N jobs ahead in the
queue (e.g., (N − 1) × s for N equal jobs of service time s), and live effect
closures (`Box<dyn FnOnce() + Send>`) execute non-preemptively to completion once
dispatched.
Queue Telemetry
let snap = queue_telemetry;
// QueueTelemetry {
// enqueued: 1042, -- total tasks submitted
// processed: 1038, -- total tasks completed
// dropped: 2, -- tasks dropped (backpressure/shutdown)
// high_water: 12, -- peak queue depth observed
// in_flight: 2, -- enqueued − processed: accepted, not finished (process-wide)
// }
Backpressure: a program's effect queue refuses a submission once its own outstanding tasks (waiting or running) reach max_queue_depth, so a long-running task cannot let an unbounded backlog build up behind it; refused tasks count as dropped.
Inline Mode: How Scrollback Preservation Works
Most TUI frameworks take over the alternate screen, destroying the user's scrollback history. FrankenTUI's inline mode keeps the UI stable while letting log output scroll naturally above it. Three strategies are implemented and selected automatically based on terminal capabilities:
Strategy A: Scroll Region (DECSTBM)
Terminal viewport (24 rows):
┌──────────────────────────┐
│ log line 47 │ ← scrollable region (rows 1-20)
│ log line 48 │ DECSTBM constrains scrolling here
│ log line 49 │
│ ... │
│ log line 66 │
├──────────────────────────┤
│ ▌Status: 3 tasks FPS:60│ ← fixed UI region (rows 21-24)
│ ▌[Tab] switch [q] quit │ cursor never enters this region
└──────────────────────────┘
CSI sequence: ESC [ top ; bottom r (set scrolling region)
When new log output arrives, the terminal scrolls only within the designated region. The UI rows below are untouched. Whether rows leaving the top of such a region enter scrollback is up to the terminal: xterm, tmux and Alacritty keep them when the region starts at row 1 (measured for tmux 3.6 by tests/e2e/scripts/test_inline_scrollback_mux.py); the vt100 crate and some other emulators keep only rows that leave a full-screen scroll.
Strategy B: Overlay Redraw
For terminals that don't support scroll regions reliably (multiplexers, terminals that fail the DECSTBM self-test), log lines are batched and streamed at the next frame, explicit flush, or exit (or early, after 256 lines / 64 KiB). The writer erases the UI rows, writes the batch from the UI's first row as ordinary lines, lets the terminal's own line feed at the bottom row scroll the whole screen, and redraws the UI below the new lines. Every line therefore reaches scrollback exactly once and in order on any terminal, and no UI row ever does, because the UI rows are erased before anything scrolls. With DEC 2026 synchronized output the erase-and-redraw is applied atomically; multiplexers run without it, so the UI can flash briefly while a batch goes out. A UI anchored to the top of the screen cannot use this transport (a whole-screen scroll would push the UI into history): there the newest log line overwrites the bottom row and log lines do not reach scrollback.
Strategy C: Hybrid
Scroll-region without synchronized output: the fast path is the same DECSTBM region as Strategy A, but without sync brackets around the redraw. Before the first frame the runtime runs a DECSTBM self‑test on the live terminal (ftui_core::caps_probe::probe_scroll_region): save cursor, set the region, turn origin mode on, move the cursor far below, ask for a cursor‑position report, restore. A terminal that honours the region reports the region's last row; one that ignores it reports the screen bottom (or nothing within 150 ms). On a bad verdict the writer switches to Strategy B before anything is drawn and writes an inline_strategy_fallback evidence row (reason cpr_mismatch or cpr_timeout, observed and expected rows); the inline_strategy row carries scroll_region_verified. The probe runs at construction time, before the input reader starts, so it cannot race the event loop; it is not repeated on resize. FTUI_SCROLL_REGION=1 skips the test and trusts the region, FTUI_SCROLL_REGION=0 selects overlay redraw outright. scripts/inline_scroll_region_selftest_e2e.py runs the showcase under a PTY that answers the cursor query as a honouring, an ignoring and a silent terminal and checks all three outcomes. Under this repository's own WezTerm session the WezTerm identity counts as a multiplexer, so inline runs there use overlay redraw and emit no DECSTBM at all; that is the mux rule, not a writer bug.
Which strategy you actually get
InlineStrategy::select (in ftui_core::inline_mode) decides in this order:
- inside tmux, screen, zellij or a WezTerm mux session: Overlay Redraw
- scroll-region capability and synchronized output both usable: Scroll Region
- scroll-region usable, no synchronized output: Hybrid
- otherwise: Overlay Redraw
"Usable" is the policy answer (use_scroll_region() / use_sync_output()) after identity detection, the live DECRPM probe and the FTUI_SCROLL_REGION / FTUI_SYNC_OUTPUT operator switches. Strategies 2 and 3 are then confirmed by the DECSTBM self‑test described under Strategy C; a terminal that fails it gets Overlay Redraw. The decision is written to the evidence file as capability_decision rows plus an inline_strategy row (with scroll_region_verified) and, on a failed self‑test, an inline_strategy_fallback row when an evidence sink is configured.
Key Invariants
With the UI anchored to the bottom (the default):
- Every completed log line reaches the terminal's or multiplexer's scrollback exactly once, in order: with Overlay Redraw on any terminal, and through a scroll region on terminals that keep rows leaving a region that starts at row 1 (see Strategy A). No UI row enters scrollback while the program runs. Checked against an independent terminal emulator in
crates/ftui-runtime/tests/e2e_inline_mode_scrollback.rs, and in real tmux 3.6 (both transports), GNU screen 4.09 and zellij 0.43 bytests/e2e/scripts/test_inline_scrollback_mux.py. - The UI never draws over a row that has not reached scrollback: the first frame scrolls the shell's last lines up to make room, and a growing inline-auto UI scrolls before drawing. (A terminal resize is the exception: FrankenTUI does not emulate the terminal's reflow.)
- Each present saves and restores the cursor. On exit the final frame stays on screen and the cursor is parked at the start of an empty row below it, so the shell's next output never overwrites part of a UI row.
- With synchronized output each frame is applied atomically. Hybrid and every multiplexer run without it, so a redraw there can briefly show partial rows.
Incremental View Maintenance (IVM)
Status: experimental (see Experimental modules)
The idea is to stop recomputing layouts, styled text, and visibility flags from scratch every frame, and instead propagate deltas through a DAG of view operators — the technique materialized-view databases use (Materialize, Noria), adapted for frame-rate rendering.
Where it runs: nowhere. There is no propagation engine. ftui_runtime::ivm has the pieces such an engine would need and not the engine itself, verified 2026-09-19:
- Nothing walks the DAG feeding one view's output into the next. The module's only
usestatements arestd::fmtandstd::hash, so no delta can reach aBufferor the presenter. - An earlier version of this section showed a diagram with
StyleMap,TextWrap,FlexSolveandRenderPlanoperators, and said theme-change deltas flow toRenderPlanwithout re-running wrapping or constraint solving. None of those four types exist, and neither do theLayoutView/RenderViewthat the module's own docs named — the two descriptions did not even agree with each other. FRANKENTUI_FULL_RECOMPUTE=1is read byIvmConfig::from_env, but nothing reads the resulting flag, so it changes no behaviour.
What does exist, and is tested: the signed-tuple delta algebra ((key, weight, logical_time) with cancellation), a DAG with topological ordering and cycle detection, a fallback-policy predicate, and two IncrementalView implementations (StyleResolutionView, FilteredListView). Useful groundwork; not something you can turn on.
Before anyone builds the engine, note that the render cost surface measured on 2026-09-19 found buffer_diff to be the cheapest pipeline stage at 4.5–9.1% of the frame, while cell_mutation and presenter_emit dominate (docs/perf/cost_surface_stage_dominance_2026-09-19.md). An incremental layer that avoids recomputation has to beat simply doing the work — which is the measurement that stopped the e-graph. Scoped permanently to the delta algebra, DAG topology, and view library (bd-lksq7).
SOS Barrier Certificates
Status: experimental (see Experimental modules)
The module offers a frame-budget admissibility test built on a polynomial barrier certificate in the sum-of-squares style. It is not used for frame admissibility in the runtime (which is decided by ConformalPredictor and BudgetController) — see Where it runs below — so the present tense here describes the function, not the render path:
State space:
x₁ = budget_remaining ∈ [0, 1] (fraction of frame budget left)
x₂ = change_rate ∈ [0, 1] (estimated render cost)
Barrier certificate B(x₁, x₂):
B(x₁, x₂) = Σ cᵢⱼ x₁ⁱ x₂ʲ (polynomial, degree 4, 15 terms)
Safety:
B(x) > 0 ⟹ state is admissible (safe to render at full fidelity)
B(x) ≤ 0 ⟹ state is at or beyond the unsafe boundary
Provenance: the coefficients are hand-chosen, not SDP-solved. sos_barrier_coeffs.rs says so itself — they were written by hand (2026-03-05) to satisfy eight verification points, and have not been verified by an SDP solver. An earlier version of this section claimed an SOS/SDP relaxation produced them; the 2026-09-01 reality check found that claim false, the source header was corrected, and this section was updated to match. If a solver is ever added, regenerate the coefficients from it and record the solver, its inputs and the run date in that file.
So what the evaluator gives you is a polynomial admissibility test whose shape was chosen by hand, not a certificate carrying an SOS proof of the Lyapunov-like decrease condition.
Where it runs: nowhere. Nothing in any crate's src/ imports ftui_runtime::sos_barrier, so no frame's budget is actually checked against the barrier. An earlier correction of this section said the evaluator "runs in constant time per frame with no allocations" — true of the function's complexity, misleading about its use, since nothing calls it per frame or at all. sos_barrier.rs is allocation-free and constant-time when called, which is the part worth relying on if you call it yourself.
Why SOS instead of a simple threshold? A polynomial barrier can encode nonlinear safe/unsafe boundaries that accurately reflect the interaction between budget remaining and workload estimate. A flat threshold either triggers too early (wasting visual quality) or too late (missing the deadline).
S3-FIFO Cache
Grapheme width lookups (ftui_core::text_width) use an S3-FIFO eviction policy, which was shown to match or outperform W-TinyLFU and ARC on most workloads while being simpler to implement (terminal capability detection is not cached; it runs once per session):
Three queues:
Small (10% capacity) ← new entries land here
Main (90% capacity) ← promoted entries (accessed ≥ 1 time in Small)
Ghost (keys only) ← recently evicted keys for frequency tracking
Eviction from Small:
if accessed ≥ 1 time → promote to Main
else → evict (key goes to Ghost)
Eviction from Main (FIFO + frequency):
if freq > 0 → decrement freq, re-insert at tail
else → evict permanently
The key insight: S3-FIFO is scan-resistant without the overhead of an LRU doubly-linked list. Sequential access patterns (like scanning a large buffer) don't flush the cache.
Flat Combining
Status: experimental (see Experimental modules)
When multiple event sources (timers, background tasks, input) post operations concurrently, flat combining batches them into a single pass. One thread becomes the "combiner" and executes ALL pending operations while holding the state lock:
Thread 1: post(op_a) → wait
Thread 2: post(op_b) → wait combiner (Thread 3):
Thread 3: post(op_c) → becomes lock state
combiner execute op_a
execute op_b
execute op_c
unlock state
wake threads 1, 2
Benefits over a bare Mutex:
- Data stays hot in L1 cache (one thread touches everything)
- Lock acquisition happens once per batch, not once per operation
- Natural coalescing: redundant operations (multiple redraws) collapse
Where it runs: nowhere. Nothing in any crate's src/ imports ftui_runtime::flat_combine, and the runtime's event sources do not post through a combiner. The diagram above describes what the module implements, not how FrankenTUI dispatches operations today.
Bidirectional Lenses
Status: experimental (see Experimental modules)
The lens module provides algebraic lenses for binding widgets to model subfields:
use ;
// A lens focuses on one part of a larger structure
let volume = field_lens;
// Laws: GetPut (setting what you just read is a no-op),
// PutGet (you read back exactly what you set)
let mut config = Config ;
assert_eq!;
volume.set;
assert_eq!;
assert_eq!; // other fields untouched
Lenses compose, so compose(config_lens, volume_lens) creates a lens from AppState directly to volume through an intermediate Config struct.
Where it runs: nowhere. The module is titled "state-widget binding", but no widget binds through a lens: nothing in any crate's src/ imports ftui_runtime::lens. The laws hold and the example above is compiled by readme_snippets; what is missing is anything on the widget side that consumes one.
Input Macro Recording & Playback
The InputMacro system records terminal events with timing for deterministic replay:
// Record
let mut recorder = new;
recorder.record_event;
recorder.record_event_with_delay;
recorder.record_event;
recorder.record_event;
let macro_data = recorder.finish;
// Replay through ProgramSimulator (replay_with_timing honors the recorded delays)
new.replay_all;
Uses: regression testing, demo recording, user workflow capture. The macro_recorder demo screen shows this in action.
State Persistence
Widget state survives across sessions via the StateRegistry:
┌───────────────────────────────────────────────────────────────┐
│ StateRegistry │
│ In-memory cache of widget states (HashMap<WidgetId, State>) │
│ Delegates to StorageBackend for persistence │
└───────────────────────────────┬───────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
FileStorage MemoryStorage impl StorageBackend
(JSON on disk) (tests only) (user-provided)
Configuration:
use ;
use Arc;
// In-memory registry needs no feature; `StateRegistry::with_file(path)` (JSON on
// disk, atomic writes) needs ftui-runtime's `state-persistence` feature.
let registry = new;
let config = default.with_persistence;
Widgets opt in by implementing the Stateful trait. On program start, the registry loads saved state; on exit (or periodic checkpoints), it flushes back to the backend.
Where it runs: opt-in via ProgramConfig::with_persistence(..) (Program loads/flushes the configured StateRegistry on startup, shutdown, periodic checkpoints, and Cmd::SaveState / Cmd::RestoreState; Stateful is implemented by ListState, TableState, TreeState, TextAreaState, and VirtualizedListState, and callers synchronize their widget states with the registry explicitly).
SLO Schema & Breach Detection
Status: experimental (see Experimental modules)
FrankenTUI supports machine-readable Service Level Objectives for runtime behavior:
# slo.yaml - the schema parse_slo_yaml actually accepts
regression_threshold: 0.10
noise_tolerance: 0.05
safe_mode_breach_count: 2
safe_mode_error_rate: 0.05
metrics:
render_p99:
metric_type: latency
max_value: 16000.0
max_ratio: 1.25
safe_mode_trigger: true
shutdown_us:
metric_type: latency
max_value: 5000.0
safe_mode_trigger: false
metrics is a map keyed by metric name, not a list. regression_threshold
and noise_tolerance are global fractions in [0.0, 1.0]; max_value is an
absolute ceiling and max_ratio a multiple of the baseline; safe_mode_trigger
makes one breach trip safe mode on its own, while safe_mode_breach_count
covers simultaneous breaches. metric_type accepts exactly latency, memory
and error_rate — anything else is an UnknownMetricType error.
Note the parser skips whole-line # comments but does not strip trailing
ones, so max_value: 16000.0 # ceiling fails to parse. Keep annotations on
their own lines.
The project's own slo.yaml is the worked example, and
slo_yaml_parses_without_errors keeps it parsing.
An earlier version of this block documented an objectives: list with
metric / budget_us / window_seconds / error_budget_pct keys. No such
schema exists — not in the parser, and not in the repository's own slo.yaml,
which has used the fields above all along. Because an empty document parses to
defaults, copying the old example produced a schema with zero metrics rather
than failing loudly. readme_slo_yaml_example_parses now pins the block above
byte-for-byte against the parser so it cannot drift again.
The SLO engine checks observations against budgets and tracks error-budget consumption:
slo.yaml ──parse──▶ SloSchema
│
observations ──▶ check_breach() ──▶ BreachResult
│
┌──────────┴──────────┐
▼ ▼
No breach Breach detected
(continue) (enter safe mode)
When an SLO is breached, safe mode (reduced rendering, aggressive coalescing) is meant to hold until the error budget recovers.
Where it runs: nowhere. Nothing in any crate's src/ imports ftui_runtime::slo, so nothing feeds it observations and nothing acts on a BreachResult — the runtime does not enter safe mode from this path, because no code path reaches it. The parser, the breach check and the error-budget accounting are implemented and covered by tests in ftui-harness.
Multi-Stage Conformal Monitoring
Status: experimental (see Experimental modules)
The design gives each render pipeline stage an independent conformal monitor:
view() → [Layout] → Buffer → [Diff] → Changes → [Present] → ANSI
↑ ↑ ↑
stage monitor stage monitor stage monitor
(calibration) (calibration) (calibration)
Each stage would maintain its own Mondrian-bucketed residual set, so a regression in layout computation is detected independently from diff or presenter regressions. Buckets are keyed by (screen mode, diff strategy, terminal size) and fall back to coarser groupings when data is sparse. The point of the granularity is to identify which pipeline stage is responsible for a slowdown rather than just flagging "frame was slow."
Where it runs: nowhere. StagedConformalPredictor is never constructed outside its own unit tests — nothing in any crate's src/ imports ftui_runtime::conformal_stages, and no stage timing is fed to it, so the runtime cannot currently attribute a slowdown to a stage. The bucketing, calibration and alerting logic are implemented and tested.
Not to be confused with conformal_predictor, which is on by default in the runtime and monitors whole-frame timing. That one is real; this one is the per-stage version that was never connected.
Headless Simulator
The ProgramSimulator runs a Model without a real terminal, enabling deterministic testing:
use ProgramSimulator;
let mut sim = new;
sim.init;
sim.send;
sim.tick;
// Capture rendered output without a terminal
let frame = sim.capture_frame;
assert_eq!;
assert_eq!;
assert!;
The simulator is the backbone of the shadow-run comparison system and the rollout scorecard. It powers every harness test without needing a PTY or terminal emulator.
Frame Arena Allocator
The render hot path uses a bump allocator reset at frame boundaries, eliminating per-frame allocator churn:
let mut arena = new; // 256 KB initial
// During frame rendering: bump-allocate transient strings
let label: &str = arena.alloc_str;
let cell_text: &str = arena.alloc_fmt;
// At frame boundary:
arena.reset; // O(1), no individual deallocations
Why bump allocation? The render path produces many small, short-lived allocations (styled text spans, layout rectangles, change runs). A bump allocator satisfies these in O(1) with zero fragmentation, and reset() reclaims everything in a single pointer write.
Where it runs: FrameArena (BumpVec, BumpString) lives in ftui-core::arena (re-exported by ftui-render::arena). Program and StepProgram reset and attach a shared FrameArena to each Frame (frame.arena()), consumed on the render hot path by ftui_text::wrap (wrap_text_in, wrap_with_options_in, wrap_text_optimal_in), ftui_layout::Flex (split_in, split_with_measurer_in, solve_constraints_with_hints_into), ftui_widgets::{paragraph::Paragraph, table::Table, tabs::Tabs, input::TextInput}, and the showcase's dashboard screen. Measured in alloc_count_bench: 0 allocs/frame (0 B, down from 1,397 allocs / 142,688 B) on the 80×24 ASCII dashboard and 3 allocs/frame (42 B in GraphemePool::intern, down 99.5% from 661 allocs / 79,962 B) on the 80×24 Unicode dashboard.
Color System
The ftui-style color module supports multiple color profiles with automatic downgrade:
| Profile | Colors | When Used |
|---|---|---|
TrueColor |
16M (24-bit RGB) | Modern terminals with COLORTERM=truecolor |
Ansi256 |
256 | Terminals with 256-color support |
Ansi16 |
16 | Basic terminals |
Mono |
2 | NO_COLOR set, or dumb terminals |
Color downgrade is automatic based on terminal capability detection:
TrueColor RGB(128, 0, 255)
→ Ansi256: round channels to the 6×6×6 cube; exact grays choose the closer cube/ramp candidate by weighted RGB distance
→ Ansi16: map to closest basic color
→ Mono: drop color entirely, keep bold/underline for emphasis
The module includes WCAG 2.1 contrast ratio utilities for accessibility checking:
let ratio = contrast_ratio;
// WCAG AA: ratio ≥ 4.5 for normal text, ≥ 3.0 for large text
// WCAG AAA: ratio ≥ 7.0 for normal text, ≥ 4.5 for large text
Perceived luminance uses the standard formula: Y = 0.2126R + 0.7152G + 0.0722B (linearized sRGB).
Evidence Sink Architecture
Every probabilistic decision in FrankenTUI is logged to a shared evidence sink, a structured JSONL stream that captures the reasoning behind runtime behavior:
let config = default
.with_evidence_sink;
Evidence events actually written by the runtime (grep for the "event" value):
diff_decision: which diff strategy was chosen and why (Beta posterior, cost estimates, fallback reason)decision,decision_evidence,regime_transition,summary: the resize coalescer's apply-vs-coalesce choices with their log10 Bayes-factor ledger and steady/burst regime changesbudget_decision: the conformal frame-time gate (bucket, quantile, upper bound, risk) together with the degradation tier chosen before and after the frameguardrail_snapshot: memory and effect-queue guardrail state whenever a guardrail fires (queue depth is the live effect backlog)voi_decision: the inline-auto height sampler's value-of-information decision (posterior, gain, cost, e-value)capability_decision: one row per session for truecolor, synchronized output and the scroll-region policy: environment detection, probe outcome, multiplexer veto, operator switch, and the log-odds ledger behind the final valueinline_strategy: which inline strategy the writer selected from those capabilities (scroll_region,hybrid,overlay_redraw) and where log lines go (log_transport:decstbm,scroll_repaint— the overlay whole-screen stream — orsingle_rowfor a top-anchored overlay, whose logs do not reach scrollback)fairness_config/fairness_decision: the input-fairness guard's Jain-index decisionseffect_queue_select: scheduler job selection when theEffectQueueexecutor backend is enabledsuspend/resume: a job-control stop served (signal, size) and the resume after it (size_changed)widget_refresh,certificate_decision,task_executor_*: widget refresh plans, presenter certificates, and executor lifecycle
Why evidence? When a frame is slow, operators can grep the JSONL for that frame index and see exactly which decisions were made and what statistical state drove them. No black boxes.
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 License (with OpenAI/Anthropic Rider) © 2026 Jeffrey Emanuel. See LICENSE.