Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

61.3 KB
Raw Blame
//! The terminal hn draws on: ratatui's crossterm backend, with colours written as tmux writes
//! them — the eight colours and their bright forms as SGR 30–37, 90–97 (40–47, 100–107 behind),
//! and so `colour0`–`colour15` too (terminfo's setaf/setab do that for the first sixteen),
//! `colourN` past them as 38;5;N, RGB as 38;2;R;G;B — where crossterm writes every colour as
//! 38;5;N, which an eight-colour terminal (the Linux console) does not read. Everything else is
//! crossterm's.

use std::io::{self, Write};

use ratatui::backend::{Backend, ClearType, CrosstermBackend, WindowSize};
use ratatui::buffer::Cell;
use ratatui::layout::{Position, Size};
use ratatui::style::{Color, Modifier};

/// [shadow]: every cell as last written, row by row — so a row whose width the terminal may
/// count otherwise can be written again whole.
pub struct TmuxBackend<W: Write> {
    inner: CrosstermBackend<W>,
    shadow: Vec<Vec<Cell>>,
    extra_shadow: std::collections::HashMap<(u16, u16), Extra>,
    /// A frame with several changes is one synchronized update (?2026), closed at its flush.
    syncing: bool,
    /// Whether that is done at all (`HARNESS_TUI_SYNC=off` turns it off).
    sync_ok: bool,
    /// The next clear-all writes the screen again row by row instead of erasing it first (see
    /// [`TmuxBackend::soft_clear_next`]); `force_whole` is that rewrite waiting for its draw.
    soft: bool,
    force_whole: bool,
    /// The cursor as last written: a frame that changes nothing writes nothing (an idle hn is
    /// silent, as tmux is — a terminal's or an outer tmux's activity mark stays clear).
    cursor_at: Option<Position>,
    cursor_shown: Option<bool>,
    /// How many cells the last frame wrote (0 for one that wrote nothing): a large one is a
    /// burst the settle rewrite follows.
    last_cells: usize,
    /// The terminal's size as a test gives it (else the terminal is asked).
    size_known: Option<Size>,
    /// The rows written cell by cell (or owed) since the last settle rewrite, and the rows that
    /// rewrite writes whole in the next frame.
    touched: std::collections::BTreeSet<u16>,
    rewrite: std::collections::BTreeSet<u16>,
}

/// Whether a frame is wrapped in synchronized output (?2026): yes, unless `HARNESS_TUI_SYNC=off`
/// (a terminal that mishandles it, e.g. ghostty-org/ghostty discussion 12062).
fn sync_wanted(setting: &str) -> bool {
    !matches!(setting.to_ascii_lowercase().as_str(), "off" | "0" | "false")
}

/// A cluster whose width terminals may count otherwise than hn does: several code points (a
/// base and its marks, ZWJ emoji, a keycap, VS16), or a script whose vowels some count as
/// spacing and some as combining (Thai, Lao, Tibetan, Myanmar, Khmer).
pub(crate) fn risky(symbol: &str) -> bool {
    let mut n = 0;
    for c in symbol.chars() {
        n += 1;
        if n > 1 { return true }
        let u = c as u32;
        if (0x0E00..=0x0FFF).contains(&u) || (0x1000..=0x109F).contains(&u) || (0x1780..=0x17FF).contains(&u) { return true }
        // One code point, but terminals and unicode-width part on it: private-use icons (Nerd
        // Font), the arrows, shapes and dingbats of ambiguous width (⚡ ✓ ● ▶), and emoji.
        // Box-drawing and block characters (U+2500–259F) are every border's and count alike.
        if (0xE000..=0xF8FF).contains(&u) || (0xF0000..=0x10FFFF).contains(&u)
            || ((0x2190..=0x2BFF).contains(&u) && !(0x2500..=0x259F).contains(&u))
            || (0x1F000..=0x1FAFF).contains(&u) { return true }
    }
    false
}

/// What the terminal was last told: colours, attributes, the underline's style, the open link.
struct Pen { fg: Color, bg: Color, ul: Color, modifier: Modifier, style: u8, overline: bool, link: Option<std::sync::Arc<str>> }

impl Pen {
    fn new() -> Pen { Pen { fg: Color::Reset, bg: Color::Reset, ul: Color::Reset, modifier: Modifier::empty(), style: 0, overline: false, link: None } }

    /// A cell's attributes (as tmux's tty_attributes writes them) and its symbol.
    fn put(&mut self, w: &mut impl Write, cell: &Cell, extra: Option<&Extra>, usstyle: bool, links: bool) -> io::Result<()> {
        // The colours fitted to the terminal (tty_check_fg / _bg): a bright foreground where
        // there are only 8 colours is its plain colour, bold.
        let (fg, bold) = fit_bright(cell.fg);
        let (bg, ul) = (fit(cell.bg), fit(cell.underline_color));
        let modifier = if bold { cell.modifier | Modifier::BOLD } else { cell.modifier };
        if modifier != self.modifier {
            // tmux's tty_attributes: an attribute taken away resets everything, then what is
            // wanted is set again.
            if !(self.modifier - modifier).is_empty() {
                w.write_all(b"\x1b[0m")?;
                (self.fg, self.bg, self.ul, self.modifier, self.style, self.overline) = (Color::Reset, Color::Reset, Color::Reset, Modifier::empty(), 0, false);
            }
            for (flag, code) in ATTRS { if modifier.contains(flag) && !self.modifier.contains(flag) { write!(w, "\x1b[{code}m")?; if code == 4 { self.style = 1 } } }
            self.modifier = modifier;
        }
        // tty_attributes' Smulx: a curly (double, dotted, dashed) underline where the
        // terminal reads one, else a plain one.
        let want = if !cell.modifier.contains(Modifier::UNDERLINED) { 0 } else if usstyle { extra.map(|e| e.underline).filter(|u| *u >= 2).unwrap_or(1) } else { 1 };
        if want != self.style && want > 0 { if want == 1 { w.write_all(b"\x1b[4:1m")? } else { write!(w, "\x1b[4:{want}m")? } self.style = want }
        let overline = extra.is_some_and(|e| e.overline);
        if overline != self.overline { w.write_all(if overline { b"\x1b[53m" } else { b"\x1b[55m" })?; self.overline = overline; }
        if fg != self.fg { write!(w, "\x1b[{}m", sgr(fg, 30))?; self.fg = fg; }
        if bg != self.bg { write!(w, "\x1b[{}m", sgr(bg, 40))?; self.bg = bg; }
        if usstyle && ul != self.ul { write!(w, "\x1b[{}m", sgr_underline(ul))?; self.ul = ul; }
        // A link (OSC 8) opened where it starts and closed where it ends.
        let want_link = if links { extra.and_then(|e| e.link.clone()) } else { None };
        if want_link != self.link {
            match &want_link { Some(uri) => write!(w, "\x1b]8;;{uri}\x1b\\")?, None => w.write_all(b"\x1b]8;;\x1b\\")? }
            self.link = want_link;
        }
        // A cell is printed, never executed: a control character (a tab a pane's grid keeps, a
        // stray escape) would move the terminal's cursor where hn does not count it, and every
        // cell after it on the row would land elsewhere. It goes as the blank it stands for.
        let symbol = cell.symbol();
        if symbol.chars().any(char::is_control) { return w.write_all(b" ") }
        w.write_all(symbol.as_bytes())
    }

    /// Everything back to the terminal's defaults (and so known).
    fn reset(&mut self, w: &mut impl Write) -> io::Result<()> {
        if self.link.is_some() { w.write_all(b"\x1b]8;;\x1b\\")? }
        if self.fg != Color::Reset || self.bg != Color::Reset || self.ul != Color::Reset || !self.modifier.is_empty() || self.style != 0 || self.overline {
            w.write_all(b"\x1b[0m")?;
        }
        *self = Pen::new();
        Ok(())
    }
}

/// What a pane's cell carries that ratatui's cell cannot: its underline's style (2 double, 3
/// curly, 4 dotted, 5 dashed — tmux's 4:N) and its link (OSC 8). Kept by position for the frame
/// being drawn (ui's pane_body), and written with the cell when the outer terminal reads them.
#[derive(Clone, PartialEq, Default, Debug)]
pub struct Extra { pub underline: u8, pub overline: bool, pub link: Option<std::sync::Arc<str>> }

