retroglyph_terminal/

lib.rs

//! ANSI/SGR cell-diff renderer shared by retroglyph's terminal-family backends.
//!
//! [`TerminalRenderer`] converts [`Tile`] content into standard ANSI/CSI escape sequences (cursor
//! movement, `SetForegroundColor`/`SetBackgroundColor`/SGR attributes, synchronized update markers)
//! and writes them to any [`std::io::Write`] sink. It has no opinion about where those bytes end up
//! or how input arrives; two crates plug it into a concrete environment:
//!
//! ```text
//!                     +-----------------------+
//!                     |     TerminalRenderer   |
//!                     |  (this crate: Tile ->  |
//!                     |   ANSI/SGR escape      |
//!                     |   sequences)           |
//!                     +-----------------------+
//!                        ^                 ^
//!                        |                 |
//!            std::io::Write          std::io::Write
//!               (String buffer)         (stdout)
//!                        |                 |
//!  +-----------------------------+   +-----------------------------+
//!  | retroglyph-terminal-wasm    |   | retroglyph-crossterm        |
//!  | pushed JS key/resize events |   | raw mode, alternate screen, |
//!  | -> String pulled by JS each |   | kitty keyboard protocol,    |
//!  | frame (xterm.js renders it) |   | crossterm::event polling    |
//!  +-----------------------------+   +-----------------------------+
//! ```
//!
//! - [`retroglyph-crossterm`](https://docs.rs/retroglyph-crossterm) drives a real TTY: raw mode,
//!   alternate screen, the kitty keyboard protocol, and `crossterm::event` polling. It writes this
//!   renderer's output straight to `stdout`.
//! - [`retroglyph-terminal-wasm`](https://docs.rs/retroglyph-terminal-wasm) drives a browser
//!   terminal emulator (e.g. xterm.js) from WASM: no TTY, no polling, output collected into a
//!   `String` for JS to pull each frame, input pushed in from JS callbacks.
//!
//! # Features
//!
//! <!-- gen-features:start -->
//! This crate has no default features; every feature below is optional and off unless enabled.
//!
//! ### `dev`
//!
//! ⚪ Optional.
//!
//! Forwards `retroglyph-core`'s `dev` feature, which forces development diagnostics on in a build
//! that would otherwise compile them out (see [`retroglyph_core::dev`]).
//!
//! ### `egc`
//!
//! ⚪ Optional.
//!
//! Forwards to `retroglyph-core`'s `egc` feature.
//!
//! This crate has EGC-aware and non-EGC-aware code paths gated on the same flag name.
//! <!-- gen-features:end -->
//!
//! # Why not part of `retroglyph-window`
//!
//! `retroglyph-window` splits input (winit event loop) from output (`Presenter`) because every
//! windowed backend shares one runtime driver: the winit event loop. That split lets renderer
//! crates avoid depending on winit's frequent major-version bumps.
//!
//! Crossterm and the wasm/xterm.js driver share no such runtime: crossterm owns a blocking poll
//! loop against a real TTY, and the wasm driver is pushed into by JS with no polling loop at all.
//! What they do share is the ANSI/SGR cell-diff renderer, so that is what lives in this crate.
//!
//! # `no_std`
//!
//! This crate always requires `std` (an `impl std::io::Write` sink), unlike `retroglyph-core`,
//! which supports `no_std`.
//!
//! # RGB color fallback on 256-color terminals
//!
//! By default ([`ColorSupport::Truecolor`]), [`Color::Rgb`] tiles are written out verbatim as a
//! 24-bit truecolor SGR sequence (`38;2;r;g;b` / `48;2;r;g;b`, one of the codes this crate's
//! internal SGR-color writer emits), with no quantization. This mirrors `crossterm`'s own
//! `SetForegroundColor`/`SetBackgroundColor` behavior (and that of most Rust terminal-UI crates):
//! truecolor codes are written unconditionally, and it is left to the terminal emulator (or a
//! multiplexer like `tmux`/`screen` sitting in between) to interpret or degrade them. In practice:
//!
//! - Terminals that advertise truecolor support (`$COLORTERM=truecolor` or `24bit`) render the
//!   exact color.
//! - Many terminals and multiplexers that only support the 256-color palette (`$TERM=*-256color`)
//!   approximate the requested RGB to the nearest palette entry themselves, since terminal
//!   implementations commonly downsample unrecognized-depth SGR sequences rather than drop them.
//! - A minority of older/limited terminals may render truecolor sequences incorrectly (wrong color,
//!   or no color at all) if they don't recognize the extended `;2;` SGR form.
//!
//! Callers that know the receiving terminal is more limited (or that `$NO_COLOR` is set) can set
//! [`TerminalRenderer::with_color_support`]/[`TerminalRenderer::set_color_support`] to
//! [`ColorSupport::Indexed256`], [`ColorSupport::Ansi16`], or [`ColorSupport::None`] instead:
//! [`draw`](TerminalRenderer::draw) then quantizes every [`Color::Rgb`] tile through
//! [`Color::to_indexed`]/[`Color::to_ansi`] (or forces [`Color::Default`]) before writing its SGR
//! sequence, so the emitted bytes match what was actually requested rather than relying on the
//! terminal to downsample. This crate does not auto-detect terminal capabilities itself (that
//! belongs to a backend that actually has access to `$TERM`/`$NO_COLOR`, e.g.
//! `retroglyph-crossterm`'s `CrosstermOptions`); [`ColorSupport::Truecolor`] remains the default.
//!
//! Callers that need a specific, correct color regardless of `ColorSupport` should use
//! [`Color::Indexed`] or [`Color::Ansi`] explicitly instead of [`Color::Rgb`]; both are passed
//! through untranslated (`38;5;n` / plain ANSI codes) at every `ColorSupport` level except
//! [`ColorSupport::None`] (which forces [`Color::Default`] regardless of the requested color) and
//! have no ambiguity across terminal color depths.

#![cfg_attr(docsrs, feature(doc_cfg))]

// Compile the code blocks in this crate's own README as doctests so its quick start is
// type-checked on every test run and cannot silently rot. The `cfg(doctest)` gate keeps this out
// of the rendered crate documentation: see `retroglyph-crossterm`'s matching include for the
// same pattern applied to the workspace root README.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeDoctests;

