rhdl_fpga_planner/

tui.rs

#![doc = include_str!("../docs/tuner.md")]

use std::io;

use ratatui::{
    Frame, Terminal,
    backend::Backend,
    crossterm::event::{self, Event, KeyCode, KeyEventKind, KeyModifiers},
    layout::{Constraint, Layout, Rect},
    style::{Color, Modifier, Style},
    text::{Line, Span},
    widgets::{Block, Borders, Gauge, Paragraph, Wrap},
};

use crate::{
    BASE_DSP, BASE_LUT, BUDGET_BRAM36, Budget, ChipPlan, Context, Cost, Delivered, Mode, Powers, Role, SHA512_BLOCKS, Share, Side, Slot,
    U280_DSP, U280_LUT, U280_URAM, build_config, plan_chip, ubft,
};

/// One row of the control list.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Control {
    /// Which paper.
    Mode,
    /// Global LUT percentage.
    Lut,
    /// Global DSP percentage.
    Dsp,
    /// BRAM percentage of the device.
    Bram,
    /// URAM percentage of the device.
    Uram,
    /// The SHA-512 line's part of the LUT split (sets its LUT allowance).
    ShaSplit,
    /// Sign side's power.
    SignPower,
    /// Verify side's power.
    VerifyPower,
    /// EdDSA background's % of the budget (DSig paper).
    Background,
    /// Ed25519 sign's % of the background (DSig paper).
    EdSplit,
    /// Verifications per signature the B key balances for.
    Mix,
    /// Best-case expectation (DSig paper).
    BestCase,
    /// Header of slot `k` (shows its derived share).
    Module(usize),
    /// Knob `j` of slot `k`.
    Knob(usize, usize),
    /// Manual share of resource `i` ([`crate::Resource::ALL`]) for slot `k`.
    Limit(usize, usize),
}

/// The planner's state.
pub struct App {
    /// Title line.
    pub title: String,
    /// Which paper.
    pub mode: Mode,
    /// Resource budget.
    pub budget: Budget,
    /// Workload.
    pub cx: Context,
    /// Side powers.
    pub powers: Powers,
    /// Components.
    pub slots: Vec<Slot>,
    /// Selected control.
    pub selected: usize,
    /// Status line.
    pub status: String,
    /// Where W writes the build flags.
    pub config_path: String,
    /// The powers are the balanced split for the current settings.
    pub balanced: bool,
    /// The DSig paper's background setting (auto or manual).
    pub bg: crate::Background,
    /// The background in use, with what the planner would choose.
    pub used: crate::BackgroundUsed,
    /// Each mode's delivered rates as last planned ([`Mode::ALL`] order),
    /// for the headline that shows every paper.
    pub headline: [Option<Delivered>; 4],
    /// The budget of the modes on the other side of the uBFT line: the
    /// papers plan an engine budget, the uBFT modes the whole device
    /// ([`Budget::whole_device`]). Switching across swaps them.
    pub other_budget: Budget,
}

/// Card and gauge colors, one per slot in order.
const COLORS: [Color; 6] = [Color::Blue, Color::Magenta, Color::Green, Color::Yellow, Color::Cyan, Color::LightRed];

/// `123456` as `"123.5k"`.
fn kilo(n: u32) -> String {
    if n >= 10_000 { format!("{:.1}k", n as f64 / 1e3) } else { n.to_string() }
}

/// Microseconds, scaled.
fn micros(us: f64) -> String {
    if us >= 1_000.0 {
        format!("{:.2}ms", us / 1e3)
    } else if us >= 10.0 {
        format!("{us:.0}us")
    } else {
        format!("{us:.2}us")
    }
}

/// Operations per second, scaled.
fn rate(x: f64) -> String {
    if x >= 1e6 {
        format!("{:.2}M", x / 1e6)
    } else if x >= 1e3 {
        format!("{:.1}k", x / 1e3)
    } else {
        format!("{x:.0}")
    }
}

/// Controls, key handling and planning for the TUI.
impl App {
    /// A planner for `slots`, balanced for the default settings.
    pub fn new(title: &str, mode: Mode, slots: Vec<Slot>) -> App {
        let mut app = App {
            title: title.into(),
            mode,
            budget: Budget::default(),
            cx: Context::default(),
            powers: Powers::default(),
            slots,
            selected: 0,
            status: String::new(),
            config_path: "build-config.toml".into(),
            balanced: false,
            bg: crate::Background::default(),
            used: crate::BackgroundUsed::default(),
            headline: [None, None, None, None],
            other_budget: if mode.is_ubft() { Budget::default() } else { Budget::whole_device() },
        };
        if mode.is_ubft() {
            app.budget = Budget::whole_device();
        }
        // A paper whose modules were not compiled in (a build without the
        // `dsig` feature) is not offered; open on one that is.
        if !app.has_paper(mode) {
            if let Some(&m) = app.papers().iter().find(|m| m.is_ubft() == mode.is_ubft()) {
                app.mode = m;
            }
        }
        // Balance the other papers first so the headline shows them all.
        let first = app.mode;
        for m in app.papers() {
            if m != first {
                app.enter(m);
                app.balance();
            }
        }
        app.enter(first);
        app.balance();
        app
    }

