Struct TerminalWriter 

pub struct TerminalWriter<W: Write> { /* private fields */ }

Unified terminal output coordinator.

Enforces the one-writer rule and implements inline mode correctly. All terminal output should go through this struct.

Implementations

impl<W: Write> TerminalWriter<W>

pub fn new( writer: W, screen_mode: ScreenMode, ui_anchor: UiAnchor, capabilities: TerminalCapabilities, ) -> Self

Create a new terminal writer.

Arguments

• writer - Output destination (takes ownership for one-writer rule)
• screen_mode - Inline or alternate screen mode
• ui_anchor - Where to anchor UI in inline mode
• capabilities - Terminal capabilities

pub fn with_diff_config( writer: W, screen_mode: ScreenMode, ui_anchor: UiAnchor, capabilities: TerminalCapabilities, diff_config: RuntimeDiffConfig, ) -> Self

Create a new terminal writer with custom diff strategy configuration.

Arguments

• writer - Output destination (takes ownership for one-writer rule)
• screen_mode - Inline or alternate screen mode
• ui_anchor - Where to anchor UI in inline mode
• capabilities - Terminal capabilities
• diff_config - Configuration for diff strategy selection

Example

use ftui_runtime::{TerminalWriter, ScreenMode, UiAnchor, RuntimeDiffConfig};
use ftui_core::terminal_capabilities::TerminalCapabilities;

// Disable Bayesian selection for deterministic diffing
let config = RuntimeDiffConfig::default()
    .with_bayesian_enabled(false);

let writer = TerminalWriter::with_diff_config(
    std::io::stdout(),
    ScreenMode::AltScreen,
    UiAnchor::Bottom,
    TerminalCapabilities::detect(),
    config,
);

pub fn diff_config(&self) -> &RuntimeDiffConfig

Get the current diff configuration.

pub fn with_evidence_sink(self, sink: EvidenceSink) -> Self

Attach an evidence sink for diff decision logging.

pub fn set_evidence_sink(&mut self, sink: Option<EvidenceSink>)

Set the evidence JSONL sink for diff decision logging.

pub fn with_render_trace(self, recorder: RenderTraceRecorder) -> Self

Attach a render-trace recorder.

pub fn set_render_trace(&mut self, recorder: Option<RenderTraceRecorder>)

Set the render-trace recorder.

pub fn diff_strategy_mut(&mut self) -> &mut DiffStrategySelector

Get mutable access to the diff strategy selector.

Useful for advanced scenarios like manual posterior updates.

pub fn diff_strategy(&self) -> &DiffStrategySelector

Get the diff strategy selector (read-only).

pub fn last_diff_strategy(&self) -> Option<DiffStrategy>

Get the last diff strategy selected during present, if any.

pub fn set_size(&mut self, width: u16, height: u16)

Set the terminal size.

Call this when the terminal is resized.

pub fn take_render_buffer(&mut self, width: u16, height: u16) -> Buffer

Take a reusable render buffer sized for the current frame.

Uses a spare buffer when available to avoid per-frame allocation.

pub fn width(&self) -> u16

Get the current terminal width.

pub fn height(&self) -> u16

Get the current terminal height.

pub fn screen_mode(&self) -> ScreenMode

Get the current screen mode.

pub fn render_height_hint(&self) -> u16

Height to use for rendering a frame.

In inline auto mode, this returns the configured maximum (clamped to terminal height) so measurement can determine actual UI height.

pub fn inline_auto_bounds(&self) -> Option<(u16, u16)>

Get sanitized min/max bounds for inline auto mode (clamped to terminal height).

pub fn auto_ui_height(&self) -> Option<u16>

Get the cached auto UI height (inline auto mode only).

pub fn set_auto_ui_height(&mut self, height: u16)

Update the computed height for inline auto mode.

pub fn clear_auto_ui_height(&mut self)

Clear the cached auto UI height (inline auto mode only).

pub fn ui_height(&self) -> u16

Get the UI height for the current mode.

pub fn inline_strategy(&self) -> InlineStrategy

Get the inline mode rendering strategy.

pub fn scroll_region_active(&self) -> bool

Check if a scroll region is currently active.

pub fn present_ui( &mut self, buffer: &Buffer, cursor: Option<(u16, u16)>, cursor_visible: bool, ) -> Result<()>

Present a UI frame.

In inline mode, this:

1. Begins synchronized output (if supported)
2. Saves cursor position
3. Moves to UI region and clears it
4. Renders the buffer using the presenter
5. Restores cursor position
6. Moves cursor to requested UI position (if any)
7. Applies cursor visibility
8. Ends synchronized output

In AltScreen mode, this just renders the buffer and positions cursor.

pub fn present_ui_owned( &mut self, buffer: Buffer, cursor: Option<(u16, u16)>, cursor_visible: bool, ) -> Result<()>

Present a UI frame, taking ownership of the buffer (O(1) — no clone).

Prefer this over [present_ui] when the caller has an owned buffer that won’t be reused, as it avoids an O(width × height) clone.

pub fn write_log(&mut self, text: &str) -> Result<()>

Write log output (goes to scrollback region in inline mode).

In inline mode, this writes to the log region (above UI for bottom-anchored, below UI for top-anchored). The cursor is explicitly positioned in the log region before writing to prevent UI corruption.

If the UI consumes the entire terminal height, there is no log region available and the write becomes a no-op.

In AltScreen mode, logs are typically not shown (returns Ok silently).

pub fn clear_screen(&mut self) -> Result<()>

Clear the screen.

pub fn hide_cursor(&mut self) -> Result<()>

Hide the cursor.

pub fn show_cursor(&mut self) -> Result<()>

Show the cursor.

pub fn flush(&mut self) -> Result<()>

Flush any buffered output.

pub fn pool(&self) -> &GraphemePool

Get the grapheme pool for interning complex characters.

pub fn pool_mut(&mut self) -> &mut GraphemePool

Get mutable access to the grapheme pool.

pub fn links(&self) -> &LinkRegistry

Get the link registry.

pub fn links_mut(&mut self) -> &mut LinkRegistry

Get mutable access to the link registry.

pub fn pool_and_links_mut(&mut self) -> (&mut GraphemePool, &mut LinkRegistry)

Borrow the grapheme pool and link registry together.

This avoids double-borrowing self at call sites that need both.

pub fn capabilities(&self) -> &TerminalCapabilities

Get the terminal capabilities.

pub fn into_inner(self) -> Option<W>

Consume the writer and return the underlying writer.

Performs cleanup operations before returning. Returns None if the buffer could not be flushed.

pub fn gc(&mut self)

Perform garbage collection on the grapheme pool.

Frees graphemes that are not referenced by the current front buffer (prev_buffer). This should be called periodically (e.g. every N frames) to prevent memory leaks in long-running applications with dynamic content (e.g. streaming logs with emoji).

Trait Implementations

impl<W: Write> Drop for TerminalWriter<W>

fn drop(&mut self)

Executes the destructor for this type.