use retroglyph_core::backend::CursorStyle;
use retroglyph_core::backend::DrawCell;
use retroglyph_core::color::Color;
use retroglyph_core::grid::Pos;
use retroglyph_core::tile::Tile;
use std::io::{self, Write};

/// How aggressively [`TerminalRenderer`] quantizes [`Color`] before emitting an SGR sequence.
///
/// See the crate-level "RGB color fallback on 256-color terminals" doc section for the full
/// contract, and [`TerminalRenderer::with_color_support`]/[`TerminalRenderer::set_color_support`]
/// to configure it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum ColorSupport {
    /// No quantization: [`Color::Rgb`] tiles are written out verbatim as a 24-bit truecolor SGR
    /// sequence. The default, matching this renderer's historical behavior.
    #[default]
    Truecolor,
    /// [`Color::Rgb`] tiles are quantized to the nearest of the 256 indexed-color palette entries
    /// via [`Color::to_indexed`] before being written.
    Indexed256,
    /// [`Color::Rgb`] tiles are quantized to the nearest of the 16 standard ANSI colors via
    /// [`Color::to_ansi`] before being written.
    Ansi16,
    /// Every [`Color`] is forced to [`Color::Default`]: no SGR color codes are emitted at all.
    None,
}

impl ColorSupport {
    /// Applies this degradation level to `color`, returning the [`Color`] that should actually be
    /// written as an SGR sequence.
    fn apply(self, color: Color) -> Color {
        match self {
            Self::Truecolor => color,
            Self::Indexed256 => color.to_indexed(),
            Self::Ansi16 => color.to_ansi(),
            // `ColorSupport` is `#[non_exhaustive]`: an unrecognized future level degrades to
            // the most conservative, always-safe choice (no color at all) rather than failing to
            // compile or accidentally passing a color through unquantized.
            _ => Color::Default,
        }
    }
}

/// Writes a [`Color`]'s SGR parameter list (no `\x1b[`/`m` wrapper) for `SetForegroundColor`
/// (`38;...`) or `SetBackgroundColor` (`48;...`) to `out`.
///
/// `base` is `38` for foreground, `48` for background (the standard SGR prefix codes); `reset`
/// is `39`/`49`, used for [`Color::Default`]. This is the shared parameter-building block behind
/// both [`write_sgr_color`] (a single complete escape sequence) and the combined-fg/bg path in
/// [`TerminalRenderer::draw`], which concatenates two calls' output with `;` into one sequence.
fn write_sgr_params<W: Write>(out: &mut W, color: Color, base: u8, reset: u8) -> io::Result<()> {
    match color {
        Color::Ansi(ansi) => {
            // Standard/bright ANSI codes are offsets from the SGR base:
            // foreground 30-37/90-97, background 40-47/100-107. `base` here
            // is 38/48 (the "extended color" introducer), so the plain ANSI
            // path uses its own literal base instead.
            let (plain_base, bright_base) = if base == 38 { (30, 90) } else { (40, 100) };
            let index = ansi.to_index();
            let code = if index < 8 {
                plain_base + index
            } else {
                bright_base + (index - 8)
            };
            write!(out, "{code}")
        }
        Color::Indexed(index) => write!(out, "{base};5;{index}"),
        // No quantization: passed straight through as a 24-bit truecolor SGR
        // sequence. See the crate-level "RGB color fallback on 256-color
        // terminals" doc section for the contract this leaves callers with.
        Color::Rgb { r, g, b } => write!(out, "{base};2;{r};{g};{b}"),
        // Covers `Color::Default` plus any future variant (`Color` is `#[non_exhaustive]`) this
        // crate doesn't know how to resolve yet; both fall back to the reset code.
        _ => write!(out, "{reset}"),
    }
}

/// Converts a [`Color`] to a standard ANSI/CSI `SetForegroundColor` (`38;...`) or
/// `SetBackgroundColor` (`48;...`) escape sequence, written to `out`.
///
/// `base` is `38` for foreground, `48` for background (the standard SGR prefix codes); `reset` is
/// `39`/`49`, used for [`Color::Default`].
fn write_sgr_color<W: Write>(out: &mut W, color: Color, base: u8, reset: u8) -> io::Result<()> {
    write!(out, "\x1b[")?;
    write_sgr_params(out, color, base, reset)?;
    write!(out, "m")
}

/// A generic ANSI/SGR cell-diff renderer.
///
/// Converts [`Tile`] content into standard ANSI/CSI escape sequences and writes them to a
/// caller-supplied [`std::io::Write`] sink `W`. Tracks cursor position and the last-emitted
/// foreground/background/attribute state across calls to [`draw`](Self::draw) so it only emits
/// the escape codes needed to move to changed cells and change state.
///
/// This type has no knowledge of *how* its output bytes reach a display (stdout, a `String`
/// buffer for JS, a test harness) or *how* input arrives: it is a pure `Tile` stream -> ANSI
/// bytes transform, reused by every terminal-family
/// [`Backend`](retroglyph_core::backend::Backend) implementor.
///
/// # Examples
///
/// Driving the renderer over a `Vec<u8>` sink and asserting on the emitted ANSI bytes: no real
/// terminal is needed, since `W` here is just an in-memory buffer.
///
/// ```
/// use retroglyph_core::backend::DrawCell;
/// use retroglyph_core::color::{AnsiColor, Color};
/// use retroglyph_core::grid::Pos;
/// use retroglyph_core::color::Style;
/// use retroglyph_core::tile::Tile;
/// use retroglyph_terminal::TerminalRenderer;
///
/// let mut renderer = TerminalRenderer::new(Vec::new());
/// let tile = Tile::new('X', Style::new().fg(Color::Ansi(AnsiColor::Red)));
/// renderer.draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))?;
/// renderer.flush()?;
///
/// let out = String::from_utf8(renderer.into_writer()).expect("renderer only writes ASCII/UTF-8");
/// // `\x1b[1;1H` moves the cursor to row 1, col 1 (1-indexed); `\x1b[31;49m` sets red
/// // foreground with the default background.
/// assert_eq!(out, "\x1b[1;1H\x1b[31;49mX");
/// # Ok::<(), std::io::Error>(())
/// ```
#[derive(Debug)]
pub struct TerminalRenderer<W> {
    writer: W,
    /// Reusable scratch buffer that a whole [`draw`](Self::draw) call is rendered into, so the
    /// call ends with exactly one [`Write::write_all`] against `writer` instead of up to four
    /// small `write!` calls per cell. Cleared (not reallocated) after each flush to `writer`, so
    /// its capacity grows to fit the largest frame drawn and is then reused every call. See
    /// retroglyph#271.
    buf: Vec<u8>,
    last_fg: Option<Color>,
    last_bg: Option<Color>,
    cursor_x: Option<u16>,
    cursor_y: Option<u16>,
    plain: bool,
    color_support: ColorSupport,
}

