ralph_workflow/json_parser/

delta_display.rs

//! Unified delta display system for streaming content.
//!
//! This module provides centralized logic for displaying partial vs. complete
//! content consistently across all parsers. It handles visual distinction,
//! real-time streaming display, and automatic transition from delta to complete.
//!
//! # `DeltaRenderer` Trait
//!
//! The `DeltaRenderer` trait defines a consistent interface for rendering
//! streaming deltas across all parsers. Implementations must ensure:
//! - First chunk shows prefix with accumulated content ending with carriage return
//! - Subsequent chunks update in-place (clear line, rewrite with prefix, carriage return)
//! - Final output adds newline when streaming completes
//!
//! # In-Place Updates
//!
//! The terminal escape sequences used for in-place updates:
//! - `\x1b[2K` - Clears the entire line (not just to end like `\x1b[0K`)
//! - `\r` - Returns cursor to the beginning of the line
//!
//! This ensures that previous content is completely erased before displaying
//! the updated content, preventing visual artifacts.
//!
//! # Multi-Line In-Place Update Pattern
//!
//! The renderer uses a multi-line pattern with cursor positioning for in-place updates.
//! This is the industry standard for streaming CLIs (used by Rich, Ink, Bubble Tea).
//!
//! ```text
//! [ccs-glm] Hello\n\x1b[1A             <- First chunk: prefix + content + newline + cursor up
//! \x1b[2K\r[ccs-glm] Hello World\n\x1b[1A  <- Second chunk: clear, rewrite, newline, cursor up
//! [ccs-glm] Hello World\n\x1b[1B\n       <- Final: move cursor down + newline
//! ```
//!
//! This pattern ensures:
//! - Newline forces immediate terminal output buffer flush
//! - Cursor positioning provides reliable in-place updates
//! - Production-quality rendering used by major CLI libraries
//!
//! # Terminal Mode Detection
//!
//! The renderer automatically detects terminal capability and adjusts output:
//! - **Full mode**: Uses cursor positioning for in-place updates (TTY with capable terminal)
//! - **Basic mode**: Uses colors but no cursor positioning (e.g., `TERM=dumb`)
//! - **None mode**: No ANSI sequences (pipes, redirects, CI environments)
//!
//! # Prefix Display Strategy
//!
//! The prefix (e.g., `[ccs-glm]`) is displayed on every delta update by default.
//! This provides clear visual feedback about which agent is currently streaming.
//!
//! ## Prefix Debouncing
//!
//! For scenarios where prefix repetition creates visual noise (e.g., character-by-character
//! streaming), the [`PrefixDebouncer`] can be used to control prefix display frequency.
//! It supports both delta-count-based and time-based strategies:
//!
//! - **Count-based**: Show prefix every N deltas (default: every delta)
//! - **Time-based**: Show prefix after M milliseconds since last prefix
//!
//! The debouncer is opt-in; the default behavior shows prefix on every delta.

use crate::json_parser::terminal::TerminalMode;
use crate::logger::Colors;

#[cfg(test)]
use std::time::{Duration, Instant};

/// ANSI escape sequence for clearing the entire line.
///
/// This is more complete than `\x1b[0K` which only clears to the end of line.
/// Using `\x1b[2K` ensures the entire line is cleared during in-place updates.
pub const CLEAR_LINE: &str = "\x1b[2K";

/// Sanitize content for single-line display during streaming.
///
/// This function prepares streamed content for in-place terminal display by:
/// - Replacing newlines with spaces (to prevent artificial line breaks)
/// - Collapsing multiple consecutive whitespace characters into single spaces
/// - Trimming leading and trailing whitespace
///
/// NOTE: This function does NOT truncate to terminal width. Truncation during
/// streaming causes visible "..." cut-offs as content accumulates. Terminal width
/// truncation should only be applied for final/non-streaming display.
///
/// # Arguments
/// * `content` - The raw content to sanitize
///
/// # Returns
/// A sanitized string suitable for single-line display, without truncation.
pub fn sanitize_for_display(content: &str) -> String {
    // Replace all whitespace (including \n, \r, \t) with spaces, then collapse multiple spaces
    let mut result = String::with_capacity(content.len());
    let mut prev_was_whitespace = false;

    for ch in content.chars() {
        if ch.is_whitespace() {
            if !prev_was_whitespace {
                result.push(' ');
                prev_was_whitespace = true;
            }
            // Skip consecutive whitespace characters
        } else {
            result.push(ch);
            prev_was_whitespace = false;
        }
    }

    // Trim leading and trailing whitespace for display
    result.trim().to_string()
}

