Skip to main content

ftui_runtime/
terminal_writer.rs

1#![forbid(unsafe_code)]
2
3//! Terminal output coordinator with inline mode support.
4//!
5//! The `TerminalWriter` is the component that makes inline mode work. It:
6//! - Serializes log writes and UI presents (one-writer rule)
7//! - Implements the cursor save/restore contract
8//! - Manages scroll regions (when optimization enabled)
9//! - Ensures single buffered write per operation
10//!
11//! # Screen Modes
12//!
13//! - **Inline Mode**: Preserves terminal scrollback. UI is rendered at the
14//!   bottom, logs scroll normally above. Uses cursor save/restore.
15//!
16//! - **AltScreen Mode**: Uses alternate screen buffer. Full-screen UI,
17//!   no scrollback preservation.
18//!
19//! # Inline Mode Contract
20//!
21//! 1. Cursor is saved before any UI operation
22//! 2. UI region is cleared and redrawn
23//! 3. Cursor is restored after UI operation
24//! 4. Log writes go above the UI region: with an active scroll region they
25//!    accumulate into scrollback; in the overlay fallback exactly one
26//!    width-clamped line is rewritten per call (an unqualified LF would
27//!    scroll the whole screen and displace the UI)
28//! 5. Terminal state is restored on drop
29//!
30//! # Usage
31//!
32//! ```ignore
33//! use ftui_runtime::{TerminalWriter, ScreenMode, UiAnchor};
34//! use ftui_render::buffer::Buffer;
35//! use ftui_core::terminal_capabilities::TerminalCapabilities;
36//!
37//! // Create writer for inline mode with 10-row UI
38//! let mut writer = TerminalWriter::new(
39//!     std::io::stdout(),
40//!     ScreenMode::Inline { ui_height: 10 },
41//!     UiAnchor::Bottom,
42//!     TerminalCapabilities::detect(),
43//! );
44//!
45//! // Write logs (goes to scrollback above UI)
46//! writer.write_log("Starting...\n")?;
47//!
48//! // Present UI
49//! let buffer = Buffer::new(80, 10);
50//! writer.present_ui(&buffer, None, true)?;
51//! ```
52
53use std::io::{self, BufWriter, Write};
54use std::sync::Arc;
55use std::sync::atomic::{AtomicU32, Ordering};
56use web_time::Instant;
57
58/// Global gauge: number of active inline-mode `TerminalWriter` instances.
59///
60/// Incremented when a writer is created in `Inline` or `InlineAuto` mode,
61/// decremented on drop. Read with [`inline_active_widgets`].
62static INLINE_ACTIVE_WIDGETS: AtomicU32 = AtomicU32::new(0);
63
64/// Read the current number of active inline-mode terminal writers.
65pub fn inline_active_widgets() -> u32 {
66    INLINE_ACTIVE_WIDGETS.load(Ordering::Relaxed)
67}
68
69use crate::evidence_sink::EvidenceSink;
70
71struct CallbackEvidenceWriter(Arc<dyn Fn(&str) + Send + Sync>);
72
73impl Write for CallbackEvidenceWriter {
74    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
75        let text = String::from_utf8_lossy(buf);
76        let trimmed = text.trim_end_matches(['\r', '\n']);
77        if !trimmed.is_empty() {
78            (self.0)(trimmed);
79        }
80        Ok(buf.len())
81    }
82
83    fn flush(&mut self) -> io::Result<()> {
84        Ok(())
85    }
86}
87
88/// A strategy downgrade forced by the DECSTBM self-test
89/// (`TerminalWriter::set_scroll_region_verified`).
90#[derive(Debug, Clone, PartialEq, Eq)]
91pub struct InlineStrategyFallback {
92    /// Strategy selected from capabilities before the test.
93    pub from: InlineStrategy,
94    /// `cpr_mismatch` (the cursor left the region) or `cpr_timeout` (no
95    /// cursor-position report arrived).
96    pub reason: &'static str,
97    /// Row the terminal reported, if it answered.
98    pub observed_row: Option<u16>,
99    /// Row a terminal that honours the region reports.
100    pub expected_row: u16,
101    /// Terminal height at the time of the test.
102    pub rows: u16,
103    /// Last row of the tested scroll region.
104    pub region_bottom: u16,
105}
106
107impl InlineStrategyFallback {
108    /// The `inline_strategy_fallback` evidence row.
109    #[must_use]
110    pub fn to_jsonl(&self) -> String {
111        let observed = self
112            .observed_row
113            .map_or_else(|| "null".to_string(), |row| row.to_string());
114        format!(
115            r#"{{"event":"inline_strategy_fallback","from":"{}","to":"overlay_redraw","reason":"{}","observed_row":{},"expected_row":{},"rows":{},"region_bottom":{}}}"#,
116            inline_strategy_str(self.from),
117            self.reason,
118            observed,
119            self.expected_row,
120            self.rows,
121            self.region_bottom
122        )
123    }
124}
125use crate::evidence_telemetry::{DiffDecisionSnapshot, set_diff_snapshot};
126use crate::render_trace::{
127    RenderTraceFrame, RenderTraceRecorder, build_diff_runs_payload, build_full_buffer_payload,
128};
129use ftui_core::caps_probe::CapabilityDecision;
130use ftui_core::inline_mode::{InlineStrategy, sanitize_overlay_log_line};
131#[cfg(test)]
132use ftui_core::terminal_capabilities::ColorDepth;
133use ftui_core::terminal_capabilities::TerminalCapabilities;
134use ftui_core::terminal_session::terminal_output_lock;
135use ftui_render::buffer::{Buffer, DirtySpanConfig, DirtySpanStats};
136use ftui_render::counting_writer::CountingWriter;
137use ftui_render::diff::{BufferDiff, TileDiffConfig, TileDiffFallback, TileDiffStats};
138use ftui_render::diff_strategy::{
139    DiffRegime, DiffStrategy, DiffStrategyConfig, DiffStrategySelector,
140};
141use ftui_render::grapheme_pool::GraphemePool;
142use ftui_render::link_registry::LinkRegistry;
143use ftui_render::presenter::Presenter;
144use ftui_render::render_certificate::{
145    RenderCertificate, RenderCertificateInputs, RenderCertificateLevel, evaluate_render_certificate,
146};
147use ftui_render::sanitize::{SanitizeMode, Text, sanitize, sanitize_with};
148use tracing::{debug_span, info, info_span, trace, warn};
149
150/// Size of the internal write buffer (64KB).
151#[allow(dead_code)] // Used by Presenter::new; kept here for reference.
152const BUFFER_CAPACITY: usize = 64 * 1024;
153
154/// DEC cursor save (ESC 7) - more portable than CSI s.
155const CURSOR_SAVE: &[u8] = b"\x1b7";
156
157/// DEC cursor restore (ESC 8) - more portable than CSI u.
158const CURSOR_RESTORE: &[u8] = b"\x1b8";
159
160/// Reset SGR before returning control to the UI renderer.
161const SGR_RESET: &[u8] = b"\x1b[0m";
162
163/// Clamp the plain projection using the same policy as unstyled overlay logs,
164/// then retain the SGR sequences interspersed through that visible prefix.
165/// `text` must already have passed SGR-only sanitization.
166fn sgr_overlay_log_line(text: &str, max_cols: usize) -> String {
167    let plain = sanitize(text);
168    let line = sanitize_overlay_log_line(&plain, max_cols);
169    let mut visible = line.chars();
170    let mut next_visible = visible.next();
171    let mut out = String::new();
172    let mut chars = text.chars();
173    while next_visible.is_some() {
174        let Some(ch) = chars.next() else {
175            break;
176        };
177        if ch == '\x1b' {
178            out.push(ch);
179            for sgr_char in chars.by_ref() {
180                out.push(sgr_char);
181                if sgr_char == 'm' {
182                    break;
183                }
184            }
185        } else if Some(ch) == next_visible {
186            out.push(ch);
187            next_visible = visible.next();
188        }
189    }
190    out
191}
192
193/// Synchronized output begin (DEC 2026).
194const SYNC_BEGIN: &[u8] = b"\x1b[?2026h";
195
196/// Synchronized output end (DEC 2026).
197const SYNC_END: &[u8] = b"\x1b[?2026l";
198
199/// Erase entire line (CSI 2 K).
200const ERASE_LINE: &[u8] = b"\x1b[2K";
201/// Reset background to terminal default (CSI 49 m).
202const SGR_BG_DEFAULT: &[u8] = b"\x1b[49m";
203
204/// How often to probe with a real diff when FullRedraw is selected.
205#[allow(dead_code)] // API for future diff strategy integration
206const FULL_REDRAW_PROBE_INTERVAL: u64 = 60;
207
208// CountingWriter is re-used from ftui_render::counting_writer::CountingWriter.
209// The Presenter wraps the writer in CountingWriter<BufWriter<W>>.
210// For byte counting, use reset_counter() and bytes_written() on the counting writer.
211
212fn default_diff_run_id() -> String {
213    format!("diff-{}", std::process::id())
214}
215
216fn diff_strategy_str(strategy: DiffStrategy) -> &'static str {
217    match strategy {
218        DiffStrategy::Full => "full",
219        DiffStrategy::DirtyRows => "dirty",
220        DiffStrategy::FullRedraw => "redraw",
221    }
222}
223
224fn inline_strategy_str(strategy: InlineStrategy) -> &'static str {
225    match strategy {
226        InlineStrategy::ScrollRegion => "scroll_region",
227        InlineStrategy::OverlayRedraw => "overlay_redraw",
228        InlineStrategy::Hybrid => "hybrid",
229    }
230}
231
232fn ui_anchor_str(anchor: UiAnchor) -> &'static str {
233    match anchor {
234        UiAnchor::Bottom => "bottom",
235        UiAnchor::Top => "top",
236    }
237}
238
239#[allow(dead_code)]
240#[inline]
241fn json_escape(value: &str) -> String {
242    let mut out = String::with_capacity(value.len());
243    for ch in value.chars() {
244        match ch {
245            '"' => out.push_str("\\\""),
246            '\\' => out.push_str("\\\\"),
247            '\n' => out.push_str("\\n"),
248            '\r' => out.push_str("\\r"),
249            '\t' => out.push_str("\\t"),
250            c if c.is_control() => {
251                use std::fmt::Write as _;
252                let _ = write!(out, "\\u{:04X}", c as u32);
253            }
254            _ => out.push(ch),
255        }
256    }
257    out
258}
259
260#[allow(dead_code)]
261fn estimate_diff_scan_cost(
262    strategy: DiffStrategy,
263    dirty_rows: usize,
264    width: usize,
265    height: usize,
266    span_stats: &DirtySpanStats,
267    tile_stats: Option<TileDiffStats>,
268) -> (usize, &'static str) {
269    match strategy {
270        DiffStrategy::Full => (width.saturating_mul(height), "full_strategy"),
271        DiffStrategy::FullRedraw => (0, "full_redraw"),
272        DiffStrategy::DirtyRows => {
273            if dirty_rows == 0 {
274                return (0, "no_dirty_rows");
275            }
276            if let Some(tile_stats) = tile_stats
277                && tile_stats.fallback.is_none()
278            {
279                return (tile_stats.scan_cells_estimate, "tile_skip");
280            }
281            let span_cells = span_stats.span_coverage_cells;
282            if span_stats.overflows > 0 {
283                let estimate = if span_cells > 0 {
284                    span_cells
285                } else {
286                    dirty_rows.saturating_mul(width)
287                };
288                return (estimate, "span_overflow");
289            }
290            if span_cells > 0 {
291                (span_cells, "none")
292            } else {
293                (dirty_rows.saturating_mul(width), "no_spans")
294            }
295        }
296    }
297}
298
299fn sanitize_auto_bounds(min_height: u16, max_height: u16) -> (u16, u16) {
300    let min = min_height.max(1);
301    let max = max_height.max(min);
302    (min, max)
303}
304
305pub use ftui_backend::{PresentTimings, ScreenMode, UiAnchor};
306
307#[derive(Debug, Clone, Copy, PartialEq, Eq)]
308struct InlineRegion {
309    start: u16,
310    height: u16,
311}
312
313struct DiffDecision {
314    #[allow(dead_code)] // reserved for future diff strategy introspection
315    strategy: DiffStrategy,
316    has_diff: bool,
317}
318
319#[derive(Debug, Clone, Copy)]
320#[allow(dead_code)]
321struct EmitStats {
322    diff_cells: usize,
323    diff_runs: usize,
324}
325
326#[derive(Debug, Clone, Copy)]
327#[allow(dead_code)]
328struct FrameEmitStats {
329    diff_strategy: DiffStrategy,
330    diff_cells: usize,
331    diff_runs: usize,
332    ui_height: u16,
333}
334
335// =============================================================================
336// Runtime Diff Configuration
337// =============================================================================
338
339/// Runtime-level configuration for diff strategy selection.
340///
341/// This wraps [`DiffStrategyConfig`] and adds runtime-specific toggles
342/// for enabling/disabling features and controlling reset policies.
343///
344/// # Example
345///
346/// ```
347/// use ftui_runtime::{RuntimeDiffConfig, DiffStrategyConfig};
348///
349/// // Use defaults (Bayesian selection enabled, dirty-rows enabled)
350/// let config = RuntimeDiffConfig::default();
351///
352/// // Disable Bayesian selection (always use dirty-rows if available)
353/// let config = RuntimeDiffConfig::default()
354///     .with_bayesian_enabled(false);
355///
356/// // Custom cost model
357/// let config = RuntimeDiffConfig::default()
358///     .with_strategy_config(DiffStrategyConfig {
359///         c_emit: 10.0,  // Higher I/O cost
360///         ..Default::default()
361///     });
362/// ```
363#[derive(Debug, Clone)]
364pub struct RuntimeDiffConfig {
365    /// Enable Bayesian strategy selection.
366    ///
367    /// When enabled, the selector uses a Beta posterior over the change rate
368    /// to choose between Full, DirtyRows, and FullRedraw strategies.
369    ///
370    /// When disabled, always uses DirtyRows if dirty tracking is available,
371    /// otherwise Full.
372    ///
373    /// Default: true
374    pub bayesian_enabled: bool,
375
376    /// Enable dirty-row optimization.
377    ///
378    /// When enabled, the DirtyRows strategy is available for selection.
379    /// When disabled, the selector chooses between Full and FullRedraw only.
380    ///
381    /// Default: true
382    pub dirty_rows_enabled: bool,
383
384    /// Emit explicit render certificates and route the DirtyRows strategy
385    /// through the certified diff path (skip-all on zero dirty rows,
386    /// narrow-to-dirty otherwise). Behavior-identical to the uncertified
387    /// dirty path; disabling only removes the certificate evidence and the
388    /// zero-dirty fast path.
389    ///
390    /// Default: true
391    pub certified_skips: bool,
392
393    /// Dirty-span tracking configuration (thresholds + feature flags).
394    ///
395    /// Controls span merging, guard bands, and enable/disable behavior.
396    pub dirty_span_config: DirtySpanConfig,
397
398    /// Tile-based diff skipping configuration (thresholds + feature flags).
399    ///
400    /// Controls SAT tile size, thresholds, and enable/disable behavior.
401    pub tile_diff_config: TileDiffConfig,
402
403    /// Reset posterior on dimension change.
404    ///
405    /// When true, the Bayesian posterior resets to priors when the buffer
406    /// dimensions change (e.g., terminal resize).
407    ///
408    /// Default: true
409    pub reset_on_resize: bool,
410
411    /// Reset posterior on buffer invalidation.
412    ///
413    /// When true, resets to priors when the previous buffer becomes invalid
414    /// (e.g., mode switch, scroll region change).
415    ///
416    /// Default: true
417    pub reset_on_invalidation: bool,
418
419    /// Underlying strategy configuration.
420    ///
421    /// Contains cost model constants, prior parameters, and decay settings.
422    pub strategy_config: DiffStrategyConfig,
423
424    /// Maximum successful incremental frames to allow between physical full redraws.
425    ///
426    /// Terminals and mux panes can lose their visible buffer without notifying the
427    /// process. A bounded full redraw interval repairs that state divergence even
428    /// when the application model has not changed. Set to `0` to disable.
429    ///
430    /// Default: 240
431    pub full_redraw_interval_frames: u64,
432
433    /// Maximum *wall-clock* time to allow between physical full redraws.
434    ///
435    /// The frame-count interval ([`Self::full_redraw_interval_frames`]) only
436    /// advances on rendered frames, so a TUI that renders sparsely (dirty-driven,
437    /// idle, or rendering slowly) can leave a desynchronized physical terminal —
438    /// e.g. corruption from an aggressive incremental diff, or a mux pane swap /
439    /// reattach — visible for a long time. A wall-clock bound guarantees the
440    /// physical terminal is fully repainted at least this often regardless of
441    /// render cadence, so any such corruption self-heals within the interval.
442    ///
443    /// `None` (the default) disables the time-based resync, preserving the
444    /// purely frame-count behavior (and deterministic-test reproducibility).
445    pub full_redraw_max_interval: Option<std::time::Duration>,
446}
447
448impl Default for RuntimeDiffConfig {
449    fn default() -> Self {
450        Self {
451            bayesian_enabled: true,
452            dirty_rows_enabled: true,
453            certified_skips: true,
454            dirty_span_config: DirtySpanConfig::default(),
455            tile_diff_config: TileDiffConfig::default(),
456            reset_on_resize: true,
457            reset_on_invalidation: true,
458            strategy_config: DiffStrategyConfig::default(),
459            full_redraw_interval_frames: 240,
460            full_redraw_max_interval: None,
461        }
462    }
463}
464
465impl RuntimeDiffConfig {
466    /// Create a new config with all defaults.
467    pub fn new() -> Self {
468        Self::default()
469    }
470
471    /// Set whether Bayesian strategy selection is enabled.
472    #[must_use]
473    pub fn with_bayesian_enabled(mut self, enabled: bool) -> Self {
474        self.bayesian_enabled = enabled;
475        self
476    }
477
478    /// Set whether dirty-row optimization is enabled.
479    #[must_use]
480    pub fn with_dirty_rows_enabled(mut self, enabled: bool) -> Self {
481        self.dirty_rows_enabled = enabled;
482        self
483    }
484
485    /// Set whether dirty-span tracking is enabled.
486    #[must_use]
487    pub fn with_dirty_spans_enabled(mut self, enabled: bool) -> Self {
488        self.dirty_span_config = self.dirty_span_config.with_enabled(enabled);
489        self
490    }
491
492    /// Set the dirty-span tracking configuration.
493    #[must_use]
494    pub fn with_dirty_span_config(mut self, config: DirtySpanConfig) -> Self {
495        self.dirty_span_config = config;
496        self
497    }
498
499    /// Toggle tile-based skipping.
500    #[must_use]
501    pub fn with_tile_skip_enabled(mut self, enabled: bool) -> Self {
502        self.tile_diff_config = self.tile_diff_config.with_enabled(enabled);
503        self
504    }
505
506    /// Set the tile-based diff configuration.
507    #[must_use]
508    pub fn with_tile_diff_config(mut self, config: TileDiffConfig) -> Self {
509        self.tile_diff_config = config;
510        self
511    }
512
513    /// Set whether to reset posterior on resize.
514    #[must_use]
515    pub fn with_reset_on_resize(mut self, enabled: bool) -> Self {
516        self.reset_on_resize = enabled;
517        self
518    }
519
520    /// Set whether to reset posterior on invalidation.
521    #[must_use]
522    pub fn with_reset_on_invalidation(mut self, enabled: bool) -> Self {
523        self.reset_on_invalidation = enabled;
524        self
525    }
526
527    /// Set the underlying strategy configuration.
528    #[must_use]
529    pub fn with_strategy_config(mut self, config: DiffStrategyConfig) -> Self {
530        self.strategy_config = config;
531        self
532    }
533
534    /// Set the maximum successful incremental frames between physical full redraws.
535    ///
536    /// A value of `0` disables periodic terminal resynchronization.
537    #[must_use]
538    pub fn with_full_redraw_interval_frames(mut self, frames: u64) -> Self {
539        self.full_redraw_interval_frames = frames;
540        self
541    }
542
543    /// Set the maximum wall-clock time between physical full redraws.
544    ///
545    /// Unlike [`Self::with_full_redraw_interval_frames`] (which only advances on
546    /// rendered frames), this bounds resynchronization by elapsed time, so an
547    /// idle or sparsely-rendering TUI still repaints the physical terminal at
548    /// least this often — bounding how long any terminal-state desync (diff
549    /// corruption, mux pane swap, reattach) can stay on screen. `None` disables
550    /// it.
551    #[must_use]
552    pub fn with_full_redraw_max_interval(mut self, interval: Option<std::time::Duration>) -> Self {
553        self.full_redraw_max_interval = interval;
554        self
555    }
556}
557
558/// Unified terminal output coordinator.
559///
560/// Enforces the one-writer rule and implements inline mode correctly.
561/// All terminal output should go through this struct.
562pub struct TerminalWriter<W: Write> {
563    /// Presenter handles efficient ANSI emission and cursor tracking.
564    /// Wrapped in `Option` so `into_inner` can take ownership; `Drop` skips
565    /// cleanup when `None` (already consumed).
566    presenter: Option<Presenter<W>>,
567    /// Current screen mode.
568    screen_mode: ScreenMode,
569    /// Last computed auto UI height (inline auto mode only).
570    auto_ui_height: Option<u16>,
571    /// Where UI is anchored in inline mode.
572    ui_anchor: UiAnchor,
573    /// Previous buffer for diffing.
574    prev_buffer: Option<Buffer>,
575    /// Spare buffer for reuse as the next render target.
576    spare_buffer: Option<Buffer>,
577    /// Pre-allocated buffer for zero-alloc clone in present_ui.
578    /// Part of a 3-buffer rotation: spare ← prev ← clone_buf ← spare.
579    clone_buf: Option<Buffer>,
580    /// Grapheme pool for complex characters.
581    pool: GraphemePool,
582    /// Link registry for hyperlinks.
583    links: LinkRegistry,
584    /// Terminal capabilities.
585    capabilities: TerminalCapabilities,
586    /// Terminal width in columns.
587    term_width: u16,
588    /// Terminal height in rows.
589    term_height: u16,
590    /// Whether we're in the middle of a sync block.
591    in_sync_block: bool,
592    /// Whether cursor has been saved.
593    cursor_saved: bool,
594    /// Current cursor visibility state (best-effort).
595    cursor_visible: bool,
596    /// Inline mode rendering strategy (selected from capabilities).
597    inline_strategy: InlineStrategy,
598    /// Whether a scroll region is currently active.
599    scroll_region_active: bool,
600    /// DECSTBM self-test verdict (`None`: not run).
601    scroll_region_verified: Option<bool>,
602    /// Strategy fallback taken because of the self-test, exported with the
603    /// capability ledger.
604    strategy_fallback: Option<InlineStrategyFallback>,
605    /// Last inline UI region for clearing on shrink.
606    last_inline_region: Option<InlineRegion>,
607    /// Bayesian diff strategy selector.
608    diff_strategy: DiffStrategySelector,
609    /// Reusable diff buffer to avoid per-frame allocations.
610    diff_scratch: BufferDiff,
611    /// Frames since last diff probe while in FullRedraw.
612    full_redraw_probe: u64,
613    /// Successful incremental frames since the terminal was physically redrawn.
614    frames_since_full_redraw: u64,
615    /// Wall-clock instant of the last physical full redraw, used to bound
616    /// terminal-state desync by elapsed time (see
617    /// [`RuntimeDiffConfig::full_redraw_max_interval`]). `None` until the first
618    /// full redraw is presented.
619    last_full_redraw_at: Option<Instant>,
620    /// Runtime diff configuration.
621    #[allow(dead_code)] // runtime toggles wired up in follow-up work
622    diff_config: RuntimeDiffConfig,
623    /// Evidence JSONL sink for diff decisions.
624    evidence_sink: Option<EvidenceSink>,
625    /// Capability decision ledger from the live probe, held until an evidence
626    /// sink is attached and then written out once (drained).
627    capability_decisions: Vec<CapabilityDecision>,
628    /// Run identifier for diff decision evidence.
629    #[allow(dead_code)]
630    /// The explicit skip certificate for the most recent diff decision.
631    last_certificate: Option<RenderCertificate>,
632    diff_evidence_run_id: String,
633    /// Monotonic event index for diff decision evidence.
634    #[allow(dead_code)]
635    diff_evidence_idx: u64,
636    /// Last diff strategy selected during present.
637    last_diff_strategy: Option<DiffStrategy>,
638    /// Render-trace recorder (optional).
639    render_trace: Option<RenderTraceRecorder>,
640    /// Whether per-frame timing capture is enabled.
641    timing_enabled: bool,
642    /// Last present timings (diff compute duration).
643    last_present_timings: Option<PresentTimings>,
644    /// Current diff regime classification.
645    diff_regime: DiffRegime,
646    /// Number of consecutive frames spent in the current diff regime.
647    diff_regime_frames: u64,
648}
649
650impl<W: Write> TerminalWriter<W> {
651    /// Create a new terminal writer.
652    ///
653    /// # Arguments
654    ///
655    /// * `writer` - Output destination (takes ownership for one-writer rule)
656    /// * `screen_mode` - Inline or alternate screen mode
657    /// * `ui_anchor` - Where to anchor UI in inline mode
658    /// * `capabilities` - Terminal capabilities
659    pub fn new(
660        writer: W,
661        screen_mode: ScreenMode,
662        ui_anchor: UiAnchor,
663        capabilities: TerminalCapabilities,
664    ) -> Self {
665        Self::with_diff_config(
666            writer,
667            screen_mode,
668            ui_anchor,
669            capabilities,
670            RuntimeDiffConfig::default(),
671        )
672    }
673
674    /// Create a new terminal writer with custom diff strategy configuration.
675    ///
676    /// # Arguments
677    ///
678    /// * `writer` - Output destination (takes ownership for one-writer rule)
679    /// * `screen_mode` - Inline or alternate screen mode
680    /// * `ui_anchor` - Where to anchor UI in inline mode
681    /// * `capabilities` - Terminal capabilities
682    /// * `diff_config` - Configuration for diff strategy selection
683    ///
684    /// # Example
685    ///
686    /// ```ignore
687    /// use ftui_runtime::{TerminalWriter, ScreenMode, UiAnchor, RuntimeDiffConfig};
688    /// use ftui_core::terminal_capabilities::TerminalCapabilities;
689    ///
690    /// // Disable Bayesian selection for deterministic diffing
691    /// let config = RuntimeDiffConfig::default()
692    ///     .with_bayesian_enabled(false);
693    ///
694    /// let writer = TerminalWriter::with_diff_config(
695    ///     std::io::stdout(),
696    ///     ScreenMode::AltScreen,
697    ///     UiAnchor::Bottom,
698    ///     TerminalCapabilities::detect(),
699    ///     config,
700    /// );
701    /// ```
702    pub fn with_diff_config(
703        writer: W,
704        screen_mode: ScreenMode,
705        ui_anchor: UiAnchor,
706        capabilities: TerminalCapabilities,
707        diff_config: RuntimeDiffConfig,
708    ) -> Self {
709        let inline_strategy = InlineStrategy::select(&capabilities);
710        let auto_ui_height = None;
711        let diff_strategy = DiffStrategySelector::new(diff_config.strategy_config.clone());
712
713        // Increment the inline-active gauge.
714        // We do this BEFORE potentially returning/panicking to maintain invariant
715        // that a TerminalWriter in inline mode ALWAYS has a corresponding increment,
716        // which will be decremented on Drop.
717        let is_inline = matches!(
718            screen_mode,
719            ScreenMode::Inline { .. } | ScreenMode::InlineAuto { .. }
720        );
721        if is_inline {
722            INLINE_ACTIVE_WIDGETS.fetch_add(1, Ordering::SeqCst);
723        }
724
725        // Log inline mode activation.
726        match screen_mode {
727            ScreenMode::Inline { ui_height } => {
728                info!(
729                    inline_height = ui_height,
730                    render_mode = %inline_strategy_str(inline_strategy),
731                    "inline mode activated"
732                );
733            }
734            ScreenMode::InlineAuto {
735                min_height,
736                max_height,
737            } => {
738                info!(
739                    min_height,
740                    max_height,
741                    render_mode = %inline_strategy_str(inline_strategy),
742                    "inline auto mode activated"
743                );
744            }
745            ScreenMode::AltScreen => {}
746        }
747
748        let mut diff_scratch = BufferDiff::new();
749        diff_scratch
750            .tile_config_mut()
751            .clone_from(&diff_config.tile_diff_config);
752
753        let presenter = Presenter::new(writer, capabilities);
754
755        Self {
756            presenter: Some(presenter),
757            screen_mode,
758            auto_ui_height,
759            ui_anchor,
760            prev_buffer: None,
761            spare_buffer: None,
762            clone_buf: None,
763            pool: GraphemePool::new(),
764            links: LinkRegistry::new(),
765            capabilities,
766            term_width: 80,
767            term_height: 24,
768            in_sync_block: false,
769            cursor_saved: false,
770            cursor_visible: true,
771            inline_strategy,
772            scroll_region_active: false,
773            scroll_region_verified: None,
774            strategy_fallback: None,
775            last_inline_region: None,
776            diff_strategy,
777            diff_scratch,
778            full_redraw_probe: 0,
779            frames_since_full_redraw: 0,
780            last_full_redraw_at: None,
781            diff_config,
782            evidence_sink: None,
783            capability_decisions: Vec::new(),
784            diff_evidence_run_id: default_diff_run_id(),
785            diff_evidence_idx: 0,
786            last_diff_strategy: None,
787            last_certificate: None,
788            render_trace: None,
789            timing_enabled: false,
790            last_present_timings: None,
791            diff_regime: DiffRegime::Sparse,
792            diff_regime_frames: 0,
793        }
794    }
795
796    /// Get a mutable reference to the internal counting writer.
797    ///
798    /// # Panics
799    ///
800    /// Panics if the presenter has been taken (via `into_inner`).
801    #[inline]
802    fn writer(&mut self) -> &mut CountingWriter<BufWriter<W>> {
803        self.presenter_mut().counting_writer_mut()
804    }
805
806    /// Get a mutable reference to the presenter.
807    ///
808    /// # Panics
809    ///
810    /// Panics if the presenter has been taken (via `into_inner`).
811    #[inline]
812    fn presenter_mut(&mut self) -> &mut Presenter<W> {
813        self.presenter
814            .as_mut()
815            .expect("presenter has been consumed")
816    }
817
818    /// Reset diff strategy state when the previous buffer is invalidated.
819    fn reset_diff_strategy(&mut self) {
820        if self.diff_config.reset_on_invalidation {
821            self.diff_strategy.reset();
822        }
823        self.full_redraw_probe = 0;
824        self.frames_since_full_redraw = 0;
825        self.last_diff_strategy = None;
826    }
827
828    /// Reset diff strategy state on terminal resize.
829    #[allow(dead_code)] // used by upcoming resize-aware diff strategy work
830    fn reset_diff_on_resize(&mut self) {
831        if self.diff_config.reset_on_resize {
832            self.diff_strategy.reset();
833        }
834        self.full_redraw_probe = 0;
835        self.frames_since_full_redraw = 0;
836        self.last_diff_strategy = None;
837    }
838
839    /// Get the current diff configuration.
840    pub fn diff_config(&self) -> &RuntimeDiffConfig {
841        &self.diff_config
842    }
843
844    /// Enable or disable per-frame timing capture.
845    pub(crate) fn set_timing_enabled(&mut self, enabled: bool) {
846        self.timing_enabled = enabled;
847        if !enabled {
848            self.last_present_timings = None;
849        }
850    }
851
852    /// Take the last present timings (if available).
853    pub fn take_last_present_timings(&mut self) -> Option<PresentTimings> {
854        self.last_present_timings.take()
855    }
856
857    /// Access the last present timings (if available).
858    #[must_use]
859    pub fn last_present_timings(&self) -> Option<&PresentTimings> {
860        self.last_present_timings.as_ref()
861    }
862
863    /// Attach an evidence sink for diff decision logging.
864    #[must_use]
865    pub fn with_evidence_sink(mut self, sink: EvidenceSink) -> Self {
866        self.evidence_sink = Some(sink);
867        self.export_capability_decisions();
868        self
869    }
870
871    /// Set the evidence JSONL sink for diff decision logging.
872    pub fn set_evidence_sink(&mut self, sink: Option<EvidenceSink>) {
873        self.evidence_sink = sink;
874        self.export_capability_decisions();
875    }
876
877    /// Set a callback that receives every formatted JSONL evidence line.
878    pub fn set_evidence_callback(&mut self, callback: Option<Arc<dyn Fn(&str) + Send + Sync>>) {
879        if let Some(cb) = callback {
880            self.set_evidence_sink(Some(EvidenceSink::from_writer(CallbackEvidenceWriter(cb))));
881        } else {
882            self.set_evidence_sink(None);
883        }
884    }
885
886    /// Attach the capability decision ledger produced by the live terminal
887    /// probe. The rows are written to the evidence sink as
888    /// `capability_decision` events, followed by one `inline_strategy` event
889    /// naming the strategy selected from those capabilities, as soon as both
890    /// the ledger and a sink are present (in either order).
891    #[must_use]
892    pub fn with_capability_decisions(mut self, decisions: Vec<CapabilityDecision>) -> Self {
893        self.capability_decisions = decisions;
894        self.export_capability_decisions();
895        self
896    }
897
898    fn export_capability_decisions(&mut self) {
899        let Some(sink) = self.evidence_sink.as_ref() else {
900            return;
901        };
902        if self.capability_decisions.is_empty() && self.strategy_fallback.is_none() {
903            return;
904        }
905        for decision in self.capability_decisions.drain(..) {
906            let _ = sink.write_jsonl(&decision.to_jsonl());
907        }
908        if let Some(fallback) = self.strategy_fallback.take() {
909            let _ = sink.write_jsonl(&fallback.to_jsonl());
910        }
911        let verified = self
912            .scroll_region_verified
913            .map_or_else(|| "null".to_string(), |v| v.to_string());
914        let _ = sink.write_jsonl(&format!(
915            r#"{{"event":"inline_strategy","strategy":"{}","use_scroll_region":{},"use_sync_output":{},"in_mux":{},"scroll_region_verified":{}}}"#,
916            inline_strategy_str(self.inline_strategy),
917            self.capabilities.use_scroll_region(),
918            self.capabilities.use_sync_output(),
919            self.capabilities.in_any_mux(),
920            verified
921        ));
922    }
923
924    /// Attach a render-trace recorder.
925    #[must_use]
926    pub fn with_render_trace(mut self, recorder: RenderTraceRecorder) -> Self {
927        self.render_trace = Some(recorder);
928        self
929    }
930
931    /// Set the render-trace recorder.
932    pub fn set_render_trace(&mut self, recorder: Option<RenderTraceRecorder>) {
933        self.render_trace = recorder;
934    }
935
936    /// Get mutable access to the diff strategy selector.
937    ///
938    /// Useful for advanced scenarios like manual posterior updates.
939    pub fn diff_strategy_mut(&mut self) -> &mut DiffStrategySelector {
940        &mut self.diff_strategy
941    }
942
943    /// Get the diff strategy selector (read-only).
944    pub fn diff_strategy(&self) -> &DiffStrategySelector {
945        &self.diff_strategy
946    }
947
948    /// Get the last diff strategy selected during present, if any.
949    pub fn last_diff_strategy(&self) -> Option<DiffStrategy> {
950        self.last_diff_strategy
951    }
952
953    /// Current diff regime classification.
954    #[must_use]
955    pub fn diff_regime(&self) -> DiffRegime {
956        self.diff_regime
957    }
958
959    /// Number of consecutive frames spent in the current diff regime.
960    #[must_use]
961    pub fn diff_regime_frames(&self) -> u64 {
962        self.diff_regime_frames
963    }
964
965    /// The explicit render certificate behind the most recent diff decision
966    /// (`None` before the first present or when certified skips are
967    /// disabled).
968    #[must_use]
969    pub fn last_render_certificate(&self) -> Option<&RenderCertificate> {
970        self.last_certificate.as_ref()
971    }
972
973    /// Set the terminal size.
974    ///
975    /// Call this when the terminal is resized.
976    pub fn set_size(&mut self, width: u16, height: u16) {
977        // May emit a DECSTBM reset when a scroll region is active; keep it
978        // inside the one-writer discipline (bd-kdn7n item 2).
979        let _output_guard = terminal_output_lock();
980        self.term_width = width;
981        self.term_height = height;
982        if matches!(self.screen_mode, ScreenMode::InlineAuto { .. }) {
983            self.auto_ui_height = None;
984        }
985        // Clear prev_buffer to force full redraw after resize
986        self.prev_buffer = None;
987        // Old-geometry coordinates are meaningless after a resize: drop the
988        // displayed-region cache so neither log positioning nor
989        // clear_inline_region_diff acts on rows that no longer exist.
990        self.last_inline_region = None;
991        self.spare_buffer = None;
992        self.clone_buf = None;
993        self.reset_diff_on_resize();
994        // Reset scroll region on resize; it will be re-established on next present
995        if self.scroll_region_active {
996            let _ = self.deactivate_scroll_region();
997        }
998    }
999
1000    /// Take a reusable render buffer sized for the current frame.
1001    ///
1002    /// Uses a spare buffer when available to avoid per-frame allocation.
1003    pub fn take_render_buffer(&mut self, width: u16, height: u16) -> Buffer {
1004        if let Some(mut buffer) = self.spare_buffer.take()
1005            && buffer.width() == width
1006            && buffer.height() == height
1007        {
1008            buffer.set_dirty_span_config(self.diff_config.dirty_span_config);
1009            buffer.reset_for_frame();
1010            return buffer;
1011        }
1012
1013        let mut buffer = Buffer::new(width, height);
1014        buffer.set_dirty_span_config(self.diff_config.dirty_span_config);
1015        buffer
1016    }
1017
1018    /// Get the current terminal width.
1019    #[inline]
1020    pub fn width(&self) -> u16 {
1021        self.term_width
1022    }
1023
1024    /// Get the current terminal height.
1025    #[inline]
1026    pub fn height(&self) -> u16 {
1027        self.term_height
1028    }
1029
1030    /// Get the current screen mode.
1031    #[inline]
1032    pub fn screen_mode(&self) -> ScreenMode {
1033        self.screen_mode
1034    }
1035
1036    /// Set the screen mode.
1037    #[inline]
1038    pub fn set_screen_mode(&mut self, mode: ScreenMode) {
1039        self.screen_mode = mode;
1040    }
1041
1042    /// Height to use for rendering a frame.
1043    ///
1044    /// Fixed inline heights are clamped to the current terminal height so
1045    /// models lay out their controls within the rows that can be presented.
1046    /// In inline auto mode, this returns the configured maximum (clamped to
1047    /// terminal height) so measurement can determine actual UI height.
1048    pub fn render_height_hint(&self) -> u16 {
1049        match self.screen_mode {
1050            ScreenMode::Inline { ui_height } => ui_height.min(self.term_height),
1051            ScreenMode::InlineAuto {
1052                min_height,
1053                max_height,
1054            } => {
1055                let (min, max) = sanitize_auto_bounds(min_height, max_height);
1056                let max = max.min(self.term_height);
1057                let min = min.min(max);
1058                if let Some(current) = self.auto_ui_height {
1059                    current.clamp(min, max).min(self.term_height).max(min)
1060                } else {
1061                    max.max(min)
1062                }
1063            }
1064            ScreenMode::AltScreen => self.term_height,
1065        }
1066    }
1067
1068    /// Get sanitized min/max bounds for inline auto mode (clamped to terminal height).
1069    pub fn inline_auto_bounds(&self) -> Option<(u16, u16)> {
1070        match self.screen_mode {
1071            ScreenMode::InlineAuto {
1072                min_height,
1073                max_height,
1074            } => {
1075                let (min, max) = sanitize_auto_bounds(min_height, max_height);
1076                Some((min.min(self.term_height), max.min(self.term_height)))
1077            }
1078            _ => None,
1079        }
1080    }
1081
1082    /// Get the cached auto UI height (inline auto mode only).
1083    pub fn auto_ui_height(&self) -> Option<u16> {
1084        match self.screen_mode {
1085            ScreenMode::InlineAuto { .. } => self.auto_ui_height,
1086            _ => None,
1087        }
1088    }
1089
1090    /// Update the computed height for inline auto mode.
1091    pub fn set_auto_ui_height(&mut self, height: u16) {
1092        if let ScreenMode::InlineAuto {
1093            min_height,
1094            max_height,
1095        } = self.screen_mode
1096        {
1097            let (min, max) = sanitize_auto_bounds(min_height, max_height);
1098            let max = max.min(self.term_height);
1099            let min = min.min(max);
1100            let clamped = height.clamp(min, max);
1101            let previous_effective = self.auto_ui_height.unwrap_or(min);
1102            if self.auto_ui_height != Some(clamped) {
1103                self.auto_ui_height = Some(clamped);
1104                if clamped != previous_effective {
1105                    self.prev_buffer = None;
1106                    self.reset_diff_strategy();
1107                    if self.scroll_region_active {
1108                        let _ = self.deactivate_scroll_region();
1109                    }
1110                }
1111            }
1112        }
1113    }
1114
1115    /// Clear the cached auto UI height (inline auto mode only).
1116    pub fn clear_auto_ui_height(&mut self) {
1117        if matches!(self.screen_mode, ScreenMode::InlineAuto { .. })
1118            && self.auto_ui_height.is_some()
1119        {
1120            self.auto_ui_height = None;
1121            self.prev_buffer = None;
1122            self.reset_diff_strategy();
1123            if self.scroll_region_active {
1124                let _ = self.deactivate_scroll_region();
1125            }
1126        }
1127    }
1128
1129    fn effective_ui_height(&self) -> u16 {
1130        match self.screen_mode {
1131            ScreenMode::Inline { ui_height } => ui_height,
1132            ScreenMode::InlineAuto {
1133                min_height,
1134                max_height,
1135            } => {
1136                let (min, max) = sanitize_auto_bounds(min_height, max_height);
1137                let current = self.auto_ui_height.unwrap_or(min);
1138                current.clamp(min, max).min(self.term_height)
1139            }
1140            ScreenMode::AltScreen => self.term_height,
1141        }
1142    }
1143
1144    /// Get the UI height for the current mode.
1145    pub fn ui_height(&self) -> u16 {
1146        self.effective_ui_height()
1147    }
1148
1149    /// Calculate the row where the UI starts (0-indexed).
1150    fn ui_start_row(&self) -> u16 {
1151        let ui_height = self.effective_ui_height().min(self.term_height);
1152        match (self.screen_mode, self.ui_anchor) {
1153            (ScreenMode::Inline { .. }, UiAnchor::Bottom)
1154            | (ScreenMode::InlineAuto { .. }, UiAnchor::Bottom) => {
1155                self.term_height.saturating_sub(ui_height)
1156            }
1157            (ScreenMode::Inline { .. }, UiAnchor::Top)
1158            | (ScreenMode::InlineAuto { .. }, UiAnchor::Top) => 0,
1159            (ScreenMode::AltScreen, _) => 0,
1160        }
1161    }
1162
1163    /// Get the inline mode rendering strategy.
1164    pub fn inline_strategy(&self) -> InlineStrategy {
1165        self.inline_strategy
1166    }
1167
1168    /// Check if a scroll region is currently active.
1169    pub fn scroll_region_active(&self) -> bool {
1170        self.scroll_region_active
1171    }
1172
1173    /// The DECSTBM self-test verdict recorded by
1174    /// [`Self::set_scroll_region_verified`] (`None`: not run).
1175    pub fn scroll_region_verified(&self) -> Option<bool> {
1176        self.scroll_region_verified
1177    }
1178
1179    /// The strategy fallback the self-test forced, if any.
1180    pub fn strategy_fallback(&self) -> Option<&InlineStrategyFallback> {
1181        self.strategy_fallback.as_ref()
1182    }
1183
1184    /// Record the DECSTBM self-test verdict
1185    /// (`ftui_core::caps_probe::probe_scroll_region`), taken by the runtime
1186    /// at construction time before the input reader starts. A negative
1187    /// verdict while the strategy is `ScrollRegion` or `Hybrid` switches the
1188    /// writer to `OverlayRedraw` before its first frame, so a terminal that
1189    /// ignores DECSTBM never scrolls the whole screen into the UI; the
1190    /// fallback is exported as an `inline_strategy_fallback` evidence row
1191    /// when a sink attaches. `None` leaves the strategy as selected.
1192    pub fn set_scroll_region_verified(
1193        &mut self,
1194        verdict: Option<ftui_core::caps_probe::ScrollRegionVerdict>,
1195        rows: u16,
1196        region_bottom: u16,
1197    ) {
1198        let Some(verdict) = verdict else {
1199            self.scroll_region_verified = None;
1200            return;
1201        };
1202        self.scroll_region_verified = Some(verdict.honoured());
1203        if verdict.honoured() {
1204            return;
1205        }
1206        let from = self.inline_strategy;
1207        if !matches!(from, InlineStrategy::ScrollRegion | InlineStrategy::Hybrid) {
1208            return;
1209        }
1210        self.inline_strategy = InlineStrategy::OverlayRedraw;
1211        if self.scroll_region_active {
1212            let _ = self.deactivate_scroll_region();
1213        }
1214        let fallback = InlineStrategyFallback {
1215            from,
1216            reason: verdict.fallback_reason().unwrap_or("cpr_mismatch"),
1217            observed_row: verdict.observed_row(),
1218            expected_row: region_bottom,
1219            rows,
1220            region_bottom,
1221        };
1222        tracing::warn!(
1223            target: crate::telemetry_schema::span::RENDER_SCROLL_REGION,
1224            from = inline_strategy_str(from),
1225            to = "overlay_redraw",
1226            reason = fallback.reason,
1227            observed_row = ?fallback.observed_row,
1228            expected_row = fallback.expected_row,
1229            rows,
1230            "DECSTBM self-test failed: inline strategy falls back to overlay redraw"
1231        );
1232        if let Some(sink) = self.evidence_sink.as_ref() {
1233            let _ = sink.write_jsonl(&fallback.to_jsonl());
1234            self.strategy_fallback = None;
1235        } else {
1236            self.strategy_fallback = Some(fallback);
1237        }
1238    }
1239
1240    /// Activate the scroll region for inline mode.
1241    ///
1242    /// Sets DECSTBM to constrain scrolling to the log region:
1243    /// - Bottom-anchored UI: log region is above the UI.
1244    /// - Top-anchored UI: log region is below the UI.
1245    ///
1246    /// Only called when the strategy permits scroll-region usage.
1247    fn activate_scroll_region(&mut self, ui_height: u16) -> io::Result<()> {
1248        if self.scroll_region_active {
1249            return Ok(());
1250        }
1251
1252        let ui_height = ui_height.min(self.term_height);
1253        if self.term_height.saturating_sub(ui_height) < 2 {
1254            // DECSTBM requires top < bottom. A one-row log area must use
1255            // overlay writes; treating a rejected region as active would
1256            // allow an ordinary LF to scroll the entire screen.
1257            return Ok(());
1258        }
1259
1260        match self.ui_anchor {
1261            UiAnchor::Bottom => {
1262                let term_height = self.term_height;
1263                let log_bottom = term_height.saturating_sub(ui_height);
1264                if log_bottom > 0 {
1265                    // DECSTBM: set scroll region to rows 1..log_bottom (1-indexed)
1266                    write!(self.writer(), "\x1b[1;{}r", log_bottom)?;
1267                    self.scroll_region_active = true;
1268                }
1269            }
1270            UiAnchor::Top => {
1271                let term_height = self.term_height;
1272                let log_top = ui_height.saturating_add(1);
1273                if log_top <= term_height {
1274                    // DECSTBM: set scroll region to rows log_top..term_height (1-indexed)
1275                    write!(self.writer(), "\x1b[{};{}r", log_top, term_height)?;
1276                    self.scroll_region_active = true;
1277                    // DECSTBM moves cursor to home; for top-anchored UI we move it
1278                    // into the log region so any subsequent output stays below UI.
1279                    write!(self.writer(), "\x1b[{};1H", log_top)?;
1280                }
1281            }
1282        }
1283        Ok(())
1284    }
1285
1286    /// Deactivate the scroll region, resetting to full screen.
1287    fn deactivate_scroll_region(&mut self) -> io::Result<()> {
1288        if self.scroll_region_active {
1289            self.writer().write_all(b"\x1b[r")?;
1290            self.scroll_region_active = false;
1291        }
1292        Ok(())
1293    }
1294
1295    fn clear_rows(&mut self, start_row: u16, height: u16) -> io::Result<()> {
1296        let start_row = start_row.min(self.term_height);
1297        let end_row = start_row.saturating_add(height).min(self.term_height);
1298        if start_row >= end_row {
1299            return Ok(());
1300        }
1301
1302        // Ensure erase operations clear to the terminal default background.
1303        // Without this, stale background fills can persist when inline regions shrink.
1304        self.writer().write_all(SGR_BG_DEFAULT)?;
1305        for row in start_row..end_row {
1306            write!(self.writer(), "\x1b[{};1H", row.saturating_add(1))?;
1307            self.writer().write_all(ERASE_LINE)?;
1308        }
1309        Ok(())
1310    }
1311
1312    fn clear_inline_region_diff(&mut self, current: InlineRegion) -> io::Result<()> {
1313        let Some(previous) = self.last_inline_region else {
1314            return Ok(());
1315        };
1316
1317        let prev_start = previous.start.min(self.term_height);
1318        let prev_end = previous
1319            .start
1320            .saturating_add(previous.height)
1321            .min(self.term_height);
1322        if prev_start >= prev_end {
1323            return Ok(());
1324        }
1325
1326        let curr_start = current.start.min(self.term_height);
1327        let curr_end = current
1328            .start
1329            .saturating_add(current.height)
1330            .min(self.term_height);
1331
1332        if curr_start > prev_start {
1333            let clear_end = curr_start.min(prev_end);
1334            if clear_end > prev_start {
1335                self.clear_rows(prev_start, clear_end - prev_start)?;
1336            }
1337        }
1338
1339        if curr_end < prev_end {
1340            let clear_start = curr_end.max(prev_start);
1341            if prev_end > clear_start {
1342                self.clear_rows(clear_start, prev_end - clear_start)?;
1343            }
1344        }
1345
1346        Ok(())
1347    }
1348
1349    /// Present a UI frame.
1350    ///
1351    /// In inline mode, this:
1352    /// 1. Begins synchronized output (if supported)
1353    /// 2. Saves cursor position
1354    /// 3. Moves to UI region and clears it
1355    /// 4. Renders the buffer using the presenter
1356    /// 5. Restores cursor position
1357    /// 6. Moves cursor to requested UI position (if any)
1358    /// 7. Applies cursor visibility
1359    /// 8. Ends synchronized output
1360    ///
1361    /// In AltScreen mode, this just renders the buffer and positions cursor.
1362    pub fn present_ui(
1363        &mut self,
1364        buffer: &Buffer,
1365        cursor: Option<(u16, u16)>,
1366        cursor_visible: bool,
1367    ) -> io::Result<()> {
1368        // One-writer discipline vs the signal/panic teardown paths
1369        // (bd-kdn7n item 2): the whole frame is one emission batch.
1370        let _output_guard = terminal_output_lock();
1371        let mode_str = match self.screen_mode {
1372            ScreenMode::Inline { .. } => "inline",
1373            ScreenMode::InlineAuto { .. } => "inline_auto",
1374            ScreenMode::AltScreen => "altscreen",
1375        };
1376        let trace_enabled = self.render_trace.is_some();
1377        if trace_enabled {
1378            self.writer().reset_counter();
1379        }
1380        let present_start = if trace_enabled {
1381            Some(Instant::now())
1382        } else {
1383            None
1384        };
1385        let _span = info_span!(
1386            crate::telemetry_schema::span::RENDER_PRESENT,
1387            mode = mode_str,
1388            width = buffer.width(),
1389            height = buffer.height(),
1390        )
1391        .entered();
1392
1393        let result = match self.screen_mode {
1394            ScreenMode::Inline { ui_height } => {
1395                self.present_inline(buffer, ui_height, cursor, cursor_visible)
1396            }
1397            ScreenMode::InlineAuto { .. } => {
1398                let ui_height = self.effective_ui_height();
1399                self.present_inline(buffer, ui_height, cursor, cursor_visible)
1400            }
1401            ScreenMode::AltScreen => self.present_altscreen(buffer, cursor, cursor_visible),
1402        };
1403
1404        let present_us = present_start.map(|start| start.elapsed().as_micros() as u64);
1405        let present_bytes = if trace_enabled {
1406            {
1407                let w = self.writer();
1408                let count = w.bytes_written();
1409                w.reset_counter();
1410                Some(count)
1411            }
1412        } else {
1413            None
1414        };
1415        if trace_enabled {
1416            // No-op: ftui_render::CountingWriter always counts; reset happens in take above.
1417        }
1418
1419        if let Ok(stats) = result {
1420            self.record_successful_present(stats.diff_strategy);
1421            // 3-buffer rotation: reuse clone_buf's allocation to avoid per-frame alloc.
1422            // Only advance the diff baseline after a successful present. If a write
1423            // failed partway through, the terminal state is unknown; the error path
1424            // below invalidates the baseline so the next frame physically repaints.
1425            let new_prev = match self.clone_buf.take() {
1426                Some(mut buf)
1427                    if buf.width() == buffer.width() && buf.height() == buffer.height() =>
1428                {
1429                    buf.clone_from(buffer);
1430                    buf
1431                }
1432                _ => buffer.clone(),
1433            };
1434            self.clone_buf = self.spare_buffer.take();
1435            self.spare_buffer = self.prev_buffer.take();
1436            self.prev_buffer = Some(new_prev);
1437
1438            if let Some(ref mut trace) = self.render_trace {
1439                let payload_info = match stats.diff_strategy {
1440                    DiffStrategy::FullRedraw => {
1441                        let payload = build_full_buffer_payload(buffer, &self.pool);
1442                        trace.write_payload(&payload).ok()
1443                    }
1444                    _ => {
1445                        let payload =
1446                            build_diff_runs_payload(buffer, &self.diff_scratch, &self.pool);
1447                        trace.write_payload(&payload).ok()
1448                    }
1449                };
1450                let (payload_kind, payload_path) = match payload_info {
1451                    Some(info) => (info.kind, Some(info.path)),
1452                    None => ("none", None),
1453                };
1454                let payload_path_ref = payload_path.as_deref();
1455                let diff_strategy = diff_strategy_str(stats.diff_strategy);
1456                let ui_anchor = ui_anchor_str(self.ui_anchor);
1457                let frame = RenderTraceFrame {
1458                    cols: buffer.width(),
1459                    rows: buffer.height(),
1460                    mode: mode_str,
1461                    ui_height: stats.ui_height,
1462                    ui_anchor,
1463                    diff_strategy,
1464                    diff_cells: stats.diff_cells,
1465                    diff_runs: stats.diff_runs,
1466                    present_bytes: present_bytes.unwrap_or(0),
1467                    render_us: None,
1468                    present_us,
1469                    payload_kind,
1470                    payload_path: payload_path_ref,
1471                    trace_us: None,
1472                };
1473                let _ = trace.record_frame(frame, buffer, &self.pool);
1474            }
1475            return Ok(());
1476        }
1477
1478        self.invalidate_after_present_error();
1479        result.map(|_| ())
1480    }
1481
1482    /// Present a UI frame, taking ownership of the buffer (O(1) — no clone).
1483    ///
1484    /// Prefer this over `present_ui` when the caller has an owned buffer
1485    /// that won't be reused, as it avoids an O(width × height) clone.
1486    pub fn present_ui_owned(
1487        &mut self,
1488        buffer: Buffer,
1489        cursor: Option<(u16, u16)>,
1490        cursor_visible: bool,
1491    ) -> io::Result<()> {
1492        // One-writer discipline vs teardown paths (bd-kdn7n item 2).
1493        let _output_guard = terminal_output_lock();
1494        let mode_str = match self.screen_mode {
1495            ScreenMode::Inline { .. } => "inline",
1496            ScreenMode::InlineAuto { .. } => "inline_auto",
1497            ScreenMode::AltScreen => "altscreen",
1498        };
1499        let trace_enabled = self.render_trace.is_some();
1500        if trace_enabled {
1501            self.writer().reset_counter();
1502        }
1503        let present_start = if trace_enabled {
1504            Some(Instant::now())
1505        } else {
1506            None
1507        };
1508        let _span = info_span!(
1509            crate::telemetry_schema::span::RENDER_PRESENT,
1510            mode = mode_str,
1511            width = buffer.width(),
1512            height = buffer.height(),
1513        )
1514        .entered();
1515
1516        let result = match self.screen_mode {
1517            ScreenMode::Inline { ui_height } => {
1518                self.present_inline(&buffer, ui_height, cursor, cursor_visible)
1519            }
1520            ScreenMode::InlineAuto { .. } => {
1521                let ui_height = self.effective_ui_height();
1522                self.present_inline(&buffer, ui_height, cursor, cursor_visible)
1523            }
1524            ScreenMode::AltScreen => self.present_altscreen(&buffer, cursor, cursor_visible),
1525        };
1526
1527        let present_us = present_start.map(|start| start.elapsed().as_micros() as u64);
1528        let present_bytes = if trace_enabled {
1529            {
1530                let w = self.writer();
1531                let count = w.bytes_written();
1532                w.reset_counter();
1533                Some(count)
1534            }
1535        } else {
1536            None
1537        };
1538        if trace_enabled {
1539            // No-op: ftui_render::CountingWriter always counts; reset happens in take above.
1540        }
1541
1542        if let Ok(stats) = result {
1543            self.record_successful_present(stats.diff_strategy);
1544            if let Some(ref mut trace) = self.render_trace {
1545                let payload_info = match stats.diff_strategy {
1546                    DiffStrategy::FullRedraw => {
1547                        let payload = build_full_buffer_payload(&buffer, &self.pool);
1548                        trace.write_payload(&payload).ok()
1549                    }
1550                    _ => {
1551                        let payload =
1552                            build_diff_runs_payload(&buffer, &self.diff_scratch, &self.pool);
1553                        trace.write_payload(&payload).ok()
1554                    }
1555                };
1556                let (payload_kind, payload_path) = match payload_info {
1557                    Some(info) => (info.kind, Some(info.path)),
1558                    None => ("none", None),
1559                };
1560                let payload_path_ref = payload_path.as_deref();
1561                let diff_strategy = diff_strategy_str(stats.diff_strategy);
1562                let ui_anchor = ui_anchor_str(self.ui_anchor);
1563                let frame = RenderTraceFrame {
1564                    cols: buffer.width(),
1565                    rows: buffer.height(),
1566                    mode: mode_str,
1567                    ui_height: stats.ui_height,
1568                    ui_anchor,
1569                    diff_strategy,
1570                    diff_cells: stats.diff_cells,
1571                    diff_runs: stats.diff_runs,
1572                    present_bytes: present_bytes.unwrap_or(0),
1573                    render_us: None,
1574                    present_us,
1575                    payload_kind,
1576                    payload_path: payload_path_ref,
1577                    trace_us: None,
1578                };
1579                let _ = trace.record_frame(frame, &buffer, &self.pool);
1580            }
1581
1582            // 3-buffer rotation: keep clone_buf populated for present_ui path.
1583            self.clone_buf = self.spare_buffer.take();
1584            self.spare_buffer = self.prev_buffer.take();
1585            self.prev_buffer = Some(buffer);
1586            return Ok(());
1587        }
1588
1589        self.invalidate_after_present_error();
1590        result.map(|_| ())
1591    }
1592
1593    fn decide_diff(&mut self, buffer: &Buffer) -> DiffDecision {
1594        let prev_dims = self
1595            .prev_buffer
1596            .as_ref()
1597            .map(|prev| (prev.width(), prev.height()));
1598        if prev_dims.is_none() || prev_dims != Some((buffer.width(), buffer.height())) {
1599            self.full_redraw_probe = 0;
1600            self.last_diff_strategy = Some(DiffStrategy::FullRedraw);
1601            self.last_certificate = Some(evaluate_render_certificate(
1602                &RenderCertificateInputs {
1603                    prev_available: prev_dims.is_some(),
1604                    dims_changed: prev_dims.is_some(),
1605                    full_redraw_due: false,
1606                    dirty_row_count: buffer.dirty_row_count(),
1607                    total_rows: buffer.height(),
1608                },
1609                Vec::new(),
1610            ));
1611            return DiffDecision {
1612                strategy: DiffStrategy::FullRedraw,
1613                has_diff: false,
1614            };
1615        }
1616
1617        if self.full_redraw_interval_due() {
1618            self.full_redraw_probe = 0;
1619            self.last_diff_strategy = Some(DiffStrategy::FullRedraw);
1620            self.last_certificate = Some(evaluate_render_certificate(
1621                &RenderCertificateInputs {
1622                    prev_available: true,
1623                    dims_changed: false,
1624                    full_redraw_due: true,
1625                    dirty_row_count: buffer.dirty_row_count(),
1626                    total_rows: buffer.height(),
1627                },
1628                Vec::new(),
1629            ));
1630            return DiffDecision {
1631                strategy: DiffStrategy::FullRedraw,
1632                has_diff: false,
1633            };
1634        }
1635
1636        let dirty_rows = buffer.dirty_row_count();
1637        let width = buffer.width() as usize;
1638        let height = buffer.height() as usize;
1639        let mut span_stats_snapshot: Option<DirtySpanStats> = None;
1640        let mut dirty_scan_cells_estimate = dirty_rows.saturating_mul(width);
1641
1642        if self.diff_config.bayesian_enabled {
1643            let span_stats = buffer.dirty_span_stats();
1644            if span_stats.span_coverage_cells > 0 {
1645                dirty_scan_cells_estimate = span_stats.span_coverage_cells;
1646            }
1647            span_stats_snapshot = Some(span_stats);
1648        }
1649
1650        // Select strategy based on config
1651        let mut strategy = if self.diff_config.bayesian_enabled {
1652            // Use Bayesian selector
1653            self.diff_strategy.select_with_scan_estimate(
1654                buffer.width(),
1655                buffer.height(),
1656                dirty_rows,
1657                dirty_scan_cells_estimate,
1658            )
1659        } else {
1660            // Simple heuristic: use DirtyRows if few rows dirty, else Full
1661            if self.diff_config.dirty_rows_enabled && dirty_rows < buffer.height() as usize {
1662                DiffStrategy::DirtyRows
1663            } else {
1664                DiffStrategy::Full
1665            }
1666        };
1667
1668        // Enforce dirty_rows_enabled toggle
1669        if !self.diff_config.dirty_rows_enabled && strategy == DiffStrategy::DirtyRows {
1670            strategy = DiffStrategy::Full;
1671            if self.diff_config.bayesian_enabled {
1672                self.diff_strategy
1673                    .override_last_strategy(strategy, "dirty_rows_disabled");
1674            }
1675        }
1676
1677        // Periodic probe when FullRedraw is selected (to update posterior)
1678        if strategy == DiffStrategy::FullRedraw {
1679            if self.full_redraw_probe >= FULL_REDRAW_PROBE_INTERVAL {
1680                self.full_redraw_probe = 0;
1681                let probed = if self.diff_config.dirty_rows_enabled
1682                    && dirty_rows < buffer.height() as usize
1683                {
1684                    DiffStrategy::DirtyRows
1685                } else {
1686                    DiffStrategy::Full
1687                };
1688                if probed != strategy {
1689                    strategy = probed;
1690                    if self.diff_config.bayesian_enabled {
1691                        self.diff_strategy
1692                            .override_last_strategy(strategy, "full_redraw_probe");
1693                    }
1694                }
1695            } else {
1696                self.full_redraw_probe = self.full_redraw_probe.saturating_add(1);
1697            }
1698        } else {
1699            self.full_redraw_probe = 0;
1700        }
1701
1702        let mut has_diff = false;
1703        match strategy {
1704            DiffStrategy::Full => {
1705                let prev = self.prev_buffer.as_ref().expect("prev buffer must exist");
1706                self.diff_scratch.compute_into(prev, buffer);
1707                self.last_certificate = Some(RenderCertificate {
1708                    level: RenderCertificateLevel::FullRequired,
1709                    causes: vec!["strategy-selected-full"],
1710                    dirty_rows: Vec::new(),
1711                    fell_back: false,
1712                });
1713                has_diff = true;
1714            }
1715            DiffStrategy::DirtyRows => {
1716                let prev = self.prev_buffer.as_ref().expect("prev buffer must exist");
1717                if self.diff_config.certified_skips {
1718                    let certificate = evaluate_render_certificate(
1719                        &RenderCertificateInputs {
1720                            prev_available: true,
1721                            dims_changed: false,
1722                            full_redraw_due: false,
1723                            dirty_row_count: dirty_rows,
1724                            total_rows: buffer.height(),
1725                        },
1726                        buffer.dirty_row_indices(),
1727                    );
1728                    self.diff_scratch
1729                        .compute_certified_into(prev, buffer, certificate.to_hint());
1730                    self.last_certificate = Some(certificate);
1731                } else {
1732                    self.diff_scratch.compute_dirty_into(prev, buffer);
1733                    self.last_certificate = None;
1734                }
1735                has_diff = true;
1736            }
1737            DiffStrategy::FullRedraw => {}
1738        }
1739
1740        let mut scan_cost_estimate = 0usize;
1741        let mut fallback_reason: &'static str = "none";
1742        let tile_stats = if strategy == DiffStrategy::DirtyRows {
1743            self.diff_scratch.last_tile_stats()
1744        } else {
1745            None
1746        };
1747
1748        // Update posterior if Bayesian mode is enabled
1749        if self.diff_config.bayesian_enabled && has_diff {
1750            let span_stats = span_stats_snapshot.unwrap_or_else(|| buffer.dirty_span_stats());
1751            let (scan_cost, reason) = estimate_diff_scan_cost(
1752                strategy,
1753                dirty_rows,
1754                width,
1755                height,
1756                &span_stats,
1757                tile_stats,
1758            );
1759            let scanned_cells = scan_cost.max(self.diff_scratch.len());
1760            self.diff_strategy
1761                .observe(scanned_cells, self.diff_scratch.len());
1762            span_stats_snapshot = Some(span_stats);
1763            scan_cost_estimate = scan_cost;
1764            fallback_reason = reason;
1765        }
1766
1767        if let Some(evidence) = self.diff_strategy.last_evidence() {
1768            let span_stats = span_stats_snapshot.unwrap_or_else(|| buffer.dirty_span_stats());
1769            let (scan_cost, reason) = if span_stats_snapshot.is_some() {
1770                (scan_cost_estimate, fallback_reason)
1771            } else {
1772                estimate_diff_scan_cost(
1773                    strategy,
1774                    dirty_rows,
1775                    width,
1776                    height,
1777                    &span_stats,
1778                    tile_stats,
1779                )
1780            };
1781            let span_coverage_pct = if evidence.total_cells == 0 {
1782                0.0
1783            } else {
1784                (span_stats.span_coverage_cells as f64 / evidence.total_cells as f64) * 100.0
1785            };
1786            let span_count = span_stats.total_spans;
1787            let max_span_len = span_stats.max_span_len;
1788            let event_idx = self.diff_evidence_idx;
1789            self.diff_evidence_idx = self.diff_evidence_idx.saturating_add(1);
1790            let tile_used = tile_stats.is_some_and(|stats| stats.fallback.is_none());
1791            let tile_fallback = tile_stats
1792                .and_then(|stats| stats.fallback)
1793                .map(TileDiffFallback::as_str)
1794                .unwrap_or("none");
1795            let run_id = json_escape(&self.diff_evidence_run_id);
1796            let strategy_json = json_escape(&strategy.to_string());
1797            let guard_reason_json = json_escape(evidence.guard_reason);
1798            let fallback_reason_json = json_escape(reason);
1799            let tile_fallback_json = json_escape(tile_fallback);
1800            let schema_version = crate::evidence_sink::EVIDENCE_SCHEMA_VERSION;
1801            let screen_mode = match self.screen_mode {
1802                ScreenMode::Inline { .. } => "inline",
1803                ScreenMode::InlineAuto { .. } => "inline_auto",
1804                ScreenMode::AltScreen => "altscreen",
1805            };
1806            let (
1807                tile_w,
1808                tile_h,
1809                tiles_x,
1810                tiles_y,
1811                dirty_tiles,
1812                dirty_cells,
1813                dirty_tile_ratio,
1814                dirty_cell_ratio,
1815                scanned_tiles,
1816                skipped_tiles,
1817                scan_cells_estimate,
1818                sat_build_cells,
1819                skipped_tile_rows,
1820                sat_queries,
1821            ) = if let Some(stats) = tile_stats {
1822                (
1823                    stats.tile_w,
1824                    stats.tile_h,
1825                    stats.tiles_x,
1826                    stats.tiles_y,
1827                    stats.dirty_tiles,
1828                    stats.dirty_cells,
1829                    stats.dirty_tile_ratio,
1830                    stats.dirty_cell_ratio,
1831                    stats.scanned_tiles,
1832                    stats.skipped_tiles,
1833                    stats.scan_cells_estimate,
1834                    stats.sat_build_cells,
1835                    stats.skipped_tile_rows,
1836                    stats.sat_queries,
1837                )
1838            } else {
1839                let cell_ratio = if evidence.total_cells > 0 {
1840                    self.diff_scratch.len() as f64 / evidence.total_cells as f64
1841                } else {
1842                    0.0
1843                };
1844                (0, 0, 0, 0, 0, 0, 0.0, cell_ratio, 0, 0, 0, 0, 0, 0)
1845            };
1846            let tile_size = tile_w as usize * tile_h as usize;
1847            let dirty_tile_count = dirty_tiles;
1848            let skipped_tile_count = skipped_tiles;
1849            let sat_build_cost_est = sat_build_cells;
1850
1851            set_diff_snapshot(Some(DiffDecisionSnapshot {
1852                event_idx,
1853                screen_mode: screen_mode.to_string(),
1854                cols: u16::try_from(width).unwrap_or(u16::MAX),
1855                rows: u16::try_from(height).unwrap_or(u16::MAX),
1856                evidence: evidence.clone(),
1857                span_count,
1858                span_coverage_pct,
1859                max_span_len,
1860                scan_cost_estimate: scan_cost,
1861                fallback_reason: reason.to_string(),
1862                tile_used,
1863                tile_fallback: tile_fallback.to_string(),
1864                strategy_used: strategy,
1865            }));
1866
1867            let current_regime = DiffRegime::classify(strategy, dirty_cell_ratio);
1868
1869            trace!(
1870                strategy = %strategy,
1871                selected = %evidence.strategy,
1872                cost_full = evidence.cost_full,
1873                cost_dirty = evidence.cost_dirty,
1874                cost_redraw = evidence.cost_redraw,
1875                dirty_rows = evidence.dirty_rows,
1876                total_rows = evidence.total_rows,
1877                total_cells = evidence.total_cells,
1878                bayesian_enabled = self.diff_config.bayesian_enabled,
1879                dirty_rows_enabled = self.diff_config.dirty_rows_enabled,
1880                regime = %current_regime.as_str(),
1881                "diff strategy selected"
1882            );
1883            if let Some(ref sink) = self.evidence_sink {
1884                let line = format!(
1885                    r#"{{"schema_version":"{}","event":"diff_decision","run_id":"{}","event_idx":{},"screen_mode":"{}","cols":{},"rows":{},"strategy":"{}","cost_full":{:.6},"cost_dirty":{:.6},"cost_redraw":{:.6},"posterior_mean":{:.6},"posterior_variance":{:.6},"alpha":{:.6},"beta":{:.6},"guard_reason":"{}","hysteresis_applied":{},"hysteresis_ratio":{:.6},"dirty_rows":{},"total_rows":{},"total_cells":{},"span_count":{},"span_coverage_pct":{:.6},"max_span_len":{},"fallback_reason":"{}","scan_cost_estimate":{},"tile_used":{},"tile_fallback":"{}","tile_w":{},"tile_h":{},"tile_size":{},"tiles_x":{},"tiles_y":{},"dirty_tiles":{},"dirty_tile_count":{},"dirty_cells":{},"dirty_tile_ratio":{:.6},"dirty_cell_ratio":{:.6},"scanned_tiles":{},"skipped_tiles":{},"skipped_tile_count":{},"tile_scan_cells_estimate":{},"sat_build_cost_est":{},"skipped_tile_rows":{},"sat_queries":{},"bayesian_enabled":{},"dirty_rows_enabled":{},"regime":"{}"}}"#,
1886                    schema_version,
1887                    run_id,
1888                    event_idx,
1889                    screen_mode,
1890                    width,
1891                    height,
1892                    strategy_json,
1893                    evidence.cost_full,
1894                    evidence.cost_dirty,
1895                    evidence.cost_redraw,
1896                    evidence.posterior_mean,
1897                    evidence.posterior_variance,
1898                    evidence.alpha,
1899                    evidence.beta,
1900                    guard_reason_json,
1901                    evidence.hysteresis_applied,
1902                    evidence.hysteresis_ratio,
1903                    evidence.dirty_rows,
1904                    evidence.total_rows,
1905                    evidence.total_cells,
1906                    span_count,
1907                    span_coverage_pct,
1908                    max_span_len,
1909                    fallback_reason_json,
1910                    scan_cost,
1911                    tile_used,
1912                    tile_fallback_json,
1913                    tile_w,
1914                    tile_h,
1915                    tile_size,
1916                    tiles_x,
1917                    tiles_y,
1918                    dirty_tiles,
1919                    dirty_tile_count,
1920                    dirty_cells,
1921                    dirty_tile_ratio,
1922                    dirty_cell_ratio,
1923                    scanned_tiles,
1924                    skipped_tiles,
1925                    skipped_tile_count,
1926                    scan_cells_estimate,
1927                    sat_build_cost_est,
1928                    skipped_tile_rows,
1929                    sat_queries,
1930                    self.diff_config.bayesian_enabled,
1931                    self.diff_config.dirty_rows_enabled,
1932                    current_regime.as_str(),
1933                );
1934                let _ = sink.write_jsonl(&line);
1935            }
1936
1937            if current_regime != self.diff_regime {
1938                let transition_event_idx = self.diff_evidence_idx;
1939                self.diff_evidence_idx = self.diff_evidence_idx.saturating_add(1);
1940                if let Some(ref sink) = self.evidence_sink {
1941                    let transition_line = format!(
1942                        r#"{{"schema_version":"{}","event":"diff_regime_transition","run_id":"{}","event_idx":{},"from":"{}","to":"{}","frames_in_previous":{},"strategy":"{}","dirty_cell_ratio":{:.6}}}"#,
1943                        schema_version,
1944                        run_id,
1945                        transition_event_idx,
1946                        self.diff_regime.as_str(),
1947                        current_regime.as_str(),
1948                        self.diff_regime_frames,
1949                        strategy_json,
1950                        dirty_cell_ratio,
1951                    );
1952                    let _ = sink.write_jsonl(&transition_line);
1953                }
1954                self.diff_regime = current_regime;
1955                self.diff_regime_frames = 1;
1956            } else {
1957                self.diff_regime_frames = self.diff_regime_frames.saturating_add(1);
1958            }
1959        }
1960
1961        // Emit the explicit skip certificate alongside the diff decision so
1962        // operators can see WHY work was skipped or performed (bd-6b9nr).
1963        if let Some(ref certificate) = self.last_certificate
1964            && let Some(ref sink) = self.evidence_sink
1965        {
1966            let line = format!(
1967                r#"{{"event":"certificate_decision","run_id":"{}","event_idx":{},"strategy":"{:?}","certificate":{}}}"#,
1968                self.diff_evidence_run_id,
1969                self.diff_evidence_idx,
1970                strategy,
1971                certificate.to_evidence_json()
1972            );
1973            let _ = sink.write_jsonl(&line);
1974        }
1975
1976        self.last_diff_strategy = Some(strategy);
1977        DiffDecision { strategy, has_diff }
1978    }
1979
1980    fn full_redraw_interval_due(&self) -> bool {
1981        // Frame-count bound: resync after N rendered incremental frames.
1982        let frame_due = self.diff_config.full_redraw_interval_frames > 0
1983            && self.frames_since_full_redraw >= self.diff_config.full_redraw_interval_frames;
1984        // Wall-clock bound: resync after the configured elapsed time regardless
1985        // of how many frames have rendered. This is what bounds terminal-state
1986        // desync (diff corruption, mux pane swap, reattach) on a sparsely- or
1987        // idly-rendering TUI, where the frame counter advances too slowly. A
1988        // missing `last_full_redraw_at` (no full redraw presented yet) is
1989        // treated as due so the first eligible frame resynchronizes.
1990        let time_due = self
1991            .diff_config
1992            .full_redraw_max_interval
1993            .is_some_and(|interval| {
1994                self.last_full_redraw_at
1995                    .is_none_or(|at| at.elapsed() >= interval)
1996            });
1997        frame_due || time_due
1998    }
1999
2000    fn record_successful_present(&mut self, strategy: DiffStrategy) {
2001        if strategy == DiffStrategy::FullRedraw {
2002            self.frames_since_full_redraw = 0;
2003            // Anchor the wall-clock resync window to this physical full redraw.
2004            if self.diff_config.full_redraw_max_interval.is_some() {
2005                self.last_full_redraw_at = Some(Instant::now());
2006            }
2007        } else {
2008            self.frames_since_full_redraw = self.frames_since_full_redraw.saturating_add(1);
2009        }
2010    }
2011
2012    fn invalidate_after_present_error(&mut self) {
2013        self.prev_buffer = None;
2014        self.last_inline_region = None;
2015        self.reset_diff_strategy();
2016    }
2017
2018    /// Drop the diff baseline so the next present rewrites every cell, for a
2019    /// caller that knows the screen no longer matches what was presented.
2020    pub(crate) fn invalidate_diff_baseline(&mut self) {
2021        self.prev_buffer = None;
2022        self.reset_diff_strategy();
2023    }
2024
2025    /// Whether the cursor was last left visible (best-effort).
2026    pub(crate) const fn cursor_visible(&self) -> bool {
2027        self.cursor_visible
2028    }
2029
2030    /// Present UI in inline mode with cursor save/restore.
2031    ///
2032    /// When the scroll-region strategy is active, DECSTBM is set to constrain
2033    /// log scrolling to the region above the UI. This prevents log output from
2034    /// overwriting the UI, reducing redraw work.
2035    fn present_inline(
2036        &mut self,
2037        buffer: &Buffer,
2038        ui_height: u16,
2039        cursor: Option<(u16, u16)>,
2040        cursor_visible: bool,
2041    ) -> io::Result<FrameEmitStats> {
2042        let sync_output_enabled = self.capabilities.use_sync_output();
2043        let render_mode = inline_strategy_str(self.inline_strategy);
2044        let _inline_span = info_span!(
2045            "inline.render",
2046            inline_height = ui_height,
2047            scrollback_preserved = tracing::field::Empty,
2048            render_mode,
2049        )
2050        .entered();
2051
2052        let result = (|| -> io::Result<FrameEmitStats> {
2053            let visible_height = ui_height.min(self.term_height);
2054            let ui_y_start = self.ui_start_row();
2055            let current_region = InlineRegion {
2056                start: ui_y_start,
2057                height: visible_height,
2058            };
2059
2060            // Begin sync output if available
2061            if sync_output_enabled && !self.in_sync_block {
2062                // Mark active before write so cleanup paths conservatively emit
2063                // SYNC_END even if the begin write fails after partial bytes.
2064                self.in_sync_block = true;
2065                if let Err(err) = self.writer().write_all(SYNC_BEGIN) {
2066                    // Attempt immediate close to avoid leaving the terminal in a
2067                    // potentially open synchronized-output state.
2068                    let _ = self.writer().write_all(SYNC_END);
2069                    self.in_sync_block = false;
2070                    let _ = self.writer().flush();
2071                    return Err(err);
2072                }
2073            }
2074
2075            // Save cursor (DEC save)
2076            self.writer().write_all(CURSOR_SAVE)?;
2077            self.cursor_saved = true;
2078
2079            // Keep the hardware cursor hidden while we issue many cursor moves.
2080            // This prevents visible cursor "speckling" artifacts during redraws.
2081            self.set_cursor_visibility(false)?;
2082
2083            // Activate scroll region if strategy calls for it
2084            {
2085                let _span =
2086                    debug_span!(crate::telemetry_schema::span::RENDER_SCROLL_REGION).entered();
2087                if visible_height > 0 {
2088                    match self.inline_strategy {
2089                        InlineStrategy::ScrollRegion | InlineStrategy::Hybrid => {
2090                            self.activate_scroll_region(visible_height)?;
2091                        }
2092                        InlineStrategy::OverlayRedraw => {}
2093                    }
2094                } else if self.scroll_region_active {
2095                    self.deactivate_scroll_region()?;
2096                }
2097            }
2098
2099            self.clear_inline_region_diff(current_region)?;
2100
2101            let mut diff_strategy = DiffStrategy::FullRedraw;
2102            let mut diff_us = 0u64;
2103            let mut emit_stats = EmitStats {
2104                diff_cells: 0,
2105                diff_runs: 0,
2106            };
2107
2108            if visible_height > 0 {
2109                // If this is a full redraw (no previous buffer) OR dimensions changed,
2110                // we must clear the entire UI region to prevent ghosting (e.g. if width shrank).
2111                let dims_changed = self.prev_buffer.as_ref().map(|b| (b.width(), b.height()))
2112                    != Some((buffer.width(), buffer.height()));
2113
2114                if self.prev_buffer.is_none() || dims_changed {
2115                    self.clear_rows(ui_y_start, visible_height)?;
2116                } else {
2117                    // If dimensions match but the buffer is shorter than the visible height,
2118                    // clear the remaining rows to prevent garbage from logs or previous frames.
2119                    let buf_height = buffer.height().min(visible_height);
2120                    if buf_height < visible_height {
2121                        let clear_start = ui_y_start.saturating_add(buf_height);
2122                        let clear_height = visible_height.saturating_sub(buf_height);
2123                        self.clear_rows(clear_start, clear_height)?;
2124                    }
2125                }
2126
2127                // Compute diff
2128                let diff_start = if self.timing_enabled {
2129                    Some(Instant::now())
2130                } else {
2131                    None
2132                };
2133                let decision = {
2134                    let _span =
2135                        debug_span!(crate::telemetry_schema::span::RENDER_DIFF_COMPUTE).entered();
2136                    self.decide_diff(buffer)
2137                };
2138                if let Some(start) = diff_start {
2139                    diff_us = start.elapsed().as_micros() as u64;
2140                }
2141                diff_strategy = decision.strategy;
2142
2143                // Emit diff using Presenter
2144                {
2145                    let _span = debug_span!(crate::telemetry_schema::span::RENDER_EMIT).entered();
2146
2147                    // Reset presenter state (cursor unknown) because we manually moved cursor/saved
2148                    // and apply viewport offset for inline positioning.
2149                    let presenter = self.presenter.as_mut().expect("presenter consumed");
2150                    presenter.reset();
2151                    presenter.set_viewport_offset_y(ui_y_start);
2152
2153                    if decision.has_diff {
2154                        presenter.prepare_runs(&self.diff_scratch);
2155                        // Clip to the visible terminal region, mirroring the
2156                        // full-redraw branch: when the terminal is shorter
2157                        // than ui_height, a below-the-fold run would emit a
2158                        // CUP past the physical bottom row, which real
2159                        // terminals clamp — corrupting the last visible row.
2160                        presenter.clip_runs_below(visible_height);
2161                        // Emit
2162                        presenter.emit_diff_runs(buffer, Some(&self.pool), Some(&self.links))?;
2163
2164                        emit_stats.diff_cells = self.diff_scratch.len();
2165                        emit_stats.diff_runs = self.diff_scratch.runs().len();
2166                    } else {
2167                        // Full redraw — clip to the visible terminal region and
2168                        // to the buffer's actual height. This avoids generating
2169                        // diff runs for rows that are outside `buffer`.
2170                        let render_height = buffer.height().min(visible_height);
2171                        let full = BufferDiff::full(buffer.width(), render_height);
2172                        presenter.prepare_runs(&full);
2173                        presenter.emit_diff_runs(buffer, Some(&self.pool), Some(&self.links))?;
2174
2175                        emit_stats.diff_cells = full.len();
2176                        emit_stats.diff_runs = full.runs().len();
2177                    }
2178
2179                    presenter.finish_frame()?;
2180                }
2181            }
2182
2183            // Restore cursor
2184            self.writer().write_all(CURSOR_RESTORE)?;
2185            self.cursor_saved = false;
2186
2187            let mut show_cursor = false;
2188            if cursor_visible
2189                && let Some((cx, cy)) = cursor
2190                && cx < buffer.width()
2191                && cy < buffer.height()
2192                && cy < visible_height
2193            {
2194                // Move to UI start + cursor y
2195                let abs_y = ui_y_start.saturating_add(cy);
2196                write!(
2197                    self.writer(),
2198                    "\x1b[{};{}H",
2199                    abs_y.saturating_add(1),
2200                    cx.saturating_add(1)
2201                )?;
2202                show_cursor = true;
2203            }
2204            self.set_cursor_visibility(show_cursor)?;
2205
2206            // End sync output (mux-aware policy).
2207            if sync_output_enabled && self.in_sync_block {
2208                self.writer().write_all(SYNC_END)?;
2209                self.in_sync_block = false;
2210            } else if !sync_output_enabled {
2211                // Defensive stale-state cleanup: clear internal state without
2212                // emitting DEC 2026 in mux/unsupported environments.
2213                self.in_sync_block = false;
2214            }
2215
2216            self.writer().flush()?;
2217            self.last_inline_region = if visible_height > 0 {
2218                Some(current_region)
2219            } else {
2220                None
2221            };
2222
2223            if self.timing_enabled {
2224                self.last_present_timings = Some(PresentTimings { diff_us });
2225            }
2226
2227            Ok(FrameEmitStats {
2228                diff_strategy,
2229                diff_cells: emit_stats.diff_cells,
2230                diff_runs: emit_stats.diff_runs,
2231                ui_height: visible_height,
2232            })
2233        })();
2234
2235        if result.is_err() {
2236            _inline_span.record("scrollback_preserved", false);
2237            warn!(
2238                inline_height = ui_height,
2239                render_mode, "scrollback preservation failed during inline render"
2240            );
2241            self.best_effort_inline_cleanup();
2242        } else {
2243            _inline_span.record("scrollback_preserved", true);
2244        }
2245
2246        result
2247    }
2248
2249    /// Present UI in alternate screen mode (simpler, no cursor gymnastics).
2250    fn present_altscreen(
2251        &mut self,
2252        buffer: &Buffer,
2253        cursor: Option<(u16, u16)>,
2254        cursor_visible: bool,
2255    ) -> io::Result<FrameEmitStats> {
2256        let sync_output_enabled = self.capabilities.use_sync_output();
2257        let diff_start = if self.timing_enabled {
2258            Some(Instant::now())
2259        } else {
2260            None
2261        };
2262        let decision = {
2263            let _span = debug_span!(crate::telemetry_schema::span::RENDER_DIFF_COMPUTE).entered();
2264            self.decide_diff(buffer)
2265        };
2266        let diff_us = diff_start
2267            .map(|start| start.elapsed().as_micros() as u64)
2268            .unwrap_or(0);
2269
2270        // Begin sync if available. Track state so we can reliably close the
2271        // block even on early-return error paths.
2272        if sync_output_enabled && !self.in_sync_block {
2273            // Mark active before write so partial begin writes are treated as
2274            // an open block for best-effort close.
2275            self.in_sync_block = true;
2276            if let Err(err) = self.writer().write_all(SYNC_BEGIN) {
2277                // Attempt immediate close to avoid leaving the terminal in a
2278                // potentially open synchronized-output state.
2279                let _ = self.writer().write_all(SYNC_END);
2280                self.in_sync_block = false;
2281                let _ = self.writer().flush();
2282                return Err(err);
2283            }
2284        }
2285
2286        let operation_result = (|| -> io::Result<FrameEmitStats> {
2287            // Keep the hardware cursor hidden while we issue many cursor moves.
2288            // This prevents visible cursor "speckling" artifacts during redraws.
2289            self.set_cursor_visibility(false)?;
2290
2291            let emit_stats = {
2292                let _span = debug_span!(crate::telemetry_schema::span::RENDER_EMIT).entered();
2293                let presenter = self.presenter.as_mut().expect("presenter consumed");
2294
2295                // Reset presenter state (cursor and style) because we manually moved
2296                // the cursor and reset the style at the end of the previous frame.
2297                presenter.reset();
2298                // AltScreen always starts at (0,0) relative to terminal.
2299                presenter.set_viewport_offset_y(0);
2300
2301                let stats = if decision.has_diff {
2302                    presenter.prepare_runs(&self.diff_scratch);
2303                    presenter.emit_diff_runs(buffer, Some(&self.pool), Some(&self.links))?;
2304
2305                    EmitStats {
2306                        diff_cells: self.diff_scratch.len(),
2307                        diff_runs: self.diff_scratch.runs().len(),
2308                    }
2309                } else {
2310                    // Full redraw: populate diff with all cells and emit.
2311                    self.diff_scratch.fill_full(buffer.width(), buffer.height());
2312                    presenter.prepare_runs(&self.diff_scratch);
2313                    presenter.emit_diff_runs(buffer, Some(&self.pool), Some(&self.links))?;
2314
2315                    EmitStats {
2316                        diff_cells: (buffer.width() as usize) * (buffer.height() as usize),
2317                        diff_runs: buffer.height() as usize,
2318                    }
2319                };
2320
2321                presenter.finish_frame()?;
2322                stats
2323            };
2324
2325            let mut show_cursor = false;
2326            if cursor_visible
2327                && let Some((cx, cy)) = cursor
2328                && cx < buffer.width()
2329                && cy < buffer.height()
2330            {
2331                // Apply requested cursor position
2332                write!(
2333                    self.writer(),
2334                    "\x1b[{};{}H",
2335                    cy.saturating_add(1),
2336                    cx.saturating_add(1)
2337                )?;
2338                show_cursor = true;
2339            }
2340            self.set_cursor_visibility(show_cursor)?;
2341
2342            if self.timing_enabled {
2343                self.last_present_timings = Some(PresentTimings { diff_us });
2344            }
2345
2346            Ok(FrameEmitStats {
2347                diff_strategy: decision.strategy,
2348                diff_cells: emit_stats.diff_cells,
2349                diff_runs: emit_stats.diff_runs,
2350                ui_height: 0,
2351            })
2352        })();
2353
2354        if operation_result.is_err()
2355            && let Some(ref mut presenter) = self.presenter
2356        {
2357            presenter.finish_frame_best_effort();
2358        }
2359
2360        // Always attempt to close sync and flush, regardless of operation_result.
2361        let sync_end_result = if sync_output_enabled && self.in_sync_block {
2362            let res = self.writer().write_all(SYNC_END);
2363            if res.is_ok() {
2364                self.in_sync_block = false;
2365            }
2366            Some(res)
2367        } else {
2368            if !sync_output_enabled {
2369                // Defensive stale-state cleanup: do not emit DEC 2026 when
2370                // policy disallows synchronized output.
2371                self.in_sync_block = false;
2372            }
2373            None
2374        };
2375        let flush_result = self.writer().flush();
2376
2377        // Cleanup failures (sync-end/flush) take precedence so terminal-state
2378        // restoration errors are never hidden by a concurrent render failure.
2379        let cleanup_error = sync_end_result
2380            .and_then(Result::err)
2381            .or_else(|| flush_result.err());
2382        if let Some(err) = cleanup_error {
2383            return Err(err);
2384        }
2385        operation_result
2386    }
2387
2388    // emit_diff, emit_full_redraw, and emit_style_flags have been removed
2389    // in favor of delegating to the Presenter for all emission paths.
2390
2391    /// Create a full-screen diff (marks all cells as changed).
2392    #[allow(dead_code)] // API for future diff strategy integration
2393    fn create_full_diff(&self, buffer: &Buffer) -> BufferDiff {
2394        BufferDiff::full(buffer.width(), buffer.height())
2395    }
2396
2397    /// Write log output (goes to the log region in inline mode).
2398    ///
2399    /// Behavior depends on how the UI is anchored on screen:
2400    ///
2401    /// - **Scroll region active** (ScrollRegion/Hybrid strategies): the cursor
2402    ///   is parked at the bottom margin of the DECSTBM log region and the text
2403    ///   is written verbatim (after escape-stripping). Each LF scrolls only
2404    ///   the log region, so lines accumulate upward into scrollback while the
2405    ///   UI stays put.
2406    ///
2407    /// - **Overlay fallback** (OverlayRedraw strategy, or any transient state
2408    ///   without an active region): an unqualified LF would scroll the whole
2409    ///   screen and displace or corrupt the displayed UI, so logs NEVER emit
2410    ///   one. Instead exactly one width-clamped line is erased-and-rewritten,
2411    ///   referenced against the *displayed* region (`last_inline_region`) so
2412    ///   height changes between presents cannot land the line inside on-screen
2413    ///   UI. Older lines remain visible above until displaced by present
2414    ///   repaints; accumulation into scrollback requires the scroll-region
2415    ///   path.
2416    ///
2417    /// If the UI consumes the entire terminal height, there is no log region
2418    /// available and the write becomes a no-op.
2419    ///
2420    /// In AltScreen mode, logs are typically not shown (returns Ok silently).
2421    pub fn write_log(&mut self, text: &str) -> io::Result<()> {
2422        self.write_log_with_mode(text, SanitizeMode::Strip)
2423    }
2424
2425    /// Write colored log text, allowing only bounded SGR sequences.
2426    ///
2427    /// Cursor commands, terminal modes and other controls are filtered at the
2428    /// emission boundary. Inline overlay logs retain the first-line and visible
2429    /// width limits of [`Self::write_log`]. Styling resets at every line/write;
2430    /// callers must repeat styling on subsequent lines. Alt-screen logs are
2431    /// suppressed, as with the default mode.
2432    pub fn write_log_sgr_only(&mut self, text: &str) -> io::Result<()> {
2433        self.write_log_with_mode(text, SanitizeMode::SgrOnly)
2434    }
2435
2436    /// Write trusted log text without sanitization or overlay clamping.
2437    ///
2438    /// **Trusted input only:** cursor movement, mode changes, clearing and
2439    /// wrapping/newlines can corrupt inline UI or terminal state. Prefer
2440    /// [`Self::write_log_sgr_only`] for colored compiler/test output. This still
2441    /// uses the terminal output lock and log region, and suppresses alt-screen
2442    /// logs, but arbitrary commands can defeat cursor restoration.
2443    pub fn write_log_raw(&mut self, text: &str) -> io::Result<()> {
2444        self.write_log_with_mode(text, SanitizeMode::Raw)
2445    }
2446
2447    /// Write annotated text, reapplying its policy at the emission boundary.
2448    pub fn write_log_text(&mut self, text: &Text<'_>) -> io::Result<()> {
2449        self.write_log_with_mode(text.as_str(), text.mode())
2450    }
2451
2452    pub(crate) fn write_log_with_mode(&mut self, text: &str, mode: SanitizeMode) -> io::Result<()> {
2453        self.write_log_impl(text, mode, false)
2454    }
2455
2456    /// Emit a model log command as a logical line. Filter before normalizing
2457    /// line endings so control parsing sees the original input boundaries.
2458    pub(crate) fn write_log_line_with_mode(
2459        &mut self,
2460        text: &str,
2461        mode: SanitizeMode,
2462    ) -> io::Result<()> {
2463        self.write_log_impl(text, mode, true)
2464    }
2465
2466    fn write_log_impl(
2467        &mut self,
2468        text: &str,
2469        mode: SanitizeMode,
2470        logical_line: bool,
2471    ) -> io::Result<()> {
2472        // One-writer discipline vs teardown paths (bd-kdn7n item 2).
2473        let _output_guard = terminal_output_lock();
2474        if mode == SanitizeMode::Raw {
2475            tracing::debug!(target: crate::telemetry_schema::TARGET_RUNTIME_LOG, mode = "raw", bytes = text.len());
2476        }
2477        // Even publicly constructed Text variants must cross this boundary.
2478        let sanitized = sanitize_with(text, mode);
2479        let sanitized = if logical_line {
2480            let mut line = if sanitized.contains('\n') {
2481                sanitized.replace("\r\n", "\n").replace('\n', "\r\n")
2482            } else {
2483                sanitized.into_owned()
2484            };
2485            if !line.ends_with("\r\n") {
2486                line.push_str("\r\n");
2487            }
2488            std::borrow::Cow::Owned(line)
2489        } else {
2490            sanitized
2491        };
2492        let text = sanitized.as_ref();
2493        match self.screen_mode {
2494            ScreenMode::Inline { ui_height } => self.write_log_inline(ui_height, text, mode),
2495            ScreenMode::InlineAuto { .. } => {
2496                let ui_height = self.effective_ui_height();
2497                self.write_log_inline(ui_height, text, mode)
2498            }
2499            ScreenMode::AltScreen => {
2500                // AltScreen: no scrollback, logs are typically handled differently
2501                // (e.g., written to a log pane or file)
2502                Ok(())
2503            }
2504        }
2505    }
2506
2507    /// Shared inline log-write path for [`ScreenMode::Inline`] and
2508    /// [`ScreenMode::InlineAuto`].
2509    ///
2510    /// `ui_height` is the *effective* (pending) UI height; the physically
2511    /// displayed region may differ until the next `present_ui`, which is why
2512    /// the overlay arm anchors against `last_inline_region`.
2513    fn write_log_inline(
2514        &mut self,
2515        ui_height: u16,
2516        text: &str,
2517        mode: SanitizeMode,
2518    ) -> io::Result<()> {
2519        let visible_height = ui_height.min(self.term_height);
2520        if visible_height >= self.term_height {
2521            // No log region available when UI fills the terminal
2522            return Ok(());
2523        }
2524
2525        if self.scroll_region_active {
2526            // A DECSTBM region matching the current effective height is
2527            // active: parking at its bottom margin lets every LF scroll the
2528            // log region alone, accumulating lines into scrollback.
2529            if !self.position_cursor_for_log(visible_height)? {
2530                return Ok(());
2531            }
2532            self.write_log_payload(text, mode)?;
2533            return self.writer().flush();
2534        }
2535
2536        // Overlay discipline: never emit an unscoped LF (it would scroll the
2537        // whole screen and push UI rows around). Erase-and-rewrite exactly
2538        // one width-clamped line instead.
2539        let log_row = match self.ui_anchor {
2540            UiAnchor::Bottom => {
2541                // One row above the uppermost of the displayed/pending UI
2542                // regions (0-indexed start doubles as the 1-indexed row
2543                // directly above that region).
2544                let pending_start = self.ui_start_row();
2545                let anchor = self.last_inline_region.map_or(pending_start, |displayed| {
2546                    displayed.start.min(pending_start)
2547                });
2548                if anchor == 0 {
2549                    // No free row above the UI.
2550                    return Ok(());
2551                }
2552                anchor
2553            }
2554            UiAnchor::Top => {
2555                // A pending shrink does not free a row until it is presented.
2556                // The old UI may still occupy even the screen's bottom row.
2557                if self.last_inline_region.is_some_and(|displayed| {
2558                    displayed.start.saturating_add(displayed.height) >= self.term_height
2559                }) {
2560                    return Ok(());
2561                }
2562                // Both displayed and pending UI leave this row free. This
2563                // path never emits LF, so the log cannot scroll either UI.
2564                self.term_height
2565            }
2566        };
2567
2568        let line = match mode {
2569            SanitizeMode::Strip => std::borrow::Cow::Owned(sanitize_overlay_log_line(
2570                text,
2571                usize::from(self.term_width),
2572            )),
2573            SanitizeMode::SgrOnly => {
2574                std::borrow::Cow::Owned(sgr_overlay_log_line(text, usize::from(self.term_width)))
2575            }
2576            SanitizeMode::Raw => std::borrow::Cow::Borrowed(text),
2577        };
2578        if line.is_empty() {
2579            return Ok(());
2580        }
2581
2582        // Bound the cursor disturbance to this write so an interleaved
2583        // present (or none) always finds the cursor where it left it.
2584        self.writer().write_all(CURSOR_SAVE)?;
2585        let write_result = write!(self.writer(), "\x1b[{log_row};1H")
2586            .and_then(|()| self.writer().write_all(ERASE_LINE))
2587            .and_then(|()| self.write_log_payload(&line, mode));
2588        let restore_result = self.writer().write_all(CURSOR_RESTORE);
2589
2590        // Restoration failures must not be swallowed by a successful body
2591        // write: the cursor contract outranks the log payload.
2592        write_result?;
2593        restore_result?;
2594        self.writer().flush()
2595    }
2596
2597    /// Isolate SGR styling, including best-effort reset after a write failure.
2598    fn write_log_payload(&mut self, text: &str, mode: SanitizeMode) -> io::Result<()> {
2599        if mode != SanitizeMode::SgrOnly {
2600            return self.writer().write_all(text.as_bytes());
2601        }
2602        let write_result: io::Result<()> = (|| {
2603            self.writer().write_all(SGR_RESET)?;
2604            for line in text.split_inclusive(['\n', '\r']) {
2605                if line.ends_with(['\n', '\r']) {
2606                    let (body, newline) = line.split_at(line.len() - 1);
2607                    self.writer().write_all(body.as_bytes())?;
2608                    self.writer().write_all(SGR_RESET)?;
2609                    self.writer().write_all(newline.as_bytes())?;
2610                } else {
2611                    self.writer().write_all(line.as_bytes())?;
2612                }
2613            }
2614            Ok(())
2615        })();
2616        let reset_result = self.writer().write_all(SGR_RESET);
2617        write_result?;
2618        reset_result
2619    }
2620
2621    /// Position cursor at the bottom margin of the active DECSTBM log region.
2622    ///
2623    /// Only meaningful while a scroll region is active (see
2624    /// [`TerminalWriter::write_log`]): for bottom-anchored UI the region spans
2625    /// rows 1..=term_height - ui_height, for top-anchored UI rows
2626    /// ui_height + 1..=term_height. Parking at the region's bottom margin
2627    /// makes each subsequent LF scroll only that region, leaving the UI
2628    /// untouched while log lines accumulate into scrollback.
2629    fn position_cursor_for_log(&mut self, ui_height: u16) -> io::Result<bool> {
2630        let visible_height = ui_height.min(self.term_height);
2631        if visible_height >= self.term_height {
2632            // No log region available when UI fills the terminal
2633            return Ok(false);
2634        }
2635
2636        let log_row = match self.ui_anchor {
2637            UiAnchor::Bottom => {
2638                // Log region is above UI: rows 1 to (term_height - ui_height)
2639                // Position at the bottom of the log region
2640                self.term_height.saturating_sub(visible_height)
2641            }
2642            UiAnchor::Top => {
2643                // Log region is below UI: rows (ui_height + 1) to term_height
2644                // Position at the bottom of the log region (last row)
2645                self.term_height
2646            }
2647        };
2648
2649        // Move to the target row, column 1 (1-indexed)
2650        write!(self.writer(), "\x1b[{};1H", log_row)?;
2651        Ok(true)
2652    }
2653
2654    /// Clear the screen.
2655    pub fn clear_screen(&mut self) -> io::Result<()> {
2656        // One-writer discipline vs teardown paths (bd-kdn7n item 2).
2657        let _output_guard = terminal_output_lock();
2658        let mut first_error = None;
2659        if self.in_sync_block {
2660            if self.capabilities.use_sync_output()
2661                && let Err(err) = self.writer().write_all(SYNC_END)
2662            {
2663                first_error = Some(err);
2664            }
2665            self.in_sync_block = false;
2666        }
2667        if self.cursor_saved {
2668            if let Err(err) = self.writer().write_all(CURSOR_RESTORE) {
2669                first_error.get_or_insert(err);
2670            }
2671            self.cursor_saved = false;
2672        }
2673        if self.scroll_region_active {
2674            if let Err(err) = self.writer().write_all(b"\x1b[r") {
2675                first_error.get_or_insert(err);
2676            }
2677            self.scroll_region_active = false;
2678        }
2679        if let Err(err) = self.writer().write_all(b"\x1b[2J\x1b[1;1H") {
2680            first_error.get_or_insert(err);
2681        }
2682        if let Err(err) = self.writer().flush() {
2683            first_error.get_or_insert(err);
2684        }
2685        self.prev_buffer = None;
2686        self.last_inline_region = None;
2687        self.reset_diff_strategy();
2688        if let Some(err) = first_error {
2689            Err(err)
2690        } else {
2691            Ok(())
2692        }
2693    }
2694
2695    fn set_cursor_visibility(&mut self, visible: bool) -> io::Result<()> {
2696        if self.cursor_visible == visible {
2697            return Ok(());
2698        }
2699        self.cursor_visible = visible;
2700        if visible {
2701            self.writer().write_all(b"\x1b[?25h")?;
2702        } else {
2703            self.writer().write_all(b"\x1b[?25l")?;
2704        }
2705        Ok(())
2706    }
2707
2708    /// Hide the cursor.
2709    pub fn hide_cursor(&mut self) -> io::Result<()> {
2710        let _output_guard = terminal_output_lock();
2711        self.set_cursor_visibility(false)?;
2712        self.writer().flush()
2713    }
2714
2715    /// Show the cursor.
2716    pub fn show_cursor(&mut self) -> io::Result<()> {
2717        let _output_guard = terminal_output_lock();
2718        self.set_cursor_visibility(true)?;
2719        self.writer().flush()
2720    }
2721
2722    /// Queue an OSC 52 clipboard write in the presenter's existing output buffer.
2723    ///
2724    /// Call [`flush`](Self::flush) when no frame follows. Unsupported capability
2725    /// sets are skipped; invalid selections and oversized payloads are errors.
2726    pub fn write_osc52_set(
2727        &mut self,
2728        selection: ftui_core::osc52::ClipboardSelection,
2729        bytes: &[u8],
2730    ) -> io::Result<()> {
2731        let seq = ftui_core::osc52::encode_set(selection, bytes)
2732            .map_err(|e| io::Error::new(io::ErrorKind::InvalidInput, e))?;
2733        self.write_osc52_control(selection, &seq, bytes.len().div_ceil(3) * 4)
2734    }
2735
2736    /// Queue an asynchronous OSC 52 clipboard read request.
2737    pub fn write_osc52_query(
2738        &mut self,
2739        selection: ftui_core::osc52::ClipboardSelection,
2740    ) -> io::Result<()> {
2741        let seq = ftui_core::osc52::encode_query(selection)
2742            .map_err(|e| io::Error::new(io::ErrorKind::InvalidInput, e))?;
2743        self.write_osc52_control(selection, &seq, 0)
2744    }
2745
2746    fn write_osc52_control(
2747        &mut self,
2748        selection: ftui_core::osc52::ClipboardSelection,
2749        seq: &[u8],
2750        payload_b64_len: usize,
2751    ) -> io::Result<()> {
2752        let caps = self.capabilities;
2753        if !caps.osc52_clipboard {
2754            tracing::debug!(target: crate::telemetry_schema::TARGET_RUNTIME, event = "osc52_write", ?selection, skipped_unsupported = true);
2755            return Ok(());
2756        }
2757        let _output_guard = terminal_output_lock();
2758        ftui_core::mux_passthrough::mux_wrap(self.writer(), &caps, seq)?;
2759        tracing::debug!(target: crate::telemetry_schema::TARGET_RUNTIME, event = "osc52_write", ?selection, payload_b64_len,
2760            wrapped = caps.in_tmux || caps.in_screen, skipped_unsupported = false);
2761        Ok(())
2762    }
2763
2764    /// Flush any buffered output.
2765    pub fn flush(&mut self) -> io::Result<()> {
2766        let _output_guard = terminal_output_lock();
2767        self.writer().flush()
2768    }
2769
2770    /// Get the grapheme pool for interning complex characters.
2771    pub fn pool(&self) -> &GraphemePool {
2772        &self.pool
2773    }
2774
2775    /// Get mutable access to the grapheme pool.
2776    pub fn pool_mut(&mut self) -> &mut GraphemePool {
2777        &mut self.pool
2778    }
2779
2780    /// Get the link registry.
2781    pub fn links(&self) -> &LinkRegistry {
2782        &self.links
2783    }
2784
2785    /// Get mutable access to the link registry.
2786    pub fn links_mut(&mut self) -> &mut LinkRegistry {
2787        &mut self.links
2788    }
2789
2790    /// Apply the program's opt-in link lifetime policy at initialization.
2791    pub(crate) fn set_hyperlink_limit(&mut self, limit: usize) {
2792        self.links = LinkRegistry::with_frame_limit(limit);
2793        self.prev_buffer = None;
2794        self.reset_diff_strategy();
2795    }
2796
2797    /// Start a managed render while preserving the last presented frame's IDs.
2798    /// Spare/clone buffers are reset or overwritten before reuse, so they are
2799    /// not roots. Unmanaged registries leave all IDs untouched.
2800    pub(crate) fn begin_link_frame(&mut self) {
2801        if let Some(previous) = self.prev_buffer.as_ref() {
2802            self.links.begin_frame(&[previous]);
2803        } else {
2804            self.links.begin_frame(&[]);
2805        }
2806    }
2807
2808    /// Borrow the grapheme pool and link registry together.
2809    ///
2810    /// This avoids double-borrowing `self` at call sites that need both.
2811    pub fn pool_and_links_mut(&mut self) -> (&mut GraphemePool, &mut LinkRegistry) {
2812        (&mut self.pool, &mut self.links)
2813    }
2814
2815    /// Get the terminal capabilities.
2816    pub fn capabilities(&self) -> &TerminalCapabilities {
2817        &self.capabilities
2818    }
2819
2820    /// Consume the writer and return the underlying writer.
2821    ///
2822    /// Performs cleanup operations before returning.
2823    /// Returns `None` if the buffer could not be flushed.
2824    pub fn into_inner(mut self) -> Option<W> {
2825        self.cleanup();
2826        // Take the presenter before Drop runs (Drop will see None and skip cleanup)
2827        self.presenter.take()?.into_inner().ok()
2828    }
2829
2830    /// Perform garbage collection on the grapheme pool.
2831    ///
2832    /// Frees graphemes that are not referenced by the current front buffer (`prev_buffer`)
2833    /// or the optional `extra_buffer` (e.g. a pending render).
2834    ///
2835    /// This should be called periodically (e.g. every N frames) to prevent memory leaks
2836    /// in long-running applications with dynamic content.
2837    pub fn gc(&mut self, extra_buffer: Option<&Buffer>) {
2838        let mut buffers = Vec::with_capacity(2);
2839        if let Some(ref buf) = self.prev_buffer {
2840            buffers.push(buf);
2841        }
2842        if let Some(buf) = extra_buffer {
2843            buffers.push(buf);
2844        }
2845        self.pool.gc(&buffers);
2846    }
2847
2848    /// Estimate total memory usage in bytes (buffers + pools).
2849    pub fn estimate_memory_usage(&self) -> usize {
2850        let mut total = 0;
2851        // Buffers (16 bytes per cell)
2852        if let Some(b) = &self.prev_buffer {
2853            total += b.width() as usize * b.height() as usize * 16;
2854        }
2855        if let Some(b) = &self.spare_buffer {
2856            total += b.width() as usize * b.height() as usize * 16;
2857        }
2858        if let Some(b) = &self.clone_buf {
2859            total += b.width() as usize * b.height() as usize * 16;
2860        }
2861        // Grapheme pool (approx 32 bytes per slot: 24 for String + overhead)
2862        total += self.pool.capacity() * 32;
2863        // Link registry
2864        total += self.links.estimate_memory();
2865        total
2866    }
2867
2868    /// Best-effort cleanup when inline present fails mid-frame.
2869    ///
2870    /// This restores sync/cursor/scroll-region state without terminating the writer.
2871    fn best_effort_inline_cleanup(&mut self) {
2872        let Some(ref mut presenter) = self.presenter else {
2873            return;
2874        };
2875        presenter.finish_frame_best_effort();
2876        let writer = presenter.counting_writer_mut();
2877
2878        // Ensure erase operations clear to the terminal default background.
2879        // Without this, background color leakage occurs during cleanup.
2880        let _ = writer.write_all(SGR_BG_DEFAULT);
2881
2882        // Emit restorations unconditionally: write errors can occur after bytes
2883        // were partially written, so internal flags may be stale.
2884        if self.in_sync_block {
2885            if self.capabilities.use_sync_output() {
2886                let _ = writer.write_all(SYNC_END);
2887            }
2888            self.in_sync_block = false;
2889        }
2890
2891        let _ = writer.write_all(CURSOR_RESTORE);
2892        self.cursor_saved = false;
2893
2894        let _ = writer.write_all(b"\x1b[r");
2895        self.scroll_region_active = false;
2896
2897        let _ = writer.write_all(b"\x1b[?25h");
2898        self.cursor_visible = true;
2899        let _ = writer.flush();
2900    }
2901
2902    /// Internal cleanup on drop.
2903    fn cleanup(&mut self) {
2904        self.release_terminal_state();
2905        if let Some(ref mut trace) = self.render_trace {
2906            let _ = trace.finish(None);
2907        }
2908    }
2909
2910    /// Hand the terminal back ahead of a job-control stop: the same bytes as
2911    /// the drop-time cleanup, but the writer stays usable. The caller must
2912    /// then [`set_size`](Self::set_size) on resume, which drops the diff
2913    /// baseline and inline-region cache: the screen is not ours after a stop.
2914    pub(crate) fn release_for_suspend(&mut self) {
2915        self.release_terminal_state();
2916    }
2917
2918    /// Close an open sync block, reset the scroll region, restore the saved
2919    /// cursor and show it, then flush.
2920    fn release_terminal_state(&mut self) {
2921        // Teardown bytes must not interleave with another thread's emission
2922        // batch (bd-kdn7n item 2); reentrant so Drop-under-lock is safe.
2923        let _output_guard = terminal_output_lock();
2924        let Some(presenter) = &mut self.presenter else {
2925            return; // Presenter already taken (via into_inner)
2926        };
2927        presenter.finish_frame_best_effort();
2928        let writer = presenter.counting_writer_mut();
2929
2930        // Ensure erase operations clear to the terminal default background.
2931        let _ = writer.write_all(SGR_BG_DEFAULT);
2932
2933        // End any pending sync block
2934        if self.in_sync_block {
2935            if self.capabilities.use_sync_output() {
2936                let _ = writer.write_all(SYNC_END);
2937            }
2938            self.in_sync_block = false;
2939        }
2940
2941        // Reset scroll region BEFORE restoring the cursor: DECSTBM reset
2942        // homes the cursor to (1,1) on real terminals, so emitting it after
2943        // CURSOR_RESTORE would discard the deliberate final placement.
2944        if self.scroll_region_active {
2945            let _ = writer.write_all(b"\x1b[r");
2946            self.scroll_region_active = false;
2947        }
2948
2949        // Restore cursor if saved
2950        if self.cursor_saved {
2951            let _ = writer.write_all(CURSOR_RESTORE);
2952            self.cursor_saved = false;
2953        }
2954
2955        // Show cursor
2956        let _ = writer.write_all(b"\x1b[?25h");
2957        self.cursor_visible = true;
2958
2959        // Flush
2960        let _ = writer.flush();
2961    }
2962}
2963
2964impl<W: Write> Drop for TerminalWriter<W> {
2965    fn drop(&mut self) {
2966        // Decrement the inline-active gauge.
2967        if matches!(
2968            self.screen_mode,
2969            ScreenMode::Inline { .. } | ScreenMode::InlineAuto { .. }
2970        ) {
2971            INLINE_ACTIVE_WIDGETS.fetch_sub(1, Ordering::SeqCst);
2972        }
2973        self.cleanup();
2974    }
2975}
2976
2977#[cfg(test)]
2978mod tests {
2979    use super::*;
2980    use ftui_render::cell::{Cell, CellAttrs, CellContent, PackedRgba, StyleFlags};
2981    use std::cell::RefCell;
2982    use std::io;
2983    use std::path::PathBuf;
2984    use std::rc::Rc;
2985
2986    #[test]
2987    fn osc52_writer_buffers_wraps_and_rejects_invalid_requests() {
2988        use ftui_core::osc52::ClipboardSelection;
2989        for mode in 0..4 {
2990            let mut caps = TerminalCapabilities::basic();
2991            caps.osc52_clipboard = mode != 0;
2992            caps.in_tmux = mode == 2;
2993            caps.in_screen = mode == 3;
2994            let mut writer =
2995                TerminalWriter::new(Vec::new(), ScreenMode::AltScreen, UiAnchor::Bottom, caps);
2996            writer
2997                .write_osc52_set(ClipboardSelection::Clipboard, b"hi")
2998                .unwrap();
2999            writer
3000                .write_osc52_query(ClipboardSelection::Clipboard)
3001                .unwrap();
3002            assert!(
3003                writer.presenter.as_mut().unwrap().writer_mut().is_empty(),
3004                "small controls remain buffered"
3005            );
3006            writer.flush().unwrap();
3007            let bytes = writer.presenter.as_mut().unwrap().writer_mut().clone();
3008            let expected: &[u8] = match mode {
3009                0 => b"",
3010                1 => b"\x1b]52;c;aGk=\x07\x1b]52;c;?\x07",
3011                2 => b"\x1bPtmux;\x1b\x1b]52;c;aGk=\x07\x1b\\\x1bPtmux;\x1b\x1b]52;c;?\x07\x1b\\",
3012                _ => b"\x1bP\x1b]52;c;aGk=\x07\x1b\\\x1bP\x1b]52;c;?\x07\x1b\\",
3013            };
3014            assert_eq!(bytes, expected);
3015            assert_eq!(
3016                writer
3017                    .write_osc52_set(ClipboardSelection::Clipboard, &vec![0; 56_245])
3018                    .unwrap_err()
3019                    .kind(),
3020                io::ErrorKind::InvalidInput
3021            );
3022            assert_eq!(
3023                writer
3024                    .write_osc52_query(ClipboardSelection::CutBuffer(8))
3025                    .unwrap_err()
3026                    .kind(),
3027                io::ErrorKind::InvalidInput
3028            );
3029            writer.flush().unwrap();
3030            assert_eq!(writer.presenter.as_mut().unwrap().writer_mut(), &bytes);
3031        }
3032    }
3033
3034    fn max_cursor_row(output: &[u8]) -> u16 {
3035        let mut max_row = 0u16;
3036        let mut i = 0;
3037        while i + 2 < output.len() {
3038            if output[i] == 0x1b && output[i + 1] == b'[' {
3039                let mut j = i + 2;
3040                let mut row: u16 = 0;
3041                let mut saw_row = false;
3042                while j < output.len() && output[j].is_ascii_digit() {
3043                    saw_row = true;
3044                    row = row
3045                        .saturating_mul(10)
3046                        .saturating_add((output[j] - b'0') as u16);
3047                    j += 1;
3048                }
3049                if saw_row && j < output.len() && output[j] == b';' {
3050                    j += 1;
3051                    let mut saw_col = false;
3052                    while j < output.len() && output[j].is_ascii_digit() {
3053                        saw_col = true;
3054                        j += 1;
3055                    }
3056                    if saw_col && j < output.len() && output[j] == b'H' {
3057                        max_row = max_row.max(row);
3058                    }
3059                }
3060            }
3061            i += 1;
3062        }
3063        max_row
3064    }
3065
3066    fn basic_caps() -> TerminalCapabilities {
3067        TerminalCapabilities::basic()
3068    }
3069
3070    fn full_caps() -> TerminalCapabilities {
3071        let mut caps = TerminalCapabilities::basic();
3072        caps.color_depth = ColorDepth::TrueColor;
3073        caps.sync_output = true;
3074        caps
3075    }
3076
3077    fn find_nth(haystack: &[u8], needle: &[u8], nth: usize) -> Option<usize> {
3078        if nth == 0 {
3079            return None;
3080        }
3081        let mut count = 0;
3082        let mut i = 0;
3083        while i + needle.len() <= haystack.len() {
3084            if &haystack[i..i + needle.len()] == needle {
3085                count += 1;
3086                if count == nth {
3087                    return Some(i);
3088                }
3089            }
3090            i += 1;
3091        }
3092        None
3093    }
3094
3095    fn temp_evidence_path(label: &str) -> PathBuf {
3096        // Retain evidence even if the test panics, with a fresh directory per run.
3097        let dir = tempfile::Builder::new()
3098            .prefix(&format!("ftui-terminal-writer-{label}-"))
3099            .disable_cleanup(true)
3100            .tempdir()
3101            .expect("create retained evidence directory");
3102        dir.path().join("evidence.jsonl")
3103    }
3104
3105    #[derive(Default)]
3106    struct FaultState {
3107        bytes: Vec<u8>,
3108        write_calls: usize,
3109        injected_failure_triggered: bool,
3110    }
3111
3112    struct SingleWriteFaultWriter {
3113        state: Rc<RefCell<FaultState>>,
3114        fail_on_call: usize,
3115        max_chunk_len: usize,
3116    }
3117
3118    impl SingleWriteFaultWriter {
3119        fn new(state: Rc<RefCell<FaultState>>, fail_on_call: usize, max_chunk_len: usize) -> Self {
3120            Self {
3121                state,
3122                fail_on_call,
3123                max_chunk_len: max_chunk_len.max(1),
3124            }
3125        }
3126    }
3127
3128    impl Write for SingleWriteFaultWriter {
3129        fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
3130            let mut state = self.state.borrow_mut();
3131            state.write_calls = state.write_calls.saturating_add(1);
3132            if !state.injected_failure_triggered && state.write_calls == self.fail_on_call {
3133                state.injected_failure_triggered = true;
3134                return Err(io::Error::other("injected partial-write fault"));
3135            }
3136
3137            let write_len = buf.len().min(self.max_chunk_len);
3138            state.bytes.extend_from_slice(&buf[..write_len]);
3139            Ok(write_len)
3140        }
3141
3142        fn flush(&mut self) -> io::Result<()> {
3143            Ok(())
3144        }
3145    }
3146
3147    #[test]
3148    fn new_creates_writer() {
3149        let output = Vec::new();
3150        let writer = TerminalWriter::new(
3151            output,
3152            ScreenMode::Inline { ui_height: 10 },
3153            UiAnchor::Bottom,
3154            basic_caps(),
3155        );
3156        assert_eq!(writer.ui_height(), 10);
3157    }
3158
3159    #[test]
3160    fn ui_start_row_bottom_anchor() {
3161        let output = Vec::new();
3162        let mut writer = TerminalWriter::new(
3163            output,
3164            ScreenMode::Inline { ui_height: 10 },
3165            UiAnchor::Bottom,
3166            basic_caps(),
3167        );
3168        writer.set_size(80, 24);
3169        assert_eq!(writer.ui_start_row(), 14); // 24 - 10 = 14
3170    }
3171
3172    #[test]
3173    fn ui_start_row_top_anchor() {
3174        let output = Vec::new();
3175        let mut writer = TerminalWriter::new(
3176            output,
3177            ScreenMode::Inline { ui_height: 10 },
3178            UiAnchor::Top,
3179            basic_caps(),
3180        );
3181        writer.set_size(80, 24);
3182        assert_eq!(writer.ui_start_row(), 0);
3183    }
3184
3185    #[test]
3186    fn ui_start_row_altscreen() {
3187        let output = Vec::new();
3188        let mut writer = TerminalWriter::new(
3189            output,
3190            ScreenMode::AltScreen,
3191            UiAnchor::Bottom,
3192            basic_caps(),
3193        );
3194        writer.set_size(80, 24);
3195        assert_eq!(writer.ui_start_row(), 0);
3196    }
3197
3198    #[test]
3199    fn present_ui_inline_saves_restores_cursor() {
3200        let mut output = Vec::new();
3201        {
3202            let mut writer = TerminalWriter::new(
3203                &mut output,
3204                ScreenMode::Inline { ui_height: 5 },
3205                UiAnchor::Bottom,
3206                basic_caps(),
3207            );
3208            writer.set_size(10, 10);
3209
3210            let buffer = Buffer::new(10, 5);
3211            writer.present_ui(&buffer, None, true).unwrap();
3212        }
3213
3214        // Should contain cursor save and restore
3215        assert!(output.windows(CURSOR_SAVE.len()).any(|w| w == CURSOR_SAVE));
3216        assert!(
3217            output
3218                .windows(CURSOR_RESTORE.len())
3219                .any(|w| w == CURSOR_RESTORE)
3220        );
3221    }
3222
3223    #[test]
3224    fn present_ui_with_sync_output() {
3225        let mut output = Vec::new();
3226        {
3227            let mut writer = TerminalWriter::new(
3228                &mut output,
3229                ScreenMode::Inline { ui_height: 5 },
3230                UiAnchor::Bottom,
3231                full_caps(),
3232            );
3233            writer.set_size(10, 10);
3234
3235            let buffer = Buffer::new(10, 5);
3236            writer.present_ui(&buffer, None, true).unwrap();
3237        }
3238
3239        // Should contain sync begin and end
3240        assert!(output.windows(SYNC_BEGIN.len()).any(|w| w == SYNC_BEGIN));
3241        assert!(output.windows(SYNC_END.len()).any(|w| w == SYNC_END));
3242    }
3243
3244    #[test]
3245    fn present_ui_altscreen_closes_stale_sync_block_when_policy_allows_sync() {
3246        let mut output = Vec::new();
3247        {
3248            let mut writer = TerminalWriter::new(
3249                &mut output,
3250                ScreenMode::AltScreen,
3251                UiAnchor::Bottom,
3252                full_caps(),
3253            );
3254            writer.set_size(8, 2);
3255            writer.in_sync_block = true;
3256
3257            let mut buffer = Buffer::new(8, 2);
3258            buffer.set_raw(0, 0, Cell::from_char('X'));
3259            writer.present_ui(&buffer, None, true).unwrap();
3260
3261            assert!(
3262                !writer.in_sync_block,
3263                "present_altscreen must close stale sync blocks"
3264            );
3265        }
3266
3267        assert!(
3268            output.windows(SYNC_END.len()).any(|w| w == SYNC_END),
3269            "sync end should be emitted when stale sync state is detected"
3270        );
3271    }
3272
3273    #[test]
3274    fn present_ui_altscreen_stale_sync_block_skips_sync_end_in_mux() {
3275        let mut output = Vec::new();
3276        {
3277            let mut writer = TerminalWriter::new(
3278                &mut output,
3279                ScreenMode::AltScreen,
3280                UiAnchor::Bottom,
3281                mux_caps(),
3282            );
3283            writer.set_size(8, 2);
3284            writer.in_sync_block = true;
3285
3286            let mut buffer = Buffer::new(8, 2);
3287            buffer.set_raw(0, 0, Cell::from_char('X'));
3288            writer.present_ui(&buffer, None, true).unwrap();
3289
3290            assert!(
3291                !writer.in_sync_block,
3292                "present_altscreen must clear stale sync state"
3293            );
3294        }
3295
3296        assert!(
3297            !output.windows(SYNC_END.len()).any(|w| w == SYNC_END),
3298            "sync end must be suppressed when policy disables synchronized output"
3299        );
3300    }
3301
3302    #[test]
3303    fn present_ui_altscreen_sanitizes_grapheme_escape_payloads() {
3304        let mut output = Vec::new();
3305        {
3306            let mut writer = TerminalWriter::new(
3307                &mut output,
3308                ScreenMode::AltScreen,
3309                UiAnchor::Bottom,
3310                basic_caps(),
3311            );
3312            writer.set_size(12, 1);
3313
3314            let gid = writer
3315                .pool_mut()
3316                .intern("ok\x1b]52;c;SGVsbG8=\x1b\\tail\u{009d}", 6);
3317            let mut buffer = Buffer::new(12, 1);
3318            buffer.set_raw(0, 0, Cell::new(CellContent::from_grapheme(gid)));
3319
3320            writer.present_ui(&buffer, None, true).unwrap();
3321        }
3322
3323        let output_str = String::from_utf8_lossy(&output);
3324        assert!(
3325            output_str.contains("oktail"),
3326            "sanitized grapheme content should preserve visible payload"
3327        );
3328        assert!(
3329            !output_str.contains("52;c;SGVsbG8"),
3330            "OSC payload must not be forwarded by alt-screen emitter"
3331        );
3332        assert!(
3333            !output_str.contains('\u{009d}'),
3334            "C1 controls must be stripped from alt-screen grapheme output"
3335        );
3336    }
3337
3338    #[test]
3339    fn present_ui_inline_skips_sync_output_in_mux() {
3340        let mut output = Vec::new();
3341        {
3342            let mut writer = TerminalWriter::new(
3343                &mut output,
3344                ScreenMode::Inline { ui_height: 5 },
3345                UiAnchor::Bottom,
3346                mux_caps(),
3347            );
3348            writer.set_size(10, 10);
3349
3350            let buffer = Buffer::new(10, 5);
3351            writer.present_ui(&buffer, None, true).unwrap();
3352        }
3353
3354        assert!(
3355            !output.windows(SYNC_BEGIN.len()).any(|w| w == SYNC_BEGIN),
3356            "sync begin must be suppressed in tmux/screen/zellij environments"
3357        );
3358        assert!(
3359            !output.windows(SYNC_END.len()).any(|w| w == SYNC_END),
3360            "sync end must be suppressed in tmux/screen/zellij environments"
3361        );
3362    }
3363
3364    #[test]
3365    fn present_ui_altscreen_skips_sync_output_in_mux() {
3366        let mut output = Vec::new();
3367        {
3368            let mut writer = TerminalWriter::new(
3369                &mut output,
3370                ScreenMode::AltScreen,
3371                UiAnchor::Bottom,
3372                mux_caps(),
3373            );
3374            writer.set_size(10, 10);
3375
3376            let buffer = Buffer::new(10, 5);
3377            writer.present_ui(&buffer, None, true).unwrap();
3378        }
3379
3380        assert!(
3381            !output.windows(SYNC_BEGIN.len()).any(|w| w == SYNC_BEGIN),
3382            "sync begin must be suppressed in tmux/screen/zellij environments"
3383        );
3384        assert!(
3385            !output.windows(SYNC_END.len()).any(|w| w == SYNC_END),
3386            "sync end must be suppressed in tmux/screen/zellij environments"
3387        );
3388    }
3389
3390    #[test]
3391    fn managed_hyperlinks_repaint_after_failed_borrowed_present() {
3392        let state = Rc::new(RefCell::new(FaultState::default()));
3393        let backend = SingleWriteFaultWriter::new(Rc::clone(&state), 1, 1);
3394        let mut caps = basic_caps();
3395        caps.osc8_hyperlinks = true;
3396        let mut writer =
3397            TerminalWriter::new(backend, ScreenMode::AltScreen, UiAnchor::Bottom, caps);
3398        writer.set_size(1, 1);
3399        writer.set_hyperlink_limit(1);
3400        writer.begin_link_frame();
3401        let old_id = writer.links_mut().register("https://failed.test");
3402        let mut buffer = Buffer::new(1, 1);
3403        buffer.set_raw(
3404            0,
3405            0,
3406            Cell::from_char('L').with_attrs(CellAttrs::new(StyleFlags::empty(), old_id)),
3407        );
3408        writer
3409            .present_ui(&buffer, None, false)
3410            .expect_err("write fault");
3411        assert!(state.borrow().injected_failure_triggered);
3412        assert!(writer.prev_buffer.is_none());
3413
3414        writer.begin_link_frame();
3415        let new_id = writer.links_mut().register("https://recovered.test");
3416        assert_eq!(new_id, old_id, "failed baseline permits safe reuse");
3417        buffer.set_raw(
3418            0,
3419            0,
3420            Cell::from_char('L').with_attrs(CellAttrs::new(StyleFlags::empty(), new_id)),
3421        );
3422        writer
3423            .present_ui(&buffer, None, false)
3424            .expect("recovered present");
3425        assert_eq!(writer.links().len(), 1);
3426        let bytes = state.borrow().bytes.clone();
3427        let output = String::from_utf8(bytes).unwrap();
3428        assert!(output.contains("\x1b]8;;https://recovered.test\x07L\x1b[0m\x1b]8;;\x07"));
3429        // BufWriter retains serialized bytes on the injected first-write
3430        // failure. Retrying may flush that old frame before the full repaint;
3431        // an I/O error is not a rollback. Require the final target, not absence
3432        // of the earlier frame's bytes. Inspect before Drop can clean up.
3433        let targets: Vec<_> = output
3434            .split("\x1b]8;;")
3435            .skip(1)
3436            .filter_map(|part| part.split_once('\x07'))
3437            .map(|(url, _)| url)
3438            .filter(|url| !url.is_empty())
3439            .collect();
3440        assert_eq!(targets, ["https://failed.test", "https://recovered.test"]);
3441        let mut terminal = ftui_render::terminal_model::TerminalModel::new(1, 1);
3442        terminal.process(output.as_bytes());
3443        let cell = terminal.cell(0, 0).unwrap();
3444        assert_eq!(cell.text, "L");
3445        assert_eq!(
3446            terminal.link_url(cell.link_id),
3447            Some("https://recovered.test")
3448        );
3449        assert!(!terminal.has_dangling_link());
3450    }
3451
3452    #[test]
3453    fn unmanaged_hyperlinks_keep_cached_ids_across_frame_preparation() {
3454        let mut writer = TerminalWriter::new(
3455            Vec::new(),
3456            ScreenMode::AltScreen,
3457            UiAnchor::Bottom,
3458            basic_caps(),
3459        );
3460        let id = writer.links_mut().register("https://cached.test");
3461        for _ in 0..3 {
3462            writer.begin_link_frame();
3463            assert_eq!(writer.links().get(id), Some("https://cached.test"));
3464        }
3465    }
3466
3467    #[test]
3468    fn present_ui_inline_skips_hyperlinks_in_mux() {
3469        let mut output = Vec::new();
3470        {
3471            let mut caps = mux_caps();
3472            caps.osc8_hyperlinks = true;
3473
3474            let mut writer = TerminalWriter::new(
3475                &mut output,
3476                ScreenMode::Inline { ui_height: 2 },
3477                UiAnchor::Bottom,
3478                caps,
3479            );
3480            writer.set_size(8, 4);
3481
3482            let link_id = writer.links_mut().register("https://example.com");
3483            let mut buffer = Buffer::new(8, 2);
3484            buffer.set_raw(
3485                0,
3486                0,
3487                Cell::from_char('L').with_attrs(CellAttrs::new(StyleFlags::empty(), link_id)),
3488            );
3489            writer.present_ui(&buffer, None, true).unwrap();
3490        }
3491
3492        assert!(
3493            !output.windows(b"\x1b]8;".len()).any(|w| w == b"\x1b]8;"),
3494            "OSC 8 sequences must be suppressed by mux hyperlink policy"
3495        );
3496    }
3497
3498    #[test]
3499    fn present_ui_inline_closes_hyperlinks_at_frame_end() {
3500        let mut output = Vec::new();
3501        {
3502            let mut caps = full_caps();
3503            caps.osc8_hyperlinks = true;
3504
3505            let mut writer = TerminalWriter::new(
3506                &mut output,
3507                ScreenMode::Inline { ui_height: 2 },
3508                UiAnchor::Bottom,
3509                caps,
3510            );
3511            writer.set_size(8, 4);
3512
3513            let link_id = writer.links_mut().register("https://example.com");
3514            let mut buffer = Buffer::new(8, 2);
3515            buffer.set_raw(
3516                0,
3517                0,
3518                Cell::from_char('L').with_attrs(CellAttrs::new(StyleFlags::empty(), link_id)),
3519            );
3520            writer.present_ui(&buffer, None, true).unwrap();
3521        }
3522
3523        let open = b"\x1b]8;;https://example.com\x07";
3524        let close = b"\x1b]8;;\x07";
3525        let open_pos = output
3526            .windows(open.len())
3527            .position(|window| window == open)
3528            .expect("expected OSC 8 open sequence");
3529        let close_pos = output
3530            .windows(close.len())
3531            .position(|window| window == close)
3532            .expect("expected OSC 8 close sequence");
3533        assert!(
3534            open_pos < close_pos,
3535            "hyperlink must close before frame end"
3536        );
3537    }
3538
3539    #[test]
3540    fn present_ui_altscreen_skips_hyperlinks_in_mux() {
3541        let mut output = Vec::new();
3542        {
3543            let mut caps = mux_caps();
3544            caps.osc8_hyperlinks = true;
3545
3546            let mut writer =
3547                TerminalWriter::new(&mut output, ScreenMode::AltScreen, UiAnchor::Bottom, caps);
3548            writer.set_size(8, 4);
3549
3550            let link_id = writer.links_mut().register("https://example.com");
3551            let mut buffer = Buffer::new(8, 2);
3552            buffer.set_raw(
3553                0,
3554                0,
3555                Cell::from_char('L').with_attrs(CellAttrs::new(StyleFlags::empty(), link_id)),
3556            );
3557            writer.present_ui(&buffer, None, true).unwrap();
3558        }
3559
3560        assert!(
3561            !output.windows(b"\x1b]8;".len()).any(|w| w == b"\x1b]8;"),
3562            "OSC 8 sequences must be suppressed by mux hyperlink policy"
3563        );
3564    }
3565
3566    #[test]
3567    fn present_ui_altscreen_closes_hyperlinks_at_frame_end() {
3568        let mut output = Vec::new();
3569        {
3570            let mut caps = full_caps();
3571            caps.osc8_hyperlinks = true;
3572
3573            let mut writer =
3574                TerminalWriter::new(&mut output, ScreenMode::AltScreen, UiAnchor::Bottom, caps);
3575            writer.set_size(8, 4);
3576
3577            let link_id = writer.links_mut().register("https://example.com");
3578            let mut buffer = Buffer::new(8, 2);
3579            buffer.set_raw(
3580                0,
3581                0,
3582                Cell::from_char('L').with_attrs(CellAttrs::new(StyleFlags::empty(), link_id)),
3583            );
3584            writer.present_ui(&buffer, None, true).unwrap();
3585        }
3586
3587        let open = b"\x1b]8;;https://example.com\x07";
3588        let close = b"\x1b]8;;\x07";
3589        let open_pos = output
3590            .windows(open.len())
3591            .position(|window| window == open)
3592            .expect("expected OSC 8 open sequence");
3593        let close_pos = output
3594            .windows(close.len())
3595            .position(|window| window == close)
3596            .expect("expected OSC 8 close sequence");
3597        assert!(
3598            open_pos < close_pos,
3599            "hyperlink must close before frame end"
3600        );
3601    }
3602
3603    #[test]
3604    fn present_ui_hides_cursor_when_requested() {
3605        let mut output = Vec::new();
3606        {
3607            let mut writer = TerminalWriter::new(
3608                &mut output,
3609                ScreenMode::AltScreen,
3610                UiAnchor::Bottom,
3611                basic_caps(),
3612            );
3613            writer.set_size(10, 5);
3614
3615            let buffer = Buffer::new(10, 5);
3616            writer.present_ui(&buffer, None, false).unwrap();
3617        }
3618
3619        assert!(
3620            output.windows(6).any(|w| w == b"\x1b[?25l"),
3621            "expected cursor hide sequence"
3622        );
3623    }
3624
3625    #[test]
3626    fn present_ui_visible_with_position_temporarily_hides_cursor() {
3627        let mut output = Vec::new();
3628        {
3629            let mut writer = TerminalWriter::new(
3630                &mut output,
3631                ScreenMode::AltScreen,
3632                UiAnchor::Bottom,
3633                basic_caps(),
3634            );
3635            writer.set_size(10, 5);
3636
3637            let buffer = Buffer::new(10, 5);
3638            writer.present_ui(&buffer, Some((0, 0)), true).unwrap();
3639        }
3640
3641        assert!(
3642            output.windows(6).any(|w| w == b"\x1b[?25l"),
3643            "expected cursor hide during frame emission"
3644        );
3645    }
3646
3647    #[test]
3648    fn present_ui_visible_without_position_hides_cursor() {
3649        let mut output = Vec::new();
3650        {
3651            let mut writer = TerminalWriter::new(
3652                &mut output,
3653                ScreenMode::AltScreen,
3654                UiAnchor::Bottom,
3655                basic_caps(),
3656            );
3657            writer.set_size(10, 5);
3658
3659            let buffer = Buffer::new(10, 5);
3660            writer.present_ui(&buffer, None, true).unwrap();
3661        }
3662
3663        assert!(
3664            output.windows(6).any(|w| w == b"\x1b[?25l"),
3665            "expected cursor hide sequence when no explicit cursor position exists"
3666        );
3667    }
3668
3669    #[test]
3670    fn write_log_in_inline_mode() {
3671        let mut output = Vec::new();
3672        {
3673            let mut writer = TerminalWriter::new(
3674                &mut output,
3675                ScreenMode::Inline { ui_height: 5 },
3676                UiAnchor::Bottom,
3677                basic_caps(),
3678            );
3679            writer.write_log("test log\n").unwrap();
3680        }
3681
3682        let output_str = String::from_utf8_lossy(&output);
3683        assert!(output_str.contains("test log"));
3684    }
3685
3686    #[test]
3687    fn write_log_in_altscreen_is_noop() {
3688        let mut output = Vec::new();
3689        {
3690            let mut writer = TerminalWriter::new(
3691                &mut output,
3692                ScreenMode::AltScreen,
3693                UiAnchor::Bottom,
3694                basic_caps(),
3695            );
3696            writer.write_log("test log\n").unwrap();
3697        }
3698
3699        let output_str = String::from_utf8_lossy(&output);
3700        // Should not contain log text (altscreen drops logs)
3701        assert!(!output_str.contains("test log"));
3702    }
3703
3704    #[test]
3705    fn clear_screen_resets_prev_buffer() {
3706        let mut output = Vec::new();
3707        let mut writer = TerminalWriter::new(
3708            &mut output,
3709            ScreenMode::AltScreen,
3710            UiAnchor::Bottom,
3711            basic_caps(),
3712        );
3713
3714        // Present a buffer
3715        let buffer = Buffer::new(10, 5);
3716        writer.present_ui(&buffer, None, true).unwrap();
3717        assert!(writer.prev_buffer.is_some());
3718
3719        // Clear screen should reset
3720        writer.clear_screen().unwrap();
3721        assert!(writer.prev_buffer.is_none());
3722    }
3723
3724    #[test]
3725    fn set_size_clears_prev_buffer() {
3726        let output = Vec::new();
3727        let mut writer = TerminalWriter::new(
3728            output,
3729            ScreenMode::AltScreen,
3730            UiAnchor::Bottom,
3731            basic_caps(),
3732        );
3733
3734        writer.prev_buffer = Some(Buffer::new(10, 10));
3735        writer.set_size(20, 20);
3736
3737        assert!(writer.prev_buffer.is_none());
3738    }
3739
3740    #[test]
3741    fn inline_auto_resize_clears_cached_height() {
3742        let output = Vec::new();
3743        let mut writer = TerminalWriter::new(
3744            output,
3745            ScreenMode::InlineAuto {
3746                min_height: 3,
3747                max_height: 8,
3748            },
3749            UiAnchor::Bottom,
3750            basic_caps(),
3751        );
3752
3753        writer.set_size(80, 24);
3754        writer.set_auto_ui_height(6);
3755        assert_eq!(writer.auto_ui_height(), Some(6));
3756        assert_eq!(writer.render_height_hint(), 6);
3757
3758        writer.set_size(100, 30);
3759        assert_eq!(writer.auto_ui_height(), None);
3760        assert_eq!(writer.render_height_hint(), 8);
3761    }
3762
3763    #[test]
3764    fn drop_cleanup_restores_cursor() {
3765        let mut output = Vec::new();
3766        {
3767            let mut writer = TerminalWriter::new(
3768                &mut output,
3769                ScreenMode::Inline { ui_height: 5 },
3770                UiAnchor::Bottom,
3771                basic_caps(),
3772            );
3773            writer.cursor_saved = true;
3774            // Dropped here
3775        }
3776
3777        // Should contain cursor restore
3778        assert!(
3779            output
3780                .windows(CURSOR_RESTORE.len())
3781                .any(|w| w == CURSOR_RESTORE)
3782        );
3783    }
3784
3785    #[test]
3786    fn drop_cleanup_ends_sync_block() {
3787        let mut output = Vec::new();
3788        {
3789            let mut writer = TerminalWriter::new(
3790                &mut output,
3791                ScreenMode::Inline { ui_height: 5 },
3792                UiAnchor::Bottom,
3793                full_caps(),
3794            );
3795            writer.in_sync_block = true;
3796            // Dropped here
3797        }
3798
3799        // Should contain sync end
3800        assert!(output.windows(SYNC_END.len()).any(|w| w == SYNC_END));
3801    }
3802
3803    #[test]
3804    fn drop_cleanup_skips_sync_end_in_mux_even_with_stale_state() {
3805        let mut output = Vec::new();
3806        {
3807            let mut writer = TerminalWriter::new(
3808                &mut output,
3809                ScreenMode::Inline { ui_height: 5 },
3810                UiAnchor::Bottom,
3811                mux_caps(),
3812            );
3813            writer.in_sync_block = true;
3814            // Dropped here
3815        }
3816
3817        assert!(
3818            !output.windows(SYNC_END.len()).any(|w| w == SYNC_END),
3819            "drop cleanup must not emit sync_end in mux environments"
3820        );
3821    }
3822
3823    #[test]
3824    fn present_multiple_frames_uses_diff() {
3825        use std::io::Cursor;
3826
3827        // Use Cursor<Vec<u8>> which allows us to track position
3828        let output = Cursor::new(Vec::new());
3829        let mut writer = TerminalWriter::new(
3830            output,
3831            ScreenMode::AltScreen,
3832            UiAnchor::Bottom,
3833            basic_caps(),
3834        );
3835        writer.set_size(10, 5);
3836
3837        // First frame - full draw
3838        let mut buffer1 = Buffer::new(10, 5);
3839        buffer1.set_raw(0, 0, Cell::from_char('A'));
3840        writer.present_ui(&buffer1, None, true).unwrap();
3841
3842        // Second frame - same content (diff is empty, minimal output)
3843        writer.present_ui(&buffer1, None, true).unwrap();
3844
3845        // Third frame - change one cell
3846        let mut buffer2 = buffer1.clone();
3847        buffer2.set_raw(1, 0, Cell::from_char('B'));
3848        writer.present_ui(&buffer2, None, true).unwrap();
3849
3850        // Test passes if it doesn't panic - the diffing is working
3851        // (Detailed output length verification would require more complex setup)
3852    }
3853
3854    #[test]
3855    fn cell_content_rendered_correctly() {
3856        let mut output = Vec::new();
3857        {
3858            let mut writer = TerminalWriter::new(
3859                &mut output,
3860                ScreenMode::AltScreen,
3861                UiAnchor::Bottom,
3862                basic_caps(),
3863            );
3864            writer.set_size(10, 5);
3865
3866            let mut buffer = Buffer::new(10, 5);
3867            buffer.set_raw(0, 0, Cell::from_char('H'));
3868            buffer.set_raw(1, 0, Cell::from_char('i'));
3869            buffer.set_raw(2, 0, Cell::from_char('!'));
3870            writer.present_ui(&buffer, None, true).unwrap();
3871        }
3872
3873        let output_str = String::from_utf8_lossy(&output);
3874        assert!(output_str.contains('H'));
3875        assert!(output_str.contains('i'));
3876        assert!(output_str.contains('!'));
3877    }
3878
3879    #[test]
3880    fn resize_reanchors_ui_region() {
3881        let output = Vec::new();
3882        let mut writer = TerminalWriter::new(
3883            output,
3884            ScreenMode::Inline { ui_height: 10 },
3885            UiAnchor::Bottom,
3886            basic_caps(),
3887        );
3888
3889        // Initial size: 80x24, UI at row 14 (24 - 10)
3890        writer.set_size(80, 24);
3891        assert_eq!(writer.ui_start_row(), 14);
3892
3893        // After resize to 80x40, UI should be at row 30 (40 - 10)
3894        writer.set_size(80, 40);
3895        assert_eq!(writer.ui_start_row(), 30);
3896
3897        // After resize to smaller 80x15, UI at row 5 (15 - 10)
3898        writer.set_size(80, 15);
3899        assert_eq!(writer.ui_start_row(), 5);
3900    }
3901
3902    #[test]
3903    fn inline_auto_height_clamps_and_uses_max_for_render() {
3904        let output = Vec::new();
3905        let mut writer = TerminalWriter::new(
3906            output,
3907            ScreenMode::InlineAuto {
3908                min_height: 3,
3909                max_height: 8,
3910            },
3911            UiAnchor::Bottom,
3912            basic_caps(),
3913        );
3914        writer.set_size(80, 24);
3915
3916        // Default to min height until measured.
3917        assert_eq!(writer.ui_height(), 3);
3918        assert_eq!(writer.auto_ui_height(), None);
3919
3920        // render_height_hint uses max to allow measurement when cache is empty.
3921        assert_eq!(writer.render_height_hint(), 8);
3922
3923        // Cache hit: render_height_hint uses cached height.
3924        writer.set_auto_ui_height(6);
3925        assert_eq!(writer.render_height_hint(), 6);
3926
3927        // Cache miss: clearing restores max hint.
3928        writer.clear_auto_ui_height();
3929        assert_eq!(writer.render_height_hint(), 8);
3930
3931        // Cache should still set when clamped to min.
3932        writer.set_auto_ui_height(3);
3933        assert_eq!(writer.auto_ui_height(), Some(3));
3934        assert_eq!(writer.ui_height(), 3);
3935
3936        writer.clear_auto_ui_height();
3937        assert_eq!(writer.render_height_hint(), 8);
3938
3939        // Clamp to max.
3940        writer.set_auto_ui_height(10);
3941        assert_eq!(writer.ui_height(), 8);
3942
3943        // Clamp to min.
3944        writer.set_auto_ui_height(1);
3945        assert_eq!(writer.ui_height(), 3);
3946    }
3947
3948    #[test]
3949    fn resize_with_top_anchor_stays_at_zero() {
3950        let output = Vec::new();
3951        let mut writer = TerminalWriter::new(
3952            output,
3953            ScreenMode::Inline { ui_height: 10 },
3954            UiAnchor::Top,
3955            basic_caps(),
3956        );
3957
3958        writer.set_size(80, 24);
3959        assert_eq!(writer.ui_start_row(), 0);
3960
3961        writer.set_size(80, 40);
3962        assert_eq!(writer.ui_start_row(), 0);
3963    }
3964
3965    #[test]
3966    fn inline_mode_never_clears_full_screen() {
3967        let mut output = Vec::new();
3968        {
3969            let mut writer = TerminalWriter::new(
3970                &mut output,
3971                ScreenMode::Inline { ui_height: 5 },
3972                UiAnchor::Bottom,
3973                basic_caps(),
3974            );
3975            writer.set_size(10, 10);
3976
3977            let buffer = Buffer::new(10, 5);
3978            writer.present_ui(&buffer, None, true).unwrap();
3979        }
3980
3981        // Should NOT contain full screen clear (ED2 = "\x1b[2J")
3982        let has_ed2 = output.windows(4).any(|w| w == b"\x1b[2J");
3983        assert!(!has_ed2, "Inline mode should never use full screen clear");
3984
3985        // Should contain individual line clears (EL = "\x1b[2K")
3986        assert!(output.windows(ERASE_LINE.len()).any(|w| w == ERASE_LINE));
3987    }
3988
3989    #[test]
3990    fn present_after_log_maintains_cursor_position() {
3991        let mut output = Vec::new();
3992        {
3993            let mut writer = TerminalWriter::new(
3994                &mut output,
3995                ScreenMode::Inline { ui_height: 5 },
3996                UiAnchor::Bottom,
3997                basic_caps(),
3998            );
3999            writer.set_size(10, 10);
4000
4001            // Present UI first
4002            let buffer = Buffer::new(10, 5);
4003            writer.present_ui(&buffer, None, true).unwrap();
4004
4005            // Write a log
4006            writer.write_log("log line\n").unwrap();
4007
4008            // Present UI again
4009            writer.present_ui(&buffer, None, true).unwrap();
4010        }
4011
4012        // Should have cursor save before each UI present. Overlay log
4013        // writes add their own balanced SAVE/RESTORE pair, so only a floor
4014        // is asserted here; balance itself is covered by the overlay tests.
4015        let save_count = output
4016            .windows(CURSOR_SAVE.len())
4017            .filter(|w| *w == CURSOR_SAVE)
4018            .count();
4019        assert!(
4020            save_count >= 2,
4021            "Should have saved cursor at least twice (once per present)"
4022        );
4023
4024        // Should have cursor restore after each UI present
4025        let restore_count = output
4026            .windows(CURSOR_RESTORE.len())
4027            .filter(|w| *w == CURSOR_RESTORE)
4028            .count();
4029        // At least 2 from presents, plus 1 from drop cleanup = 3
4030        assert!(
4031            restore_count >= 2,
4032            "Should have restored cursor at least twice"
4033        );
4034    }
4035
4036    #[test]
4037    fn ui_height_bounds_check() {
4038        let output = Vec::new();
4039        let mut writer = TerminalWriter::new(
4040            output,
4041            ScreenMode::Inline { ui_height: 100 },
4042            UiAnchor::Bottom,
4043            basic_caps(),
4044        );
4045
4046        // Terminal smaller than UI height
4047        writer.set_size(80, 10);
4048
4049        // Should saturate to 0, not underflow
4050        assert_eq!(writer.ui_start_row(), 0);
4051    }
4052
4053    #[test]
4054    fn inline_ui_height_clamped_to_terminal_height() {
4055        let mut output = Vec::new();
4056        {
4057            let mut writer = TerminalWriter::new(
4058                &mut output,
4059                ScreenMode::Inline { ui_height: 10 },
4060                UiAnchor::Bottom,
4061                basic_caps(),
4062            );
4063            writer.set_size(8, 3);
4064            let buffer = Buffer::new(8, 10);
4065            writer.present_ui(&buffer, None, true).unwrap();
4066        }
4067
4068        let max_row = max_cursor_row(&output);
4069        assert!(
4070            max_row <= 3,
4071            "cursor row {} exceeds terminal height",
4072            max_row
4073        );
4074    }
4075
4076    #[test]
4077    fn inline_diff_frame_never_emits_below_the_fold() {
4078        // Regression: the incremental-diff branch emitted every diff run
4079        // unclipped. With ui_height > term_height, a change on a buffer row
4080        // below the fold produced a CUP past the physical bottom row, which
4081        // real terminals clamp — scribbling over the last visible row. The
4082        // full-redraw branch already clipped; the diff branch must too.
4083        let mut output = Vec::new();
4084        {
4085            let mut writer = TerminalWriter::new(
4086                &mut output,
4087                ScreenMode::Inline { ui_height: 20 },
4088                UiAnchor::Bottom,
4089                basic_caps(),
4090            );
4091            writer.set_size(80, 10); // terminal shorter than the UI
4092
4093            // Frame 1: full redraw (clipped by the existing logic).
4094            let buffer = Buffer::new(80, 20);
4095            writer.present_ui(&buffer, None, true).unwrap();
4096
4097            // Frame 2: change ONLY a below-the-fold row (row 19).
4098            let mut buffer2 = Buffer::new(80, 20);
4099            buffer2.set(0, 19, ftui_render::cell::Cell::from_char('B'));
4100            writer.present_ui(&buffer2, None, true).unwrap();
4101        }
4102
4103        let max_row = max_cursor_row(&output);
4104        assert!(
4105            max_row <= 10,
4106            "diff frame emitted cursor row {max_row} past the 10-row terminal"
4107        );
4108        // The below-the-fold glyph must not appear anywhere in the output.
4109        assert!(
4110            !output.windows(1).any(|w| w == b"B"),
4111            "below-the-fold cell was emitted"
4112        );
4113    }
4114
4115    #[test]
4116    fn inline_shrink_clears_stale_rows() {
4117        let mut output = Vec::new();
4118        {
4119            let mut writer = TerminalWriter::new(
4120                &mut output,
4121                ScreenMode::InlineAuto {
4122                    min_height: 1,
4123                    max_height: 6,
4124                },
4125                UiAnchor::Bottom,
4126                basic_caps(),
4127            );
4128            writer.set_size(10, 10);
4129
4130            let buffer = Buffer::new(10, 6);
4131            writer.set_auto_ui_height(6);
4132            writer.present_ui(&buffer, None, true).unwrap();
4133
4134            writer.set_auto_ui_height(3);
4135            writer.present_ui(&buffer, None, true).unwrap();
4136        }
4137
4138        let second_save = find_nth(&output, CURSOR_SAVE, 2).expect("expected second cursor save");
4139        let after_save = &output[second_save..];
4140        let restore_idx = after_save
4141            .windows(CURSOR_RESTORE.len())
4142            .position(|w| w == CURSOR_RESTORE)
4143            .expect("expected cursor restore after second save");
4144        let segment = &after_save[..restore_idx];
4145        let erase_count = segment
4146            .windows(ERASE_LINE.len())
4147            .filter(|w| *w == ERASE_LINE)
4148            .count();
4149        let bg_reset_count = segment
4150            .windows(SGR_BG_DEFAULT.len())
4151            .filter(|w| *w == SGR_BG_DEFAULT)
4152            .count();
4153
4154        assert_eq!(erase_count, 6, "expected clears for stale + new rows");
4155        assert!(
4156            bg_reset_count >= 2,
4157            "expected background resets before row clears"
4158        );
4159    }
4160
4161    // --- Scroll-region optimization tests ---
4162
4163    /// Capabilities that enable scroll-region strategy (no mux, scroll_region + sync_output).
4164    fn scroll_region_caps() -> TerminalCapabilities {
4165        let mut caps = TerminalCapabilities::basic();
4166        caps.scroll_region = true;
4167        caps.sync_output = true;
4168        caps
4169    }
4170
4171    /// Capabilities for hybrid strategy (scroll_region but no sync_output).
4172    fn hybrid_caps() -> TerminalCapabilities {
4173        let mut caps = TerminalCapabilities::basic();
4174        caps.scroll_region = true;
4175        caps
4176    }
4177
4178    /// Capabilities that force overlay (in tmux even with scroll_region).
4179    fn mux_caps() -> TerminalCapabilities {
4180        let mut caps = TerminalCapabilities::basic();
4181        caps.scroll_region = true;
4182        caps.sync_output = true;
4183        caps.in_tmux = true;
4184        caps
4185    }
4186
4187    #[test]
4188    fn scroll_region_bounds_bottom_anchor() {
4189        let mut output = Vec::new();
4190        {
4191            let mut writer = TerminalWriter::new(
4192                &mut output,
4193                ScreenMode::Inline { ui_height: 5 },
4194                UiAnchor::Bottom,
4195                scroll_region_caps(),
4196            );
4197            writer.set_size(10, 10);
4198            let buffer = Buffer::new(10, 5);
4199            writer.present_ui(&buffer, None, true).unwrap();
4200        }
4201
4202        let seq = b"\x1b[1;5r";
4203        assert!(
4204            output.windows(seq.len()).any(|w| w == seq),
4205            "expected scroll region for bottom anchor"
4206        );
4207    }
4208
4209    #[test]
4210    fn scroll_region_bounds_top_anchor() {
4211        let mut output = Vec::new();
4212        {
4213            let mut writer = TerminalWriter::new(
4214                &mut output,
4215                ScreenMode::Inline { ui_height: 5 },
4216                UiAnchor::Top,
4217                scroll_region_caps(),
4218            );
4219            writer.set_size(10, 10);
4220            let buffer = Buffer::new(10, 5);
4221            writer.present_ui(&buffer, None, true).unwrap();
4222        }
4223
4224        let seq = b"\x1b[6;10r";
4225        assert!(
4226            output.windows(seq.len()).any(|w| w == seq),
4227            "expected scroll region for top anchor"
4228        );
4229        let cursor_seq = b"\x1b[6;1H";
4230        assert!(
4231            output.windows(cursor_seq.len()).any(|w| w == cursor_seq),
4232            "expected cursor move into log region for top anchor"
4233        );
4234    }
4235
4236    #[test]
4237    fn present_ui_inline_resets_style_before_cursor_restore() {
4238        let mut output = Vec::new();
4239        {
4240            let mut writer = TerminalWriter::new(
4241                &mut output,
4242                ScreenMode::Inline { ui_height: 2 },
4243                UiAnchor::Bottom,
4244                basic_caps(),
4245            );
4246            writer.set_size(5, 5);
4247            let mut buffer = Buffer::new(5, 2);
4248            buffer.set_raw(0, 0, Cell::from_char('X').with_fg(PackedRgba::RED));
4249            writer.present_ui(&buffer, None, true).unwrap();
4250        }
4251
4252        let seq = b"\x1b[0m\x1b8";
4253        assert!(
4254            output.windows(seq.len()).any(|w| w == seq),
4255            "expected SGR reset before cursor restore in inline mode"
4256        );
4257    }
4258
4259    /// Regression for the "0 DECSTBM under xterm-256color" audit finding:
4260    /// scroll-region capability without sync output selects `Hybrid`, and
4261    /// the first inline present emits the DECSTBM region. (The audit run
4262    /// emitted none because this repository's WezTerm session counts as a
4263    /// multiplexer, which selects overlay redraw; that is the mux rule.)
4264    #[test]
4265    fn hybrid_strategy_emits_decstbm_without_sync() {
4266        let mut caps = TerminalCapabilities::basic();
4267        caps.scroll_region = true;
4268        caps.sync_output = false;
4269        let mut output = Vec::new();
4270        {
4271            let mut w = TerminalWriter::new(
4272                &mut output,
4273                ScreenMode::Inline { ui_height: 3 },
4274                UiAnchor::Bottom,
4275                caps,
4276            );
4277            w.set_size(80, 24);
4278            assert_eq!(w.inline_strategy(), InlineStrategy::Hybrid);
4279            assert_eq!(w.scroll_region_verified(), None);
4280
4281            let mut buffer = Buffer::new(80, 3);
4282            buffer.set(0, 0, ftui_render::cell::Cell::from_char('H'));
4283            w.present_ui(&buffer, None, false).expect("present");
4284            assert!(w.scroll_region_active());
4285        }
4286        let out = String::from_utf8_lossy(&output).into_owned();
4287        assert!(
4288            out.contains("\x1b[1;21r"),
4289            "Hybrid must set DECSTBM 1..rows-ui_height; got: {out:?}"
4290        );
4291        assert!(
4292            !out.contains("\x1b[?2026h"),
4293            "no sync brackets without sync output; got: {out:?}"
4294        );
4295    }
4296
4297    /// A negative DECSTBM self-test verdict switches a scroll-region
4298    /// strategy to overlay redraw before the first frame and exports the
4299    /// fallback with the ledger; a positive verdict keeps it.
4300    #[test]
4301    fn unverified_scroll_region_falls_back_to_overlay_and_exports_evidence() {
4302        use ftui_core::caps_probe::ScrollRegionVerdict;
4303
4304        let mut caps = TerminalCapabilities::basic();
4305        caps.scroll_region = true;
4306        caps.sync_output = false;
4307
4308        // Honoured: nothing changes.
4309        let mut kept_output = Vec::new();
4310        {
4311            let mut kept = TerminalWriter::new(
4312                &mut kept_output,
4313                ScreenMode::Inline { ui_height: 3 },
4314                UiAnchor::Bottom,
4315                caps,
4316            );
4317            kept.set_scroll_region_verified(
4318                Some(ScrollRegionVerdict::Honoured { observed_row: 21 }),
4319                24,
4320                21,
4321            );
4322            assert_eq!(kept.inline_strategy(), InlineStrategy::Hybrid);
4323            assert_eq!(kept.scroll_region_verified(), Some(true));
4324            assert!(kept.strategy_fallback().is_none());
4325        }
4326
4327        // Ignored: fall back, remember the fallback until a sink attaches.
4328        let evidence_path = temp_evidence_path("scroll_region_fallback");
4329        let mut output = Vec::new();
4330        {
4331            let mut w = TerminalWriter::new(
4332                &mut output,
4333                ScreenMode::Inline { ui_height: 3 },
4334                UiAnchor::Bottom,
4335                caps,
4336            );
4337            w.set_size(80, 24);
4338            w.set_scroll_region_verified(
4339                Some(ScrollRegionVerdict::Ignored { observed_row: 24 }),
4340                24,
4341                21,
4342            );
4343            assert_eq!(w.inline_strategy(), InlineStrategy::OverlayRedraw);
4344            assert_eq!(w.scroll_region_verified(), Some(false));
4345            let fallback = w.strategy_fallback().expect("fallback recorded").clone();
4346            assert_eq!(fallback.from, InlineStrategy::Hybrid);
4347            assert_eq!(fallback.reason, "cpr_mismatch");
4348            assert_eq!(fallback.observed_row, Some(24));
4349            assert_eq!(fallback.expected_row, 21);
4350
4351            let mut buffer = Buffer::new(80, 3);
4352            buffer.set(0, 0, ftui_render::cell::Cell::from_char('O'));
4353            w.present_ui(&buffer, None, false).expect("present");
4354            assert!(!w.scroll_region_active());
4355
4356            let sink = crate::evidence_sink::EvidenceSink::from_config(
4357                &crate::evidence_sink::EvidenceSinkConfig::enabled_file(&evidence_path),
4358            )
4359            .expect("sink config")
4360            .expect("sink enabled");
4361            w.set_evidence_sink(Some(sink));
4362            w.export_capability_decisions();
4363            assert!(w.strategy_fallback().is_none(), "exported once");
4364        }
4365        let out = String::from_utf8_lossy(&output).into_owned();
4366        assert!(
4367            !out.contains("\x1b[1;21r"),
4368            "no DECSTBM after the fallback; got: {out:?}"
4369        );
4370        let contents = std::fs::read_to_string(&evidence_path).expect("evidence written");
4371        assert!(
4372            contents.contains(
4373                r#"{"event":"inline_strategy_fallback","from":"hybrid","to":"overlay_redraw","reason":"cpr_mismatch","observed_row":24,"expected_row":21,"rows":24,"region_bottom":21}"#
4374            ),
4375            "{contents}"
4376        );
4377        assert!(
4378            contents.contains(r#""event":"inline_strategy","strategy":"overlay_redraw""#)
4379                && contents.contains(r#""scroll_region_verified":false"#),
4380            "{contents}"
4381        );
4382
4383        // Timeout counts as not honoured too.
4384        let mut timed_out_output = Vec::new();
4385        {
4386            let mut timed_out = TerminalWriter::new(
4387                &mut timed_out_output,
4388                ScreenMode::Inline { ui_height: 3 },
4389                UiAnchor::Bottom,
4390                caps,
4391            );
4392            timed_out.set_scroll_region_verified(Some(ScrollRegionVerdict::NoReply), 24, 21);
4393            assert_eq!(timed_out.inline_strategy(), InlineStrategy::OverlayRedraw);
4394            assert_eq!(
4395                timed_out.strategy_fallback().map(|f| f.reason),
4396                Some("cpr_timeout")
4397            );
4398        }
4399    }
4400
4401    #[test]
4402    fn evidence_sink_exports_capability_decisions_and_inline_strategy() {
4403        use ftui_core::capability_override::PolicyOverrides;
4404        use ftui_core::caps_probe::{ProbeConfig, ProbeResult, decisions_from_probe};
4405
4406        // A terminal that was not on the allowlist but answered DECRPM 2026.
4407        let mut before = TerminalCapabilities::basic();
4408        before.scroll_region = true;
4409        let config = ProbeConfig {
4410            probe_da1: false,
4411            probe_da2: false,
4412            probe_background: false,
4413            probe_truecolor: false,
4414            probe_sync_output: true,
4415            ..ProbeConfig::default()
4416        };
4417        let result = ProbeResult {
4418            sync_output: Some(true),
4419            ..ProbeResult::default()
4420        };
4421        let mut after = before;
4422        after.refine_from_probe(&result);
4423        let decisions = decisions_from_probe(
4424            &before,
4425            &config,
4426            &result,
4427            PolicyOverrides::default(),
4428            &after,
4429        );
4430
4431        let evidence_path = temp_evidence_path("capability_decisions");
4432        let sink = crate::evidence_sink::EvidenceSink::from_config(
4433            &crate::evidence_sink::EvidenceSinkConfig::enabled_file(&evidence_path),
4434        )
4435        .expect("sink config")
4436        .expect("sink enabled");
4437
4438        // Ledger attached before the sink: rows must still come out once.
4439        let w = TerminalWriter::new(
4440            Vec::new(),
4441            ScreenMode::Inline { ui_height: 5 },
4442            UiAnchor::Bottom,
4443            after,
4444        )
4445        .with_capability_decisions(decisions.clone())
4446        .with_evidence_sink(sink.clone());
4447        assert_eq!(w.inline_strategy(), InlineStrategy::ScrollRegion);
4448        drop(w);
4449
4450        // Sink attached before the ledger: same result.
4451        let w = TerminalWriter::new(
4452            Vec::new(),
4453            ScreenMode::Inline { ui_height: 5 },
4454            UiAnchor::Bottom,
4455            after,
4456        )
4457        .with_evidence_sink(sink)
4458        .with_capability_decisions(decisions);
4459        drop(w);
4460
4461        let contents = std::fs::read_to_string(&evidence_path).expect("evidence file written");
4462        let lines: Vec<&str> = contents.lines().collect();
4463        assert_eq!(
4464            lines.len(),
4465            8,
4466            "3 decisions + 1 strategy row, twice: {contents}"
4467        );
4468        for block in lines.chunks(4) {
4469            assert!(
4470                block[0].contains(r#""capability":"true_color""#),
4471                "{}",
4472                block[0]
4473            );
4474            assert!(
4475                block[1].contains(r#""capability":"sync_output""#),
4476                "{}",
4477                block[1]
4478            );
4479            assert!(block[1].contains(r#""probe":"confirmed""#), "{}", block[1]);
4480            assert!(block[1].contains(r#""final":true"#), "{}", block[1]);
4481            assert!(
4482                block[2].contains(r#""capability":"scroll_region""#),
4483                "{}",
4484                block[2]
4485            );
4486            assert!(block[2].contains(r#""probe":"not_probed""#), "{}", block[2]);
4487            assert_eq!(
4488                block[3],
4489                r#"{"event":"inline_strategy","strategy":"scroll_region","use_scroll_region":true,"use_sync_output":true,"in_mux":false,"scroll_region_verified":null}"#
4490            );
4491        }
4492    }
4493
4494    #[test]
4495    fn strategy_selected_from_capabilities() {
4496        // No capabilities → OverlayRedraw
4497        let w = TerminalWriter::new(
4498            Vec::new(),
4499            ScreenMode::Inline { ui_height: 5 },
4500            UiAnchor::Bottom,
4501            basic_caps(),
4502        );
4503        assert_eq!(w.inline_strategy(), InlineStrategy::OverlayRedraw);
4504
4505        // scroll_region + sync_output → ScrollRegion
4506        let w = TerminalWriter::new(
4507            Vec::new(),
4508            ScreenMode::Inline { ui_height: 5 },
4509            UiAnchor::Bottom,
4510            scroll_region_caps(),
4511        );
4512        assert_eq!(w.inline_strategy(), InlineStrategy::ScrollRegion);
4513
4514        // scroll_region only → Hybrid
4515        let w = TerminalWriter::new(
4516            Vec::new(),
4517            ScreenMode::Inline { ui_height: 5 },
4518            UiAnchor::Bottom,
4519            hybrid_caps(),
4520        );
4521        assert_eq!(w.inline_strategy(), InlineStrategy::Hybrid);
4522
4523        // In mux → OverlayRedraw even with all caps
4524        let w = TerminalWriter::new(
4525            Vec::new(),
4526            ScreenMode::Inline { ui_height: 5 },
4527            UiAnchor::Bottom,
4528            mux_caps(),
4529        );
4530        assert_eq!(w.inline_strategy(), InlineStrategy::OverlayRedraw);
4531    }
4532
4533    #[test]
4534    fn scroll_region_activated_on_present() {
4535        let mut output = Vec::new();
4536        {
4537            let mut writer = TerminalWriter::new(
4538                &mut output,
4539                ScreenMode::Inline { ui_height: 5 },
4540                UiAnchor::Bottom,
4541                scroll_region_caps(),
4542            );
4543            writer.set_size(80, 24);
4544            assert!(!writer.scroll_region_active());
4545
4546            let buffer = Buffer::new(80, 5);
4547            writer.present_ui(&buffer, None, true).unwrap();
4548            assert!(writer.scroll_region_active());
4549        }
4550
4551        // Should contain DECSTBM: ESC [ 1 ; 19 r (rows 1-19 are log region)
4552        let expected = b"\x1b[1;19r";
4553        assert!(
4554            output.windows(expected.len()).any(|w| w == expected),
4555            "Should set scroll region to rows 1-19"
4556        );
4557    }
4558
4559    #[test]
4560    fn scroll_region_not_activated_for_overlay() {
4561        let mut output = Vec::new();
4562        {
4563            let mut writer = TerminalWriter::new(
4564                &mut output,
4565                ScreenMode::Inline { ui_height: 5 },
4566                UiAnchor::Bottom,
4567                basic_caps(),
4568            );
4569            writer.set_size(80, 24);
4570
4571            let buffer = Buffer::new(80, 5);
4572            writer.present_ui(&buffer, None, true).unwrap();
4573            assert!(!writer.scroll_region_active());
4574        }
4575
4576        // Should NOT contain any scroll region setup
4577        let decstbm = b"\x1b[1;19r";
4578        assert!(
4579            !output.windows(decstbm.len()).any(|w| w == decstbm),
4580            "OverlayRedraw should not set scroll region"
4581        );
4582    }
4583
4584    #[test]
4585    fn scroll_region_not_activated_in_mux() {
4586        let mut output = Vec::new();
4587        {
4588            let mut writer = TerminalWriter::new(
4589                &mut output,
4590                ScreenMode::Inline { ui_height: 5 },
4591                UiAnchor::Bottom,
4592                mux_caps(),
4593            );
4594            writer.set_size(80, 24);
4595
4596            let buffer = Buffer::new(80, 5);
4597            writer.present_ui(&buffer, None, true).unwrap();
4598            assert!(!writer.scroll_region_active());
4599        }
4600
4601        // Should NOT contain scroll region setup despite having the capability
4602        let decstbm = b"\x1b[1;19r";
4603        assert!(
4604            !output.windows(decstbm.len()).any(|w| w == decstbm),
4605            "Mux environment should not use scroll region"
4606        );
4607    }
4608
4609    #[test]
4610    fn scroll_region_reset_on_cleanup() {
4611        let mut output = Vec::new();
4612        {
4613            let mut writer = TerminalWriter::new(
4614                &mut output,
4615                ScreenMode::Inline { ui_height: 5 },
4616                UiAnchor::Bottom,
4617                scroll_region_caps(),
4618            );
4619            writer.set_size(80, 24);
4620
4621            let buffer = Buffer::new(80, 5);
4622            writer.present_ui(&buffer, None, true).unwrap();
4623            // Dropped here - cleanup should reset scroll region
4624        }
4625
4626        // Should contain scroll region reset: ESC [ r
4627        let reset = b"\x1b[r";
4628        assert!(
4629            output.windows(reset.len()).any(|w| w == reset),
4630            "Cleanup should reset scroll region"
4631        );
4632    }
4633
4634    #[test]
4635    fn scroll_region_reset_on_resize() {
4636        let output = Vec::new();
4637        let mut writer = TerminalWriter::new(
4638            output,
4639            ScreenMode::Inline { ui_height: 5 },
4640            UiAnchor::Bottom,
4641            scroll_region_caps(),
4642        );
4643        writer.set_size(80, 24);
4644
4645        // Manually activate scroll region
4646        writer.activate_scroll_region(5).unwrap();
4647        assert!(writer.scroll_region_active());
4648
4649        // Resize should deactivate it
4650        writer.set_size(80, 40);
4651        assert!(!writer.scroll_region_active());
4652    }
4653
4654    #[test]
4655    fn scroll_region_reactivated_after_resize() {
4656        let mut output = Vec::new();
4657        {
4658            let mut writer = TerminalWriter::new(
4659                &mut output,
4660                ScreenMode::Inline { ui_height: 5 },
4661                UiAnchor::Bottom,
4662                scroll_region_caps(),
4663            );
4664            writer.set_size(80, 24);
4665
4666            // First present activates scroll region
4667            let buffer = Buffer::new(80, 5);
4668            writer.present_ui(&buffer, None, true).unwrap();
4669            assert!(writer.scroll_region_active());
4670
4671            // Resize deactivates
4672            writer.set_size(80, 40);
4673            assert!(!writer.scroll_region_active());
4674
4675            // Next present re-activates with new dimensions
4676            let buffer2 = Buffer::new(80, 5);
4677            writer.present_ui(&buffer2, None, true).unwrap();
4678            assert!(writer.scroll_region_active());
4679        }
4680
4681        // Should contain the new scroll region: ESC [ 1 ; 35 r (40 - 5 = 35)
4682        let new_region = b"\x1b[1;35r";
4683        assert!(
4684            output.windows(new_region.len()).any(|w| w == new_region),
4685            "Should set scroll region to new dimensions after resize"
4686        );
4687    }
4688
4689    #[test]
4690    fn hybrid_strategy_activates_scroll_region() {
4691        let mut output = Vec::new();
4692        {
4693            let mut writer = TerminalWriter::new(
4694                &mut output,
4695                ScreenMode::Inline { ui_height: 5 },
4696                UiAnchor::Bottom,
4697                hybrid_caps(),
4698            );
4699            writer.set_size(80, 24);
4700
4701            let buffer = Buffer::new(80, 5);
4702            writer.present_ui(&buffer, None, true).unwrap();
4703            assert!(writer.scroll_region_active());
4704        }
4705
4706        // Hybrid uses scroll region as internal optimization
4707        let expected = b"\x1b[1;19r";
4708        assert!(
4709            output.windows(expected.len()).any(|w| w == expected),
4710            "Hybrid should activate scroll region as optimization"
4711        );
4712    }
4713
4714    #[test]
4715    fn altscreen_does_not_activate_scroll_region() {
4716        let output = Vec::new();
4717        let mut writer = TerminalWriter::new(
4718            output,
4719            ScreenMode::AltScreen,
4720            UiAnchor::Bottom,
4721            scroll_region_caps(),
4722        );
4723        writer.set_size(80, 24);
4724
4725        let buffer = Buffer::new(80, 24);
4726        writer.present_ui(&buffer, None, true).unwrap();
4727        assert!(!writer.scroll_region_active());
4728    }
4729
4730    #[test]
4731    fn scroll_region_still_saves_restores_cursor() {
4732        let mut output = Vec::new();
4733        {
4734            let mut writer = TerminalWriter::new(
4735                &mut output,
4736                ScreenMode::Inline { ui_height: 5 },
4737                UiAnchor::Bottom,
4738                scroll_region_caps(),
4739            );
4740            writer.set_size(80, 24);
4741
4742            let buffer = Buffer::new(80, 5);
4743            writer.present_ui(&buffer, None, true).unwrap();
4744        }
4745
4746        // Even with scroll region, cursor save/restore is used for UI presents
4747        assert!(
4748            output.windows(CURSOR_SAVE.len()).any(|w| w == CURSOR_SAVE),
4749            "Scroll region mode should still save cursor"
4750        );
4751        assert!(
4752            output
4753                .windows(CURSOR_RESTORE.len())
4754                .any(|w| w == CURSOR_RESTORE),
4755            "Scroll region mode should still restore cursor"
4756        );
4757    }
4758
4759    // --- Log write cursor positioning tests (bd-xh8s) ---
4760
4761    #[test]
4762    fn write_log_positions_cursor_bottom_anchor() {
4763        // Verify log writes position cursor at the bottom of the log region
4764        // for bottom-anchored UI (log region is above UI).
4765        let mut output = Vec::new();
4766        {
4767            let mut writer = TerminalWriter::new(
4768                &mut output,
4769                ScreenMode::Inline { ui_height: 5 },
4770                UiAnchor::Bottom,
4771                basic_caps(),
4772            );
4773            writer.set_size(80, 24);
4774            writer.write_log("test log\n").unwrap();
4775        }
4776
4777        // For bottom-anchored with ui_height=5, term_height=24:
4778        // Log region is rows 1-19 (24-5=19 rows)
4779        // Cursor should be positioned at row 19 (bottom of log region)
4780        let expected_pos = b"\x1b[19;1H";
4781        assert!(
4782            output
4783                .windows(expected_pos.len())
4784                .any(|w| w == expected_pos),
4785            "Log write should position cursor at row 19 for bottom anchor"
4786        );
4787    }
4788
4789    #[test]
4790    fn write_log_positions_cursor_top_anchor() {
4791        // Verify log writes position cursor at the bottom of the log region
4792        // for top-anchored UI (log region is below UI).
4793        let mut output = Vec::new();
4794        {
4795            let mut writer = TerminalWriter::new(
4796                &mut output,
4797                ScreenMode::Inline { ui_height: 5 },
4798                UiAnchor::Top,
4799                basic_caps(),
4800            );
4801            writer.set_size(80, 24);
4802            writer.write_log("test log\n").unwrap();
4803        }
4804
4805        // For top-anchored with ui_height=5, term_height=24:
4806        // Log region is rows 6-24 (below UI)
4807        // Cursor should be positioned at row 24 (bottom of log region)
4808        let expected_pos = b"\x1b[24;1H";
4809        assert!(
4810            output
4811                .windows(expected_pos.len())
4812                .any(|w| w == expected_pos),
4813            "Log write should position cursor at row 24 for top anchor"
4814        );
4815    }
4816
4817    #[test]
4818    fn write_log_contains_text() {
4819        // Verify the log text is actually written after cursor positioning.
4820        let mut output = Vec::new();
4821        {
4822            let mut writer = TerminalWriter::new(
4823                &mut output,
4824                ScreenMode::Inline { ui_height: 5 },
4825                UiAnchor::Bottom,
4826                basic_caps(),
4827            );
4828            writer.set_size(80, 24);
4829            writer.write_log("hello world\n").unwrap();
4830        }
4831
4832        let output_str = String::from_utf8_lossy(&output);
4833        assert!(output_str.contains("hello world"));
4834    }
4835
4836    #[test]
4837    fn write_log_sanitizes_escape_injection_payloads() {
4838        let mut output = Vec::new();
4839        {
4840            let mut writer = TerminalWriter::new(
4841                &mut output,
4842                ScreenMode::Inline { ui_height: 5 },
4843                UiAnchor::Bottom,
4844                basic_caps(),
4845            );
4846            writer.set_size(80, 24);
4847            writer
4848                .write_log("safe\x1b]52;c;SGVsbG8=\x1b\\tail\u{009d}x\n")
4849                .unwrap();
4850        }
4851
4852        let output_str = String::from_utf8_lossy(&output);
4853        assert!(output_str.contains("safetailx"));
4854        assert!(
4855            !output_str.contains("52;c;SGVsbG8"),
4856            "OSC payload must not be forwarded to terminal output"
4857        );
4858        assert!(
4859            !output_str.contains('\u{009d}'),
4860            "C1 controls must be stripped from log output"
4861        );
4862    }
4863
4864    #[test]
4865    fn write_log_multiple_writes_position_each_time() {
4866        // Verify cursor is positioned for each log write.
4867        let mut output = Vec::new();
4868        {
4869            let mut writer = TerminalWriter::new(
4870                &mut output,
4871                ScreenMode::Inline { ui_height: 5 },
4872                UiAnchor::Bottom,
4873                basic_caps(),
4874            );
4875            writer.set_size(80, 24);
4876            writer.write_log("first\n").unwrap();
4877            writer.write_log("second\n").unwrap();
4878        }
4879
4880        // Should have cursor positioning twice
4881        let expected_pos = b"\x1b[19;1H";
4882        let count = output
4883            .windows(expected_pos.len())
4884            .filter(|w| *w == expected_pos)
4885            .count();
4886        assert_eq!(count, 2, "Should position cursor for each log write");
4887    }
4888
4889    #[test]
4890    fn write_log_after_present_ui_works_correctly() {
4891        // Verify log writes work correctly after UI presentation.
4892        let mut output = Vec::new();
4893        {
4894            let mut writer = TerminalWriter::new(
4895                &mut output,
4896                ScreenMode::Inline { ui_height: 5 },
4897                UiAnchor::Bottom,
4898                basic_caps(),
4899            );
4900            writer.set_size(80, 24);
4901
4902            // Present UI first
4903            let buffer = Buffer::new(80, 5);
4904            writer.present_ui(&buffer, None, true).unwrap();
4905
4906            // Then write log
4907            writer.write_log("after UI\n").unwrap();
4908        }
4909
4910        let output_str = String::from_utf8_lossy(&output);
4911        assert!(output_str.contains("after UI"));
4912
4913        // Log write should still position cursor
4914        let expected_pos = b"\x1b[19;1H";
4915        // Find position after cursor restore (log write happens after present_ui)
4916        assert!(
4917            output
4918                .windows(expected_pos.len())
4919                .any(|w| w == expected_pos),
4920            "Log write after present_ui should position cursor"
4921        );
4922    }
4923
4924    #[test]
4925    fn write_log_ui_fills_terminal_is_noop() {
4926        // When UI fills the entire terminal, there's no log region.
4927        // Drop cleanup writes reset sequences (\x1b[0m, \x1b[?25h), so we
4928        // verify the output does not contain the log text itself.
4929        let mut output = Vec::new();
4930        {
4931            let mut writer = TerminalWriter::new(
4932                &mut output,
4933                ScreenMode::Inline { ui_height: 24 },
4934                UiAnchor::Bottom,
4935                basic_caps(),
4936            );
4937            writer.set_size(80, 24);
4938            writer.write_log("should still write\n").unwrap();
4939        }
4940        // Log text must NOT appear; only Drop cleanup sequences are expected.
4941        assert!(
4942            !output
4943                .windows(b"should still write".len())
4944                .any(|w| w == b"should still write"),
4945            "write_log should not emit log text when UI fills the terminal"
4946        );
4947    }
4948
4949    #[test]
4950    fn write_log_with_scroll_region_active() {
4951        // Verify log writes work correctly when scroll region is active.
4952        let mut output = Vec::new();
4953        {
4954            let mut writer = TerminalWriter::new(
4955                &mut output,
4956                ScreenMode::Inline { ui_height: 5 },
4957                UiAnchor::Bottom,
4958                scroll_region_caps(),
4959            );
4960            writer.set_size(80, 24);
4961
4962            // Present UI to activate scroll region
4963            let buffer = Buffer::new(80, 5);
4964            writer.present_ui(&buffer, None, true).unwrap();
4965            assert!(writer.scroll_region_active());
4966
4967            // Log write should still position cursor
4968            writer.write_log("with scroll region\n").unwrap();
4969        }
4970
4971        let output_str = String::from_utf8_lossy(&output);
4972        assert!(output_str.contains("with scroll region"));
4973    }
4974
4975    #[test]
4976    fn log_write_cursor_position_not_in_ui_region_bottom_anchor() {
4977        // Verify the cursor position for log writes is never in the UI region.
4978        // For bottom-anchored with ui_height=5, term_height=24:
4979        // UI region is rows 20-24 (1-indexed)
4980        // Log region is rows 1-19
4981        // Log cursor should be at row 19 (bottom of log region)
4982        let mut output = Vec::new();
4983        {
4984            let mut writer = TerminalWriter::new(
4985                &mut output,
4986                ScreenMode::Inline { ui_height: 5 },
4987                UiAnchor::Bottom,
4988                basic_caps(),
4989            );
4990            writer.set_size(80, 24);
4991            writer.write_log("test\n").unwrap();
4992        }
4993
4994        // Parse cursor position commands in output
4995        // Looking for ESC [ row ; col H patterns
4996        let mut found_row = None;
4997        let mut i = 0;
4998        while i + 2 < output.len() {
4999            if output[i] == 0x1b && output[i + 1] == b'[' {
5000                let mut j = i + 2;
5001                let mut row: u16 = 0;
5002                while j < output.len() && output[j].is_ascii_digit() {
5003                    row = row * 10 + (output[j] - b'0') as u16;
5004                    j += 1;
5005                }
5006                if j < output.len() && output[j] == b';' {
5007                    j += 1;
5008                    while j < output.len() && output[j].is_ascii_digit() {
5009                        j += 1;
5010                    }
5011                    if j < output.len() && output[j] == b'H' {
5012                        found_row = Some(row);
5013                    }
5014                }
5015            }
5016            i += 1;
5017        }
5018
5019        if let Some(row) = found_row {
5020            // UI region starts at row 20 (24 - 5 + 1 = 20)
5021            assert!(
5022                row < 20,
5023                "Log cursor row {} should be below UI start row 20",
5024                row
5025            );
5026        }
5027    }
5028
5029    #[test]
5030    fn log_write_cursor_position_not_in_ui_region_top_anchor() {
5031        // Verify the cursor position for log writes is never in the UI region.
5032        // For top-anchored with ui_height=5, term_height=24:
5033        // UI region is rows 1-5 (1-indexed)
5034        // Log region is rows 6-24
5035        // Log cursor should be at row 24 (bottom of log region)
5036        let mut output = Vec::new();
5037        {
5038            let mut writer = TerminalWriter::new(
5039                &mut output,
5040                ScreenMode::Inline { ui_height: 5 },
5041                UiAnchor::Top,
5042                basic_caps(),
5043            );
5044            writer.set_size(80, 24);
5045            writer.write_log("test\n").unwrap();
5046        }
5047
5048        // Parse cursor position commands in output
5049        let mut found_row = None;
5050        let mut i = 0;
5051        while i + 2 < output.len() {
5052            if output[i] == 0x1b && output[i + 1] == b'[' {
5053                let mut j = i + 2;
5054                let mut row: u16 = 0;
5055                while j < output.len() && output[j].is_ascii_digit() {
5056                    row = row * 10 + (output[j] - b'0') as u16;
5057                    j += 1;
5058                }
5059                if j < output.len() && output[j] == b';' {
5060                    j += 1;
5061                    while j < output.len() && output[j].is_ascii_digit() {
5062                        j += 1;
5063                    }
5064                    if j < output.len() && output[j] == b'H' {
5065                        found_row = Some(row);
5066                    }
5067                }
5068            }
5069            i += 1;
5070        }
5071
5072        if let Some(row) = found_row {
5073            // UI region is rows 1-5
5074            assert!(
5075                row > 5,
5076                "Log cursor row {} should be above UI end row 5",
5077                row
5078            );
5079        }
5080    }
5081
5082    #[test]
5083    fn present_ui_positions_cursor_after_restore() {
5084        let mut output = Vec::new();
5085        {
5086            let mut writer = TerminalWriter::new(
5087                &mut output,
5088                ScreenMode::Inline { ui_height: 5 },
5089                UiAnchor::Bottom,
5090                basic_caps(),
5091            );
5092            writer.set_size(80, 24);
5093
5094            let buffer = Buffer::new(80, 5);
5095            // Request cursor at (2, 1) in UI coordinates
5096            writer.present_ui(&buffer, Some((2, 1)), true).unwrap();
5097        }
5098
5099        // UI starts at row 20 (24 - 5 + 1 = 20) (1-indexed)
5100        // Cursor requested at relative (2, 1) -> (x=3, y=2) (1-indexed)
5101        // Absolute position: y = 20 + 1 = 21. x = 3.
5102        let expected_pos = b"\x1b[21;3H";
5103
5104        // Find restore
5105        let restore_idx = find_nth(&output, CURSOR_RESTORE, 1).expect("expected cursor restore");
5106        let after_restore = &output[restore_idx..];
5107
5108        // Ensure cursor positioning happens *after* restore
5109        assert!(
5110            after_restore
5111                .windows(expected_pos.len())
5112                .any(|w| w == expected_pos),
5113            "Cursor positioning should happen after restore"
5114        );
5115    }
5116
5117    #[test]
5118    fn present_ui_inline_skips_cursor_position_when_x_is_out_of_bounds() {
5119        let mut output = Vec::new();
5120        {
5121            let mut writer = TerminalWriter::new(
5122                &mut output,
5123                ScreenMode::Inline { ui_height: 5 },
5124                UiAnchor::Bottom,
5125                basic_caps(),
5126            );
5127            writer.set_size(80, 24);
5128
5129            let buffer = Buffer::new(4, 5);
5130            writer.present_ui(&buffer, Some((4, 1)), true).unwrap();
5131        }
5132
5133        let restore_idx = find_nth(&output, CURSOR_RESTORE, 1).expect("expected cursor restore");
5134        let after_restore = &output[restore_idx..];
5135        let invalid_pos = b"\x1b[21;5H";
5136        assert!(
5137            !after_restore
5138                .windows(invalid_pos.len())
5139                .any(|w| w == invalid_pos),
5140            "inline cursor should not move to x outside the buffer width"
5141        );
5142    }
5143
5144    #[test]
5145    fn present_ui_inline_skips_cursor_position_when_y_is_below_buffer_height() {
5146        let mut output = Vec::new();
5147        {
5148            let mut writer = TerminalWriter::new(
5149                &mut output,
5150                ScreenMode::Inline { ui_height: 5 },
5151                UiAnchor::Bottom,
5152                basic_caps(),
5153            );
5154            writer.set_size(80, 24);
5155
5156            let buffer = Buffer::new(4, 2);
5157            writer.present_ui(&buffer, Some((1, 4)), true).unwrap();
5158        }
5159
5160        let restore_idx = find_nth(&output, CURSOR_RESTORE, 1).expect("expected cursor restore");
5161        let after_restore = &output[restore_idx..];
5162        let invalid_pos = b"\x1b[24;2H";
5163        assert!(
5164            !after_restore
5165                .windows(invalid_pos.len())
5166                .any(|w| w == invalid_pos),
5167            "inline cursor should not move below the buffer height just because the inline region is taller"
5168        );
5169    }
5170
5171    // =========================================================================
5172    // RuntimeDiffConfig tests
5173    // =========================================================================
5174
5175    #[test]
5176    fn runtime_diff_config_default() {
5177        let config = RuntimeDiffConfig::default();
5178        assert!(config.bayesian_enabled);
5179        assert!(config.dirty_rows_enabled);
5180        assert!(config.dirty_span_config.enabled);
5181        assert!(config.tile_diff_config.enabled);
5182        assert!(config.reset_on_resize);
5183        assert!(config.reset_on_invalidation);
5184        assert_eq!(config.full_redraw_interval_frames, 240);
5185    }
5186
5187    #[test]
5188    fn runtime_diff_config_builder() {
5189        let custom_span = DirtySpanConfig::default().with_max_spans_per_row(8);
5190        let tile_config = TileDiffConfig::default()
5191            .with_enabled(false)
5192            .with_tile_size(24, 12)
5193            .with_dense_tile_ratio(0.75)
5194            .with_max_tiles(2048);
5195        let config = RuntimeDiffConfig::new()
5196            .with_bayesian_enabled(false)
5197            .with_dirty_rows_enabled(false)
5198            .with_dirty_span_config(custom_span)
5199            .with_dirty_spans_enabled(false)
5200            .with_tile_diff_config(tile_config)
5201            .with_reset_on_resize(false)
5202            .with_reset_on_invalidation(false)
5203            .with_full_redraw_interval_frames(17);
5204
5205        assert!(!config.bayesian_enabled);
5206        assert!(!config.dirty_rows_enabled);
5207        assert!(!config.dirty_span_config.enabled);
5208        assert_eq!(config.dirty_span_config.max_spans_per_row, 8);
5209        assert!(!config.tile_diff_config.enabled);
5210        assert_eq!(config.tile_diff_config.tile_w, 24);
5211        assert_eq!(config.tile_diff_config.tile_h, 12);
5212        assert_eq!(config.tile_diff_config.max_tiles, 2048);
5213        assert!(!config.reset_on_resize);
5214        assert!(!config.reset_on_invalidation);
5215        assert_eq!(config.full_redraw_interval_frames, 17);
5216    }
5217
5218    #[test]
5219    fn with_diff_config_applies_strategy_config() {
5220        use ftui_render::diff_strategy::DiffStrategyConfig;
5221
5222        let strategy_config = DiffStrategyConfig {
5223            prior_alpha: 5.0,
5224            prior_beta: 5.0,
5225            ..Default::default()
5226        };
5227
5228        let runtime_config =
5229            RuntimeDiffConfig::default().with_strategy_config(strategy_config.clone());
5230
5231        let writer = TerminalWriter::with_diff_config(
5232            Vec::<u8>::new(),
5233            ScreenMode::AltScreen,
5234            UiAnchor::Bottom,
5235            basic_caps(),
5236            runtime_config,
5237        );
5238
5239        // Verify the strategy config was applied
5240        let (alpha, beta) = writer.diff_strategy().posterior_params();
5241        assert!((alpha - 5.0).abs() < 0.001);
5242        assert!((beta - 5.0).abs() < 0.001);
5243    }
5244
5245    #[test]
5246    fn with_diff_config_applies_tile_config() {
5247        let tile_config = TileDiffConfig::default()
5248            .with_enabled(false)
5249            .with_tile_size(32, 16)
5250            .with_max_tiles(1024);
5251        let runtime_config = RuntimeDiffConfig::default().with_tile_diff_config(tile_config);
5252
5253        let mut writer = TerminalWriter::with_diff_config(
5254            Vec::<u8>::new(),
5255            ScreenMode::AltScreen,
5256            UiAnchor::Bottom,
5257            basic_caps(),
5258            runtime_config,
5259        );
5260
5261        let applied = writer.diff_scratch.tile_config_mut();
5262        assert!(!applied.enabled);
5263        assert_eq!(applied.tile_w, 32);
5264        assert_eq!(applied.tile_h, 16);
5265        assert_eq!(applied.max_tiles, 1024);
5266    }
5267
5268    #[test]
5269    fn diff_config_accessor() {
5270        let config = RuntimeDiffConfig::default().with_bayesian_enabled(false);
5271
5272        let writer = TerminalWriter::with_diff_config(
5273            Vec::<u8>::new(),
5274            ScreenMode::AltScreen,
5275            UiAnchor::Bottom,
5276            basic_caps(),
5277            config,
5278        );
5279
5280        assert!(!writer.diff_config().bayesian_enabled);
5281    }
5282
5283    #[test]
5284    fn last_diff_strategy_updates_after_present() {
5285        let mut output = Vec::new();
5286        let mut writer = TerminalWriter::with_diff_config(
5287            &mut output,
5288            ScreenMode::AltScreen,
5289            UiAnchor::Bottom,
5290            basic_caps(),
5291            RuntimeDiffConfig::default(),
5292        );
5293        writer.set_size(10, 3);
5294
5295        let mut buffer = Buffer::new(10, 3);
5296        buffer.set_raw(0, 0, Cell::from_char('X'));
5297
5298        assert!(writer.last_diff_strategy().is_none());
5299        writer.present_ui(&buffer, None, false).unwrap();
5300        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5301
5302        buffer.set_raw(1, 1, Cell::from_char('Y'));
5303        writer.present_ui(&buffer, None, false).unwrap();
5304        assert!(writer.last_diff_strategy().is_some());
5305    }
5306
5307    #[test]
5308    fn full_redraw_interval_forces_terminal_resync() {
5309        let mut output = Vec::new();
5310        let mut writer = TerminalWriter::with_diff_config(
5311            &mut output,
5312            ScreenMode::AltScreen,
5313            UiAnchor::Bottom,
5314            basic_caps(),
5315            RuntimeDiffConfig::default()
5316                .with_bayesian_enabled(false)
5317                .with_full_redraw_interval_frames(1),
5318        );
5319        writer.set_size(4, 2);
5320
5321        let mut buffer = Buffer::new(4, 2);
5322        buffer.set_raw(0, 0, Cell::from_char('A'));
5323
5324        writer.present_ui(&buffer, None, false).unwrap();
5325        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5326
5327        writer.present_ui(&buffer, None, false).unwrap();
5328        assert_ne!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5329
5330        writer.present_ui(&buffer, None, false).unwrap();
5331        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5332    }
5333
5334    #[test]
5335    fn full_redraw_interval_emits_current_frame_after_incremental_baseline() {
5336        let state = Rc::new(RefCell::new(FaultState::default()));
5337        let writer_backend = SingleWriteFaultWriter::new(Rc::clone(&state), usize::MAX, 1);
5338        let mut writer = TerminalWriter::with_diff_config(
5339            writer_backend,
5340            ScreenMode::AltScreen,
5341            UiAnchor::Bottom,
5342            basic_caps(),
5343            RuntimeDiffConfig::default()
5344                .with_bayesian_enabled(false)
5345                .with_full_redraw_interval_frames(1),
5346        );
5347        writer.set_size(4, 2);
5348
5349        let mut buffer = Buffer::new(4, 2);
5350        buffer.set_raw(0, 0, Cell::from_char('Q'));
5351
5352        writer.present_ui(&buffer, None, false).unwrap();
5353        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5354
5355        buffer.set_raw(1, 0, Cell::from_char('Z'));
5356        writer.present_ui(&buffer, None, false).unwrap();
5357        assert_ne!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5358
5359        state.borrow_mut().bytes.clear();
5360        writer.present_ui(&buffer, None, false).unwrap();
5361        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5362
5363        let bytes = state.borrow().bytes.clone();
5364        assert!(
5365            bytes.windows(b"QZ".len()).any(|window| window == b"QZ"),
5366            "forced full redraw should emit adjacent current-frame cells"
5367        );
5368    }
5369
5370    #[test]
5371    fn full_redraw_interval_zero_disables_terminal_resync() {
5372        let mut output = Vec::new();
5373        let mut writer = TerminalWriter::with_diff_config(
5374            &mut output,
5375            ScreenMode::AltScreen,
5376            UiAnchor::Bottom,
5377            basic_caps(),
5378            RuntimeDiffConfig::default()
5379                .with_bayesian_enabled(false)
5380                .with_full_redraw_interval_frames(0),
5381        );
5382        writer.set_size(4, 2);
5383
5384        let mut buffer = Buffer::new(4, 2);
5385        buffer.set_raw(0, 0, Cell::from_char('A'));
5386
5387        writer.present_ui(&buffer, None, false).unwrap();
5388        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5389
5390        for _ in 0..5 {
5391            writer.present_ui(&buffer, None, false).unwrap();
5392            assert_ne!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5393        }
5394    }
5395
5396    #[test]
5397    fn full_redraw_max_interval_zero_forces_resync_every_frame() {
5398        // A zero wall-clock interval means "always due": every present must be a
5399        // full physical redraw, regardless of the frame counter. This is the
5400        // wall-clock bound that repairs terminal-state desync on an idle /
5401        // sparsely-rendering TUI where the frame counter advances too slowly.
5402        let mut output = Vec::new();
5403        let mut writer = TerminalWriter::with_diff_config(
5404            &mut output,
5405            ScreenMode::AltScreen,
5406            UiAnchor::Bottom,
5407            basic_caps(),
5408            RuntimeDiffConfig::default()
5409                .with_bayesian_enabled(false)
5410                // Disable the frame-count path to isolate the wall-clock bound.
5411                .with_full_redraw_interval_frames(0)
5412                .with_full_redraw_max_interval(Some(std::time::Duration::ZERO)),
5413        );
5414        writer.set_size(4, 2);
5415
5416        let mut buffer = Buffer::new(4, 2);
5417        buffer.set_raw(0, 0, Cell::from_char('A'));
5418
5419        // First frame is a full redraw (no prior baseline) and every subsequent
5420        // frame is forced full by the zero interval.
5421        for _ in 0..5 {
5422            writer.present_ui(&buffer, None, false).unwrap();
5423            assert_eq!(
5424                writer.last_diff_strategy(),
5425                Some(DiffStrategy::FullRedraw),
5426                "zero wall-clock interval must force a full redraw every frame"
5427            );
5428        }
5429    }
5430
5431    #[test]
5432    fn full_redraw_max_interval_none_keeps_incremental_after_baseline() {
5433        // The wall-clock bound is opt-in: with it unset (None) and the
5434        // frame-count path disabled, frames stay incremental after the initial
5435        // baseline full redraw — preserving the default sparse-diff behavior and
5436        // deterministic-test reproducibility.
5437        let mut output = Vec::new();
5438        let mut writer = TerminalWriter::with_diff_config(
5439            &mut output,
5440            ScreenMode::AltScreen,
5441            UiAnchor::Bottom,
5442            basic_caps(),
5443            RuntimeDiffConfig::default()
5444                .with_bayesian_enabled(false)
5445                .with_full_redraw_interval_frames(0)
5446                .with_full_redraw_max_interval(None),
5447        );
5448        writer.set_size(4, 2);
5449
5450        let mut buffer = Buffer::new(4, 2);
5451        buffer.set_raw(0, 0, Cell::from_char('A'));
5452
5453        writer.present_ui(&buffer, None, false).unwrap();
5454        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
5455
5456        for _ in 0..5 {
5457            writer.present_ui(&buffer, None, false).unwrap();
5458            assert_ne!(
5459                writer.last_diff_strategy(),
5460                Some(DiffStrategy::FullRedraw),
5461                "no wall-clock bound must leave frames incremental after baseline"
5462            );
5463        }
5464    }
5465
5466    #[test]
5467    fn diff_decision_evidence_schema_includes_span_fields() {
5468        let evidence_path = temp_evidence_path("diff_decision_schema");
5469        let sink = EvidenceSink::from_config(
5470            &crate::evidence_sink::EvidenceSinkConfig::enabled_file(&evidence_path),
5471        )
5472        .expect("evidence sink config")
5473        .expect("evidence sink enabled");
5474
5475        let mut writer = TerminalWriter::with_diff_config(
5476            Vec::<u8>::new(),
5477            ScreenMode::AltScreen,
5478            UiAnchor::Bottom,
5479            basic_caps(),
5480            RuntimeDiffConfig::default(),
5481        )
5482        .with_evidence_sink(sink);
5483        writer.set_size(10, 3);
5484
5485        let mut buffer = Buffer::new(10, 3);
5486        buffer.set_raw(0, 0, Cell::from_char('X'));
5487        writer.present_ui(&buffer, None, false).unwrap();
5488
5489        buffer.set_raw(1, 1, Cell::from_char('Y'));
5490        writer.present_ui(&buffer, None, false).unwrap();
5491
5492        let jsonl = std::fs::read_to_string(&evidence_path).expect("read evidence jsonl");
5493        let line = jsonl
5494            .lines()
5495            .find(|line| line.contains("\"event\":\"diff_decision\""))
5496            .expect("diff_decision line");
5497        let value: serde_json::Value = serde_json::from_str(line).expect("valid json");
5498
5499        assert_eq!(
5500            value["schema_version"],
5501            crate::evidence_sink::EVIDENCE_SCHEMA_VERSION
5502        );
5503        assert_eq!(value["event"], "diff_decision");
5504        assert!(
5505            value["run_id"]
5506                .as_str()
5507                .map(|s| !s.is_empty())
5508                .unwrap_or(false),
5509            "run_id should be a non-empty string"
5510        );
5511        assert!(
5512            value["event_idx"].is_number(),
5513            "event_idx should be numeric"
5514        );
5515        assert_eq!(value["screen_mode"], "altscreen");
5516        assert!(value["cols"].is_number(), "cols should be numeric");
5517        assert!(value["rows"].is_number(), "rows should be numeric");
5518        assert!(
5519            value["span_count"].is_number(),
5520            "span_count should be numeric"
5521        );
5522        assert!(
5523            value["span_coverage_pct"].is_number(),
5524            "span_coverage_pct should be numeric"
5525        );
5526        assert!(
5527            value["tile_size"].is_number(),
5528            "tile_size should be numeric"
5529        );
5530        assert!(
5531            value["dirty_tile_count"].is_number(),
5532            "dirty_tile_count should be numeric"
5533        );
5534        assert!(
5535            value["skipped_tile_count"].is_number(),
5536            "skipped_tile_count should be numeric"
5537        );
5538        assert!(
5539            value["sat_build_cost_est"].is_number(),
5540            "sat_build_cost_est should be numeric"
5541        );
5542        assert!(
5543            value["skipped_tile_rows"].is_number(),
5544            "skipped_tile_rows should be numeric"
5545        );
5546        assert!(
5547            value["sat_queries"].is_number(),
5548            "sat_queries should be numeric"
5549        );
5550        assert!(
5551            value["fallback_reason"].is_string(),
5552            "fallback_reason should be string"
5553        );
5554        assert!(
5555            value["scan_cost_estimate"].is_number(),
5556            "scan_cost_estimate should be numeric"
5557        );
5558        assert!(
5559            value["max_span_len"].is_number(),
5560            "max_span_len should be numeric"
5561        );
5562        assert!(
5563            value["guard_reason"].is_string(),
5564            "guard_reason should be a string"
5565        );
5566        assert!(
5567            value["hysteresis_applied"].is_boolean(),
5568            "hysteresis_applied should be boolean"
5569        );
5570        assert!(
5571            value["hysteresis_ratio"].is_number(),
5572            "hysteresis_ratio should be numeric"
5573        );
5574        assert!(
5575            value["fallback_reason"].is_string(),
5576            "fallback_reason should be a string"
5577        );
5578        assert!(
5579            value["scan_cost_estimate"].is_number(),
5580            "scan_cost_estimate should be numeric"
5581        );
5582    }
5583
5584    #[test]
5585    fn diff_decision_has_regime_field() {
5586        let evidence_path = temp_evidence_path("diff_decision_has_regime");
5587        let sink = EvidenceSink::from_config(
5588            &crate::evidence_sink::EvidenceSinkConfig::enabled_file(&evidence_path),
5589        )
5590        .expect("evidence sink config")
5591        .expect("evidence sink enabled");
5592
5593        let mut writer = TerminalWriter::with_diff_config(
5594            Vec::<u8>::new(),
5595            ScreenMode::AltScreen,
5596            UiAnchor::Bottom,
5597            basic_caps(),
5598            RuntimeDiffConfig::default(),
5599        )
5600        .with_evidence_sink(sink);
5601        writer.set_size(10, 3);
5602
5603        let mut buffer = Buffer::new(10, 3);
5604        buffer.set_raw(0, 0, Cell::from_char('X'));
5605        writer.present_ui(&buffer, None, false).unwrap();
5606
5607        buffer.set_raw(1, 1, Cell::from_char('Y'));
5608        writer.present_ui(&buffer, None, false).unwrap();
5609
5610        let jsonl = std::fs::read_to_string(&evidence_path).expect("read evidence jsonl");
5611        let line = jsonl
5612            .lines()
5613            .find(|line| line.contains("\"event\":\"diff_decision\""))
5614            .expect("diff_decision line");
5615        let value: serde_json::Value = serde_json::from_str(line).expect("valid json");
5616
5617        assert_eq!(value["event"], "diff_decision");
5618        assert!(
5619            value.get("regime").is_some(),
5620            "diff_decision should contain 'regime'"
5621        );
5622        assert_eq!(value["regime"], "sparse");
5623        assert_eq!(writer.diff_regime(), DiffRegime::Sparse);
5624    }
5625
5626    #[test]
5627    fn diff_regime_transition_emitted_once_per_change() {
5628        let evidence_path = temp_evidence_path("diff_regime_transition_emitted");
5629        let sink = EvidenceSink::from_config(
5630            &crate::evidence_sink::EvidenceSinkConfig::enabled_file(&evidence_path),
5631        )
5632        .expect("evidence sink config")
5633        .expect("evidence sink enabled");
5634
5635        let mut writer = TerminalWriter::with_diff_config(
5636            Vec::<u8>::new(),
5637            ScreenMode::AltScreen,
5638            UiAnchor::Bottom,
5639            basic_caps(),
5640            RuntimeDiffConfig::default(),
5641        )
5642        .with_evidence_sink(sink);
5643        writer.set_size(10, 10);
5644
5645        let mut buffer = Buffer::new(10, 10);
5646        // Baseline frame (initial redraw, populates prev_buffer)
5647        writer.present_ui(&buffer, None, false).unwrap();
5648
5649        // Three sparse presents
5650        buffer.set_raw(0, 0, Cell::from_char('1'));
5651        writer.present_ui(&buffer, None, false).unwrap();
5652        assert_eq!(writer.diff_regime(), DiffRegime::Sparse);
5653
5654        buffer.set_raw(0, 1, Cell::from_char('2'));
5655        writer.present_ui(&buffer, None, false).unwrap();
5656        assert_eq!(writer.diff_regime(), DiffRegime::Sparse);
5657
5658        buffer.set_raw(0, 2, Cell::from_char('3'));
5659        writer.present_ui(&buffer, None, false).unwrap();
5660        assert_eq!(writer.diff_regime(), DiffRegime::Sparse);
5661
5662        // One full redraw (all cells modified -> ratio >= 0.60 -> DiffRegime::Redraw)
5663        for y in 0..10 {
5664            for x in 0..10 {
5665                buffer.set_raw(x, y, Cell::from_char('X'));
5666            }
5667        }
5668        writer.present_ui(&buffer, None, false).unwrap();
5669        assert_eq!(writer.diff_regime(), DiffRegime::Redraw);
5670
5671        // Sparse present again
5672        buffer.set_raw(0, 0, Cell::from_char('Z'));
5673        writer.present_ui(&buffer, None, false).unwrap();
5674        assert_eq!(writer.diff_regime(), DiffRegime::Sparse);
5675
5676        let jsonl = std::fs::read_to_string(&evidence_path).expect("read evidence jsonl");
5677        let transition_lines: Vec<&str> = jsonl
5678            .lines()
5679            .filter(|line| line.contains("\"event\":\"diff_regime_transition\""))
5680            .collect();
5681
5682        assert_eq!(
5683            transition_lines.len(),
5684            2,
5685            "expected exactly two transition lines, got: {transition_lines:?}"
5686        );
5687
5688        let first: serde_json::Value =
5689            serde_json::from_str(transition_lines[0]).expect("valid json first transition");
5690        assert_eq!(first["event"], "diff_regime_transition");
5691        assert_eq!(first["from"], "sparse");
5692        assert_eq!(first["to"], "redraw");
5693        assert_eq!(first["frames_in_previous"], 3);
5694
5695        let second: serde_json::Value =
5696            serde_json::from_str(transition_lines[1]).expect("valid json second transition");
5697        assert_eq!(second["event"], "diff_regime_transition");
5698        assert_eq!(second["from"], "redraw");
5699        assert_eq!(second["to"], "sparse");
5700        assert_eq!(second["frames_in_previous"], 1);
5701    }
5702
5703    #[test]
5704    fn diff_strategy_posterior_updates_with_total_cells() {
5705        let mut output = Vec::new();
5706        let mut writer = TerminalWriter::with_diff_config(
5707            &mut output,
5708            ScreenMode::AltScreen,
5709            UiAnchor::Bottom,
5710            basic_caps(),
5711            RuntimeDiffConfig::default(),
5712        );
5713        writer.set_size(10, 10);
5714
5715        let mut buffer = Buffer::new(10, 10);
5716        buffer.set_raw(0, 0, Cell::from_char('A'));
5717        writer.present_ui(&buffer, None, false).unwrap();
5718
5719        let mut buffer2 = Buffer::new(10, 10);
5720        for x in 0..10u16 {
5721            buffer2.set_raw(x, 0, Cell::from_char('X'));
5722        }
5723        writer.present_ui(&buffer2, None, false).unwrap();
5724
5725        let config = writer.diff_strategy().config().clone();
5726        let total_cells = 10usize * 10usize;
5727        let changed = 10usize;
5728        let alpha = config.prior_alpha * config.decay + changed as f64;
5729        let beta = config.prior_beta * config.decay + (total_cells - changed) as f64;
5730        let expected = alpha / (alpha + beta);
5731        let mean = writer.diff_strategy().posterior_mean();
5732        assert!(
5733            (mean - expected).abs() < 1e-9,
5734            "posterior mean should use total_cells; got {mean:.6}, expected {expected:.6}"
5735        );
5736    }
5737
5738    #[test]
5739    fn log_write_without_scroll_region_preserves_diff_strategy() {
5740        // Overlay log writes never scroll the screen (single erased-and-
5741        // rewritten line, no unqualified LF), so the displayed UI baseline
5742        // stays valid and the diff strategy posterior must be PRESERVED —
5743        // the old reset-to-priors behavior compensated for log-induced
5744        // scrolling that no longer happens.
5745        let mut output = Vec::new();
5746        {
5747            let config = RuntimeDiffConfig::default();
5748            let mut writer = TerminalWriter::with_diff_config(
5749                &mut output,
5750                ScreenMode::Inline { ui_height: 5 },
5751                UiAnchor::Bottom,
5752                basic_caps(), // no scroll region support
5753                config,
5754            );
5755            writer.set_size(80, 24);
5756
5757            // Present a frame and observe some changes to modify posterior
5758            let mut buffer = Buffer::new(80, 5);
5759            buffer.set_raw(0, 0, Cell::from_char('X'));
5760            writer.present_ui(&buffer, None, false).unwrap();
5761
5762            // Present another frame
5763            buffer.set_raw(1, 1, Cell::from_char('Y'));
5764            writer.present_ui(&buffer, None, false).unwrap();
5765
5766            let (alpha_before, beta_before) = writer.diff_strategy().posterior_params();
5767
5768            // Log write without scroll region must not disturb diff state
5769            assert!(!writer.scroll_region_active());
5770            writer.write_log("log message\n").unwrap();
5771
5772            let (alpha_after, beta_after) = writer.diff_strategy().posterior_params();
5773            assert!(
5774                (alpha_after - alpha_before).abs() < 0.01
5775                    && (beta_after - beta_before).abs() < 0.01,
5776                "posterior should be preserved across overlay log write: \
5777                 before=({}, {}), after=({}, {})",
5778                alpha_before,
5779                beta_before,
5780                alpha_after,
5781                beta_after
5782            );
5783        }
5784    }
5785
5786    #[test]
5787    fn log_write_with_scroll_region_preserves_diff_strategy() {
5788        // When scroll region is active, log writes should NOT reset diff strategy
5789        let mut output = Vec::new();
5790        {
5791            let config = RuntimeDiffConfig::default();
5792            let mut writer = TerminalWriter::with_diff_config(
5793                &mut output,
5794                ScreenMode::Inline { ui_height: 5 },
5795                UiAnchor::Bottom,
5796                scroll_region_caps(), // has scroll region support
5797                config,
5798            );
5799            writer.set_size(80, 24);
5800
5801            // Present frames to activate scroll region and update posterior
5802            let mut buffer = Buffer::new(80, 5);
5803            buffer.set_raw(0, 0, Cell::from_char('X'));
5804            writer.present_ui(&buffer, None, false).unwrap();
5805
5806            buffer.set_raw(1, 1, Cell::from_char('Y'));
5807            writer.present_ui(&buffer, None, false).unwrap();
5808
5809            assert!(writer.scroll_region_active());
5810
5811            // Get posterior before log write
5812            let (alpha_before, beta_before) = writer.diff_strategy().posterior_params();
5813
5814            // Log write with scroll region active should NOT reset
5815            writer.write_log("log message\n").unwrap();
5816
5817            let (alpha_after, beta_after) = writer.diff_strategy().posterior_params();
5818            assert!(
5819                (alpha_after - alpha_before).abs() < 0.01
5820                    && (beta_after - beta_before).abs() < 0.01,
5821                "posterior should be preserved with scroll region: before=({}, {}), after=({}, {})",
5822                alpha_before,
5823                beta_before,
5824                alpha_after,
5825                beta_after
5826            );
5827        }
5828    }
5829
5830    // --- Overlay log discipline regressions (bd-th0p6 / bd-le0q8) ---
5831
5832    #[test]
5833    fn sgr_overlay_matches_plain_width_policy_for_unicode_and_controls() {
5834        for text in [
5835            "\x1b[31m界界界!",
5836            "\x1b[31me\u{301}\x1b[32mclair",
5837            "\x1b[31m\u{301}leading\tspace\nignored",
5838            "\x1b[4:3m👩\u{200d}💻 work\rignored",
5839            "\x1b[31m\t\nignored",
5840        ] {
5841            for width in 0..12 {
5842                let styled = sgr_overlay_log_line(text, width);
5843                assert_eq!(
5844                    sanitize(&styled),
5845                    sanitize_overlay_log_line(&sanitize(text), width),
5846                    "text={text:?}, width={width}"
5847                );
5848                assert_eq!(sanitize_with(&styled, SanitizeMode::SgrOnly), styled);
5849            }
5850        }
5851    }
5852
5853    #[test]
5854    fn log_modes_route_through_both_inline_strategies_and_anchors() {
5855        for mode in [
5856            SanitizeMode::Strip,
5857            SanitizeMode::SgrOnly,
5858            SanitizeMode::Raw,
5859        ] {
5860            for anchor in [UiAnchor::Top, UiAnchor::Bottom] {
5861                for scroll_region in [false, true] {
5862                    let caps = if scroll_region {
5863                        scroll_region_caps()
5864                    } else {
5865                        basic_caps()
5866                    };
5867                    let mut writer = TerminalWriter::new(
5868                        Vec::new(),
5869                        ScreenMode::Inline { ui_height: 2 },
5870                        anchor,
5871                        caps,
5872                    );
5873                    writer.set_size(10, 8);
5874                    if scroll_region {
5875                        writer.present_ui(&Buffer::new(10, 2), None, true).unwrap();
5876                        assert!(writer.scroll_region_active());
5877                    }
5878                    writer.flush().unwrap();
5879                    let start = writer.writer().inner().get_ref().len();
5880                    let payload = "\x1b[31mcolored\x1b[2J\nsecond";
5881                    match mode {
5882                        SanitizeMode::Strip => writer.write_log(payload),
5883                        SanitizeMode::SgrOnly => writer.write_log_sgr_only(payload),
5884                        SanitizeMode::Raw => writer.write_log_raw(payload),
5885                    }
5886                    .unwrap();
5887                    writer.flush().unwrap();
5888                    let output = &writer.writer().inner().get_ref()[start..];
5889                    let output = std::str::from_utf8(output).unwrap();
5890                    assert!(output.contains("colored"));
5891                    assert_eq!(output.contains("\x1b[31m"), mode != SanitizeMode::Strip);
5892                    assert_eq!(output.contains("\x1b[2J"), mode == SanitizeMode::Raw);
5893                    assert_eq!(
5894                        output.contains('\n'),
5895                        scroll_region || mode == SanitizeMode::Raw
5896                    );
5897                    assert_eq!(
5898                        output.contains("second"),
5899                        scroll_region || mode == SanitizeMode::Raw
5900                    );
5901                    let log_row = if anchor == UiAnchor::Top { 8 } else { 6 };
5902                    assert!(output.contains(&format!("\x1b[{log_row};1H")));
5903                    if mode == SanitizeMode::SgrOnly {
5904                        assert!(output.contains("colored\x1b[0m"));
5905                        if scroll_region {
5906                            assert!(output.contains("\x1b[0m\nsecond\x1b[0m"));
5907                        } else {
5908                            assert!(output.ends_with("\x1b[0m\x1b8"));
5909                        }
5910                    }
5911                }
5912            }
5913        }
5914    }
5915
5916    #[test]
5917    fn sgr_overlay_clamps_colored_payload_by_visible_columns() {
5918        let mut writer = TerminalWriter::new(
5919            Vec::new(),
5920            ScreenMode::Inline { ui_height: 5 },
5921            UiAnchor::Bottom,
5922            basic_caps(),
5923        );
5924        writer.set_size(80, 24);
5925        writer
5926            .write_log_sgr_only(&format!("\x1b[38:2::255:0:0m{}\nignored", "x".repeat(200)))
5927            .unwrap();
5928        let output = String::from_utf8(writer.into_inner().unwrap()).unwrap();
5929        assert_eq!(output.matches('x').count(), 80);
5930        assert!(output.contains("\x1b[38:2::255:0:0m"));
5931        assert!(!output.contains('\n'));
5932        assert!(!output.contains("ignored"));
5933        assert!(output.contains(&format!("{}\x1b[0m\x1b8", "x".repeat(80))));
5934    }
5935
5936    #[test]
5937    fn log_modes_remain_noops_without_a_log_region() {
5938        for screen_mode in [ScreenMode::AltScreen, ScreenMode::Inline { ui_height: 24 }] {
5939            for mode in [
5940                SanitizeMode::Strip,
5941                SanitizeMode::SgrOnly,
5942                SanitizeMode::Raw,
5943            ] {
5944                let mut writer =
5945                    TerminalWriter::new(Vec::new(), screen_mode, UiAnchor::Bottom, basic_caps());
5946                writer.set_size(80, 24);
5947                writer
5948                    .write_log_with_mode("\x1b[2J\x1b[31mhidden\n", mode)
5949                    .unwrap();
5950                writer.flush().unwrap();
5951                assert!(writer.writer().inner().get_ref().is_empty());
5952            }
5953        }
5954    }
5955
5956    #[test]
5957    fn annotated_logs_are_resanitized_even_for_public_variants() {
5958        let mut writer = TerminalWriter::new(
5959            Vec::new(),
5960            ScreenMode::Inline { ui_height: 5 },
5961            UiAnchor::Bottom,
5962            basic_caps(),
5963        );
5964        let payload = "\x1b[31mtext\x1b[2J";
5965        for text in [
5966            Text::Sanitized(std::borrow::Cow::Borrowed(payload)),
5967            Text::SgrOnly(std::borrow::Cow::Borrowed(payload)),
5968            Text::trusted(payload),
5969        ] {
5970            writer.flush().unwrap();
5971            let start = writer.writer().inner().get_ref().len();
5972            writer.write_log_text(&text).unwrap();
5973            writer.flush().unwrap();
5974            let output = std::str::from_utf8(&writer.writer().inner().get_ref()[start..]).unwrap();
5975            assert_eq!(
5976                output.contains("\x1b[31m"),
5977                text.mode() != SanitizeMode::Strip
5978            );
5979            assert_eq!(output.contains("\x1b[2J"), text.mode() == SanitizeMode::Raw);
5980        }
5981    }
5982
5983    #[test]
5984    fn sgr_logs_render_color_and_leave_following_output_unstyled() {
5985        use ftui_harness::terminal_model::{ModelStyle, Rgb, TerminalModel};
5986
5987        let mut writer = TerminalWriter::new(
5988            Vec::new(),
5989            ScreenMode::InlineAuto {
5990                min_height: 2,
5991                max_height: 4,
5992            },
5993            UiAnchor::Bottom,
5994            basic_caps(),
5995        );
5996        writer.set_size(20, 8);
5997        writer
5998            .write_log_sgr_only("\x1b[1;38;2;255;0;0mred\x1b[2J")
5999            .unwrap();
6000        writer.flush().unwrap();
6001        let mut terminal = TerminalModel::new(20, 8);
6002        terminal.feed(writer.writer().inner().get_ref());
6003        let row = writer.ui_start_row() - 1;
6004        assert!(terminal.row_text(row).starts_with("red"));
6005        assert_eq!(terminal.style_at(0, row).fg, Some(Rgb::new(255, 0, 0)));
6006        assert!(terminal.style_at(0, row).bold);
6007        // This model ignores DEC save/restore. Explicitly position subsequent
6008        // output: this checks SGR rendering/reset, not physical cursor restore.
6009        terminal.feed(b"\x1b[1;1Hplain");
6010        assert!(terminal.row_text(0).starts_with("plain"));
6011        assert_eq!(terminal.style_at(0, 0), ModelStyle::default());
6012    }
6013
6014    #[test]
6015    fn sgr_log_write_failure_keeps_reset_pending_and_reports_the_error() {
6016        let state = Rc::new(RefCell::new(FaultState::default()));
6017        let output = SingleWriteFaultWriter::new(Rc::clone(&state), usize::MAX, 10);
6018        let mut writer = TerminalWriter::new(
6019            output,
6020            ScreenMode::Inline { ui_height: 2 },
6021            UiAnchor::Bottom,
6022            scroll_region_caps(),
6023        );
6024        writer.set_size(80, 24);
6025        writer.present_ui(&Buffer::new(80, 2), None, true).unwrap();
6026        writer.flush().unwrap();
6027        assert!(writer.scroll_region_active());
6028        // Two short writes drain the cursor/reset prefix; the third writes
6029        // the red SGR and some text. Fail on the fourth, with styling active.
6030        let fail_on_call = state.borrow().write_calls + 4;
6031        writer.writer().inner_mut().get_mut().fail_on_call = fail_on_call;
6032        let error = writer
6033            .write_log_sgr_only(&format!("\x1b[31m{}", "x".repeat(100_000)))
6034            .unwrap_err();
6035        assert_eq!(error.kind(), io::ErrorKind::Other);
6036        assert!(state.borrow().injected_failure_triggered);
6037        assert!(contains_bytes(&state.borrow().bytes, b"\x1b[31mxxxxx"));
6038        writer.flush().unwrap();
6039        assert!(state.borrow().bytes.ends_with(SGR_RESET));
6040    }
6041
6042    /// CONTRACT: without a scroll region, write_log must never emit an
6043    /// unqualified LF (it would scroll the whole screen and displace the UI)
6044    /// and must erase the line before rewriting it so shorter lines cannot
6045    /// leave remnants of longer predecessors.
6046    #[test]
6047    fn overlay_write_log_emits_single_erased_line_no_lf() {
6048        let mut output = Vec::new();
6049        {
6050            let mut writer = TerminalWriter::new(
6051                &mut output,
6052                ScreenMode::Inline { ui_height: 5 },
6053                UiAnchor::Bottom,
6054                basic_caps(),
6055            );
6056            writer.set_size(80, 24);
6057            writer.write_log("first line\n").unwrap();
6058        }
6059
6060        assert!(
6061            !output.contains(&b'\n'),
6062            "overlay write_log must never emit a raw LF byte"
6063        );
6064        assert!(
6065            contains_bytes(&output, ERASE_LINE),
6066            "overlay write_log must erase the log row before writing"
6067        );
6068        assert!(
6069            contains_bytes(&output, b"first line"),
6070            "the (single-line) log payload must be emitted"
6071        );
6072    }
6073
6074    /// CONTRACT: multi-line payloads collapse to their first display line in
6075    /// overlay mode — subsequent lines must never scribble toward the UI.
6076    #[test]
6077    fn overlay_write_log_drops_lines_after_first() {
6078        let mut output = Vec::new();
6079        {
6080            let mut writer = TerminalWriter::new(
6081                &mut output,
6082                ScreenMode::Inline { ui_height: 5 },
6083                UiAnchor::Bottom,
6084                basic_caps(),
6085            );
6086            writer.set_size(80, 24);
6087            writer.write_log("only me\nhidden tail\n").unwrap();
6088        }
6089
6090        let text = String::from_utf8_lossy(&output);
6091        assert!(text.contains("only me"), "first line must be emitted");
6092        assert!(
6093            !text.contains("hidden tail"),
6094            "second line must be dropped in overlay mode"
6095        );
6096    }
6097
6098    /// CONTRACT (bd-th0p6 top-anchor): with a top-anchored UI and no scroll
6099    /// region, log writes park on the screen's bottom row but never emit LF,
6100    /// so nothing can push UI rows into scrollback.
6101    #[test]
6102    fn overlay_top_anchor_write_log_never_scrolls() {
6103        let mut output = Vec::new();
6104        {
6105            let mut writer = TerminalWriter::new(
6106                &mut output,
6107                ScreenMode::Inline { ui_height: 5 },
6108                UiAnchor::Top,
6109                basic_caps(),
6110            );
6111            writer.set_size(80, 24);
6112            writer.write_log("top anchored\n").unwrap();
6113        }
6114
6115        assert!(
6116            !output.contains(&b'\n'),
6117            "top-anchor overlay logs must not emit LF (screen-scroll hazard)"
6118        );
6119        assert!(
6120            contains_bytes(&output, b"\x1b[24;1H"),
6121            "log should target the screen's bottom row (below the UI)"
6122        );
6123        assert!(contains_bytes(&output, b"top anchored"));
6124    }
6125
6126    /// CONTRACT (bd-th0p6): log payloads are clamped to the terminal width so
6127    /// they cannot wrap into the first UI row.
6128    #[test]
6129    fn overlay_write_log_clamps_to_terminal_width() {
6130        let long_line = "x".repeat(100);
6131        let mut output = Vec::new();
6132        {
6133            let mut writer = TerminalWriter::new(
6134                &mut output,
6135                ScreenMode::Inline { ui_height: 5 },
6136                UiAnchor::Bottom,
6137                basic_caps(),
6138            );
6139            writer.set_size(80, 24);
6140            writer.write_log(&long_line).unwrap();
6141        }
6142
6143        let emitted_xs = output.iter().filter(|&&b| b == b'x').count();
6144        assert_eq!(
6145            emitted_xs, 80,
6146            "exactly term_width columns of the log line must be emitted"
6147        );
6148    }
6149
6150    /// never inside it — instead of using the pending effective height.
6151    #[test]
6152    fn inline_auto_shrink_positions_log_against_displayed_region() {
6153        let mut output = Vec::new();
6154        {
6155            let mut writer = TerminalWriter::new(
6156                &mut output,
6157                ScreenMode::InlineAuto {
6158                    min_height: 1,
6159                    max_height: 8,
6160                },
6161                UiAnchor::Bottom,
6162                basic_caps(),
6163            );
6164            writer.set_size(80, 24);
6165
6166            // Measure to the max: display an 8-row UI (rows 17-24,
6167            // region start 16, 0-indexed).
6168            writer.set_auto_ui_height(8);
6169            let buffer = Buffer::new(80, 8);
6170            writer.present_ui(&buffer, None, false).unwrap();
6171
6172            // Remeasure drops the pending effective height to min=1 while
6173            // rows 17-24 are still physically on screen.
6174            writer.clear_auto_ui_height();
6175
6176            // A Cmd::Log before the next present must land ABOVE row 17.
6177            writer.write_log("mid-flight\n").unwrap();
6178        }
6179
6180        // The overlay log write emits exactly SAVE + CUP + EL + payload, a
6181        // contiguous pattern no present path produces (presents emit more
6182        // bytes between SAVE and any CUP). Asserting on that whole pattern
6183        // scopes the check to the log write alone.
6184        assert!(
6185            contains_bytes(&output, b"\x1b7\x1b[16;1H\x1b[2K"),
6186            "log must anchor one row above the displayed region start"
6187        );
6188        for row in 17..=24 {
6189            assert!(
6190                !contains_bytes(&output, format!("\x1b7\x1b[{row};1H").as_bytes()),
6191                "log must not position inside displayed UI row {row}"
6192            );
6193        }
6194        assert!(contains_bytes(&output, b"mid-flight"));
6195    }
6196
6197    #[test]
6198    fn inline_auto_single_log_row_uses_overlay_until_more_space_is_presented() {
6199        for anchor in [UiAnchor::Top, UiAnchor::Bottom] {
6200            let mut writer = TerminalWriter::new(
6201                Vec::new(),
6202                ScreenMode::InlineAuto {
6203                    min_height: 1,
6204                    max_height: 5,
6205                },
6206                anchor,
6207                scroll_region_caps(),
6208            );
6209            writer.set_size(20, 5);
6210            // Establish a valid region first, then replace it with geometry
6211            // that has only one free log row.
6212            writer.present_ui(&Buffer::new(20, 1), None, false).unwrap();
6213            assert!(writer.scroll_region_active());
6214            writer.set_auto_ui_height(4);
6215            writer.present_ui(&Buffer::new(20, 4), None, false).unwrap();
6216            assert!(
6217                !writer.scroll_region_active(),
6218                "DECSTBM cannot describe a single row"
6219            );
6220            let before = writer.writer().inner().get_ref().len();
6221            writer
6222                .write_log_sgr_only("\x1b[31mfirst\nsecond\n")
6223                .unwrap();
6224            writer.flush().unwrap();
6225            let output = &writer.writer().inner().get_ref()[before..];
6226            assert!(contains_bytes(output, b"first"));
6227            assert!(!contains_bytes(output, b"second"));
6228            assert!(
6229                !output.contains(&b'\n'),
6230                "single-row log must not scroll the screen"
6231            );
6232            let row = if anchor == UiAnchor::Top { 5 } else { 1 };
6233            assert!(contains_bytes(output, format!("\x1b[{row};1H").as_bytes()));
6234
6235            writer.set_auto_ui_height(3);
6236            writer.present_ui(&Buffer::new(20, 3), None, false).unwrap();
6237            assert!(
6238                writer.scroll_region_active(),
6239                "two-row log area supports DECSTBM again"
6240            );
6241            let before = writer.writer().inner().get_ref().len();
6242            writer.write_log("first\nsecond\n").unwrap();
6243            writer.flush().unwrap();
6244            assert!(contains_bytes(
6245                &writer.writer().inner().get_ref()[before..],
6246                b"first\nsecond\n"
6247            ));
6248        }
6249    }
6250
6251    #[test]
6252    fn inline_auto_full_height_shrink_keeps_logs_out_until_present() {
6253        for caps in [basic_caps(), scroll_region_caps()] {
6254            for anchor in [UiAnchor::Top, UiAnchor::Bottom] {
6255                for clear_height in [false, true] {
6256                    for mode in [
6257                        SanitizeMode::Strip,
6258                        SanitizeMode::SgrOnly,
6259                        SanitizeMode::Raw,
6260                    ] {
6261                        let mut writer = TerminalWriter::new(
6262                            Vec::new(),
6263                            ScreenMode::InlineAuto {
6264                                min_height: 1,
6265                                max_height: 5,
6266                            },
6267                            anchor,
6268                            caps,
6269                        );
6270                        writer.set_size(20, 5);
6271                        writer.set_auto_ui_height(5);
6272                        writer.present_ui(&Buffer::new(20, 5), None, false).unwrap();
6273                        if clear_height {
6274                            writer.clear_auto_ui_height();
6275                        } else {
6276                            writer.set_auto_ui_height(1);
6277                        }
6278                        writer.flush().unwrap();
6279                        let before = writer.writer().inner().get_ref().len();
6280                        writer
6281                            .write_log_with_mode("\x1b[31mwaiting\n", mode)
6282                            .unwrap();
6283                        writer.flush().unwrap();
6284                        assert_eq!(
6285                            writer.writer().inner().get_ref().len(),
6286                            before,
6287                            "displayed UI still fills the screen: {anchor:?}, {mode:?}, clear={clear_height}"
6288                        );
6289
6290                        // Suppression ends when the smaller UI is actually
6291                        // displayed, for both scroll and overlay strategies.
6292                        writer.present_ui(&Buffer::new(20, 1), None, false).unwrap();
6293                        let before = writer.writer().inner().get_ref().len();
6294                        writer.write_log_with_mode("resumed", mode).unwrap();
6295                        writer.flush().unwrap();
6296                        assert!(contains_bytes(
6297                            &writer.writer().inner().get_ref()[before..],
6298                            b"resumed"
6299                        ));
6300                    }
6301                }
6302            }
6303        }
6304    }
6305
6306    /// CONTRACT: set_size invalidates the displayed-region cache — old
6307    /// geometry must not steer log positioning or shrink-erasure afterward.
6308    #[test]
6309    fn set_size_clears_last_inline_region() {
6310        let mut writer = TerminalWriter::new(
6311            Vec::new(),
6312            ScreenMode::Inline { ui_height: 5 },
6313            UiAnchor::Bottom,
6314            basic_caps(),
6315        );
6316        writer.set_size(80, 24);
6317        let buffer = Buffer::new(80, 5);
6318        writer.present_ui(&buffer, None, false).unwrap();
6319        assert!(writer.last_inline_region.is_some());
6320
6321        writer.set_size(80, 30);
6322        assert!(
6323            writer.last_inline_region.is_none(),
6324            "resize must invalidate the displayed-region cache"
6325        );
6326    }
6327    #[test]
6328    fn strategy_selection_config_flags_applied() {
6329        // Verify that RuntimeDiffConfig flags are correctly stored and accessible
6330        let config = RuntimeDiffConfig::default()
6331            .with_dirty_rows_enabled(false)
6332            .with_bayesian_enabled(false);
6333
6334        let writer = TerminalWriter::with_diff_config(
6335            Vec::<u8>::new(),
6336            ScreenMode::AltScreen,
6337            UiAnchor::Bottom,
6338            basic_caps(),
6339            config,
6340        );
6341
6342        // Config should be accessible
6343        assert!(!writer.diff_config().dirty_rows_enabled);
6344        assert!(!writer.diff_config().bayesian_enabled);
6345
6346        // Diff strategy should use the underlying strategy config
6347        let (alpha, beta) = writer.diff_strategy().posterior_params();
6348        // Default priors
6349        assert!((alpha - 1.0).abs() < 0.01);
6350        assert!((beta - 19.0).abs() < 0.01);
6351    }
6352
6353    #[test]
6354    fn resize_respects_reset_toggle() {
6355        // With reset_on_resize disabled, posterior should be preserved after resize
6356        let config = RuntimeDiffConfig::default().with_reset_on_resize(false);
6357
6358        let mut writer = TerminalWriter::with_diff_config(
6359            Vec::<u8>::new(),
6360            ScreenMode::AltScreen,
6361            UiAnchor::Bottom,
6362            basic_caps(),
6363            config,
6364        );
6365        writer.set_size(80, 24);
6366
6367        // Present frames to update posterior
6368        let mut buffer = Buffer::new(80, 24);
6369        buffer.set_raw(0, 0, Cell::from_char('X'));
6370        writer.present_ui(&buffer, None, false).unwrap();
6371
6372        let mut buffer2 = Buffer::new(80, 24);
6373        buffer2.set_raw(1, 1, Cell::from_char('Y'));
6374        writer.present_ui(&buffer2, None, false).unwrap();
6375
6376        // Posterior should have moved from initial priors
6377        let (alpha_before, beta_before) = writer.diff_strategy().posterior_params();
6378
6379        // Resize - with reset disabled, posterior should be preserved
6380        writer.set_size(100, 30);
6381
6382        let (alpha_after, beta_after) = writer.diff_strategy().posterior_params();
6383        assert!(
6384            (alpha_after - alpha_before).abs() < 0.01 && (beta_after - beta_before).abs() < 0.01,
6385            "posterior should be preserved when reset_on_resize=false"
6386        );
6387    }
6388
6389    // =========================================================================
6390    // Enum / Default / Debug tests
6391    // =========================================================================
6392
6393    #[test]
6394    fn screen_mode_default_is_altscreen() {
6395        assert_eq!(ScreenMode::default(), ScreenMode::AltScreen);
6396    }
6397
6398    #[test]
6399    fn screen_mode_debug_format() {
6400        let dbg = format!("{:?}", ScreenMode::Inline { ui_height: 7 });
6401        assert!(dbg.contains("Inline"));
6402        assert!(dbg.contains('7'));
6403    }
6404
6405    #[test]
6406    fn screen_mode_inline_auto_debug_format() {
6407        let dbg = format!(
6408            "{:?}",
6409            ScreenMode::InlineAuto {
6410                min_height: 3,
6411                max_height: 10
6412            }
6413        );
6414        assert!(dbg.contains("InlineAuto"));
6415    }
6416
6417    #[test]
6418    fn screen_mode_eq_inline_auto() {
6419        let a = ScreenMode::InlineAuto {
6420            min_height: 2,
6421            max_height: 8,
6422        };
6423        let b = ScreenMode::InlineAuto {
6424            min_height: 2,
6425            max_height: 8,
6426        };
6427        assert_eq!(a, b);
6428        let c = ScreenMode::InlineAuto {
6429            min_height: 2,
6430            max_height: 9,
6431        };
6432        assert_ne!(a, c);
6433    }
6434
6435    #[test]
6436    fn ui_anchor_default_is_bottom() {
6437        assert_eq!(UiAnchor::default(), UiAnchor::Bottom);
6438    }
6439
6440    #[test]
6441    fn ui_anchor_debug_format() {
6442        assert_eq!(format!("{:?}", UiAnchor::Top), "Top");
6443        assert_eq!(format!("{:?}", UiAnchor::Bottom), "Bottom");
6444    }
6445
6446    // =========================================================================
6447    // Accessor tests
6448    // =========================================================================
6449
6450    #[test]
6451    fn width_height_accessors() {
6452        let output = Vec::new();
6453        let mut writer = TerminalWriter::new(
6454            output,
6455            ScreenMode::AltScreen,
6456            UiAnchor::Bottom,
6457            basic_caps(),
6458        );
6459        // Default dimensions are 80x24
6460        assert_eq!(writer.width(), 80);
6461        assert_eq!(writer.height(), 24);
6462
6463        writer.set_size(120, 40);
6464        assert_eq!(writer.width(), 120);
6465        assert_eq!(writer.height(), 40);
6466    }
6467
6468    #[test]
6469    fn screen_mode_accessor() {
6470        let writer = TerminalWriter::new(
6471            Vec::new(),
6472            ScreenMode::Inline { ui_height: 5 },
6473            UiAnchor::Top,
6474            basic_caps(),
6475        );
6476        assert_eq!(writer.screen_mode(), ScreenMode::Inline { ui_height: 5 });
6477    }
6478
6479    #[test]
6480    fn capabilities_accessor() {
6481        let caps = full_caps();
6482        let writer = TerminalWriter::new(Vec::new(), ScreenMode::AltScreen, UiAnchor::Bottom, caps);
6483        assert!(writer.capabilities().supports_true_color());
6484        assert!(writer.capabilities().sync_output);
6485    }
6486
6487    // =========================================================================
6488    // into_inner tests
6489    // =========================================================================
6490
6491    #[test]
6492    fn into_inner_returns_writer() {
6493        let writer = TerminalWriter::new(
6494            Vec::new(),
6495            ScreenMode::AltScreen,
6496            UiAnchor::Bottom,
6497            basic_caps(),
6498        );
6499        let inner = writer.into_inner();
6500        assert!(inner.is_some());
6501    }
6502
6503    #[test]
6504    fn into_inner_performs_cleanup() {
6505        let mut writer = TerminalWriter::new(
6506            Vec::new(),
6507            ScreenMode::Inline { ui_height: 5 },
6508            UiAnchor::Bottom,
6509            basic_caps(),
6510        );
6511        writer.cursor_saved = true;
6512        writer.in_sync_block = false;
6513
6514        let inner = writer.into_inner().unwrap();
6515        // Cleanup should have written cursor restore
6516        assert!(
6517            inner
6518                .windows(CURSOR_RESTORE.len())
6519                .any(|w| w == CURSOR_RESTORE),
6520            "into_inner should perform cleanup before returning"
6521        );
6522    }
6523
6524    // =========================================================================
6525    // take_render_buffer tests
6526    // =========================================================================
6527
6528    #[test]
6529    fn take_render_buffer_creates_new_when_no_spare() {
6530        let mut writer = TerminalWriter::new(
6531            Vec::new(),
6532            ScreenMode::AltScreen,
6533            UiAnchor::Bottom,
6534            basic_caps(),
6535        );
6536        let buf = writer.take_render_buffer(80, 24);
6537        assert_eq!(buf.width(), 80);
6538        assert_eq!(buf.height(), 24);
6539    }
6540
6541    #[test]
6542    fn take_render_buffer_reuses_spare_on_match() {
6543        let mut writer = TerminalWriter::new(
6544            Vec::new(),
6545            ScreenMode::AltScreen,
6546            UiAnchor::Bottom,
6547            basic_caps(),
6548        );
6549        // Inject a spare buffer
6550        writer.spare_buffer = Some(Buffer::new(80, 24));
6551        assert!(writer.spare_buffer.is_some());
6552
6553        let buf = writer.take_render_buffer(80, 24);
6554        assert_eq!(buf.width(), 80);
6555        assert_eq!(buf.height(), 24);
6556        // Spare should have been taken
6557        assert!(writer.spare_buffer.is_none());
6558    }
6559
6560    #[test]
6561    fn take_render_buffer_ignores_spare_on_size_mismatch() {
6562        let mut writer = TerminalWriter::new(
6563            Vec::new(),
6564            ScreenMode::AltScreen,
6565            UiAnchor::Bottom,
6566            basic_caps(),
6567        );
6568        writer.spare_buffer = Some(Buffer::new(80, 24));
6569
6570        // Request different size - should create new, not reuse
6571        let buf = writer.take_render_buffer(100, 30);
6572        assert_eq!(buf.width(), 100);
6573        assert_eq!(buf.height(), 30);
6574    }
6575
6576    // =========================================================================
6577    // gc tests
6578    // =========================================================================
6579
6580    #[test]
6581    fn gc_with_no_prev_buffer() {
6582        let mut writer = TerminalWriter::new(
6583            Vec::new(),
6584            ScreenMode::AltScreen,
6585            UiAnchor::Bottom,
6586            basic_caps(),
6587        );
6588        assert!(writer.prev_buffer.is_none());
6589        // Should not panic
6590        writer.gc(None);
6591    }
6592
6593    #[test]
6594    fn gc_with_prev_buffer() {
6595        let mut writer = TerminalWriter::new(
6596            Vec::new(),
6597            ScreenMode::AltScreen,
6598            UiAnchor::Bottom,
6599            basic_caps(),
6600        );
6601        writer.prev_buffer = Some(Buffer::new(10, 5));
6602        // Should not panic
6603        writer.gc(None);
6604    }
6605
6606    // =========================================================================
6607    // hide_cursor / show_cursor tests
6608    // =========================================================================
6609
6610    #[test]
6611    fn hide_cursor_emits_sequence() {
6612        let mut output = Vec::new();
6613        {
6614            let mut writer = TerminalWriter::new(
6615                &mut output,
6616                ScreenMode::AltScreen,
6617                UiAnchor::Bottom,
6618                basic_caps(),
6619            );
6620            writer.hide_cursor().unwrap();
6621        }
6622        assert!(
6623            output.windows(6).any(|w| w == b"\x1b[?25l"),
6624            "hide_cursor should emit cursor hide sequence"
6625        );
6626    }
6627
6628    #[test]
6629    fn show_cursor_emits_sequence() {
6630        let mut output = Vec::new();
6631        {
6632            let mut writer = TerminalWriter::new(
6633                &mut output,
6634                ScreenMode::AltScreen,
6635                UiAnchor::Bottom,
6636                basic_caps(),
6637            );
6638            // First hide, then show
6639            writer.hide_cursor().unwrap();
6640            writer.show_cursor().unwrap();
6641        }
6642        assert!(
6643            output.windows(6).any(|w| w == b"\x1b[?25h"),
6644            "show_cursor should emit cursor show sequence"
6645        );
6646    }
6647
6648    #[test]
6649    fn hide_cursor_idempotent() {
6650        // Use Cursor<Vec<u8>> to own the writer
6651        use std::io::Cursor;
6652        let mut writer = TerminalWriter::new(
6653            Cursor::new(Vec::new()),
6654            ScreenMode::AltScreen,
6655            UiAnchor::Bottom,
6656            basic_caps(),
6657        );
6658        writer.hide_cursor().unwrap();
6659        let inner = writer.into_inner().unwrap().into_inner();
6660        let hide_count = inner.windows(6).filter(|w| *w == b"\x1b[?25l").count();
6661        // Should have exactly 1 hide (from hide_cursor) — Drop cleanup shows cursor (?25h)
6662        assert_eq!(
6663            hide_count, 1,
6664            "hide_cursor called once should emit exactly one hide sequence"
6665        );
6666    }
6667
6668    #[test]
6669    fn show_cursor_idempotent_when_already_visible() {
6670        use std::io::Cursor;
6671        let mut writer = TerminalWriter::new(
6672            Cursor::new(Vec::new()),
6673            ScreenMode::AltScreen,
6674            UiAnchor::Bottom,
6675            basic_caps(),
6676        );
6677        // Cursor starts visible — show should be noop
6678        writer.show_cursor().unwrap();
6679        let inner = writer.into_inner().unwrap().into_inner();
6680        // No ?25h should appear from show_cursor (only from cleanup)
6681        let show_count = inner.windows(6).filter(|w| *w == b"\x1b[?25h").count();
6682        assert!(
6683            show_count <= 1,
6684            "show_cursor when already visible should not add extra show sequences"
6685        );
6686    }
6687
6688    // =========================================================================
6689    // pool / links accessor tests
6690    // =========================================================================
6691
6692    #[test]
6693    fn pool_accessor() {
6694        let writer = TerminalWriter::new(
6695            Vec::new(),
6696            ScreenMode::AltScreen,
6697            UiAnchor::Bottom,
6698            basic_caps(),
6699        );
6700        // Pool should be accessible (just testing it doesn't panic)
6701        let _pool = writer.pool();
6702    }
6703
6704    #[test]
6705    fn pool_mut_accessor() {
6706        let mut writer = TerminalWriter::new(
6707            Vec::new(),
6708            ScreenMode::AltScreen,
6709            UiAnchor::Bottom,
6710            basic_caps(),
6711        );
6712        let _pool = writer.pool_mut();
6713    }
6714
6715    #[test]
6716    fn links_accessor() {
6717        let writer = TerminalWriter::new(
6718            Vec::new(),
6719            ScreenMode::AltScreen,
6720            UiAnchor::Bottom,
6721            basic_caps(),
6722        );
6723        let _links = writer.links();
6724    }
6725
6726    #[test]
6727    fn links_mut_accessor() {
6728        let mut writer = TerminalWriter::new(
6729            Vec::new(),
6730            ScreenMode::AltScreen,
6731            UiAnchor::Bottom,
6732            basic_caps(),
6733        );
6734        let _links = writer.links_mut();
6735    }
6736
6737    #[test]
6738    fn pool_and_links_mut_accessor() {
6739        let mut writer = TerminalWriter::new(
6740            Vec::new(),
6741            ScreenMode::AltScreen,
6742            UiAnchor::Bottom,
6743            basic_caps(),
6744        );
6745        let (_pool, _links) = writer.pool_and_links_mut();
6746    }
6747
6748    // =========================================================================
6749    // Helper function tests
6750    // =========================================================================
6751
6752    #[test]
6753    fn sanitize_auto_bounds_normal() {
6754        assert_eq!(sanitize_auto_bounds(3, 10), (3, 10));
6755    }
6756
6757    #[test]
6758    fn sanitize_auto_bounds_zero_min() {
6759        // min=0 should become 1
6760        assert_eq!(sanitize_auto_bounds(0, 10), (1, 10));
6761    }
6762
6763    #[test]
6764    fn sanitize_auto_bounds_max_less_than_min() {
6765        // max < min should be clamped to min
6766        assert_eq!(sanitize_auto_bounds(5, 3), (5, 5));
6767    }
6768
6769    #[test]
6770    fn sanitize_auto_bounds_both_zero() {
6771        assert_eq!(sanitize_auto_bounds(0, 0), (1, 1));
6772    }
6773
6774    #[test]
6775    fn diff_strategy_str_variants() {
6776        assert_eq!(diff_strategy_str(DiffStrategy::Full), "full");
6777        assert_eq!(diff_strategy_str(DiffStrategy::DirtyRows), "dirty");
6778        assert_eq!(diff_strategy_str(DiffStrategy::FullRedraw), "redraw");
6779    }
6780
6781    #[test]
6782    fn ui_anchor_str_variants() {
6783        assert_eq!(ui_anchor_str(UiAnchor::Bottom), "bottom");
6784        assert_eq!(ui_anchor_str(UiAnchor::Top), "top");
6785    }
6786
6787    #[test]
6788    fn json_escape_plain_text() {
6789        assert_eq!(json_escape("hello"), "hello");
6790    }
6791
6792    #[test]
6793    fn json_escape_special_chars() {
6794        assert_eq!(json_escape(r#"a"b"#), r#"a\"b"#);
6795        assert_eq!(json_escape("a\\b"), r#"a\\b"#);
6796        assert_eq!(json_escape("a\nb"), r#"a\nb"#);
6797        assert_eq!(json_escape("a\rb"), r#"a\rb"#);
6798        assert_eq!(json_escape("a\tb"), r#"a\tb"#);
6799    }
6800
6801    #[test]
6802    fn json_escape_control_chars() {
6803        let s = String::from("\x00\x01\x1f");
6804        let escaped = json_escape(&s);
6805        assert!(escaped.contains("\\u0000"));
6806        assert!(escaped.contains("\\u0001"));
6807        assert!(escaped.contains("\\u001F"));
6808    }
6809
6810    #[test]
6811    fn json_escape_unicode_passthrough() {
6812        assert_eq!(json_escape("caf\u{00e9}"), "caf\u{00e9}");
6813        assert_eq!(json_escape("\u{1f600}"), "\u{1f600}");
6814    }
6815
6816    // CountingWriter tests removed — the local CountingWriter was removed
6817    // in favour of ftui_render::counting_writer::CountingWriter (accessed via
6818    // Presenter). The render-crate CountingWriter has its own test suite.
6819
6820    #[test]
6821    fn counting_writer_into_inner() {
6822        let mut cw = CountingWriter::new(Vec::new());
6823        cw.write_all(b"data").unwrap();
6824        let inner = cw.into_inner();
6825        assert_eq!(inner, b"data");
6826    }
6827
6828    // =========================================================================
6829    // estimate_diff_scan_cost tests
6830    // =========================================================================
6831
6832    fn zero_span_stats() -> DirtySpanStats {
6833        DirtySpanStats {
6834            rows_full_dirty: 0,
6835            rows_with_spans: 0,
6836            total_spans: 0,
6837            overflows: 0,
6838            span_coverage_cells: 0,
6839            max_span_len: 0,
6840            max_spans_per_row: 4,
6841        }
6842    }
6843
6844    #[test]
6845    fn estimate_diff_scan_cost_full_strategy() {
6846        let stats = zero_span_stats();
6847        let (cost, label) = estimate_diff_scan_cost(DiffStrategy::Full, 0, 80, 24, &stats, None);
6848        assert_eq!(cost, 80 * 24);
6849        assert_eq!(label, "full_strategy");
6850    }
6851
6852    #[test]
6853    fn estimate_diff_scan_cost_full_redraw() {
6854        let stats = zero_span_stats();
6855        let (cost, label) =
6856            estimate_diff_scan_cost(DiffStrategy::FullRedraw, 5, 80, 24, &stats, None);
6857        assert_eq!(cost, 0);
6858        assert_eq!(label, "full_redraw");
6859    }
6860
6861    #[test]
6862    fn estimate_diff_scan_cost_dirty_rows_no_dirty() {
6863        let stats = zero_span_stats();
6864        let (cost, label) =
6865            estimate_diff_scan_cost(DiffStrategy::DirtyRows, 0, 80, 24, &stats, None);
6866        assert_eq!(cost, 0);
6867        assert_eq!(label, "no_dirty_rows");
6868    }
6869
6870    #[test]
6871    fn estimate_diff_scan_cost_dirty_rows_with_span_coverage() {
6872        let mut stats = zero_span_stats();
6873        stats.span_coverage_cells = 100;
6874        let (cost, label) =
6875            estimate_diff_scan_cost(DiffStrategy::DirtyRows, 5, 80, 24, &stats, None);
6876        assert_eq!(cost, 100);
6877        assert_eq!(label, "none");
6878    }
6879
6880    #[test]
6881    fn estimate_diff_scan_cost_dirty_rows_no_spans() {
6882        let stats = zero_span_stats();
6883        let (cost, label) =
6884            estimate_diff_scan_cost(DiffStrategy::DirtyRows, 5, 80, 24, &stats, None);
6885        assert_eq!(cost, 5 * 80);
6886        assert_eq!(label, "no_spans");
6887    }
6888
6889    #[test]
6890    fn estimate_diff_scan_cost_dirty_rows_overflow_with_span() {
6891        let mut stats = zero_span_stats();
6892        stats.span_coverage_cells = 150;
6893        stats.overflows = 1;
6894        let (cost, label) =
6895            estimate_diff_scan_cost(DiffStrategy::DirtyRows, 5, 80, 24, &stats, None);
6896        assert_eq!(cost, 150);
6897        assert_eq!(label, "span_overflow");
6898    }
6899
6900    #[test]
6901    fn estimate_diff_scan_cost_dirty_rows_overflow_no_span() {
6902        let mut stats = zero_span_stats();
6903        stats.overflows = 1;
6904        let (cost, label) =
6905            estimate_diff_scan_cost(DiffStrategy::DirtyRows, 5, 80, 24, &stats, None);
6906        assert_eq!(cost, 5 * 80);
6907        assert_eq!(label, "span_overflow");
6908    }
6909
6910    #[test]
6911    fn estimate_diff_scan_cost_tile_skip() {
6912        let stats = zero_span_stats();
6913        let tile = TileDiffStats {
6914            width: 80,
6915            height: 24,
6916            tile_w: 16,
6917            tile_h: 8,
6918            tiles_x: 5,
6919            tiles_y: 3,
6920            total_tiles: 15,
6921            dirty_cells: 10,
6922            dirty_tiles: 2,
6923            dirty_cell_ratio: 0.005,
6924            dirty_tile_ratio: 0.13,
6925            scanned_tiles: 2,
6926            skipped_tiles: 13,
6927            sat_build_cells: 1920,
6928            scan_cells_estimate: 42,
6929            skipped_tile_rows: 1,
6930            sat_queries: 3,
6931            fallback: None,
6932        };
6933        let (cost, label) =
6934            estimate_diff_scan_cost(DiffStrategy::DirtyRows, 5, 80, 24, &stats, Some(tile));
6935        assert_eq!(cost, 42);
6936        assert_eq!(label, "tile_skip");
6937    }
6938
6939    #[test]
6940    fn estimate_diff_scan_cost_tile_with_fallback_uses_spans() {
6941        let mut stats = zero_span_stats();
6942        stats.span_coverage_cells = 200;
6943        let tile = TileDiffStats {
6944            width: 80,
6945            height: 24,
6946            tile_w: 16,
6947            tile_h: 8,
6948            tiles_x: 5,
6949            tiles_y: 3,
6950            total_tiles: 15,
6951            dirty_cells: 10,
6952            dirty_tiles: 2,
6953            dirty_cell_ratio: 0.005,
6954            dirty_tile_ratio: 0.13,
6955            scanned_tiles: 2,
6956            skipped_tiles: 13,
6957            sat_build_cells: 1920,
6958            scan_cells_estimate: 42,
6959            skipped_tile_rows: 0,
6960            sat_queries: 0,
6961            fallback: Some(TileDiffFallback::SmallScreen),
6962        };
6963        let (cost, label) =
6964            estimate_diff_scan_cost(DiffStrategy::DirtyRows, 5, 80, 24, &stats, Some(tile));
6965        // Tile has fallback, so falls through to span logic
6966        assert_eq!(cost, 200);
6967        assert_eq!(label, "none");
6968    }
6969
6970    // =========================================================================
6971    // InlineAuto edge cases
6972    // =========================================================================
6973
6974    #[test]
6975    fn inline_auto_bounds_accessor() {
6976        let mut writer = TerminalWriter::new(
6977            Vec::new(),
6978            ScreenMode::InlineAuto {
6979                min_height: 3,
6980                max_height: 10,
6981            },
6982            UiAnchor::Bottom,
6983            basic_caps(),
6984        );
6985        writer.set_size(80, 24);
6986        let bounds = writer.inline_auto_bounds();
6987        assert_eq!(bounds, Some((3, 10)));
6988    }
6989
6990    #[test]
6991    fn inline_auto_bounds_clamped_to_terminal() {
6992        let mut writer = TerminalWriter::new(
6993            Vec::new(),
6994            ScreenMode::InlineAuto {
6995                min_height: 3,
6996                max_height: 50,
6997            },
6998            UiAnchor::Bottom,
6999            basic_caps(),
7000        );
7001        writer.set_size(80, 20);
7002        let bounds = writer.inline_auto_bounds();
7003        assert_eq!(bounds, Some((3, 20)));
7004    }
7005
7006    #[test]
7007    fn inline_auto_bounds_returns_none_for_non_auto() {
7008        let writer = TerminalWriter::new(
7009            Vec::new(),
7010            ScreenMode::Inline { ui_height: 5 },
7011            UiAnchor::Bottom,
7012            basic_caps(),
7013        );
7014        assert_eq!(writer.inline_auto_bounds(), None);
7015
7016        let writer2 = TerminalWriter::new(
7017            Vec::new(),
7018            ScreenMode::AltScreen,
7019            UiAnchor::Bottom,
7020            basic_caps(),
7021        );
7022        assert_eq!(writer2.inline_auto_bounds(), None);
7023    }
7024
7025    #[test]
7026    fn auto_ui_height_returns_none_for_non_auto() {
7027        let writer = TerminalWriter::new(
7028            Vec::new(),
7029            ScreenMode::Inline { ui_height: 5 },
7030            UiAnchor::Bottom,
7031            basic_caps(),
7032        );
7033        assert_eq!(writer.auto_ui_height(), None);
7034    }
7035
7036    #[test]
7037    fn render_height_hint_altscreen() {
7038        let mut writer = TerminalWriter::new(
7039            Vec::new(),
7040            ScreenMode::AltScreen,
7041            UiAnchor::Bottom,
7042            basic_caps(),
7043        );
7044        writer.set_size(80, 24);
7045        assert_eq!(writer.render_height_hint(), 24);
7046    }
7047
7048    #[test]
7049    fn render_height_hint_inline_fixed() {
7050        let mut writer = TerminalWriter::new(
7051            Vec::new(),
7052            ScreenMode::Inline { ui_height: 7 },
7053            UiAnchor::Bottom,
7054            basic_caps(),
7055        );
7056        assert_eq!(writer.render_height_hint(), 7);
7057        writer.set_size(80, 3);
7058        assert_eq!(writer.render_height_hint(), 3);
7059        writer.set_size(80, 24);
7060        assert_eq!(writer.render_height_hint(), 7);
7061        let mut oversized = TerminalWriter::new(
7062            Vec::new(),
7063            ScreenMode::Inline {
7064                ui_height: u16::MAX,
7065            },
7066            UiAnchor::Bottom,
7067            basic_caps(),
7068        );
7069        oversized.set_size(80, 24);
7070        assert_eq!(oversized.render_height_hint(), 24);
7071    }
7072
7073    // =========================================================================
7074    // RuntimeDiffConfig builder edge cases
7075    // =========================================================================
7076
7077    #[test]
7078    fn runtime_diff_config_tile_skip_toggle() {
7079        let config = RuntimeDiffConfig::new().with_tile_skip_enabled(false);
7080        assert!(!config.tile_diff_config.enabled);
7081    }
7082
7083    #[test]
7084    fn runtime_diff_config_dirty_spans_toggle() {
7085        let config = RuntimeDiffConfig::new().with_dirty_spans_enabled(false);
7086        assert!(!config.dirty_span_config.enabled);
7087    }
7088
7089    // =========================================================================
7090    // present_ui edge cases
7091    // =========================================================================
7092
7093    #[test]
7094    fn present_ui_altscreen_no_cursor_save_restore() {
7095        let mut output = Vec::new();
7096        {
7097            let mut writer = TerminalWriter::new(
7098                &mut output,
7099                ScreenMode::AltScreen,
7100                UiAnchor::Bottom,
7101                basic_caps(),
7102            );
7103            writer.set_size(10, 5);
7104            let buffer = Buffer::new(10, 5);
7105            writer.present_ui(&buffer, None, true).unwrap();
7106        }
7107
7108        // AltScreen should NOT use cursor save/restore (those are inline-mode specific)
7109        let save_count = output
7110            .windows(CURSOR_SAVE.len())
7111            .filter(|w| *w == CURSOR_SAVE)
7112            .count();
7113        assert_eq!(save_count, 0, "AltScreen should not save cursor");
7114    }
7115
7116    #[test]
7117    fn clear_screen_emits_ed2() {
7118        let mut output = Vec::new();
7119        {
7120            let mut writer = TerminalWriter::new(
7121                &mut output,
7122                ScreenMode::AltScreen,
7123                UiAnchor::Bottom,
7124                basic_caps(),
7125            );
7126            writer.clear_screen().unwrap();
7127        }
7128        assert!(
7129            output.windows(4).any(|w| w == b"\x1b[2J"),
7130            "clear_screen should emit ED2 sequence"
7131        );
7132    }
7133
7134    #[test]
7135    fn clear_screen_resets_active_scroll_region_before_clearing() {
7136        let mut output = Vec::new();
7137        {
7138            let mut writer = TerminalWriter::new(
7139                &mut output,
7140                ScreenMode::Inline { ui_height: 5 },
7141                UiAnchor::Bottom,
7142                scroll_region_caps(),
7143            );
7144            writer.set_size(80, 24);
7145
7146            let buffer = Buffer::new(80, 5);
7147            writer.present_ui(&buffer, None, true).unwrap();
7148            assert!(writer.scroll_region_active());
7149
7150            writer.clear_screen().unwrap();
7151            assert!(
7152                !writer.scroll_region_active(),
7153                "clear_screen should leave no active scroll region"
7154            );
7155        }
7156
7157        let reset_idx = output
7158            .windows(b"\x1b[r".len())
7159            .position(|w| w == b"\x1b[r")
7160            .expect("expected scroll-region reset");
7161        let clear_idx = output
7162            .windows(b"\x1b[2J".len())
7163            .position(|w| w == b"\x1b[2J")
7164            .expect("expected full clear");
7165        assert!(
7166            reset_idx < clear_idx,
7167            "clear_screen should reset DECSTBM before full-screen clear"
7168        );
7169    }
7170
7171    #[test]
7172    fn clear_screen_restores_saved_cursor_before_clearing() {
7173        let mut output = Vec::new();
7174        {
7175            let mut writer = TerminalWriter::new(
7176                &mut output,
7177                ScreenMode::Inline { ui_height: 5 },
7178                UiAnchor::Bottom,
7179                basic_caps(),
7180            );
7181            writer.cursor_saved = true;
7182
7183            writer.clear_screen().unwrap();
7184            assert!(
7185                !writer.cursor_saved,
7186                "clear_screen should clear stale saved-cursor state"
7187            );
7188        }
7189
7190        let restore_idx = output
7191            .windows(CURSOR_RESTORE.len())
7192            .position(|w| w == CURSOR_RESTORE)
7193            .expect("expected cursor restore");
7194        let clear_idx = output
7195            .windows(b"\x1b[2J".len())
7196            .position(|w| w == b"\x1b[2J")
7197            .expect("expected full clear");
7198        assert!(
7199            restore_idx < clear_idx,
7200            "clear_screen should restore any saved cursor before clearing"
7201        );
7202    }
7203
7204    #[test]
7205    fn clear_screen_closes_stale_sync_block_before_clearing() {
7206        let mut output = Vec::new();
7207        {
7208            let mut writer = TerminalWriter::new(
7209                &mut output,
7210                ScreenMode::Inline { ui_height: 5 },
7211                UiAnchor::Bottom,
7212                full_caps(),
7213            );
7214            writer.in_sync_block = true;
7215
7216            writer.clear_screen().unwrap();
7217            assert!(
7218                !writer.in_sync_block,
7219                "clear_screen should clear stale sync-block state"
7220            );
7221        }
7222
7223        let sync_end_idx = output
7224            .windows(SYNC_END.len())
7225            .position(|w| w == SYNC_END)
7226            .expect("expected sync end");
7227        let clear_idx = output
7228            .windows(b"\x1b[2J".len())
7229            .position(|w| w == b"\x1b[2J")
7230            .expect("expected full clear");
7231        assert!(
7232            sync_end_idx < clear_idx,
7233            "clear_screen should end any open sync block before clearing"
7234        );
7235    }
7236
7237    #[test]
7238    fn clear_screen_skips_sync_end_in_mux_while_clearing_stale_state() {
7239        let mut output = Vec::new();
7240        {
7241            let mut writer = TerminalWriter::new(
7242                &mut output,
7243                ScreenMode::Inline { ui_height: 5 },
7244                UiAnchor::Bottom,
7245                mux_caps(),
7246            );
7247            writer.in_sync_block = true;
7248
7249            writer.clear_screen().unwrap();
7250            assert!(
7251                !writer.in_sync_block,
7252                "clear_screen should clear stale sync state even when sync output is disabled"
7253            );
7254        }
7255
7256        assert!(
7257            !output.windows(SYNC_END.len()).any(|w| w == SYNC_END),
7258            "clear_screen must not emit sync_end in mux environments"
7259        );
7260        assert!(
7261            output.windows(b"\x1b[2J".len()).any(|w| w == b"\x1b[2J"),
7262            "clear_screen should still clear the screen"
7263        );
7264    }
7265
7266    #[test]
7267    fn clear_screen_invalidates_cached_state_even_when_flush_fails() {
7268        let state = Rc::new(RefCell::new(FaultState::default()));
7269        let writer_backend = SingleWriteFaultWriter::new(Rc::clone(&state), 1, 1);
7270        let mut writer = TerminalWriter::new(
7271            writer_backend,
7272            ScreenMode::Inline { ui_height: 5 },
7273            UiAnchor::Bottom,
7274            basic_caps(),
7275        );
7276        writer.cursor_saved = true;
7277        writer.prev_buffer = Some(Buffer::new(4, 2));
7278        writer.last_inline_region = Some(InlineRegion {
7279            start: 19,
7280            height: 5,
7281        });
7282        writer.last_diff_strategy = Some(DiffStrategy::DirtyRows);
7283
7284        let err = writer
7285            .clear_screen()
7286            .expect_err("expected injected flush write failure");
7287        assert_eq!(err.kind(), io::ErrorKind::Other);
7288        assert!(state.borrow().injected_failure_triggered);
7289        assert!(
7290            writer.prev_buffer.is_none(),
7291            "clear_screen should invalidate cached frame state after flush failure"
7292        );
7293        assert!(
7294            writer.last_inline_region.is_none(),
7295            "clear_screen should drop inline region cache after flush failure"
7296        );
7297        assert!(
7298            writer.last_diff_strategy.is_none(),
7299            "clear_screen should reset diff strategy after flush failure"
7300        );
7301    }
7302
7303    #[test]
7304    fn present_ui_retry_after_write_failure_forces_repaint() {
7305        let state = Rc::new(RefCell::new(FaultState::default()));
7306        let writer_backend = SingleWriteFaultWriter::new(Rc::clone(&state), 1, 1);
7307        let mut writer = TerminalWriter::new(
7308            writer_backend,
7309            ScreenMode::AltScreen,
7310            UiAnchor::Bottom,
7311            basic_caps(),
7312        );
7313        writer.set_size(4, 2);
7314
7315        let mut buffer = Buffer::new(4, 2);
7316        buffer.set_raw(0, 0, Cell::from_char('A'));
7317
7318        let err = writer
7319            .present_ui(&buffer, None, true)
7320            .expect_err("first present should hit the injected write fault");
7321        assert_eq!(err.kind(), io::ErrorKind::Other);
7322        assert!(
7323            writer.prev_buffer.is_none(),
7324            "failed present must not advance the diff baseline"
7325        );
7326
7327        writer
7328            .present_ui(&buffer, None, true)
7329            .expect("retry after transient failure should succeed");
7330
7331        let bytes = state.borrow().bytes.clone();
7332        assert!(
7333            bytes.contains(&b'A'),
7334            "retry should emit the missing cell content after a failed present"
7335        );
7336    }
7337
7338    #[test]
7339    fn present_ui_write_failure_with_existing_baseline_invalidates_diff_state() {
7340        let state = Rc::new(RefCell::new(FaultState::default()));
7341        let writer_backend = SingleWriteFaultWriter::new(Rc::clone(&state), 1, 1);
7342        let mut writer = TerminalWriter::new(
7343            writer_backend,
7344            ScreenMode::AltScreen,
7345            UiAnchor::Bottom,
7346            basic_caps(),
7347        );
7348        writer.set_size(4, 2);
7349
7350        let mut previous = Buffer::new(4, 2);
7351        previous.set_raw(0, 0, Cell::from_char('A'));
7352        writer.prev_buffer = Some(previous);
7353        writer.last_inline_region = Some(InlineRegion {
7354            start: 0,
7355            height: 2,
7356        });
7357        writer.last_diff_strategy = Some(DiffStrategy::DirtyRows);
7358        writer.frames_since_full_redraw = 7;
7359
7360        let mut buffer = Buffer::new(4, 2);
7361        buffer.set_raw(0, 0, Cell::from_char('B'));
7362
7363        let err = writer
7364            .present_ui(&buffer, None, true)
7365            .expect_err("present should hit the injected write fault");
7366        assert_eq!(err.kind(), io::ErrorKind::Other);
7367        assert!(
7368            writer.prev_buffer.is_none(),
7369            "failed present with a prior baseline must force the next frame to repaint"
7370        );
7371        assert!(
7372            writer.last_inline_region.is_none(),
7373            "failed present must drop inline-region assumptions"
7374        );
7375        assert_eq!(writer.last_diff_strategy(), None);
7376        assert_eq!(writer.frames_since_full_redraw, 0);
7377
7378        writer
7379            .present_ui(&buffer, None, true)
7380            .expect("retry after transient failure should succeed");
7381        assert_eq!(writer.last_diff_strategy(), Some(DiffStrategy::FullRedraw));
7382    }
7383
7384    #[test]
7385    fn set_size_resets_scroll_region_and_spare_buffer() {
7386        let output = Vec::new();
7387        let mut writer = TerminalWriter::new(
7388            output,
7389            ScreenMode::Inline { ui_height: 5 },
7390            UiAnchor::Bottom,
7391            basic_caps(),
7392        );
7393        writer.spare_buffer = Some(Buffer::new(80, 24));
7394        writer.set_size(100, 30);
7395        assert!(writer.spare_buffer.is_none());
7396    }
7397
7398    // =========================================================================
7399    // Inline active widgets gauge tests (bd-1q5.15)
7400    // =========================================================================
7401
7402    /// Mutex to serialize gauge tests against concurrent inline writer
7403    /// creation/destruction in other tests.
7404    static GAUGE_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
7405
7406    #[test]
7407    fn inline_active_widgets_gauge_increments_for_inline_mode() {
7408        let _lock = GAUGE_TEST_LOCK
7409            .lock()
7410            .unwrap_or_else(|err| err.into_inner());
7411
7412        // Other tests may create/drop inline writers concurrently.
7413        // Retry until we observe one uncontended +1/-1 transition.
7414        for _ in 0..64 {
7415            let before = inline_active_widgets();
7416            let writer = TerminalWriter::new(
7417                Vec::new(),
7418                ScreenMode::Inline { ui_height: 5 },
7419                UiAnchor::Bottom,
7420                basic_caps(),
7421            );
7422            let after_create = inline_active_widgets();
7423            drop(writer);
7424            let after_drop = inline_active_widgets();
7425
7426            if after_create == before.saturating_add(1) && after_drop == before {
7427                return;
7428            }
7429            std::thread::yield_now();
7430        }
7431
7432        panic!("failed to observe uncontended inline gauge +1/-1 transition");
7433    }
7434
7435    #[test]
7436    fn inline_active_widgets_gauge_increments_for_inline_auto_mode() {
7437        let _lock = GAUGE_TEST_LOCK
7438            .lock()
7439            .unwrap_or_else(|err| err.into_inner());
7440
7441        for _ in 0..64 {
7442            let before = inline_active_widgets();
7443            let writer = TerminalWriter::new(
7444                Vec::new(),
7445                ScreenMode::InlineAuto {
7446                    min_height: 2,
7447                    max_height: 10,
7448                },
7449                UiAnchor::Bottom,
7450                basic_caps(),
7451            );
7452            let after_create = inline_active_widgets();
7453            drop(writer);
7454            let after_drop = inline_active_widgets();
7455
7456            if after_create == before.saturating_add(1) && after_drop == before {
7457                return;
7458            }
7459            std::thread::yield_now();
7460        }
7461
7462        panic!("failed to observe uncontended inline-auto gauge +1/-1 transition");
7463    }
7464
7465    #[test]
7466    fn inline_active_widgets_gauge_unchanged_for_altscreen() {
7467        let _lock = GAUGE_TEST_LOCK
7468            .lock()
7469            .unwrap_or_else(|err| err.into_inner());
7470
7471        for _ in 0..64 {
7472            let before = inline_active_widgets();
7473            let writer = TerminalWriter::new(
7474                Vec::new(),
7475                ScreenMode::AltScreen,
7476                UiAnchor::Bottom,
7477                basic_caps(),
7478            );
7479            let after_create = inline_active_widgets();
7480            drop(writer);
7481            let after_drop = inline_active_widgets();
7482
7483            if after_create == before && after_drop == before {
7484                return;
7485            }
7486            std::thread::yield_now();
7487        }
7488
7489        panic!("failed to observe stable altscreen gauge behavior");
7490    }
7491
7492    // =========================================================================
7493    // Inline scrollback preservation tests (bd-1q5.16)
7494    // =========================================================================
7495
7496    /// CSI ?1049h — the alternate-screen enter sequence that must NEVER appear
7497    /// in inline mode output.
7498    const ALTSCREEN_ENTER: &[u8] = b"\x1b[?1049h";
7499
7500    /// CSI ?1049l — the alternate-screen exit sequence.
7501    const ALTSCREEN_EXIT: &[u8] = b"\x1b[?1049l";
7502
7503    /// Helper: returns true if `haystack` contains the byte subsequence `needle`.
7504    fn contains_bytes(haystack: &[u8], needle: &[u8]) -> bool {
7505        haystack.windows(needle.len()).any(|w| w == needle)
7506    }
7507
7508    #[test]
7509    fn inline_render_never_emits_altscreen_enter() {
7510        // The defining contract of inline mode: CSI ?1049h must not appear.
7511        let mut output = Vec::new();
7512        {
7513            let mut writer = TerminalWriter::new(
7514                &mut output,
7515                ScreenMode::Inline { ui_height: 5 },
7516                UiAnchor::Bottom,
7517                basic_caps(),
7518            );
7519            writer.set_size(80, 24);
7520
7521            let buffer = Buffer::new(80, 5);
7522            writer.present_ui(&buffer, None, true).unwrap();
7523            writer.write_log("hello\n").unwrap();
7524            // Second present to exercise diff path
7525            writer.present_ui(&buffer, None, true).unwrap();
7526        }
7527
7528        assert!(
7529            !contains_bytes(&output, ALTSCREEN_ENTER),
7530            "inline mode must never emit CSI ?1049h (alternate screen enter)"
7531        );
7532        assert!(
7533            !contains_bytes(&output, ALTSCREEN_EXIT),
7534            "inline mode must never emit CSI ?1049l (alternate screen exit)"
7535        );
7536    }
7537
7538    #[test]
7539    fn inline_auto_render_never_emits_altscreen_enter() {
7540        let mut output = Vec::new();
7541        {
7542            let mut writer = TerminalWriter::new(
7543                &mut output,
7544                ScreenMode::InlineAuto {
7545                    min_height: 3,
7546                    max_height: 10,
7547                },
7548                UiAnchor::Bottom,
7549                basic_caps(),
7550            );
7551            writer.set_size(80, 24);
7552
7553            let buffer = Buffer::new(80, 5);
7554            writer.present_ui(&buffer, None, true).unwrap();
7555        }
7556
7557        assert!(
7558            !contains_bytes(&output, ALTSCREEN_ENTER),
7559            "InlineAuto mode must never emit CSI ?1049h"
7560        );
7561    }
7562
7563    #[test]
7564    fn inline_scrollback_preserved_after_present() {
7565        // Scrollback preservation means log text written before present_ui
7566        // survives the UI render pass. We verify the output buffer contains
7567        // both the log text and cursor save/restore (the contract that
7568        // guarantees scrollback isn't disturbed).
7569        let mut output = Vec::new();
7570        {
7571            let mut writer = TerminalWriter::new(
7572                &mut output,
7573                ScreenMode::Inline { ui_height: 5 },
7574                UiAnchor::Bottom,
7575                basic_caps(),
7576            );
7577            writer.set_size(80, 24);
7578
7579            writer.write_log("scrollback line A\n").unwrap();
7580            writer.write_log("scrollback line B\n").unwrap();
7581
7582            let buffer = Buffer::new(80, 5);
7583            writer.present_ui(&buffer, None, true).unwrap();
7584
7585            // Another log after render should also work
7586            writer.write_log("scrollback line C\n").unwrap();
7587        }
7588
7589        let text = String::from_utf8_lossy(&output);
7590        assert!(text.contains("scrollback line A"), "first log must survive");
7591        assert!(
7592            text.contains("scrollback line B"),
7593            "second log must survive"
7594        );
7595        assert!(
7596            text.contains("scrollback line C"),
7597            "post-render log must survive"
7598        );
7599
7600        // Cursor save/restore must bracket the UI render to leave
7601        // scrollback position untouched.
7602        assert!(
7603            contains_bytes(&output, CURSOR_SAVE),
7604            "present_ui must save cursor to protect scrollback"
7605        );
7606        assert!(
7607            contains_bytes(&output, CURSOR_RESTORE),
7608            "present_ui must restore cursor to protect scrollback"
7609        );
7610    }
7611
7612    #[test]
7613    fn multiple_inline_writers_coexist() {
7614        // Two independent inline writers should each manage their own state
7615        // without interfering. Uses owned Vec writers so each can be
7616        // independently dropped and inspected.
7617        let mut writer_a = TerminalWriter::new(
7618            Vec::new(),
7619            ScreenMode::Inline { ui_height: 3 },
7620            UiAnchor::Bottom,
7621            basic_caps(),
7622        );
7623        writer_a.set_size(40, 12);
7624
7625        let mut writer_b = TerminalWriter::new(
7626            Vec::new(),
7627            ScreenMode::Inline { ui_height: 5 },
7628            UiAnchor::Bottom,
7629            basic_caps(),
7630        );
7631        writer_b.set_size(80, 24);
7632
7633        // Both can render independently without panicking
7634        let buf_a = Buffer::new(40, 3);
7635        let buf_b = Buffer::new(80, 5);
7636        writer_a.present_ui(&buf_a, None, true).unwrap();
7637        writer_b.present_ui(&buf_b, None, true).unwrap();
7638
7639        // Second render pass (diff path) also works
7640        writer_a.present_ui(&buf_a, None, true).unwrap();
7641        writer_b.present_ui(&buf_b, None, true).unwrap();
7642
7643        // Both drop cleanly (no panic, no double-free)
7644        drop(writer_a);
7645        drop(writer_b);
7646    }
7647
7648    #[test]
7649    fn multiple_inline_writers_gauge_tracks_both() {
7650        // Verify the gauge correctly tracks two simultaneous inline writers.
7651        let _lock = GAUGE_TEST_LOCK
7652            .lock()
7653            .unwrap_or_else(|err| err.into_inner());
7654
7655        for _ in 0..64 {
7656            let before = inline_active_widgets();
7657            let writer_a = TerminalWriter::new(
7658                Vec::new(),
7659                ScreenMode::Inline { ui_height: 3 },
7660                UiAnchor::Bottom,
7661                basic_caps(),
7662            );
7663            let after_a = inline_active_widgets();
7664
7665            let writer_b = TerminalWriter::new(
7666                Vec::new(),
7667                ScreenMode::Inline { ui_height: 5 },
7668                UiAnchor::Bottom,
7669                basic_caps(),
7670            );
7671            let after_b = inline_active_widgets();
7672
7673            drop(writer_a);
7674            let after_drop_a = inline_active_widgets();
7675
7676            drop(writer_b);
7677            let after_drop_b = inline_active_widgets();
7678
7679            if after_a == before.saturating_add(1)
7680                && after_b == before.saturating_add(2)
7681                && after_drop_a == before.saturating_add(1)
7682                && after_drop_b == before
7683            {
7684                return;
7685            }
7686            std::thread::yield_now();
7687        }
7688
7689        panic!("failed to observe uncontended two-writer gauge transitions");
7690    }
7691
7692    #[test]
7693    fn resize_during_inline_mode_preserves_scrollback() {
7694        // Resize should re-anchor the UI region without emitting
7695        // alternate screen sequences and should allow continued rendering.
7696        let mut output = Vec::new();
7697        {
7698            let mut writer = TerminalWriter::new(
7699                &mut output,
7700                ScreenMode::Inline { ui_height: 5 },
7701                UiAnchor::Bottom,
7702                basic_caps(),
7703            );
7704            writer.set_size(80, 24);
7705
7706            let buffer = Buffer::new(80, 5);
7707            writer.present_ui(&buffer, None, true).unwrap();
7708
7709            // Simulate resize
7710            writer.set_size(100, 30);
7711            assert_eq!(writer.ui_start_row(), 25); // 30 - 5
7712
7713            // Render again after resize
7714            let buffer2 = Buffer::new(100, 5);
7715            writer.present_ui(&buffer2, None, true).unwrap();
7716
7717            // Log still works after resize
7718            writer.write_log("post-resize log\n").unwrap();
7719        }
7720
7721        let text = String::from_utf8_lossy(&output);
7722        assert!(text.contains("post-resize log"));
7723        assert!(
7724            !contains_bytes(&output, ALTSCREEN_ENTER),
7725            "resize must not trigger alternate screen"
7726        );
7727    }
7728
7729    #[test]
7730    fn resize_shrink_during_inline_mode_clamps_correctly() {
7731        // Shrinking the terminal so UI region overlaps should still work
7732        // without alternate screen sequences.
7733        let mut output = Vec::new();
7734        {
7735            let mut writer = TerminalWriter::new(
7736                &mut output,
7737                ScreenMode::Inline { ui_height: 10 },
7738                UiAnchor::Bottom,
7739                basic_caps(),
7740            );
7741            writer.set_size(80, 24);
7742            assert_eq!(writer.ui_start_row(), 14);
7743
7744            // Shrink terminal to smaller than UI height
7745            writer.set_size(80, 8);
7746            assert_eq!(writer.ui_start_row(), 0); // 8 - 10 would underflow, clamped to 0
7747
7748            // Rendering should still work (height clamped to terminal)
7749            let buffer = Buffer::new(80, 8);
7750            writer.present_ui(&buffer, None, true).unwrap();
7751        }
7752
7753        assert!(
7754            !contains_bytes(&output, ALTSCREEN_ENTER),
7755            "shrunken terminal must not switch to altscreen"
7756        );
7757    }
7758
7759    #[test]
7760    fn inline_render_emits_tracing_span_fields() {
7761        // Verify the inline.render span is entered during present_ui in inline
7762        // mode by checking that the tracing infrastructure is invoked.
7763        // We use a tracing subscriber to capture span creation.
7764        use std::sync::Arc;
7765        use std::sync::atomic::AtomicBool;
7766
7767        struct SpanChecker {
7768            saw_inline_render: Arc<AtomicBool>,
7769        }
7770
7771        impl tracing::Subscriber for SpanChecker {
7772            fn enabled(&self, _metadata: &tracing::Metadata<'_>) -> bool {
7773                true
7774            }
7775            fn new_span(&self, span: &tracing::span::Attributes<'_>) -> tracing::span::Id {
7776                if span.metadata().name() == "inline.render" {
7777                    self.saw_inline_render
7778                        .store(true, std::sync::atomic::Ordering::SeqCst);
7779                }
7780                tracing::span::Id::from_u64(1)
7781            }
7782            fn record(&self, _span: &tracing::span::Id, _values: &tracing::span::Record<'_>) {}
7783            fn record_follows_from(&self, _span: &tracing::span::Id, _follows: &tracing::span::Id) {
7784            }
7785            fn event(&self, _event: &tracing::Event<'_>) {}
7786            fn enter(&self, _span: &tracing::span::Id) {}
7787            fn exit(&self, _span: &tracing::span::Id) {}
7788        }
7789
7790        let saw_it = Arc::new(AtomicBool::new(false));
7791
7792        // Span callsite interest caches are process-global while this
7793        // dispatcher is thread-local: a parallel test can race the
7794        // info_span!("inline.render") callsite into caching "not enabled"
7795        // even after a rebuild (bd-r2qx8). Retry with a fresh subscriber and
7796        // a fresh rebuild each round; a neighbor can only win the race
7797        // transiently, never persistently.
7798        for _ in 0..8 {
7799            saw_it.store(false, std::sync::atomic::Ordering::SeqCst);
7800            let subscriber = SpanChecker {
7801                saw_inline_render: Arc::clone(&saw_it),
7802            };
7803
7804            let _guard = tracing::subscriber::set_default(subscriber);
7805            tracing::callsite::rebuild_interest_cache();
7806
7807            let mut output = Vec::new();
7808            {
7809                let mut writer = TerminalWriter::new(
7810                    &mut output,
7811                    ScreenMode::Inline { ui_height: 5 },
7812                    UiAnchor::Bottom,
7813                    basic_caps(),
7814                );
7815                writer.set_size(80, 24);
7816
7817                let buffer = Buffer::new(80, 5);
7818                writer.present_ui(&buffer, None, true).unwrap();
7819            }
7820
7821            if saw_it.load(std::sync::atomic::Ordering::SeqCst) {
7822                return;
7823            }
7824        }
7825
7826        assert!(
7827            saw_it.load(std::sync::atomic::Ordering::SeqCst),
7828            "present_ui in inline mode must emit an inline.render tracing span"
7829        );
7830    }
7831
7832    #[test]
7833    fn inline_render_no_altscreen_with_scroll_region_strategy() {
7834        // Even with scroll region caps, inline mode must not emit altscreen.
7835        let mut output = Vec::new();
7836        {
7837            let mut writer = TerminalWriter::new(
7838                &mut output,
7839                ScreenMode::Inline { ui_height: 5 },
7840                UiAnchor::Bottom,
7841                scroll_region_caps(),
7842            );
7843            writer.set_size(80, 24);
7844
7845            let buffer = Buffer::new(80, 5);
7846            writer.present_ui(&buffer, None, true).unwrap();
7847            writer.present_ui(&buffer, None, true).unwrap();
7848        }
7849
7850        assert!(
7851            !contains_bytes(&output, ALTSCREEN_ENTER),
7852            "scroll region strategy must never emit altscreen enter"
7853        );
7854    }
7855
7856    #[test]
7857    fn inline_render_no_altscreen_with_hybrid_strategy() {
7858        let mut output = Vec::new();
7859        {
7860            let mut writer = TerminalWriter::new(
7861                &mut output,
7862                ScreenMode::Inline { ui_height: 5 },
7863                UiAnchor::Bottom,
7864                hybrid_caps(),
7865            );
7866            writer.set_size(80, 24);
7867
7868            let buffer = Buffer::new(80, 5);
7869            writer.present_ui(&buffer, None, true).unwrap();
7870        }
7871
7872        assert!(
7873            !contains_bytes(&output, ALTSCREEN_ENTER),
7874            "hybrid strategy must never emit altscreen enter"
7875        );
7876    }
7877
7878    #[test]
7879    fn inline_render_no_altscreen_with_mux_strategy() {
7880        let mut output = Vec::new();
7881        {
7882            let mut writer = TerminalWriter::new(
7883                &mut output,
7884                ScreenMode::Inline { ui_height: 5 },
7885                UiAnchor::Bottom,
7886                mux_caps(),
7887            );
7888            writer.set_size(80, 24);
7889
7890            let buffer = Buffer::new(80, 5);
7891            writer.present_ui(&buffer, None, true).unwrap();
7892        }
7893
7894        assert!(
7895            !contains_bytes(&output, ALTSCREEN_ENTER),
7896            "mux (overlay) strategy must never emit altscreen enter"
7897        );
7898    }
7899
7900    #[test]
7901    fn test_altscreen_wide_char_rendering() {
7902        use ftui_render::cell::Cell;
7903        let mut output = Vec::new();
7904        {
7905            let mut writer = TerminalWriter::new(
7906                &mut output,
7907                ScreenMode::AltScreen,
7908                UiAnchor::Bottom,
7909                basic_caps(),
7910            );
7911            writer.set_size(10, 5);
7912
7913            let mut buf = Buffer::new(10, 1);
7914            // Wide char at x=0 (width 2)
7915            buf.set_raw(0, 0, Cell::from_char('中'));
7916            // x=1 is implicitly CONTINUATION from Buffer::new init (or empty)
7917            // Wait, set_raw only sets one cell.
7918            // But Presenter logic depends on Buffer content.
7919            // For the test, we want to simulate the state where we have a wide char.
7920            // The proper way is to use `set` which handles continuations, or manually set them.
7921            buf.set(0, 0, Cell::from_char('中')); // This sets x=0 to '中', x=1 to CONTINUATION
7922
7923            // Force a diff by having a different previous buffer
7924            let prev = Buffer::new(10, 1);
7925            writer.prev_buffer = Some(prev);
7926
7927            writer.present_ui(&buf, None, true).unwrap();
7928        }
7929
7930        let output_str = String::from_utf8_lossy(&output);
7931
7932        // Should contain '中'
7933        assert!(output_str.contains('中'));
7934
7935        // Should NOT contain a space immediately after '中' (if it was treated as orphan)
7936        // Since '中' is e4 b8 ad (3 bytes).
7937        let bytes = output_str.as_bytes();
7938        let pos = bytes.windows(3).position(|w| w == "中".as_bytes());
7939        assert!(pos.is_some());
7940
7941        // Check byte after '中'
7942        let after = pos.unwrap() + 3;
7943        if after < bytes.len() {
7944            // It might be ANSI sequence or nothing. It should NOT be space (0x20).
7945            assert_ne!(
7946                bytes[after], 0x20,
7947                "Wide char continuation clobbered with space"
7948            );
7949        }
7950    }
7951
7952    // =========================================================================
7953    // NON-INTERFERENCE CONTRACT TESTS (bd-1bavy)
7954    //
7955    // These tests verify that terminal mode behavior and ownership semantics
7956    // are preserved under lifecycle changes. The Asupersync migration MUST
7957    // keep all these guarantees intact.
7958    // =========================================================================
7959
7960    /// CONTRACT: INLINE_ACTIVE_WIDGETS gauge increments on inline writer
7961    /// creation and decrements on drop. Net effect of create+drop is zero.
7962    /// Note: Tests use relative deltas because the global counter is shared.
7963    #[test]
7964    fn noninterference_inline_gauge_balanced_across_lifecycle() {
7965        let _lock = GAUGE_TEST_LOCK
7966            .lock()
7967            .unwrap_or_else(|err| err.into_inner());
7968
7969        for _ in 0..64 {
7970            let before = inline_active_widgets();
7971            let writer = TerminalWriter::new(
7972                Vec::new(),
7973                ScreenMode::Inline { ui_height: 3 },
7974                UiAnchor::Bottom,
7975                basic_caps(),
7976            );
7977            let during = inline_active_widgets();
7978            drop(writer);
7979            let after = inline_active_widgets();
7980
7981            if during == before.saturating_add(1) && after == before {
7982                return;
7983            }
7984            std::thread::yield_now();
7985        }
7986
7987        panic!("failed to observe stable inline lifecycle gauge transition");
7988    }
7989
7990    /// CONTRACT: AltScreen writers do NOT affect the inline gauge.
7991    /// Verified by checking the ScreenMode match in the Drop impl.
7992    /// (Note: the global atomic gauge is tested for inline modes in
7993    /// other tests; here we just verify the code path distinction.)
7994    #[test]
7995    fn noninterference_altscreen_does_not_affect_inline_gauge() {
7996        let _lock = GAUGE_TEST_LOCK
7997            .lock()
7998            .unwrap_or_else(|err| err.into_inner());
7999
8000        // The contract is verified structurally: ScreenMode::AltScreen does
8001        // not match the inline pattern in both the constructor (fetch_add)
8002        // and the Drop impl (fetch_sub). We verify this by checking that
8003        // creating and immediately dropping an AltScreen writer round-trips
8004        // without affecting the delta observed from a controlled inline writer.
8005        let mut observed_stable = false;
8006        for _ in 0..64 {
8007            let before = inline_active_widgets();
8008            drop(TerminalWriter::new(
8009                Vec::new(),
8010                ScreenMode::AltScreen,
8011                UiAnchor::Bottom,
8012                basic_caps(),
8013            ));
8014            let after = inline_active_widgets();
8015
8016            if after == before {
8017                observed_stable = true;
8018                break;
8019            }
8020            std::thread::yield_now();
8021        }
8022
8023        assert!(
8024            observed_stable,
8025            "failed to observe stable altscreen lifecycle gauge transition"
8026        );
8027
8028        // Also verify the structural contract directly:
8029        assert!(
8030            !matches!(
8031                ScreenMode::AltScreen,
8032                ScreenMode::Inline { .. } | ScreenMode::InlineAuto { .. }
8033            ),
8034            "AltScreen must not match inline patterns"
8035        );
8036    }
8037
8038    /// CONTRACT: InlineAuto also tracks the inline gauge correctly.
8039    #[test]
8040    fn noninterference_inline_auto_gauge_balanced() {
8041        let _lock = GAUGE_TEST_LOCK
8042            .lock()
8043            .unwrap_or_else(|err| err.into_inner());
8044
8045        for _ in 0..64 {
8046            let before = inline_active_widgets();
8047            let writer = TerminalWriter::new(
8048                Vec::new(),
8049                ScreenMode::InlineAuto {
8050                    min_height: 3,
8051                    max_height: 10,
8052                },
8053                UiAnchor::Bottom,
8054                basic_caps(),
8055            );
8056            let during = inline_active_widgets();
8057            drop(writer);
8058            let after = inline_active_widgets();
8059
8060            if during == before.saturating_add(1) && after == before {
8061                return;
8062            }
8063            std::thread::yield_now();
8064        }
8065
8066        panic!("failed to observe stable inline-auto lifecycle gauge transition");
8067    }
8068
8069    /// CONTRACT: into_inner() performs cleanup before releasing the writer.
8070    /// The returned output must contain cursor-show and flush.
8071    #[test]
8072    fn noninterference_into_inner_performs_cleanup() {
8073        let _lock = GAUGE_TEST_LOCK
8074            .lock()
8075            .unwrap_or_else(|err| err.into_inner());
8076
8077        let cursor_show = b"\x1b[?25h";
8078        for _ in 0..64 {
8079            let before_gauge = inline_active_widgets();
8080
8081            let mut writer = TerminalWriter::new(
8082                Vec::new(),
8083                ScreenMode::Inline { ui_height: 5 },
8084                UiAnchor::Bottom,
8085                basic_caps(),
8086            );
8087            writer.set_size(80, 24);
8088
8089            let during_gauge = inline_active_widgets();
8090            let output = writer.into_inner().expect("should return writer");
8091            let after_gauge = inline_active_widgets();
8092
8093            if during_gauge == before_gauge.saturating_add(1) && after_gauge == before_gauge {
8094                assert!(
8095                    output.windows(cursor_show.len()).any(|w| w == cursor_show),
8096                    "into_inner must emit cursor show during cleanup"
8097                );
8098                return;
8099            }
8100            std::thread::yield_now();
8101        }
8102
8103        panic!("failed to observe stable into_inner gauge transition");
8104    }
8105
8106    /// CONTRACT: Cleanup output from inline mode must contain cursor restore
8107    /// (DEC 8) if cursor was saved during present.
8108    #[test]
8109    fn noninterference_inline_cleanup_restores_cursor_after_present() {
8110        let mut output = Vec::new();
8111        {
8112            let mut writer = TerminalWriter::new(
8113                &mut output,
8114                ScreenMode::Inline { ui_height: 5 },
8115                UiAnchor::Bottom,
8116                basic_caps(),
8117            );
8118            writer.set_size(80, 24);
8119
8120            let buffer = Buffer::new(80, 5);
8121            writer.present_ui(&buffer, None, true).unwrap();
8122
8123            // Writer will be dropped here, triggering cleanup
8124        }
8125
8126        // Count cursor save/restore pairs
8127        let saves = output
8128            .windows(CURSOR_SAVE.len())
8129            .filter(|w| *w == CURSOR_SAVE)
8130            .count();
8131        let restores = output
8132            .windows(CURSOR_RESTORE.len())
8133            .filter(|w| *w == CURSOR_RESTORE)
8134            .count();
8135
8136        assert!(saves > 0, "present must save cursor");
8137        assert!(
8138            restores >= saves,
8139            "cleanup must ensure all cursor saves are restored: {saves} saves, {restores} restores"
8140        );
8141    }
8142
8143    /// CONTRACT: AltScreen cleanup must show cursor. It must NOT emit
8144    /// cursor restore or scroll region reset (those are inline-only).
8145    #[test]
8146    fn noninterference_altscreen_cleanup_minimal() {
8147        let mut output = Vec::new();
8148        {
8149            let mut writer = TerminalWriter::new(
8150                &mut output,
8151                ScreenMode::AltScreen,
8152                UiAnchor::Bottom,
8153                basic_caps(),
8154            );
8155            writer.set_size(80, 24);
8156
8157            let mut buffer = Buffer::new(80, 24);
8158            buffer.set_raw(0, 0, Cell::from_char('A'));
8159            writer.present_ui(&buffer, None, true).unwrap();
8160        }
8161
8162        // Must contain cursor show
8163        let cursor_show = b"\x1b[?25h";
8164        assert!(
8165            output.windows(cursor_show.len()).any(|w| w == cursor_show),
8166            "AltScreen cleanup must show cursor"
8167        );
8168
8169        // Must NOT contain scroll region reset (inline-only)
8170        // (scroll region was never activated for AltScreen)
8171        // This is verified by the scroll_region_active flag being false
8172    }
8173
8174    /// CONTRACT: Rapid present/log interleaving in inline mode must not
8175    /// corrupt the output stream. Each present must be complete and each
8176    /// log must be sanitized.
8177    #[test]
8178    fn noninterference_rapid_present_log_interleave() {
8179        let mut output = Vec::new();
8180        {
8181            let mut writer = TerminalWriter::new(
8182                &mut output,
8183                ScreenMode::Inline { ui_height: 3 },
8184                UiAnchor::Bottom,
8185                basic_caps(),
8186            );
8187            writer.set_size(40, 12);
8188
8189            for i in 0..10 {
8190                let mut buffer = Buffer::new(40, 3);
8191                buffer.set_raw(0, 0, Cell::from_char(char::from(b'A' + (i % 26))));
8192                writer.present_ui(&buffer, None, true).unwrap();
8193                writer.write_log(&format!("log-{i}")).unwrap();
8194            }
8195        }
8196
8197        // Output must contain cursor show (cleanup ran)
8198        let cursor_show = b"\x1b[?25h";
8199        assert!(
8200            output.windows(cursor_show.len()).any(|w| w == cursor_show),
8201            "cleanup must complete after rapid interleaving"
8202        );
8203
8204        // Output must not contain unmatched escape sequences
8205        // (simple check: no bare ESC at end without terminator)
8206        let output_len = output.len();
8207        if output_len > 1 {
8208            let last_esc = output.iter().rposition(|&b| b == 0x1b);
8209            if let Some(pos) = last_esc {
8210                // If the last ESC is within 10 bytes of the end, verify it's a complete sequence
8211                if output_len - pos < 10 {
8212                    // Should be part of cursor show or similar short sequence
8213                    assert!(
8214                        output_len - pos >= 3,
8215                        "truncated escape sequence at end of output"
8216                    );
8217                }
8218            }
8219        }
8220    }
8221
8222    /// CONTRACT: Resize between presents must not leave stale diff state.
8223    /// The first present after resize must produce valid output.
8224    #[test]
8225    fn noninterference_resize_between_presents_clears_diff_state() {
8226        let mut output = Vec::new();
8227        {
8228            let mut writer = TerminalWriter::new(
8229                &mut output,
8230                ScreenMode::Inline { ui_height: 5 },
8231                UiAnchor::Bottom,
8232                basic_caps(),
8233            );
8234            writer.set_size(80, 24);
8235
8236            // First present at 80x5
8237            let buffer1 = Buffer::new(80, 5);
8238            writer.present_ui(&buffer1, None, true).unwrap();
8239
8240            // Resize
8241            writer.set_size(120, 30);
8242            assert!(
8243                writer.prev_buffer.is_none(),
8244                "set_size must clear prev_buffer to invalidate diff"
8245            );
8246
8247            // Second present at 120x5 — must not panic or produce corrupt output
8248            let buffer2 = Buffer::new(120, 5);
8249            writer.present_ui(&buffer2, None, true).unwrap();
8250        }
8251
8252        // If we got here without panic, the resize was handled correctly
8253        let cursor_show = b"\x1b[?25h";
8254        assert!(
8255            output.windows(cursor_show.len()).any(|w| w == cursor_show),
8256            "output must be valid after resize"
8257        );
8258    }
8259
8260    /// CONTRACT: Multiple writers can be created sequentially on the same
8261    /// output without interference. Each writer's cleanup must be complete
8262    /// before the next writer starts.
8263    #[test]
8264    fn noninterference_sequential_writers_clean_handoff() {
8265        let mut output = Vec::new();
8266
8267        // First writer: Inline mode
8268        {
8269            let mut writer = TerminalWriter::new(
8270                &mut output,
8271                ScreenMode::Inline { ui_height: 3 },
8272                UiAnchor::Bottom,
8273                basic_caps(),
8274            );
8275            writer.set_size(40, 12);
8276            let buffer = Buffer::new(40, 3);
8277            writer.present_ui(&buffer, None, true).unwrap();
8278            // Dropped: cleanup runs
8279        }
8280
8281        let inline_end = output.len();
8282
8283        // Second writer: AltScreen mode on same output
8284        {
8285            let mut writer = TerminalWriter::new(
8286                &mut output,
8287                ScreenMode::AltScreen,
8288                UiAnchor::Bottom,
8289                basic_caps(),
8290            );
8291            writer.set_size(40, 12);
8292            let mut buffer = Buffer::new(40, 12);
8293            buffer.set_raw(0, 0, Cell::from_char('Z'));
8294            writer.present_ui(&buffer, None, true).unwrap();
8295            // Dropped: cleanup runs
8296        }
8297
8298        // Both cleanups must have produced cursor show
8299        let cursor_show = b"\x1b[?25h";
8300        let first_show = output[..inline_end]
8301            .windows(cursor_show.len())
8302            .any(|w| w == cursor_show);
8303        let second_show = output[inline_end..]
8304            .windows(cursor_show.len())
8305            .any(|w| w == cursor_show);
8306
8307        assert!(first_show, "first writer must show cursor on cleanup");
8308        assert!(second_show, "second writer must show cursor on cleanup");
8309    }
8310
8311    /// CONTRACT: present_ui_owned must produce identical output to present_ui
8312    /// for the same buffer content. The only difference should be performance.
8313    #[test]
8314    fn noninterference_present_ui_owned_matches_present_ui() {
8315        let mut output_borrowed = Vec::new();
8316        let mut output_owned = Vec::new();
8317
8318        let mut buffer = Buffer::new(20, 5);
8319        buffer.set_raw(0, 0, Cell::from_char('H'));
8320        buffer.set_raw(1, 0, Cell::from_char('i'));
8321
8322        // Borrowed path
8323        {
8324            let mut writer = TerminalWriter::new(
8325                &mut output_borrowed,
8326                ScreenMode::Inline { ui_height: 5 },
8327                UiAnchor::Bottom,
8328                basic_caps(),
8329            );
8330            writer.set_size(20, 10);
8331            writer.present_ui(&buffer, None, true).unwrap();
8332        }
8333
8334        // Owned path
8335        {
8336            let mut writer = TerminalWriter::new(
8337                &mut output_owned,
8338                ScreenMode::Inline { ui_height: 5 },
8339                UiAnchor::Bottom,
8340                basic_caps(),
8341            );
8342            writer.set_size(20, 10);
8343            writer.present_ui_owned(buffer, None, true).unwrap();
8344        }
8345
8346        // Both must contain cursor save/restore
8347        assert!(
8348            output_borrowed
8349                .windows(CURSOR_SAVE.len())
8350                .any(|w| w == CURSOR_SAVE),
8351            "borrowed path must save cursor"
8352        );
8353        assert!(
8354            output_owned
8355                .windows(CURSOR_SAVE.len())
8356                .any(|w| w == CURSOR_SAVE),
8357            "owned path must save cursor"
8358        );
8359
8360        // Both must contain the 'H' character
8361        assert!(
8362            output_borrowed.windows(1).any(|w| w == b"H"),
8363            "borrowed path must render content"
8364        );
8365        assert!(
8366            output_owned.windows(1).any(|w| w == b"H"),
8367            "owned path must render content"
8368        );
8369    }
8370
8371    /// CONTRACT: write_log is a no-op in AltScreen mode but works in inline.
8372    /// This behavioral difference must be preserved.
8373    #[test]
8374    fn noninterference_write_log_mode_behavior_preserved() {
8375        // Inline: write_log produces output
8376        let mut inline_output = Vec::new();
8377        {
8378            let mut writer = TerminalWriter::new(
8379                &mut inline_output,
8380                ScreenMode::Inline { ui_height: 3 },
8381                UiAnchor::Bottom,
8382                basic_caps(),
8383            );
8384            writer.set_size(40, 12);
8385            writer.write_log("hello").unwrap();
8386        }
8387        assert!(
8388            inline_output.windows(5).any(|w| w == b"hello"),
8389            "inline write_log must produce output"
8390        );
8391
8392        // AltScreen: write_log is silent
8393        let mut alt_output = Vec::new();
8394        {
8395            let mut writer = TerminalWriter::new(
8396                &mut alt_output,
8397                ScreenMode::AltScreen,
8398                UiAnchor::Bottom,
8399                basic_caps(),
8400            );
8401            writer.set_size(40, 12);
8402            writer.write_log("hello").unwrap();
8403        }
8404        // The output should not contain "hello" text from write_log
8405        // (it will contain cleanup sequences)
8406        let has_hello = alt_output.windows(5).any(|w| w == b"hello");
8407        assert!(!has_hello, "AltScreen write_log must be silent (no-op)");
8408    }
8409
8410    /// CONTRACT: Sync output sequences are balanced (begin/end) across
8411    /// multiple present calls. An open sync block must never leak.
8412    #[test]
8413    fn noninterference_sync_output_balanced_across_multiple_presents() {
8414        let mut output = Vec::new();
8415        {
8416            let mut writer = TerminalWriter::new(
8417                &mut output,
8418                ScreenMode::Inline { ui_height: 3 },
8419                UiAnchor::Bottom,
8420                full_caps(),
8421            );
8422            writer.set_size(20, 10);
8423
8424            for _ in 0..5 {
8425                let buffer = Buffer::new(20, 3);
8426                writer.present_ui(&buffer, None, true).unwrap();
8427            }
8428            // Writer drop triggers cleanup
8429        }
8430
8431        let begins = output
8432            .windows(SYNC_BEGIN.len())
8433            .filter(|w| *w == SYNC_BEGIN)
8434            .count();
8435        let ends = output
8436            .windows(SYNC_END.len())
8437            .filter(|w| *w == SYNC_END)
8438            .count();
8439
8440        assert!(begins > 0, "sync-capable writer must emit SYNC_BEGIN");
8441        assert_eq!(
8442            begins, ends,
8443            "sync blocks must be balanced: {begins} begins, {ends} ends"
8444        );
8445    }
8446
8447    /// CONTRACT: InlineAuto effective_ui_height is clamped to terminal height.
8448    /// A writer with max_height > terminal height must clamp without panic.
8449    #[test]
8450    fn noninterference_inline_auto_height_clamped_without_panic() {
8451        let mut output = Vec::new();
8452        {
8453            let mut writer = TerminalWriter::new(
8454                &mut output,
8455                ScreenMode::InlineAuto {
8456                    min_height: 3,
8457                    max_height: 100,
8458                },
8459                UiAnchor::Bottom,
8460                basic_caps(),
8461            );
8462            // Terminal is only 10 rows tall
8463            writer.set_size(80, 10);
8464
8465            // effective_ui_height for InlineAuto clamps to term_height
8466            let effective = writer.effective_ui_height();
8467            assert!(
8468                effective <= 10,
8469                "InlineAuto effective_ui_height must clamp to terminal height, got {effective}"
8470            );
8471
8472            let buffer = Buffer::new(80, effective);
8473            writer.present_ui(&buffer, None, true).unwrap();
8474        }
8475    }
8476
8477    /// CONTRACT: Inline mode with ui_height > terminal height must not panic
8478    /// during present. The rendering path handles this gracefully.
8479    #[test]
8480    fn noninterference_inline_oversized_height_no_panic() {
8481        let mut output = Vec::new();
8482        {
8483            let mut writer = TerminalWriter::new(
8484                &mut output,
8485                ScreenMode::Inline { ui_height: 100 },
8486                UiAnchor::Bottom,
8487                basic_caps(),
8488            );
8489            writer.set_size(80, 10);
8490
8491            // Inline effective_ui_height returns raw value without clamping
8492            // but the rendering path must handle this without panic
8493            let buffer = Buffer::new(80, 10);
8494            // This should not panic even though ui_height > term_height
8495            let result = writer.present_ui(&buffer, None, true);
8496            assert!(
8497                result.is_ok(),
8498                "present_ui must not panic with oversized ui_height"
8499            );
8500        }
8501    }
8502
8503    // ── Render-certificate integration (bd-6b9nr) ───────────────────────────
8504
8505    fn present_sequence(certified: bool) -> (Vec<u8>, Vec<String>) {
8506        let config = RuntimeDiffConfig {
8507            certified_skips: certified,
8508            // Deterministic strategy behavior for the byte-equality comparison.
8509            bayesian_enabled: false,
8510            ..RuntimeDiffConfig::default()
8511        };
8512        let mut writer = TerminalWriter::with_diff_config(
8513            Vec::new(),
8514            ScreenMode::Inline { ui_height: 4 },
8515            UiAnchor::Bottom,
8516            full_caps(),
8517            config,
8518        );
8519        writer.set_size(24, 12);
8520
8521        let mut certificates = Vec::new();
8522        for frame in 0..4u16 {
8523            let mut buffer = Buffer::new(24, 4);
8524            if frame > 0 {
8525                buffer.clear_dirty();
8526            }
8527            match frame {
8528                // Frame 0: initial paint (all rows dirty by construction).
8529                0 => {}
8530                // Frame 1: identical content — zero dirty rows.
8531                1 => {}
8532                // Frame 2: sparse update on two rows.
8533                2 => {
8534                    buffer.set(3, 1, ftui_render::cell::Cell::from_char('X'));
8535                    buffer.set(9, 3, ftui_render::cell::Cell::from_char('Y'));
8536                }
8537                // Frame 3: another sparse update.
8538                _ => {
8539                    buffer.set(3, 1, ftui_render::cell::Cell::from_char('Z'));
8540                }
8541            }
8542            writer
8543                .present_ui_owned(buffer, None, false)
8544                .expect("present");
8545            certificates.push(
8546                writer
8547                    .last_render_certificate()
8548                    .map(|c| format!("{}:{:?}", c.level.label(), c.causes.clone()))
8549                    .unwrap_or_else(|| "none".to_string()),
8550            );
8551        }
8552        (writer.into_inner().expect("writer sink"), certificates)
8553    }
8554
8555    #[test]
8556    fn certified_path_is_byte_identical_to_legacy_dirty_path() {
8557        let (certified_bytes, _) = present_sequence(true);
8558        let (legacy_bytes, _) = present_sequence(false);
8559        assert_eq!(
8560            certified_bytes, legacy_bytes,
8561            "certified diff path changed visible output"
8562        );
8563    }
8564
8565    #[test]
8566    fn zero_dirty_frame_earns_a_skip_all_certificate() {
8567        let (_, certificates) = present_sequence(true);
8568        // Frame 1 re-presents identical content with zero dirty rows.
8569        assert!(
8570            certificates[1].starts_with("skip-all"),
8571            "frame 1 certificate was {}",
8572            certificates[1]
8573        );
8574        // Sparse frames narrow to their dirty rows.
8575        assert!(
8576            certificates[2].starts_with("narrow-to-dirty"),
8577            "frame 2 certificate was {}",
8578            certificates[2]
8579        );
8580    }
8581
8582    #[test]
8583    fn certificates_name_full_work_causes() {
8584        let (_, certificates) = present_sequence(true);
8585        // Frame 0 has no previous buffer: full redraw with a named cause.
8586        assert!(
8587            certificates[0].contains("no-previous-frame"),
8588            "frame 0 certificate was {}",
8589            certificates[0]
8590        );
8591    }
8592
8593    #[test]
8594    fn legacy_path_records_no_certificate() {
8595        let (_, certificates) = present_sequence(false);
8596        // The dirty-rows frames record None when certified skips are off
8597        // (frame 0/resize paths still certify full work explicitly).
8598        assert_eq!(certificates[2], "none");
8599        assert_eq!(certificates[3], "none");
8600    }
8601}