cerno_tui/

render.rs

//! Drawing.

use crate::app::{App, Focus, Status};
use crate::draft::Kind;
use crate::editor::{Editor, Field};
use cerno_types::Answer;
use ratatui::Frame;
use ratatui::layout::{Constraint, Direction, Layout, Rect};
use ratatui::style::{Color, Modifier, Style};
use ratatui::text::{Line, Span};
use ratatui::widgets::{Block, Clear, List, ListItem, ListState, Paragraph, Wrap};

/// Eighth-width blocks, so a probability of one percent is still visible as something.
const EIGHTHS: [char; 8] = ['▏', '▎', '▍', '▌', '▋', '▊', '▉', '█'];
const EMPTY: char = '░';

/// Below this share of the model's probability on the offered letters, an answer is flagged. A
/// display threshold only: the service reports `label_mass` and leaves the judgement to callers.
/// Half is where the letters stop being what the model most wanted to write.
const LOW_LABEL_MASS: f64 = 0.5;

/// A horizontal bar `width` cells wide showing `probability`.
///
/// Sub-cell resolution matters here: a choice between twenty options routinely puts one percent
/// on a loser, and rounding that to an empty bar would show "impossible" where the model
/// actually said "unlikely". Eighth-blocks keep the distinction at any sane width.
pub fn bar(probability: f64, width: usize) -> String {
    if width == 0 {
        return String::new();
    }

    let clamped = probability.clamp(0.0, 1.0);
    let eighths = (clamped * width as f64 * 8.0).round() as usize;
    let full = (eighths / 8).min(width);
    let remainder = eighths % 8;

    let mut out = String::with_capacity(width * 3);
    for _ in 0..full {
        out.push(EIGHTHS[7]);
    }
    if full < width && remainder > 0 {
        out.push(EIGHTHS[remainder - 1]);
    }

    let drawn = full + usize::from(full < width && remainder > 0);
    for _ in drawn..width {
        out.push(EMPTY);
    }
    out
}

pub fn draw(frame: &mut Frame, app: &App) {
    let [body, status] =
        Layout::vertical([Constraint::Min(6), Constraint::Length(1)]).areas(frame.area());
    let [left, right] =
        Layout::horizontal([Constraint::Percentage(50), Constraint::Percentage(50)]).areas(body);
    let [state_area, questions_area] =
        Layout::vertical([Constraint::Percentage(40), Constraint::Percentage(60)]).areas(left);

    draw_state(frame, app, state_area);
    draw_questions(frame, app, questions_area);
    draw_answers(frame, app, right);
    draw_status(frame, app, status);

    if let Some(editor) = &app.editor {
        draw_editor(frame, editor, frame.area());
    }
    if app.show_help {
        draw_help(frame, frame.area());
    }
}

fn border(focused: bool) -> Style {
    if focused {
        Style::default().fg(Color::Cyan)
    } else {
        Style::default().fg(Color::DarkGray)
    }
}

fn draw_state(frame: &mut Frame, app: &App, area: Rect) {
    let block = Block::bordered()
        .title(" State (1) ")
        .border_style(border(app.focus == Focus::State));

    frame.render_widget(&block, area);
    frame.render_widget(&app.state, block.inner(area));
}

fn draw_questions(frame: &mut Frame, app: &App, area: Rect) {
    let focused = app.focus == Focus::Questions;
    let block = Block::bordered()
        .title(" Questions (2) ")
        .border_style(border(focused));
    let inner = block.inner(area);
    frame.render_widget(block, area);

    let mut items: Vec<ListItem> = Vec::with_capacity(app.questions.len() + 1);

    for (index, draft) in app.questions.iter().enumerate() {
        let selected = focused && index == app.selected;
        let blamed = app.is_blamed(index);

        let marker = if selected { "▸ " } else { "  " };
        let style = if blamed {
            Style::default().fg(Color::Red).add_modifier(Modifier::BOLD)
        } else if selected {
            Style::default().add_modifier(Modifier::BOLD)
        } else {
            Style::default()
        };

        items.push(ListItem::new(Line::from(vec![
            Span::styled(marker, style),
            Span::styled(format!("{:<10}", truncate(&draft.id, 10)), style),
            Span::styled(
                format!("{:<7}", draft.kind.label()),
                Style::default().fg(kind_colour(draft.kind)),
            ),
            Span::styled(draft.summary(), Style::default().fg(Color::Gray)),
        ])));
    }

    // The add row is a list position like the questions above it, so the cursor can reach it.
    let on_add = focused && app.on_add_row();
    items.push(ListItem::new(Span::styled(
        format!("{}+ add question  (a)", if on_add { "▸ " } else { "  " }),
        if on_add {
            Style::default().add_modifier(Modifier::BOLD)
        } else {
            Style::default().fg(Color::DarkGray)
        },
    )));

    // Stateful, so a selection below the bottom edge scrolls the list rather than vanishing.
    let mut state = ListState::default().with_selected(Some(app.selected));
    frame.render_stateful_widget(List::new(items), inner, &mut state);
}

