FrankenTUI

https://frankentui.com
Admin
FrankenTUI is a high-performance TUI kernel built in Rust with deterministic rendering, compiles to...
Tokens:12,201
Snippets:251
Trust Score:4.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Resizable Widget Integration

Source: https://frankentui.com/web_react

Integrate the FrankenTerminal React component into your application. This example demonstrates basic usage with common props for sizing and behavior.

```APIDOC
## Resizable Widget

Embed a live FrankenTUI terminal in any React page. Three lines of code, full GPU-accelerated rendering, automatic resize handling.

### Integration Example

```javascript
import FrankenTerminal from "@/components/franken-terminal";

<FrankenTerminal
  width="100%"
  height={400}
  captureKeys={false}
  showStatus
/>
```

## Props Reference

Key props for sizing, behavior, and callbacks.

| Prop          | Type    | Default   | Description                                  |
|---------------|---------|-----------|----------------------------------------------|
| width         | number  | string    | "100%"    | CSS width of the container                   |
| height        | number  | string    | "400px"   | CSS height of the container                  |
| captureKeys   | boolean | true      | Capture keyboard events when focused         |
| showStatus    | boolean | true      | Show cols×rows overlay                       |
| loadTextAssets| boolean | true      | Load 14MB text assets (Shakespeare, SQLite)  |
| autoFocus     | boolean | false     | Focus the canvas on mount                    |
| zoom          | number  | 1.0       | Initial zoom level                           |
| onReady       | () => void| —         | Fired when WASM loads and first frame renders|
| onResize      | (cols, rows) => void | — | Fired when terminal grid resizes             |
| onError       | (error) => void | — | Fired on WASM load failure                   |
```

--------------------------------

### State Machines: Terminal + Rendering Pipeline Specification

Source: https://frankentui.com/how-it-was-built/spec-evolution-lab

This document specifies the formal backbone for FrankenTUI, covering terminal and rendering pipeline state machines. It details state variables, safety invariants, and enforcement points for both compile-time and runtime checks. Useful for implementation structure, invariant placement, and test strategy.

```markdown
# State Machines: Terminal + Rendering Pipeline
+
This document is the formal-ish specification backbone for FrankenTUI.
+
It is intentionally written to be directly useful for:
- implementation structure (which module owns what)
- invariant placement (type-level vs runtime checks)
- test strategy (unit/property/PTY)
+
See Bead: bd-10i.13.1.
+
---
+
## 1) Terminal State Machine
+
### 1.1 State Variables
We model the terminal as a state machine that consumes bytes and updates a display grid.
+
Minimal state (conceptual):
- `cursor`: (x, y)
- `style`: current SGR state (fg/bg/attrs)
- `grid`: a width×height array of `Cell`
- `mode`: Normal | Raw | AltScreen
+
ftui-specific derived state:
- `link_state`: OSC 8 hyperlink open/close tracking
- `cursor_visible`: bool
- `sync_output`: bool (DEC 2026 nesting/active)
- `scroll_region`: optional (top..bottom) margins
+
### 1.2 Safety Invariants
- Cursor bounds: `0 <= x < width`, `0 <= y < height`.
- Grid validity: every cell is a valid `Cell` value.
- Mode cleanup: on exit, Raw/AltScreen/mouse/paste/focus modes are restored to safe defaults.
+
### 1.3 Where This Is Enforced
Type-level (compile-time-ish):
- `TerminalSession` owns terminal lifecycle so that cleanup cannot be “forgotten”.
+
Runtime checks:
- bounds checks on cursor moves (or explicit clamping policy)
- internal assertions in debug builds for invariants
+
Tests:
- PTY tests validate cleanup invariants under normal exit + panic.
+
Implementation module targets (will be updated as code lands):
- Terminal lifecycle + cleanup: `crates/ftui-core/src/terminal_session.rs`
- Capability model: `crates/ftui-core/src/terminal_capabilities.rs`
+
---
+
## 2) Rendering Pipeline State Machine
+
### 2.1 States
States (from plan):
- Idle
- Measuring
- Rendering
- Diffing
- Presenting
- Error
+
### 2.2 Transitions
- Idle → Measuring (render request)
- Measuring → Rendering (layout complete)
- Rendering → Diffing (draw complete)
- Diffing → Presenting (diff computed)
- Presenting → Idle (present complete)
- * → Error (I/O error, internal invariant violation)
- Error → Idle (recover)
+
### 2.3 Pipeline Invariants
I1. In Rendering state, only the back buffer is modified.
I2. In Presenting state, only ANSI output is produced.
I3. After Presenting, front buffer equals desired grid.
I4. Error state restores terminal to a safe state.
I5. Scissor stack intersection monotonically decreases on push.
I6. Opacity stack product stays in [0, 1].
+
### 2.4 Where This Is Enforced
Type-level:
- Separate “front” vs “back” buffers owned by Frame/Presenter APIs.
+
Runtime checks:
- scissor stack push/pop asserts intersection monotonicity in debug
- opacity stack push/pop clamps and asserts range
+
Tests:
- executable invariant tests (bd-10i.13.2)
- property tests for diff correctness (bd-2x0j)
- terminal-model presenter roundtrip tests (bd-10i.11.1)
+
Implementation module targets (will be updated as code lands):
- Buffer/Cell invariants: `crates/ftui-render/src/buffer.rs`, `crates/ftui-render/src/cell.rs`
- Diff engine: `crates/ftui-render/src/diff.rs`
- Presenter: `crates/ftui-render/src/presenter.rs`
+
---
+
## 3) Notes for Contributors
+
- The goal is not “perfect formalism”; the goal is to prevent drift.
- If you change behavior in Buffer/Presenter/TerminalSession, update this document and add tests.

```

