WIP: Rework TUI viewport, history printing, and selection/copy

[joshka-oai]

WIP: Rework TUI viewport, history printing, and selection/copy

Draft PR – large behavior change to how the TUI owns its viewport, history, and suspend behavior. Core model is in place; a few items are still being polished before this is ready to merge.

---

Summary

This PR moves the Codex TUI off of “cooperating” with the terminal’s scrollback and onto a model where the in‑memory transcript is the single source of truth. The TUI now owns scrolling, selection, copy, and suspend/exit printing based on that transcript, and only writes to terminal scrollback in append‑only fashion on suspend/exit. It also fixes streaming wrapping so streamed responses reflow with the viewport, and introduces configuration to control whether we print history on suspend or only on exit.

High‑level goals:

• Ensure history is complete, ordered, and never silently dropped.
• Print each logical history cell at most once into scrollback, even with resizes and suspends.
• Make scrolling, selection, and copy match the visible transcript, not the terminal’s notion of scrollback.
• Keep suspend/alt‑screen behavior predictable across terminals.

---

Core Design Changes

Transcript & viewport ownership

• Treat the transcript as a list of cells (user prompts, agent messages, system/info rows, streaming segments).
• On each frame:
  • Compute a transcript region as “full terminal frame minus the bottom input area”.
  • Flatten all cells into visual lines plus metadata (which cell + which line within that cell).
  • Use scroll state to choose which visual line is at the top of the region.
  • Clear that region and draw just the visible slice of lines.
• The terminal’s scrollback is no longer part of the live layout algorithm; it is only ever written to when we decide to print history.

User message styling

• User prompts now render as clear blocks with:
  • A blank padding line above and below.
  • A full‑width background for every line in the block (including the prompt line itself).
• The same block styling is used when we print history into scrollback, so the transcript looks consistent whether you are in the TUI or scrolling back after exit/suspend.

---

Scrolling, Mouse, Selection, and Copy

Scrolling

• Scrolling is defined in terms of the flattened transcript lines:
  • Mouse wheel scrolls up/down by fixed line increments.
  • PgUp/PgDn/Home/End operate on the same scroll model.
• The footer shows:
  • Whether you are “following live output” vs “scrolled up”.
  • Current scroll position (line / total).
• When there is no history yet, the bottom pane is pegged high and gradually moves down as the transcript fills, matching the existing UX.

Selection

• Click‑and‑drag defines a linear selection over transcript line/column coordinates, not raw screen rows.
• Selection is content‑anchored:
  • When you scroll, the selection moves with the underlying lines instead of sticking to a fixed Y position.
  • This holds both when scrolling manually and when new content streams in, as long as you are in “follow” mode.
• The selection only covers the “transcript text” area:
  • Left gutter/prefix (bullets, markers) is intentionally excluded.
  • This keeps copy/paste cleaner and avoids including structural margin characters.

Copy (Ctrl+Y)

• Introduce a small clipboard abstraction (ClipboardManager‑style) and use a cross‑platform clipboard crate under the hood.
• When Ctrl+Y is pressed and a non‑empty selection exists:
  • Re‑render the transcript region off‑screen using the same wrapping as the visible viewport.
  • Walk the selected line/column range over that buffer to reconstruct the exact text:
    • Includes spaces between words.
    • Preserves empty lines within the selection.
  • Send the resulting text to the system clipboard.
  • Show a short status message in the footer indicating success/failure.
• Copy is best‑effort:
  • Clipboard failures (headless environment, sandbox, remote sessions) are handled gracefully via status messages; they do not crash the TUI.
  • Copy does not insert a new history entry; it only affects the status bar.

---

Streaming and Wrapping

Previous behavior

Previously, streamed markdown:

• Was wrapped at a fixed width at commit time inside the streaming collector.
• Those wrapped Line<'static> values were then wrapped again at display time.
• As a result, streamed paragraphs could not “un‑wrap” when the terminal width increased; they were permanently split according to the width at the start of the stream.

New behavior

This PR implements the first step from codex-rs/tui/streaming_wrapping_design.md:

• Streaming collector is constructed without a fixed width for wrapping.
  • It still:
    • Buffers the full markdown source for the current stream.
    • Commits only at newline boundaries.
    • Emits logical lines as new content becomes available.
• Agent message cells now wrap streamed content only at display time, based on the current viewport width, just like non‑streaming messages.
• Consequences:
  • Streamed responses reflow correctly when the terminal is resized.
  • Animation steps are per logical line instead of per “pre‑wrapped” visual line; this makes some commits slightly larger but keeps the behavior simple and predictable.

Streaming responses are still represented as a sequence of logical history entries (first line + continuations) and integrate with the same scrolling, selection, and printing model.

