tui2: stop baking streaming wraps; reflow agent markdown (#8761)

Background
Streaming assistant prose in tui2 was being rendered with viewport-width
wrapping during streaming, then stored in history cells as already split
`Line`s. Those width-derived breaks became indistinguishable from hard
newlines, so the transcript could not "un-split" on resize. This also
degraded copy/paste, since soft wraps looked like hard breaks.

What changed
- Introduce width-agnostic `MarkdownLogicalLine` output in
`tui2/src/markdown_render.rs`, preserving markdown wrap semantics:
initial/subsequent indents, per-line style, and a preformatted flag.
- Update the streaming collector (`tui2/src/markdown_stream.rs`) to emit
logical lines (newline-gated) and remove any captured viewport width.
- Update streaming orchestration (`tui2/src/streaming/*`) to queue and
emit logical lines, producing `AgentMessageCell::new_logical(...)`.
- Make `AgentMessageCell` store logical lines and wrap at render time in
`HistoryCell::transcript_lines_with_joiners(width)`, emitting joiners so
copy/paste can join soft-wrap continuations correctly.

Overlay deferral
When an overlay is active, defer *cells* (not rendered `Vec<Line>`) and
render them at overlay close time. This avoids baking width-derived
wraps based on a stale width.

Tests + docs
- Add resize/reflow regression tests + snapshots for streamed agent
output.
- Expand module/API docs for the new logical-line streaming pipeline and
clarify joiner semantics.
- Align scrollback-related docs/comments with current tui2 behavior
(main draw loop does not flush queued "history lines" to the terminal).

More details
See `codex-rs/tui2/docs/streaming_wrapping_design.md` for the full
problem statement and solution approach, and
`codex-rs/tui2/docs/tui_viewport_and_history.md` for viewport vs printed
output behavior.
This commit is contained in:
Josh McKinney
2026-01-05 18:37:58 -08:00
committed by GitHub
parent 771f1ca6ab
commit c92dbea7c1
13 changed files with 868 additions and 325 deletions
+46 -13
View File
@@ -1,6 +1,25 @@
//! Orchestrates streaming assistant output into immutable transcript cells.
//!
//! The UI receives assistant output as a sequence of deltas. TUI2 wants to:
//!
//! - render incrementally during streaming,
//! - keep the transcript model append-only (emit immutable history cells),
//! - avoid duplicating content or showing partial final lines, and
//! - preserve resize reflow by not baking width-derived wraps into stored cells.
//!
//! [`StreamController`] glues together:
//!
//! - newline-gated delta accumulation (`MarkdownStreamCollector`),
//! - commit-tick animation (`StreamState` queue), and
//! - history cell emission (`AgentMessageCell::new_logical`).
//!
//! Each emitted cell contains **logical markdown lines** plus wrap metadata. The cell wraps those
//! lines at render time using the current viewport width and returns soft-wrap joiners for
//! copy/paste fidelity.
use crate::history_cell::HistoryCell;
use crate::history_cell::{self};
use ratatui::text::Line;
use crate::markdown_render::MarkdownLogicalLine;
use super::StreamState;
@@ -13,15 +32,19 @@ pub(crate) struct StreamController {
}
impl StreamController {
pub(crate) fn new(width: Option<usize>) -> Self {
/// Create a new controller for one assistant message stream.
pub(crate) fn new() -> Self {
Self {
state: StreamState::new(width),
state: StreamState::new(),
finishing_after_drain: false,
header_emitted: false,
}
}
/// Push a delta; if it contains a newline, commit completed lines and start animation.
/// Push a streaming delta and enqueue newly completed logical lines.
///
/// Returns `true` when at least one logical line was committed and should trigger commit-tick
/// animation.
pub(crate) fn push(&mut self, delta: &str) -> bool {
let state = &mut self.state;
if !delta.is_empty() {
@@ -38,7 +61,10 @@ impl StreamController {
false
}
/// Finalize the active stream. Drain and emit now.
/// Finalize the active stream and emit any remaining logical lines.
///
/// This forces the final "partial" line to be committed (if present) and resets the controller
/// so it is ready for the next stream.
pub(crate) fn finalize(&mut self) -> Option<Box<dyn HistoryCell>> {
// Finalize collector first.
let remaining = {
@@ -62,21 +88,28 @@ impl StreamController {
self.emit(out_lines)
}
/// Step animation: commit at most one queued line and handle end-of-drain cleanup.
/// Advance the commit-tick animation by at most one logical line.
///
/// Returns `(cell, idle)` where:
/// - `cell` is a new immutable history cell to append to the transcript (if any output is ready)
/// - `idle` is `true` once the queue is fully drained.
pub(crate) fn on_commit_tick(&mut self) -> (Option<Box<dyn HistoryCell>>, bool) {
let step = self.state.step();
(self.emit(step), self.state.is_idle())
}
fn emit(&mut self, lines: Vec<Line<'static>>) -> Option<Box<dyn HistoryCell>> {
fn emit(&mut self, lines: Vec<MarkdownLogicalLine>) -> Option<Box<dyn HistoryCell>> {
if lines.is_empty() {
return None;
}
Some(Box::new(history_cell::AgentMessageCell::new(lines, {
let header_emitted = self.header_emitted;
self.header_emitted = true;
!header_emitted
})))
Some(Box::new(history_cell::AgentMessageCell::new_logical(
lines,
{
let header_emitted = self.header_emitted;
self.header_emitted = true;
!header_emitted
},
)))
}
}
@@ -99,7 +132,7 @@ mod tests {
#[tokio::test]
async fn controller_loose_vs_tight_with_commit_ticks_matches_full() {
let mut ctrl = StreamController::new(None);
let mut ctrl = StreamController::new();
let mut lines = Vec::new();
// Exact deltas from the session log (section: Loose vs. tight list items)
+28 -8
View File
@@ -1,39 +1,59 @@
//! Streaming state for newline-gated assistant output.
//!
//! The streaming pipeline in `tui2` is split into:
//!
//! - [`crate::markdown_stream::MarkdownStreamCollector`]: accumulates raw deltas and commits
//! completed *logical* markdown lines (width-agnostic).
//! - [`StreamState`]: a small queue that supports "commit tick" animation by releasing at most one
//! logical line per tick.
//! - [`controller::StreamController`]: orchestration (header emission, finalize/drain semantics,
//! and converting queued logical lines into `HistoryCell`s).
//!
//! Keeping the queued units as logical lines (not wrapped visual lines) is essential for resize
//! reflow: visual wrapping depends on the current viewport width and must be performed at render
//! time inside the relevant history cell.
use std::collections::VecDeque;
use ratatui::text::Line;
use crate::markdown_render::MarkdownLogicalLine;
use crate::markdown_stream::MarkdownStreamCollector;
pub(crate) mod controller;
pub(crate) struct StreamState {
pub(crate) collector: MarkdownStreamCollector,
queued_lines: VecDeque<Line<'static>>,
queued_lines: VecDeque<MarkdownLogicalLine>,
pub(crate) has_seen_delta: bool,
}
impl StreamState {
pub(crate) fn new(width: Option<usize>) -> Self {
/// Create a fresh streaming state for one assistant message.
pub(crate) fn new() -> Self {
Self {
collector: MarkdownStreamCollector::new(width),
collector: MarkdownStreamCollector::new(),
queued_lines: VecDeque::new(),
has_seen_delta: false,
}
}
/// Reset state for the next stream.
pub(crate) fn clear(&mut self) {
self.collector.clear();
self.queued_lines.clear();
self.has_seen_delta = false;
}
pub(crate) fn step(&mut self) -> Vec<Line<'static>> {
/// Pop at most one queued logical line (for commit-tick animation).
pub(crate) fn step(&mut self) -> Vec<MarkdownLogicalLine> {
self.queued_lines.pop_front().into_iter().collect()
}
pub(crate) fn drain_all(&mut self) -> Vec<Line<'static>> {
/// Drain all queued logical lines (used on finalize).
pub(crate) fn drain_all(&mut self) -> Vec<MarkdownLogicalLine> {
self.queued_lines.drain(..).collect()
}
/// True when there is no queued output waiting to be emitted by commit ticks.
pub(crate) fn is_idle(&self) -> bool {
self.queued_lines.is_empty()
}
pub(crate) fn enqueue(&mut self, lines: Vec<Line<'static>>) {
/// Enqueue newly committed logical lines.
pub(crate) fn enqueue(&mut self, lines: Vec<MarkdownLogicalLine>) {
self.queued_lines.extend(lines);
}
}