fn kind_colour(kind: Kind) -> Color {
    match kind {
        Kind::Noul => Color::Green,
        Kind::Choice => Color::Blue,
        Kind::Score => Color::Magenta,
    }
}

fn draw_answers(frame: &mut Frame, app: &App, area: Rect) {
    let block = Block::bordered().border_style(border(app.focus == Focus::Answers));
    let inner = block.inner(area);

    let Some(answers) = &app.answers else {
        app.answers_max_scroll.set(0);
        frame.render_widget(block.title(" Answers "), area);
        let hint = if app.questions.is_empty() {
            "Add a question with `a`, then send with Ctrl+S."
        } else {
            "Ctrl+S to send."
        };
        frame.render_widget(
            Paragraph::new(hint).style(Style::default().fg(Color::DarkGray)),
            inner,
        );
        return;
    };

    // Answers from a previous request are dimmed rather than cleared, so a run at a different
    // calibration can be compared against the one before it.
    let base = if app.stale {
        Style::default().fg(Color::DarkGray)
    } else {
        Style::default()
    };

    let width = inner.width as usize;
    let mut lines: Vec<Line> = Vec::new();

    for id in app.answer_order() {
        let Ok(answer) = answers.get(id) else {
            continue;
        };
        lines.extend(answer_lines(id, app.question_for(id), answer, width, base));
        lines.push(Line::default());
    }

    lines.push(Line::from(Span::styled(
        format!(
            "{} · {} ms · {} tokens",
            answers.model(),
            answers.timing_ms(),
            answers.usage().input_tokens
        ),
        Style::default().fg(Color::DarkGray),
    )));

    // Counted after wrapping, the way the paragraph will lay them out, so the last line can be
    // scrolled to and no further.
    let pane_width = usize::from(inner.width.max(1));
    let drawn: usize = lines
        .iter()
        .map(|line| line.width().div_ceil(pane_width).max(1))
        .sum();
    let max_scroll =
        u16::try_from(drawn.saturating_sub(usize::from(inner.height))).unwrap_or(u16::MAX);
    app.answers_max_scroll.set(max_scroll);
    let scroll = app.answers_scroll.min(max_scroll);

    let mut title = String::from(" Answers ");
    if app.stale {
        title.push_str("(stale) ");
    }
    // Arrows say there is more than fits, and on which side; `3` or Tab gets there to scroll.
    if scroll > 0 {
        title.push_str("↑ ");
    }
    if scroll < max_scroll {
        title.push_str("↓ ");
    }
    frame.render_widget(block.title(title), area);

    frame.render_widget(
        Paragraph::new(lines)
            .wrap(Wrap { trim: false })
            .scroll((scroll, 0)),
        inner,
    );
}

/// One option of an answer, as a row in the pane.
struct Row {
    label: String,
    probability: f64,
    winner: bool,
}

/// Cells in an option row besides its label and bar: indent, letter and space, the spaces
/// around the bar, the bound marker and `100.0%`.
const ROW_FIXED: usize = 2 + 2 + 1 + 1 + 1 + 6;

/// The letter the model answered with for the option at `index`, in the order
/// `cerno-core`'s `labels` hands them out: a noul's Yes is `A`, a score's level 1 is `A`.
fn letter(index: usize) -> String {
    char::from(b'A' + (index as u8).min(25)).to_string()
}

/// A colour for a stale answer stays dim; everything else takes the accent.
fn tint(base: Style, colour: Color) -> Style {
    if base.fg.is_some() {
        base
    } else {
        base.fg(colour)
    }
}

