retroglyph_crossterm/

lib.rs

//! [`Output`], [`Input`], and [`Cursor`] implementations that render to a real terminal via
//! `crossterm`, bundled together as [`Backend`](retroglyph_core::backend::Backend).
//!
//! This crate owns the OS/TTY-specific parts: raw mode, the alternate
//! screen, the kitty keyboard protocol, and `crossterm::event` polling.
//! Cell-diffing and ANSI/SGR output are delegated to
//! [`retroglyph_terminal::TerminalRenderer`].
//!
//! [`draw`](Output::draw), [`flush`](Output::flush), and
//! [`clear`](Output::clear) propagate `std::io::Error` through this
//! backend's [`Output::Error`] type. `resize`, `set_cursor_visible`, and
//! `set_cursor_position` are infallible ([`Output::resize`] and the [`Cursor`] methods have no
//! `Result` return), so I/O failures in those methods (e.g. a closed terminal or disconnected
//! pipe) are discarded silently rather than surfaced.
//!
//! # Event polling and CPU cost
//!
//! [`poll_event`](Input::poll_event) wraps a single `crossterm::event::poll()` syscall per call.
//! A zero timeout (as used by
//! [`Terminal::drain_events`](retroglyph_core::terminal::Terminal::drain_events) to drain everything
//! buffered without blocking) performs one non-blocking `crossterm::event::poll(Duration::ZERO)`
//! syscall (`select`/`epoll` under the hood), not a busy spin inside `poll_event` itself: once
//! the OS reports no data waiting, it returns `None` immediately rather than looping. The actual
//! CPU cost lives one level up, in the caller's game loop: an uncapped loop that calls
//! `drain_events()` every iteration with no frame limiter (no `sleep`, no vsync wait) will issue
//! that non-blocking syscall as fast as the CPU allows, trading power/CPU usage for input
//! latency.
//!
//! # Focus and lifecycle events
//!
//! With [`CrosstermOptions::focus_change`] enabled (the default), a terminal losing and regaining
//! input focus is reported as [`Event::FocusLost`]/[`Event::FocusGained`]. This is the only
//! lifecycle signal this backend currently has: unlike a windowed backend, there's no separate
//! "suspended"/"paused" notion here, and this crate maps every focus change the same way
//! regardless of the underlying reason (window manager focus switch, terminal minimized, or,
//! notably on Wayland compositors, a terminal surface being hidden or unmapped without an
//! accompanying resize).
//!
//! Terminal-side state (raw mode, the alternate screen, cursor position, last-written
//! colors/attributes) is untouched by a focus change and is preserved across it: this backend
//! does not react to [`Event::FocusLost`]/[`Event::FocusGained`] itself, so nothing is torn down
//! or reinitialized. Rendering is not deferred automatically either: [`Output::draw`] and
//! [`Output::flush`] keep writing escape sequences to stdout even while unfocused, since
//! crossterm has no OS-level way to know whether that output is actually being presented while
//! hidden. An app that wants to pause redraws while unfocused (e.g. to avoid wasted work on a
//! backgrounded Wayland surface) should track [`Event::FocusLost`]/[`Event::FocusGained`] itself
//! and skip its own draw calls in between.
//!
//! If `retroglyph-core` later adds a dedicated `Event::Suspended` (or similar) distinct from
//! plain focus loss, this crate would need coordinated changes with `retroglyph-window` (which
//! shares the `Event` enum) before mapping anything to it; no such variant exists today, so there
//! is nothing for this backend to emit.
//!
//! # Tracing
//!
//! With the optional `tracing` feature enabled, [`Output::draw`], [`Output::flush`], and
//! [`Input::poll_event`] are each wrapped in a `tracing` span (`debug` level for `draw`/`flush`,
//! `trace` for `poll_event` since it's called every game-loop iteration by
//! [`Terminal::drain_events`](retroglyph_core::terminal::Terminal::drain_events)), so a subscriber (e.g.
//! `tracing-subscriber`'s fmt layer, or a flamegraph via `tracing-flame`) can show where render
//! and input-polling time actually goes. The feature adds no code and no dependency when disabled.
//!
//! # 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-terminal`'s `egc` feature (which forwards to `retroglyph-core`'s),
//! enabling grapheme-cluster-aware cell diffing.
//!
//! This crate has no code of its own gated on the flag; it exposes it so callers don't need to know
//! which crate in the terminal family actually implements it.
//!
//! ### `tracing`
//!
//! ⚪ Optional.
//!
//! Instruments `draw`, `flush`, and `poll_event` with `tracing` spans for profiling render/input
//! time.
//!
//! See where time is spent with any `tracing` subscriber (e.g. `tracing-subscriber`'s fmt layer, or
//! a flamegraph via `tracing-flame`).
//! <!-- gen-features:end -->
//!
//! # Content writer
//!
//! [`Crossterm`] is generic over its content writer: `Crossterm<W>`, defaulting to
//! `BufWriter<Stdout>` to match this type's historical, stdout-only behavior. Use
//! [`Crossterm::with_writer`] or [`CrosstermOptions::build_with_writer`] to render into a file,
//! a pipe, or an in-memory buffer instead, e.g. to capture and assert on the emitted ANSI/SGR
//! bytes in a test without a real TTY. Only the rendered cell content goes through `W`; raw
//! mode, the alternate screen, and the other terminal-protocol negotiation always target the
//! real process stdout regardless of `W`: see [`CrosstermOptions::build_with_writer`]'s docs
//! for the exact split.

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

// Compile the code blocks in both this crate's own README and the workspace root README as
// doctests so the quick-start examples are type-checked on every test run and cannot silently
// rot. The `cfg(doctest)` gate keeps these out of the rendered crate documentation.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeDoctests;

#[cfg(doctest)]
#[doc = include_str!("../../../README.md")]
struct WorkspaceReadmeDoctests;

use core::time::Duration;
use retroglyph_core::backend::DrawCell;
use retroglyph_core::backend::{Cursor, CursorStyle, Input, Output};
use retroglyph_core::event::Event;
use retroglyph_core::grid::HasSize;
use retroglyph_core::grid::{Pos, Size};
use retroglyph_terminal::TerminalRenderer;
use std::collections::VecDeque;
use std::io::{BufWriter, IsTerminal, Stdout};

// Orphan-rule note: `retroglyph_core` types and `crossterm` types are both
// foreign to this crate now that the workspace is split, so `From`/`TryFrom`
// impls between them are no longer legal (neither type is local). These are
// plain conversion functions instead.

/// Keyboard enhancement flags requested when the terminal supports the kitty
/// keyboard protocol. `REPORT_EVENT_TYPES` is what upgrades us from press-only
/// to press/repeat/release; `DISAMBIGUATE_ESCAPE_CODES` makes modified keys
/// unambiguous and is also what unlocks `CapsLock`/`ScrollLock`/`NumLock`/
/// `PrintScreen`/`Pause`/`Menu` reporting at all. `REPORT_ALL_KEYS_AS_ESCAPE_CODES` is what
/// additionally unlocks a bare modifier press (`crossterm::event::KeyCode::Modifier`, mapped to
/// [`retroglyph_core::event::KeyCode::Modifier`]) being reported as its own key event instead of
/// being silently absorbed into the modifiers field of the next non-modifier key.
fn keyboard_enhancement_flags() -> crossterm::event::KeyboardEnhancementFlags {
    crossterm::event::KeyboardEnhancementFlags::REPORT_EVENT_TYPES
        | crossterm::event::KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES
        | crossterm::event::KeyboardEnhancementFlags::REPORT_ALL_KEYS_AS_ESCAPE_CODES
}

/// Chooses a [`ColorSupport`](retroglyph_terminal::ColorSupport) level from the de facto
/// `$NO_COLOR`/`$TERM` conventions, as a pure function of their values so it's testable without
/// mutating real process environment variables.
///
/// - `no_color` any non-empty value (per <https://no-color.org>) forces
///   [`ColorSupport::None`](retroglyph_terminal::ColorSupport::None).
/// - `term` equal to `"dumb"` (the canonical "assume nothing" signal used by Emacs' shell mode,
///   some CI systems, and similar) also forces `ColorSupport::None`. A bare `"dumb"` is never
///   emitted by a terminal that actually supports color, so this carries no false-positive risk,
///   unlike the heuristic described next.
/// - Otherwise, [`ColorSupport::Truecolor`](retroglyph_terminal::ColorSupport::Truecolor):
///   matches [`TerminalRenderer`](retroglyph_terminal::TerminalRenderer)'s own default and this
///   crate's pre-existing behavior (always pass `Color::Rgb` through verbatim). Degrading below
///   this is opt-in on one of the two positive signals above; their absence is not itself a
///   signal of anything narrower.
///
/// This does **not** try to infer [`ColorSupport::Indexed256`] or
/// [`ColorSupport::Ansi16`] from `$TERM`/`$COLORTERM` text (an earlier version of this function
/// selected `Indexed256` for any `$TERM` containing `"256color"`, and `Truecolor` only for an
/// explicit `$COLORTERM=truecolor`/`24bit`). Both heuristics look reasonable in isolation and
/// both have the same failure mode: `xterm-256color` is the single most common `$TERM` value in
/// existence, including on terminals that also fully support truecolor, and plenty of genuinely
/// truecolor-capable environments never set `$COLORTERM` at all (this workspace's own PTY test
/// harness is one: `portable-pty` sets `$TERM=xterm-256color` unconditionally for the child it
/// spawns and never sets `$COLORTERM`, which silently downgraded every snapshot test's rendered
/// colors and broke them all: retroglyph#585 CI). Requiring an unambiguous signal before
/// degrading, rather than guessing from `$TERM`'s text, is what avoids repeating that. Both
/// narrower levels remain fully available as an explicit choice via
/// [`CrosstermOptions::color_support`](CrosstermOptions::color_support); they just aren't guessed
/// at automatically.
fn detect_color_support(
    no_color: Option<&str>,
    term: Option<&str>,
) -> retroglyph_terminal::ColorSupport {
    use retroglyph_terminal::ColorSupport;

    if no_color.is_some_and(|value| !value.is_empty()) {
        return ColorSupport::None;
    }
    if term == Some("dumb") {
        return ColorSupport::None;
    }
    ColorSupport::Truecolor
}

/// Thin env-reading wrapper around [`detect_color_support`]; reads the real process environment.
fn detect_color_support_from_env() -> retroglyph_terminal::ColorSupport {
    detect_color_support(
        std::env::var("NO_COLOR").ok().as_deref(),
        std::env::var("TERM").ok().as_deref(),
    )
}

// Tracks whether the currently-live `Crossterm` instance (there's normally at most one, since
// each holds exclusive use of stdout/raw mode) actually entered the alternate screen / enabled
// raw mode, so `restore_terminal` (shared by `Drop` and the process-wide panic hook, neither of
// which has access to a specific instance's `CrosstermOptions`) only undoes what was actually
// done. Unlike the other features (mouse capture, focus-change, bracketed paste, kitty protocol),
// which are safe to unconditionally disable/pop even if never enabled (crossterm's own commands
// are no-ops on a terminal that never received the matching enable sequence), unconditionally
// emitting `LeaveAlternateScreen`/`disable_raw_mode()` when we never entered/enabled them could
// corrupt a caller's already-cooked-mode terminal or emit a stray escape into their normal
// scrollback buffer.
static ALT_SCREEN_ACTIVE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
static RAW_MODE_ACTIVE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

// Tracks whether *some* `Crossterm` instance is currently live, independent of the two statics
// above (which track what a *single* construction actually enabled, for `restore_terminal`'s own
// bookkeeping). This is the fix for the hazard those two statics can't protect against on their
// own: constructing a second `Crossterm` while a first is still alive both stomp the same
// process-wide raw-mode/alternate-screen state, and dropping either one calls the shared
// `restore_terminal()`, which would tear down state the other instance still believes is active
// (e.g. dropping instance A disables raw mode and clears `RAW_MODE_ACTIVE`, while instance B is
// still alive and now silently receives line-buffered, echoed input instead of raw key events).
// Rather than trying to make concurrent instances safe (which would need real per-instance
// state, not process-global statics, since stdout/raw-mode/the alternate screen are process-wide
// OS resources with no instance-scoped handle), construction of a second live instance is
// rejected outright: see [`InstanceGuard`].
static INSTANCE_LIVE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);