    /// Whether this chip has the modules of `mode`'s paper: a paper's
    /// signing module decides it (Ed25519 signing for the Ed25519 paper,
    /// DSig signing for the DSig paper; a uBFT module of that role for a
    /// uBFT mode).
    pub fn has_paper(&self, mode: Mode) -> bool {
        let role = if mode.paper() == Mode::Dsig { Role::DsigSign } else { Role::Ed25519Sign };
        self.slots.iter().any(|s| s.component.role() == role && s.component.ubft() == mode.is_ubft())
    }

    /// The papers this chip can plan, in display order ([`Mode::ALL`]).
    pub fn papers(&self) -> Vec<Mode> {
        Mode::ALL.into_iter().filter(|&m| self.has_paper(m)).collect()
    }

    /// Each slot's guaranteed share in the current mode.
    fn shares_now(&self) -> Vec<Share> {
        crate::shares_with(&self.budget, &self.slots, &crate::allowances_in(self.mode, &self.slots))
    }

    /// The fixed allowances of the current mode, summed.
    fn fixed_now(&self) -> Cost {
        crate::allowances_in(self.mode, &self.slots).into_iter().flatten().fold(Cost::default(), |a, f| a.add(f, 1))
    }

    /// Make `mode` current, swapping budgets when it crosses the uBFT line.
    fn enter(&mut self, mode: Mode) {
        if mode.is_ubft() != self.mode.is_ubft() {
            std::mem::swap(&mut self.budget, &mut self.other_budget);
        }
        self.mode = mode;
    }

    /// Every control, in display order.
    pub fn controls(&self) -> Vec<Control> {
        let mut c = vec![Control::Mode, Control::Lut, Control::Dsp, Control::Bram, Control::Uram];
        if self.sha_lut_knob().is_some() {
            c.push(Control::ShaSplit);
        }
        c.extend([Control::SignPower, Control::VerifyPower]);
        if self.mode == Mode::Dsig {
            c.push(Control::Background);
            c.push(Control::EdSplit);
        }
        c.push(Control::Mix);
        if self.mode.paper() == Mode::Dsig {
            c.push(Control::BestCase);
        }
        for (k, s) in self.slots.iter().enumerate() {
            if !self.mode.admits(&*s.component) {
                continue;
            }
            c.push(Control::Module(k));
            // Shared knobs appear under every module that has them; either
            // row sets all of them.
            for j in 0..s.component.knobs().len() {
                c.push(Control::Knob(k, j));
            }
            if s.component.fixed().is_none() {
                for i in 0..4 {
                    c.push(Control::Limit(k, i));
                }
            }
        }
        c
    }

    /// The SHA-512 line's LUT allowance knob: (slot, knob index).
    pub fn sha_lut_knob(&self) -> Option<(usize, usize)> {
        let k = self
            .slots
            .iter()
            .position(|s| s.component.role() == Role::Sha512 && s.component.fixed().is_some() && self.mode.admits(&*s.component))?;
        let j = self.slots[k].component.knobs().iter().position(|x| x.name.contains("LUT"))?;
        Some((k, j))
    }

    /// Whether the SHA-512 line sizes itself to demand (its "size" knob on
    /// auto).
    pub fn sha_auto(&self) -> bool {
        self.slots
            .iter()
            .any(|s| s.component.role() == Role::Sha512 && s.component.knobs().iter().any(|k| k.name == "size" && k.value < 0.5))
    }

    /// The LUT split in % of the LUT budget: (SHA line, DSig foreground,
    /// Ed25519). The Ed25519 paper has no DSig part. Sums to 100.
    pub fn lut_split(&self) -> (f64, f64, f64) {
        let luts = self.budget.luts().max(1) as f64;
        let sha = (100.0 * self.fixed_now().lut as f64 / luts).min(100.0);
        let rest = 100.0 - sha;
        if self.mode.paper() == Mode::Dsig {
            let b = self.used.share;
            (sha, rest * (100.0 - b) / 100.0, rest * b / 100.0)
        } else {
            (sha, 0.0, rest)
        }
    }

    /// The other modules that share knob `name` (shown in its label).
    fn sharers(&self, name: &str) -> Vec<String> {
        self.slots
            .iter()
            .filter(|s| self.mode.admits(&*s.component) && s.component.knobs().iter().any(|x| x.shared && x.name == name))
            .map(|s| s.component.name())
            .collect()
    }