/// One answer: headline, the question it was asked with, a bar per option, and warnings.
fn answer_lines(
    id: &str,
    question: Option<&str>,
    answer: &Answer,
    width: usize,
    base: Style,
) -> Vec<Line<'static>> {
    let bold = base.add_modifier(Modifier::BOLD);
    let dim = base.fg(Color::DarkGray);
    let mut lines = Vec::new();

    let (value, rows, detail) = match answer {
        Answer::Noul { noul, .. } => (
            format!("noul {noul:.4}"),
            vec![
                Row {
                    label: "Yes".into(),
                    probability: *noul,
                    winner: *noul >= 0.5,
                },
                Row {
                    label: "No".into(),
                    probability: 1.0 - *noul,
                    winner: *noul < 0.5,
                },
            ],
            None,
        ),

        Answer::Choice {
            choice,
            index,
            probabilities,
            ..
        } => (
            format!("choice → {choice}"),
            probabilities
                .iter()
                .enumerate()
                .map(|(i, entry)| Row {
                    label: entry.option.clone(),
                    probability: entry.probability,
                    winner: i == *index,
                })
                .collect(),
            None,
        ),

        Answer::Score {
            score,
            expected_score,
            legend,
            probabilities,
            ..
        } => (
            format!("score → {score} \"{legend}\""),
            probabilities
                .iter()
                .map(|entry| Row {
                    label: format!("{} {}", entry.level, entry.legend),
                    probability: entry.probability,
                    winner: entry.level == *score,
                })
                .collect(),
            Some(format!("expected {expected_score:.2}")),
        ),
    };

    // Headline: id and value on the left, confidence pushed to the right edge. A noul has no
    // confidence — its probability already is the answer — so its right side stays empty.
    let left = format!("{}  {value}", truncate(id, 20));
    let right = answer
        .confidence()
        .map(|confidence| format!("conf {confidence:.3} {}", bar(confidence, 10)))
        .unwrap_or_default();
    let gap = width
        .saturating_sub(left.chars().count() + right.chars().count())
        .max(2);
    lines.push(Line::from(vec![
        Span::styled(left, bold),
        Span::raw(" ".repeat(gap)),
        Span::styled(right, dim),
    ]));

    if let Some(question) = question.filter(|q| !q.is_empty()) {
        lines.push(Line::from(Span::styled(
            format!("  {question}"),
            dim.add_modifier(Modifier::ITALIC),
        )));
    }
    if let Some(detail) = detail {
        lines.push(Line::from(Span::styled(format!("  {detail}"), dim)));
    }

    // The label column fits the longest label, up to two fifths of the pane; the bar takes the
    // rest, so a wide terminal gets a finer bar rather than empty space.
    let longest = rows
        .iter()
        .map(|r| r.label.chars().count())
        .max()
        .unwrap_or(0);
    let label_width = longest.min(width * 2 / 5).max(3);
    let bar_width = width.saturating_sub(ROW_FIXED + label_width).max(1);

    let bounded = answer.truncated_labels();
    for (index, row) in rows.iter().enumerate() {
        let letter = letter(index);
        let bound = bounded
            .iter()
            .any(|l| l.trim().eq_ignore_ascii_case(&letter));
        lines.push(option_line(
            &letter,
            row,
            label_width,
            bar_width,
            bound,
            base,
        ));
    }

    // A truncated answer is an upper bound, not an observation, and saying so is the whole
    // reason the flag travels back with every answer.
    if answer.truncated() {
        let text = format!(
            "  ⚠ truncated: {} fell outside the host's window; ≤ marks an upper bound",
            bounded.join(", ")
        );
        lines.push(Line::from(Span::styled(text, tint(base, Color::Yellow))));
    }

    // The bars are normalised over the letters, so they look as decisive when the model was
    // about to write something else and the letters were far behind. Only the mass says so.
    let mass = answer.label_mass();
    if mass < LOW_LABEL_MASS {
        let text = format!(
            "  ⚠ only {:.1}% of the model's probability was on the letters; it was not answering \
             with one",
            mass * 100.0
        );
        lines.push(Line::from(Span::styled(text, tint(base, Color::Yellow))));
    }

    lines
}