/// RAII guard enforcing the "at most one live [`Crossterm`] instance per process" invariant.
///
/// [`InstanceGuard::acquire`] atomically claims [`INSTANCE_LIVE`] (returning an error if another
/// instance already holds it) and stores the resulting guard as a field of [`Crossterm`], so it
/// stays held for exactly as long as that `Crossterm` is alive. Dropping the guard (whether via
/// the owning `Crossterm`'s normal `Drop`, or because a `?` inside
/// [`Crossterm::build_from_options`] unwound out of the constructor after the guard was acquired
/// but before construction finished) releases the flag, so a single failed construction attempt
/// can never permanently wedge out all future construction.
///
/// This is independent of `restore_terminal()`/the panic hook: `restore_terminal()`
/// only clears `ALT_SCREEN_ACTIVE`/`RAW_MODE_ACTIVE` (idempotent swaps that are safe to call any
/// number of times, including from both the panic hook and the eventual `Drop`). Ordinary Rust
/// destructor semantics already guarantee this guard's `Drop` runs during an unwind (the panic
/// hook itself runs *before* unwinding starts, so it never needs to touch `INSTANCE_LIVE`), so
/// there's no double-release or release-when-nothing-was-acquired hazard: exactly one `Drop` runs
/// per successful `acquire()`, whether the instance is dropped normally or unwinds away after a
/// panic.
struct InstanceGuard {
    // Always `true` for a live `InstanceGuard`; `acquire()` never constructs one otherwise. Kept
    // as a field (rather than always releasing unconditionally in `Drop`) so the invariant "one
    // release per successful acquire" is enforced by the type itself, not just by convention.
    armed: bool,
}

impl InstanceGuard {
    /// Attempts to claim the process-wide "a `Crossterm` instance is live" flag.
    ///
    /// Returns `Err` with [`std::io::ErrorKind::ResourceBusy`] if another instance already holds
    /// it; the caller (`Crossterm::build_from_options`) is expected to propagate that error
    /// straight out of the constructor via `?` without attempting any teardown, since nothing was
    /// set up yet.
    fn acquire() -> Result<Self, std::io::Error> {
        use std::sync::atomic::Ordering;

        INSTANCE_LIVE
            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
            .map(|_| Self { armed: true })
            .map_err(|_| {
                std::io::Error::new(
                    std::io::ErrorKind::ResourceBusy,
                    "a Crossterm instance is already live in this process; only one may be \
                     constructed at a time (drop the existing instance before constructing \
                     another)",
                )
            })
    }
}

impl Drop for InstanceGuard {
    fn drop(&mut self) {
        if self.armed {
            INSTANCE_LIVE.store(false, std::sync::atomic::Ordering::Release);
        }
    }
}

/// Writes the escape sequence that's always safe to emit during terminal restore (popping the
/// kitty keyboard enhancement flags, disabling bracketed paste/focus-change/mouse capture,
/// resetting every SGR attribute, and showing the cursor) to `w`.
///
/// Split out of [`restore_terminal`] so these exact bytes can be asserted on directly against an
/// in-memory `Vec<u8>` in tests, since `restore_terminal` itself always targets the real process
/// stdout and so can't otherwise be observed from a unit test.
///
/// `SetAttribute(Attribute::Reset)` (`\x1b[0m`) clears every SGR attribute (colors, bold,
/// underline, etc.) back to the terminal's own default. The SGR "pen" is terminal-global state,
/// independent of which screen buffer is active, so without this the last color the app drew with
/// (e.g. a tinted background) survives `LeaveAlternateScreen`/raw mode exit and leaks into the
/// shell. Left unreset, that leftover pen state is also what many terminals use to paint newly
/// erased/blank cells ("background color erase") the next time this app enters the alternate
/// screen, so any per-frame blend against `Color::Default` compounds a little darker on every
/// subsequent run instead of starting from a clean slate. Unlike `LeaveAlternateScreen`/raw mode,
/// every command written here is always safe to emit (just an escape sequence, no visible glyph),
/// so it doesn't need to be gated on whether this process actually entered/enabled those.
fn write_restore_sequence<W: std::io::Write>(w: &mut W) -> std::io::Result<()> {
    // Pop the keyboard enhancement flags pushed in `Crossterm::new`. Terminals
    // that never understood the push ignore the pop just the same.
    crossterm::execute!(w, crossterm::event::PopKeyboardEnhancementFlags)?;
    crossterm::execute!(
        w,
        crossterm::event::DisableBracketedPaste,
        crossterm::event::DisableFocusChange,
        crossterm::event::DisableMouseCapture,
        crossterm::style::SetAttribute(crossterm::style::Attribute::Reset),
        crossterm::cursor::Show
    )
}

/// Helper function to restore the terminal to its normal state.
/// This is called during drops and emergency panic hooks.
fn restore_terminal() {
    use std::sync::atomic::Ordering;

    let mut stdout = std::io::stdout();
    let _ = write_restore_sequence(&mut stdout);
    if ALT_SCREEN_ACTIVE.swap(false, Ordering::AcqRel) {
        let _ = crossterm::execute!(stdout, crossterm::terminal::LeaveAlternateScreen);
    }
    if RAW_MODE_ACTIVE.swap(false, Ordering::AcqRel) {
        let _ = crossterm::terminal::disable_raw_mode();
    }
}

/// Options controlling which optional terminal protocol features
/// [`Crossterm::with_options`] enables.
///
/// All features default to `true`; mouse capture, the kitty keyboard
/// protocol, entering the alternate screen, and raw mode all match the
/// unconditional behavior of [`Crossterm::new`] prior to this type's
/// introduction. Use [`CrosstermOptions::mouse_capture`],
/// [`CrosstermOptions::kitty_protocol`], [`CrosstermOptions::focus_change`],
/// [`CrosstermOptions::bracketed_paste`], [`CrosstermOptions::alt_screen`], or
/// [`CrosstermOptions::raw_mode`] to disable a feature entirely, e.g. when
/// running on a terminal (or through a pipe/CI harness/`tmux`/SSH session)
/// where the feature is unwanted.
///
/// This is also the type returned by [`Crossterm::builder`], the preferred
/// entry point for constructing one of these: `Crossterm::builder()` reads
/// better at a call site than `CrosstermOptions::new()` but the two are
/// otherwise identical (`builder()` just calls `Self::new()`).
///
/// This crate does not attempt to auto-detect terminal
/// capabilities (no `TERM` parsing, no `supports_keyboard_enhancement()`
/// query): those queries can block for seconds on terminals that never
/// respond. `CrosstermOptions` is the opt-out mechanism instead: callers who
/// know their environment don't support a feature can disable it explicitly.
///
/// ```
/// use retroglyph_crossterm::Crossterm;
///
/// let options = Crossterm::builder().mouse_capture(false).kitty_protocol(false);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
// Six independent, unrelated terminal protocol toggles, not a state machine in disguise: each
// maps to one crossterm enable/disable command pair (or, for raw_mode/alt_screen, one
// enable/leave pair) and is meaningful on its own.
#[allow(clippy::struct_excessive_bools)]
pub struct CrosstermOptions {
    mouse_capture: bool,
    kitty_protocol: bool,
    focus_change: bool,
    bracketed_paste: bool,
    alt_screen: bool,
    raw_mode: bool,
    // `None` means auto-detect from `$NO_COLOR`/`$TERM` at build time (see
    // `detect_color_support_from_env`); `Some` is an explicit caller override that skips
    // detection entirely. Unlike the six booleans above, this can't default to a plain `bool`
    // (or even a bare `ColorSupport`) without losing the ability to tell "caller explicitly
    // wants `Truecolor`" apart from "caller didn't say, go detect it".
    color_support: Option<retroglyph_terminal::ColorSupport>,
}

impl CrosstermOptions {
    /// Creates a new set of options with every feature enabled.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Sets whether to enable mouse capture (`crossterm::event::EnableMouseCapture`).
    #[must_use]
    pub const fn mouse_capture(mut self, enabled: bool) -> Self {
        self.mouse_capture = enabled;
        self
    }

    /// Sets whether to push the kitty keyboard protocol's enhancement flags
    /// (`crossterm::event::PushKeyboardEnhancementFlags`).
    #[must_use]
    pub const fn kitty_protocol(mut self, enabled: bool) -> Self {
        self.kitty_protocol = enabled;
        self
    }

    /// Sets whether to report focus gained/lost as
    /// [`Event::FocusGained`]/[`Event::FocusLost`]
    /// (`crossterm::event::EnableFocusChange`).
    ///
    /// See the crate-level "Focus and lifecycle events" docs for the pause/resume contract this
    /// implies (e.g. on Wayland, where a terminal can lose and regain focus independent of any
    /// resize).
    #[must_use]
    pub const fn focus_change(mut self, enabled: bool) -> Self {
        self.focus_change = enabled;
        self
    }

    /// Sets whether to report bracketed paste as [`Event::Paste`]
    /// (`crossterm::event::EnableBracketedPaste`).
    #[must_use]
    pub const fn bracketed_paste(mut self, enabled: bool) -> Self {
        self.bracketed_paste = enabled;
        self
    }

    /// Sets whether to enter the alternate screen
    /// (`crossterm::terminal::EnterAlternateScreen`).
    ///
    /// Disabling this keeps rendering on the caller's normal scrollback buffer instead of
    /// switching to a dedicated full-screen surface; on exit, [`Crossterm`] only leaves the
    /// alternate screen (`LeaveAlternateScreen`) if it entered it, so disabling this doesn't
    /// risk leaving the caller's real terminal buffer in an unexpected state.
    #[must_use]
    pub const fn alt_screen(mut self, enabled: bool) -> Self {
        self.alt_screen = enabled;
        self
    }

    /// Sets whether to enable raw mode (`crossterm::terminal::enable_raw_mode`).
    ///
    /// Disabling this leaves the terminal in cooked mode, so the OS/shell keep handling line
    /// buffering, echo, and signal-generating keys (`Ctrl-C`, `Ctrl-Z`) itself instead of
    /// forwarding every keystroke as an [`Event::Key`].
    /// Restore only disables raw mode if this backend is the one that enabled it.
    #[must_use]
    pub const fn raw_mode(mut self, enabled: bool) -> Self {
        self.raw_mode = enabled;
        self
    }

    /// Overrides the [`ColorSupport`](retroglyph_terminal::ColorSupport) level, skipping this
    /// crate's own `$NO_COLOR`/`$TERM` auto-detection (see
    /// [`Crossterm::color_support`] for the auto-detected default and how it's chosen).
    /// Use this when a caller knows the receiving terminal's actual color depth (or wants to
    /// force it) rather than trusting the environment.
    #[must_use]
    pub const fn color_support(mut self, color_support: retroglyph_terminal::ColorSupport) -> Self {
        self.color_support = Some(color_support);
        self
    }

    /// Builds the [`Crossterm`] backend with these options, rendering to standard output.
    ///
    /// Equivalent to [`Crossterm::with_options`]; this is the terminal step of the
    /// `Crossterm::builder().<options>().build()` chain started by [`Crossterm::builder`].
    /// Use [`build_with_writer`](Self::build_with_writer) to render to a different sink (a
    /// file, a pipe, an in-memory buffer for tests) instead of stdout.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if raw mode or terminal commands fail. Also returns an
    /// `std::io::Error` with [`std::io::ErrorKind::ResourceBusy`] if another [`Crossterm`]
    /// instance is already live in this process: see the concurrency contract documented on
    /// [`Crossterm`].
    pub fn build(self) -> Result<Crossterm, std::io::Error> {
        // Detect once, up front, whether the real process stdout is an interactive terminal so
        // the resulting renderer degrades to pipe-safe plain text (see
        // `TerminalRenderer::set_plain_mode`) when stdout is a file, a pipe, or otherwise
        // redirected (`> log.txt`, CI runners, etc). This mirrors
        // `TerminalRenderer::auto`, but is spelled out with an explicit `is_terminal()` check on
        // the un-wrapped `Stdout` handle rather than a call to `auto` itself: `auto` requires
        // `W: IsTerminal`, and the buffered `BufWriter<Stdout>` this backend renders through
        // doesn't implement that trait (only the unbuffered `Stdout`/`File`/etc. do), so the
        // check has to happen before wrapping in `BufWriter`.
        let plain = !std::io::stdout().is_terminal();
        Crossterm::build_from_options(self, BufWriter::new(std::io::stdout()), plain)
    }