    /// The text of one control row.
    fn label(&self, c: Control) -> String {
        let b = &self.budget;
        match c {
            Control::Mode => format!("Paper        {}", self.mode.name()),
            Control::Lut => format!("LUT budget  {:5.1} % = {} of {}", b.lut_percent, kilo(b.luts()), kilo(BASE_LUT)),
            Control::Dsp => format!("DSP budget  {:5.1} % = {} of {} (dev {})", b.dsp_percent, b.dsps(), BASE_DSP, U280_DSP),
            Control::Bram => format!("BRAM budget {:5.1} % = {} of {} BRAM36 (dynamic region)", b.bram_percent, b.brams(), BUDGET_BRAM36),
            Control::Uram => format!("URAM budget {:5.1} % = {} of {}", b.uram_percent, b.urams(), U280_URAM),
            Control::ShaSplit => {
                let (sha, dsig, ed) = self.lut_split();
                let size = if self.sha_auto() { " auto" } else { "" };
                if self.mode.paper() == Mode::Dsig {
                    format!("LUT split   SHA{size} {sha:.1}% | DSig {dsig:.1}% | Ed25519 {ed:.1}%")
                } else {
                    format!("LUT split   SHA{size} {sha:.1}% ({}) | Ed25519 {ed:.1}%", kilo(self.fixed_now().lut))
                }
            }
            Control::SignPower if self.mode.paper() == Mode::Dsig => {
                format!("HBSS sign   {:5.1} % of the foreground", self.powers.sign)
            }
            Control::VerifyPower if self.mode.paper() == Mode::Dsig => {
                format!("HBSS verify {:5.1} % of the foreground (sum 100)", self.powers.verify)
            }
            Control::SignPower => format!("Sign power  {:5.1} % of the budget", self.powers.sign),
            Control::VerifyPower => format!("Verify power{:5.1} % of the budget (sign + verify = 100)", self.powers.verify),
            Control::Background => {
                let u = &self.used;
                let mode = if self.bg.share.is_some() { "manual" } else { "auto" };
                format!(
                    "EdDSA background {:5.1} % of non-SHA ({mode}), HBSS {:.1} %; needed {:.1} %",
                    u.share,
                    100.0 - u.share,
                    u.needed_share
                )
            }
            Control::EdSplit => {
                let u = &self.used;
                let mode = if self.bg.sign.is_some() { "manual" } else { "auto" };
                format!("  within EdDSA: sign {:5.1} % / verify {:.1} % ({mode}); best {:.1} %", u.sign, 100.0 - u.sign, u.needed_sign)
            }
            Control::Mix => format!("Mix (for B) {:.2} verifies per signature", self.cx.mix),
            Control::BestCase => format!(
                "Best case   {:5.1} %  (root cached: {:.1} %)",
                self.cx.best_case,
                100.0 * self.cx.cache_hit(self.plan().delivered.batch)
            ),
            Control::Module(k) => {
                let s = &self.slots[k];
                match s.component.fixed() {
                    Some(f) => {
                        let why = if s.component.role() == Role::Sha512 { "LUT split" } else { "fixed" };
                        format!("{}  {} LUT {} DSP ({why})", s.component.name(), kilo(f.lut), f.dsp)
                    }
                    None => {
                        // The guaranteed share in real units.
                        let g = self.shares_now()[k];
                        format!(
                            "{}  {:4.1} % = {} LUT {} DSP {} BRAM {} URAM",
                            s.component.name(),
                            s.power,
                            kilo(g.lut),
                            g.dsp,
                            g.bram36,
                            g.uram
                        )
                    }
                }
            }
            Control::Limit(k, i) => {
                let r = crate::Resource::ALL[i];
                let g = r.of(&self.shares_now()[k]);
                match self.slots[k].limits[i] {
                    Some(pct) => format!("    {:<4} share        {pct:5.1} % = {} (manual cap)", r.name(), kilo(g)),
                    None => format!("    {:<4} share        auto ({}; Right sets a cap)", r.name(), kilo(g)),
                }
            }
            Control::Knob(k, j) => {
                let knob = &self.slots[k].component.knobs()[j];
                let n = if knob.shared { self.sharers(&knob.name).len() } else { 0 };
                let note = if n > 1 { format!("  (sets all {n})") } else { String::new() };
                format!("    {:<18} {}{note}", knob.name, knob.show())
            }
        }
    }