---

Printing History on Suspend and Exit

High‑water mark and append‑only scrollback

• Introduce a cell‑based high‑water mark (printed_history_cells) on the transcript:
  • Represents “how many cells at the front of the transcript have already been printed”.
  • Completely independent of wrapped line counts or terminal geometry.
• Whenever we print history (suspend or exit):
  • Take the suffix of transcript_cells beyond printed_history_cells.
  • Render just that suffix into styled lines at the current width.
  • Write those lines to stdout.
  • Advance printed_history_cells to cover all cells we just printed.
• Older cells are never re‑rendered for scrollback. They stay in whatever wrapping they had when printed, which is acceptable as long as the logical content is present once.

Suspend (Ctrl+Z)

• On suspend:
  • Leave alt screen if active and restore normal terminal modes.
  • Render the not‑yet‑printed suffix of the transcript and append it to normal scrollback.
  • Advance the high‑water mark.
  • Suspend the process.
• On resume (fg):
  • Re‑enter the TUI mode (alt screen + input modes).
  • Clear the viewport region and fully redraw from in‑memory transcript and state.

This gives predictable behavior across terminals without trying to maintain scrollback live.

Exit

• On exit:
  • Render any remaining unprinted cells once and write them to stdout.
  • Add an extra blank line after the final Codex history cell before printing token usage, so the transcript and usage info are visually separated.
• If you never suspended, exit prints the entire transcript exactly once.
• If you suspended one or more times, exit prints only the cells appended after the last suspend.

---

Configuration: Suspend Printing

This PR also adds configuration to control when we print history:

• New TUI config option to gate printing on suspend:
  • At minimum:
    • print_on_suspend = true – current behavior: print new history at each suspend and on exit.
    • print_on_suspend = false – only print on exit.
  • Default is tuned to preserve current behavior, but this can be revisited based on feedback.
• The config is respected in the suspend path:
  • If disabled, suspend only restores terminal modes and stops rendering but does not print new history.
  • Exit still prints the full not‑yet‑printed suffix once.

This keeps the core viewport logic agnostic to preference, while letting users who care about quiet scrollback opt out of suspend printing.

---

Tradeoffs

What we gain:

• A single authoritative history model (the in‑memory transcript).
• Deterministic viewport rendering independent of terminal quirks.
• Suspend/exit flows that:
  • Print each logical history cell exactly once.
  • Work across resizes and different terminals.
  • Interact cleanly with alt screen and raw‑mode toggling.
• Consistent, content‑anchored scrolling, selection, and copy.
• Streaming messages that reflow correctly with the viewport width.

What we accept:

• Scrollback may contain older cells wrapped differently than newer ones.
• Streaming responses appear in scrollback as a sequence of blocks corresponding to their streaming structure, not as a single retroactively reflowed paragraph.
• We do not attempt to rewrite or reflow already‑printed scrollback.

For deeper rationale and diagrams, see docs/tui_viewport_and_history.md and codex-rs/tui/streaming_wrapping_design.md.

---

Still to Do Before This PR Is Ready

These are scoped to this PR (not long‑term future work):

• [ ] Streaming wrapping polish

  • Double‑check all streaming paths use display‑time wrapping only.
  • Ensure tests cover resizing after streaming has started.

• [ ] Suspend printing config

  • Finalize config shape and default (keep existing behavior vs opt‑out).
  • Wire config through TUI startup and document it in the appropriate config docs.

• [x] Bottom pane positioning

  • Ensure the bottom pane is pegged high when there’s no history and smoothly moves down as the transcript fills, matching the current behavior across startup and resume.

• [x] Transcript mouse scrolling

  • Re‑enable wheel‑based transcript scrolling on top of the new scroll model.
  • Make sure mouse scroll does not get confused with “alternate scroll” modes from terminals.

• [x] Mouse selection vs streaming

  • When selection is active, stop auto‑scrolling on streaming so the selection remains stable on the selected content.
  • Ensure that when streaming continues after selection is cleared, “follow latest output” mode resumes correctly.

• [ ] Auto‑scroll during drag

  • While the user is dragging a selection, auto‑scroll when the cursor is at/near the top or bottom of the transcript viewport to allow selecting beyond the current visible window.

• [ ] Feature flag / rollout

  • Investigate gating the new viewport/history behavior behind a feature flag for initial rollout, so we can fall back to the old behavior if needed during early testing.

• [ ] Before/after videos

  • Capture short clips showing:
    • Scrolling (mouse + keys).
    • Selection and copy.
    • Streaming behavior under resize.
    • Suspend/resume and exit printing.
  • Use these to validate UX and share context in the PR discussion.

---

[joshka-oai]

@codex review

[joshka-oai]

@codex review