    /// Builds the [`Crossterm`] backend with these options, rendering to `writer` instead of
    /// stdout.
    ///
    /// `writer` only receives the rendered cell content ([`Output::draw`]/[`Output::flush`]
    /// output, plus the runtime [`Output::clear`]/[`Cursor::set_cursor_visible`]/
    /// [`Cursor::set_cursor_position`] escapes). Terminal-protocol setup/teardown (raw mode,
    /// the alternate screen, the initial cursor hide, mouse capture, focus-change reporting,
    /// bracketed paste, and the kitty keyboard protocol) always targets the real process
    /// stdout regardless of `writer`, since those are properties of the actual controlling
    /// terminal, not of an arbitrary byte sink. Callers rendering to a non-terminal `writer`
    /// (a file, a pipe, an in-memory buffer) should disable the features they don't want
    /// touching the real terminal via [`CrosstermOptions::raw_mode`],
    /// [`CrosstermOptions::alt_screen`], [`CrosstermOptions::mouse_capture`], etc.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if raw mode or terminal commands fail. Also returns an
    /// `std::io::Error` with [`std::io::ErrorKind::ResourceBusy`] if another [`Crossterm`]
    /// instance is already live in this process: see the concurrency contract documented on
    /// [`Crossterm`].
    pub fn build_with_writer<W: std::io::Write>(
        self,
        writer: W,
    ) -> Result<Crossterm<W>, std::io::Error> {
        // Unlike `build`, `writer` here is an arbitrary caller-supplied sink with no `IsTerminal`
        // bound (a `Vec<u8>` in tests, for instance, doesn't implement it), so there's no way to
        // auto-detect plain mode; default to `false` (ANSI/SGR escapes on), matching this
        // method's historical behavior.
        Crossterm::build_from_options(self, writer, false)
    }
}

impl Default for CrosstermOptions {
    /// Every feature enabled; matches [`Crossterm::new`]'s historical behavior. `color_support`
    /// defaults to `None` (auto-detect from the environment at build time; see
    /// [`CrosstermOptions::color_support`]).
    fn default() -> Self {
        Self {
            mouse_capture: true,
            kitty_protocol: true,
            focus_change: true,
            bracketed_paste: true,
            alt_screen: true,
            raw_mode: true,
            color_support: None,
        }
    }
}

/// A terminal rendering backend powered by `crossterm`.
///
/// Generic over the content writer `W`: the sink that receives rendered cell output
/// ([`Output::draw`]/[`Output::flush`], plus the runtime cursor/clear escapes). Defaults to
/// `BufWriter<Stdout>`, matching this type's historical behavior; use
/// [`Crossterm::with_writer`]/[`CrosstermOptions::build_with_writer`] to render to a file, a
/// pipe, or an in-memory buffer instead (e.g. for tests that want to inspect the emitted ANSI
/// bytes without a real TTY). See [`CrosstermOptions::build_with_writer`] for exactly which
/// operations go through `W` versus the real terminal.
///
/// # Concurrency: only one live instance per process
///
/// Raw mode, the alternate screen, and the other terminal-protocol state this backend negotiates
/// are process-wide OS resources (there's exactly one controlling terminal, one raw-mode flag,
/// one alternate-screen buffer), not something a `Crossterm` instance owns exclusively the way a
/// `File` owns a file descriptor. Because of that, at most one `Crossterm` (of any `W`) may be
/// live at a time in a process: constructing a second one while a first is still alive ([`new`],
/// [`with_options`], [`with_writer`], and every [`CrosstermOptions::build`]/
/// [`CrosstermOptions::build_with_writer`] call) returns an `std::io::Error` with
/// [`std::io::ErrorKind::ResourceBusy`] instead of proceeding: this is a documented error, not
/// undefined behavior, and nothing is torn down or corrupted by the attempt. Sequential
/// construct-drop-construct is fully supported: once the live instance is dropped, a new one can
/// be constructed immediately.
///
/// [`new`]: Crossterm::new
/// [`with_options`]: Crossterm::with_options
/// [`with_writer`]: Crossterm::with_writer
pub struct Crossterm<W: std::io::Write = BufWriter<Stdout>> {
    renderer: TerminalRenderer<W>,
    // Held for exactly the lifetime of this instance; releases the process-wide "an instance is
    // live" flag when this value is dropped (see [`InstanceGuard`]). Never read after
    // construction (it's kept purely for its `Drop` side effect), hence the leading
    // underscore, which also suppresses the otherwise-applicable `dead_code` lint.
    _instance_guard: InstanceGuard,
    // Cached result of the last successful `crossterm::terminal::size()` query. Seeded once at
    // construction and refreshed only when `poll_event` observes a `crossterm::event::Event::
    // Resize`: the app already receives that event on every real terminal resize, so there's
    // no need to re-query on every `Output::size()` call (a `TIOCGWINSZ` ioctl), which used to
    // run once per frame. See retroglyph#279.
    //
    // `size()` itself never re-queries after construction (see retroglyph#279), so the only
    // fallible query is the one-time seed in `build_from_options`; that's also the only place a
    // hardcoded guess (80x24, not a "last known good" value, since none exists yet) is ever
    // used. See retroglyph#281.
    cached_size: Size,
    // Events handed to `Input::push_event`, drained ahead of the real terminal by `poll_event`.
    //
    // Unlike the windowed backends, this one has its own event source, so nothing *has* to push
    // into it, but the `Input::push_event` contract is "queue this for `poll_event`", and a
    // silent no-op is a trap for the two callers that legitimately want it: a test harness
    // injecting synthetic input, and a driver that drains the queue to intercept a key and hands
    // the rest back (see `retroglyph-examples`' FPS overlay toggle). Both used to lose every
    // event they pushed here.
    pushed_events: VecDeque<Event>,
    // The options this instance was built with, retained so `suspend`/`SuspendGuard::resume` can
    // redo the exact enable sequence [`build_from_options`](Self::build_from_options) ran at
    // construction (raw mode, the alternate screen, mouse capture, focus-change reporting,
    // bracketed paste, the kitty keyboard protocol) rather than guessing which features were on.
    options: CrosstermOptions,
}

impl Crossterm {
    /// Creates a new `Crossterm` backend rendering to standard output.
    ///
    /// Enables raw mode, enters the alternate screen, hides the cursor, and
    /// enables mouse capture, focus-change reporting, bracketed paste, and
    /// the kitty keyboard protocol (all by default; see [`CrosstermOptions`]
    /// to disable any of them). Registers a process-wide panic hook (once,
    /// across all instances) that restores the terminal before the default
    /// panic handler runs, so a panic mid-render doesn't leave the user's
    /// shell in raw mode or the alternate screen.
    ///
    /// This is a thin wrapper over [`Crossterm::with_options`] with
    /// [`CrosstermOptions::default()`].
    ///
    /// # Errors
    ///
    /// Same as [`CrosstermOptions::build`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use retroglyph_core::terminal::Terminal;
    /// use retroglyph_crossterm::Crossterm;
    ///
    /// // Requires a real controlling terminal (raw mode, the alternate screen, and cursor
    /// // hiding all target the actual process stdout), so this example is `no_run`.
    /// let mut term = Terminal::new(Crossterm::new()?);
    /// term.draw(|_surface| {})?;
    /// # Ok::<(), std::io::Error>(())
    /// ```
    pub fn new() -> Result<Self, std::io::Error> {
        Self::with_options(CrosstermOptions::default())
    }

    /// Starts building a `Crossterm` backend with explicit control over which optional
    /// terminal protocol features are enabled.
    ///
    /// Equivalent to `CrosstermOptions::new()`; call [`CrosstermOptions::build`] (or
    /// [`CrosstermOptions::build_with_writer`]) once the desired features are chosen. This is
    /// the preferred entry point over `CrosstermOptions::new()` for readability at the call
    /// site:
    ///
    /// ```
    /// use retroglyph_crossterm::Crossterm;
    ///
    /// let options = Crossterm::builder()
    ///     .mouse_capture(false)
    ///     .kitty_protocol(false)
    ///     .alt_screen(true)
    ///     .raw_mode(true);
    /// // let backend = options.build()?; // requires a real terminal
    /// ```
    #[must_use]
    pub fn builder() -> CrosstermOptions {
        CrosstermOptions::new()
    }

    /// Creates a new `Crossterm` backend rendering to standard output, with
    /// explicit control over which optional protocol features are enabled.
    ///
    /// Hides the cursor unconditionally. Raw mode, entering the alternate screen, mouse
    /// capture, focus-change reporting, bracketed paste, and the kitty keyboard protocol are
    /// all enabled by default but can be disabled individually via `options`; see
    /// [`CrosstermOptions`]. Registers a process-wide panic hook (once, across all instances)
    /// that restores the terminal before the default panic handler runs, so a panic
    /// mid-render doesn't leave the user's shell in raw mode or the alternate screen.
    ///
    /// This is a thin wrapper over [`CrosstermOptions::build`]; prefer
    /// `Crossterm::builder().<options>().build()` at new call sites.
    ///
    /// # Errors
    ///
    /// Same as [`CrosstermOptions::build`].
    pub fn with_options(options: CrosstermOptions) -> Result<Self, std::io::Error> {
        options.build()
    }

    /// Creates a crossterm terminal and drives `app` with the blocking loop until
    /// it returns [`Flow::Exit`](retroglyph_core::app::Flow).
    ///
    /// This is a thin wrapper over the generic
    /// [`run_blocking`](retroglyph_core::app::run_blocking); the terminal is restored on the
    /// way out via `Drop`, so raw mode and the alternate screen are left intact
    /// until the loop actually returns. Event-driven by default (see
    /// [`RunOptions::default`](retroglyph_core::app::RunOptions)): an app that returns
    /// [`Flow::Idle`](retroglyph_core::app::Flow::Idle) blocks on input rather than spinning. Use
    /// [`Crossterm::run_with`] to pass different [`RunOptions`](retroglyph_core::app::RunOptions),
    /// for example [`RunOptions::animated`](retroglyph_core::app::RunOptions::animated) for a
    /// continuously-rendering app.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if the terminal fails to initialize, or if a frame present
    /// fails while `app` is running.
    pub fn run<A>(app: A) -> Result<(), std::io::Error>
    where
        A: retroglyph_core::app::App<Self>,
    {
        Self::run_with(app, retroglyph_core::app::RunOptions::default())
    }

    /// Creates a crossterm terminal and drives `app` with the blocking loop, per `options`, until
    /// it returns [`Flow::Exit`](retroglyph_core::app::Flow).
    ///
    /// This is a thin wrapper over the generic
    /// [`run_blocking_with`](retroglyph_core::app::run_blocking_with); see [`Crossterm::run`] for the
    /// zero-config equivalent, and [`RunOptions`](retroglyph_core::app::RunOptions) for the available
    /// pacing and idle-blocking controls. Reaching this method is the intended way to opt into
    /// [`RunOptions::animated`](retroglyph_core::app::RunOptions::animated) or a custom
    /// [`RunOptions::idle_wake`](retroglyph_core::app::RunOptions) without hand-building a
    /// [`Terminal`](retroglyph_core::terminal::Terminal) and calling `run_blocking_with` directly.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if the terminal fails to initialize, or if a frame present
    /// fails while `app` is running.
    pub fn run_with<A>(
        app: A,
        options: retroglyph_core::app::RunOptions,
    ) -> Result<(), std::io::Error>
    where
        A: retroglyph_core::app::App<Self>,
    {
        let term = retroglyph_core::terminal::Terminal::new(Self::new()?);
        retroglyph_core::app::run_blocking_with(term, app, options)
    }
}