    /// Move the selected control by `steps`.
    pub fn adjust(&mut self, steps: f64) {
        let Some(&c) = self.controls().get(self.selected) else {
            return;
        };
        match c {
            Control::Mode => {
                self.switch_paper();
                return;
            }
            Control::Lut => {
                self.budget.lut_percent = (self.budget.lut_percent + steps).clamp(0.0, 100.0 * U280_LUT as f64 / BASE_LUT as f64)
            }
            Control::Dsp => {
                self.budget.dsp_percent = (self.budget.dsp_percent + steps).clamp(0.0, 100.0 * U280_DSP as f64 / BASE_DSP as f64)
            }
            Control::Bram => self.budget.bram_percent = (self.budget.bram_percent + steps).clamp(0.0, 100.0),
            Control::Uram => self.budget.uram_percent = (self.budget.uram_percent + steps).clamp(0.0, 100.0),
            // The two powers always sum to 100 %.
            Control::SignPower => {
                self.powers.sign = (self.powers.sign + steps).clamp(0.0, 100.0);
                self.powers.verify = 100.0 - self.powers.sign;
            }
            Control::VerifyPower => {
                self.powers.verify = (self.powers.verify + steps).clamp(0.0, 100.0);
                self.powers.sign = 100.0 - self.powers.verify;
            }
            // 0.5 % per press from the value in use; below 0 returns to
            // auto.
            Control::Background => {
                let next = self.bg.share.unwrap_or(self.used.share) + 0.5 * steps;
                self.bg.share = if next < 0.0 { None } else { Some(next.min(100.0)) };
            }
            Control::EdSplit => {
                let next = self.bg.sign.unwrap_or(self.used.sign) + 0.5 * steps;
                self.bg.sign = if next < 0.0 { None } else { Some(next.min(100.0)) };
            }
            // 0.5 % of the LUT budget per press, in the knob's own steps.
            Control::ShaSplit => {
                let Some((k, j)) = self.sha_lut_knob() else {
                    return;
                };
                let knob = self.slots[k].component.knobs()[j].clone();
                let step = (0.005 * self.budget.luts() as f64 / knob.step.max(1.0)).round().max(1.0) * knob.step.max(1.0);
                let value = (knob.value + step * steps).clamp(knob.min, knob.max);
                let was_auto = self.sha_auto();
                self.slots[k].component.set_knob(j, value);
                if was_auto {
                    self.status = "SHA-512 line set by hand; its \"size\" knob returns it to auto.".into();
                }
                if value >= knob.max && steps > 0.0 {
                    self.status = format!("The SHA-512 line is at its largest allowance ({} LUT).", kilo(knob.max as u32));
                }
            }
            Control::Mix => self.cx.mix = ((self.cx.mix + 0.05 * steps) * 100.0).round().clamp(0.0, 1_000.0) / 100.0,
            Control::BestCase => self.cx.best_case = (self.cx.best_case + steps).clamp(0.0, 100.0),
            Control::Module(_) => return,
            // 0.5 % per press, starting from the current share; below 0
            // returns to auto.
            Control::Limit(k, i) => {
                let r = crate::Resource::ALL[i];
                let total = r.of(&self.budget.rest_with(&crate::allowances_in(self.mode, &self.slots))).max(1) as f64;
                let now = self.slots[k].limits[i].unwrap_or(100.0 * r.of(&self.shares_now()[k]) as f64 / total);
                let next = ((now + 0.5 * steps) * 2.0).round() / 2.0;
                self.slots[k].limits[i] = if next < 0.0 { None } else { Some(next.min(100.0)) };
            }
            Control::Knob(k, j) => {
                let knob = self.slots[k].component.knobs()[j].clone();
                let value = knob.moved(steps);
                self.slots[k].component.set_knob(j, value);
                // A shared knob takes the same value in every module with it.
                if knob.shared {
                    for other in 0..self.slots.len() {
                        if other == k {
                            continue;
                        }
                        let found = self.slots[other].component.knobs().iter().position(|x| x.shared && x.name == knob.name);
                        if let Some(i) = found {
                            self.slots[other].component.set_knob(i, value);
                        }
                    }
                }
            }
        }
        // Re-plan with the new settings.
        self.used = crate::apply_layout(self.mode, &self.budget, &self.cx, &mut self.slots, self.powers, self.bg).1;
        self.balanced = false;
        self.note_headline();
    }

    /// Record this paper's delivered rates for the headline.
    fn note_headline(&mut self) {
        let d = self.plan().delivered;
        let i = Mode::ALL.iter().position(|&m| m == self.mode).unwrap();
        self.headline[i] = Some(d);
    }

    /// Switch to the next paper this build has ([`papers`](Self::papers),
    /// wrapping around) and balance it.
    pub fn switch_paper(&mut self) {
        let papers = self.papers();
        let at = papers.iter().position(|&m| m == self.mode).unwrap_or(0);
        let next = papers[(at + 1) % papers.len().max(1)];
        if next == self.mode {
            self.status = format!("This build has only the {}; build with the `dsig` feature (`cargo tuner`) for both.", self.mode.name());
            return;
        }
        self.enter(next);
        self.selected = 0;
        self.balance();
    }

    /// Choose the side powers for the mix (what "100 %" means).
    pub fn balance(&mut self) {
        self.powers = crate::balance_mix_with(self.mode, &self.budget, &self.cx, &mut self.slots, self.bg);
        self.used = crate::apply_layout(self.mode, &self.budget, &self.cx, &mut self.slots, self.powers, self.bg).1;
        self.balanced = true;
        self.note_headline();
        let d = self.plan().delivered;
        self.status = format!(
            "Balanced for {:.2} verifies per signature: sign power {:.1} %, verify power {:.1} % -> {} {}/s and {} {}/s.",
            self.cx.mix,
            self.powers.sign,
            self.powers.verify,
            rate(d.sign.rate),
            self.mode.op(Side::Sign),
            rate(d.verify.rate),
            self.mode.op(Side::Verify)
        );
    }

    /// Write the build flags of the current plan.
    pub fn write_config(&mut self) {
        let text = build_config(self.mode, &self.budget, &self.cx, &self.slots);
        if self.mode.is_ubft() {
            if let Err(error) = crate::build_apply::UbftBuild::from_toml(&text) {
                self.status = format!("Plan not written: {error}");
                return;
            }
        }
        self.status = match std::fs::write(&self.config_path, text) {
            Ok(()) if self.mode.is_ubft() => format!("Wrote {}; plan only. Apply with apply_ubft_plan.", self.config_path),
            Ok(()) => format!("Wrote {}; model record only (no validated apply path for this mode).", self.config_path),
            Err(e) => format!("Could not write {}: {e}", self.config_path),
        };
    }

