eger 1.2.0

//! Per-cell (pixel-level) ANSI coloring and animation for **any** already
//! rendered block of ASCII text — a static image conversion, a decoded
//! GIF/video frame, or plain block-letter banner text — as opposed to
//! single-line text animations or block-letter banners, which only color a
//! single line or a banner's own generated glyphs.
//!
//! Where single-line text animations assign one color per *character*
//! of a line, and block-letter banners assign one color per *source
//! character* of a banner (applied across that character's whole glyph),
//! [`PixelAnimation`] assigns one color per *grid cell* (column `x`, row
//! `y`) of arbitrary ASCII art. That makes it work identically whether the
//! art came from [`crate::banner::banner_lines`], an `iascii` image
//! conversion ([`colorize_grid`]/[`colorize_grid_frames`]), a decoded GIF
//! frame ([`colorize_sequence`], e.g. from [`crate::image::gif_to_lines`]),
//! or already-rendered video frames ([`colorize_joined_sequence`], e.g.
//! from `video::render_video_frames` with
//! `video::ColorMode::Plain`) — all of these are ultimately just
//! rows of characters, and this module only ever looks at that.
//!
//! Built-in styles ([`PixelAnimation::Rainbow`], [`PixelAnimation::Wave`],
//! [`PixelAnimation::Pulse`], [`PixelAnimation::Blink`],
//! [`PixelAnimation::Plasma`], [`PixelAnimation::Ripple`]) all boil down to a
//! `(x, y, frame) -> Rgb` function evaluated per cell.
//! [`PixelAnimation::Custom`] lets you supply that function yourself —
//! including a purely mathematical one (your own sine mixes, radial
//! gradients, noise, cellular automata, whatever `x`/`y`/`frame` can
//! drive) — for effects the built-ins don't cover. [`PixelAnimation::Plasma`] and
//! [`PixelAnimation::Ripple`] are themselves just built-in examples of that: nothing they
//! do can't also be written as a [`PixelAnimation::custom`] closure.
//!
//! Every built-in only ever needs `+`, `*`, `sin`/`sqrt`/`rem_euclid`, so a
//! [`PixelAnimation::Custom`] closure can freely mix in whatever other math
//! it wants (noise functions, distance fields, lookup tables, ...) without
//! needing any support from this module beyond the `(x, y, frame, ch)`
//! it's called with.
//!
//! Coloring skips whitespace cells (a space stays a plain, unescaped
//! space) rather than wrapping every blank cell in its own ANSI
//! reset/color pair — that keeps output size down and avoids painting a
//! colored "background" over what is, in ASCII art, usually meant to be
//! empty space.
//!
//! # Performance
//!
//! Adjacent (including across a row boundary) same-color cells are merged
//! into a single escape/reset pair rather than one pair per cell, and each
//! distinct color's escape string is computed once per frame and reused —
//! see [`colorize_lines`]'s implementation note. Generating many frames
//! ([`colorize_frames`], [`colorize_grid_frames`], [`colorize_sequence`],
//! [`colorize_joined_sequence`]) is parallelized across frames with Rayon,
//! unconditionally, the same "across independent units of work" kind of
//! parallelism [`crate::image::render_batch_parallel`] and
//! `video::stream_video_frames` already use elsewhere in this
//! crate — no feature flag needed.

use crate::rgb::{hsv_to_rgb, Rgb};
use rayon::prelude::*;
use std::collections::HashMap;
use std::sync::Arc;

/// A per-cell color function: given a cell's column (`x`), row (`y`), the
/// current animation frame index, and the character occupying that cell,
/// returns the color to draw it in.
///
/// `ch` is passed through (rather than requiring the closure to be
/// generated from a fixed grid up front) so a function can, for example,
/// color a particular character differently from the rest — most
/// position/time-only effects simply ignore it.
pub type ColorFn = Arc<dyn Fn(usize, usize, u64, char) -> Rgb + Send + Sync>;

