Struct Terminal 

pub struct Terminal<B: Backend> { /* private fields */ }

Renderer that manages live and pinned blocks over a terminal backend.

A terminal starts by hiding the cursor. Callers mutate blocks, call Terminal::render when they want output, and call Terminal::finish to leave the live transcript behind and restore terminal state.

Implementations

impl Terminal<StdoutBackend<Stdout>>

pub fn stdout() -> Result<Self>

Creates a terminal that renders to process stdout.

Examples found in repository

examples/conversation.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

impl<B: Backend> Terminal<B>

pub fn new(backend: B) -> Result<Self>

Creates a terminal over backend and hides the cursor.

pub fn backend(&self) -> &B

Returns the backend used by this terminal.

This is primarily useful for tests and backend-specific inspection. Prefer the renderer APIs for normal terminal output.

pub fn backend_mut(&mut self) -> &mut B

Returns mutable access to the backend used by this terminal.

Direct backend writes can invalidate the renderer’s cached screen assumptions. After writing through this escape hatch, call Terminal::force_full_redraw before the next Terminal::render so the renderer recovers with a full rewrite.

pub fn push_live(&mut self, block: impl Render + 'static) -> Result<()>

Appends an unidentified live block before pinned blocks.

Live blocks form the durable conversation transcript and are left behind by Terminal::finish.

Examples found in repository

examples/conversation.rs (line 244)

fn submit_input<B: mural::Backend>(
    terminal: &mut Terminal<B>,
) -> Result<String, Box<dyn std::error::Error>> {
    let submitted = {
        terminal
            .pinned_block_mut::<Padding<Textarea>>("input")?
            .content_mut()
            .take()
    };

    terminal.push_live(live_padded(user_message(&submitted)?))?;
    render_frame(terminal)?;
    Ok(submitted)
}

pub fn push_pinned(&mut self, block: impl Render + 'static) -> Result<()>

Appends an unidentified pinned block after all live blocks.

Pinned blocks are useful for status UI and are removed during Terminal::finish.

Examples found in repository

examples/conversation.rs (line 21)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

pub fn insert_live( &mut self, id: impl Into<String>, block: impl Render + 'static, ) -> Result<(), TerminalError>

Appends an identified live block.

Identified blocks can later be mutated with Terminal::live_block_mut or removed with Terminal::remove_live. Ids are unique across live and pinned regions.

Examples found in repository

examples/conversation.rs (line 48)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

pub fn insert_pinned( &mut self, id: impl Into<String>, block: impl Render + 'static, ) -> Result<(), TerminalError>

Appends an identified pinned block.

Identified pinned blocks can later be mutated with Terminal::pinned_block_mut or removed with Terminal::remove_pinned.

Examples found in repository

examples/conversation.rs (line 22)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

pub fn live_block_mut<T: 'static>( &mut self, id: &str, ) -> Result<&mut T, TerminalError>

Returns typed mutable access to an identified live block.

Successful mutable access marks the block dirty so the next render will rerender it.

Examples found in repository

examples/conversation.rs (line 64)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

pub fn pinned_block_mut<T: 'static>( &mut self, id: &str, ) -> Result<&mut T, TerminalError>

Returns typed mutable access to an identified pinned block.

Successful mutable access marks the block dirty so the next render will rerender it.

Examples found in repository

examples/conversation.rs (line 212)

fn type_into_input<B: mural::Backend>(
    terminal: &mut Terminal<B>,
    content: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    for ch in content.chars() {
        terminal
            .pinned_block_mut::<Padding<Textarea>>("input")?
            .content_mut()
            .insert_char(ch);
        render_frame(terminal)?;
    }
    Ok(())
}

fn move_input_left<B: mural::Backend>(
    terminal: &mut Terminal<B>,
    steps: usize,
) -> Result<(), Box<dyn std::error::Error>> {
    for _ in 0..steps {
        terminal
            .pinned_block_mut::<Padding<Textarea>>("input")?
            .content_mut()
            .move_left();
        render_frame(terminal)?;
    }
    Ok(())
}

fn submit_input<B: mural::Backend>(
    terminal: &mut Terminal<B>,
) -> Result<String, Box<dyn std::error::Error>> {
    let submitted = {
        terminal
            .pinned_block_mut::<Padding<Textarea>>("input")?
            .content_mut()
            .take()
    };

    terminal.push_live(live_padded(user_message(&submitted)?))?;
    render_frame(terminal)?;
    Ok(submitted)
}

fn show_status<B: mural::Backend>(
    terminal: &mut Terminal<B>,
    content: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    terminal
        .pinned_block_mut::<Padding<AnswerStatus>>("status")?
        .content_mut()
        .show(content)?;
    Ok(())
}

fn hide_status<B: mural::Backend>(
    terminal: &mut Terminal<B>,
) -> Result<(), Box<dyn std::error::Error>> {
    terminal
        .pinned_block_mut::<Padding<AnswerStatus>>("status")?
        .content_mut()
        .hide();
    Ok(())
}

pub fn remove_live(&mut self, id: &str) -> Result<(), TerminalError>

Removes an identified live block.

Examples found in repository

examples/conversation.rs (line 50)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

pub fn remove_pinned(&mut self, id: &str) -> Result<(), TerminalError>

Removes an identified pinned block.

pub fn is_block_dirty(&self, id: &str) -> Result<bool, TerminalError>

Reports whether an identified block is dirty and will be rerendered.

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

Forces the next render to recover by rewriting the full managed screen buffer.

Use this after direct writes through Terminal::backend_mut or after any external terminal interaction that may have invalidated the renderer’s cached screen snapshot.

pub fn resize(&mut self, size: Size) -> Result<()>

Notifies the terminal about a caller-observed resize.

The notification performs no I/O immediately. The next render uses the new safe printable width and performs a full redraw.

Examples found in repository

examples/conversation.rs (line 86)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

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

Renders dirty or changed live and pinned blocks to the backend.

Mural writes the smallest safe suffix when possible and falls back to a full rewrite for recovery, resize, or changes above the visible viewport.

Examples found in repository

examples/conversation.rs (line 191)

fn render_frame<B: mural::Backend>(terminal: &mut Terminal<B>) -> std::io::Result<()> {
    terminal.render()?;
    thread::sleep(FRAME_DELAY);
    Ok(())
}

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

Finishes live rendering and restores terminal state.

Finish renders a final live-only frame, removes pinned UI with the same diff/recovery algorithm used by Terminal::render, moves to a fresh prompt line, shows the cursor, and flushes. After finish, rendering and mutation APIs return lifecycle errors.

Examples found in repository

examples/conversation.rs (line 104)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run this example manually to watch Mural update a conversation in the
    // terminal's normal buffer:
    //
    //     cargo run --example conversation
    let mut terminal = Terminal::stdout()?;

    // Live blocks are the transcript. Pinned blocks render after live blocks and
    // are useful for transient status and input UI. The status block starts
    // hidden, then appears directly above the input separator while the
    // assistant is answering.
    terminal.push_pinned(Text::from_plain("")?)?;
    terminal.insert_pinned("status", pinned(AnswerStatus::hidden()))?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    terminal.insert_pinned(
        "input",
        pinned(
            Textarea::new()
                .placeholder("type a message…")?
                .placeholder_style(Style::new().fg(Color::BrightBlack).dim())
                .max_height(3),
        ),
    )?;
    terminal.push_pinned(pinned(
        Hr::new().style(Style::new().fg(Color::BrightBlack).dim()),
    ))?;
    render_frames(&mut terminal, 8)?;

    // The first user message also goes through the textarea: applications own
    // raw mode and keyboard events; this example mutates the textarea directly
    // to simulate typing and submitting.
    type_into_input(&mut terminal, "explain Mural in one sentence")?;
    render_frames(&mut terminal, 4)?;
    submit_input(&mut terminal)?;

    show_status(&mut terminal, "answering")?;
    terminal.insert_live("thinking", live_padded(thinking_message("thinking…")?))?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking")?;
    terminal.insert_live("assistant", live_padded(assistant_message("Mural keeps")?))?;
    render_frames(&mut terminal, 3)?;

    // Identified blocks can be mutated between renders. This simulates a
    // streaming assistant response over several visible frames. The pinned
    // status spinner advances on every render while it is visible.
    for content in [
        "Mural keeps",
        "Mural keeps a live conversation",
        "Mural keeps a live conversation region plus pinned input",
        "Mural keeps a live conversation region plus pinned input/status UI in a normal terminal buffer.",
    ] {
        *terminal
            .live_block_mut::<Padding<ListItem>>("assistant")?
            .content_mut() = assistant_message(content)?;
        render_frames(&mut terminal, 5)?;
    }
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // Type a second message, move the cursor left, insert a missing word, then
    // submit. The submitted value is appended to the live transcript.
    type_into_input(&mut terminal, "what happens if terminal changes size?")?;
    move_input_left(&mut terminal, "terminal changes size?".chars().count())?;
    type_into_input(&mut terminal, "the ")?;
    render_frames(&mut terminal, 6)?;

    let submitted = submit_input(&mut terminal)?;
    show_status(&mut terminal, "adapting to resize")?;
    terminal.insert_live(
        "thinking-resize",
        live_padded(thinking_message("checking terminal size…")?),
    )?;
    render_frames(&mut terminal, 8)?;

    terminal.resize(Size::new(48, 12))?;
    *terminal
        .live_block_mut::<Padding<ListItem>>("thinking-resize")?
        .content_mut() = thinking_message("reflowing the conversation for 48 columns…")?;
    render_frames(&mut terminal, 10)?;
    terminal.remove_live("thinking-resize")?;
    terminal.insert_live(
        "assistant-resize",
        live_padded(assistant_message(format!(
            "For `{submitted}`, the caller notifies Mural about the new size, and the next render performs a full redraw at the new safe width."
        ))?),
    )?;
    render_frames(&mut terminal, 12)?;
    hide_status(&mut terminal)?;
    render_frames(&mut terminal, 6)?;

    // finish() removes pinned UI, leaves live transcript text behind, restores
    // the cursor, and flushes the backend.
    terminal.finish()?;
    println!("\nfinished: pinned status/input were cleaned up; live transcript remains above.");

    Ok(())
}

Trait Implementations

impl<B: Backend> Drop for Terminal<B>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.