    /// Handle one key; `false` to quit.
    pub fn key(&mut self, code: KeyCode, shift: bool) -> bool {
        let n = self.controls().len();
        let steps = if shift { 5.0 } else { 1.0 };
        match code {
            KeyCode::Char('q') | KeyCode::Esc => return false,
            KeyCode::Down | KeyCode::Tab => self.selected = (self.selected + 1) % n,
            KeyCode::Up => self.selected = (self.selected + n - 1) % n,
            KeyCode::Left => self.adjust(-steps),
            KeyCode::Right => self.adjust(steps),
            KeyCode::Char('b') | KeyCode::Char('B') => self.balance(),
            KeyCode::Char('p') | KeyCode::Char('P') => self.switch_paper(),
            KeyCode::Char('w') | KeyCode::Char('W') => self.write_config(),
            _ => {}
        }
        self.selected = self.selected.min(self.controls().len() - 1);
        true
    }

    /// The current plan.
    pub fn plan(&self) -> ChipPlan {
        plan_chip(self.mode, &self.budget, &self.cx, &self.slots)
    }
}

/// The next faster build of `slot` with more LUTs and everything else as
/// in `share`: `(extra LUTs, its capacity)`, probing in 1k steps up to 64k.
/// Builds come in whole blocks (a field machine is ~11k LUTs), so a rate
/// that stays flat while LUTs grow is waiting for this step.
pub fn next_step(slot: &Slot, share: &Share, cx: &Context, rate_now: f64) -> Option<(u32, f64)> {
    (1..=64u32).find_map(|k| {
        let wider = Share { lut: share.lut + 1_000 * k, ..*share };
        crate::plan_slot(slot, &wider, cx).filter(|p| p.rate > rate_now * (1.0 + 1e-6) + 1.0).map(|p| (1_000 * k, p.rate))
    })
}

/// Gauge fill for `used` of `limit` (full when the limit is zero but
/// something is used).
fn ratio(used: u32, limit: u32) -> f64 {
    if limit == 0 { if used == 0 { 0.0 } else { 1.0 } } else { (used as f64 / limit as f64).clamp(0.0, 1.0) }
}

/// Four gauges (LUT, DSP, BRAM, URAM) of `used` against `limit`; a gauge
/// turns red at 97 %.
fn gauge_row(frame: &mut Frame, area: Rect, used: Cost, limit: Share, color: Color) {
    let cols = Layout::horizontal([Constraint::Ratio(1, 4); 4]).split(area);
    for (i, (name, u, l)) in
        [("LUT", used.lut, limit.lut), ("DSP", used.dsp, limit.dsp), ("BRAM", used.bram36, limit.bram36), ("URAM", used.uram, limit.uram)]
            .into_iter()
            .enumerate()
    {
        let full = l > 0 && u as f64 >= 0.97 * l as f64;
        frame.render_widget(
            Gauge::default()
                .ratio(ratio(u, l))
                .label(format!("{name} {}/{}", kilo(u), kilo(l)))
                .gauge_style(Style::default().fg(if full { Color::Red } else { color })),
            cols[i],
        );
    }
}