--------------------------------

### Minimal FrankenTUI Counter App

Source: https://frankentui.com/getting-started

A complete, runnable counter application in under 50 lines of Rust code. It demonstrates basic event handling, model updates, and UI rendering using FrankenTUI components. Press 'q' to quit.

```rust
use ftui_core::event::Event;
use ftui_core::geometry::Rect;
use ftui_render::frame::Frame;
use ftui_runtime::{App, Cmd, Model, ScreenMode};
use ftui_widgets::paragraph::Paragraph;

struct TickApp {
    ticks: u64,
}

#[derive(Debug, Clone)]
enum Msg {
    Tick,
    Quit,
}

impl From<Event> for Msg {
    fn from(e: Event) -> Self {
        match e {
            Event::Key(k) if k.is_char('q') => Msg::Quit,
            _ => Msg::Tick,
        }
    }
}

impl Model for TickApp {
    type Message = Msg;

    fn update(&mut self, msg: Msg) -> Cmd<Msg> {
        match msg {
            Msg::Tick => {
                self.ticks += 1;
                Cmd::none()
            }
            Msg::Quit => Cmd::quit(),
        }
    }

    fn view(&self, frame: &mut Frame) {
        let text = format!("Ticks: {}  (press 'q' to quit)", self.ticks);
        let area = Rect::new(0, 0, frame.width(), 1);
        Paragraph::new(text).render(area, frame);
    }
}

fn main() -> std::io::Result<()> {
    App::new(TickApp { ticks: 0 })
        .screen_mode(ScreenMode::Inline { ui_height: 1 })
        .run()
}
```

--------------------------------

### Add FrankenTUI to Rust Project

Source: https://frankentui.com/getting-started

Use this command to add the FrankenTUI kernel to your Rust project dependencies.

```bash
$cargo add ftui
```

--------------------------------

### Bayesian Hint Ranking Formula

Source: https://frankentui.com/architecture

Formula for Bayesian Hint Ranking, which prioritizes keybindings by expected utility, considering VOI and hysteresis for stability.

```plaintext
Vᵢ = E[Uᵢ] + w_voi·√Var(Uᵢ) - λ·Cᵢ
```

--------------------------------

### Fenwick Tree Update and Query

Source: https://frankentui.com/architecture

Illustrates the core operations of a Fenwick Tree (Binary Indexed Tree) for efficient prefix sum calculations. Used for O(log n) positioning in virtualized lists.

```plaintext
update: j += j & -j | query: j -= j & -j
```

--------------------------------

### Git Log: Selected Commits

Source: https://frankentui.com/how-it-was-built

A selection of timestamped git commit messages from the FrankenTUI development sprint, useful for tracking project progress and specific changes.

```git
git log --oneline (selected)
```

```git
[2026-01-31 14:21] 7a23b45a Initial commit: FrankenTUI plan documents
```

```git
[2026-01-31 15:54] 40b720d4 Upgrade plan to V6.1: practice-proven hybrid architecture
```

```git
[2026-01-31 22:27] 6c9158cf Add 15 comprehensive feature beads with 46 subtasks
```

```git
[2026-01-31 23:23] aadc5679 feat: initialize Rust workspace with ftui crate structure
```

```git
[2026-02-01 02:10] ced1e5e7 feat: Add terminal session, color downgrade, style system, and terminal model
```

```git
[2026-02-01 02:15] 0da0ba05 feat: Implement Buffer API and supporting infrastructure
```

```git
[2026-02-01 12:52] 9abb1bf9 feat(ftui-render): Implement BufferDiff with row-major scan
```

```git
[2026-02-01 12:57] aa58e858 feat: Implement Presenter with state-tracked ANSI emission
```

```git
[2026-02-01 13:07] 0baccfdd feat(layout): Add Flex layout solver and terminal_writer fixes
```

```git
[2026-02-01 22:03] 0d03d898 feat: major expansion with demo showcase, PTY improvements, and documentation
```

```git
[2026-02-03 21:36] 02427dbf feat(runtime): add evidence structs and optimize diff buffer reuse
```