impl<W: Write> TerminalRenderer<W> {
    /// Creates a new renderer writing to `writer`.
    pub const fn new(writer: W) -> Self {
        Self {
            writer,
            buf: Vec::new(),
            last_fg: None,
            last_bg: None,
            cursor_x: None,
            cursor_y: None,
            plain: false,
            color_support: ColorSupport::Truecolor,
        }
    }

    /// Creates a new renderer writing to `writer`, with plain-mode set explicitly.
    ///
    /// See [`set_plain_mode`](Self::set_plain_mode) for what plain mode changes; prefer
    /// [`TerminalRenderer::auto`] when `W` implements [`std::io::IsTerminal`] and the mode should
    /// be picked automatically instead of hardcoded.
    pub const fn with_plain_mode(writer: W, plain: bool) -> Self {
        Self {
            writer,
            buf: Vec::new(),
            last_fg: None,
            last_bg: None,
            cursor_x: None,
            cursor_y: None,
            plain,
            color_support: ColorSupport::Truecolor,
        }
    }

    /// Returns whether plain mode is enabled. See [`set_plain_mode`](Self::set_plain_mode).
    pub const fn plain_mode(&self) -> bool {
        self.plain
    }

    /// Returns the configured [`ColorSupport`] level. See
    /// [`set_color_support`](Self::set_color_support).
    pub const fn color_support(&self) -> ColorSupport {
        self.color_support
    }

    /// Sets the [`ColorSupport`] level. See the crate-level "RGB color fallback on 256-color
    /// terminals" doc section for the full contract.
    pub const fn set_color_support(&mut self, color_support: ColorSupport) {
        self.color_support = color_support;
    }

    /// This renderer with `color_support` set. See [`set_color_support`](Self::set_color_support).
    #[must_use]
    pub const fn with_color_support(mut self, color_support: ColorSupport) -> Self {
        self.color_support = color_support;
        self
    }

    /// Enables or disables plain mode.
    ///
    /// In plain mode, [`draw`](Self::draw) and the synchronized-update markers stop emitting
    /// ANSI/CSI escape sequences (cursor moves, color/SGR codes, `\x1b[?2026h`/`l`) entirely.
    /// Cell text is written as plain text instead, with row changes turned into `\n` and gaps
    /// between non-adjacent cells on the same row padded with spaces, so a full-grid
    /// [`draw`](Self::draw) call degrades to a readable ASCII rendering of that frame.
    ///
    /// This is modeled on Python's `blessed`, which does the same thing when its output stream
    /// isn't a TTY: piping or redirecting output (`myapp > log.txt`) shouldn't leave a file full
    /// of unreadable escape codes. Because this renderer only ever draws *changed* cells, repeated
    /// [`draw`](Self::draw) calls in plain mode append each frame's diff as more plain text rather
    /// than overwriting previous output in place: there is no cursor-addressable terminal to
    /// overwrite when the sink is a file or pipe, so this is a lossy degradation intended for
    /// logging/debugging, not for reproducing the exact interactive frame sequence.
    pub const fn set_plain_mode(&mut self, plain: bool) {
        self.plain = plain;
    }

    /// Returns a reference to the underlying writer.
    pub const fn writer(&self) -> &W {
        &self.writer
    }

    /// Returns a mutable reference to the underlying writer.
    pub const fn writer_mut(&mut self) -> &mut W {
        &mut self.writer
    }

    /// Consumes the renderer, returning the underlying writer.
    pub fn into_writer(self) -> W {
        self.writer
    }

    /// Resets tracked cursor/style state without touching the writer.
    ///
    /// Call this after an external clear (e.g. `\x1b[2J`) so the next [`draw`](Self::draw)
    /// doesn't skip a `MoveTo`/color/attribute escape under the assumption the terminal is still
    /// in the last-known state.
    pub const fn reset_state(&mut self) {
        self.last_fg = None;
        self.last_bg = None;
        self.cursor_x = None;
        self.cursor_y = None;
    }

    /// Resets only tracked cursor position, leaving tracked color/attribute state alone.
    ///
    /// Call this after a write that moves the real cursor without touching color (e.g.
    /// [`move_cursor_to`](Self::move_cursor_to)): the next [`draw`](Self::draw) must still emit a
    /// `MoveTo` for a changed cell that happens to match the now-stale tracked coordinates, but
    /// its color/attribute escapes stay conditional on an actual style change, since the pen
    /// itself never moved.
    const fn reset_cursor_tracking(&mut self) {
        self.cursor_x = None;
        self.cursor_y = None;
    }