/// Draw one frame.
pub fn draw(frame: &mut Frame, app: &App) {
    let plan = app.plan();
    let areas =
        Layout::vertical([Constraint::Length(2), Constraint::Min(8), Constraint::Length(2), Constraint::Length(1)]).split(frame.area());
    // Every paper's headline (the others as last planned): rates for the
    // papers, a slot's crypto time for the uBFT modes.
    let head = |m: Mode| {
        let i = Mode::ALL.iter().position(|&x| x == m).unwrap();
        let d = if m == app.mode { Some(&plan.delivered) } else { app.headline[i].as_ref() };
        let Some(d) = d else {
            return format!("{}: not planned", m.short());
        };
        if m.is_ubft() {
            let n = ubft::UBFT_REPLICAS[0];
            format!("{}: slot crypto serial model {} at n={n} (no measured speedup)", m.short(), micros(ubft::serial_slot_crypto_us(d, n)))
        } else {
            format!("{}: {}/s sign, {}/s verify", m.short(), rate(d.sign.rate), rate(d.verify.rate))
        }
    };
    frame.render_widget(
        Paragraph::new(vec![
            Line::from(Span::styled(
                format!(
                    "{}   {} MHz   now: {}{}",
                    app.title,
                    app.cx.mhz,
                    app.mode.name(),
                    if app.papers().len() > 1 { "   (P switches paper)" } else { "" }
                ),
                Style::default().fg(Color::Cyan).add_modifier(Modifier::BOLD),
            )),
            Line::from({
                let style =
                    |m: Mode| Style::default().fg(if app.mode == m { Color::Green } else { Color::DarkGray }).add_modifier(Modifier::BOLD);
                // Only the papers compiled into this build (the Ed25519-only
                // tuner has no DSig paper to show).
                let mut spans = Vec::new();
                for m in app.papers() {
                    if !spans.is_empty() {
                        spans.push(Span::raw("    "));
                    }
                    spans.push(Span::styled(head(m), style(m)));
                }
                if !app.has_paper(Mode::Dsig) {
                    spans.push(Span::raw("    (no DSig in this build: `cargo tuner` builds both papers)"));
                }
                spans
            }),
        ]),
        areas[0],
    );
    let cols = Layout::horizontal([Constraint::Percentage(42), Constraint::Percentage(58)]).split(areas[1]);

    // Controls, scrolled to keep the selection visible.
    let controls = app.controls();
    let block = Block::default().borders(Borders::ALL).title(" Controls ");
    let inner = block.inner(cols[0]);
    frame.render_widget(block, cols[0]);
    let height = inner.height as usize;
    let first = app.selected.saturating_sub(height.saturating_sub(1));
    let lines: Vec<Line> = controls
        .iter()
        .enumerate()
        .skip(first)
        .take(height)
        .map(|(i, &c)| {
            let style = if i == app.selected {
                Style::default().fg(Color::Yellow).add_modifier(Modifier::BOLD)
            } else if matches!(c, Control::Module(_) | Control::Mode | Control::SignPower | Control::VerifyPower | Control::Background) {
                Style::default().add_modifier(Modifier::BOLD)
            } else {
                Style::default()
            };
            Line::from(Span::styled(format!("{} {}", if i == app.selected { ">" } else { " " }, app.label(c)), style))
        })
        .collect();
    frame.render_widget(Paragraph::new(lines), inner);

    // Right: the two sides, one card per module in the mode, the chip.
    let d = &plan.delivered;
    let shown: Vec<usize> = (0..app.slots.len()).filter(|&k| app.mode.admits(&*app.slots[k].component)).collect();
    let roles: Vec<Role> = Role::OPS.iter().copied().filter(|r| d.need(*r) > 0.0).collect();
    let ubft_rows = if app.mode.is_ubft() { 3 + ubft::UBFT_REPLICAS.len() } else { 0 };
    let summary_height = 2 + 2 + roles.len() + d.services.len() + usize::from(d.batch_mismatch) + ubft_rows;
    let mut rows = vec![Constraint::Length(summary_height as u16)];
    rows.extend(shown.iter().map(|_| Constraint::Length(4)));
    rows.push(Constraint::Length(3));
    rows.push(Constraint::Min(0));
    let right = Layout::vertical(rows).split(cols[1]);

    let block = Block::default().borders(Borders::ALL).title(if app.balanced {
        " Delivered (balanced for the mix) "
    } else {
        " Delivered (B balances) "
    });
    let inner = block.inner(right[0]);
    frame.render_widget(block, right[0]);
    let mut lines = Vec::new();
    for (side, color) in [(Side::Sign, Color::Green), (Side::Verify, Color::Magenta)] {
        let s = d.side(side);
        lines.push(Line::from(vec![
            Span::styled(format!("{:>8}/s {}", rate(s.rate), app.mode.op(side)), Style::default().fg(color).add_modifier(Modifier::BOLD)),
            Span::raw(format!("   latency {}   limited by {}", micros(s.latency_us), s.bottleneck)),
        ]));
    }
    for role in &roles {
        let capacity: f64 = shown
            .iter()
            .filter(|&&k| app.slots[k].component.role() == *role)
            .filter_map(|&k| plan.parts[k].1.as_ref().map(|p| p.rate))
            .sum();
        lines.push(Line::from(format!(
            "  {:<15} {:>8}/s of {:>8}/s capacity  {:>7} latency  ({:.4} per {})",
            role.name(),
            rate(d.of(*role)),
            rate(capacity),
            micros(d.latency_of(*role)),
            d.need(*role),
            role.side().map_or("", |s| s.name())
        )));
    }
    for s in &d.services {
        let text = format!(
            "  {:<15} {:>8}/s of {:>8}/s supply{}",
            s.name,
            rate(s.demand),
            rate(s.supply),
            if d.sha_bound { "   <- limits the chip" } else { "" }
        );
        lines.push(Line::from(Span::styled(text, Style::default().fg(if d.sha_bound { Color::Red } else { Color::Reset }))));
    }
    if d.batch_mismatch {
        lines.push(Line::from(Span::styled(
            format!("  DSig sign and verify use different batch sizes; using the signer's K = {}", d.batch),
            Style::default().fg(Color::Red),
        )));
    }
    // A uBFT slot: one share signed, 2f peers' shares verified.
    if app.mode.is_ubft() {
        lines.push(Line::from(Span::styled(
            format!(
                "  target: {:.0}x completed operations over both baselines on card (not measured; failed runs are not divisors)",
                ubft::UBFT_TARGET_SPEEDUP
            ),
            Style::default().fg(Color::Yellow),
        )));
        lines.push(Line::from(Span::styled(
            "  uBFT slot crypto SERIAL MODEL (sign + 2f sequential verifies; excludes network/recovery)",
            Style::default().add_modifier(Modifier::BOLD),
        )));
        lines.push(Line::from("  HLS baseline: unmatched 1-byte input; no ratio."));
        lines.push(Line::from("  Replica BRAM/URAM allowance: unknown."));
        let capacity = app.slots.iter().filter(|slot| slot.component.ubft() && slot.component.role() == Role::Other)
            .flat_map(|slot| slot.component.knobs()).find(|knob| knob.name == "replica capacity (N)")
            .map_or(16, |knob| knob.value as u32);
        for n in ubft::UBFT_REPLICAS {
            if n > capacity { continue; }
            let t = ubft::serial_slot_crypto_us(d, n);
            lines.push(Line::from(format!(
                "  n = {n:<2} ({} verifies)  {:>9} projected crypto time; no system ratio",
                ubft::quorum_verifies(n),
                micros(t)
            )));
        }
    }
    frame.render_widget(Paragraph::new(lines), inner);

    for (row, &k) in shown.iter().enumerate() {
        let slot = &app.slots[k];
        let color = COLORS[k % COLORS.len()];
        let (share, p) = &plan.parts[k];
        let lent = slot.component.fixed().is_none() && *share != plan.guaranteed[k];
        let area = right[row + 1];
        let side = slot.component.role().side().map_or(String::new(), |s| format!(" ({} side)", s.name()));
        let block = Block::default().borders(Borders::ALL).title(format!(" {}{side} ", slot.component.name()));
        let inner = block.inner(area);
        frame.render_widget(block, area);
        let parts = Layout::vertical([Constraint::Length(1), Constraint::Length(1)]).split(inner);
        match p {
            Some(p) => {
                frame.render_widget(
                    Paragraph::new(Line::from(vec![
                        Span::styled(format!("{} {}/s", rate(p.rate), p.unit), Style::default().fg(color).add_modifier(Modifier::BOLD)),
                        Span::raw(format!(
                            "  {}  lat {} idle / {} loaded{}{}  [{}; limit {}; {}]",
                            p.detail,
                            micros(p.idle_latency_us(app.cx.mhz)),
                            micros(p.loaded_latency_us(app.cx.mhz)),
                            if d.sha_bound && p.demands.iter().any(|f| f.service == SHA512_BLOCKS) { ", SHA-limited" } else { "" },
                            if lent { ", uses resources other modules left free" } else { "" },
                            if p.measured { "measured" } else { "model" },
                            p.limit,
                            if slot.component.fixed().is_some() {
                                "fixed allowance".to_string()
                            } else {
                                match next_step(slot, share, &app.cx, p.rate) {
                                    Some((lut, r)) => {
                                        format!("next: +{} LUT -> {}/s", kilo(lut), rate(r))
                                    }
                                    None => "next: not within +64k LUT".to_string(),
                                }
                            }
                        )),
                    ])),
                    parts[0],
                );
                gauge_row(frame, parts[1], p.cost, *share, color);
            }
            None => frame.render_widget(
                Paragraph::new(if let Some(why) = slot.component.unavailable() {
                    why
                } else if slot.power > 0.0 || slot.component.fixed().is_some() {
                    let first = next_step(slot, share, &app.cx, 0.0)
                        .map_or("its first build needs more than +64k LUT (or another resource)".to_string(), |(lut, r)| {
                            format!("its first build needs +{} LUT ({}/s)", kilo(lut), rate(r))
                        });
                    format!("Nothing fits a {:.1} % share ({} LUT): {first}.", slot.power, kilo(share.lut))
                } else {
                    "Off (no share).".to_string()
                })
                .style(Style::default().fg(Color::DarkGray)),
                parts[0],
            ),
        }
    }
    let n = shown.len();
    let block = Block::default().borders(Borders::ALL).title(" Whole chip (budget + SHA line) ");
    let inner = block.inner(right[n + 1]);
    frame.render_widget(block, right[n + 1]);
    gauge_row(frame, inner, plan.total, app.budget.chip(), Color::Cyan);

    frame.render_widget(Paragraph::new(app.status.as_str()).wrap(Wrap { trim: true }), areas[2]);
    frame.render_widget(
        Paragraph::new("Up/Down select  Left/Right adjust (Shift x5)  B balance  P switch paper  W write build flags  Q quit"),
        areas[3],
    );
}

