retroglyph_core/terminal/

present.rs

//! Frame presentation: [`draw`](Terminal::draw), [`present`](Terminal::present), and
//! [`present_count`](Terminal::present_count).
//!
//! `present` is the one piece of `Terminal`'s API that has to reconcile three different backend
//! shapes (compositing vs. cell, single-layer vs. multi-layer) with the error-recovery contract
//! documented on it; its own doc comment and the tests below cover that matrix directly.

use alloc::vec::Vec;

use super::{LayerOp, Terminal};
use crate::backend::{Backend, Compositing, Output};
use crate::grid::{Grid, HasSize};
use crate::surface::Surface;

/// Which of `present`'s three dispatch paths a call takes, decided once up front from the same
/// `compositing()`/`max_layer()` inputs the branches below read, rather than discovered
/// branch-by-branch. Only [`Flattened`](Self::Flattened) leaves the flatten buffers holding this
/// frame's content; every other variant means the buffers were bypassed and are stale for next
/// time, which `present` derives from `path` directly instead of each branch remembering to say
/// so (see retroglyph#960, the shipped bug from that obligation being invisible).
#[derive(Clone, Copy)]
enum PresentPath {
    /// Backend composites the raw layered stream itself; `present` never touches the flatten
    /// buffers.
    Composited { needs_full_frame: bool },
    /// Only layer 0 is in play; diff the real grids directly rather than flatten an exact copy.
    SingleLayer,
    /// Multiple layers, non-compositing backend: flatten `current` into the scratch buffers and
    /// diff those.
    Flattened,
}

impl<B: Backend> Terminal<B> {
    /// Draws one frame: `f` gets a [`Surface`] scoped to the whole terminal on layer 0, then the
    /// frame is presented (see [`present`](Self::present)) once `f` returns.
    ///
    /// This is the common entry point for drawing: a caller that draws every frame regardless of
    /// whether anything changed calls this once per frame. A caller that only wants to redraw
    /// when its own state changed should gate the call to `draw` itself (e.g. `if
    /// state.changed() { term.draw(|s| render(s, &state))?; }`) rather than rely on `draw`/
    /// [`present`](Self::present) to no-op.
    ///
    /// # Errors
    ///
    /// Propagates errors from [`present`](Self::present).
    pub fn draw(&mut self, f: impl FnOnce(&mut Surface<'_>)) -> Result<(), <B as Output>::Error> {
        let area = self.area();
        let mut surface = Surface::new(&mut self.current, area, 0);
        f(&mut surface);
        self.present()
    }

    /// Number of times [`present`](Self::present) has been called so far.
    ///
    /// Wraps on overflow; intended for detecting whether `present` was called *at all* between two
    /// points in time (compare a saved count against the current one), not as a precise total.
    /// Embedding drivers (e.g. `retroglyph-window`'s windowed drivers) use this to decide whether
    /// application code already presented during a frame, so they can skip a redundant
    /// driver-side present.
    #[must_use]
    pub const fn present_count(&self) -> u64 {
        self.present_count
    }

    /// Layer ids with `op` currently pending, in ascending order.
    ///
    /// The single `u8::try_from` site for `pending_layer_ops`: see `present`'s own `# Panics`
    /// note for why it never actually panics.
    fn pending_layers(&self, op: LayerOp) -> impl Iterator<Item = u8> + '_ {
        self.pending_layer_ops
            .iter()
            .enumerate()
            .filter(move |&(_, &o)| o == op)
            .map(|(id, _)| u8::try_from(id).expect("layer table is indexed by u8 layer ids"))
    }