/// A per-cell color animation applied over an existing block of plain
/// (uncolored) ASCII text. See the module docs for how this differs from
/// [`crate::text::TextAnimation`]/[`crate::banner`]'s per-character
/// coloring.
#[derive(Clone)]
pub enum PixelAnimation {
    /// A hue sweep across both axes: `hue` depends on `frame` plus a
    /// per-cell offset along `x` and `y`, so the rainbow band visibly
    /// moves across the art over time instead of every cell cycling in
    /// lockstep. `speed` is degrees of hue shift per frame.
    Rainbow { speed: f32 },
    /// A brightness band sweeps left-to-right across the art against
    /// `base_color` — the same math as
    /// [`crate::text::TextAnimation::Wave`], extended from one line to a
    /// whole grid (every row sees the same horizontal sweep).
    Wave { base_color: Rgb },
    /// The whole grid breathes between dim and full brightness together
    /// (every cell shares one global brightness curve).
    Pulse { base_color: Rgb },
    /// Alternates every other frame between two flat colors.
    Blink { on_color: Rgb, off_color: Rgb },
    /// Classic demoscene "plasma": a sum of sine waves over `x`, `y`, and
    /// time, mapped onto hue. Purely mathematical, needs no base color.
    /// `scale` sets the spatial frequency (smaller = larger color blobs);
    /// `speed` sets how fast it animates.
    Plasma { scale: f32, speed: f32 },
    /// Concentric rings of brightness expanding outward from the grid's
    /// center against `base_color`; another purely math-driven built-in,
    /// provided as a second worked example alongside [`PixelAnimation::Plasma`]. `speed`
    /// controls how fast the rings travel outward.
    Ripple { base_color: Rgb, speed: f32 },
    /// A static (time-independent) linear gradient between `from` and
    /// `to`, sweeping left-to-right if `horizontal` is `true` or
    /// top-to-bottom otherwise. Unlike the other built-ins this ignores
    /// `frame` entirely — it's the simplest possible
    /// [`Rgb::mix`]-based effect, provided as a ready-made built-in for
    /// the common "just tint this art between two brand colors" case
    /// instead of requiring a [`PixelAnimation::custom`] closure for it.
    Gradient {
        from: Rgb,
        to: Rgb,
        horizontal: bool,
    },
    /// Wraps `base` and applies `transform` (see `ColorTransform` in the
    /// `color` module) to whatever color `base` would
    /// have produced for that cell — so, for example, a rainbow wrapped
    /// with `Saturate(0.4)` is a desaturated rainbow sweep, without
    /// needing a bespoke "desaturated rainbow" variant. Composes with any
    /// other `PixelAnimation`, including another `Transformed`.
    ///
    /// Requires the `color` feature (for the transform type).
    #[cfg(feature = "color")]
    Transformed {
        base: Box<PixelAnimation>,
        transform: crate::color::ColorTransform,
    },
    /// A user-supplied [`ColorFn`] — see [`PixelAnimation::custom`].
    Custom(ColorFn),
}

impl PixelAnimation {
    /// Wraps a closure as [`PixelAnimation::Custom`]. The closure receives
    /// `(x, y, frame_index, ch)` for every non-space cell and returns that
    /// cell's color; use ordinary floating-point math over `x`/`y`/`frame`
    /// for anything from a simple linear gradient to arbitrary generative
    /// patterns.
    ///
    /// ```
    /// use eger::colorize::PixelAnimation;
    /// use eger::Rgb;
    ///
    /// // A diagonal gradient from red (top-left) to blue (bottom-right),
    /// // static in time (ignores `frame`).
    /// let gradient = PixelAnimation::custom(|x, y, _frame, _ch| {
    ///     let t = ((x + y) as f32 / 40.0).clamp(0.0, 1.0);
    ///     Rgb::new((255.0 * (1.0 - t)) as u8, 0, (255.0 * t) as u8)
    /// });
    /// ```
    pub fn custom(f: impl Fn(usize, usize, u64, char) -> Rgb + Send + Sync + 'static) -> Self {
        Self::Custom(Arc::new(f))
    }
}