struct Frame { extras: std::collections::HashMap<(u16, u16), Extra>, usstyle: bool, links: bool }
static FRAME: std::sync::Mutex<Option<Frame>> = std::sync::Mutex::new(None);

/// A frame begins: no cell's extras yet, and what the outer terminal reads — styled and coloured
/// underlines (tmux's usstyle feature), links (hyperlinks).
pub fn begin_frame(usstyle: bool, links: bool) {
    if let Ok(mut f) = FRAME.lock() { *f = Some(Frame { extras: Default::default(), usstyle, links }) }
}

pub fn set_extra(x: u16, y: u16, extra: Extra) {
    if let Ok(mut f) = FRAME.lock() { if let Some(f) = f.as_mut() { f.extras.insert((x, y), extra); } }
}

/// A full repaint rewrites rows over what the terminal holds, unless its size changed: then the
/// terminal reflowed its own cells and only an erase leaves no text outside the new rows.
pub fn repaint_is_soft(drawn: Size, now: Size) -> bool { drawn == now }

/// An overlay owns its cells; pane metadata underneath must not bleed through it.
pub fn clear_extras(area: ratatui::layout::Rect) {
    if let Ok(mut frame) = FRAME.lock() { if let Some(frame) = frame.as_mut() {
        frame.extras.retain(|&(x, y), _| !area.contains(Position::new(x, y)));
    } }
}

/// Whether the outer terminal reads styled underlines with their colour (usstyle) and links
/// (hyperlinks): terminal-features for this TERM (as tmux's), else the terminals known to.
pub fn outer_features(features: &[String]) -> (bool, bool) {
    static KNOWN: std::sync::OnceLock<(String, bool)> = std::sync::OnceLock::new();
    let (term, known) = KNOWN.get_or_init(|| {
        let term = std::env::var("TERM").unwrap_or_default();
        let program = std::env::var("TERM_PROGRAM").unwrap_or_default();
        let known = matches!(program.as_str(), "iTerm.app" | "WezTerm" | "ghostty" | "vscode" | "tmux")
            || ["xterm-kitty", "xterm-ghostty", "wezterm", "alacritty", "foot", "tmux", "contour", "rio"].iter().any(|t| term.starts_with(t));
        (term, known)
    });
    // (A terminal that said what it is and has them: tmux's features for it.)
    let said = terminal_name().map(|n| n.to_lowercase()).is_some_and(|n| ["iterm2", "tmux", "wezterm", "foot", "kitty", "ghostty", "contour", "rio"].iter().any(|p| n.starts_with(p)));
    let (mut us, mut links) = (*known || said, *known || said);
    for f in features {
        let (pattern, rest) = f.split_once(':').unwrap_or((f.as_str(), ""));
        if !crate::cmd::fnmatch(pattern, term) { continue }
        for x in rest.split(':') { match x { "usstyle" => us = true, "hyperlinks" => links = true, _ => {} } }
    }
    (us, links)
}

impl<W: Write> TmuxBackend<W> {
    pub fn new(writer: W) -> Self {
        let sync_ok = sync_wanted(&std::env::var("HARNESS_TUI_SYNC").unwrap_or_default());
        Self { sync_ok, ..Self::with_sync(writer) }
    }

    fn with_sync(writer: W) -> Self { Self { inner: CrosstermBackend::new(writer), shadow: Vec::new(), extra_shadow: Default::default(), syncing: false, sync_ok: true, soft: false, force_whole: false, cursor_at: None, cursor_shown: None, last_cells: 0, size_known: None, touched: Default::default(), rewrite: Default::default() } }

    fn screen_size(&self) -> Option<Size> { self.size_known.or_else(|| self.inner.size().ok()) }

    /// The next `clear()` does not erase the screen: every row is written again, its text and then
    /// the rest of it erased, so a stale cell goes but the screen is never seen blank.
    pub fn soft_clear_next(&mut self) { self.soft = true }

    /// The cells the last frame wrote.
    pub fn last_cells(&self) -> usize { self.last_cells }

    /// Rows the next settle rewrite writes too (where an overlay was).
    pub fn owe_rows(&mut self, rows: impl IntoIterator<Item = u16>) { self.touched.extend(rows) }

    /// The settle rewrite: the next frame writes whole every row touched since the last one (and
    /// nothing when none was: an idle hn stays silent).
    pub fn settle_next(&mut self) { let touched = std::mem::take(&mut self.touched); self.rewrite.extend(touched) }

    /// Opens the frame's synchronized update (once); `flush` closes it. A clear belongs inside it,
    /// so the terminal shows the erase and the redraw together, never the blank between them.
    fn begin_sync(&mut self) -> io::Result<()> {
        if self.sync_ok && !self.syncing { self.inner.write_all(b"\x1b[?2026h")?; self.syncing = true }
        Ok(())
    }

    fn row_risky(&self, y: u16) -> bool { self.shadow.get(y as usize).map(|r| r.iter().any(|c| risky(c.symbol()))).unwrap_or(false) }

    fn remember(&mut self, x: u16, y: u16, cell: &Cell) {
        let (x, y) = (x as usize, y as usize);
        if self.shadow.len() <= y { self.shadow.resize(y + 1, Vec::new()) }
        // (A wide cluster covers the cells after it: ratatui blanks them and sends none.)
        let wide = unicode_width::UnicodeWidthStr::width(cell.symbol()).max(1);
        let row = &mut self.shadow[y];
        if row.len() < x + wide { row.resize(x + wide, Cell::default()) }
        row[x] = cell.clone();
        for c in &mut row[x + 1..x + wide] { *c = Cell::default() }
    }
}

/// What has been written to the terminal, in bytes (#{client_written}).
pub static WRITTEN: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);

/// The terminal's writer, its bytes counted.
pub struct Counted<W: Write>(pub W);

impl<W: Write> Write for Counted<W> {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        let n = self.0.write(buf)?;
        WRITTEN.fetch_add(n as u64, std::sync::atomic::Ordering::Relaxed);
        crate::verify::capture(&buf[..n]);
        Ok(n)
    }
    fn flush(&mut self) -> io::Result<()> { self.0.flush() }
}

impl<W: Write> Write for TmuxBackend<W> {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> { self.cursor_at = None; self.inner.write(buf) }
    fn flush(&mut self) -> io::Result<()> { Write::flush(&mut self.inner) }
}

/// The mouse modes tmux asks the terminal for (tty_update_mode): presses, drags and SGR (1000,
/// 1002, 1006) — and every motion (1003) only while a pane or a menu wants it. 0 off, 1 on, 2 all.
pub struct Mouse(pub u8);

impl crossterm::Command for Mouse {
    fn write_ansi(&self, f: &mut impl std::fmt::Write) -> std::fmt::Result {
        f.write_str(match self.0 { 0 => "\x1b[?1006l\x1b[?1000l\x1b[?1002l\x1b[?1003l", 1 => "\x1b[?1003l\x1b[?1006h\x1b[?1000h\x1b[?1002h", _ => "\x1b[?1006h\x1b[?1000h\x1b[?1002h\x1b[?1003h" })
    }
    #[cfg(windows)]
    fn execute_winapi(&self) -> io::Result<()> { Ok(()) }
}

/// What the terminal said it is (XDA, `CSI > q`: `iTerm2 3.5.4`, `tmux 3.5a`, `kitty(0.36.4)`),
/// as tmux asks it at attach; None when it said nothing.
static TERMINAL: std::sync::OnceLock<String> = std::sync::OnceLock::new();
static TERMINAL_ANSWERED: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// Query without waiting: the normal input reader separates replies from typeahead.
/// OSC 11 (default background) is asked, and now OSC 10 (default foreground) too: hn reports
/// them to each machine's daemon (`theme_set`) so agent panes are painted to match, exactly as
/// the desktop app does. Asking OSC 10 is what keeps hn's chrome on the terminal's own
/// foreground (an ivory/cream), not a white computed from the background. OSC 4 asks the terminal's
/// own colours 1-7 too: with no theme chosen, hn's accent is one of them (`native_accent`), so the
/// focused pane, the current tab and the panels' marks are in the terminal's theme, not a fixed teal.
pub fn ask_terminal() {
    let mut out = io::stdout();
    let _ = out.write_all(b"\x1b[>q\x1b[c\x1b]11;?\x07\x1b]10;?\x07\x1b]4;1;?\x07\x1b]4;2;?\x07\x1b]4;3;?\x07\x1b]4;4;?\x07\x1b]4;5;?\x07\x1b]4;6;?\x07\x1b]4;7;?\x07");
    let _ = out.flush();
}

