One-writer rule

When FrankenTUI is active, only one entity writes to the terminal — the TerminalWriter owned by your TerminalSession. Any other code that reaches stdout or stderr during a running FrankenTUI session produces undefined behaviour.

This is not a style guide. It is a correctness invariant with teeth.

Source: crates/ftui-runtime/src/terminal_writer.rs + docs/one-writer-rule.md + docs/adr/ADR-005-one-writer-rule.md.

Why one writer

Terminals are shared mutable state with a cursor, a current SGR state, and a mode flag (raw / cooked, alt-screen on/off, mouse on/off). If two entities write concurrently, every one of those pieces of state becomes unpredictable. Concretely:

• Cursor drift. Two writers each think they know where the cursor is; both move it; the UI draws in the wrong place.
• Partial sequences. One writer emits half of a CSI sequence, the other writer emits a byte, and the terminal interprets the result as garbage.
• Interleaved output. UI frames and log lines bleed into each other.
• State corruption. Raw mode gets flipped off by a library that thinks it owns stdout; alt-screen never gets exited; the terminal is unusable after exit.

Inline mode is especially sensitive because it overlays UI on the scrollback — every stray byte lives in the user’s history forever.

What counts as terminal output

How it is enforced

TerminalWriter is the single gateway. Every byte that reaches the terminal during a session goes through it:

Model::view  ──▶  Frame  ──▶  Buffer  ──▶  BufferDiff
                                                │
       LogSink ─────────────────────────┐       ▼
       PtyCapture ──────────────────────┼──▶  TerminalWriter ──▶ BackendPresenter ──▶ TTY
       StdioCapture (feature-gated) ────┘

• TerminalSession (from ftui-core) owns the raw-mode + alt-screen lifecycle and constructs the single TerminalWriter.
• TerminalWriter (from ftui-runtime) serialises all writes and coordinates with the presenter’s SGR state machine.
• RAII cleanup. When TerminalSession drops — normal exit or panic — it restores the terminal to sane state. This is why the one-writer rule must hold: if another writer can race with the drop, cleanup gets interleaved with whatever the other writer is doing.

Approved routing patterns

There are three patterns for getting non-UI output onto the terminal. Pick based on where the bytes come from.

A. LogSink — in-process logs

For logs your own code produces.

use ftui::LogSink;
use std::io::Write;
 
fn main() -> Result<()> {
    let app = App::new()?;
    let log = app.log_sink();
 
    writeln!(log, "Starting process…")?;
    writeln!(log, "Loaded {} items", count)?;
 
    app.run()
}

• LogSink implements std::io::Write.
• Output is sanitised by default — CSI / OSC / DCS / APC sequences are stripped, only TAB / LF / CR C0 controls are kept. See ADR-006 .
• Thread-safe: clone the sink and write from multiple threads.

B. PtyCapture — subprocess output

For external tools you spawn (cargo, git, make, a shell command).

use ftui::pty::PtyCapture;
 
fn main() -> Result<()> {
    let app = App::new()?;
    let capture = PtyCapture::spawn(&["cargo", "build"])?;
    app.attach_pty(capture);
    app.run()
}

• The subprocess runs under a real pseudo-terminal — it can’t tell the difference, so it emits progress bars and colours normally.
• ANSI sequences from trusted tools can be preserved with pty.set_passthrough_sgr(true). Leave it off for anything that consumes untrusted input.

C. StdioCapture — best-effort safety net

For catching accidental writes from libraries you don’t control.

use ftui::StdioCapture;
 
fn main() -> Result<()> {
    let _guard = StdioCapture::enable()?; // BEFORE App::new
    let app = App::new()?;
    app.run()
}

• Feature-gated: features = ["stdio-capture"].
• Best effort, not 100% reliable. Native code, FFI calls, or processes that dup stdout past it will still slip through.
• Adds runtime overhead. Prefer as a safety net, not a primary strategy.

What happens if you violate the rule

There is no helpful error. The terminal just misbehaves. That is why this is the first thing to audit when a user reports “weird rendering”.

Debugging output issues

rg --type rust 'println!|eprintln!|std::io::stdout|io::stdout\(\)\.write'

rg --type rust 'Command::new\(|std::process::Command'

Mux and passthrough notes

Under tmux, screen, or zellij:

1. Passthrough mode may be needed for some features (e.g. OSC 52 clipboard, synchronised output).
2. set-clipboard on in tmux is required for clipboard shortcuts.
3. Bracketed paste works with modern mux versions.
4. FrankenTUI auto-detects mux environment and adjusts; you don’t need to configure this in application code.

# ~/.tmux.conf
set -g set-clipboard on
set -g allow-passthrough on

Quick reference

// DO — use LogSink for your logs
let log = app.log_sink();
writeln!(log, "status: {}", status)?;
 
// DO — use PTY capture for subprocesses
let pty = PtyCapture::spawn(&["my-tool"])?;
app.attach_pty(pty);
 
// DON'T — direct terminal writes
println!("status: {}", status);          // BAD
 
// DON'T — raw subprocess without PTY
Command::new("my-tool").spawn()?;        // BAD

Pitfalls

Related