fn option_line(
    letter: &str,
    row: &Row,
    label_width: usize,
    bar_width: usize,
    bound: bool,
    base: Style,
) -> Line<'static> {
    let (text, colour) = if row.winner {
        (base.add_modifier(Modifier::BOLD), Color::Green)
    } else {
        (base, Color::Cyan)
    };

    Line::from(vec![
        Span::styled(format!("  {letter} "), base.fg(Color::DarkGray)),
        Span::styled(
            format!("{:<label_width$} ", truncate(&row.label, label_width)),
            text,
        ),
        Span::styled(bar(row.probability, bar_width), tint(base, colour)),
        Span::styled(if bound { " ≤" } else { "  " }, tint(base, Color::Yellow)),
        Span::styled(format!("{:>5.1}%", row.probability * 100.0), text),
    ])
}

fn draw_status(frame: &mut Frame, app: &App, area: Rect) {
    let health = match app.healthy {
        Some(true) => Span::styled(" ●", Style::default().fg(Color::Green)),
        Some(false) => Span::styled(" ○ unreachable", Style::default().fg(Color::Red)),
        None => Span::styled(" ?", Style::default().fg(Color::DarkGray)),
    };

    let mut spans = vec![
        Span::styled(app.url.clone(), Style::default().fg(Color::DarkGray)),
        health,
        Span::styled(
            format!(" · {}", app.model.as_deref().unwrap_or("default model")),
            Style::default().fg(Color::DarkGray),
        ),
    ];

    if let Some(temperature) = app.calibration {
        spans.push(Span::styled(
            format!(" · T {temperature:.2}"),
            Style::default().fg(Color::Magenta),
        ));
    }

    match &app.status {
        Status::Sending { started, .. } => {
            const SPINNER: [char; 4] = ['|', '/', '-', '\\'];
            spans.push(Span::styled(
                format!(
                    " · {} sending {:.1}s  (Esc cancels)",
                    SPINNER[(app.tick as usize) % SPINNER.len()],
                    started.elapsed().as_secs_f32()
                ),
                Style::default().fg(Color::Yellow),
            ));
        }
        Status::Failed(failure) => {
            let code = failure
                .code
                .map(|c| format!("{c:?}"))
                .unwrap_or_else(|| "error".into());
            spans.push(Span::styled(
                format!(" · {code}: {}", failure.message),
                Style::default().fg(Color::Red),
            ));
        }
        Status::Idle => spans.push(Span::styled(
            " · ^S send · ? help",
            Style::default().fg(Color::DarkGray),
        )),
    }

    frame.render_widget(Paragraph::new(Line::from(spans)), area);
}

fn draw_editor(frame: &mut Frame, editor: &Editor, area: Rect) {
    let fields = editor.fields();
    let height = fields.len() as u16 * 3 + 2;
    let area = centred(area, 64, height.min(area.height));

    frame.render_widget(Clear, area);
    let block = Block::bordered()
        .title(if editor.is_editing() {
            " Edit question "
        } else {
            " New question "
        })
        .border_style(Style::default().fg(Color::Cyan));
    let inner = block.inner(area);
    frame.render_widget(block, area);

    let constraints: Vec<Constraint> = fields.iter().map(|_| Constraint::Length(3)).collect();
    let rows = Layout::default()
        .direction(Direction::Vertical)
        .constraints(constraints)
        .split(inner);

    for (field, row) in fields.iter().zip(rows.iter()) {
        let focused = *field == editor.focused();

        // A default belongs beside its field, not inside it: text in the field joins whatever
        // gets typed, which is what produced "urgentq1" and "5unkritisch".
        let title = match field {
            Field::Id if editor.is_blank(Field::Id) => {
                format!(" id  (blank → {}) ", editor.fallback_id())
            }
            Field::Levels if editor.is_blank(Field::Levels) => {
                format!(" levels  (blank → {}) ", Editor::DEFAULT_LEVELS)
            }
            _ => format!(" {} ", field.label()),
        };

        let field_block = Block::bordered().title(title).border_style(border(focused));
        let field_inner = field_block.inner(*row);
        frame.render_widget(field_block, *row);

        if *field == Field::Kind {
            let spans: Vec<Span> = Kind::ALL
                .iter()
                .flat_map(|kind| {
                    let selected = *kind == editor.kind();
                    let style = if selected {
                        Style::default()
                            .fg(kind_colour(*kind))
                            .add_modifier(Modifier::BOLD)
                    } else {
                        Style::default().fg(Color::DarkGray)
                    };
                    [
                        Span::styled(
                            if selected {
                                format!("[{}]", kind.label())
                            } else {
                                format!(" {} ", kind.label())
                            },
                            style,
                        ),
                        Span::raw(" "),
                    ]
                })
                .collect();
            frame.render_widget(Paragraph::new(Line::from(spans)), field_inner);
        } else {
            frame.render_widget(editor.field(*field), field_inner);
        }
    }
}