/// What hn draws with that the terminal answered or the look chose: one for the whole process —
/// and in tests each test thread's own, as the fzf look is (theme.rs): tests run side by side, and
/// each draws with the colours it set, not with what another set meanwhile.
struct Kept<T: 'static> {
    #[cfg(not(test))]
    shared: std::sync::RwLock<T>,
    #[cfg(test)]
    local: &'static std::thread::LocalKey<std::cell::RefCell<T>>,
}

impl<T: Clone> Kept<T> {
    fn get(&self) -> T {
        #[cfg(not(test))]
        { self.shared.read().unwrap_or_else(|e| e.into_inner()).clone() }
        #[cfg(test)]
        { self.local.with(|c| c.borrow().clone()) }
    }

    fn update<R>(&self, f: impl FnOnce(&mut T) -> R) -> R {
        #[cfg(not(test))]
        { f(&mut self.shared.write().unwrap_or_else(|e| e.into_inner())) }
        #[cfg(test)]
        { self.local.with(|c| f(&mut c.borrow_mut())) }
    }
}

/// A [Kept] named [$name] of type [$t], starting as [$init].
macro_rules! kept {
    ($name:ident, $local:ident, $t:ty, $init:expr) => {
        #[cfg(test)]
        thread_local! { static $local: std::cell::RefCell<$t> = const { std::cell::RefCell::new($init) }; }
        #[cfg(not(test))]
        static $name: Kept<$t> = Kept { shared: std::sync::RwLock::new($init) };
        #[cfg(test)]
        static $name: Kept<$t> = Kept { local: &$local };
    };
}

// The terminal's colours 1-7 as it answered OSC 4 (`#rrggbb`), where it did.
kept!(PALETTE, PALETTE_HERE, [Option<[u8; 3]>; 8], [None; 8]);

/// Record an OSC 4 answer for colour [n] (1-7 are kept; the rest are not asked).
pub fn set_palette_colour(n: u8, colour: Option<String>) {
    let Some((r, g, b)) = colour.as_deref().and_then(hex_rgb) else { return };
    if (1..8).contains(&n) { PALETTE.update(|p| p[n as usize] = Some([r, g, b])) }
}

/// The accent the terminal's own theme gives, when it answered its colours and its background:
/// picked from colours 1-7 as a bundled theme's is (`theme::accent_of`).
pub fn native_accent() -> Option<[u8; 3]> {
    let (bg, _) = native_terminal_colours()?;
    let (r, g, b) = hex_rgb(&bg)?;
    let p = PALETTE.get();
    let colours: Vec<(usize, [u8; 3])> = (1..8).filter_map(|i| p[i].map(|c| (i, c))).collect();
    // (Most of them, or it is not the terminal's palette speaking.)
    if colours.len() < 5 { return None }
    Some(crate::theme::accent_of([r, g, b], &colours))
}

pub fn terminal_answer(answer: Option<String>) -> bool {
    let first = !TERMINAL_ANSWERED.swap(true, std::sync::atomic::Ordering::Relaxed);
    answer.map(|name| TERMINAL.set(name).is_ok()).unwrap_or(false) || first
}

/// The terminal's own name for itself (XDA), when it gave one.
pub fn terminal_name() -> Option<&'static str> { TERMINAL.get().map(String::as_str) }

/// A terminal that says what it is and is one tmux gives 24-bit colour (tty_default_features:
/// iTerm2, tmux, WezTerm, foot, XTerm, mintty) — or one of today's that has it too.
fn modern_terminal() -> bool {
    let Some(name) = terminal_name() else { return false };
    let n = name.to_lowercase();
    ["iterm2", "tmux", "wezterm", "foot", "xterm(", "mintty", "kitty", "ghostty", "alacritty", "contour", "rio", "konsole", "xterm.js", "warp", "vte"].iter().any(|p| n.starts_with(p))
}

/// How many colours the terminal shows, as tmux reads it (terminfo's colors; 24-bit with RGB):
/// 0, 8, 16, 256, or 1 << 24.
static COLOURS: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(1 << 24);

pub fn set_colours(n: u32) { COLOURS.store(n, std::sync::atomic::Ordering::Relaxed) }

/// The terminal's own default background and foreground, from its OSC 10/11 answers, as
/// `#rrggbb` (bg, fg). None until the terminal answers. hn starts on top of the terminal, so
/// these are asked directly and answer reliably; the daemon uses them to paint agent panes.
#[derive(Clone)]
struct TerminalColours { bg: String, fg: String, foreground_reported: bool }
kept!(TERMINAL_FG_BG, TERMINAL_FG_BG_HERE, Option<TerminalColours>, None);

fn hex_rgb(hex: &str) -> Option<(u8, u8, u8)> {
    let h = hex.trim_start_matches('#');
    if h.len() != 6 { return None }
    let v = u32::from_str_radix(h, 16).ok()?;
    Some(((v >> 16) as u8, ((v >> 8) & 0xff) as u8, (v & 0xff) as u8))
}

/// A foreground that reads on the background: dark on light, light on dark.
fn companion_fg(bg: &str) -> String {
    let Some((r, g, b)) = hex_rgb(bg) else { return "#f5f5f5".into() };
    let lum = 0.299 * r as f64 + 0.587 * g as f64 + 0.114 * b as f64;
    if lum > 128.0 { "#1a1a1a".into() } else { "#f5f5f5".into() }
}

/// What the terminal answered for its default colours, (bg, fg) hex, when it answered.
/// A theme chosen in the settings (`@hn-theme`) stands in for them: hn's chrome, and the panes the
/// daemon paints, take the theme's background and foreground.
pub fn terminal_colours() -> Option<(String, String)> {
    if let Some(theme) = THEME_COLOURS.get() { return Some(theme) }
    native_terminal_colours()
}

/// The terminal's own answer, whatever theme is chosen (the settings' "Terminal default").
pub fn native_terminal_colours() -> Option<(String, String)> {
    TERMINAL_FG_BG.get().map(|c| (c.bg, c.fg))
}

// The chosen theme's (background, foreground) as `#rrggbb`; None: the terminal's own.
kept!(THEME_COLOURS, THEME_COLOURS_HERE, Option<(String, String)>, None);

/// Tests that set hn's colours (a theme, an accent) or read them back held this, one at a time,
/// when the colours were one for the whole test process; they are each test thread's own now
/// ([Kept]), so it only orders those tests.
#[cfg(test)]
pub fn colours_lock() -> std::sync::MutexGuard<'static, ()> {
    static LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
    LOCK.lock().unwrap_or_else(|e| e.into_inner())
}

/// Whether a theme's colours stand in for the terminal's now.
pub fn theme_chosen() -> bool { THEME_COLOURS.get().is_some() }

/// Draw with a theme's colours (or, None, the terminal's again). True when that changed them.
pub fn set_theme_colours(colours: Option<(String, String)>) -> bool {
    THEME_COLOURS.update(|g| { let changed = *g != colours; *g = colours; changed })
}

// The `[look]` accent (`@hn-accent`, a `#rrggbb`) to draw hn's chrome with, when the look names
// one. Kept separate from the terminal palette because an accent is a choice, not a terminal
// answer; `theme::accent()` consults it first and falls back to the derived teal.
kept!(ACCENT_OVERRIDE, ACCENT_OVERRIDE_HERE, Option<String>, None);

pub fn set_accent_override(hex: Option<String>) {
    ACCENT_OVERRIDE.update(|g| *g = hex.map(normalise_hex_short))
}

pub fn accent_override() -> Option<String> { ACCENT_OVERRIDE.get() }

/// Accept `#rgb` too (shorthand) by expanding it to `#rrggbb`, the form hn parses.
fn normalise_hex_short(hex: String) -> String {
    let h = hex.trim_start_matches('#');
    if h.len() == 3 { format!("#{}{}{}{}{}{}", &h[0..1], &h[0..1], &h[1..2], &h[1..2], &h[2..3], &h[2..3]) } else { hex }
}