/// Configuration for streaming display behavior.
///
/// This struct allows customization of streaming output features like
/// prefix debouncing and multi-line handling.
///
/// Default values:
/// - `prefix_delta_threshold`: 0 (show prefix only on first delta)
/// - `prefix_time_threshold`: None (no time-based debouncing)
#[derive(Debug, Clone, Default)]
#[cfg(test)]
pub struct StreamingConfig {
    /// Minimum number of deltas between prefix displays (0 = show on every delta)
    pub prefix_delta_threshold: u32,
    /// Minimum time between prefix displays (None = no time-based debouncing)
    pub prefix_time_threshold: Option<Duration>,
}

/// Controls prefix display frequency during streaming.
///
/// This debouncer reduces visual noise from frequent prefix redisplay during
/// rapid streaming (e.g., character-by-character output). It supports two
/// debouncing strategies:
///
/// 1. **Count-based**: Show prefix every N deltas
/// 2. **Time-based**: Show prefix after M milliseconds since last prefix
///
/// # Example
///
/// ```ignore
/// use std::time::Duration;
///
/// let config = StreamingConfig {
///     prefix_delta_threshold: 5,
///     prefix_time_threshold: Some(Duration::from_millis(100)),
/// };
/// let mut debouncer = PrefixDebouncer::new(config);
///
/// // First delta always shows prefix
/// assert!(debouncer.should_show_prefix(true));
///
/// // Subsequent deltas may skip prefix based on thresholds
/// assert!(!debouncer.should_show_prefix(false)); // Delta 2: skip
/// assert!(!debouncer.should_show_prefix(false)); // Delta 3: skip
/// // ... after threshold reached or time elapsed, prefix shows again
/// ```
#[derive(Debug, Clone)]
#[cfg(test)]
pub struct PrefixDebouncer {
    config: StreamingConfig,
    delta_count: u32,
    last_prefix_time: Option<Instant>,
}

#[cfg(test)]
impl PrefixDebouncer {
    /// Create a new prefix debouncer with the given configuration.
    pub const fn new(config: StreamingConfig) -> Self {
        Self {
            config,
            delta_count: 0,
            last_prefix_time: None,
        }
    }

    /// Reset the debouncer state (e.g., at the start of a new content block).
    pub const fn reset(&mut self) {
        self.delta_count = 0;
        self.last_prefix_time = None;
    }

    /// Determine if the prefix should be shown for the current delta.
    ///
    /// # Arguments
    /// * `is_first_delta` - Whether this is the first delta of a content block
    ///
    /// # Returns
    /// * `true` - Show the prefix
    /// * `false` - Skip the prefix (still perform line clearing)
    pub fn should_show_prefix(&mut self, is_first_delta: bool) -> bool {
        // Always show prefix on first delta
        if is_first_delta {
            self.delta_count = 0;
            self.last_prefix_time = Some(Instant::now());
            return true;
        }

        self.delta_count += 1;

        // Check time-based threshold
        if let Some(threshold) = self.config.prefix_time_threshold {
            if let Some(last_time) = self.last_prefix_time {
                if last_time.elapsed() >= threshold {
                    self.delta_count = 0;
                    self.last_prefix_time = Some(Instant::now());
                    return true;
                }
            }
        }

        // Check count-based threshold
        if self.config.prefix_delta_threshold > 0
            && self.delta_count >= self.config.prefix_delta_threshold
        {
            self.delta_count = 0;
            self.last_prefix_time = Some(Instant::now());
            return true;
        }

        // Default behavior: only first delta shows prefix.
        // With no thresholds configured, subsequent deltas don't show prefix.
        // This preserves the original behavior while allowing opt-in debouncing.
        false
    }
}

#[cfg(test)]
impl Default for PrefixDebouncer {
    fn default() -> Self {
        Self::new(StreamingConfig::default())
    }
}