    /// Present the current frame: computes the diff against the previous frame, sends changed
    /// cells to the backend, flushes, then swaps buffers. Always presents unconditionally, even
    /// if nothing was drawn since the last call; most callers want [`draw`](Self::draw) instead
    /// of calling this directly.
    ///
    /// When the backend requires a full frame (see
    /// [`crate::backend::Compositing::PixelLayered`]'s `needs_full_frame` field), all cells from
    /// every allocated layer are sent rather than just the diff, so pixel-based backends can
    /// clear and redraw to avoid orphaned pixels from sub-cell offsets.
    ///
    /// After a present, the new current buffer is cleared so the next frame starts empty.
    /// Callers should not draw into a frame and skip presenting it: the next [`draw`](Self::draw)
    /// call starts from an empty grid regardless.
    ///
    /// # Immediate mode
    ///
    /// This is an immediate-mode API (the same trade [ratatui] makes): the
    /// current buffer is wiped after every present, so each frame must redraw
    /// its entire scene from scratch by default. [`retain_layer`](Self::retain_layer) is the
    /// escape hatch: it makes one specific layer's last-presented content stand in for a redraw,
    /// so the app can skip regenerating it. The diff only bounds what is sent to the backend
    /// (terminal or pixel I/O); it does not bound the CPU cost of your redraw, except for a
    /// layer marked via `retain_layer`.
    ///
    /// [ratatui]: https://docs.rs/ratatui
    ///
    /// # Panics
    ///
    /// Never panics in practice: `pending_layer_ops` is indexed by u8 layer id and grown only up
    /// to `idx + 1` for `idx = usize::from(layer_id)` in
    /// [`retain_layer`](Self::retain_layer)/[`drop_layer`](Self::drop_layer), so its length is
    /// always at most 256 and every index encountered here fits in u8.
    ///
    /// # Errors
    ///
    /// Propagates errors from the backend's [`draw_layers`](crate::backend::Output::draw_layers) or
    /// [`flush`](crate::backend::Output::flush) operations. Either failure returns before the
    /// current/previous buffers are swapped, so the cells from the failed frame stay marked
    /// dirty in `previous` and are resent the next time `present` succeeds. `current` is still
    /// cleared, same as on success, so the caller doesn't need to redraw anything to recover:
    /// just call `draw`/`present` again, and the next frame starts from an empty grid like any
    /// other.
    #[doc(alias = "flush")]
    #[doc(alias = "render")]
    pub fn present(&mut self) -> Result<(), <B as Output>::Error> {
        self.present_count = self.present_count.wrapping_add(1);
        let retained: Vec<u8> = self.pending_layers(LayerOp::Retain).collect();
        if !retained.is_empty() {
            // Overwrite each retained layer's (empty, never-drawn-this-frame) content in
            // `current` with `previous`'s, so the diff below finds no change on it: the backend
            // gets nothing to redraw, and the copy (a flat per-layer clone) is far cheaper than
            // whatever the app would have spent regenerating identical content. See
            // `retain_layer`'s doc for why this has to run before the diff rather than skip the
            // post-swap clear: `current` and `previous` alternate buffers every present, so
            // anything short of re-syncing from the authoritative `previous` here would desync
            // them again after a second consecutive retained frame.
            //
            // Uses `copy_layer_from` rather than `blit`: `blit` is a clipping/positioning copy
            // that degrades multi-cell spans to their text fallback and treats empty tiles as
            // transparent (an overlay, not a replacement), both wrong here, since a retained
            // layer is copied whole, at the same geometry, and must be indistinguishable from
            // what was presented last frame, whatever the app did or didn't draw into it this
            // frame (retroglyph#955, retroglyph#956).
            for id in retained {
                self.current.copy_layer_from(id, &self.previous);
                self.pending_layer_ops[usize::from(id)] = LayerOp::None;
            }
        }
        // Decided once, up front, from the same `compositing()`/`max_layer()` inputs the three
        // branches below read: see `PresentPath`'s docs for why this replaced each branch
        // separately remembering to mark the flatten buffers stale.
        let path = match self.backend.compositing() {
            Compositing::PixelLayered { needs_full_frame } => {
                PresentPath::Composited { needs_full_frame }
            }
            // Sticky-off, not sticky-on: layers are never deallocated on their own once written
            // (see `Grid`'s layer storage), so `max_layer()` never drops back to 0 on its own. A
            // terminal that ever draws to layer 1+, even for a single transient frame, stays on
            // `Flattened` for the rest of the process, unless it explicitly calls `drop_layer` on
            // every layer above 0 (retroglyph#1028).
            Compositing::CellFlattened
                if self.current.max_layer() == 0 && self.previous.max_layer() == 0 =>
            {
                PresentPath::SingleLayer
            }
            Compositing::CellFlattened => PresentPath::Flattened,
        };
        // The fallible part is scoped to this closure so both the success and error paths
        // below can clear `current` before returning: `current` is presentation-buffer state
        // for the *next* frame, not part of what makes the resend-on-retry behavior work (that
        // lives entirely in `previous`/`flattened_previous`, left untouched here), so clearing
        // it is safe unconditionally and keeps immediate mode's "next `draw` starts empty"
        // contract true even after a failed present.
        let result = (|| -> Result<(), <B as Output>::Error> {
            match path {
                PresentPath::Composited { needs_full_frame } => {
                    // Pixel/GPU backends composite the raw layered stream themselves.
                    if needs_full_frame {
                        let all = self.current.layers();
                        self.backend.draw_layers(all)?;
                    } else {
                        let diff = self.current.diff(&self.previous);
                        self.backend.draw_layers(diff)?;
                    }
                }
                PresentPath::SingleLayer => {
                    // Fast path: only layer 0 is in play, so flattening would be an exact
                    // copy of `current`. Diff the real grids directly and skip the
                    // flatten buffers entirely.
                    let diff = self.current.diff(&self.previous);
                    self.backend.draw_layers(diff)?;
                }
                PresentPath::Flattened => {
                    // Cell backends receive a pre-flattened, single-layer diff so layers
                    // 1+ appear everywhere, not just on pixel backends.
                    let size = self.current.size();
                    let flattened_current = self
                        .flattened_current
                        .get_or_insert_with(|| Grid::new(size.width(), size.height()));
                    let flattened_previous = self
                        .flattened_previous
                        .get_or_insert_with(|| Grid::new(size.width(), size.height()));
                    if self.flattened_stale {
                        // The previous frame took a different path, so `flattened_previous`
                        // is stale. Clear it to force a full redraw this frame.
                        flattened_previous.clear_all();
                    }
                    self.current.flatten_into(flattened_current);
                    let diff = flattened_current.diff(flattened_previous);
                    self.backend.draw_layers(diff)?;
                }
            }
            self.backend.flush()
        })();
        // Written here, unconditionally, rather than only on success: this has to update even
        // when draw/flush fails below, because a failed present still ran `path`'s branch (or
        // didn't run the flatten branch at all), and the next present's flatten-branch decision
        // must reflect that regardless of whether this frame's error propagates.
        self.flattened_stale = !matches!(path, PresentPath::Flattened);
        if let Err(err) = result {
            // `current` is cleared even on failure so the next frame still starts from an
            // empty grid; only the swap below is skipped. `previous`/`flattened_previous`
            // still hold the last confirmed frame, so the next `present`'s diff against them
            // resends the cells that never actually reached the backend instead of silently
            // dropping them.
            self.current.clear_all();
            return Err(err);
        }
        // Deallocate any layer `drop_layer` marked, now that the diff above (computed while the
        // layer was still allocated, if only as an already-cleared buffer) has told the backend
        // to erase whatever it last showed there. Also gated on `flush` succeeding, for the same
        // reason as the swaps below: on failure, `previous` must keep the layer allocated so a
        // retried `present` can still resend the erase that never actually reached the backend.
        let dropped: Vec<u8> = self.pending_layers(LayerOp::Drop).collect();
        for id in dropped {
            // If the app drew to `layer` again after calling `drop_layer` but before this
            // present, that write is a live redraw the app clearly wants kept, not stale content:
            // cancel the drop instead of discarding it.
            if self.current.layer_is_empty(id) {
                self.current.deallocate_layer(id);
                self.previous.deallocate_layer(id);
            }
            self.pending_layer_ops[usize::from(id)] = LayerOp::None;
        }
        // Both swaps happen only after `flush` succeeds, for the same reason described above.
        if matches!(path, PresentPath::Flattened) {
            core::mem::swap(&mut self.flattened_current, &mut self.flattened_previous);
        }
        core::mem::swap(&mut self.current, &mut self.previous);
        self.current.clear_all();
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::backend::{Cursor, DrawCell, Headless, Input};
    use crate::color::Color;
    use crate::color::Style;
    use crate::event::Event;
    use crate::grid::{Pos, Size};
    use alloc::vec::Vec;
    use core::time::Duration;

    /// Wraps [`Headless`] and fails the next [`flush`](Output::flush) or
    /// [`draw_layers`](Output::draw_layers) call once, then forwards everything (including a
    /// failed `draw_layers` call's content, which already reached the inner backend) as normal.
    /// Used to exercise `present`'s documented error-recovery contract: either failure must
    /// leave the frame's cells marked dirty so they are resent on the next successful `present`.
    ///
    /// Its `composites_layers` field is also configurable, so the same helper covers the
    /// compositing, flatten, and single-layer fast-path branches of `present`.
    ///
    /// `std`-only: its `Output::Error` is `std::io::Error`, purely as a convenient stand-in
    /// error type for this test.
    #[cfg(feature = "std")]
    struct FlushOnceFailing {
        inner: Headless,
        fail_next_flush: bool,
        fail_next_draw_layers: bool,
        composites_layers: bool,
        /// Number of cells received by the most recent `draw_layers` call, so tests can
        /// tell whether a frame's diff was actually sent, independent of `Headless`'s
        /// applied grid (which a real backend might not update until well after `flush`).
        last_draw_len: usize,
    }

    #[cfg(feature = "std")]
    impl FlushOnceFailing {
        fn new(width: u16, height: u16) -> Self {
            Self {
                inner: Headless::new(width, height),
                fail_next_flush: false,
                fail_next_draw_layers: false,
                composites_layers: false,
                last_draw_len: 0,
            }
        }
    }

    #[cfg(feature = "std")]
    impl Output for FlushOnceFailing {
        type Error = std::io::Error;

        fn draw_layers<'a, I>(&mut self, content: I) -> Result<(), Self::Error>
        where
            I: Iterator<Item = DrawCell<'a>>,
        {
            if self.fail_next_draw_layers {
                self.fail_next_draw_layers = false;
                return Err(std::io::Error::other("simulated draw_layers failure"));
            }
            let content: Vec<_> = content.collect();
            self.last_draw_len = content.len();
            // Infallible in `Headless`; map its error type to ours to keep the wrapper's
            // error type consistent across all `Output` methods.
            self.inner
                .draw_layers(content.into_iter())
                .map_err(|e| match e {})
        }

        fn flush(&mut self) -> Result<(), Self::Error> {
            if self.fail_next_flush {
                self.fail_next_flush = false;
                return Err(std::io::Error::other("simulated flush failure"));
            }
            self.inner.flush().map_err(|e| match e {})
        }

        fn size(&self) -> Size {
            self.inner.size()
        }

        fn clear(&mut self) -> Result<(), Self::Error> {
            self.inner.clear().map_err(|e| match e {})
        }

        fn compositing(&self) -> Compositing {
            if self.composites_layers {
                Compositing::PixelLayered {
                    needs_full_frame: false,
                }
            } else {
                Compositing::CellFlattened
            }
        }
    }

    #[cfg(feature = "std")]
    impl Input for FlushOnceFailing {
        fn poll_event(&mut self, timeout: Duration) -> Option<Event> {
            self.inner.poll_event(timeout)
        }
    }

    #[cfg(feature = "std")]
    impl Cursor for FlushOnceFailing {}

    #[test]
    fn test_draw_composites_layers_for_cell_backend() {
        // A cell backend (Headless) must see layers 1+ composited, not
        // dropped. Terrain on layer 0, entity on layer 1.
        let mut term = Terminal::new(Headless::new(3, 1));
        term.draw(|s| {
            s.put((0, 0), '.', Style::default());
            s.put((1, 0), '.', Style::default());
            s.on_layer(1).put((1, 0), '@', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(0, 0)].glyph(), '.');
        // Layer 1's glyph wins at (1, 0).
        assert_eq!(term.backend().grid()[Pos::new(1, 0)].glyph(), '@');
    }

    /// A `Compositing::PixelLayered` backend, the branch of `present` no real backend in this
    /// workspace's core tests exercises (`retroglyph-gl`/`retroglyph-software` test their own
    /// side of the [`Output`] contract, not `present`'s choice between it and a diff).
    /// `needs_full_frame` is fixed at construction, so one struct covers both dispatch modes.
    ///
    /// Unlike [`Headless`], this records the raw `(layer, pos, glyph)` cells it receives instead
    /// of writing them into a single flat grid: a real compositing backend interprets an
    /// unwritten (default/blank) cell on a higher layer as transparent, but `Headless::draw_layers`
    /// writes every cell it's handed literally to one shared grid regardless of layer, so replaying
    /// a raw multi-layer stream through it (rather than the pre-flattened stream the non-
    /// compositing path sends) does not reproduce correct compositing.
    struct CompositingBackend {
        size: Size,
        full_frame: bool,
        last_draw_cells: Vec<(u8, Pos, char)>,
    }

    impl CompositingBackend {
        fn new(width: u16, height: u16, full_frame: bool) -> Self {
            Self {
                size: Size::new(width, height),
                full_frame,
                last_draw_cells: Vec::new(),
            }
        }
    }

    impl Output for CompositingBackend {
        type Error = core::convert::Infallible;

        fn draw_layers<'a, I>(&mut self, content: I) -> Result<(), Self::Error>
        where
            I: Iterator<Item = DrawCell<'a>>,
        {
            self.last_draw_cells = content
                .map(|cell| (cell.layer, cell.pos, cell.tile.glyph()))
                .collect();
            Ok(())
        }

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

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

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

        fn compositing(&self) -> Compositing {
            Compositing::PixelLayered {
                needs_full_frame: self.full_frame,
            }
        }
    }

    impl Input for CompositingBackend {
        fn poll_event(&mut self, _timeout: Duration) -> Option<Event> {
            None
        }
    }

    impl Cursor for CompositingBackend {}

    #[test]
    fn test_composites_layers_diff_dispatches_only_changed_cells() {
        let mut term = Terminal::new(CompositingBackend::new(3, 1, false));
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.put((1, 0), 'b', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_cells.len(),
            2,
            "first frame: only the two written cells differ from the pre-allocated blank layer 0"
        );

        // Second, identical frame: nothing changed, so the compositing branch's diff half sends
        // nothing, same as the non-compositing diff path.
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.put((1, 0), 'b', Style::default());
        })
        .expect("draw failed");
        assert!(
            term.backend().last_draw_cells.is_empty(),
            "PixelLayered {{ needs_full_frame: false }} still dispatches only the diff"
        );
    }