#[cfg(test)]
mod accent_override_tests {
    use super::*;
    #[test]
    fn shorthand_accent_is_expanded_and_roundtrips() {
        let _colours = colours_lock();
        set_accent_override(Some("#7aa".into()));
        assert_eq!(normalise_hex_short("#7aa".into()), "#77aaaa");
        assert_eq!(accent_override().as_deref(), Some("#77aaaa"));
        set_accent_override(None);
        assert_eq!(accent_override(), None);
    }
}

/// Record an OSC 10/11 answer. A half left blank keeps the other (a terminal may answer bg only);
/// a missing foreground is chosen for contrast on the background.
pub fn set_terminal_colours(bg: Option<String>, fg: Option<String>) {
    TERMINAL_FG_BG.update(|kept| *kept = updated_terminal_colours(kept.as_ref(), bg, fg));
}

fn updated_terminal_colours(existing: Option<&TerminalColours>, bg: Option<String>, fg: Option<String>) -> Option<TerminalColours> {
    let foreground_reported = fg.is_some() || existing.is_some_and(|c| c.foreground_reported);
    let bg = bg.or_else(|| existing.map(|c| c.bg.clone()))?;
    let fg = fg.or_else(|| existing.filter(|c| c.foreground_reported).map(|c| c.fg.clone()))
        .unwrap_or_else(|| companion_fg(&bg));
    Some(TerminalColours { bg, fg, foreground_reported })
}

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

    #[test]
    fn a_background_change_recomputes_inferred_foreground_only() {
        let dark = updated_terminal_colours(None, Some("#101010".into()), None).unwrap();
        assert_eq!(dark.fg, "#f5f5f5");
        let light = updated_terminal_colours(Some(&dark), Some("#f7f7f7".into()), None).unwrap();
        assert_eq!(light.fg, "#1a1a1a");
        let own = updated_terminal_colours(Some(&light), None, Some("#202020".into())).unwrap();
        let next = updated_terminal_colours(Some(&own), Some("#eeeeee".into()), None).unwrap();
        assert_eq!(next.fg, "#202020");
    }
}

/// Whether the terminal's background is light, from its OSC 11 answer, when it answered.
pub fn terminal_is_light() -> Option<bool> {
    let (bg, _) = terminal_colours()?;
    let (r, g, b) = hex_rgb(&bg)?;
    Some(0.299 * r as f64 + 0.587 * g as f64 + 0.114 * b as f64 > 128.0)
}

/// The terminal's colours from its name and what it says of itself, and what the config says of
/// it: 24-bit with COLORTERM truecolor or 24bit, a `-direct` terminal, an explicit RGB
/// feature/override, or a recognized terminal name. A query still awaiting a reply leaves
/// the TERM entry's colour limit intact. Else 16 for a 16-colour one, 8 for xterm, screen,
/// linux and their kin, none for vt100 and dumb.
pub fn colours_for(term: &str, colorterm: &str, features: &[String], overrides: &[String]) -> u32 {
    let says = |list: &[String], caps: &[&str]| list.iter().any(|f| {
        let mut parts = f.split(':');
        let pat = parts.next().unwrap_or("");
        crate::cmd::fnmatch(pat, term) && parts.any(|c| caps.contains(&c.split('=').next().unwrap_or(c)))
    });
    if matches!(colorterm, "truecolor" | "24bit") || term.ends_with("-direct") || says(features, &["RGB"]) || says(overrides, &["Tc", "RGB"]) { return 1 << 24 }
    // What the terminal said it is, whatever TERM says (an old outer tmux's `screen`, TERM=xterm
    // over ssh from iTerm2): its features, as tmux adds them.
    if modern_terminal() { return 1 << 24 }
    if matches!(term, "xterm-kitty" | "xterm-ghostty" | "alacritty" | "wezterm" | "foot") { return 1 << 24 }
    // A missing or delayed capability reply is not evidence of RGB support.
    if term.contains("256color") { return 256 }
    if term.contains("16color") { return 16 }
    if term.is_empty() { return 256 }
    if matches!(term, "vt100" | "vt102" | "vt220" | "dumb") { return 0 }
    8
}

/// tmux's colour_find_rgb: the nearest of the 256 (the 6x6x6 cube, or the grey ramp).
fn find_rgb(r: u8, g: u8, b: u8) -> u8 {
    const Q2C: [i32; 6] = [0x00, 0x5f, 0x87, 0xaf, 0xd7, 0xff];
    let cube = |v: i32| if v < 48 { 0 } else if v < 114 { 1 } else { (v - 35) / 40 };
    let (r, g, b) = (r as i32, g as i32, b as i32);
    let (qr, qg, qb) = (cube(r), cube(g), cube(b));
    let (cr, cg, cb) = (Q2C[qr as usize], Q2C[qg as usize], Q2C[qb as usize]);
    if cr == r && cg == g && cb == b { return (16 + 36 * qr + 6 * qg + qb) as u8 }
    let avg = (r + g + b) / 3;
    let grey_idx = if avg > 238 { 23 } else { (avg - 3) / 10 };
    let grey = 8 + 10 * grey_idx;
    let dist = |x: i32, y: i32, z: i32| (x - r) * (x - r) + (y - g) * (y - g) + (z - b) * (z - b);
    if dist(grey, grey, grey) < dist(cr, cg, cb) { (232 + grey_idx) as u8 } else { (16 + 36 * qr + 6 * qg + qb) as u8 }
}

/// tmux's colour_256to16.
const TO16: [u8; 256] = [
    0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
    0, 4, 4, 4, 12, 12, 2, 6, 4, 4, 12, 12, 2, 2, 6, 4,
    12, 12, 2, 2, 2, 6, 12, 12, 10, 10, 10, 10, 14, 12, 10, 10,
    10, 10, 10, 14, 1, 5, 4, 4, 12, 12, 3, 8, 4, 4, 12, 12,
    2, 2, 6, 4, 12, 12, 2, 2, 2, 6, 12, 12, 10, 10, 10, 10,
    14, 12, 10, 10, 10, 10, 10, 14, 1, 1, 5, 4, 12, 12, 1, 1,
    5, 4, 12, 12, 3, 3, 8, 4, 12, 12, 2, 2, 2, 6, 12, 12,
    10, 10, 10, 10, 14, 12, 10, 10, 10, 10, 10, 14, 1, 1, 1, 5,
    12, 12, 1, 1, 1, 5, 12, 12, 1, 1, 1, 5, 12, 12, 3, 3,
    3, 7, 12, 12, 10, 10, 10, 10, 14, 12, 10, 10, 10, 10, 10, 14,
    9, 9, 9, 9, 13, 12, 9, 9, 9, 9, 13, 12, 9, 9, 9, 9,
    13, 12, 9, 9, 9, 9, 13, 12, 11, 11, 11, 11, 7, 12, 10, 10,
    10, 10, 10, 14, 9, 9, 9, 9, 9, 13, 9, 9, 9, 9, 9, 13,
    9, 9, 9, 9, 9, 13, 9, 9, 9, 9, 9, 13, 9, 9, 9, 9,
    9, 13, 11, 11, 11, 11, 11, 15, 0, 0, 0, 0, 0, 0, 8, 8,
    8, 8, 8, 8, 7, 7, 7, 7, 7, 7, 15, 15, 15, 15, 15, 15,
];

/// A colour fitted to the terminal, as tty_check_fg / _bg fit it: 24-bit to the nearest of the
/// 256 where there is no 24-bit; 256 to 16 where there are fewer, the bright ones the aixterm
/// ones — or their plain colours where there are only 8; none at all where there is none.
pub fn fit(c: Color) -> Color { fit_bright(c).0 }

/// [fit], and whether a bright colour became a plain one (a foreground is then bold).
fn fit_bright(c: Color) -> (Color, bool) {
    let colours = COLOURS.load(std::sync::atomic::Ordering::Relaxed);
    if colours == 0 { return (Color::Reset, false) }
    let c = match c { Color::Rgb(r, g, b) if colours < (1 << 24) => Color::Indexed(find_rgb(r, g, b)), c => c };
    if colours >= 256 { return (c, false) }
    let plain = [Color::Black, Color::Red, Color::Green, Color::Yellow, Color::Blue, Color::Magenta, Color::Cyan, Color::Gray];
    let bright = [Color::DarkGray, Color::LightRed, Color::LightGreen, Color::LightYellow, Color::LightBlue, Color::LightMagenta, Color::LightCyan, Color::White];
    match c {
        // One of the 256: its nearest of the 16, a bright one plain where there are 8.
        Color::Indexed(n) => {
            let n = TO16[n as usize] as usize;
            (if n < 8 { plain[n] } else if colours >= 16 { bright[n - 8] } else { plain[n - 8] }, false)
        }
        // An aixterm colour (90–97) where there are 8: its plain colour, bright (bold).
        c => match bright.iter().position(|b| *b == c) { Some(n) if colours < 16 => (plain[n], true), _ => (c, false) },
    }
}