fn draw_help(frame: &mut Frame, area: Rect) {
    let lines = vec![
        "Tab / Shift+Tab   move between panes; 1 2 3 jump to one",
        "↑ ↓               select a question, or the add row below them",
        "Enter             edit the selected question, or add on the add row",
        "a / e / d         add · edit · delete",
        "↑ ↓ PgUp PgDn     scroll the answers, when they have focus",
        "Ctrl+S            send",
        "Esc               close a dialog, or cancel a request in flight",
        "m                 next model",
        "t / T / c         temperature up · down · back to the default",
        "?                 this help",
        "Ctrl+C            quit  (q also quits outside the state box)",
    ];

    let area = centred(area, 70, lines.len() as u16 + 2);
    frame.render_widget(Clear, area);

    let block = Block::bordered()
        .title(" Keys ")
        .border_style(Style::default().fg(Color::Cyan));
    let inner = block.inner(area);
    frame.render_widget(block, area);
    frame.render_widget(Paragraph::new(lines.join("\n")), inner);
}

fn centred(area: Rect, width: u16, height: u16) -> Rect {
    let width = width.min(area.width);
    let height = height.min(area.height);
    Rect {
        x: area.x + (area.width - width) / 2,
        y: area.y + (area.height - height) / 2,
        width,
        height,
    }
}

fn truncate(value: &str, width: usize) -> String {
    if value.chars().count() <= width {
        return value.to_string();
    }
    value
        .chars()
        .take(width.saturating_sub(1))
        .collect::<String>()
        + "…"
}

#[cfg(test)]
mod tests {
    use super::*;

    fn filled(bar: &str) -> usize {
        bar.chars().filter(|c| *c != EMPTY).count()
    }

    #[test]
    fn a_bar_is_always_exactly_its_width() {
        for probability in [0.0, 0.001, 0.25, 0.5, 0.987, 1.0] {
            for width in [1usize, 4, 16, 24] {
                let rendered = bar(probability, width);
                assert_eq!(
                    rendered.chars().count(),
                    width,
                    "p={probability} width={width} gave {rendered:?}"
                );
            }
        }
    }

    #[test]
    fn a_full_bar_is_all_blocks_and_an_empty_one_is_none() {
        assert_eq!(bar(1.0, 4), "████");
        assert_eq!(bar(0.0, 4), "░░░░");
    }

    /// The point of eighth-blocks: one percent must not render as nothing.
    #[test]
    fn a_small_probability_still_shows_something() {
        let rendered = bar(0.011, 16);

        assert!(
            filled(&rendered) > 0,
            "1.1% rendered as empty: {rendered:?}"
        );
        assert!(
            filled(&rendered) < 2,
            "1.1% should be a sliver: {rendered:?}"
        );
    }

    #[test]
    fn bars_grow_monotonically_with_probability() {
        let mut previous = 0usize;
        for step in 0..=20 {
            let rendered = bar(step as f64 / 20.0, 20);
            let ink = rendered.chars().filter(|c| *c == EIGHTHS[7]).count();
            assert!(ink >= previous, "went backwards at {step}: {rendered:?}");
            previous = ink;
        }
    }

    /// Probabilities arrive from a softmax and should already be in range, but a bar is not the
    /// place to find out otherwise.
    #[test]
    fn out_of_range_values_are_clamped_rather_than_panicking() {
        assert_eq!(bar(-0.5, 4), "░░░░");
        assert_eq!(bar(2.0, 4), "████");
        assert_eq!(bar(f64::NAN, 4).chars().count(), 4);
        assert_eq!(bar(0.5, 0), "");
    }

    #[test]
    fn long_labels_are_truncated_with_an_ellipsis() {
        assert_eq!(truncate("short", 10), "short");
        assert_eq!(truncate("a-very-long-option", 8), "a-very-…");
        assert_eq!(truncate("exactly10!", 10), "exactly10!");
    }
}