```git
[2026-02-04 16:35] 2020c901 docs: crates.io publish prep + crate docs (bd-3lul4)
```

```git
[2026-02-05 01:25] b8f0d6d3 bd-17unx publish 0.1.1 crates
```

```git
[2026-02-05 02:34] 5383ae71 Update changelog for 0.1.1 publish
```

--------------------------------

### Embed Resizable FrankenTUI Widget in React

Source: https://frankentui.com/web_react

Import and use the FrankenTerminal component to embed a live terminal. Set dimensions and optional props for behavior. The component handles WASM loading and resize events automatically.

```javascript
import FrankenTerminal from "@/components/franken-terminal";

<FrankenTerminal
  width="100%"
  height={400}
  captureKeys={false}
  showStatus
/>
```

--------------------------------

### Summed-Area Table (SAT) Formula

Source: https://frankentui.com/architecture

The recursive formula for a 2D Summed-Area Table, enabling O(1) tile density checks by precomputing 2D prefix sums.

```plaintext
SAT(x,y) = A(x,y) + SAT(x-1,y) + SAT(x,y-1) - SAT(x-1,y-1)
```

--------------------------------

### 16-Byte Cell Model Structure

Source: https://frankentui.com/architecture

Defines the structure of a 16-byte cell, optimized for cache alignment and SIMD operations. Includes fields for character/glyph, foreground and background colors, attributes, and link ID.

```rust
struct Cell {
    content: CellContent,
    fg: PackedRgba,
    bg: PackedRgba,
    attrs: CellAttrs,
    link_id: u16,
}
```

--------------------------------

### Jain's Fairness Index Formula

Source: https://frankentui.com/architecture

The formula for Jain's Fairness Index, a scale-independent metric used to ensure rendering does not starve input processing.

```plaintext
F = (Σxᵢ)² / (n·Σxᵢ²)
```

--------------------------------

### Bayesian Capability Detection Formula

Source: https://frankentui.com/architecture

Formula for Bayesian Capability Detection, using log Bayes factors to combine evidence from various noisy signals for robust feature detection.

```plaintext
logit P(feature|E) = logit P(feature) + Σ log BFᵢ
```

--------------------------------

### Porter-Duff Compositing Equation

Source: https://frankentui.com/architecture

The alpha-blending equation for Porter-Duff compositing, enabling full alpha blending with opacity stacks for translucent effects.

```plaintext
C_out = C_src·α_src + C_dst·α_dst·(1-α_src)
```

--------------------------------

### Damped Spring Physics Equation

Source: https://frankentui.com/architecture

The differential equation governing a critically-damped harmonic oscillator, used for natural and smooth animation without overshoot.

```plaintext
x'' + c·x' + k(x - x*) = 0
```

--------------------------------

### Value of Information (VOI) Formula

Source: https://frankentui.com/architecture

The formula for Value of Information (VOI) analysis, used to track which diagnostic measurements improve decisions and optimize telemetry overhead.

```plaintext
VOI = E[max(a,b)|X] - max(E[a],E[b])
```

--------------------------------

### Exponential Moving Average (EMA) Formula

Source: https://frankentui.com/architecture

The formula for Exponential Moving Average, used for smoothed frame-time estimation to enable adaptive budget allocation.

```plaintext
EMA_t = α·x_t + (1-α)·EMA_{t-1}
```

--------------------------------

### Gray-Scott Reaction-Diffusion PDE

Source: https://frankentui.com/architecture

The partial differential equations governing the Gray-Scott model, used as a pattern generator for organic visual effects rendered in terminal cells.

```plaintext
∂u/∂t = Dᵤ∇²u - uv² + F(1-u)
```

--------------------------------

### CUSUM Hover Stabilizer Formula

Source: https://frankentui.com/architecture

The formula for the Cumulative Sum (CUSUM) change-point detector used to stabilize hover targets by suppressing mouse jitter.

```plaintext
S_t = max(0, S_{t-1} + d_t - k)
```

--------------------------------

### Bayesian Fuzzy Scoring Formula

Source: https://frankentui.com/architecture

The formula for Bayesian Fuzzy Scoring, using posterior odds and Bayes factors to rank command palette matches based on various clues.

```plaintext
P(R|E)/P(¬R|E) = P(R)/P(¬R) × Π BFᵢ
```

--------------------------------

### Bayesian Height Prediction Formula

Source: https://frankentui.com/architecture

The Normal-Normal conjugate update formula for Bayesian Height Prediction, used to estimate unseen row heights and prevent scroll jumps in lists.

```plaintext
μₙ = (κ₀·μ₀ + n·x̄) / (κ₀ + n)
```

--------------------------------

### Dirty-Span Interval Union

Source: https://frankentui.com/architecture

Represents the union of dirty spans within a row, used to optimize diffing by scanning only the changed intervals.

```plaintext
Sᵧ = ∪ₖ [x₀ₖ, x₁ₖ)
```
Tokens:
Raw