    #[test]
    fn test_composites_layers_full_frame_dispatches_every_allocated_cell() {
        let mut term = Terminal::new(CompositingBackend::new(3, 1, true));
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.put((1, 0), 'b', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_cells.len(),
            3,
            "first frame: every cell in the sole allocated layer (width 3), not just the two \
             written ones"
        );

        // Second, identical frame: unlike the diff branch above, needs_full_frame: true actually
        // takes effect here, so the whole layer is resent rather than an empty diff.
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.put((1, 0), 'b', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_cells.len(),
            3,
            "PixelLayered {{ needs_full_frame: true }} resends every allocated cell on every present"
        );
    }

    /// A cell backend whose `compositing()` can be toggled between presents, standing in
    /// for a backend that degrades from pixel compositing to a cell path at runtime (retroglyph#960).
    struct TogglingCompositor {
        inner: Headless,
        composites: bool,
    }

    impl Output for TogglingCompositor {
        type Error = core::convert::Infallible;

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

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

        fn size(&self) -> Size {
            self.inner.size()
        }

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

        fn compositing(&self) -> Compositing {
            if self.composites {
                Compositing::PixelLayered {
                    needs_full_frame: false,
                }
            } else {
                Compositing::CellFlattened
            }
        }
    }

    impl Input for TogglingCompositor {
        fn poll_event(&mut self, timeout: Duration) -> Option<Event> {
            self.inner.poll_event(timeout)
        }
    }