impl<W: std::io::Write> Crossterm<W> {
    /// Creates a new `Crossterm` backend rendering to `writer` instead of standard output.
    ///
    /// Thin wrapper over [`CrosstermOptions::build_with_writer`] with
    /// [`CrosstermOptions::default()`]; see that method for the exact contract of which
    /// operations go through `writer` versus the real terminal.
    ///
    /// # Errors
    ///
    /// Same as [`CrosstermOptions::build`].
    ///
    /// # Examples
    ///
    /// Rendering into an in-memory buffer, to capture and assert on the emitted ANSI/SGR bytes
    /// without a real TTY. Terminal-protocol setup (raw mode, the alternate screen, hiding the
    /// cursor) still targets the real process stdout regardless of `writer` (see this method's
    /// docs above), so this example is `no_run`: it requires an actual controlling terminal to
    /// construct successfully, even though `writer` itself is just a `Vec<u8>`.
    ///
    /// ```no_run
    /// use retroglyph_crossterm::Crossterm;
    ///
    /// let mut buffer: Vec<u8> = Vec::new();
    /// let term = Crossterm::with_writer(&mut buffer)?;
    /// drop(term);
    /// assert!(buffer.is_empty());
    /// # Ok::<(), std::io::Error>(())
    /// ```
    pub fn with_writer(writer: W) -> Result<Self, std::io::Error> {
        CrosstermOptions::default().build_with_writer(writer)
    }

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

    /// Returns whether the underlying renderer is in plain (non-ANSI) mode.
    ///
    /// [`CrosstermOptions::build`] sets this automatically based on whether the real process
    /// stdout is an interactive terminal (see that method's docs); [`CrosstermOptions::build_with_writer`]
    /// always leaves it `false`, since an arbitrary writer's "is this a terminal" status can't be
    /// determined generically. See
    /// [`TerminalRenderer::set_plain_mode`](retroglyph_terminal::TerminalRenderer::set_plain_mode)
    /// for what plain mode changes about rendering.
    pub const fn plain_mode(&self) -> bool {
        self.renderer.plain_mode()
    }

    /// Returns the configured [`ColorSupport`](retroglyph_terminal::ColorSupport) level.
    ///
    /// Set explicitly via [`CrosstermOptions::color_support`], or auto-detected from
    /// `$NO_COLOR`/`$TERM` if not overridden; see that method's docs for the detection rules.
    pub const fn color_support(&self) -> retroglyph_terminal::ColorSupport {
        self.renderer.color_support()
    }

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

    /// Updates the cached size field if `event` is a `crossterm::event::Event::Resize`; a
    /// no-op for every other event kind.
    ///
    /// Split out of [`Input::poll_event`] so it can be exercised directly in tests without
    /// requiring a real terminal event source. See retroglyph#279.
    const fn refresh_cached_size_on_resize(&mut self, event: &crossterm::event::Event) {
        if let crossterm::event::Event::Resize(width, height) = *event {
            self.cached_size = Size::new(width, height);
        }
    }

    fn build_from_options(
        options: CrosstermOptions,
        writer: W,
        plain: bool,
    ) -> Result<Self, std::io::Error> {
        // Setup panic hook on first backend creation
        static PANIC_HOOK: std::sync::Once = std::sync::Once::new();
        PANIC_HOOK.call_once(|| {
            let original_hook = std::panic::take_hook();
            std::panic::set_hook(Box::new(move |panic_info| {
                restore_terminal();
                original_hook(panic_info);
            }));
        });

        // Reject a second concurrent instance up front, before touching any terminal state.
        // Held for the lifetime of the returned `Crossterm` (see `InstanceGuard`'s docs); if any
        // `?` below returns early, this local binding drops immediately and releases the flag, so
        // a failed construction attempt never permanently wedges out future construction.
        let instance_guard = InstanceGuard::acquire()?;

        enable_terminal_features(options)?;

        // Seed the cached size once, up front, so `size()` never has to query on the
        // per-frame path; kept fresh afterward by `poll_event` observing `Event::Resize` (see
        // below). Fall back to 80x24 (not the historical, and non-conventional, 80x25) if
        // this initial query fails; there's no better "last known good" size to fall back to
        // yet, since none has been observed. See retroglyph#281.
        let (width, height) = crossterm::terminal::size().unwrap_or((80, 24));

        // Use the caller's explicit override if given; otherwise detect from
        // `$NO_COLOR`/`$TERM`. Unlike `plain` above (which needs `writer`'s own
        // `IsTerminal` status and so can't be detected for an arbitrary `build_with_writer`
        // sink), these are process environment variables independent of `writer`, so detection
        // applies the same way regardless of which `build*` method was called.
        let color_support = options
            .color_support
            .unwrap_or_else(detect_color_support_from_env);

        Ok(Self {
            renderer: TerminalRenderer::with_plain_mode(writer, plain)
                .with_color_support(color_support),
            _instance_guard: instance_guard,
            cached_size: Size::new(width, height),
            pushed_events: VecDeque::new(),
            options,
        })
    }
}

/// Enables the terminal-protocol features `options` selects, targeting the real process stdout.
///
/// Shared by [`Crossterm::build_from_options`] (initial construction) and
/// [`SuspendGuard`]'s resume path (undoing a [`Crossterm::suspend`]), since both need to redo the
/// exact same enable sequence against the same set of options.
fn enable_terminal_features(options: CrosstermOptions) -> std::io::Result<()> {
    use std::sync::atomic::Ordering;

    if options.raw_mode {
        crossterm::terminal::enable_raw_mode()?;
        RAW_MODE_ACTIVE.store(true, Ordering::Release);
    }

    // Terminal-protocol setup always targets the real process stdout, independent of any content
    // writer a `Crossterm<W>` may be rendering to: these are properties of the actual controlling
    // terminal (raw mode, the alternate screen, mouse/focus/paste/kitty negotiation), not of the
    // content sink a caller may have swapped in via `build_with_writer`. See that method's docs.
    let mut stdout = std::io::stdout();

    if options.alt_screen {
        crossterm::execute!(stdout, crossterm::terminal::EnterAlternateScreen)?;
        ALT_SCREEN_ACTIVE.store(true, Ordering::Release);
    }

    crossterm::execute!(stdout, crossterm::cursor::Hide)?;

    if options.mouse_capture {
        crossterm::execute!(stdout, crossterm::event::EnableMouseCapture)?;
    }

    if options.focus_change {
        crossterm::execute!(stdout, crossterm::event::EnableFocusChange)?;
    }

    if options.bracketed_paste {
        crossterm::execute!(stdout, crossterm::event::EnableBracketedPaste)?;
    }

    if options.kitty_protocol {
        // Opt into the kitty keyboard protocol so we receive key repeat and
        // release events. We push optimistically rather than gating on
        // `supports_keyboard_enhancement()`: that query blocks for the
        // terminal's response (seconds on terminals that never answer, e.g.
        // pipes and CI), stalling startup. Terminals that don't implement the
        // protocol silently ignore the CSI sequence, and we map whatever key
        // events they do send. The matching pop happens on restore.
        crossterm::execute!(
            stdout,
            crossterm::event::PushKeyboardEnhancementFlags(keyboard_enhancement_flags())
        )?;
    }

    Ok(())
}

impl<W: std::io::Write> Drop for Crossterm<W> {
    fn drop(&mut self) {
        // Flush whatever `draw`/cursor calls left buffered in `renderer` *before* `restore_
        // terminal` runs: `restore_terminal` writes straight to `std::io::stdout()` and knows
        // nothing about this instance's writer. Without this, a `BufWriter` writer (the default)
        // would only flush once this whole `drop` returns and Rust drops `renderer` for real,
        // dumping any still-queued escape bytes onto the shell *after* the alternate screen has
        // already been left. See retroglyph#716.
        let _ = self.renderer.flush();
        restore_terminal();
    }
}

impl<W: std::io::Write> Crossterm<W> {
    /// Temporarily hands the real terminal back to the OS/shell, for shelling out to `$EDITOR`,
    /// a pager, or a debugger.
    ///
    /// Exits raw mode, leaves the alternate screen, and shows the cursor, only undoing whichever
    /// of those this instance actually has active, using the same "only undo what was actually
    /// done" bookkeeping this instance's `Drop` and the process-wide panic hook already share,
    /// leaving the terminal in the state a normal shell command expects. Mouse capture,
    /// focus-change reporting, bracketed paste, and the kitty keyboard protocol are also
    /// disabled, matching what a normal process exit/panic already does.
    ///
    /// Returns a [`SuspendGuard`] borrowing `self`: while it's alive, no other `Crossterm` method
    /// can be called (the borrow checker enforces this), and dropping the guard (or calling
    /// [`SuspendGuard::resume`] explicitly) restores every option this instance was originally
    /// built with and forces a full redraw on the next [`Output::draw`], since whatever ran while
    /// suspended may have written arbitrary content to the real screen that this backend's diff
    /// state doesn't know about.
    ///
    /// Does not handle `Ctrl+Z`/`SIGTSTP`: this is an explicit API for the common case (a key
    /// binding that shells out), not a signal handler. An app that also wants to
    /// suspend on `SIGTSTP` needs to install its own signal handler and call this method (and
    /// [`SuspendGuard::resume`]) from it.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if flushing the pending frame fails, or if any of the
    /// terminal-restoring commands fail (e.g. a closed terminal or disconnected pipe).
    pub fn suspend(&mut self) -> std::io::Result<SuspendGuard<'_, W>> {
        // Flush before handing the terminal back: `restore_terminal` writes straight to
        // `std::io::stdout()`, not `self.renderer`'s writer, so without this a still-buffered
        // `draw`/cursor call's escape bytes (possibly including an unterminated synchronized-
        // update start) would land on whatever program `suspend` hands the terminal to. See
        // retroglyph#716.
        self.renderer.flush()?;
        restore_terminal();
        Ok(SuspendGuard {
            crossterm: self,
            resumed: false,
        })
    }
}

/// RAII guard returned by [`Crossterm::suspend`]; see that method's docs for the full contract.
///
/// Borrows the suspended [`Crossterm`] mutably for its whole lifetime, so no other method on it
/// can be called (accidentally drawing, polling, or moving the cursor) while the real terminal is
/// handed back to the OS/shell.
pub struct SuspendGuard<'a, W: std::io::Write> {
    crossterm: &'a mut Crossterm<W>,
    // Set once `resume`/`Drop` has actually run the restore sequence, so a caller who calls
    // `resume()` explicitly doesn't pay for (or risk double-applying) a second restore when the
    // guard is then dropped.
    resumed: bool,
}

impl<W: std::io::Write> SuspendGuard<'_, W> {
    /// Restores every option the suspended [`Crossterm`] was originally built with and forces a
    /// full redraw on the next [`Output::draw`]. Equivalent to letting the guard drop, but lets a
    /// caller observe the `std::io::Error` a dropped guard would otherwise discard.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if any of the terminal-restoring commands fail (e.g. a closed
    /// terminal or disconnected pipe).
    pub fn resume(mut self) -> std::io::Result<()> {
        self.resume_inner()
    }

    fn resume_inner(&mut self) -> std::io::Result<()> {
        if self.resumed {
            return Ok(());
        }
        self.resumed = true;
        enable_terminal_features(self.crossterm.options)?;
        // The shelled-out program may have written arbitrary content to the real screen; forget
        // the tracked cursor/style state so the next `draw` re-emits full escape sequences
        // instead of skipping them under the assumption the terminal is still in the last-known
        // state (mirrors what `Output::clear` already does for the same reason).
        self.crossterm.renderer.reset_state();
        Ok(())
    }
}

impl<W: std::io::Write> Drop for SuspendGuard<'_, W> {
    fn drop(&mut self) {
        let _ = self.resume_inner();
    }
}

impl<W: std::io::Write> Output for Crossterm<W> {
    type Error = std::io::Error;

    #[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip_all))]
    fn draw_layers<'a, I>(&mut self, content: I) -> Result<(), Self::Error>
    where
        I: Iterator<Item = DrawCell<'a>>,
    {
        // Silently drop cells positioned outside the grid, the same as `Headless` and
        // `Software` already do: a caller-supplied `pos` is not trusted input, and this
        // renderer (unlike those two) has no bounds check of its own to fall back on.
        let size = self.cached_size;
        let content =
            content.filter(move |cell| cell.pos.x < size.width() && cell.pos.y < size.height());
        // Begin synchronized update so the terminal holds rendering until
        // flush() sends the matching End marker.
        self.renderer.draw_frame(content)
    }

    #[cfg_attr(feature = "tracing", tracing::instrument(level = "debug", skip_all))]
    fn flush(&mut self) -> Result<(), Self::Error> {
        self.renderer.end_frame()
    }

    fn size(&self) -> Size {
        // No syscall: just return the size cached at construction and kept fresh by
        // `poll_event` observing `Event::Resize`. See retroglyph#279.
        self.cached_size
    }