/// Evaluates `animation` at one cell. `width`/`height` are the bounding
/// box of the art being colored, needed by animations (like [`PixelAnimation::Ripple`])
/// whose math depends on the grid's overall size, not just one cell's
/// coordinates.
///
/// This is the per-cell entry point behind [`colorize_lines`]; it is also
/// public so realtime consumers (e.g. `Canvas::apply_animation`, when the
/// `canvas` feature is on) can drive any animation over their own buffers
/// without going through a text round-trip.
///
/// [`PixelAnimation::Ripple`]: PixelAnimation::Ripple
pub fn animation_color(
    animation: &PixelAnimation,
    x: usize,
    y: usize,
    frame: u64,
    ch: char,
    width: usize,
    height: usize,
) -> Rgb {
    pixel_color(animation, x, y, frame, ch, width, height)
}

/// Evaluates `animation` at one cell. `width`/`height` are the bounding
/// box of the art being colored, needed by animations (like [`PixelAnimation::Ripple`])
/// whose math depends on the grid's overall size, not just one cell's
/// coordinates.
///
/// [`PixelAnimation::Ripple`]: PixelAnimation::Ripple
pub(crate) fn pixel_color(
    animation: &PixelAnimation,
    x: usize,
    y: usize,
    frame: u64,
    ch: char,
    width: usize,
    height: usize,
) -> Rgb {
    match animation {
        PixelAnimation::Rainbow { speed } => {
            let hue = (frame as f32 * speed + x as f32 * 6.0 + y as f32 * 10.0) % 360.0;
            hsv_to_rgb(hue, 1.0, 1.0)
        }
        PixelAnimation::Wave { base_color } => {
            let span = (width as i64 + 8).max(1);
            let pos = (frame as i64) % span;
            let dist = (x as i64 - pos).unsigned_abs() as f32;
            let brightness = (1.0 - (dist / 4.0).min(1.0)).max(0.15);
            base_color.scale(brightness)
        }
        PixelAnimation::Pulse { base_color } => {
            let t = frame as f32 * 0.35;
            let brightness = (0.5 + 0.5 * t.sin()).clamp(0.15, 1.0);
            base_color.scale(brightness)
        }
        PixelAnimation::Blink {
            on_color,
            off_color,
        } => {
            if frame % 2 == 0 {
                *on_color
            } else {
                *off_color
            }
        }
        PixelAnimation::Plasma { scale, speed } => {
            let t = frame as f32 * speed;
            let fx = x as f32 * scale;
            let fy = y as f32 * scale;
            let v = (fx + t).sin()
                + (fy + t).sin()
                + (fx + fy + t).sin()
                + ((fx * fx + fy * fy).sqrt() - t).sin();
            // `v` ranges over roughly [-4, 4]; spread it across the full
            // hue wheel and let `rem_euclid` fold negative values back
            // into `0..360` instead of clamping/discarding them.
            let hue = (v * 45.0).rem_euclid(360.0);
            hsv_to_rgb(hue, 1.0, 1.0)
        }
        PixelAnimation::Ripple { base_color, speed } => {
            let cx = width as f32 / 2.0;
            let cy = height as f32 / 2.0;
            let dist = ((x as f32 - cx).powi(2) + (y as f32 - cy).powi(2)).sqrt();
            let phase = dist * 0.5 - frame as f32 * speed;
            let brightness = (0.5 + 0.5 * phase.sin()).clamp(0.15, 1.0);
            base_color.scale(brightness)
        }
        PixelAnimation::Gradient {
            from,
            to,
            horizontal,
        } => {
            let t = if *horizontal {
                if width <= 1 {
                    0.0
                } else {
                    x as f32 / (width - 1) as f32
                }
            } else if height <= 1 {
                0.0
            } else {
                y as f32 / (height - 1) as f32
            };
            from.mix(*to, t)
        }
        #[cfg(feature = "color")]
        PixelAnimation::Transformed { base, transform } => {
            let color = pixel_color(base, x, y, frame, ch, width, height);
            transform.apply(color)
        }
        PixelAnimation::Custom(f) => f(x, y, frame, ch),
    }
}