/// Run the planner on any backend until Q.
pub fn run_on<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
    loop {
        terminal.draw(|f| draw(f, app))?;
        if let Event::Key(key) = event::read()? {
            if key.kind == KeyEventKind::Press && !app.key(key.code, key.modifiers.contains(KeyModifiers::SHIFT)) {
                return Ok(());
            }
        }
    }
}

/// Run the planner in the terminal.
pub fn run(title: &str, mode: Mode, slots: Vec<Slot>) -> io::Result<()> {
    let mut app = App::new(title, mode, slots);
    let mut terminal = ratatui::init();
    let result = run_on(&mut terminal, &mut app);
    ratatui::restore();
    result
}

/// Render `app` into text (for tests and documentation).
pub fn snapshot(app: &App, width: u16, height: u16) -> String {
    let mut t = Terminal::new(ratatui::backend::TestBackend::new(width, height)).unwrap();
    t.draw(|f| draw(f, app)).unwrap();
    let buf = t.backend().buffer().clone();
    let mut out = String::new();
    for y in 0..buf.area.height {
        let line: String = (0..buf.area.width).map(|x| buf[(x, y)].symbol().to_string()).collect();
        out.push_str(line.trim_end());
        out.push('\n');
    }
    out
}

/// TUI rendering and key handling tests.
#[cfg(test)]
mod tests {
    use super::*;
    use crate::{Component, Knob, Plan};