/// Renderer for streaming delta content.
///
/// This trait defines the contract for rendering streaming deltas consistently
/// across all parsers. Implementations must ensure:
///
/// 1. **First chunk**: Shows prefix with accumulated content, ending with newline + cursor up
/// 2. **Subsequent chunks**: Clear line, rewrite with prefix and accumulated content, newline + cursor up
/// 3. **Completion**: Move cursor down + newline when streaming completes
///
/// # Rendering Rules
///
/// - `render_first_delta()`: Called for the first delta of a content block
///   - Must include prefix
///   - Must end with newline + cursor up (`\n\x1b[1A`) for in-place updates (in Full mode)
///   - Shows the accumulated content so far
///
/// - `render_subsequent_delta()`: Called for subsequent deltas
///   - Must include prefix (rewrite entire line)
///   - Must use `\x1b[2K\r` to clear entire line and return to start (in Full mode)
///   - Shows the full accumulated content (not just the new delta)
///   - Must end with newline + cursor up (`\n\x1b[1A`) (in Full mode)
///
/// - `render_completion()`: Called when streaming completes
///   - Returns cursor down + newline (`\x1b[1B\n`) in Full mode
///   - Returns simple newline in Basic/None mode
///
/// # Terminal Mode Awareness
///
/// The renderer automatically adapts output based on terminal capability:
/// - **Full mode**: Uses cursor positioning for in-place updates
/// - **Basic mode**: Uses colors but simple line output (no cursor positioning)
/// - **None mode**: Plain text output (no ANSI sequences)
///
/// # Example
///
/// ```ignore
/// use crate::json_parser::delta_display::DeltaRenderer;
/// use crate::logger::Colors;
/// use crate::json_parser::TerminalMode;
///
/// let colors = Colors { enabled: true };
/// let terminal_mode = TerminalMode::detect();
///
/// // First chunk
/// let output = DeltaRenderer::render_first_delta(
///     "Hello",
///     "ccs-glm",
///     colors,
///     terminal_mode
/// );
///
/// // Second chunk
/// let output = DeltaRenderer::render_subsequent_delta(
///     "Hello World",
///     "ccs-glm",
///     colors,
///     terminal_mode
/// );
///
/// // Complete
/// let output = DeltaRenderer::render_completion(terminal_mode);
/// ```
pub trait DeltaRenderer {
    /// Render the first delta of a content block.
    ///
    /// This is called when streaming begins for a new content block.
    /// The output should include the prefix and the accumulated content.
    ///
    /// # Arguments
    /// * `accumulated` - The full accumulated content so far
    /// * `prefix` - The agent prefix (e.g., "ccs-glm")
    /// * `colors` - Terminal colors
    /// * `terminal_mode` - The detected terminal capability mode
    ///
    /// # Returns
    /// A formatted string with prefix and content. In Full mode, ends with `\n\x1b[1A`.
    fn render_first_delta(
        accumulated: &str,
        prefix: &str,
        colors: Colors,
        terminal_mode: TerminalMode,
    ) -> String;

    /// Render a subsequent delta (in-place update).
    ///
    /// This is called for all deltas after the first. The output should
    /// clear the entire line and rewrite with the prefix and accumulated content
    /// in Full mode, or append content in Basic/None mode.
    ///
    /// # Arguments
    /// * `accumulated` - The full accumulated content so far
    /// * `prefix` - The agent prefix (e.g., "ccs-glm")
    /// * `colors` - Terminal colors
    /// * `terminal_mode` - The detected terminal capability mode
    ///
    /// # Returns
    /// A formatted string with prefix and content.
    fn render_subsequent_delta(
        accumulated: &str,
        prefix: &str,
        colors: Colors,
        terminal_mode: TerminalMode,
    ) -> String;

    /// Render the completion of streaming.
    ///
    /// This is called when streaming completes to move cursor down and add newline.
    /// This method ONLY handles cursor state cleanup - it does NOT render content.
    ///
    /// The streamed content is already visible on the terminal from previous deltas.
    /// This method simply positions the cursor correctly for subsequent output.
    ///
    /// # Arguments
    /// * `terminal_mode` - The detected terminal capability mode
    ///
    /// # Returns
    /// A string with appropriate cursor sequence for the terminal mode.
    fn render_completion(terminal_mode: TerminalMode) -> String {
        match terminal_mode {
            TerminalMode::Full => "\x1b[1B\n".to_string(),
            TerminalMode::Basic | TerminalMode::None => "\n".to_string(),
        }
    }
}