/// Colors one frame of `lines` (plain, uncolored rows of characters —
/// e.g. from [`crate::banner::banner_lines`], [`crate::render::plain_string`]
/// split on `\n`, or [`crate::render::grid_to_lines`] with `depth: None`)
/// under `animation` at animation frame `frame`, returning a single
/// `\n`-joined ANSI string (the same convention [`crate::render::grid_to_string`]
/// uses).
///
/// Cells holding a space are left as a plain, unescaped space rather than
/// being wrapped in a color/reset pair — see the module docs. Generic over
/// `S: AsRef<str>` so callers already holding borrowed `&str` rows (e.g.
/// [`colorize_joined_sequence`] splitting one big `String` on `\n`) don't
/// have to clone them into owned `String`s just to call this.
pub fn colorize_lines<S: AsRef<str>>(
    lines: &[S],
    animation: &PixelAnimation,
    frame: u64,
) -> String {
    let (width, height) = line_dims(lines);
    colorize_lines_with_dims(lines, width, height, animation, frame)
}

/// The actual per-frame coloring work, taking `width`/`height` as inputs
/// instead of recomputing them — [`colorize_frames`]/[`colorize_grid_frames`]
/// compute them once for `lines` and reuse them across every generated
/// frame, since `lines` (and therefore its dimensions) doesn't change
/// frame to frame in either of those.
///
/// Adjacent same-color cells — including across a row boundary, since
/// ANSI color state isn't reset by a bare `\n` in any real terminal — are
/// merged into a single `escape .. reset` pair instead of one pair per
/// cell, and every distinct color's escape string is computed once per
/// call and reused (`colors` cache) rather than reformatted on every
/// occurrence. For a mostly-uniform-color frame (`Pulse`, `Blink`, ...)
/// this collapses what would otherwise be one escape pair per non-space
/// cell down to a small handful for the entire frame.
fn colorize_lines_with_dims<S: AsRef<str>>(
    lines: &[S],
    width: usize,
    height: usize,
    animation: &PixelAnimation,
    frame: u64,
) -> String {
    // Rough capacity: glyph cells plus a modest allowance for the
    // relatively small number of `\x1b[38;2;r;g;bm` / `\x1b[0m` escapes
    // this now actually emits, now that runs are merged rather than
    // repeated per cell.
    let mut out: Vec<u8> = Vec::with_capacity(height * (width + 1) + 64);
    let mut colors: HashMap<Rgb, Vec<u8>> = HashMap::new();
    let mut run_color: Option<Rgb> = None;

    for (y, line) in lines.iter().enumerate() {
        if y > 0 {
            out.push(b'\n');
        }
        for (x, ch) in line.as_ref().chars().enumerate() {
            if ch == ' ' {
                if run_color.take().is_some() {
                    out.extend_from_slice(b"\x1b[0m");
                }
                out.push(b' ');
                continue;
            }
            let color = pixel_color(animation, x, y, frame, ch, width, height);
            if run_color != Some(color) {
                if run_color.is_some() {
                    out.extend_from_slice(b"\x1b[0m");
                }
                let escape = colors.entry(color).or_insert_with(|| {
                    let mut e = Vec::with_capacity(19);
                    crate::fast_ansi::push_truecolor_escape(&mut e, color.0, color.1, color.2);
                    e
                });
                out.extend_from_slice(escape);
                run_color = Some(color);
            }
            crate::fast_ansi::push_char(&mut out, ch);
        }
    }
    if run_color.is_some() {
        out.extend_from_slice(b"\x1b[0m");
    }
    // Safe: escapes are ASCII and glyphs are pushed as valid UTF-8.
    unsafe { String::from_utf8_unchecked(out) }
}

fn line_dims<S: AsRef<str>>(lines: &[S]) -> (usize, usize) {
    let width = lines
        .iter()
        .map(|l| l.as_ref().chars().count())
        .max()
        .unwrap_or(0);
    (width, lines.len())
}