    /// Begins a synchronized update (`\x1b[?2026h`).
    ///
    /// Terminals that support this hold rendering until the matching
    /// [`end_synchronized_update`](Self::end_synchronized_update), avoiding visible tearing
    /// mid-frame. Terminals that don't understand the sequence ignore it.
    ///
    /// A no-op in [plain mode](Self::set_plain_mode): synchronized updates are themselves a
    /// control code with nothing to synchronize once cell output has already degraded to plain
    /// text.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn begin_synchronized_update(&mut self) -> io::Result<()> {
        if self.plain {
            return Ok(());
        }
        write!(self.writer, "\x1b[?2026h")
    }

    /// Ends a synchronized update (`\x1b[?2026l`). See
    /// [`begin_synchronized_update`](Self::begin_synchronized_update).
    ///
    /// A no-op in [plain mode](Self::set_plain_mode); see
    /// [`begin_synchronized_update`](Self::begin_synchronized_update).
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn end_synchronized_update(&mut self) -> io::Result<()> {
        if self.plain {
            return Ok(());
        }
        write!(self.writer, "\x1b[?2026l")
    }

    /// Draws changed cells, emitting only the escape sequences needed to move the cursor and
    /// change color/attribute state versus what was last drawn.
    ///
    /// Mirrors [`Output::draw`](retroglyph_core::backend::Output::draw)'s contract: `content` is
    /// a stream of `(Pos, &Tile, Option<&str>)` items to render, the last being the tile's full
    /// grapheme text when it has one. As with `Output::draw`, that trailing `Option<&str>` is
    /// only ever `Some` when this crate's `egc` feature is enabled; without `egc` it is always
    /// `None`. Does not flush; call [`flush`](Self::flush) after.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn draw<'a, I>(&mut self, content: I) -> io::Result<()>
    where
        I: Iterator<Item = DrawCell<'a>>,
    {
        // Dispatch once here to one of two disjoint code paths, rather than re-checking `plain`
        // per cell. Both paths render into `self.buf` first and this writes it out with a single
        // `Write::write_all`, rather than up to four small `write!` calls per cell (see
        // retroglyph#271); this also means `writer` no longer needs to be pre-wrapped in a
        // `BufWriter` for reasonable syscall behavior, though nothing stops a caller from still
        // doing so.
        if self.plain {
            self.draw_plain(content)?;
        } else {
            self.draw_escape(content)?;
        }
        self.writer.write_all(&self.buf)?;
        self.buf.clear();
        Ok(())
    }

    /// Escape-mode half of [`draw`](Self::draw): full ANSI/CSI cursor-move and SGR color/attribute
    /// diffing against tracked state, renders into `self.buf`. See [`draw`](Self::draw) for the
    /// shared contract and [`draw_plain`](Self::draw_plain) for the plain-mode counterpart.
    #[allow(clippy::similar_names)]
    fn draw_escape<'a, I>(&mut self, content: I) -> io::Result<()>
    where
        I: Iterator<Item = DrawCell<'a>>,
    {
        for draw_cell in content {
            let (pos, cell, extra) = (draw_cell.pos, draw_cell.tile, draw_cell.grapheme);
            #[cfg(not(feature = "egc"))]
            let _ = extra;

            // Spacer cells are the right half of a wide character. The wide
            // char itself already drew over this position, so skip it. `Grid::put_tile` sets
            // this flag on every feature combination (not just `egc`; see its own doc comment),
            // so this check isn't `egc`-gated either.
            if cell
                .flags()
                .contains(retroglyph_core::tile::TileFlags::WIDE_CHAR_SPACER)
            {
                continue;
            }

            // Applied here (last-known-state comparisons and the SGR sequences below both use
            // the degraded color), not on `Tile::style` itself: `ColorSupport` degrades what is
            // *emitted*, not the tile's own requested color.
            let fg = self.color_support.apply(cell.style().foreground());
            let bg = self.color_support.apply(cell.style().background());

            // Only emit a cursor move when the cursor isn't already at the
            // right position (adjacent cells advance the cursor by printing).
            let needs_move = self.cursor_y != Some(pos.y) || self.cursor_x != Some(pos.x);
            if needs_move {
                // CSI row;col H is 1-indexed; saturate rather than wrap at u16::MAX.
                write!(
                    self.buf,
                    "\x1b[{};{}H",
                    pos.y.saturating_add(1),
                    pos.x.saturating_add(1)
                )?;
            }

            let fg_changed = self.last_fg != Some(fg);
            let bg_changed = self.last_bg != Some(bg);

            // When both channels change in the same cell transition, combine them into a
            // single SGR sequence (`\x1b[38;...;48;...m`) instead of two: same visual
            // effect, half the CSI-introducer/terminator overhead. Only one of the two
            // actually changing still gets a single-channel sequence, so an unchanged
            // channel is never re-emitted.
            if fg_changed && bg_changed {
                write!(self.buf, "\x1b[")?;
                write_sgr_params(&mut self.buf, fg, 38, 39)?;
                write!(self.buf, ";")?;
                write_sgr_params(&mut self.buf, bg, 48, 49)?;
                write!(self.buf, "m")?;
                self.last_fg = Some(fg);
                self.last_bg = Some(bg);
            } else if fg_changed {
                write_sgr_color(&mut self.buf, fg, 38, 39)?;
                self.last_fg = Some(fg);
            } else if bg_changed {
                write_sgr_color(&mut self.buf, bg, 48, 49)?;
                self.last_bg = Some(bg);
            }

            let cell_width = Self::write_glyph(&mut self.buf, cell, extra)?;

            // After printing, the terminal cursor advances by the cell's
            // display width. Track that so the next cell can skip the move.
            self.cursor_x = Some(pos.x.saturating_add(cell_width));
            self.cursor_y = Some(pos.y);
        }
        Ok(())
    }

    /// Plain-mode half of [`draw`](Self::draw): no escape sequences, cell text degraded to
    /// readable ASCII (row changes become `\n`, gaps become spaces), renders into `self.buf`.
    /// See [`draw`](Self::draw) for the shared contract, [`set_plain_mode`](Self::set_plain_mode)
    /// for the full plain-mode contract, and [`draw_escape`](Self::draw_escape) for the
    /// escape-mode counterpart.
    fn draw_plain<'a, I>(&mut self, content: I) -> io::Result<()>
    where
        I: Iterator<Item = DrawCell<'a>>,
    {
        for draw_cell in content {
            let (pos, cell, extra) = (draw_cell.pos, draw_cell.tile, draw_cell.grapheme);
            #[cfg(not(feature = "egc"))]
            let _ = extra;

            // See `draw_escape`'s identical check above: `WIDE_CHAR_SPACER` is set regardless of
            // `egc`, so skipping it here isn't `egc`-gated either.
            if cell
                .flags()
                .contains(retroglyph_core::tile::TileFlags::WIDE_CHAR_SPACER)
            {
                continue;
            }

            // Row change: newline(s) instead of a cursor-move escape. Advancing rows emits one
            // `\n` per skipped row so blank rows still show up as blank lines. A backward row, or
            // (the `pos.x < cursor_x` guard below) a same-row cell arriving out of ascending-x
            // order, both just start a fresh line: plain mode has no cursor-addressing escape
            // codes to seek backward with, so there is no way to overwrite/insert at an
            // already-passed column without corrupting what was already written. Starting a new
            // line is the least-surprising degradation available: it reproduces the
            // already-established backward-row behavior instead of silently misplacing the cell
            // right after the previous one at the wrong column (see retroglyph#273).
            let start_col = match self.cursor_y {
                Some(y) if pos.y == y && pos.x >= self.cursor_x.unwrap_or(0) => {
                    self.cursor_x.unwrap_or(0)
                }
                Some(y) if pos.y > y => {
                    for _ in 0..(pos.y - y) {
                        writeln!(self.buf)?;
                    }
                    0
                }
                Some(_) => {
                    writeln!(self.buf)?;
                    0
                }
                None => 0,
            };
            // Pad gaps between non-adjacent cells on the same row with spaces so columns
            // still line up; a fresh row starts padding from column 0.
            for _ in start_col..pos.x {
                write!(self.buf, " ")?;
            }

            let cell_width = Self::write_glyph(&mut self.buf, cell, extra)?;

            self.cursor_x = Some(pos.x.saturating_add(cell_width));
            self.cursor_y = Some(pos.y);
        }
        Ok(())
    }

    /// Writes `cell`'s printable text (the full grapheme from `extra` when the `egc` feature
    /// provides one, otherwise just the primary glyph) to `out`, returning its precomputed
    /// display width ([`Tile::width`]) so the caller can advance the tracked cursor position.
    /// Shared by [`draw_escape`](Self::draw_escape) and [`draw_plain`](Self::draw_plain).
    fn write_glyph(out: &mut Vec<u8>, cell: &Tile, extra: Option<&str>) -> io::Result<u16> {
        #[cfg(not(feature = "egc"))]
        let _ = extra;
        #[cfg(feature = "egc")]
        {
            // Print the full EGC if present; otherwise the primary glyph.
            let mut glyph_buf = [0u8; 4];
            let s: &str = match extra {
                Some(extra) => extra,
                None => cell.glyph().encode_utf8(&mut glyph_buf),
            };
            write!(out, "{s}")?;
        }
        #[cfg(not(feature = "egc"))]
        {
            write!(out, "{}", cell.glyph())?;
        }
        Ok(cell.width())
    }

    /// Flushes the underlying writer.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails to flush.
    pub fn flush(&mut self) -> io::Result<()> {
        self.writer.flush()
    }

    /// Begins a synchronized update and draws `content`, without flushing.
    ///
    /// Combines [`begin_synchronized_update`](Self::begin_synchronized_update) and
    /// [`draw`](Self::draw) into the single call every `Output::draw_layers` implementor in this
    /// workspace needs: call [`end_frame`](Self::end_frame) afterward to close the synchronized
    /// update and flush.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn draw_frame<'a, I>(&mut self, content: I) -> io::Result<()>
    where
        I: Iterator<Item = DrawCell<'a>>,
    {
        self.begin_synchronized_update()?;
        self.draw(content)
    }

    /// Ends a synchronized update and flushes the underlying writer.
    ///
    /// Combines [`end_synchronized_update`](Self::end_synchronized_update) and
    /// [`flush`](Self::flush) into the single call every `Output::flush` implementor in this
    /// workspace needs; pairs with [`draw_frame`](Self::draw_frame).
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn end_frame(&mut self) -> io::Result<()> {
        self.end_synchronized_update()?;
        self.flush()
    }

    /// Erases the whole screen and resets tracked state.
    ///
    /// Emits a full SGR reset (`\x1b[0m`) before the erase (`\x1b[2J`): most terminals implement
    /// erase-display via background color erase (BCE), painting erased cells with whatever
    /// background is currently active in the pen rather than the terminal's true default, so a
    /// colored cell drawn just before this call would otherwise leave a stale tint across the
    /// whole screen. Also homes the cursor (`\x1b[H`) and, after writing, flushes the underlying
    /// writer and calls [`reset_state`](Self::reset_state): the terminal-side state (cursor
    /// position, last color/attrs) is now stale versus what's actually on screen, so the next
    /// [`draw`](Self::draw) must re-emit full escape sequences instead of skipping them under the
    /// assumption the terminal is still in the last-known state.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails to write or flush.
    pub fn clear_screen(&mut self) -> io::Result<()> {
        write!(self.writer, "\x1b[0m\x1b[2J\x1b[H")?;
        self.writer.flush()?;
        self.reset_state();
        Ok(())
    }

    /// Moves the cursor to `position` (CUP, `CSI row;col H`, 1-indexed), without flushing.
    ///
    /// The real cursor is now wherever `position` says, not wherever the last drawn glyph left
    /// it, so this also resets tracked cursor position: otherwise the next [`draw`](Self::draw)
    /// could skip a move for a changed cell that happens to match the now-stale tracked
    /// coordinates. Color/attribute tracking is untouched: a bare cursor move doesn't change
    /// what's in the pen, so an unchanged style still skips its escape on the next draw.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn move_cursor_to(&mut self, position: Pos) -> io::Result<()> {
        write!(
            self.writer,
            "\x1b[{};{}H",
            position.y.saturating_add(1),
            position.x.saturating_add(1)
        )?;
        self.reset_cursor_tracking();
        Ok(())
    }

    /// Shows or hides the cursor (DECTCEM, `CSI ?25 h`/`CSI ?25 l`), without flushing.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn set_cursor_visible(&mut self, visible: bool) -> io::Result<()> {
        if visible {
            write!(self.writer, "\x1b[?25h")
        } else {
            write!(self.writer, "\x1b[?25l")
        }
    }

    /// Sets the cursor's shape (DECSCUSR, `CSI Ps SP q`), without flushing.
    ///
    /// # Errors
    ///
    /// Returns an error if the writer fails.
    pub fn set_cursor_style(&mut self, style: CursorStyle) -> io::Result<()> {
        // `CursorStyle` is `#[non_exhaustive]`: a future shape added upstream falls back to the
        // terminal's own default (`Ps` 0) rather than failing to compile here.
        let ps = match style {
            CursorStyle::BlinkingBlock => 1,
            CursorStyle::SteadyBlock => 2,
            CursorStyle::BlinkingUnderline => 3,
            CursorStyle::SteadyUnderline => 4,
            CursorStyle::BlinkingBar => 5,
            CursorStyle::SteadyBar => 6,
            _ => 0,
        };
        write!(self.writer, "\x1b[{ps} q")
    }
}