/// Default implementation of `DeltaRenderer` for text content.
///
/// This implementation follows the multi-line rendering pattern used by production CLIs:
/// - Prefix and content on same line ending with newline + cursor up
/// - Content updates in-place using clear, rewrite, and newline + cursor up
/// - Sanitizes newlines to spaces (to prevent artificial line breaks)
/// - Uses ANSI escape codes for in-place updates with full line clear
/// - Applies consistent color formatting
///
/// # Output Pattern
///
/// ## Full Mode (TTY with capable terminal)
///
/// ```text
/// [ccs-glm] Hello\n\x1b[1A             <- First chunk: prefix + content + newline + cursor up
/// \x1b[2K\r[ccs-glm] Hello World\n\x1b[1A  <- Second chunk: clear, rewrite, newline, cursor up
/// [ccs-glm] Hello World\n\x1b[1B\n       <- Final: move cursor down + newline
/// ```
///
/// ## Basic/None Mode (colors only or plain text)
///
/// ```text
/// [ccs-glm] Hello\n                      <- First chunk: simple line output
/// [ccs-glm] Hello World\n                <- Second chunk: full content (no in-place update)
///                                       <- Final: just a newline
/// ```
///
/// The multi-line pattern is the industry standard used by Rich, Ink, Bubble Tea
/// and other production CLI libraries for clean streaming output.
pub struct TextDeltaRenderer;

impl DeltaRenderer for TextDeltaRenderer {
    fn render_first_delta(
        accumulated: &str,
        prefix: &str,
        colors: Colors,
        terminal_mode: TerminalMode,
    ) -> String {
        // Sanitize content: replace newlines with spaces and collapse multiple whitespace
        // NOTE: No truncation here - allow full content to accumulate during streaming
        let sanitized = sanitize_for_display(accumulated);

        match terminal_mode {
            TerminalMode::Full => {
                // Multi-line pattern: end with newline + cursor up for in-place updates
                // This forces terminal output flush and positions cursor for rewrite
                format!(
                    "{}[{}]{} {}{}{}\n\x1b[1A",
                    colors.dim(),
                    prefix,
                    colors.reset(),
                    colors.white(),
                    sanitized,
                    colors.reset()
                )
            }
            TerminalMode::Basic | TerminalMode::None => {
                // Simple line output without cursor positioning
                format!(
                    "{}[{}]{} {}{}{}\n",
                    colors.dim(),
                    prefix,
                    colors.reset(),
                    colors.white(),
                    sanitized,
                    colors.reset()
                )
            }
        }
    }

    fn render_subsequent_delta(
        accumulated: &str,
        prefix: &str,
        colors: Colors,
        terminal_mode: TerminalMode,
    ) -> String {
        // Sanitize content: replace newlines with spaces and collapse multiple whitespace
        // NOTE: No truncation here - allow full content to accumulate during streaming
        let sanitized = sanitize_for_display(accumulated);

        match terminal_mode {
            TerminalMode::Full => {
                // Clear line, rewrite with prefix and accumulated content, end with newline + cursor up
                // This creates in-place update using multi-line pattern
                format!(
                    "{CLEAR_LINE}\r{}[{}]{} {}{}{}\n\x1b[1A",
                    colors.dim(),
                    prefix,
                    colors.reset(),
                    colors.white(),
                    sanitized,
                    colors.reset()
                )
            }
            TerminalMode::Basic | TerminalMode::None => {
                // Simple line output without cursor positioning
                // Note: This will show each update as a new line, which is intentional
                // for non-TTY or basic terminal output
                format!(
                    "{}[{}]{} {}{}{}\n",
                    colors.dim(),
                    prefix,
                    colors.reset(),
                    colors.white(),
                    sanitized,
                    colors.reset()
                )
            }
        }
    }
}

/// Delta display formatter
///
/// Formats delta content for user display with consistent styling across all parsers.
pub struct DeltaDisplayFormatter {
    /// Whether to mark partial content visually
    mark_partial: bool,
}

impl DeltaDisplayFormatter {
    /// Create a new formatter with default settings
    pub const fn new() -> Self {
        Self { mark_partial: true }
    }