    impl Cursor for TogglingCompositor {}

    #[test]
    fn present_marks_flatten_buffers_stale_after_a_composites_layers_present() {
        // A backend that ever answers `PixelLayered` from `compositing()` and later
        // `CellFlattened` must not leave `flattened_previous` holding a frame that was never
        // actually the last one presented. Sequence: flatten branch (establishes stale-looking
        // data) -> composites branch (bypasses the flatten buffers entirely) -> flatten branch
        // again, where the bug would incorrectly diff against the first frame's flattened data
        // instead of the second.
        let mut term = Terminal::new(TogglingCompositor {
            inner: Headless::new(3, 1),
            composites: false,
        });

        // Frame 1: flatten branch. Layer 1 is touched so `max_layer() != 0`, and
        // `compositing()` is `CellFlattened`, so this flattens and diffs normally.
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), '#', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'a');

        // Frame 2: composites branch. Bypasses the flatten buffers entirely, so
        // `flattened_previous` still holds frame 1's flattened content. Layer 1 is redrawn
        // identically to frame 1 so `Grid::diff` (now that it also reports a layer that stopped
        // being written, retroglyph#1018) sees no change there and doesn't emit anything for it;
        // `Headless::draw_layers` writes every cell to one shared grid regardless of layer (see
        // `CompositingBackend`'s docs above), so a real layer-1 diff would corrupt this frame's
        // single-grid glyph check, which is unrelated to what this test is verifying.
        term.backend_mut().composites = true;
        term.draw(|s| {
            s.put((0, 0), 'b', Style::default());
            s.on_layer(1).put((1, 0), '#', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'b');

        // Frame 3: back to the flatten branch. Draws 'a' at (0, 0) again, on layer 0, but with
        // layer 1 also touched so this lands in the flatten branch rather than the fast path.
        // 'a' matches what frame 1 left in `flattened_previous`, even though the real last
        // presented frame (frame 2) showed 'b' there. Without the fix, the stale match makes the
        // diff skip (0, 0), and the backend keeps showing frame 2's 'b' forever.
        term.backend_mut().composites = false;
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((2, 0), '@', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().inner.grid()[Pos::new(0, 0)].glyph(),
            'a',
            "flattened_previous must be cleared after a PixelLayered present, not diffed \
             against as if it were the last frame actually shown"
        );

        // `TogglingCompositor` forwards `clear` and `poll_event` unconditionally, same as every
        // other method on it, so exercise both here rather than leaving them as dead delegation.
        term.backend_mut().clear().expect("clear failed");
        term.backend_mut().inner.push_event(Event::Close);
        assert_eq!(term.poll(Duration::ZERO), Some(Event::Close));
    }

    #[test]
    fn test_draw_explicit_space_on_higher_layer_erases_and_sets_bg() {
        // An explicit space on a higher layer is opaque: it overwrites the
        // glyph beneath (erase) and applies its background. This is the
        // deliberate consequence of the explicit-EMPTY transparency model.
        let mut term = Terminal::new(Headless::new(2, 1));
        term.draw(|s| {
            s.put((0, 0), 'x', Style::default());
            s.on_layer(1).put((0, 0), ' ', Style::new().bg(Color::RED));
        })
        .expect("draw failed");
        let cell = term.backend().grid()[Pos::new(0, 0)];
        assert_eq!(cell.glyph(), ' ');
        assert_eq!(cell.style().background(), Color::RED);
    }

    #[test]
    fn test_draw_single_layer_fast_path_matches_backend() {
        // Only layer 0 is ever touched: the fast path must still deliver the
        // correct cells to a cell backend across multiple frames.
        let mut term = Terminal::new(Headless::new(3, 1));
        term.draw(|s| s.put((0, 0), 'a', Style::default()))
            .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(0, 0)].glyph(), 'a');

        // Immediate mode: redraw 'a' and add 'c'.
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.put((2, 0), 'c', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(term.backend().grid()[Pos::new(2, 0)].glyph(), 'c');

        // A cell that is not redrawn is erased (immediate mode).
        term.draw(|s| s.put((0, 0), 'a', Style::default()))
            .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(term.backend().grid()[Pos::new(2, 0)].glyph(), ' ');
    }

    #[test]
    fn test_present_transition_single_to_multi_layer() {
        // Start single-layer (fast path), then introduce layer 1. The frame
        // that adds the layer must composite correctly despite the fast path
        // having bypassed the flatten buffers.
        let mut term = Terminal::new(Headless::new(2, 1));
        term.draw(|s| {
            s.put((0, 0), '.', Style::default());
            s.put((1, 0), '.', Style::default());
        })
        .expect("draw failed");

        term.draw(|s| {
            s.put((0, 0), '.', Style::default());
            s.put((1, 0), '.', Style::default());
            s.on_layer(1).put((1, 0), '@', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(0, 0)].glyph(), '.');
        assert_eq!(term.backend().grid()[Pos::new(1, 0)].glyph(), '@');
    }

    #[test]
    fn test_present_transition_multi_to_single_to_multi_layer() {
        // The reverse of the transition above: multi-layer (flatten path) drops back to
        // single-layer (fast path, sets `flattened_stale`), then multi-layer again. The frame
        // that returns to multi-layer must see `flattened_previous` cleared rather than diffed
        // against the stale content the fast path bypassed, or the reintroduced layer's cells
        // would wrongly look unchanged.
        let mut term = Terminal::new(Headless::new(2, 1));
        term.draw(|s| {
            s.put((0, 0), '.', Style::default());
            s.on_layer(1).put((1, 0), '@', Style::default());
        })
        .expect("draw failed");

        // Single-layer frame: fast path, `flattened_stale` set.
        term.draw(|s| s.put((0, 0), '.', Style::default()))
            .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(1, 0)].glyph(), ' ');

        // Back to multi-layer: must composite correctly despite the intervening fast-path frame.
        term.draw(|s| {
            s.put((0, 0), '.', Style::default());
            s.on_layer(1).put((1, 0), '@', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(0, 0)].glyph(), '.');
        assert_eq!(term.backend().grid()[Pos::new(1, 0)].glyph(), '@');
    }

    #[cfg(feature = "std")]
    #[test]
    fn present_resends_cells_after_a_failed_flush_on_the_multi_layer_path() {
        // Two-layer terminal so `present` takes the flatten-buffer path (not the
        // single-layer fast path, which already handled this correctly).
        let mut term = Terminal::new(FlushOnceFailing::new(2, 1));

        term.backend_mut().fail_next_flush = true;
        let result = term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), 'b', Style::default());
        });
        assert!(result.is_err(), "flush was expected to fail this frame");
        assert_eq!(
            term.backend().last_draw_len,
            2,
            "the failed frame's diff should still have been sent to draw_layers"
        );

        // Same content, flush succeeds this time. If the flatten buffers had already been
        // swapped on the failed attempt, this diff would see "no change" and send nothing.
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), 'b', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_len,
            2,
            "both cells must be resent since neither ever reached the screen"
        );
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(term.backend().inner.grid()[Pos::new(1, 0)].glyph(), 'b');
    }

    #[cfg(feature = "std")]
    #[test]
    fn present_stale_flag_survives_a_failed_bypass_present() {
        // Pins the ordering risk from retroglyph#1395: the `flattened_stale` assignment sits
        // after the fallible closure but before the `if let Err` early return, so it updates even
        // when the present that bypassed the flatten buffers fails. If it were only reachable on
        // the success path instead, this test would fail: `flattened_stale` would stay `false`
        // (left over from frame 1) into frame 3, which would then wrongly diff against
        // `flattened_previous`'s frame-1 content instead of clearing it for a full redraw.
        //
        // Sequence: flatten (ok, establishes `flattened_previous`) -> compositing bypass (flush
        // fails, but still must mark `flattened_stale`) -> flatten again, which must see the
        // staleness and do a full redraw rather than diff against frame 1's stale data.
        let mut term = Terminal::new(FlushOnceFailing::new(2, 1));

        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), '#', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'a');

        // Compositing bypass path (`Compositing::PixelLayered`), and the flush fails.
        term.backend_mut().composites_layers = true;
        term.backend_mut().fail_next_flush = true;
        let result = term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), '#', Style::default());
        });
        assert!(result.is_err(), "flush was expected to fail this frame");

        // Back to the flatten path. Draws 'a' at (0, 0) again, matching what `flattened_previous`
        // still holds from frame 1 (the compositing frame bypassed the flatten buffers entirely,
        // whether or not it failed). Without `flattened_stale` surviving the failed present, this
        // would wrongly look unchanged and skip sending (0, 0).
        term.backend_mut().composites_layers = false;
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), '@', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_len,
            2,
            "a full redraw is expected: (0, 0) resent despite matching flattened_previous's \
             stale content, plus the changed (1, 0)"
        );
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(term.backend().inner.grid()[Pos::new(1, 0)].glyph(), '@');
    }

    #[cfg(feature = "std")]
    #[test]
    fn present_resends_cells_after_a_failed_draw_layers_on_the_multi_layer_path() {
        // `draw_layers` is the other documented early return in `present`: it must leave
        // `previous`/`flattened_previous` untouched, same as a failed `flush`, so the next
        // `present` resends everything rather than silently dropping it.
        let mut term = Terminal::new(FlushOnceFailing::new(2, 1));

        term.backend_mut().fail_next_draw_layers = true;
        let result = term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), 'b', Style::default());
        });
        assert!(
            result.is_err(),
            "draw_layers was expected to fail this frame"
        );
        assert_eq!(
            term.backend().last_draw_len,
            0,
            "a failed draw_layers call never recorded any content on the wrapper"
        );

        // Same content, draw_layers succeeds this time.
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), 'b', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_len,
            2,
            "both cells must be resent since neither ever reached the screen"
        );
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(term.backend().inner.grid()[Pos::new(1, 0)].glyph(), 'b');
    }

    #[cfg(feature = "std")]
    #[test]
    fn present_resends_cells_after_a_failed_flush_on_the_single_layer_fast_path() {
        // Only layer 0 is ever touched, so `present` takes the fast path that diffs the raw
        // grids directly, skipping the flatten buffers entirely.
        let mut term = Terminal::new(FlushOnceFailing::new(2, 1));

        term.backend_mut().fail_next_flush = true;
        let result = term.draw(|s| s.put((0, 0), 'a', Style::default()));
        assert!(result.is_err(), "flush was expected to fail this frame");
        assert_eq!(
            term.backend().last_draw_len,
            1,
            "the failed frame's diff should still have been sent to draw_layers"
        );

        // Nothing drawn this time: if the fast path's diff had already been swapped forward on
        // the failed attempt, this frame would see no change and resend nothing.
        term.draw(|s| s.put((0, 0), 'a', Style::default()))
            .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_len,
            1,
            "the cell must be resent since it never reached the screen"
        );
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'a');
    }

    #[cfg(feature = "std")]
    #[test]
    fn present_failure_does_not_leak_the_failed_frames_content_into_the_next_frame() {
        // Single-layer terminal so `present` takes the fast path, matching the issue's repro.
        let mut term = Terminal::new(FlushOnceFailing::new(3, 1));

        term.backend_mut().fail_next_flush = true;
        let result = term.draw(|s| s.put((2, 0), 'X', Style::default()));
        assert!(result.is_err(), "flush was expected to fail this frame");

        // Next frame redraws different content and never touches (2, 0). `previous` is still
        // empty (the swap was skipped), so if `current` had also been left holding the failed
        // frame's 'X' (the bug), the diff below would see (2, 0) as newly changed from empty
        // to 'X' and needlessly resend it, on top of the one cell this frame actually drew.
        term.draw(|s| s.put((0, 0), 'A', Style::default()))
            .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_len,
            1,
            "only the redrawn cell should be sent; the failed frame's 'X' must not leak back in"
        );
        assert_eq!(term.backend().inner.grid()[Pos::new(0, 0)].glyph(), 'A');
    }

    #[cfg(feature = "std")]
    #[test]
    fn present_resends_cells_after_a_failed_flush_on_the_compositing_path() {
        // `Compositing::PixelLayered` takes `present`'s first branch entirely, bypassing both
        // the fast path and the flatten buffers; a failed flush there must still leave `previous`
        // untouched so the raw per-layer diff is resent.
        let mut term = Terminal::new(FlushOnceFailing::new(2, 1));
        term.backend_mut().composites_layers = true;

        // Layer 1 is newly allocated this frame, so its diff against an absent previous layer
        // includes every cell in its width (see `Grid::diff`'s "newly allocated layer" case), not
        // just the one actually written; layer 0 contributes only its one real change.
        term.backend_mut().fail_next_flush = true;
        let result = term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), 'b', Style::default());
        });
        assert!(result.is_err(), "flush was expected to fail this frame");
        assert_eq!(
            term.backend().last_draw_len,
            3,
            "the failed frame's diff should still have been sent to draw_layers"
        );

        // Same content, flush succeeds this time. If `previous` had already been swapped forward
        // on the failed attempt, layer 1 would no longer be "newly allocated" and this diff would
        // shrink to just the real changes instead of resending the same content.
        term.draw(|s| {
            s.put((0, 0), 'a', Style::default());
            s.on_layer(1).put((1, 0), 'b', Style::default());
        })
        .expect("draw failed");
        assert_eq!(
            term.backend().last_draw_len,
            3,
            "the same diff must be resent since it never reached the screen"
        );
    }

    #[test]
    fn test_present_untouched_higher_layer_is_transparent() {
        // A higher layer that was allocated but not written at this cell must
        // not disturb the lower layer's glyph or background.
        let mut term = Terminal::new(Headless::new(2, 1));
        term.draw(|s| {
            s.put((0, 0), 'x', Style::default());
            // Allocate layer 1 by writing elsewhere, leaving (0, 0) empty.
            s.on_layer(1).put((1, 0), 'y', Style::default());
        })
        .expect("draw failed");
        assert_eq!(term.backend().grid()[Pos::new(0, 0)].glyph(), 'x');
    }

    #[test]
    fn test_terminal_present_count_advances_once_per_present_call() {
        let mut term = Terminal::new(Headless::new(2, 1));
        assert_eq!(term.present_count(), 0);

        term.draw(|_| {}).expect("draw failed"); // `draw` always presents.
        assert_eq!(term.present_count(), 1);

        term.present().expect("present failed");
        assert_eq!(term.present_count(), 2);

        term.present().expect("present failed");
        assert_eq!(term.present_count(), 3);
    }
}