Preview streaming prose before a newline arrives in the TUI (#45135)

## Why

Unterminated prose stayed hidden until a newline arrived or the stream completed, leaving long single-line responses invisible while they streamed.

## What changed

- Show live prose previews for agent messages and proposed plans, requesting redraws when the preview changes.
- Keep previews out of the scrollback queue and render the full source on newline or completion without duplicating text.
- Bound previews to the most recent 8 KiB at a Unicode character boundary, with an ellipsis for omitted text, and reflow them when the width changes.
- Preserve holdback for incomplete table and code structures, retaining the last safe prose preview when a pipe arrives.

## Testing

Add controller tests and TUI snapshots covering visibility before completion, resize reflow, finalization without duplication, long Unicode previews, table and code holdback, and inline visualization context.

GitOrigin-RevId: 26c83c218b986625820b20779a46d1b800a7e0ff
This commit is contained in:
Eric Traut authored and copyberry committed 2026-09-12 23:54:20 +00:00
1 parent b979d4f1f0
commit b966240bea
13 files changed
+386 -53

No files matched your search

+41 -18
View File
@@ -31,7 +31,8 @@
//!
//! - `emitted_stable_len <= enqueued_stable_len <= render.lines.len()`.
//! - committed source is append-only until `reset()`; never modified mid-stream.
//! - Tail starts exactly at `enqueued_stable_len`.
//! - The committed-source tail starts at `enqueued_stable_len`; a bounded prose preview may
//! follow it without affecting any stable line counts.
//! - During confirmed table streaming, only lines from the table header onward
//! are forced into tail; pre-table lines may remain stable.
@@ -51,6 +52,7 @@ use std::time::Duration;
use std::time::Instant;
use super::StreamState;
use super::prose_preview::ProsePreview;
use super::render::StreamingRender;
use super::render::render_source;
use super::table_holdback::TableHoldbackScanner;
@@ -77,6 +79,8 @@ struct StreamCore {
width: Option<usize>,
/// Incremental render of committed source at `width`.
render: StreamingRender,
/// Disposable partial prose, never counted in the stable render or queue.
preview: ProsePreview,
/// Lines enqueued into the commit-animation queue.
enqueued_stable_len: usize,
/// Lines actually emitted to scrollback.
@@ -114,6 +118,7 @@ impl StreamCore {
state: StreamState::new(width, cwd),
width,
render: StreamingRender::new(),
preview: ProsePreview::default(),
enqueued_stable_len: 0,
emitted_stable_len: 0,
cwd: cwd.to_path_buf(),
@@ -124,19 +129,23 @@ impl StreamCore {
}
}
/// Push a streaming delta and enqueue any newly-stable rendered lines.
/// Push a delta and report whether the queue or prose preview changed.
///
/// Only newline-terminated source is committed for rendering. This is
/// Only newline-terminated source is committed to the stable render. This is
/// important for tables because an unterminated partial row must stay out
/// of both the stable queue and the live tail until its structure is
/// unambiguous; otherwise the user can briefly see malformed columns that
/// immediately disappear on the next delta.
/// immediately disappear on the next delta. Unterminated prose gets a separate,
/// bounded preview that never advances the stable boundary.
fn push_delta(&mut self, delta: &str) -> bool {
if !delta.is_empty() {
self.state.has_seen_delta = true;
}
self.state.collector.push_delta(delta);
if delta.contains('\n') {
self.preview = ProsePreview::default();
}
let mut enqueued = false;
if delta.contains('\n')
&& let Some(range) = self.state.collector.commit_complete_source()
@@ -154,7 +163,23 @@ impl StreamCore {
);
enqueued = self.sync_stable_queue();
}
enqueued
let preview_changed = self.refresh_preview();
enqueued || preview_changed
}
fn refresh_preview(&mut self) -> bool {
if self.holdback_scanner.allows_prose_preview() {
self.preview.update(
self.state.collector.pending_source(),
self.width,
&self.cwd,
self.render_mode,
self.inline_visualization_context.as_ref(),
)
} else {
self.preview = ProsePreview::default();
false
}
}
/// Drain the collector, render the final source snapshot, and return lines not yet emitted.
@@ -225,9 +250,12 @@ impl StreamCore {
#[inline]
fn current_tail_lines(&self) -> Vec<HyperlinkLine> {
let start = self.enqueued_stable_len.min(self.render.lines.len());
self.render.lines[start..].to_vec()
let mut lines = self.render.lines[start..].to_vec();
lines.extend(self.preview.lines.iter().cloned());
lines
}
/// Whether committed Markdown needs tail reflow. Disposable prose previews do not.
#[inline]
fn has_tail(&self) -> bool {
self.enqueued_stable_len < self.render.lines.len()
@@ -250,6 +278,7 @@ impl StreamCore {
let had_live_tail = self.has_tail();
self.width = width;
self.state.collector.set_width(width);
self.refresh_preview();
let source = self.state.collector.committed_source();
if source.is_empty() {
return;
@@ -287,6 +316,7 @@ impl StreamCore {
fn reset(&mut self) {
self.state.clear();
self.render.clear();
self.preview = ProsePreview::default();
self.enqueued_stable_len = 0;
self.emitted_stable_len = 0;
self.stable_prefix_len_cache = None;
@@ -301,6 +331,7 @@ impl StreamCore {
let had_pending_queue = self.state.queued_len() > 0;
let had_live_tail = self.has_tail();
self.render_mode = render_mode;
self.refresh_preview();
let source = self.state.collector.committed_source();
if source.is_empty() {
return;
@@ -756,6 +787,10 @@ impl PlanStreamController {
}
}
#[cfg(test)]
#[path = "controller_preview_tests.rs"]
mod preview_tests;
#[cfg(test)]
mod tests {
use super::*;
@@ -955,18 +990,6 @@ mod tests {
);
}
#[test]
fn controller_live_tail_requires_table_holdback_state() {
let mut ctrl = stream_controller(Some(80));
ctrl.push("plain text without newline");
assert!(
ctrl.current_tail_lines().is_empty(),
"expected no live tail outside table holdback state",
);
assert!(!ctrl.has_live_tail());
}
#[test]
fn controller_live_tail_rerenders_table_tail_after_resize() {
let mut ctrl = stream_controller(Some(96));
@@ -0,0 +1,137 @@
use super::*;
use crate::terminal_hyperlinks::visible_lines;
use pretty_assertions::assert_eq;
#[test]
fn unterminated_prose_reflows_and_finishes_without_duplication() {
let cwd = std::env::temp_dir();
for ending in ["", "\n"] {
let mut controller = StreamController::new(Some(32), &cwd, HistoryRenderMode::Rich);
let mut source = String::from("`numbers` ");
controller.push(&source);
for number in 100..200 {
let delta = format!("{number} ");
source.push_str(&delta);
controller.push(&delta);
assert_eq!(controller.queued_lines(), 0);
assert_eq!(
controller.current_tail_lines(),
render_source(
&source,
Some(32),
&cwd,
HistoryRenderMode::Rich,
/*inline_visualization_context*/ None
),
);
}
controller.push(" | pending structure");
controller.set_width(Some(48));
assert_eq!(controller.queued_lines(), 0);
assert_eq!(
controller.current_tail_lines(),
render_source(
&source,
Some(48),
&cwd,
HistoryRenderMode::Rich,
/*inline_visualization_context*/ None
),
);
source.push_str(" | pending structure");
controller.push(ending);
let (queued, _) = controller.on_commit_tick_batch(usize::MAX);
let (remaining, finalized_source) = controller.finalize();
let displayed = queued
.into_iter()
.chain(remaining)
.flat_map(|cell| cell.display_lines(/*width*/ 50))
.collect::<Vec<_>>();
let expected = history_cell::AgentMessageCell::new_hyperlink_lines(
render_source(
&source,
Some(48),
&cwd,
HistoryRenderMode::Rich,
/*inline_visualization_context*/ None,
),
/*is_first_line*/ true,
);
assert_eq!(displayed, expected.display_lines(/*width*/ 50));
assert_eq!(finalized_source, Some(format!("{source}\n")));
assert!(!controller.has_live_tail());
}
}
#[test]
fn partial_markdown_structures_remain_newline_gated() {
let cwd = std::env::temp_dir();
for (committed, partial) in [
("", "| partial header"),
("", "```rust"),
("", "> ~~~rust"),
("```rust\n", "let partial = 1;"),
("- ```rust\n", " let partial = 1;"),
("> - ```rust\n", "> let partial = 1;"),
(" indented code\n", " partial code"),
("```markdown\n", "partial markdown fence"),
("| A | B |\n| --- | --- |\n", "partial row"),
] {
let mut controller = StreamController::new(Some(40), &cwd, HistoryRenderMode::Rich);
controller.push(committed);
let tail = controller.current_tail_lines();
let queued = controller.queued_lines();
controller.push(partial);
assert_eq!(controller.current_tail_lines(), tail);
assert_eq!(controller.queued_lines(), queued);
}
}
#[test]
fn long_unicode_preview_keeps_recent_text_and_finalizes_full_source() {
let cwd = std::env::temp_dir();
let mut controller = StreamController::new(Some(40), &cwd, HistoryRenderMode::Rich);
controller.push(&"🦀 ".repeat(3000));
controller.push("latest text");
let preview = visible_lines(controller.current_tail_lines());
assert_eq!(preview.first(), Some(&Line::from("…")));
let text = preview
.iter()
.map(Line::to_string)
.collect::<Vec<_>>()
.join(" ");
assert!(text.trim_end().ends_with("latest text"), "{text}");
assert_eq!(controller.queued_lines(), 0);
let (_, source) = controller.finalize();
assert_eq!(source, Some(format!("{}latest text\n", "🦀 ".repeat(3000))));
}
#[test]
fn prose_preview_resumes_after_fenced_code() {
let cwd = std::env::temp_dir();
let mut controller = StreamController::new(Some(40), &cwd, HistoryRenderMode::Rich);
controller.push("```rust\nlet x = 1;\n```\n");
controller.on_commit_tick_batch(usize::MAX);
controller.push("prose after code");
assert_eq!(
visible_lines(controller.current_tail_lines()),
vec![Line::from("prose after code")],
);
}
#[test]
fn prose_after_a_table_is_previewed_until_another_table_starts() {
let cwd = std::env::temp_dir();
let mut controller = StreamController::new(Some(40), &cwd, HistoryRenderMode::Rich);
controller.push("| A | B |\n| --- | --- |\n| a | b |\n\n");
controller.push("prose after the table");
let tail = visible_lines(controller.current_tail_lines());
assert_eq!(tail.last(), Some(&Line::from("prose after the table")));
assert_eq!(controller.queued_lines(), 0);
controller.push("\n\n| C | D |\n| --- | --- |\n");
let tail = controller.current_tail_lines();
controller.push("partial row");
assert_eq!(controller.current_tail_lines(), tail);
}
+1
View File
@@ -20,6 +20,7 @@ pub(crate) mod chunking;
mod code_fence;
pub(crate) mod commit_tick;
pub(crate) mod controller;
mod prose_preview;
mod render;
mod table_holdback;
@@ -0,0 +1,63 @@
//! Bounded, disposable previews of unterminated prose. Preview lines never enter scrollback;
//! newline commitment and finalization render the original source independently.
use super::render::render_source;
use crate::history_cell::HistoryRenderMode;
use crate::inline_visualization::InlineVisualizationContext;
use crate::terminal_hyperlinks::HyperlinkLine;
use ratatui::text::Line;
use std::path::Path;
const MAX_PREVIEW_BYTES: usize = 8192;
/// Tracks one append-only incomplete line; reset when a newline is committed.
#[derive(Default)]
pub(super) struct ProsePreview {
pub(super) lines: Vec<HyperlinkLine>,
scanned_len: usize,
safe_len: usize,
has_pipe: bool,
}
impl ProsePreview {
pub(super) fn update(
&mut self,
source: &str,
width: Option<usize>,
cwd: &Path,
render_mode: HistoryRenderMode,
inline_visualization_context: Option<&InlineVisualizationContext>,
) -> bool {
// Only scan newly arrived bytes, including on very long single-line responses.
self.has_pipe |= source[self.scanned_len..].contains('|');
self.scanned_len = source.len();
// Indented and quoted lines may belong to nested code blocks. Keep their
// existing newline holdback instead of guessing at the missing block context.
if !(self.has_pipe
|| source.starts_with([' ', '\t', '>'])
|| source.starts_with("```")
|| source.starts_with("~~~")
|| matches!(source, "`" | "``" | "~" | "~~"))
{
self.safe_len = source.len();
}
// Retain the last safe text when tokens reveal structure, but still reflow it.
let source = &source[..self.safe_len];
let start = source.ceil_char_boundary(source.len().saturating_sub(MAX_PREVIEW_BYTES));
let mut lines = render_source(
&source[start..],
width,
cwd,
render_mode,
inline_visualization_context,
);
if start > 0 {
lines.insert(0, HyperlinkLine::new(Line::from("…")));
}
if self.lines == lines {
return false;
}
self.lines = lines;
true
}
}
+20 -3
View File
@@ -54,6 +54,8 @@ pub(super) struct TableHoldbackScanner {
previous_line: Option<PreviousLineState>,
pending_header_start: Option<usize>,
confirmed_table_start: Option<usize>,
/// Unlike scrollback holdback, partial-row holdback ends at a blank line.
in_table: bool,
}
impl TableHoldbackScanner {
@@ -64,6 +66,7 @@ impl TableHoldbackScanner {
previous_line: None,
pending_header_start: None,
confirmed_table_start: None,
in_table: false,
}
}
@@ -88,6 +91,13 @@ impl TableHoldbackScanner {
}
}
/// Partial prose can be previewed only outside tables and fenced blocks.
pub(super) fn allows_prose_preview(&self) -> bool {
!self.in_table
&& !self.previous_line.is_some_and(|line| line.is_header)
&& self.fence_tracker.kind() == FenceKind::Outside
}
/// Advance the scanner with newly committed source.
///
/// Chunks are expected to contain only source that is now safe to commit
@@ -129,15 +139,19 @@ impl TableHoldbackScanner {
let is_header = candidate_text.is_some_and(is_table_header_line);
let is_delimiter = candidate_text.is_some_and(is_table_delimiter_line);
if self.confirmed_table_start.is_none()
&& let Some(previous_line) = self.previous_line
if strip_blockquote_prefix(line).is_empty() {
self.in_table = false;
}
if let Some(previous_line) = self.previous_line
&& previous_line.fence_kind != FenceKind::Other
&& fence_kind != FenceKind::Other
&& previous_line.is_header
&& is_delimiter
{
self.confirmed_table_start = Some(previous_line.source_start);
self.confirmed_table_start
.get_or_insert(previous_line.source_start);
self.pending_header_start = None;
self.in_table = true;
}
if self.confirmed_table_start.is_none() && !line.trim().is_empty() {
@@ -155,6 +169,9 @@ impl TableHoldbackScanner {
});
self.fence_tracker.advance(line);
if fence_kind != FenceKind::Outside && self.fence_tracker.kind() == FenceKind::Outside {
self.in_table = false;
}
self.source_offset = self.source_offset.saturating_add(source_line.len());
}
}