    /// Format thinking content specifically
    ///
    /// Thinking content has special formatting to distinguish it from regular text.
    pub fn format_thinking(&self, content: &str, prefix: &str, colors: Colors) -> String {
        if self.mark_partial {
            format!(
                "{}[{}]{} {}Thinking: {}{}{}\n",
                colors.dim(),
                prefix,
                colors.reset(),
                colors.dim(),
                colors.cyan(),
                content,
                colors.reset()
            )
        } else {
            format!(
                "{}[{}]{} {}Thinking: {}{}{}\n",
                colors.dim(),
                prefix,
                colors.reset(),
                colors.cyan(),
                colors.reset(),
                content,
                colors.reset()
            )
        }
    }

    /// Format tool input specifically
    ///
    /// Tool input is shown with appropriate styling.
    ///
    /// # Current Behavior
    ///
    /// Every call renders the full `[prefix]   └─ content` pattern.
    /// This provides clarity about which agent's tool is being invoked.
    ///
    /// # Future Enhancement
    ///
    /// For streaming tool inputs with multiple deltas, consider suppressing
    /// the `[prefix]` on continuation lines to reduce visual noise:
    /// - First tool input line: `[prefix] Tool: name`
    /// - Continuation: `           └─ more input` (aligned, no prefix)
    ///
    /// This would require tracking whether the prefix has been displayed
    /// for the current tool block, likely via the streaming session state.
    pub fn format_tool_input(&self, content: &str, prefix: &str, colors: Colors) -> String {
        if self.mark_partial {
            format!(
                "{}[{}]{} {}  └─ {}{}{}\n",
                colors.dim(),
                prefix,
                colors.reset(),
                colors.dim(),
                colors.reset(),
                content,
                colors.reset()
            )
        } else {
            format!(
                "{}[{}]{} {}  └─ {}{}\n",
                colors.dim(),
                prefix,
                colors.reset(),
                colors.reset(),
                content,
                colors.reset()
            )
        }
    }
}