/// A colour's SGR parameters as tmux's tty_colours_fg / _bg write them ([base] 30, 40 or 58).
fn sgr(c: Color, base: u16) -> String {
    let named = |n: u16| (n + base).to_string();
    let bright = |n: u16| (n + base + 60).to_string();
    match c {
        Color::Reset => (base + 9).to_string(),
        Color::Black => named(0), Color::Red => named(1), Color::Green => named(2), Color::Yellow => named(3),
        Color::Blue => named(4), Color::Magenta => named(5), Color::Cyan => named(6), Color::Gray => named(7),
        Color::DarkGray => bright(0), Color::LightRed => bright(1), Color::LightGreen => bright(2), Color::LightYellow => bright(3),
        Color::LightBlue => bright(4), Color::LightMagenta => bright(5), Color::LightCyan => bright(6), Color::White => bright(7),
        // setaf's `%p1%{8}%<%t3%p1%d%e%p1%{16}%<%t9%p1%{8}%-%d%e38;5;%p1%d`.
        Color::Indexed(n) if n < 8 && base != 58 => named(n as u16),
        Color::Indexed(n) if n < 16 && base != 58 => bright(n as u16 - 8),
        Color::Indexed(n) => format!("{};5;{n}", base + 8),
        Color::Rgb(r, g, b) => format!("{};2;{r};{g};{b}", base + 8),
    }
}

/// The underline colour: 58;5;N or 58;2;R;G;B (a named one as its index), 59 for none.
fn sgr_underline(c: Color) -> String {
    match c {
        Color::Reset => "59".into(),
        Color::Indexed(n) => format!("58;5;{n}"),
        Color::Rgb(r, g, b) => format!("58;2;{r};{g};{b}"),
        named => {
            let order = [Color::Black, Color::Red, Color::Green, Color::Yellow, Color::Blue, Color::Magenta, Color::Cyan, Color::Gray,
                Color::DarkGray, Color::LightRed, Color::LightGreen, Color::LightYellow, Color::LightBlue, Color::LightMagenta, Color::LightCyan, Color::White];
            format!("58;5;{}", order.iter().position(|o| *o == named).unwrap_or(0))
        }
    }
}

const ATTRS: [(Modifier, u8); 9] = [
    (Modifier::BOLD, 1), (Modifier::DIM, 2), (Modifier::ITALIC, 3), (Modifier::UNDERLINED, 4), (Modifier::SLOW_BLINK, 5),
    (Modifier::RAPID_BLINK, 6), (Modifier::REVERSED, 7), (Modifier::HIDDEN, 8), (Modifier::CROSSED_OUT, 9),
];

impl<W: Write> Backend for TmuxBackend<W> {
    type Error = io::Error;

    fn draw<'a, I>(&mut self, content: I) -> io::Result<()>
    where
        I: Iterator<Item = (u16, u16, &'a Cell)>,
    {
        let mut cells: Vec<(u16, u16, Cell)> = content.map(|(x, y, c)| (x, y, c.clone())).collect();
        let frame = FRAME.lock().ok();
        let frame = frame.as_ref().and_then(|f| f.as_ref());
        let extras = frame.map(|f| f.extras.clone()).unwrap_or_default();
        // Ratatui cannot compare underline styles, links or overline. Redraw those
        // cells even when their text and ordinary attributes have not changed.
        let changed: std::collections::HashSet<(u16, u16)> = self.extra_shadow.keys().chain(extras.keys()).copied()
            .filter(|p| self.extra_shadow.get(p) != extras.get(p)).collect();
        for (x, y) in changed {
            if cells.iter().any(|(cx, cy, _)| *cx == x && *cy == y) { continue }
            if let Some(cell) = self.shadow.get(y as usize).and_then(|row| row.get(x as usize)) { cells.push((x, y, cell.clone())); }
        }
        self.extra_shadow = extras;
        // Nothing changed: nothing written.
        let all = std::mem::take(&mut self.force_whole);
        let rewrite = std::mem::take(&mut self.rewrite);
        self.last_cells = cells.len();
        if cells.is_empty() && !all && rewrite.is_empty() { return Ok(()) }
        // An input method or the terminal itself may have moved the cursor since the last frame:
        // the first cell of a frame that writes is placed by a CUP, never assumed.
        self.cursor_at = None;
        // A row that holds (or held) a cluster the terminal may count otherwise is written again
        // whole from its first column, as fzf writes a line: a cell-by-cell update there would
        // leave a stale character where the two counts part (a Thai vowel beside a keycap).
        let touched: std::collections::BTreeSet<u16> = cells.iter().map(|c| c.1).collect();
        let was: std::collections::HashSet<u16> = touched.iter().copied().filter(|y| self.row_risky(*y)).collect();
        for (x, y, c) in &cells { self.remember(*x, *y, c) }
        let mut whole: std::collections::BTreeSet<u16> = touched.iter().copied().filter(|y| was.contains(y) || self.row_risky(*y)).collect();
        // A soft clear: every row of the screen (the terminal's height; else the rows known). A
        // settle rewrite: the rows touched since the last one.
        if all {
            let rows = self.screen_size().map(|s| s.height as usize).unwrap_or(self.shadow.len()).max(self.shadow.len());
            whole.extend((0..rows).map(|y| y as u16));
        }
        whole.extend(rewrite);
        // The rows written cell by cell are the next settle rewrite's.
        self.touched.extend(touched.into_iter().filter(|y| !whole.contains(y)));
        // A single-cell update fits in the writer's one buffered flush; synchronizing it
        // adds sixteen bytes to an ordinary one-byte echo without hiding any redraw.
        if cells.len() > 1 || !whole.is_empty() { self.begin_sync()? }
        let (usstyle, links) = frame.map(|f| (f.usstyle, f.links)).unwrap_or((false, false));
        let extra_at = |x: u16, y: u16| frame.and_then(|f| f.extras.get(&(x, y)));
        let cols = if whole.is_empty() { None } else { self.screen_size().map(|s| s.width as usize) };
        // CrosstermBackend writes through to its writer.
        let w = &mut self.inner;
        let mut pen = Pen::new();
        for (x, y, cell) in cells.iter().filter(|c| !whole.contains(&c.1)) {
            // Printing advances the cursor. Keep that position across frames as well: an
            // ordinary echoed key needs neither a CUP before it nor one after it.
            if self.cursor_at != Some(Position::new(*x, *y)) { write!(w, "\x1b[{};{}H", y + 1, x + 1)?; }
            pen.put(w, cell, extra_at(*x, *y), usstyle, links)?;
            let width = unicode_width::UnicodeWidthStr::width(cell.symbol()).max(1) as u16;
            self.cursor_at = Some(Position::new(x.saturating_add(width), *y));
        }
        // A row written whole: its text from the first column, then the rest of the row erased —
        // never erased first, which a terminal without ?2026 would show blank for a moment.
        let blank = Cell::default();
        let width = |c: &Cell| unicode_width::UnicodeWidthStr::width(c.symbol()).max(1);
        for y in whole {
            // A row of a soft clear with nothing on it is still erased: a stale cell may be there.
            let row = match self.shadow.get(y as usize) { Some(row) => row.as_slice(), None if all => &[], None => continue };
            // (Blank cells at its end are the erase's.)
            let end = row.iter().enumerate().rev().find(|(x, c)| **c != blank || extra_at(*x as u16, y).is_some())
                .map_or(0, |(x, c)| x + width(c));
            write!(w, "\x1b[{};1H", y + 1)?;
            let (mut skip, mut placed) = (0usize, true);
            for (x, cell) in row[..end].iter().enumerate() {
                if skip > 0 { skip -= 1; continue }
                // After a cluster the terminal may have counted otherwise, the next cell goes
                // where hn counts it.
                if !placed { write!(w, "\x1b[{};{}H", y + 1, x + 1)?; }
                pen.put(w, cell, extra_at(x as u16, y), usstyle, links)?;
                skip = width(cell) - 1;
                placed = !risky(cell.symbol());
            }
            // A row that reaches the last column needs no erase (and the cursor waiting there
            // would take that column's cell with it).
            if cols.is_none_or(|c| end < c) {
                if !placed { write!(w, "\x1b[{};{}H", y + 1, end + 1)?; placed = true }
                pen.reset(w)?;
                w.write_all(b"\x1b[K")?;
            }
            self.cursor_at = placed.then(|| Position::new(end as u16, y));
        }
        // SGR 0 restores all three colours and attributes in one command; when they
        // are already default, a plain-text echo has nothing to restore.
        pen.reset(w)
    }

    fn hide_cursor(&mut self) -> io::Result<()> { if self.cursor_shown == Some(false) { return Ok(()) } self.cursor_shown = Some(false); self.inner.hide_cursor() }
    fn show_cursor(&mut self) -> io::Result<()> { if self.cursor_shown == Some(true) { return Ok(()) } self.cursor_shown = Some(true); self.inner.show_cursor() }
    // (Never asked of the terminal — \e[6n and a wait for its answer: hn draws the whole screen,
    // and a terminal slow to answer, or one that never does, must not stop it starting.)
    fn get_cursor_position(&mut self) -> io::Result<Position> { Ok(Position::ORIGIN) }
    fn set_cursor_position<P: Into<Position>>(&mut self, position: P) -> io::Result<()> {
        let p = position.into();
        if self.cursor_at == Some(p) { return Ok(()) }
        self.cursor_at = Some(p);
        self.inner.set_cursor_position(p)
    }
    fn clear(&mut self) -> io::Result<()> { self.shadow.clear(); self.extra_shadow.clear(); self.touched.clear(); self.rewrite.clear(); self.cursor_at = None; self.cursor_shown = None; self.inner.clear() }
    fn clear_region(&mut self, clear_type: ClearType) -> io::Result<()> {
        if matches!(clear_type, ClearType::All) {
            // Hard or soft, the draw that follows is the same update; `flush` closes it.
            self.begin_sync()?;
            self.shadow.clear();
            self.extra_shadow.clear();
            // Every row is written again: no settle rewrite is owed for what came before.
            self.touched.clear();
            self.rewrite.clear();
            // A soft clear forgets what was written but erases nothing: the draw that follows writes
            // every row, each its text and then the rest erased, so the screen is never seen blank.
            if std::mem::take(&mut self.soft) { self.cursor_at = None; self.force_whole = true; return Ok(()) }
        }
        self.inner.clear_region(clear_type)
    }
    fn append_lines(&mut self, n: u16) -> io::Result<()> { self.cursor_at = None; self.inner.append_lines(n) }
    fn size(&self) -> io::Result<Size> { self.inner.size() }
    fn window_size(&mut self) -> io::Result<WindowSize> { self.inner.window_size() }
    fn flush(&mut self) -> io::Result<()> {
        if std::mem::take(&mut self.syncing) { self.inner.write_all(b"\x1b[?2026l")? }
        Backend::flush(&mut self.inner)
    }
}

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