    fn resize(&mut self, size: Size) {
        // Keep `cached_size` in sync with the caller's own idea of the terminal's dimensions,
        // the same as observing a real `crossterm::event::Event::Resize` in `poll_event` does
        // (see `cached_size`'s docs): without this, `size()` drifted permanently from the real
        // terminal size after any resize, since nothing else here ever wrote to it
        // (retroglyph#763).
        self.cached_size = size;
        let _ = self.clear();
    }

    fn clear(&mut self) -> Result<(), Self::Error> {
        // Reset SGR attributes *before* erasing: most terminals implement "erase display" via
        // background color erase (BCE), painting the erased cells with whatever background is
        // currently active in the pen, not the terminal's true default. Left un-reset, a cell
        // colored by the last frame (a themed panel, a highlighted tile) becomes the color
        // `clear_screen` paints the whole screen with. That would be merely cosmetic for one
        // frame, except every cell here is a `resize()` call too (see `Output::resize` above):
        // `Terminal::resize` wipes `previous` to default tiles, so any `current` cell that's also
        // still at its default (e.g. anything the app hasn't drawn into the newly grown area yet)
        // never differs from `previous` and is never resent by the diff in `present()`. That
        // leaves the BCE-tinted patch on screen permanently: exactly the "gaps where the
        // background doesn't clear" symptom after a resize, since nothing ever draws over it
        // again.
        self.renderer.clear_screen()
    }
}

impl<W: std::io::Write> Input for Crossterm<W> {
    /// Polls for the next input event, blocking up to `timeout`. See the crate-level "Event
    /// polling and CPU cost" doc section for what a zero `timeout` costs and where the actual CPU
    /// cost of an uncapped game loop comes from.
    ///
    /// Backends and examples in this workspace that need a frame cap (e.g. software + WASM,
    /// gated on `requestAnimationFrame`) already throttle themselves upstream of this call; a
    /// crossterm-driven loop wanting the same tradeoff should add its own
    /// `std::thread::sleep`/tick budget around `drain_events()` rather than expecting this method
    /// to throttle on its behalf.
    #[cfg_attr(feature = "tracing", tracing::instrument(level = "trace", skip(self)))]
    fn poll_event(&mut self, timeout: Duration) -> Option<Event> {
        // Pushed events jump the queue: they were either injected by a test harness or handed
        // back by a driver that already read them off the real terminal, so in both cases they
        // are older than anything crossterm still has waiting.
        if let Some(event) = self.pushed_events.pop_front() {
            return Some(event);
        }

        let start = std::time::Instant::now();
        let mut remaining = timeout;

        loop {
            // Cap the polling timeout to 1 hour to prevent system-call overflow of massive durations (like Duration::MAX).
            let poll_timeout = if remaining > Duration::from_secs(3600) {
                Duration::from_secs(3600)
            } else {
                remaining
            };

            match crossterm::event::poll(poll_timeout) {
                Ok(true) => {
                    if let Ok(event) = crossterm::event::read() {
                        // Refresh the cached size in lockstep with the resize event the app
                        // itself is about to receive, so `size()` (no syscall) stays consistent
                        // with what already triggered this event. See retroglyph#279.
                        self.refresh_cached_size_on_resize(&event);
                        if let Some(mapped) = from_crossterm_event(event) {
                            return Some(mapped);
                        }
                    }
                    // An unmappable event was consumed. In non-blocking mode
                    // (timeout zero, used by drain_events), retry immediately
                    // so we don't stop draining with events still buffered.
                    if timeout.is_zero() {
                        continue;
                    }
                }
                Ok(false) => {
                    // Timeout elapsed on this poll chunk.
                }
                Err(_) => {
                    return None;
                }
            }

            let elapsed = start.elapsed();
            if elapsed >= timeout {
                return None;
            }
            remaining = timeout.checked_sub(elapsed).unwrap_or(Duration::ZERO);
        }
    }

    /// Queues `event` ahead of the real terminal's own stream; the next
    /// [`poll_event`](Self::poll_event) returns it.
    ///
    /// See the `pushed_events` field comment for why this backend implements this at all, when it
    /// has a perfectly good event source of its own.
    fn push_event(&mut self, event: Event) {
        self.pushed_events.push_back(event);
    }
}

impl<W: std::io::Write> Crossterm<W> {
    /// Sets the terminal window/tab title.
    ///
    /// Queues `crossterm::terminal::SetTitle` and flushes immediately (unlike
    /// [`Cursor::set_cursor_visible`]/[`Cursor::set_cursor_position`], this is not expected to be
    /// called every frame, so there is no deferred-flush benefit to chase). Not every terminal
    /// emulator honors this OSC sequence; on ones that don't, this is silently a no-op from the
    /// caller's perspective.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if writing or flushing the escape sequence fails (e.g. a
    /// closed terminal or disconnected pipe).
    pub fn set_title(&mut self, title: &str) -> std::io::Result<()> {
        let writer = self.renderer.writer_mut();
        crossterm::queue!(writer, crossterm::terminal::SetTitle(title))?;
        writer.flush()
    }

    /// Rings the terminal bell (writes the `BEL` control character, `\x07`).
    ///
    /// Crossterm has no dedicated `Command` type for this (unlike [`Self::set_title`]'s
    /// `SetTitle`), so this writes the raw byte directly. Whether the terminal actually makes a
    /// sound, flashes, or does nothing at all is entirely up to the terminal emulator/user
    /// configuration.
    ///
    /// # Errors
    ///
    /// Returns an `std::io::Error` if writing or flushing the byte fails (e.g. a closed terminal
    /// or disconnected pipe).
    pub fn ring_bell(&mut self) -> std::io::Result<()> {
        let writer = self.renderer.writer_mut();
        writer.write_all(b"\x07")?;
        writer.flush()
    }
}

impl<W: std::io::Write> Cursor for Crossterm<W> {
    /// Queues the show/hide escape without flushing; the next [`Output::flush`] call drains it
    /// along with everything else. A caller that hides the cursor and moves it in the same frame
    /// (a common pattern right before a draw) would otherwise pay an extra flush per call on top
    /// of the normal draw/flush pair, with no observable benefit since nothing reads the terminal
    /// state in between.
    fn set_cursor_visible(&mut self, visible: bool) {
        let _ = self.renderer.set_cursor_visible(visible);
    }

    /// Queues the cursor-move escape without flushing; see [`set_cursor_visible`](Self::set_cursor_visible)'s
    /// docs for why this is deferred to the next [`Output::flush`] instead of flushing here.
    fn set_cursor_position(&mut self, position: Pos) {
        let _ = self.renderer.move_cursor_to(position);
    }

    /// Queues the `DECSCUSR` cursor-shape escape without flushing; see
    /// [`set_cursor_visible`](Self::set_cursor_visible)'s docs for why this is deferred to the
    /// next [`Output::flush`] instead of flushing here.
    fn set_cursor_style(&mut self, style: CursorStyle) {
        let _ = self.renderer.set_cursor_style(style);
    }
}

const fn from_crossterm_key_code(
    code: crossterm::event::KeyCode,
) -> Option<retroglyph_core::event::KeyCode> {
    use crossterm::event::KeyCode as CK;
    use retroglyph_core::event::KeyCode as K;
    match code {
        CK::Char(c) => Some(K::Char(c)),
        CK::F(n) => Some(K::F(n)),
        CK::Backspace => Some(K::Backspace),
        CK::Enter => Some(K::Enter),
        CK::Left => Some(K::Left),
        CK::Right => Some(K::Right),
        CK::Up => Some(K::Up),
        CK::Down => Some(K::Down),
        CK::Home => Some(K::Home),
        CK::End => Some(K::End),
        CK::PageUp => Some(K::PageUp),
        CK::PageDown => Some(K::PageDown),
        CK::Tab => Some(K::Tab),
        CK::BackTab => Some(K::BackTab),
        CK::Delete => Some(K::Delete),
        CK::Insert => Some(K::Insert),
        CK::Esc => Some(K::Escape),
        CK::CapsLock => Some(K::CapsLock),
        CK::ScrollLock => Some(K::ScrollLock),
        CK::NumLock => Some(K::NumLock),
        CK::PrintScreen => Some(K::PrintScreen),
        CK::Pause => Some(K::Pause),
        CK::Menu => Some(K::Menu),
        _ => None,
    }
}

/// Maps a bare modifier keypress reported under
/// [`crossterm::event::KeyboardEnhancementFlags::REPORT_ALL_KEYS_AS_ESCAPE_CODES`] to retroglyph's
/// flat [`ModifierKey`](retroglyph_core::event::ModifierKey) plus the side it came from.
///
/// Crossterm's `Hyper`/`Meta`/`IsoLevel3Shift`/`IsoLevel5Shift` variants have no retroglyph
/// equivalent and fall through to `None`, same as any other unmapped key.
const fn from_crossterm_modifier_key_code(
    code: crossterm::event::ModifierKeyCode,
) -> Option<(
    retroglyph_core::event::ModifierKey,
    retroglyph_core::event::KeyLocation,
)> {
    use crossterm::event::ModifierKeyCode as CM;
    use retroglyph_core::event::KeyLocation as L;
    use retroglyph_core::event::ModifierKey as M;
    match code {
        CM::LeftShift => Some((M::Shift, L::Left)),
        CM::RightShift => Some((M::Shift, L::Right)),
        CM::LeftControl => Some((M::Control, L::Left)),
        CM::RightControl => Some((M::Control, L::Right)),
        CM::LeftAlt => Some((M::Alt, L::Left)),
        CM::RightAlt => Some((M::Alt, L::Right)),
        CM::LeftSuper => Some((M::Super, L::Left)),
        CM::RightSuper => Some((M::Super, L::Right)),
        CM::LeftHyper
        | CM::RightHyper
        | CM::LeftMeta
        | CM::RightMeta
        | CM::IsoLevel3Shift
        | CM::IsoLevel5Shift => None,
    }
}

const fn from_crossterm_key_kind(
    kind: crossterm::event::KeyEventKind,
) -> retroglyph_core::event::KeyEventKind {
    use crossterm::event::KeyEventKind as CK;
    use retroglyph_core::event::KeyEventKind as K;
    match kind {
        CK::Press => K::Press,
        CK::Repeat => K::Repeat,
        CK::Release => K::Release,
    }
}

// `KeyEventState::KEYPAD` (set under the kitty keyboard protocol) is the only thing this
// state-flags-only mapping can report; it has no notion of a left/right pair for a single
// symbolic key on its own. `Left`/`Right` locations ARE reachable from this backend, but only via
// `crossterm::event::ModifierKeyCode`'s own Left/Right variants (see
// `from_crossterm_modifier_key_code`), which `from_crossterm_event` consults instead of this
// function for `KeyCode::Modifier` events.
const fn from_crossterm_key_state(
    state: crossterm::event::KeyEventState,
) -> retroglyph_core::event::KeyLocation {
    use retroglyph_core::event::KeyLocation as L;
    if state.contains(crossterm::event::KeyEventState::KEYPAD) {
        L::Numpad
    } else {
        L::Standard
    }
}

const fn from_crossterm_key_modifiers(
    mods: crossterm::event::KeyModifiers,
) -> retroglyph_core::event::KeyModifiers {
    retroglyph_core::event::KeyModifiers::from_parts(
        mods.contains(crossterm::event::KeyModifiers::SHIFT),
        mods.contains(crossterm::event::KeyModifiers::CONTROL),
        mods.contains(crossterm::event::KeyModifiers::ALT),
        mods.contains(crossterm::event::KeyModifiers::SUPER),
    )
}

const fn from_crossterm_mouse_button(
    btn: crossterm::event::MouseButton,
) -> retroglyph_core::event::MouseButton {
    use crossterm::event::MouseButton as CB;
    use retroglyph_core::event::MouseButton as B;
    match btn {
        CB::Left => B::Left,
        CB::Right => B::Right,
        CB::Middle => B::Middle,
    }
}