impl Default for DeltaDisplayFormatter {
    fn default() -> Self {
        Self::new()
    }
}

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

    fn test_colors() -> Colors {
        Colors { enabled: false }
    }

    #[test]
    fn test_format_thinking_content() {
        let formatter = DeltaDisplayFormatter::new();
        let output = formatter.format_thinking("Thinking about this", "Claude", test_colors());
        assert!(output.contains("Thinking"));
        assert!(output.contains("Thinking about this"));
    }

    #[test]
    fn test_format_tool_input() {
        let formatter = DeltaDisplayFormatter::new();
        let output = formatter.format_tool_input("command=ls -la", "Claude", test_colors());
        assert!(output.contains("command=ls -la"));
        assert!(output.contains("└─"));
    }

    // Tests for DeltaRenderer trait

    #[test]
    fn test_text_delta_renderer_first_delta_full_mode() {
        let output = TextDeltaRenderer::render_first_delta(
            "Hello",
            "ccs-glm",
            test_colors(),
            TerminalMode::Full,
        );
        assert!(output.contains("[ccs-glm]"));
        assert!(output.contains("Hello"));
        // Multi-line pattern: ends with newline + cursor up
        assert!(output.ends_with("\x1b[1A"));
        assert!(output.contains('\n'));
        assert!(output.contains("\x1b[1A"));
    }

    #[test]
    fn test_text_delta_renderer_first_delta_none_mode() {
        let output = TextDeltaRenderer::render_first_delta(
            "Hello",
            "ccs-glm",
            test_colors(),
            TerminalMode::None,
        );
        assert!(output.contains("[ccs-glm]"));
        assert!(output.contains("Hello"));
        // No cursor positioning in None mode
        assert!(!output.contains("\x1b[1A"));
        assert!(!output.contains("\x1b[2K"));
        // But should still have newline
        assert!(output.contains('\n'));
        assert!(output.ends_with('\n'));
    }

    #[test]
    fn test_text_delta_renderer_first_delta_basic_mode() {
        let output = TextDeltaRenderer::render_first_delta(
            "Hello",
            "ccs-glm",
            test_colors(),
            TerminalMode::Basic,
        );
        assert!(output.contains("[ccs-glm]"));
        assert!(output.contains("Hello"));
        // No cursor positioning in Basic mode
        assert!(!output.contains("\x1b[1A"));
        assert!(!output.contains("\x1b[2K"));
        // But should still have newline
        assert!(output.contains('\n'));
        assert!(output.ends_with('\n'));
    }

    #[test]
    fn test_text_delta_renderer_subsequent_delta_full_mode() {
        let output = TextDeltaRenderer::render_subsequent_delta(
            "Hello World",
            "ccs-glm",
            test_colors(),
            TerminalMode::Full,
        );
        assert!(output.contains(CLEAR_LINE));
        assert!(output.contains('\r'));
        assert!(output.contains("Hello World"));
        // Multi-line pattern: ends with newline + cursor up
        assert!(output.contains("\x1b[1A"));
        assert!(output.ends_with("\x1b[1A"));
        assert!(output.contains("[ccs-glm]"));
    }

    #[test]
    fn test_text_delta_renderer_subsequent_delta_none_mode() {
        let output = TextDeltaRenderer::render_subsequent_delta(
            "Hello World",
            "ccs-glm",
            test_colors(),
            TerminalMode::None,
        );
        assert!(!output.contains(CLEAR_LINE));
        assert!(!output.contains('\r'));
        assert!(output.contains("Hello World"));
        // No cursor positioning in None mode
        assert!(!output.contains("\x1b[1A"));
        // But should still have newline
        assert!(output.contains('\n'));
        assert!(output.ends_with('\n'));
    }

    #[test]
    fn test_text_delta_renderer_uses_full_line_clear() {
        let output = TextDeltaRenderer::render_subsequent_delta(
            "Hello World",
            "ccs-glm",
            test_colors(),
            TerminalMode::Full,
        );
        // Should use \x1b[2K (full line clear), not \x1b[0K (clear to end)
        assert!(output.contains("\x1b[2K"));
        // Should NOT contain \x1b[0K
        assert!(!output.contains("\x1b[0K"));
    }

    #[test]
    fn test_text_delta_renderer_completion_full_mode() {
        let output = TextDeltaRenderer::render_completion(TerminalMode::Full);
        // Multi-line pattern: cursor down + newline
        assert!(output.contains("\x1b[1B"));
        assert!(output.contains('\n'));
        assert_eq!(output, "\x1b[1B\n");
    }

    #[test]
    fn test_text_delta_renderer_completion_none_mode() {
        let output = TextDeltaRenderer::render_completion(TerminalMode::None);
        // Just a newline in None mode
        assert!(!output.contains("\x1b[1B"));
        assert!(output.contains('\n'));
        assert_eq!(output, "\n");
    }

    #[test]
    fn test_text_delta_renderer_completion_basic_mode() {
        let output = TextDeltaRenderer::render_completion(TerminalMode::Basic);
        // Just a newline in Basic mode
        assert!(!output.contains("\x1b[1B"));
        assert!(output.contains('\n'));
        assert_eq!(output, "\n");
    }

    #[test]
    fn test_text_delta_renderer_sanitizes_newlines() {
        let output = TextDeltaRenderer::render_first_delta(
            "Hello\nWorld",
            "ccs-glm",
            test_colors(),
            TerminalMode::Full,
        );
        // Newlines should be replaced with spaces
        assert!(!output.contains("Hello\nWorld"));
        assert!(output.contains("Hello World"));
    }

    #[test]
    fn test_text_delta_renderer_in_place_update_sequence() {
        let colors = test_colors();

        // First chunk - multi-line pattern: ends with newline + cursor up
        let out1 =
            TextDeltaRenderer::render_first_delta("Hello", "ccs-glm", colors, TerminalMode::Full);
        assert!(out1.contains("[ccs-glm]"));
        assert!(out1.ends_with("\x1b[1A"));
        assert!(out1.contains('\n'));
        assert!(out1.contains("\x1b[1A"));

        // Second chunk (in-place update with newline + cursor up)
        let out2 = TextDeltaRenderer::render_subsequent_delta(
            "Hello World",
            "ccs-glm",
            colors,
            TerminalMode::Full,
        );
        assert!(out2.contains("\x1b[2K"));
        assert!(out2.contains('\r'));
        assert!(out2.contains("\x1b[1A")); // Cursor up in multi-line pattern
        assert!(out2.contains("[ccs-glm]")); // Prefix is rewritten

        // Completion
        let out3 = TextDeltaRenderer::render_completion(TerminalMode::Full);
        assert!(out3.contains("\x1b[1B"));
        assert_eq!(out3, "\x1b[1B\n");
    }

    #[test]
    fn test_full_streaming_sequence_no_extra_blank_lines() {
        let colors = test_colors();

        // Simulate a full streaming sequence and verify no extra blank lines
        let first =
            TextDeltaRenderer::render_first_delta("Hello", "agent", colors, TerminalMode::Full);
        let second = TextDeltaRenderer::render_subsequent_delta(
            "Hello World",
            "agent",
            colors,
            TerminalMode::Full,
        );
        let complete = TextDeltaRenderer::render_completion(TerminalMode::Full);

        // First delta: ends with exactly one \n followed by cursor up
        assert!(first.ends_with("\n\x1b[1A"));
        assert_eq!(first.matches('\n').count(), 1);

        // Subsequent delta: starts with clear+return, ends with \n + cursor up
        assert!(second.starts_with("\x1b[2K\r"));
        assert!(second.ends_with("\n\x1b[1A"));
        assert_eq!(second.matches('\n').count(), 1);

        // Completion: exactly cursor down + one newline
        assert_eq!(complete, "\x1b[1B\n");
        assert_eq!(complete.matches('\n').count(), 1);
    }

    #[test]
    fn test_non_tty_streaming_sequence_simple_output() {
        let colors = test_colors();

        // Simulate a full streaming sequence in None mode
        let first =
            TextDeltaRenderer::render_first_delta("Hello", "agent", colors, TerminalMode::None);
        let second = TextDeltaRenderer::render_subsequent_delta(
            "Hello World",
            "agent",
            colors,
            TerminalMode::None,
        );
        let complete = TextDeltaRenderer::render_completion(TerminalMode::None);

        // First delta: simple line ending with newline
        assert!(first.contains("Hello"));
        assert!(first.ends_with('\n'));
        assert!(!first.contains('\x1b'));

        // Second delta: simple line with full content (no in-place update)
        assert!(second.contains("Hello World"));
        assert!(second.ends_with('\n'));
        assert!(!second.contains('\x1b'));

        // Completion: just a newline
        assert_eq!(complete, "\n");
    }

    #[test]
    fn test_prefix_displayed_on_all_deltas() {
        let colors = test_colors();
        let prefix = "my-agent";

        // First delta shows prefix
        let first = TextDeltaRenderer::render_first_delta("A", prefix, colors, TerminalMode::Full);
        assert!(first.contains(&format!("[{prefix}]")));

        // Subsequent delta also shows prefix (design decision: prefix on every delta)
        let subsequent =
            TextDeltaRenderer::render_subsequent_delta("AB", prefix, colors, TerminalMode::Full);
        assert!(subsequent.contains(&format!("[{prefix}]")));
    }

    // Tests for sanitize_for_display helper function

    #[test]
    fn test_sanitize_collapses_multiple_newlines() {
        let result = sanitize_for_display("Hello\n\nWorld");
        // Multiple newlines should become a single space
        assert_eq!(result, "Hello World");
    }

    #[test]
    fn test_sanitize_collapses_multiple_spaces() {
        let result = sanitize_for_display("Hello   World");
        assert_eq!(result, "Hello World");
    }

    #[test]
    fn test_sanitize_mixed_whitespace() {
        let result = sanitize_for_display("Hello\n\n  \t\t  World");
        // All whitespace (newlines, spaces, tabs) collapsed to single space
        assert_eq!(result, "Hello World");
    }

    #[test]
    fn test_sanitize_trims_leading_trailing_whitespace() {
        let result = sanitize_for_display("  Hello World  ");
        assert_eq!(result, "Hello World");
    }

    #[test]
    fn test_sanitize_only_whitespace() {
        let result = sanitize_for_display("   \n\n   ");
        // Only whitespace content becomes empty string
        assert_eq!(result, "");
    }

    #[test]
    fn test_sanitize_preserves_single_spaces() {
        let result = sanitize_for_display("Hello World Test");
        assert_eq!(result, "Hello World Test");
    }

    #[test]
    fn test_sanitize_does_not_truncate() {
        // sanitize_for_display no longer truncates - it just sanitizes whitespace
        let long_content = "This is a very long string that should NOT be truncated anymore";
        let result = sanitize_for_display(long_content);
        // Should NOT be truncated
        assert_eq!(result, long_content);
        assert!(!result.contains("..."));
    }

    #[test]
    fn test_delta_renderer_multiple_newlines_render_cleanly() {
        let colors = test_colors();
        let output = TextDeltaRenderer::render_first_delta(
            "Hello\n\n\nWorld",
            "agent",
            colors,
            TerminalMode::Full,
        );
        // Multiple newlines should render as single space
        assert!(output.contains("Hello World"));
        // Should NOT have multiple spaces
        assert!(!output.contains("  "));
    }

    #[test]
    fn test_delta_renderer_trailing_whitespace_trimmed() {
        let colors = test_colors();
        let output = TextDeltaRenderer::render_first_delta(
            "Hello World   ",
            "agent",
            colors,
            TerminalMode::Full,
        );
        // Trailing spaces should be trimmed
        assert!(output.contains("Hello World"));
        // Content should not end with space before escape sequences
        // (it ends with reset color then \n\x1b[1A)
    }

    // Tests for StreamingConfig

    #[test]
    fn test_streaming_config_defaults() {
        let config = StreamingConfig::default();
        assert_eq!(config.prefix_delta_threshold, 0);
        assert!(config.prefix_time_threshold.is_none());
    }

    // Tests for PrefixDebouncer

    #[test]
    fn test_prefix_debouncer_default_first_only() {
        let mut debouncer = PrefixDebouncer::default();

        // First delta always shows prefix
        assert!(debouncer.should_show_prefix(true));

        // With default config (no thresholds), only first delta shows prefix
        // This preserves the original behavior
        assert!(!debouncer.should_show_prefix(false));
        assert!(!debouncer.should_show_prefix(false));
        assert!(!debouncer.should_show_prefix(false));
    }

    #[test]
    fn test_prefix_debouncer_count_threshold() {
        let config = StreamingConfig {
            prefix_delta_threshold: 3,
            prefix_time_threshold: None,
        };
        let mut debouncer = PrefixDebouncer::new(config);

        // First delta always shows prefix
        assert!(debouncer.should_show_prefix(true));

        // Next 2 deltas should skip prefix
        assert!(!debouncer.should_show_prefix(false)); // delta 1
        assert!(!debouncer.should_show_prefix(false)); // delta 2

        // 3rd delta hits threshold, shows prefix
        assert!(debouncer.should_show_prefix(false)); // delta 3

        // Cycle resets
        assert!(!debouncer.should_show_prefix(false)); // delta 1
        assert!(!debouncer.should_show_prefix(false)); // delta 2
        assert!(debouncer.should_show_prefix(false)); // delta 3
    }

    #[test]
    fn test_prefix_debouncer_reset() {
        let config = StreamingConfig {
            prefix_delta_threshold: 3,
            prefix_time_threshold: None,
        };
        let mut debouncer = PrefixDebouncer::new(config);

        // Build up delta count
        debouncer.should_show_prefix(true);
        debouncer.should_show_prefix(false);
        debouncer.should_show_prefix(false);

        // Reset clears state
        debouncer.reset();

        // After reset, next delta is treated as fresh
        // (but not "first delta" unless caller says so)
        assert!(!debouncer.should_show_prefix(false)); // delta 1 after reset
        assert!(!debouncer.should_show_prefix(false)); // delta 2
        assert!(debouncer.should_show_prefix(false)); // delta 3 hits threshold
    }

    #[test]
    fn test_prefix_debouncer_first_delta_always_shows() {
        let config = StreamingConfig {
            prefix_delta_threshold: 100,
            prefix_time_threshold: None,
        };
        let mut debouncer = PrefixDebouncer::new(config);

        // First delta always shows prefix regardless of threshold
        assert!(debouncer.should_show_prefix(true));

        // Even after many skips, marking as first shows prefix
        for _ in 0..10 {
            debouncer.should_show_prefix(false);
        }
        assert!(debouncer.should_show_prefix(true)); // First delta again
    }

    #[test]
    fn test_prefix_debouncer_time_threshold() {
        // Note: This test uses Duration::ZERO for immediate threshold.
        // In practice, time-based debouncing uses longer durations like 100ms.
        let config = StreamingConfig {
            prefix_delta_threshold: 0,
            prefix_time_threshold: Some(Duration::ZERO),
        };
        let mut debouncer = PrefixDebouncer::new(config);

        // First delta shows prefix
        assert!(debouncer.should_show_prefix(true));

        // Since threshold is ZERO, any elapsed time triggers prefix
        // In practice, Instant::now() moves forward, so this should show
        assert!(debouncer.should_show_prefix(false));
    }
}