impl<W: Write + io::IsTerminal> TerminalRenderer<W> {
    /// Creates a new renderer writing to `writer`, auto-detecting plain mode from whether
    /// `writer` is a TTY.
    ///
    /// Equivalent to `TerminalRenderer::with_plain_mode(writer, !writer.is_terminal())`. `W`
    /// must implement [`std::io::IsTerminal`] for this to be callable: `std::io::Stdout`,
    /// `std::io::Stdin`, `std::io::Stderr`, `std::fs::File`, and their `*Lock` variants all do;
    /// an in-memory sink like `Vec<u8>` does not, so use
    /// [`with_plain_mode`](Self::with_plain_mode) directly for those.
    ///
    /// This mirrors how `retroglyph-crossterm` would typically wire up pipe-safe output: check
    /// once at startup whether the real destination is an interactive terminal, and fall back to
    /// plain text for everything else (files, pipes, `> log.txt` redirection, CI runners).
    pub fn auto(writer: W) -> Self {
        let plain = !writer.is_terminal();
        Self::with_plain_mode(writer, plain)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use retroglyph_core::color::AnsiColor;
    use retroglyph_core::color::Style;
    use retroglyph_core::grid::Pos;
    use retroglyph_core::tile::Tile;

    fn render_one(tile: &Tile) -> String {
        render_one_at(Pos { x: 0, y: 0 }, tile)
    }

    fn render_one_at(pos: Pos, tile: &Tile) -> String {
        let mut renderer = TerminalRenderer::new(Vec::new());
        renderer
            .draw(core::iter::once(DrawCell::new(pos, tile)))
            .unwrap();
        renderer.flush().unwrap();
        String::from_utf8(renderer.into_writer()).unwrap()
    }

    #[test]
    fn moves_cursor_with_1_indexed_csi() {
        let tile = Tile::new('X', Style::default());
        let out = render_one(&tile);
        assert!(out.contains("\x1b[1;1H"), "output: {out:?}");
        assert!(out.contains('X'));
    }

    #[test]
    fn does_not_overflow_at_the_maximum_position() {
        // retroglyph#729: the 1-based CUP computation (`pos.x + 1`/`pos.y + 1`) and the
        // `cursor_x` advance (`pos.x + cell_width`) used plain `u16` arithmetic that overflowed at
        // `u16::MAX`.
        let tile = Tile::new('X', Style::default());
        let out = render_one_at(
            Pos {
                x: u16::MAX,
                y: u16::MAX,
            },
            &tile,
        );
        assert!(out.contains('X'));
    }

    #[test]
    fn default_color_emits_reset_codes() {
        let tile = Tile::new('X', Style::default());
        let out = render_one(&tile);
        // Both fg and bg are unset on the very first draw, so they're combined into a single
        // SGR sequence rather than two separate `\x1b[39m\x1b[49m` escapes.
        assert!(out.contains("\x1b[39;49m"), "output: {out:?}");
    }

    #[test]
    fn ansi_color_maps_to_standard_sgr_range() {
        let style = Style::new().fg(Color::Ansi(AnsiColor::Red));
        let tile = Tile::new('X', style);
        let out = render_one(&tile);
        // Red is index 1 -> plain base 30 + 1 = 31. Background is still default (49), and both
        // channels changed on this first draw, so they're combined into one sequence.
        assert!(out.contains("\x1b[31;49m"), "output: {out:?}");
    }

    #[test]
    fn bright_ansi_color_maps_to_bright_sgr_range() {
        let style = Style::new().fg(Color::Ansi(AnsiColor::BrightRed));
        let tile = Tile::new('X', style);
        let out = render_one(&tile);
        // BrightRed is index 9 -> bright base 90 + (9-8) = 91, combined with the default bg.
        assert!(out.contains("\x1b[91;49m"), "output: {out:?}");
    }

    #[test]
    fn rgb_color_uses_extended_sgr() {
        let style = Style::new().fg(Color::Rgb { r: 1, g: 2, b: 3 });
        let tile = Tile::new('X', style);
        let out = render_one(&tile);
        assert!(out.contains("\x1b[38;2;1;2;3;49m"), "output: {out:?}");
    }

    #[test]
    fn indexed_color_uses_extended_sgr() {
        let style = Style::new().fg(Color::Indexed(200));
        let tile = Tile::new('X', style);
        let out = render_one(&tile);
        assert!(out.contains("\x1b[38;5;200;49m"), "output: {out:?}");
    }

    #[test]
    fn rgb_color_is_passed_through_without_quantization() {
        // Regression test for the documented RGB fallback contract: an RGB
        // value that doesn't land on any of the 256-color palette's exact
        // entries (e.g. a 6x6x6 cube step or a grayscale ramp step) is still
        // emitted verbatim as a 24-bit truecolor sequence, not snapped to the
        // nearest indexed color.
        let style = Style::new().fg(Color::Rgb {
            r: 91,
            g: 142,
            b: 217,
        });
        let tile = Tile::new('X', style);
        let out = render_one(&tile);
        assert!(out.contains("\x1b[38;2;91;142;217;49m"), "output: {out:?}");
        assert!(
            !out.contains("38;5;"),
            "expected no indexed fallback, got: {out:?}"
        );
    }

    fn render_one_with_color_support(tile: &Tile, color_support: ColorSupport) -> String {
        let mut renderer = TerminalRenderer::new(Vec::new()).with_color_support(color_support);
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, tile)))
            .unwrap();
        renderer.flush().unwrap();
        String::from_utf8(renderer.into_writer()).unwrap()
    }

    #[test]
    fn color_support_defaults_to_truecolor() {
        let renderer = TerminalRenderer::new(Vec::new());
        assert_eq!(renderer.color_support(), ColorSupport::Truecolor);
    }

    #[test]
    fn with_color_support_sets_the_configured_level() {
        let renderer = TerminalRenderer::new(Vec::new()).with_color_support(ColorSupport::Ansi16);
        assert_eq!(renderer.color_support(), ColorSupport::Ansi16);
    }

    #[test]
    fn color_support_truecolor_passes_rgb_through_unquantized() {
        let style = Style::new().fg(Color::Rgb {
            r: 91,
            g: 142,
            b: 217,
        });
        let tile = Tile::new('X', style);
        let out = render_one_with_color_support(&tile, ColorSupport::Truecolor);
        assert!(out.contains("\x1b[38;2;91;142;217;49m"), "output: {out:?}");
    }

    #[test]
    fn color_support_indexed256_quantizes_rgb_to_the_256_color_palette() {
        let style = Style::new().fg(Color::Rgb { r: 1, g: 2, b: 3 });
        let tile = Tile::new('X', style);
        let out = render_one_with_color_support(&tile, ColorSupport::Indexed256);
        assert!(
            out.contains("38;5;"),
            "expected an indexed SGR sequence, got: {out:?}"
        );
        assert!(
            !out.contains("38;2;"),
            "expected no truecolor sequence, got: {out:?}"
        );
    }

    #[test]
    fn color_support_ansi16_quantizes_rgb_to_the_standard_ansi_range() {
        let style = Style::new().fg(Color::Rgb { r: 255, g: 0, b: 0 });
        let tile = Tile::new('X', style);
        let out = render_one_with_color_support(&tile, ColorSupport::Ansi16);
        assert!(
            !out.contains("38;2;") && !out.contains("38;5;"),
            "expected a plain ANSI SGR code, got: {out:?}"
        );
        // Pure red quantizes to bright red (index 9 -> bright base 90 + 1 = 91).
        assert!(out.contains("\x1b[91;49m"), "output: {out:?}");
    }

    #[test]
    fn color_support_none_forces_every_color_to_default() {
        let style = Style::new()
            .fg(Color::Rgb {
                r: 91,
                g: 142,
                b: 217,
            })
            .bg(Color::Ansi(AnsiColor::Red));
        let tile = Tile::new('X', style);
        let out = render_one_with_color_support(&tile, ColorSupport::None);
        assert!(out.contains("\x1b[39;49m"), "output: {out:?}");
        assert!(
            !out.contains("38;") && !out.contains("48;") && !out.contains("31;"),
            "expected no color codes at all, got: {out:?}"
        );
    }

    #[test]
    fn combines_fg_and_bg_into_single_sequence_when_both_change() {
        // Both channels change relative to the previous cell's state, so they should be
        // coalesced into one `\x1b[38;...;48;...m` sequence instead of two separate escapes.
        let old = Tile::new(
            'A',
            Style::new()
                .fg(Color::Rgb { r: 1, g: 2, b: 3 })
                .bg(Color::Rgb { r: 4, g: 5, b: 6 }),
        );
        let new = Tile::new(
            'B',
            Style::new()
                .fg(Color::Rgb {
                    r: 10,
                    g: 20,
                    b: 30,
                })
                .bg(Color::Rgb {
                    r: 40,
                    g: 50,
                    b: 60,
                }),
        );
        let mut renderer = TerminalRenderer::new(Vec::new());
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &old)))
            .unwrap();
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &new)))
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert!(
            out.contains("\x1b[38;2;10;20;30;48;2;40;50;60m"),
            "output: {out:?}"
        );
        assert!(
            !out.contains("\x1b[48;2;40;50;60m"),
            "bg should not be emitted as a separate sequence, got: {out:?}"
        );
    }

    #[test]
    fn only_fg_change_emits_single_channel_sequence() {
        // Background is unchanged between the two draws, so only the fg escape should be
        // emitted: no combined sequence, and no redundant bg re-emission.
        let bg = Color::Rgb { r: 4, g: 5, b: 6 };
        let old = Tile::new('A', Style::new().fg(Color::Rgb { r: 1, g: 2, b: 3 }).bg(bg));
        let new = Tile::new(
            'B',
            Style::new()
                .fg(Color::Rgb {
                    r: 10,
                    g: 20,
                    b: 30,
                })
                .bg(bg),
        );
        let mut renderer = TerminalRenderer::new(Vec::new());
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &old)))
            .unwrap();
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &new)))
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        // Only the second draw's fg escape should appear after the first draw's combined one;
        // check the second draw doesn't re-emit a bg sequence.
        let second_draw_start = out.rfind("\x1b[1;1H").unwrap();
        let second_draw = &out[second_draw_start..];
        assert!(
            second_draw.contains("\x1b[38;2;10;20;30m"),
            "output: {second_draw:?}"
        );
        assert!(
            !second_draw.contains("48;2;4;5;6"),
            "output: {second_draw:?}"
        );
    }

    #[test]
    fn adjacent_cells_skip_redundant_move() {
        let tile_a = Tile::new('A', Style::default());
        let tile_b = Tile::new('B', Style::default());
        let mut renderer = TerminalRenderer::new(Vec::new());
        renderer
            .draw(
                [
                    DrawCell::new(Pos { x: 0, y: 0 }, &tile_a),
                    DrawCell::new(Pos { x: 1, y: 0 }, &tile_b),
                ]
                .into_iter(),
            )
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        // Only one cursor move: the second cell is adjacent to the first.
        assert_eq!(out.matches('H').count(), 1, "output: {out:?}");
    }

    #[test]
    fn reset_state_clears_tracked_state() {
        let tile = Tile::new('X', Style::default());
        let mut renderer = TerminalRenderer::new(Vec::new());
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();
        renderer.reset_state();
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        // Without reset_state, the second draw call (same pos, same style)
        // would skip the move + color codes entirely.
        assert_eq!(out.matches("\x1b[1;1H").count(), 2, "output: {out:?}");
    }

    #[test]
    fn synchronized_update_markers() {
        let mut renderer = TerminalRenderer::new(Vec::new());
        renderer.begin_synchronized_update().unwrap();
        renderer.end_synchronized_update().unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert_eq!(out, "\x1b[?2026h\x1b[?2026l");
    }

    /// A multi-cell span's covered cells carry that span's text fallback, so a terminal must
    /// print all of them. Unlike `WIDE_CHAR_SPACER`, which both draw paths skip.
    #[test]
    fn span_covered_cells_are_printed_as_the_text_fallback() {
        use retroglyph_core::grid::Grid;

        let mut grid = Grid::new(2, 2);
        grid.write_span(0, 0, 0, &["C=", "[]"], Style::default())
            .expect("2x2 span fits in a 2x2 grid");
        let tiles: Vec<(Pos, Tile)> = (0..2)
            .flat_map(|y| (0..2).map(move |x| (Pos { x, y }, x, y)))
            .map(|(pos, x, y)| (pos, *grid.tile(0, (x, y)).unwrap()))
            .collect();

        for plain in [false, true] {
            let mut renderer = TerminalRenderer::with_plain_mode(Vec::new(), plain);
            renderer
                .draw(tiles.iter().map(|(pos, tile)| DrawCell::new(*pos, tile)))
                .unwrap();
            renderer.flush().unwrap();
            let out = String::from_utf8(renderer.into_writer()).unwrap();
            for glyph in ['C', '=', '[', ']'] {
                assert!(
                    out.contains(glyph),
                    "plain={plain}: span fallback glyph {glyph:?} missing from {out:?}"
                );
            }
        }
    }

    #[test]
    fn plain_mode_strips_escape_codes() {
        let style = Style::new().fg(Color::Ansi(AnsiColor::Red));
        let tile = Tile::new('X', style);
        let mut renderer = TerminalRenderer::with_plain_mode(Vec::new(), true);
        renderer
            .draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert_eq!(out, "X");
    }

    #[test]
    fn plain_mode_does_not_overflow_the_cursor_x_advance_at_the_maximum_column() {
        // retroglyph#729: `cursor_x = pos.x + cell_width` overflowed for a cell at `x: u16::MAX`.
        let tile = Tile::new('X', Style::default());
        let mut renderer = TerminalRenderer::with_plain_mode(Vec::new(), true);
        renderer
            .draw(core::iter::once(DrawCell::new(
                Pos { x: u16::MAX, y: 0 },
                &tile,
            )))
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert!(out.ends_with('X'), "output: {out:?}");
    }

    #[test]
    fn plain_mode_renders_full_grid_as_readable_ascii() {
        // A 2-row, gapped grid: row 0 has 'A' at col 0 and 'B' at col 2 (a
        // gap at col 1); row 1 has 'C' at col 0. Plain mode should turn this
        // into readable text: gaps become spaces, row changes become '\n'.
        let a = Tile::new('A', Style::default());
        let b = Tile::new('B', Style::default());
        let c = Tile::new('C', Style::default());
        let mut renderer = TerminalRenderer::with_plain_mode(Vec::new(), true);
        renderer
            .draw(
                [
                    DrawCell::new(Pos { x: 0, y: 0 }, &a),
                    DrawCell::new(Pos { x: 2, y: 0 }, &b),
                    DrawCell::new(Pos { x: 0, y: 1 }, &c),
                ]
                .into_iter(),
            )
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert_eq!(out, "A B\nC");
        assert!(!out.contains('\x1b'), "output: {out:?}");
    }

    #[test]
    fn plain_mode_skips_blank_rows() {
        let a = Tile::new('A', Style::default());
        let b = Tile::new('B', Style::default());
        let mut renderer = TerminalRenderer::with_plain_mode(Vec::new(), true);
        renderer
            .draw(
                [
                    DrawCell::new(Pos { x: 0, y: 0 }, &a),
                    DrawCell::new(Pos { x: 0, y: 2 }, &b),
                ]
                .into_iter(),
            )
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert_eq!(out, "A\n\nB");
    }

    #[test]
    fn plain_mode_handles_descending_x_on_same_row_without_corrupting_output() {
        // Regression test for retroglyph#273: two cells on the same row delivered out of
        // ascending-x order (x=5 then x=2) used to compute an empty `start_col..pos.x` padding
        // range (5..2), silently appending the second cell right after the first with no
        // separator, misplacing it. Plain mode has no cursor-addressing escapes to seek
        // backward with, so the fix starts a fresh line for the out-of-order cell instead
        // (the same fallback already used for backward-row repeats) rather than corrupting the
        // column alignment of the first line.
        let a = Tile::new('A', Style::default());
        let b = Tile::new('B', Style::default());
        let mut renderer = TerminalRenderer::with_plain_mode(Vec::new(), true);
        renderer
            .draw(
                [
                    DrawCell::new(Pos { x: 5, y: 0 }, &a),
                    DrawCell::new(Pos { x: 2, y: 0 }, &b),
                ]
                .into_iter(),
            )
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        // First line: 5 spaces of padding then 'A'. Second line (fresh, since x went
        // backward): 2 spaces of padding then 'B'. Never "AB" or "A B" glued together on one
        // line at the wrong column.
        assert_eq!(out, "     A\n  B");
    }

    #[test]
    fn plain_mode_suppresses_synchronized_update_markers() {
        let mut renderer = TerminalRenderer::with_plain_mode(Vec::new(), true);
        renderer.begin_synchronized_update().unwrap();
        renderer.end_synchronized_update().unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert_eq!(out, "");
    }

    #[test]
    fn plain_mode_setter_and_getter_round_trip() {
        let mut renderer = TerminalRenderer::new(Vec::new());
        assert!(!renderer.plain_mode());
        renderer.set_plain_mode(true);
        assert!(renderer.plain_mode());
    }

    #[test]
    fn auto_detects_plain_mode_from_non_terminal_writer() {
        // `Vec<u8>` isn't a TTY-capable writer, but `std::fs::File` implements
        // `IsTerminal`, and a regular file is never a terminal.
        let path = std::env::temp_dir().join(format!(
            "retroglyph-terminal-auto-plain-mode-test-{}-{:?}",
            std::process::id(),
            std::thread::current().id()
        ));
        let file = std::fs::File::create(&path).unwrap();
        let renderer = TerminalRenderer::auto(file);
        assert!(renderer.plain_mode());
        drop(renderer);
        let _ = std::fs::remove_file(&path);
    }

    #[cfg(feature = "egc")]
    #[test]
    fn draw_prints_full_grapheme_when_provided() {
        // The tile's `glyph` is just the primary codepoint ('e'); the full
        // combining-mark cluster only reaches the renderer via the third
        // `draw` item, not the tile itself (see `Grid::grapheme`).
        let tile = Tile::new('e', Style::default());
        let mut renderer = TerminalRenderer::new(Vec::new());
        renderer
            .draw(core::iter::once(
                DrawCell::new(Pos { x: 0, y: 0 }, &tile).with_grapheme(Some("e\u{0301}")),
            ))
            .unwrap();
        renderer.flush().unwrap();
        let out = String::from_utf8(renderer.into_writer()).unwrap();
        assert!(out.contains("e\u{0301}"), "output: {out:?}");
    }
}