// Every `crossterm::event::MouseEventKind` variant now has a retroglyph equivalent (unlike
// `from_crossterm_key_code`, which still has unmappable `KeyCode`s), so this is infallible.
//
// Crossterm's scroll variants are line-quantized with no magnitude of their own, so each is
// synthesized as a `Scroll{dx,dy}` of magnitude 1.0 in the matching sign direction (see
// `MouseEventKind::Scroll`'s docs for the sign convention this preserves).
const fn from_crossterm_mouse_event_kind(
    kind: crossterm::event::MouseEventKind,
) -> retroglyph_core::event::MouseEventKind {
    use crossterm::event::MouseEventKind as CM;
    use retroglyph_core::event::MouseEventKind as K;
    match kind {
        CM::Down(btn) => K::Down(from_crossterm_mouse_button(btn)),
        CM::Up(btn) => K::Up(from_crossterm_mouse_button(btn)),
        CM::Drag(btn) => K::Drag(from_crossterm_mouse_button(btn)),
        CM::Moved => K::Moved,
        CM::ScrollUp => K::Scroll { dx: 0.0, dy: 1.0 },
        CM::ScrollDown => K::Scroll { dx: 0.0, dy: -1.0 },
        CM::ScrollLeft => K::Scroll { dx: -1.0, dy: 0.0 },
        CM::ScrollRight => K::Scroll { dx: 1.0, dy: 0.0 },
    }
}

const fn from_crossterm_mouse_event(
    m: crossterm::event::MouseEvent,
) -> retroglyph_core::event::MouseEvent {
    // Crossterm is a character-mode backend; it has no sub-cell resolution.
    retroglyph_core::event::MouseEvent::new(
        from_crossterm_mouse_event_kind(m.kind),
        Pos {
            x: m.column,
            y: m.row,
        },
        from_crossterm_key_modifiers(m.modifiers),
    )
}