/// Generates `frames` animated frames of the *same* static `lines`,
/// analogous to [`crate::banner::banner_frames`] but for arbitrary ASCII
/// art instead of banner glyphs — use this to animate the color of a
/// single static image conversion, a banner, or any other one-shot piece
/// of ASCII art over time.
///
/// For art whose *content* is already changing frame to frame (a decoded
/// GIF or video), use [`colorize_sequence`]/[`colorize_joined_sequence`]
/// instead, which recolor each already-distinct frame using its own
/// position in the sequence as the time input.
///
/// Frames are generated in parallel with Rayon (unconditional, like
/// [`crate::image::render_batch_parallel`]/`video::stream_video_frames`'s
/// own across-frame parallelism — no feature flag needed, since every
/// frame here is an independent, read-only computation over the same
/// `lines`).
pub fn colorize_frames<S: AsRef<str> + Sync>(
    lines: &[S],
    animation: &PixelAnimation,
    frames: u64,
) -> Vec<String> {
    let (width, height) = line_dims(lines);
    (0..frames)
        .into_par_iter()
        .map(|i| colorize_lines_with_dims(lines, width, height, animation, i))
        .collect()
}

/// Extracts an `iascii::grid::Grid`'s characters as plain (uncolored)
/// rows, discarding any per-cell color `iascii` itself computed from pixel
/// luminance/color — the starting point for driving a grid's color
/// entirely from a [`PixelAnimation`] instead.
fn grid_plain_lines(grid: &iascii::grid::Grid) -> Vec<String> {
    // Mirrors `crate::render::plain_string`'s own row/cell iteration
    // exactly (rather than assuming `Grid::rows()`'s row type exposes an
    // `.iter()` of its own), just collecting each row into a `String`
    // instead of one big newline-joined blob.
    grid.rows()
        .map(|row| {
            let mut line = String::new();
            for cell in row {
                line.push(cell.ch);
            }
            line
        })
        .collect()
}

/// [`colorize_lines`] for an `iascii` [`Grid`](iascii::grid::Grid) directly
/// — e.g. the output of `image::convert` for a single image — so
/// a static image's ASCII art can be colored/animated by a
/// [`PixelAnimation`] instead of (or as well as) `iascii`'s own
/// pixel-luminance coloring.
pub fn colorize_grid(grid: &iascii::grid::Grid, animation: &PixelAnimation, frame: u64) -> String {
    colorize_lines(&grid_plain_lines(grid), animation, frame)
}

/// [`colorize_frames`] for an `iascii` [`Grid`](iascii::grid::Grid) — the
/// natural way to turn one converted image into an animated banner-style
/// piece: convert it once, then animate its color over as many frames as
/// you like without re-converting.
pub fn colorize_grid_frames(
    grid: &iascii::grid::Grid,
    animation: &PixelAnimation,
    frames: u64,
) -> Vec<String> {
    colorize_frames(&grid_plain_lines(grid), animation, frames)
}

/// Recolors a sequence of already-decoded, *already content-animated*
/// ASCII frames — e.g. the `Vec<String>` rows of each GIF frame from
/// [`crate::image::gif_to_lines`] (`frames.iter().map(|(lines, _)| lines)`)
/// — using `animation`, where each frame's position in `frames` is used as
/// its animation frame index. That keeps the color animation in sync with
/// the sequence's own timeline instead of restarting the color animation
/// from frame 0 on every call. Frames are recolored in parallel (see
/// [`colorize_frames`]'s docs on why that needs no feature flag here).
pub fn colorize_sequence(frames: &[Vec<String>], animation: &PixelAnimation) -> Vec<String> {
    frames
        .par_iter()
        .enumerate()
        .map(|(i, lines)| colorize_lines(lines, animation, i as u64))
        .collect()
}