    /// A module with one shared choice knob and nothing to plan.
    struct SharedKnob(f64);
    impl Component for SharedKnob {
        fn name(&self) -> String {
            "shared".into()
        }
        fn role(&self) -> Role {
            Role::Ed25519Sign
        }
        fn knobs(&self) -> Vec<Knob> {
            vec![Knob { value: self.0, ..Knob::choice("scheme", 0, &["a", "b"]).shared() }]
        }
        fn set_knob(&mut self, _: usize, value: f64) {
            self.0 = value;
        }
        fn plan(&self, _: &Share, _: &Context) -> Option<Plan> {
            None
        }
    }

    /// Both papers render at several sizes; sign and verify are reported
    /// separately; moving power from verify to sign moves the rates.
    #[test]
    fn renders_both_modes_with_separate_sides() {
        let mut app = App::new("TEST", Mode::Ed25519, crate::demo::chip());
        let ed = snapshot(&app, 130, 40);
        assert!(ed.contains("Ed25519 signatures") && ed.contains("Ed25519 verifications"), "{ed}");
        let before = app.plan().delivered;
        app.selected = app.controls().iter().position(|c| *c == Control::SignPower).unwrap();
        app.adjust(10.0);
        let after = app.plan().delivered;
        assert!(after.sign.rate >= before.sign.rate && after.verify.rate <= before.verify.rate);
        assert_eq!(app.powers.sign + app.powers.verify, 100.0);
        app.selected = 0;
        app.adjust(1.0); // Mode -> DSig, rebalanced.
        assert_eq!(app.mode, Mode::Dsig);
        let ds = snapshot(&app, 130, 44);
        assert!(ds.contains("DSig signatures") && ds.contains("DSig verifications") && ds.contains("Ed25519 sign"), "{ds}");
        // Every split sums to 100: foreground + background, HBSS sign +
        // verify, Ed25519 sign + verify; a manual background is applied.
        app.selected = app.controls().iter().position(|c| *c == Control::Background).unwrap();
        app.adjust(4.0);
        let b = app.bg.share.expect("manual");
        let p: Vec<f64> = app.slots.iter().map(|s| s.power).collect();
        // demo::chip order: Ed sign, Ed verify, DSig sign, DSig verify.
        assert!((p[0] + p[1] - b).abs() < 1e-9 && (p[2] + p[3] - (100.0 - b)).abs() < 1e-9, "{b} {p:?}");
        // A shared knob is listed once and sets every module that has it.
        let mut shared = App::new("TEST", Mode::Ed25519, crate::demo::chip());
        for k in [0, 1] {
            shared.slots[k] = Slot::new(Box::new(SharedKnob(0.0)), 0.0);
        }
        let rows: Vec<Control> = shared.controls().into_iter().filter(|c| matches!(c, Control::Knob(_, _))).collect();
        assert_eq!(rows.len(), 2 + 2, "the shared knob under both modules plus the SHA line's two: {rows:?}");
        shared.selected = shared.controls().iter().position(|c| *c == Control::Knob(0, 0)).unwrap();
        shared.adjust(1.0);
        assert_eq!(shared.slots[1].component.knobs()[0].value, 1.0);
        for (w, h) in [(80, 24), (50, 16)] {
            assert!(snapshot(&app, w, h).contains("TEST"));
        }
        println!("{ed}\n{ds}");
    }

    /// A chip with a uBFT service offers its mode after the papers; the
    /// mode plans on the whole device and its headline is a slot's crypto
    /// time with explicit baseline and resource limitations. Switching back restores the
    /// papers' budget.
    #[test]
    fn ubft_mode_is_offered_and_rendered() {
        let mut app = App::new("TEST", Mode::Ed25519, crate::demo::ubft_chip());
        assert_eq!(app.papers(), [Mode::Dsig, Mode::Ed25519, Mode::UbftEd25519]);
        app.selected = 0;
        app.adjust(1.0); // Ed25519 -> uBFT+Ed25519.
        assert_eq!(app.mode, Mode::UbftEd25519);
        assert_eq!(app.budget, Budget::whole_device());
        let u = snapshot(&app, 150, 44);
        assert!(u.contains("slot crypto") && u.contains("HLS baseline") && u.contains("uBFT replica") && u.contains("n = 7"), "{u}");
        assert!(!u.contains("DSig sign  "), "{u}");
        assert!(!u.contains("x faster") && u.contains("MODEL") && u.contains("unknown"), "{u}");
        app.adjust(1.0); // -> DSig paper, back on the engine budget.
        assert_eq!(app.mode, Mode::Dsig);
        assert_eq!(app.budget, Budget::default());
        println!("{u}");
    }
}