// Taking ownership matches the call site: `crossterm::event::read()` hands us
// a freshly-owned `Event` with nothing else holding a reference to it.
//
// `#[doc(hidden)] pub` (rather than private) solely so `benches/event_translation.rs` (a
// separate compiled crate, same restriction as an integration test) can call it directly to
// measure retroglyph#285's "event translation throughput" case; this is not a supported public
// API and can change or disappear without a semver-relevant changelog entry.
#[doc(hidden)]
// The single failure mode is "this event has no retroglyph equivalent", which `Option` expresses
// directly; the only caller (`poll_event`) already discards an unmappable event entirely (see the
// retry-on-unmappable-event loop above).
#[must_use]
#[allow(clippy::needless_pass_by_value)]
pub fn from_crossterm_event(event: crossterm::event::Event) -> Option<Event> {
    use crossterm::event::Event as CE;
    match event {
        CE::Key(k) => {
            // A bare modifier press takes a separate path: `ModifierKeyCode` carries the
            // left/right side itself, which overrides whatever `from_crossterm_key_state` would
            // otherwise report (it only ever detects `Numpad` from the `KEYPAD` state flag).
            if let crossterm::event::KeyCode::Modifier(mkc) = k.code {
                let (modifier, location) = from_crossterm_modifier_key_code(mkc)?;
                return Some(Event::Key(retroglyph_core::event::KeyEvent::with_location(
                    retroglyph_core::event::KeyCode::Modifier(modifier),
                    from_crossterm_key_modifiers(k.modifiers),
                    from_crossterm_key_kind(k.kind),
                    location,
                )));
            }

            // With `DISAMBIGUATE_ESCAPE_CODES` enabled (see `keyboard_enhancement_flags`),
            // terminals that support the kitty keyboard protocol report Shift+Tab as `Tab` plus
            // a shift modifier (CSI-u always encodes Tab's base codepoint, never a separate
            // "backtab" one) rather than the legacy `ESC[Z` -> `KeyCode::BackTab` escape. Without
            // this, Shift+Tab is silently indistinguishable from plain Tab on any terminal that
            // negotiated the enhanced protocol (kitty, WezTerm, foot, Ghostty, recent Alacritty).
            let is_shift_tab = matches!(k.code, crossterm::event::KeyCode::Tab)
                && k.modifiers.contains(crossterm::event::KeyModifiers::SHIFT);
            let code = if is_shift_tab {
                retroglyph_core::event::KeyCode::BackTab
            } else {
                from_crossterm_key_code(k.code)?
            };
            Some(Event::Key(retroglyph_core::event::KeyEvent::with_location(
                code,
                from_crossterm_key_modifiers(k.modifiers),
                from_crossterm_key_kind(k.kind),
                from_crossterm_key_state(k.state),
            )))
        }
        CE::Mouse(m) => Some(Event::Mouse(from_crossterm_mouse_event(m))),
        CE::Resize(w, h) => Some(Event::Resize(w, h)),
        CE::Paste(text) => Some(Event::Paste(text)),
        CE::FocusGained => Some(Event::FocusGained),
        CE::FocusLost => Some(Event::FocusLost),
    }
}

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

    // `cargo test` runs `#[test]` functions in this module across multiple threads by default.
    // Any test that actually constructs a `Crossterm`/acquires an `InstanceGuard` contends for
    // the same process-wide `INSTANCE_LIVE` flag, so without serializing them a legitimate
    // concurrent construction from an unrelated test in this file could spuriously trip the new
    // "second live instance" rejection. This lock (held only by tests that touch that shared
    // state) keeps those tests deterministic without disabling parallelism for the whole file.
    static TEST_GUARD_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    fn key_code_of(ct_event: crossterm::event::Event) -> retroglyph_core::event::KeyCode {
        match from_crossterm_event(ct_event) {
            Some(Event::Key(key)) => key.code,
            other => panic!("expected Some(Event::Key(_)), got {other:?}"),
        }
    }

    #[test]
    fn restore_sequence_resets_all_sgr_attributes() {
        // Regression test: `restore_terminal` (shared by `Drop`, the panic hook, and `suspend`)
        // used to leave the last frame's SGR colors/attributes active on exit. That leftover
        // "pen" state leaked into the shell, and into whatever a terminal uses to paint newly
        // erased cells the next time this process entered the alternate screen, so a background
        // that blended against `Color::Default` got a little darker on every subsequent launch
        // instead of starting from a clean slate. `write_restore_sequence` must always emit a
        // full SGR reset (`\x1b[0m`) so every restore leaves the terminal's pen at its own
        // default, regardless of whatever color/attribute state the app last drew with.
        let mut buf = Vec::new();
        write_restore_sequence(&mut buf).unwrap();
        let out = String::from_utf8(buf).unwrap();
        assert!(
            out.contains("\x1b[0m"),
            "restore sequence must reset all SGR attributes, got: {out:?}"
        );
    }

    #[test]
    fn keypad_state_maps_to_numpad_location() {
        let ct_event =
            crossterm::event::Event::Key(crossterm::event::KeyEvent::new_with_kind_and_state(
                crossterm::event::KeyCode::Char('8'),
                crossterm::event::KeyModifiers::NONE,
                crossterm::event::KeyEventKind::Press,
                crossterm::event::KeyEventState::KEYPAD,
            ));
        let Some(Event::Key(key)) = from_crossterm_event(ct_event) else {
            panic!("expected Some(Event::Key(_))");
        };
        assert_eq!(key.location, retroglyph_core::event::KeyLocation::Numpad);
    }

    #[test]
    fn no_keypad_state_maps_to_standard_location() {
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Char('8'),
            crossterm::event::KeyModifiers::NONE,
        ));
        let Some(Event::Key(key)) = from_crossterm_event(ct_event) else {
            panic!("expected Some(Event::Key(_))");
        };
        assert_eq!(key.location, retroglyph_core::event::KeyLocation::Standard);
    }

    #[test]
    fn left_shift_modifier_key_maps_to_modifier_with_left_location() {
        use retroglyph_core::event::{KeyCode, KeyLocation, ModifierKey};

        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Modifier(crossterm::event::ModifierKeyCode::LeftShift),
            crossterm::event::KeyModifiers::SHIFT,
        ));
        let Some(Event::Key(key)) = from_crossterm_event(ct_event) else {
            panic!("expected Some(Event::Key(_))");
        };
        assert_eq!(key.code, KeyCode::Modifier(ModifierKey::Shift));
        assert_eq!(key.location, KeyLocation::Left);
    }

    #[test]
    fn right_alt_modifier_key_maps_to_modifier_with_right_location() {
        use retroglyph_core::event::{KeyCode, KeyLocation, ModifierKey};

        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Modifier(crossterm::event::ModifierKeyCode::RightAlt),
            crossterm::event::KeyModifiers::ALT,
        ));
        let Some(Event::Key(key)) = from_crossterm_event(ct_event) else {
            panic!("expected Some(Event::Key(_))");
        };
        assert_eq!(key.code, KeyCode::Modifier(ModifierKey::Alt));
        assert_eq!(key.location, KeyLocation::Right);
    }

    #[test]
    fn hyper_modifier_key_has_no_retroglyph_equivalent() {
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Modifier(crossterm::event::ModifierKeyCode::LeftHyper),
            crossterm::event::KeyModifiers::NONE,
        ));
        assert_eq!(from_crossterm_event(ct_event), None);
    }

    #[test]
    fn caps_lock_maps_straight_through() {
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::CapsLock,
            crossterm::event::KeyModifiers::NONE,
        ));
        assert_eq!(
            key_code_of(ct_event),
            retroglyph_core::event::KeyCode::CapsLock
        );
    }

    #[test]
    fn crossterm_options_default_matches_historical_always_on_behavior() {
        // `Crossterm::new()` used to unconditionally enable raw mode, the alternate screen,
        // mouse capture, and push the kitty keyboard protocol; `CrosstermOptions::default()`
        // must preserve that behavior exactly so `Crossterm::new()` (which delegates to
        // `with_options(CrosstermOptions::default())`) stays backward compatible. Focus-change
        // and bracketed-paste reporting are later additions and default to enabled as well,
        // consistent with the other features.
        let options = CrosstermOptions::default();
        assert!(options.mouse_capture);
        assert!(options.kitty_protocol);
        assert!(options.focus_change);
        assert!(options.bracketed_paste);
        assert!(options.alt_screen);
        assert!(options.raw_mode);
    }

    #[test]
    fn crossterm_builder_is_equivalent_to_options_new() {
        // `Crossterm::builder()` is the documented preferred entry point; it must produce the
        // same defaults as `CrosstermOptions::new()`/`::default()`.
        assert_eq!(Crossterm::builder(), CrosstermOptions::new());
    }

    #[test]
    fn disabling_raw_mode_and_alt_screen_lets_build_succeed_without_a_tty() {
        // With both raw mode and the alternate screen opted out, `build()` no longer calls
        // `enable_raw_mode()`/`EnterAlternateScreen` (the two commands that fail outright
        // without a real controlling terminal), so construction can succeed even against a
        // fully redirected/piped stdout (as under `cargo test`). Skip the assertion (rather than
        // failing) on the rare environment where even the always-safe cursor-hide escape write
        // fails outright (e.g. a closed stdout), since that's not what this test is about.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        if let Ok(term) = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .build()
        {
            drop(term);
        }
    }

    #[test]
    fn suspend_resume_forces_a_full_redraw() {
        // With every TTY-only feature disabled (the same combination other `build_with_writer`
        // tests use to run without a real terminal), `suspend`/resuming a dropped `SuspendGuard`
        // still exercise the shared restore/`enable_terminal_features` machinery: both only
        // touch process stdout via always-safe commands (cursor show/hide, disabling features
        // that were never enabled) when raw mode/the alternate screen are off, so this succeeds
        // under `cargo test`'s non-TTY stdout.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        let tile = Tile::new('X', retroglyph_core::color::Style::default());

        // Establish tracked cursor state at (0, 0): a second draw at the same position would
        // normally skip the `MoveTo` escape since the cursor is already tracked as being there.
        term.draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();
        term.flush().unwrap();

        {
            let guard = term.suspend().expect("suspend must succeed without a real terminal once all TTY-only features are disabled");
            drop(guard);
        }

        // `resume` (run here via `Drop`) must have called `reset_state`, so this draw at the same
        // position re-emits the cursor-move escape instead of skipping it.
        term.draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();
        term.flush().unwrap();

        let written = String::from_utf8(term.writer().clone()).unwrap();
        assert_eq!(
            written.matches("\x1b[1;1H").count(),
            2,
            "expected the cursor-move escape to be re-emitted after resume: {written:?}"
        );
    }

    #[test]
    fn set_cursor_position_desyncs_the_renderers_tracked_cursor() {
        // Regression test for retroglyph#713: `set_cursor_position` queued its `MoveTo` escape
        // straight into the writer without telling the shared `TerminalRenderer` the cursor had
        // moved, so `cursor_x`/`cursor_y` kept whatever position the last *drawn glyph* left them
        // at. A subsequent `draw()` whose first changed cell happened to match that stale tracked
        // position then skipped its own `MoveTo` entirely, painting wherever the real cursor was
        // actually left (by `set_cursor_position`) instead of the intended cell.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        let tile_a = Tile::new('A', retroglyph_core::color::Style::default());
        let tile_b = Tile::new('B', retroglyph_core::color::Style::default());

        // Drawing at (0, 0) leaves the renderer tracking the cursor at (1, 0), right after the
        // glyph it just wrote.
        term.draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile_a)))
            .unwrap();
        term.flush().unwrap();

        // The app parks the caret elsewhere, e.g. a text field or status line, once per frame: a
        // common pattern that must not corrupt the next frame's diff.
        Cursor::set_cursor_position(&mut term, Pos { x: 7, y: 3 });
        term.flush().unwrap();

        // The first (and only) changed cell in this frame is exactly (1, 0): the position
        // `set_cursor_position` desynced the tracked cursor from.
        term.draw(core::iter::once(DrawCell::new(Pos { x: 1, y: 0 }, &tile_b)))
            .unwrap();
        term.flush().unwrap();

        let written = String::from_utf8(term.writer().clone()).unwrap();
        let cup_1_0 = "\x1b[1;2H"; // 1-indexed CUP for (x=1, y=0)
        let b_pos = written
            .rfind('B')
            .unwrap_or_else(|| panic!("expected 'B' in output: {written:?}"));
        let cup_pos = written.rfind(cup_1_0).unwrap_or_else(|| {
            panic!("expected a CUP back to (1, 0) before drawing 'B', got: {written:?}")
        });
        assert!(
            cup_pos < b_pos,
            "CUP to (1, 0) must precede 'B': {written:?}"
        );
    }

    #[test]
    fn suspend_resume_is_idempotent_when_resume_is_called_explicitly() {
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        let guard = term.suspend().expect(
            "suspend must succeed without a real terminal once all TTY-only features are disabled",
        );
        guard.resume().expect(
            "resume must succeed without a real terminal once all TTY-only features are disabled",
        );
        // The guard is consumed by `resume`, so there's no double-restore on drop to assert
        // against directly; this test's real assertion is that `resume()` itself returns `Ok`.
    }

    #[test]
    fn restore_does_not_flush_pending_content_before_giving_the_terminal_back() {
        // Regression test for retroglyph#716: `suspend` (and `Crossterm::drop`, exercised the
        // same way here since both share `restore_terminal`) must flush whatever `draw` left
        // buffered in the renderer before handing control back, not after.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        let tile = Tile::new('X', retroglyph_core::color::Style::default());
        // Drawn but deliberately *not* flushed: this is the buffered content `suspend` must not
        // strand behind the restore sequence.
        term.draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();

        let guard = term.suspend().expect(
            "suspend must succeed without a real terminal once all TTY-only features are disabled",
        );
        // Once `suspend` has returned, the pending frame must already be visible in the writer,
        // not still sitting in `renderer`'s internal buffer waiting on a later flush.
        let written = String::from_utf8(guard.crossterm.writer().clone()).unwrap();
        assert!(
            written.contains('X'),
            "expected the drawn cell to have been flushed to the writer before suspend returned: {written:?}"
        );
        drop(guard);
    }

    #[test]
    fn pushed_events_are_returned_by_poll_event_in_order() {
        use retroglyph_core::event::{KeyCode, KeyEvent, KeyModifiers};

        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let Ok(mut term) = CrosstermOptions::new()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
        else {
            return;
        };

        let first = Event::Key(KeyEvent::new(KeyCode::Char('a'), KeyModifiers::NONE));
        let second = Event::Resize(10, 4);
        term.push_event(first.clone());
        term.push_event(second.clone());

        assert_eq!(term.poll_event(Duration::ZERO), Some(first));
        assert_eq!(term.poll_event(Duration::ZERO), Some(second));
        // Drained: the next poll falls through to the real (empty, non-TTY) event source.
        assert_eq!(term.poll_event(Duration::ZERO), None);
    }

    #[test]
    fn build_with_writer_renders_cell_content_into_a_custom_sink() {
        // The whole point of a generic content writer: draw/flush output lands in `writer`
        // (here a `Vec<u8>`) instead of stdout, with no real terminal required as long as the
        // real-terminal-only features (raw mode, alt screen, mouse/focus/paste/kitty) are
        // disabled, exactly the combination `CrosstermOptions::build_with_writer`'s docs
        // recommend for a non-TTY sink.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        let tile = Tile::new('X', retroglyph_core::color::Style::default());
        term.draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();
        term.flush().unwrap();

        let written = String::from_utf8(term.writer().clone()).unwrap();
        assert!(
            written.contains('X'),
            "expected drawn glyph in output: {written:?}"
        );
        assert!(
            !term.plain_mode(),
            "build_with_writer must not auto-detect plain mode for an arbitrary writer"
        );
    }

    #[test]
    fn clear_resets_sgr_attributes_before_erasing() {
        // Regression test: `Output::clear` (also called by `Output::resize` on every terminal
        // resize) used to issue `Clear(ClearType::All)` without resetting the SGR pen first.
        // Terminals that implement erase-display via background color erase (BCE) paint erased
        // cells with whatever background is currently active, not the terminal's true default,
        // so a colored cell drawn just before a resize left a stale tint across the whole
        // screen, and since `Terminal::resize` (in `retroglyph-core`) wipes the diff's
        // `previous` grid to default tiles, nothing ever draws over that tint again in areas
        // that stay at their default value. `clear` must emit a full SGR reset ahead of the
        // erase so BCE always paints with the terminal's real default background.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        // Draw a colored cell first so the SGR pen is left non-default, mirroring the last
        // frame drawn before a real resize.
        let style = retroglyph_core::color::Style::new().bg(retroglyph_core::color::Color::Rgb {
            r: 200,
            g: 0,
            b: 0,
        });
        let tile = Tile::new('X', style);
        term.draw(core::iter::once(DrawCell::new(Pos { x: 0, y: 0 }, &tile)))
            .unwrap();
        term.flush().unwrap();

        term.clear().unwrap();

        let written = String::from_utf8(term.writer().clone()).unwrap();
        let clear_pos = written
            .rfind("\x1b[2J")
            .unwrap_or_else(|| panic!("clear() must emit Clear(ClearType::All), got: {written:?}"));
        let reset_pos = written
            .rfind("\x1b[0m")
            .unwrap_or_else(|| panic!("clear() must emit a full SGR reset, got: {written:?}"));
        assert!(
            reset_pos < clear_pos,
            "SGR reset must precede the erase so background color erase paints with the \
             terminal's true default, not the last frame's color; output: {written:?}"
        );
    }

    #[test]
    fn with_writer_is_equivalent_to_default_options_build_with_writer() {
        // `Crossterm::with_writer` is the `CrosstermOptions::default()` shortcut, matching how
        // `Crossterm::new()` relates to `with_options(CrosstermOptions::default())`. Both fail
        // the same way without a real terminal (raw mode/alt screen left enabled), so just
        // assert they agree on success or failure rather than requiring either to succeed. Each
        // build is dropped before the next one starts (rather than held simultaneously) so the
        // comparison reflects real-terminal availability, not a spurious rejection from the new
        // "only one live instance" guard tripping on the still-live first instance.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let via_shortcut = Crossterm::with_writer(Vec::<u8>::new());
        let via_shortcut_ok = via_shortcut.is_ok();
        drop(via_shortcut);
        let via_builder = CrosstermOptions::default().build_with_writer(Vec::<u8>::new());
        let via_builder_ok = via_builder.is_ok();
        drop(via_builder);
        assert_eq!(via_shortcut_ok, via_builder_ok);
    }

    #[test]
    fn instance_guard_rejects_a_second_concurrent_acquire() {
        // Exercises the internal guard type directly: deterministic and doesn't require a real
        // TTY, unlike driving raw-mode/alt-screen terminal calls through a full `Crossterm`
        // construction would. The first `acquire()` claims the process-wide flag; a second
        // `acquire()` while the first guard is still alive must be rejected; once the first guard
        // is dropped, `acquire()` must succeed again.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);

        let first = InstanceGuard::acquire().expect("first acquire must succeed");

        match InstanceGuard::acquire() {
            Ok(_) => {
                panic!("a second concurrent acquire must be rejected while the first guard is live")
            }
            Err(err) => assert_eq!(err.kind(), std::io::ErrorKind::ResourceBusy),
        }

        drop(first);

        let third = InstanceGuard::acquire();
        assert!(
            third.is_ok(),
            "acquire must succeed again once the prior guard is dropped"
        );
    }

    #[test]
    fn constructing_a_second_live_crossterm_is_rejected_until_the_first_is_dropped() {
        // End-to-end version of `instance_guard_rejects_a_second_concurrent_acquire`, through the
        // public `Crossterm` API rather than the internal guard type. All TTY-only features are
        // disabled so construction doesn't require a real terminal (see
        // `build_with_writer_renders_cell_content_into_a_custom_sink` above for why that
        // combination is safe under `cargo test`'s captured, non-TTY stdout).
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);

        let options = || {
            Crossterm::builder()
                .raw_mode(false)
                .alt_screen(false)
                .mouse_capture(false)
                .focus_change(false)
                .bracketed_paste(false)
                .kitty_protocol(false)
        };

        let first = options()
            .build_with_writer(Vec::new())
            .expect("first construction must succeed without a TTY");

        match options().build_with_writer(Vec::new()) {
            Ok(_) => panic!(
                "a second live Crossterm instance must be rejected while the first is still alive"
            ),
            Err(err) => assert_eq!(err.kind(), std::io::ErrorKind::ResourceBusy),
        }

        drop(first);

        let third = options().build_with_writer(Vec::new());
        assert!(
            third.is_ok(),
            "construction must succeed again once the first instance is dropped"
        );
    }

    #[test]
    fn crossterm_options_can_opt_out_of_all_features() {
        // Compile-level/API-shape check: building a `CrosstermOptions` with all flags disabled
        // via the builder type-checks and round-trips its fields. Exercising the actual terminal
        // commands (`with_options`/`build` itself) requires a real TTY, which isn't available in
        // CI, so this is not a full integration test (see tests/non_tty.rs for the
        // non-TTY integration coverage that is possible without one).
        let options = CrosstermOptions::new()
            .mouse_capture(false)
            .kitty_protocol(false)
            .focus_change(false)
            .bracketed_paste(false)
            .alt_screen(false)
            .raw_mode(false);
        assert!(!options.mouse_capture);
        assert!(!options.kitty_protocol);
        assert!(!options.focus_change);
        assert!(!options.bracketed_paste);
        assert!(!options.alt_screen);
        assert!(!options.raw_mode);
    }

    #[test]
    fn legacy_backtab_maps_straight_through() {
        // Terminals without the kitty protocol send the legacy `ESC[Z` escape, which crossterm
        // already decodes as `KeyCode::BackTab` with no shift modifier attached.
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::BackTab,
            crossterm::event::KeyModifiers::NONE,
        ));
        assert_eq!(
            key_code_of(ct_event),
            retroglyph_core::event::KeyCode::BackTab
        );
    }

    #[test]
    fn kitty_protocol_shift_tab_normalizes_to_backtab() {
        // Under DISAMBIGUATE_ESCAPE_CODES, kitty-protocol terminals report Shift+Tab as plain
        // `Tab` plus a shift modifier rather than a distinct backtab code: this is the case
        // `from_crossterm_event` has to normalize.
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Tab,
            crossterm::event::KeyModifiers::SHIFT,
        ));
        assert_eq!(
            key_code_of(ct_event),
            retroglyph_core::event::KeyCode::BackTab
        );
    }

    #[test]
    fn plain_tab_is_unaffected() {
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Tab,
            crossterm::event::KeyModifiers::NONE,
        ));
        assert_eq!(key_code_of(ct_event), retroglyph_core::event::KeyCode::Tab);
    }

    #[test]
    fn shift_modifier_on_non_tab_keys_is_unaffected() {
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Char('a'),
            crossterm::event::KeyModifiers::SHIFT,
        ));
        assert_eq!(
            key_code_of(ct_event),
            retroglyph_core::event::KeyCode::Char('a')
        );
    }

    #[test]
    fn crossterm_super_modifier_is_mapped_on_key_events() {
        // Under DISAMBIGUATE_ESCAPE_CODES (the default kitty flag negotiated by
        // `Crossterm::builder()`), a compliant terminal reports the Super/Cmd bit, and
        // crossterm's own `parse_modifiers` already maps it to `KeyModifiers::SUPER`. This
        // translation layer must not drop it (retroglyph#714).
        let ct_event = crossterm::event::Event::Key(crossterm::event::KeyEvent::new(
            crossterm::event::KeyCode::Char('s'),
            crossterm::event::KeyModifiers::SUPER,
        ));
        let Some(Event::Key(key)) = from_crossterm_event(ct_event) else {
            panic!("expected a key event")
        };
        assert!(
            key.modifiers
                .contains(retroglyph_core::event::KeyModifiers::SUPER)
        );
        assert_eq!(key.code, retroglyph_core::event::KeyCode::Char('s'));
    }

    #[test]
    fn crossterm_super_modifier_is_mapped_on_mouse_events() {
        // The same translation function backs mouse events, so the gap in
        // `from_crossterm_key_modifiers` affected Cmd-modified clicks identically (retroglyph#714).
        let ct_event = crossterm::event::Event::Mouse(crossterm::event::MouseEvent {
            kind: crossterm::event::MouseEventKind::Down(crossterm::event::MouseButton::Left),
            column: 0,
            row: 0,
            modifiers: crossterm::event::KeyModifiers::SUPER,
        });
        let Some(Event::Mouse(mouse)) = from_crossterm_event(ct_event) else {
            panic!("expected a mouse event")
        };
        assert!(
            mouse
                .modifiers
                .contains(retroglyph_core::event::KeyModifiers::SUPER)
        );
    }

    #[test]
    fn size_does_not_requery_after_construction() {
        // `size()` must return the field cached at construction rather than issuing a fresh
        // `crossterm::terminal::size()` syscall on every call (retroglyph#279). Overwrite the
        // cached field with a sentinel value no real terminal query would plausibly produce,
        // then confirm `size()` echoes that sentinel back instead of re-querying and returning
        // whatever the actual (non-TTY, under `cargo test`) terminal size happens to be.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        let sentinel = Size::new(4321, 1234);
        term.cached_size = sentinel;

        assert_eq!(
            term.size(),
            sentinel,
            "size() must return the cached field, not re-query the terminal"
        );
    }

    #[test]
    fn resize_event_refreshes_the_cached_size() {
        // `poll_event` refreshes the cached size in lockstep with any `Event::Resize` it reads
        // (retroglyph#279). `refresh_cached_size_on_resize` is the extracted helper it
        // calls; exercising it directly avoids needing a real terminal event source to prove
        // the cache-update behavior.
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        term.refresh_cached_size_on_resize(&crossterm::event::Event::Resize(120, 40));
        assert_eq!(term.size(), Size::new(120, 40));

        // Non-resize events must not disturb the cached size.
        term.refresh_cached_size_on_resize(&crossterm::event::Event::FocusGained);
        assert_eq!(term.size(), Size::new(120, 40));
    }

    #[test]
    fn crossterm_paste_maps_to_retroglyph_paste() {
        let ct_event = crossterm::event::Event::Paste("pasted text".to_string());
        match from_crossterm_event(ct_event) {
            Some(Event::Paste(text)) => assert_eq!(text, "pasted text"),
            other => panic!("expected Some(Event::Paste(_)), got {other:?}"),
        }
    }

    #[test]
    fn crossterm_focus_gained_maps_correctly() {
        let ct_event = crossterm::event::Event::FocusGained;
        assert!(matches!(
            from_crossterm_event(ct_event),
            Some(Event::FocusGained)
        ));
    }

    #[test]
    fn crossterm_focus_lost_maps_correctly() {
        let ct_event = crossterm::event::Event::FocusLost;
        assert!(matches!(
            from_crossterm_event(ct_event),
            Some(Event::FocusLost)
        ));
    }

    fn mouse_event_kind_of(
        kind: crossterm::event::MouseEventKind,
    ) -> retroglyph_core::event::MouseEventKind {
        from_crossterm_mouse_event_kind(kind)
    }

    #[test]
    fn mouse_down_and_up_still_map_after_option_signature_change() {
        use retroglyph_core::event::{MouseButton as B, MouseEventKind as K};

        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::Down(
                crossterm::event::MouseButton::Left
            )),
            K::Down(B::Left)
        );
        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::Up(
                crossterm::event::MouseButton::Right
            )),
            K::Up(B::Right)
        );
        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::Moved),
            K::Moved
        );
        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::ScrollUp),
            K::Scroll { dx: 0.0, dy: 1.0 }
        );
        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::ScrollDown),
            K::Scroll { dx: 0.0, dy: -1.0 }
        );
    }

    #[test]
    fn mouse_drag_preserves_which_button_is_held() {
        use retroglyph_core::event::{MouseButton as B, MouseEventKind as K};

        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::Drag(
                crossterm::event::MouseButton::Left
            )),
            K::Drag(B::Left)
        );
        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::Drag(
                crossterm::event::MouseButton::Right
            )),
            K::Drag(B::Right)
        );
        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::Drag(
                crossterm::event::MouseButton::Middle
            )),
            K::Drag(B::Middle)
        );
    }

    #[test]
    fn mouse_horizontal_scroll_round_trips() {
        use retroglyph_core::event::MouseEventKind as K;

        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::ScrollLeft),
            K::Scroll { dx: -1.0, dy: 0.0 }
        );
        assert_eq!(
            mouse_event_kind_of(crossterm::event::MouseEventKind::ScrollRight),
            K::Scroll { dx: 1.0, dy: 0.0 }
        );
    }

    #[test]
    fn detect_color_support_no_color_wins_over_everything_else() {
        use retroglyph_terminal::ColorSupport;

        assert_eq!(
            detect_color_support(Some("1"), Some("dumb")),
            ColorSupport::None
        );
        // Any non-empty value counts, per https://no-color.org.
        assert_eq!(
            detect_color_support(Some("anything"), None),
            ColorSupport::None
        );
    }

    #[test]
    fn detect_color_support_empty_no_color_does_not_count() {
        use retroglyph_terminal::ColorSupport;

        assert_eq!(
            detect_color_support(Some(""), None),
            ColorSupport::Truecolor
        );
    }

    #[test]
    fn detect_color_support_dumb_term_forces_none() {
        // The one $TERM value that's an unambiguous "assume nothing" signal: never emitted by
        // a terminal that actually supports color, unlike a "...256color" suffix (see the next
        // test).
        use retroglyph_terminal::ColorSupport;

        assert_eq!(detect_color_support(None, Some("dumb")), ColorSupport::None);
    }

    #[test]
    fn detect_color_support_falls_back_to_truecolor_with_no_signal() {
        // No `$NO_COLOR` and a `$TERM` that isn't the unambiguous "dumb" (or no `$TERM` at all,
        // as in a minimal CI/test harness): this must not be read as evidence of a limited
        // terminal, so it matches `TerminalRenderer`'s own `ColorSupport::default()` and this
        // crate's pre-existing always-truecolor behavior.
        use retroglyph_terminal::ColorSupport;

        assert_eq!(detect_color_support(None, None), ColorSupport::Truecolor);
        assert_eq!(
            detect_color_support(None, Some("xterm")),
            ColorSupport::Truecolor
        );
        // retroglyph#585 CI: this workspace's own PTY test harness spawns every example with
        // exactly this $TERM and no $COLORTERM. A `$TERM`-text heuristic that read "256color" as
        // a limit (rather than the common, often truecolor-capable default it is) silently
        // downgraded every snapshot test's rendered colors and broke all of them at once.
        assert_eq!(
            detect_color_support(None, Some("xterm-256color")),
            ColorSupport::Truecolor
        );
    }

    #[test]
    fn crossterm_options_color_support_override_is_used_verbatim() {
        use retroglyph_terminal::ColorSupport;

        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .color_support(ColorSupport::Indexed256)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        assert_eq!(term.color_support(), ColorSupport::Indexed256);
    }

    #[test]
    fn set_title_writes_the_osc_title_escape() {
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        term.set_title("my title").unwrap();

        let written = String::from_utf8(term.writer().clone()).unwrap();
        assert_eq!(written, "\x1B]0;my title\x07");
    }

    #[test]
    fn ring_bell_writes_the_bel_byte() {
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        term.ring_bell().unwrap();

        assert_eq!(term.writer().as_slice(), b"\x07");
    }

    #[test]
    fn set_cursor_style_queues_the_matching_decscusr_escape() {
        use retroglyph_core::backend::CursorStyle;

        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        let mut term = Crossterm::builder()
            .raw_mode(false)
            .alt_screen(false)
            .mouse_capture(false)
            .focus_change(false)
            .bracketed_paste(false)
            .kitty_protocol(false)
            .build_with_writer(Vec::new())
            .expect("building against a Vec<u8> writer with all TTY features disabled must not require a real terminal");

        term.set_cursor_style(CursorStyle::BlinkingBar);

        assert_eq!(term.writer().as_slice(), b"\x1b[5 q");
    }

    /// Wraps [`Crossterm`] so [`Observable::snapshot`] hashes only the bytes written since the
    /// previous call, per that trait's docs: this backend's observable state is an append-only
    /// escape-byte log, so "changed" means "appended", tracked here as a remembered offset into
    /// [`Crossterm::writer`] rather than by hashing the whole log every time.
    struct CrosstermObserver {
        term: Crossterm<Vec<u8>>,
        offset: usize,
    }

    impl CrosstermObserver {
        fn new(size: Size) -> Self {
            let mut term = Crossterm::builder()
                .raw_mode(false)
                .alt_screen(false)
                .mouse_capture(false)
                .focus_change(false)
                .bracketed_paste(false)
                .kitty_protocol(false)
                .build_with_writer(Vec::new())
                .expect(
                    "building against a Vec<u8> writer with all TTY features disabled must not require a real terminal",
                );
            // `resize` (now that it actually updates `cached_size`, see retroglyph#763) seeds
            // the size the conformance harness asked for; its own escape bytes are folded into
            // the initial offset below rather than showing up in the first measured delta.
            term.resize(size);
            let offset = term.writer().len();
            Self { term, offset }
        }
    }

    impl Output for CrosstermObserver {
        type Error = std::io::Error;

        fn draw_layers<'a, I>(&mut self, content: I) -> Result<(), Self::Error>
        where
            I: Iterator<Item = DrawCell<'a>>,
        {
            self.term.draw(content)
        }

        fn flush(&mut self) -> Result<(), Self::Error> {
            self.term.flush()
        }

        fn size(&self) -> Size {
            Output::size(&self.term)
        }

        fn clear(&mut self) -> Result<(), Self::Error> {
            Output::clear(&mut self.term)
        }

        fn resize(&mut self, size: Size) {
            Output::resize(&mut self.term, size);
        }
    }

    impl Cursor for CrosstermObserver {
        fn set_cursor_position(&mut self, position: Pos) {
            Cursor::set_cursor_position(&mut self.term, position);
        }

        fn set_cursor_style(&mut self, style: CursorStyle) {
            Cursor::set_cursor_style(&mut self.term, style);
        }
    }

    impl retroglyph_core::testing::conformance::Observable for CrosstermObserver {
        fn snapshot(&mut self) -> u64 {
            let bytes = self.term.writer();
            let delta = &bytes[self.offset..];
            let hash = retroglyph_core::testing::conformance::fnv1a(delta);
            self.offset = bytes.len();
            hash
        }
    }

    #[test]
    fn satisfies_the_output_contract() {
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        retroglyph_core::testing::conformance::assert_output_contract(CrosstermObserver::new);
    }

    #[test]
    #[ignore = "retroglyph#713: set_cursor_position doesn't resync the renderer's tracked cursor"]
    fn satisfies_the_cursor_contract() {
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        retroglyph_core::testing::conformance::assert_cursor_contract(CrosstermObserver::new);
    }

    #[test]
    fn satisfies_the_cursor_style_contract() {
        let _lock = TEST_GUARD_LOCK
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        retroglyph_core::testing::conformance::assert_cursor_style_contract(CrosstermObserver::new);
    }
}