/// Same as [`colorize_sequence`], but for frames already joined into one
/// `\n`-separated `String` per frame — the shape
/// `video::render_video_frames`/`video::stream_video_frames`
/// return, and the shape to ask for via
/// `video::ColorMode::Plain` when you want a [`PixelAnimation`],
/// not `iascii`'s own pixel coloring, driving a video's ASCII output.
///
/// Each frame's `\n`-separated rows are split into borrowed `&str` slices
/// rather than cloned into owned `String`s before coloring — a `String`
/// per row was pure overhead, since [`colorize_lines`] never needed to own
/// them in the first place.
pub fn colorize_joined_sequence(frames: &[String], animation: &PixelAnimation) -> Vec<String> {
    frames
        .par_iter()
        .enumerate()
        .map(|(i, frame)| {
            let lines: Vec<&str> = frame.lines().collect();
            colorize_lines(&lines, animation, i as u64)
        })
        .collect()
}

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

    fn block(rows: &[&str]) -> Vec<String> {
        rows.iter().map(|r| r.to_string()).collect()
    }

    #[test]
    fn spaces_are_never_wrapped_in_color_escapes() {
        let lines = block(&["# #", " # "]);
        let out = colorize_lines(&lines, &PixelAnimation::Rainbow { speed: 10.0 }, 0);
        // Every space in the original stays a bare space in the output —
        // i.e. no "\x1b[...m \x1b[0m" pair was emitted for it.
        assert!(!out.contains("m \x1b[0m"));
    }

    #[test]
    fn rainbow_colors_every_non_space_cell_and_resets_after_each() {
        let lines = block(&["##", "##"]);
        let out = colorize_lines(&lines, &PixelAnimation::Rainbow { speed: 5.0 }, 2);
        assert_eq!(
            out.matches("\x1b[38;2;").count(),
            4,
            "one color per '#' cell"
        );
        assert_eq!(out.matches("\x1b[0m").count(), 4);
    }

    #[test]
    fn blink_alternates_between_the_two_configured_colors_by_frame() {
        let lines = block(&["#"]);
        let animation = PixelAnimation::Blink {
            on_color: Rgb::new(255, 0, 0),
            off_color: Rgb::new(0, 0, 255),
        };
        assert!(colorize_lines(&lines, &animation, 0).contains("38;2;255;0;0"));
        assert!(colorize_lines(&lines, &animation, 1).contains("38;2;0;0;255"));
    }

    #[test]
    fn colorize_frames_generates_the_requested_number_of_frames() {
        let lines = block(&["###"]);
        let frames = colorize_frames(
            &lines,
            &PixelAnimation::Plasma {
                scale: 0.3,
                speed: 0.2,
            },
            6,
        );
        assert_eq!(frames.len(), 6);
        for frame in &frames {
            assert!(frame.contains("\x1b[38;2;"));
        }
    }

    #[test]
    fn custom_closure_receives_the_expected_coordinates_and_character() {
        let lines = block(&["ab"]);
        let seen = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let recorder = seen.clone();
        let animation = PixelAnimation::custom(move |x, y, frame, ch| {
            recorder.lock().unwrap().push((x, y, frame, ch));
            Rgb::WHITE
        });
        colorize_lines(&lines, &animation, 7);
        let calls = seen.lock().unwrap();
        assert_eq!(&*calls, &[(0, 0, 7, 'a'), (1, 0, 7, 'b')]);
    }

    #[test]
    fn colorize_sequence_uses_each_frames_own_index_as_animation_time() {
        // A Blink animation alternates by parity of the frame index, so
        // consecutive sequence entries (indices 0 and 1) must land on
        // opposite colors even though each is colorized independently.
        let animation = PixelAnimation::Blink {
            on_color: Rgb::new(255, 0, 0),
            off_color: Rgb::new(0, 0, 255),
        };
        let frames = vec![block(&["#"]), block(&["#"])];
        let out = colorize_sequence(&frames, &animation);
        assert!(out[0].contains("38;2;255;0;0"));
        assert!(out[1].contains("38;2;0;0;255"));
    }

    #[test]
    fn colorize_joined_sequence_splits_on_newlines_before_recoloring() {
        let animation = PixelAnimation::Blink {
            on_color: Rgb::new(255, 0, 0),
            off_color: Rgb::new(0, 0, 255),
        };
        let frames = vec!["##\n##".to_string(), "##\n##".to_string()];
        let out = colorize_joined_sequence(&frames, &animation);
        assert_eq!(out.len(), 2);
        assert!(out[0].lines().count() == 2);
        assert!(out[0].contains("38;2;255;0;0"));
        assert!(out[1].contains("38;2;0;0;255"));
    }

    #[test]
    fn adjacent_and_cross_row_same_color_cells_share_one_escape_pair() {
        // A custom animation that always returns the same color regardless
        // of position should collapse an entire multi-row, multi-column
        // frame into exactly one open + one reset (color state persists
        // across a bare '\n' on every real terminal), instead of one pair
        // per non-space cell.
        let lines = block(&["####", "####", "####"]);
        let animation = PixelAnimation::custom(|_, _, _, _| Rgb::new(10, 20, 30));
        let out = colorize_lines(&lines, &animation, 0);
        assert_eq!(out.matches("\x1b[38;2;10;20;30m").count(), 1);
        assert_eq!(out.matches("\x1b[0m").count(), 1);
        assert_eq!(out.lines().count(), 3, "row newlines are still present");
    }

    #[test]
    fn a_space_breaks_a_run_even_when_the_color_either_side_matches() {
        let lines = block(&["# #"]);
        let animation = PixelAnimation::custom(|_, _, _, _| Rgb::new(1, 2, 3));
        let out = colorize_lines(&lines, &animation, 0);
        // Two separate '#' runs either side of the space, so two opens and
        // two resets, not one merged run spanning the space.
        assert_eq!(out.matches("\x1b[38;2;1;2;3m").count(), 2);
        assert_eq!(out.matches("\x1b[0m").count(), 2);
    }

    #[test]
    fn repeated_non_adjacent_colors_still_produce_the_correct_escapes() {
        // Alternates by column parity, so on a wide row the same two
        // colors repeat many times non-contiguously — exercising the
        // escape-string cache's correctness (not just its speed): every
        // occurrence, cached or freshly formatted, must still be right.
        let red = Rgb::new(255, 0, 0);
        let blue = Rgb::new(0, 0, 255);
        let animation =
            PixelAnimation::custom(move |x, _, _, _| if x % 2 == 0 { red } else { blue });
        let out = colorize_lines(&block(&["##########"]), &animation, 0);
        assert_eq!(out.matches("\x1b[38;2;255;0;0m").count(), 5);
        assert_eq!(out.matches("\x1b[38;2;0;0;255m").count(), 5);
    }

    #[test]
    fn colorize_lines_accepts_borrowed_str_slices_without_cloning() {
        // colorize_joined_sequence relies on this: `S = &str` must work
        // directly, not just `S = String`.
        let borrowed: Vec<&str> = vec!["#", "#"];
        let out = colorize_lines(&borrowed, &PixelAnimation::Rainbow { speed: 4.0 }, 0);
        assert!(out.contains("\x1b[38;2;"));
    }

    #[test]
    fn ripple_and_wave_do_not_panic_on_a_single_cell_grid() {
        // width/height of 1 exercises the smallest possible denominators
        // in Wave's `span` and Ripple's center-distance math.
        let lines = block(&["#"]);
        for animation in [
            PixelAnimation::Wave {
                base_color: Rgb::WHITE,
            },
            PixelAnimation::Ripple {
                base_color: Rgb::WHITE,
                speed: 0.3,
            },
        ] {
            let out = colorize_lines(&lines, &animation, 3);
            assert!(out.contains("\x1b[38;2;"));
        }
    }

    #[test]
    fn gradient_horizontal_starts_at_from_and_ends_at_to() {
        let animation = PixelAnimation::Gradient {
            from: Rgb::RED,
            to: Rgb::BLUE,
            horizontal: true,
        };
        let out = pixel_color(&animation, 0, 0, 0, '#', 4, 1);
        assert_eq!(out, Rgb::RED);
        let out = pixel_color(&animation, 3, 0, 0, '#', 4, 1);
        assert_eq!(out, Rgb::BLUE);
    }

    #[test]
    fn gradient_vertical_starts_at_from_and_ends_at_to() {
        let animation = PixelAnimation::Gradient {
            from: Rgb::GREEN,
            to: Rgb::YELLOW,
            horizontal: false,
        };
        let out = pixel_color(&animation, 0, 0, 0, '#', 1, 3);
        assert_eq!(out, Rgb::GREEN);
        let out = pixel_color(&animation, 0, 2, 0, '#', 1, 3);
        assert_eq!(out, Rgb::YELLOW);
    }

    #[test]
    fn gradient_is_time_independent() {
        let animation = PixelAnimation::Gradient {
            from: Rgb::RED,
            to: Rgb::BLUE,
            horizontal: true,
        };
        let at_frame_0 = pixel_color(&animation, 2, 0, 0, '#', 5, 1);
        let at_frame_99 = pixel_color(&animation, 2, 0, 99, '#', 5, 1);
        assert_eq!(at_frame_0, at_frame_99);
    }

    #[test]
    fn gradient_single_column_does_not_divide_by_zero() {
        let animation = PixelAnimation::Gradient {
            from: Rgb::RED,
            to: Rgb::BLUE,
            horizontal: true,
        };
        // width == 1 would divide by (width - 1) == 0 without the guard.
        let out = pixel_color(&animation, 0, 0, 0, '#', 1, 1);
        assert_eq!(out, Rgb::RED);
    }

    #[cfg(feature = "color")]
    #[test]
    fn transformed_grayscale_wraps_rainbow_and_desaturates_it() {
        let rainbow = PixelAnimation::Rainbow { speed: 5.0 };
        let wrapped = PixelAnimation::Transformed {
            base: Box::new(rainbow.clone()),
            transform: crate::color::ColorTransform::Grayscale,
        };
        let plain = pixel_color(&rainbow, 3, 0, 7, '#', 10, 10);
        let gray = pixel_color(&wrapped, 3, 0, 7, '#', 10, 10);
        // The un-transformed Rainbow output at these coordinates should not
        // already happen to be gray, so the wrapped version must differ.
        assert_ne!(plain, gray);
        assert_eq!(gray.g(), gray.b());
    }

    #[cfg(feature = "color")]
    #[test]
    fn transformed_none_matches_the_base_animation_exactly() {
        let base = PixelAnimation::Ripple {
            base_color: Rgb::WHITE,
            speed: 0.4,
        };
        let wrapped = PixelAnimation::Transformed {
            base: Box::new(base.clone()),
            transform: crate::color::ColorTransform::None,
        };
        for frame in [0u64, 1, 5] {
            assert_eq!(
                pixel_color(&base, 2, 3, frame, '#', 8, 8),
                pixel_color(&wrapped, 2, 3, frame, '#', 8, 8)
            );
        }
    }

    #[cfg(feature = "color")]
    #[test]
    fn transformed_can_wrap_another_transformed() {
        let doubly_wrapped = PixelAnimation::Transformed {
            base: Box::new(PixelAnimation::Transformed {
                base: Box::new(PixelAnimation::Gradient {
                    from: Rgb::BLACK,
                    to: Rgb::WHITE,
                    horizontal: true,
                }),
                transform: crate::color::ColorTransform::Invert,
            }),
            transform: crate::color::ColorTransform::Invert,
        };
        // Two inverts cancel: the doubly-wrapped gradient should match the
        // plain gradient exactly.
        let plain = PixelAnimation::Gradient {
            from: Rgb::BLACK,
            to: Rgb::WHITE,
            horizontal: true,
        };
        assert_eq!(
            pixel_color(&doubly_wrapped, 4, 0, 0, '#', 10, 1),
            pixel_color(&plain, 4, 0, 0, '#', 10, 1)
        );
    }

    #[cfg(feature = "color")]
    #[test]
    fn colorize_lines_renders_gradient_and_transformed_end_to_end() {
        let lines = block(&["#####", "#####"]);
        for animation in [
            PixelAnimation::Gradient {
                from: Rgb::RED,
                to: Rgb::BLUE,
                horizontal: true,
            },
            PixelAnimation::Transformed {
                base: Box::new(PixelAnimation::Plasma {
                    scale: 0.3,
                    speed: 0.2,
                }),
                transform: crate::color::ColorTransform::Sepia,
            },
        ] {
            let out = colorize_lines(&lines, &animation, 1);
            assert!(out.contains("\x1b[38;2;"));
            assert_eq!(out.lines().count(), 2);
        }
    }
}