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