    #[test]
    fn a_control_character_in_a_cell_is_never_sent_to_the_terminal() {
        // A tab written as a cell moves the terminal's cursor to its next tab stop: every cell after
        // it on the row, written without a cursor move, then lands to the right of where hn put it.
        use alacritty_terminal::index::{Column, Line};
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        let (mut a, mut tab, mut b) = (Cell::default(), Cell::default(), Cell::default());
        a.set_char('a'); tab.set_symbol("\t"); b.set_char('b');
        backend.draw([(0u16, 0u16, &a), (1, 0, &tab), (2, 0, &b)].into_iter()).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        assert!(!written.contains(&b'\t'), "{:?}", String::from_utf8_lossy(&written));
        let mut pane = crate::pane::Pane::new(1, "m", "a", 20, 2);
        pane.feed(&written);
        assert_eq!(pane.term.grid()[Line(0)][Column(2)].c, 'b', "b lands where hn drew it");
    }

    #[test]
    fn a_frame_knows_how_many_cells_it_wrote() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        let mut c = Cell::default();
        c.set_char('a');
        backend.draw([(0u16, 0u16, &c), (1, 0, &c), (2, 0, &c)].into_iter()).unwrap();
        Backend::flush(&mut backend).unwrap();
        assert_eq!(backend.last_cells(), 3);
        backend.draw(std::iter::empty()).unwrap();
        assert_eq!(backend.last_cells(), 0, "a frame with no change wrote none");
    }

    #[test]
    fn a_repaint_is_soft_unless_the_size_changed() {
        assert!(repaint_is_soft(Size::new(80, 24), Size::new(80, 24)));
        assert!(!repaint_is_soft(Size::new(80, 24), Size::new(100, 24)));
        assert!(!repaint_is_soft(Size::new(80, 24), Size::new(80, 20)));
    }

    #[test]
    fn a_soft_clear_writes_each_row_once_inside_one_update_and_never_erases_first() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        backend.size_known = Some(Size::new(10, 3));
        let mut cells = Vec::new();
        for y in 0..3u16 { let mut c = Cell::default(); c.set_char('x'); cells.push((0u16, y, c)) }
        backend.draw(cells.iter().map(|(x, y, c)| (*x, *y, c))).unwrap();
        Backend::flush(&mut backend).unwrap();
        backend.soft_clear_next();
        Backend::clear_region(&mut backend, ClearType::All).unwrap();
        backend.draw(cells.iter().map(|(x, y, c)| (*x, *y, c))).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        assert!(!s.contains("\x1b[2J") && !s.contains("\x1b[2K"), "{s:?}");
        // Each row's text, then the rest of the row erased: never a blank row mid-write.
        for y in 1..=3 { assert_eq!(s.matches(&format!("\x1b[{y};1Hx\x1b[K")).count(), 1, "row {y}: {s:?}") }
        assert_eq!(s.matches("\x1b[?2026h").count(), 2, "one update per frame: {s:?}");
        assert_eq!(s.matches("\x1b[?2026l").count(), 2, "{s:?}");
        // The soft frame's update opens before its first row is written.
        let after_first = &s[s.find("\x1b[?2026l").unwrap()..];
        assert!(after_first.find("\x1b[?2026h").unwrap() < after_first.find("\x1b[1;1Hx").unwrap(), "{s:?}");
    }

    /// Cells for [text] from column 0 of row [y], each at the column its width puts it.
    fn text_at(backend: &mut TmuxBackend<&mut Vec<u8>>, y: u16, text: &str) {
        use unicode_segmentation::UnicodeSegmentation;
        let mut cells = Vec::new();
        let mut x = 0u16;
        for g in text.graphemes(true) {
            let mut c = Cell::default();
            c.set_symbol(g);
            cells.push((x, y, c));
            x += unicode_width::UnicodeWidthStr::width(g).max(1) as u16;
        }
        backend.draw(cells.iter().map(|(x, y, c)| (*x, *y, c))).unwrap();
        Backend::flush(backend).unwrap();
    }

    #[test]
    fn a_whole_row_writes_its_text_and_then_erases_the_rest() {
        use alacritty_terminal::index::{Column, Line};
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        backend.size_known = Some(Size::new(20, 2));
        text_at(&mut backend, 0, "abcdefgh");
        backend.soft_clear_next();
        Backend::clear_region(&mut backend, ClearType::All).unwrap();
        text_at(&mut backend, 0, "ab");
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        assert!(!s.contains("\x1b[2K"), "{s:?}");
        assert!(s.contains("\x1b[1;1Hab\x1b[K"), "the text first, then the rest of the row: {s:?}");
        assert!(s.contains("\x1b[2;1H\x1b[K"), "an empty row is still erased: {s:?}");
        let mut pane = crate::pane::Pane::new(1, "m", "a", 20, 2);
        pane.feed(&written);
        let row: String = (0..8).map(|x| pane.term.grid()[Line(0)][Column(x)].c).collect();
        assert_eq!(row, "ab      ", "no cell of the longer row survives");
    }

    #[test]
    fn a_whole_row_that_reaches_the_right_edge_is_not_erased_after_it() {
        // The cursor waits on the last column after printing there: an erase then takes that cell.
        use alacritty_terminal::index::{Column, Line};
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        backend.size_known = Some(Size::new(4, 1));
        backend.soft_clear_next();
        Backend::clear_region(&mut backend, ClearType::All).unwrap();
        text_at(&mut backend, 0, "abcd");
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        assert!(!s.contains("\x1b[K") && !s.contains("\x1b[2K"), "{s:?}");
        let mut pane = crate::pane::Pane::new(1, "m", "a", 4, 1);
        pane.feed(&written);
        assert_eq!(pane.term.grid()[Line(0)][Column(3)].c, 'd', "{s:?}");
    }

    #[test]
    fn a_risky_row_is_written_whole_text_first_and_placed_after_each_risky_symbol() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        backend.size_known = Some(Size::new(20, 2));
        text_at(&mut backend, 0, "go⚡ now");
        text_at(&mut backend, 1, "ab⚡");
        // One cell changes on each row: both rows hold a risky symbol, so both are written whole.
        let mut x = Cell::default();
        x.set_char('x');
        backend.draw([(5u16, 0u16, &x), (0, 1, &x)].into_iter()).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        let last = &s[s.rfind("\x1b[?2026h").unwrap()..];
        assert!(!last.contains("\x1b[2K"), "{last:?}");
        assert!(last.contains("\x1b[1;1Hgo⚡\x1b[1;5H xow\x1b[K"), "the cell after ⚡ placed by hn, the erase after the text: {last:?}");
        // A row that ends on a risky symbol: the erase starts where hn counts the row's end.
        assert!(last.contains("\x1b[2;1Hxb⚡\x1b[2;5H\x1b[K"), "{last:?}");
    }

    #[test]
    fn a_settle_rewrite_writes_only_the_rows_touched_since_the_last_one() {
        use alacritty_terminal::index::{Column, Line};
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        backend.size_known = Some(Size::new(10, 4));
        text_at(&mut backend, 0, "ab");
        text_at(&mut backend, 2, "cd");
        backend.settle_next();
        backend.draw(std::iter::empty()).unwrap();
        Backend::flush(&mut backend).unwrap();
        // Nothing touched since: the next one writes nothing (an idle hn stays silent).
        backend.settle_next();
        backend.draw(std::iter::empty()).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        let settle = &s[s.rfind("\x1b[?2026h").unwrap()..];
        assert_eq!(settle, "\x1b[?2026h\x1b[1;1Hab\x1b[K\x1b[3;1Hcd\x1b[K\x1b[?2026l", "rows 1 and 3, not the screen: {s:?}");
        // A cell the terminal kept wrongly on a touched row is gone after it.
        let mut pane = crate::pane::Pane::new(1, "m", "a", 10, 4);
        pane.feed(b"\x1b[1;6HX");
        pane.feed(&written);
        assert_eq!(pane.term.grid()[Line(0)][Column(5)].c, ' ');
    }

    #[test]
    fn a_settle_rewrite_takes_the_rows_an_overlay_left_and_none_a_repaint_wrote() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        backend.size_known = Some(Size::new(10, 4));
        for y in 0..3 { text_at(&mut backend, y, "xy") }
        backend.settle_next();
        backend.draw(std::iter::empty()).unwrap();
        Backend::flush(&mut backend).unwrap();
        // One row changes, and an overlay that covered row 2 is gone.
        text_at(&mut backend, 0, "ab");
        backend.owe_rows(1..2);
        backend.settle_next();
        backend.draw(std::iter::empty()).unwrap();
        Backend::flush(&mut backend).unwrap();
        // A row changes, then a repaint writes every row: nothing is owed after it.
        text_at(&mut backend, 2, "cd");
        backend.soft_clear_next();
        Backend::clear_region(&mut backend, ClearType::All).unwrap();
        let (mut a, mut b) = (Cell::default(), Cell::default());
        a.set_char('a'); b.set_char('b');
        backend.draw([(0u16, 0u16, &a), (1, 0, &b)].into_iter()).unwrap();
        Backend::flush(&mut backend).unwrap();
        backend.settle_next();
        backend.draw(std::iter::empty()).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        let frames: Vec<&str> = s.split("\x1b[?2026h").collect();
        let second = frames.iter().find(|f| f.starts_with("\x1b[1;1Hab\x1b[K")).unwrap_or_else(|| panic!("{s:?}"));
        assert!(second.starts_with("\x1b[1;1Hab\x1b[K\x1b[2;1Hxy\x1b[K\x1b[?2026l"), "the changed row and the overlay's, not row 3: {s:?}");
        assert!(frames.last().unwrap().contains("\x1b[4;1H\x1b[K"), "the repaint is the last frame written: {s:?}");
    }

    #[test]
    fn a_soft_clear_writes_every_row_over_the_screen_without_erasing_it() {
        use alacritty_terminal::index::{Column, Line};
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        let (mut a, mut b) = (Cell::default(), Cell::default());
        a.set_char('a'); b.set_char('b');
        backend.draw([(0u16, 0u16, &a), (1, 0, &b)].into_iter()).unwrap();
        Backend::flush(&mut backend).unwrap();
        // The next frame is the same (so a normal draw would write nothing), but a cell the terminal
        // holds wrongly — a ghost — is the reason to write the screen again, and with no blank flash.
        backend.soft_clear_next();
        Backend::clear_region(&mut backend, ClearType::All).unwrap();
        backend.draw([(0u16, 0u16, &a), (1, 0, &b)].into_iter()).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let mut pane = crate::pane::Pane::new(1, "m", "a", 20, 4);
        // The terminal before the repaint: the first frame, and a stale X the backend never wrote.
        let first_len = written.iter().position(|&c| c == b'a').unwrap_or(0);
        let _ = first_len;
        pane.feed(b"\x1b[1;6HX\x1b[1;1H");
        pane.feed(&written);
        let text = String::from_utf8_lossy(&written);
        assert!(!text.contains("\x1b[2J"), "a soft clear must not erase the screen: {text:?}");
        assert_eq!(pane.term.grid()[Line(0)][Column(0)].c, 'a');
        assert_eq!(pane.term.grid()[Line(0)][Column(5)].c, ' ', "the stale cell was erased by its row being written again");
    }

    fn two_cells(backend: &mut TmuxBackend<&mut Vec<u8>>) {
        let (mut a, mut b) = (Cell::default(), Cell::default());
        a.set_char('a'); b.set_char('b');
        backend.draw([(0u16, 0u16, &a), (1, 0, &b)].into_iter()).unwrap();
    }

    #[test]
    fn a_hard_clear_is_inside_the_frames_synchronized_update() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        two_cells(&mut backend);
        Backend::flush(&mut backend).unwrap();
        // What `Terminal::clear` asks of the backend, then the frame that follows it.
        Backend::clear_region(&mut backend, ClearType::All).unwrap();
        two_cells(&mut backend);
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        let clear = s.find("\x1b[2J").expect("a hard clear");
        let open = s[..clear].rfind("\x1b[?2026h").expect("opened before the clear");
        assert!(s[..clear].rfind("\x1b[?2026l").map_or(true, |close| close < open), "no close between open and clear: {s:?}");
        assert!(s[clear..].contains("\x1b[?2026l"), "closed after the redraw: {s:?}");
        assert_eq!(s.matches("\x1b[?2026h").count(), s.matches("\x1b[?2026l").count(), "balanced: {s:?}");
        assert_eq!(s[clear..].matches("\x1b[?2026h").count(), 0, "the frame joins the clear's update, it does not open another: {s:?}");
    }

    #[test]
    fn a_hard_clear_without_synchronized_output_writes_no_2026() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        backend.sync_ok = false;
        Backend::clear_region(&mut backend, ClearType::All).unwrap();
        two_cells(&mut backend);
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        assert!(s.contains("\x1b[2J") && !s.contains("2026"), "{s:?}");
    }

    #[test]
    fn synchronized_output_is_on_unless_turned_off() {
        assert!(sync_wanted(""));
        assert!(sync_wanted("on"));
        assert!(!sync_wanted("off"));
        assert!(!sync_wanted("OFF"));
    }

    #[test]
    fn a_frame_is_not_wrapped_in_2026_when_it_is_left_out() {
        let draw = |sync_ok: bool| {
            let mut written = Vec::new();
            let mut backend = TmuxBackend::with_sync(&mut written);
            backend.sync_ok = sync_ok;
            let (mut a, mut b) = (Cell::default(), Cell::default());
            a.set_char('a'); b.set_char('b');
            backend.draw([(0u16, 0u16, &a), (1, 0, &b)].into_iter()).unwrap();
            Backend::flush(&mut backend).unwrap();
            drop(backend);
            String::from_utf8_lossy(&written).to_string()
        };
        assert!(draw(true).contains("\x1b[?2026h") && draw(true).contains("\x1b[?2026l"));
        assert!(!draw(false).contains("2026"));
    }

    #[test]
    fn single_symbols_terminals_count_otherwise_are_risky_too() {
        // Private-use icons (Nerd Font), arrows/shapes/dingbats of ambiguous width, and emoji
        // written as one code point: terminals disagree on their width as they do on clusters.
        for s in ["\u{e0a0}", "\u{f07b}", "\u{26a1}", "\u{2713}", "\u{25cf}", "\u{25b6}", "\u{1f44d}"] {
            assert!(risky(s), "{s:?} should be written with its row");
        }
        // Text, the box-drawing and block characters of every border, and wide CJK are counted alike everywhere.
        for s in ["a", "é", "中", "─", "│", "█", "▀"] {
            assert!(!risky(s), "{s:?} should stay a cell-by-cell update");
        }
    }

    #[test]
    fn plain_echo_keeps_the_printed_cursor_and_needs_few_bytes() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::new(&mut written);
        backend.set_cursor_position(Position::new(2, 1)).unwrap();
        let mut cell = Cell::default();
        cell.set_char('x');
        backend.draw(std::iter::once((2, 1, &cell))).unwrap();
        backend.set_cursor_position(Position::new(3, 1)).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let bytes = written.as_slice();
        assert!(bytes.len() <= 13, "one echoed key wrote {} bytes: its initial cursor, the frame's own CUP and the char", bytes.len());
        let mut pane = crate::pane::Pane::new(1, "m", "a", 20, 4);
        pane.feed(bytes);
        use alacritty_terminal::index::{Column, Line, Point};
        assert_eq!(pane.term.grid()[Line(1)][Column(2)].c, 'x');
        assert_eq!(pane.term.grid().cursor.point, Point::new(Line(1), Column(3)));
    }

    #[test]
    fn each_frame_places_the_cursor_itself() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::with_sync(&mut written);
        let (mut a, mut b, mut c) = (Cell::default(), Cell::default(), Cell::default());
        a.set_char('a'); b.set_char('b'); c.set_char('c');
        backend.draw([(0u16, 0u16, &a), (1, 0, &b)].into_iter()).unwrap();
        Backend::flush(&mut backend).unwrap();
        // The next frame changes only the cell right after the cursor hn left (column 2).
        backend.draw(std::iter::once((2u16, 0u16, &c))).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let s = String::from_utf8_lossy(&written);
        assert!(s.contains("\x1b[1;3H"), "the second frame moved the cursor first: {s:?}");
    }

    #[test]
    fn an_idle_frame_writes_nothing_after_a_frame_with_cells() {
        // As ratatui calls the backend for a frame: draw, place the cursor, flush. A frame with
        // nothing changed writes nothing, not even a cursor move.
        let mut a = Cell::default();
        a.set_char('a');
        let at = Position::new(1, 0);
        let (mut one, mut two) = (Vec::new(), Vec::new());
        let mut backend = TmuxBackend::with_sync(&mut one);
        backend.draw(std::iter::once((0u16, 0u16, &a))).unwrap();
        backend.set_cursor_position(at).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        let mut backend = TmuxBackend::with_sync(&mut two);
        backend.draw(std::iter::once((0u16, 0u16, &a))).unwrap();
        backend.set_cursor_position(at).unwrap();
        Backend::flush(&mut backend).unwrap();
        backend.draw(std::iter::empty()).unwrap();
        backend.set_cursor_position(at).unwrap();
        Backend::flush(&mut backend).unwrap();
        drop(backend);
        assert_eq!(String::from_utf8_lossy(&one), String::from_utf8_lossy(&two));
    }

    #[test]
    fn styled_frame_restores_colours_before_plain_echo() {
        let mut written = Vec::new();
        let mut backend = TmuxBackend::new(&mut written);
        let mut coloured = Cell::default();
        coloured.set_char('a').set_fg(Color::Red).set_bg(Color::Blue);
        backend.draw(std::iter::once((0, 0, &coloured))).unwrap();
        Backend::flush(&mut backend).unwrap();
        let mut plain = Cell::default();
        plain.set_char('b');
        backend.draw(std::iter::once((1, 0, &plain))).unwrap();
        Backend::flush(&mut backend).unwrap();
        let mut pane = crate::pane::Pane::new(1, "m", "a", 20, 4);
        drop(backend);
        pane.feed(&written);
        use alacritty_terminal::index::{Column, Line};
        use alacritty_terminal::vte::ansi::{Color as AnsiColor, NamedColor};
        let grid = pane.term.grid();
        assert_eq!(grid[Line(0)][Column(0)].fg, AnsiColor::Named(NamedColor::Red));
        assert_eq!(grid[Line(0)][Column(1)].fg, AnsiColor::Named(NamedColor::Foreground));
        assert_eq!(grid[Line(0)][Column(1)].bg, AnsiColor::Named(NamedColor::Background));
    }

    #[test]
    fn pane_attributes_are_written_and_reset_independently() {
        let mut written = Vec::new();
        let mut pen = Pen::new();
        let mut cell = Cell::default();
        cell.set_char('X').set_style(ratatui::style::Style::default().add_modifier(Modifier::UNDERLINED | Modifier::SLOW_BLINK));
        pen.put(&mut written, &cell, Some(&Extra { underline: 2, overline: true, link: None }), true, false).unwrap();
        // Removing only overline must not disturb blink or double underline.
        cell.set_char('Y');
        pen.put(&mut written, &cell, Some(&Extra { underline: 2, ..Default::default() }), true, false).unwrap();
        pen.reset(&mut written).unwrap();
        written.push(b'Z');
        let mut pane = crate::pane::Pane::new(1, "local", "rendered", 20, 4);
        pane.feed(&written);
        use alacritty_terminal::{index::{Column, Line}, term::cell::Flags};
        assert!(pane.term.grid()[Line(0)][Column(0)].flags.contains(Flags::DOUBLE_UNDERLINE | Flags::BLINK | Flags::OVERLINE));
        assert!(pane.term.grid()[Line(0)][Column(1)].flags.contains(Flags::DOUBLE_UNDERLINE | Flags::BLINK));
        assert!(!pane.term.grid()[Line(0)][Column(1)].flags.contains(Flags::OVERLINE));
        assert_eq!(pane.term.grid()[Line(0)][Column(2)].flags, Flags::empty());
    }

    #[test]
    fn colours_as_tmux_writes_them() {
        assert_eq!(super::find_rgb(255, 128, 0), 208);
        assert_eq!(super::find_rgb(0, 64, 128), 24);
        assert_eq!(super::TO16[208], 9);
        assert_eq!(super::colours_for("xterm-16color", "", &[], &[]), 16);
        assert_eq!(super::colours_for("xterm-256color", "", &[], &[]), 256);
        assert_eq!(super::colours_for("screen-256color", "", &[], &[]), 256);
        assert_eq!(super::colours_for("xterm-256color", "truecolor", &[], &[]), 1 << 24);
        assert_eq!(super::colours_for("xterm-256color", "", &["xterm*:RGB".to_string()], &[]), 1 << 24);
        assert_eq!(super::colours_for("xterm", "", &[], &[]), 8);
        assert_eq!(super::colours_for("vt100", "", &[], &[]), 0);
        assert_eq!(sgr(Color::Red, 30), "31");
        assert_eq!(sgr(Color::Green, 40), "42");
        assert_eq!(sgr(Color::LightBlue, 30), "94");
        assert_eq!(sgr(Color::White, 40), "107");
        assert_eq!(sgr(Color::Reset, 40), "49");
        // The first sixteen of the 256 as terminfo's setaf/setab write them (\e[38;5;1m → 31).
        assert_eq!(sgr(Color::Indexed(1), 30), "31");
        assert_eq!(sgr(Color::Indexed(9), 30), "91");
        assert_eq!(sgr(Color::Indexed(4), 40), "44");
        assert_eq!(sgr(Color::Indexed(12), 40), "104");
        assert_eq!(sgr(Color::Indexed(16), 30), "38;5;16");
        assert_eq!(sgr(Color::Rgb(1, 2, 3), 40), "48;2;1;2;3");
    }
}