Struct Renderer 

pub struct Renderer<W: Write> { /* private fields */ }

Renders an immutable document prefix and a mutable viewport-local suffix.

stable_rows declares the leading rows that will never change again. Stable rows enter native scrollback only when they leave the visible top edge. Already-clipped stable rows remain protected but deferred until a rebuild, avoiding a viewport replay that would displace native text selections. A committed or previously declared-stable mutation is rejected before any terminal output, because native scrollback has no addressable cells. The retained physical screen model composes the raw previous frame with its stored viewport layers.

Implementations

impl<W: Write> Renderer<W>

pub fn new(writer: W) -> Self

Creates a renderer whose first document clears only the visible viewport.

Examples found in repository

examples/footers.rs (line 57)

async fn main() -> io::Result<()> {
	let caps = detect();
	let charset = UiContext::default().with_terminal_caps(&caps).charset;
	let mut terminal = Terminal::enter(TerminalOptions::new(caps).mouse(true))?;
	let mut renderer = Renderer::new(TtyOut::new()?);
	renderer.apply_caps(&caps)?;
	match run(&mut terminal, &mut renderer, charset).await {
		Ok(()) => terminal.leave_alt(),
		Err(error) => {
			let _ = terminal.leave_alt();
			Err(error)
		},
	}
}

examples/chat/main.rs (line 60)

async fn main() -> io::Result<()> {
	let caps = detect();
	// One detected presentation context — charset, graphics, appearance —
	// threads through every scene instead of per-module hardcodes.
	let ctx = UiContext::default().with_terminal_caps(&caps);
	let mut terminal =
		Terminal::enter(TerminalOptions::new(caps).cursor_style(CursorStyle::BlinkingBar))?;
	let mut renderer = Renderer::new(TtyOut::new()?);
	renderer.apply_caps(&caps)?;
	run(&mut terminal, &mut renderer, &ctx).await
}

pub fn apply_caps(&mut self, caps: &TerminalCaps) -> Result<()>

Configures every capability-driven renderer option from resolved caps.

Errors

Rejects zero cell-pixel dimensions.

Examples found in repository

examples/footers.rs (line 58)

async fn main() -> io::Result<()> {
	let caps = detect();
	let charset = UiContext::default().with_terminal_caps(&caps).charset;
	let mut terminal = Terminal::enter(TerminalOptions::new(caps).mouse(true))?;
	let mut renderer = Renderer::new(TtyOut::new()?);
	renderer.apply_caps(&caps)?;
	match run(&mut terminal, &mut renderer, charset).await {
		Ok(()) => terminal.leave_alt(),
		Err(error) => {
			let _ = terminal.leave_alt();
			Err(error)
		},
	}
}

examples/chat/main.rs (line 61)

async fn main() -> io::Result<()> {
	let caps = detect();
	// One detected presentation context — charset, graphics, appearance —
	// threads through every scene instead of per-module hardcodes.
	let ctx = UiContext::default().with_terminal_caps(&caps);
	let mut terminal =
		Terminal::enter(TerminalOptions::new(caps).cursor_style(CursorStyle::BlinkingBar))?;
	let mut renderer = Renderer::new(TtyOut::new()?);
	renderer.apply_caps(&caps)?;
	run(&mut terminal, &mut renderer, &ctx).await
}

pub fn register_image( &mut self, id: u32, png_bytes: impl Into<CowBytes<'static>>, ) -> Result<()>

Registers PNG bytes for a typed terminal image ID.

Protocol encoding is deferred until a presented frame references the ID. Re-registering an ID replaces its bytes and protocol cache.

Errors

Rejects ID zero and IDs wider than Kitty’s 24-bit placeholder encoding.

Examples found in repository

examples/companies.rs (lines 202-205)

async fn main() -> io::Result<()> {
	let mut app = AppOptions::new()
		.mouse()
		.probe(Duration::from_millis(150))
		.graphics_with(forced_from_args)
		.start(|env| build_ui(env.viewport, env.ctx))
		.await?;
	if app.caps().graphics != Graphics::Cells {
		for (index, provider) in PROVIDERS.iter().enumerate() {
			let png = tokio::fs::read(format!("{ASSET_DIR}/{}.png", provider.id)).await?;
			app.renderer_mut().register_image(
				u32::try_from(index + 1).expect("provider count fits image IDs"),
				png,
			)?;
		}
		app.ui_mut().invalidate(SCROLL_ID);
	}
	show_stats(&mut app, None);
	let mut chosen: Option<String> = None;
	while let Some(event) = app.next().await? {
		match event {
			AppEvent::Resized(viewport) => {
				app.ui_mut().set_height(SCROLL_ID, scroll_height(viewport));
			},
			AppEvent::Pressed(id) => chosen = Some(id.to_string()),
			_ => {},
		}
		show_stats(&mut app, chosen.as_deref());
	}
	Ok(())
}

pub const fn set_graphics(&mut self, graphics: Graphics)

Selects how typed image cells are materialized.

Set this before the first presentation. Graphics::Cells, Graphics::Sixel, and Graphics::KittyDirect materialize typed cells as ordinary blanks; Graphics::KittyPlaceholders uses Unicode placeholders.

pub const fn set_sync_output(&mut self, enabled: bool)

Enables or disables DEC synchronized-output wrapping.

Wrapping is enabled by default to preserve the renderer’s historical behavior. Capability detection should disable it for unsupported terminals.

pub const fn set_screen_to_scrollback(&mut self, enabled: bool)

Enables or disables moving cleared viewport content to native scrollback.

When enabled, a full viewport clear first emits Kitty’s CSI 22 J extension. It is disabled by default.

pub const fn set_margin_scrollback(&mut self, enabled: bool)

Enables committing scrolled-out rows through a top-anchored DECSTBM region instead of a whole-screen scroll.

Screen rows below the region never move during a commit, and native scrollback receives exactly the same history as a whole-screen scroll. Whether a terminal-native text selection over the pinned rows survives is a separate, terminal-specific property: kitty and Alacritty transform selections correctly on region scrolls; ghostty, iTerm2, and xterm.js leave them anchored to pre-scroll storage rows, so they drift upward — matching what a whole-screen scroll does to selections over stationary live content repainted back into place; WezTerm clears them. Enable this only for terminals that move rows scrolled out of a top-anchored region into native scrollback (see TerminalCaps::margin_scrollback); it is disabled by default.

pub const fn set_hyperlinks(&mut self, enabled: bool)

Enables or disables OSC 8 hyperlink materialization.

Link identities remain attached to frame cells while disabled, but output stays byte-for-byte identical to ordinary styled text.

pub fn set_cell_pixel_size(&mut self, width: u16, height: u16) -> Result<()>

Sets the terminal cell size used to scale sixel placements.

The default is 9 by 18 pixels per cell, matching pi’s nominal terminal metrics. Detection code may override it before presentation.

Errors

Rejects a zero pixel dimension.

pub const fn set_tmux_passthrough(&mut self, enabled: bool)

Enables tmux DCS passthrough for Kitty and sixel graphics sequences.

Cursor movement, synchronized output, and ordinary text styling remain direct terminal output.

pub fn present( &mut self, next: Frame, viewport_height: u16, stable_rows: u16, ) -> Result<PaintStats>

Paints a logical document with an immutable leading-row boundary.

The caller must disable terminal autowrap and keep terminal geometry fixed while the renderer is active; the renderer itself re-enables DECAWM transiently to join flagged soft-wrap boundaries (see Frame::set_soft_wrap) so native selection and scrollback copy them as one unbroken line. Advancing stable_rows is permanent, and committed history makes the document height a ratchet: between rebuilds the document may only grow, so transient rows (pickers, extra input lines) must be absorbed by the caller rather than shrinking the frame.

Errors

Rejects zero or changed geometry, a retreating stable boundary, mutation within the prior stable prefix, or a document whose tail shrank below committed history. Writer failure poisons the renderer because its physical state is unknown.

pub fn present_ref( &mut self, next: &Frame, viewport_height: u16, stable_rows: u16, ) -> Result<PaintStats>

Renderer::present without taking the frame: diffs against the retained previous frame, then clone_froms the borrowed one into it — reusing the existing cell allocation instead of copying a whole frame per paint. Cost is still O(grid) cell clones per call; retained callers that track their own damage should prefer Renderer::present_damaged.

Errors

Same contract as Renderer::present.

pub fn present_overlaid( &mut self, next: &Frame, damaged: &[(u16, u16)], viewport_height: u16, stable_rows: u16, layers: &[Layer<'_>], ) -> Result<PaintStats>

Paints a damaged raw document with declarative viewport-anchored layers.

damaged follows Renderer::present_damaged. Layers composite only into the live viewport while history commits keep flowing: a row leaving the window is repainted from the raw document before it scrolls into native scrollback, so layer cells never reach history. Direct-drawn sixel, Kitty-direct, and iTerm2 images remain raw and are not occluded; Kitty placeholder cells participate in composition.

Errors

Same contract as Renderer::present.

Examples found in repository

examples/chat/main.rs (lines 413-419)

async fn chat<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	ctx: &'a UiContext,
) -> io::Result<()> {
	let mut viewport = terminal.size()?;
	if !run_welcome(terminal, renderer, ctx.charset, &mut viewport).await? {
		return Ok(());
	}
	// The welcome scene held the alternate screen; releasing it restores the
	// untouched shell and the chat pushes inline from a clean slate.
	terminal.leave_alt()?;

	let mut demo = Demo::new(ctx);
	let mut overlay: Option<Overlay> = None;
	let mut current_model = 0_usize;
	let started = Instant::now();
	let mut sidebar = Sidebar::new(MODELS[current_model].name, ctx);
	demo.set_right_inset(sidebar.reserved(viewport));
	{
		let rendered = demo.render(viewport);
		let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
		present(renderer, rendered, viewport, &layers)?;
	}

	// Alternate-screen ownership for the chat scene: a resize gesture borrows
	// it for throwaway drag frames, an open overlay holds it for its lifetime.
	let mut drag_alt = false;
	let mut overlay_stale = false;
	let mut resize = None;
	// At most one in-flight background clipboard read (Ctrl+V/Ctrl+Shift+V).
	let mut paste_read: Option<PasteRead> = None;
	let mut next_frame = Instant::now() + FRAME_INTERVAL;
	loop {
		let paste_deadline = paste_read.as_ref().map(|read| read.abandon_at);
		tokio::select! {
			// The terminal branch pauses while a clipboard read is in flight:
			// the event mailbox buffers input in order, so an Enter typed
			// right after Ctrl+V lands *after* the paste instead of
			// submitting an empty prompt. The read below is bounded, so the
			// pause is too; retained App hosts get the finer-grained
			// per-event queue instead.
			event = terminal.next(), if paste_read.is_none() => match event? {
				TerminalEvent::Resize => {
					let now = Instant::now();
					let resized = observe_resize(terminal, &mut viewport, &mut resize, now)?;
					demo.set_right_inset(sidebar.reserved(viewport));
					if overlay.is_some() && resized {
						overlay_stale = true;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(()),
				TerminalEvent::Input(event) => {
					let Some(event) = user_event(terminal, renderer, event)? else {
						continue;
					};
					match event {
					InputEvent::Key(key) => {
						if overlay.is_some() {
							if key == Key::Ctrl('c') {
								break;
							}
							let event = overlay
								.as_mut()
								.expect("overlay checked above")
								.handle_key(key);
							if apply_overlay_event(
								event,
								&mut overlay,
								&mut current_model,
								terminal,
								renderer,
								&mut demo,
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut overlay_stale,
								&mut resize,
								ctx,
							)? {
								break;
							}
						} else if key == Key::Ctrl('b') {
							sidebar.toggle();
							demo.set_right_inset(sidebar.reserved(viewport));
						} else if key == Key::Ctrl('k') {
							overlay = Some(Overlay::Palette(CommandPalette::open(ctx)));
							open_overlay(
								terminal,
								renderer,
								&mut demo,
								overlay.as_mut().expect("palette just opened"),
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut drag_alt,
								&mut overlay_stale,
								&mut resize,
							)?;
						} else if sidebar.focused() {
							if key == Key::Ctrl('c') {
								break;
							}
							sidebar.handle_key(key);
						} else if key == Key::Ctrl('p') || key == Key::Alt('p') {
							overlay = Some(Overlay::Picker(ModelPicker::open(current_model, ctx)));
							open_overlay(
								terminal,
								renderer,
								&mut demo,
								overlay.as_mut().expect("picker just opened"),
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut drag_alt,
								&mut overlay_stale,
								&mut resize,
							)?;
						} else if let Some(scope) = ClipboardRead::for_key(key) {
							// The terminal did not claim the chord; read the
							// system clipboard off-thread, preferring images
							// unless the raw spelling asked for text only. A
							// failed spawn closes the channel, so the receive
							// branch below recovers input immediately.
							paste_read = Some(PasteRead::start(scope));
						} else {
							let quit = demo.handle_key(key);
							if demo.take_switch_request() {
								overlay = Some(Overlay::Picker(ModelPicker::open(current_model, ctx)));
								open_overlay(
									terminal,
									renderer,
									&mut demo,
									overlay.as_mut().expect("picker just opened"),
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut drag_alt,
									&mut overlay_stale,
									&mut resize,
								)?;
							}
							if quit {
								break;
							}
						}
						next_frame = Instant::now();
					},
					InputEvent::Paste(text) => {
						let event = overlay.as_mut().map(|active| active.handle_paste(&text));
						match event {
							Some(event) => {
								if apply_overlay_event(
									event,
									&mut overlay,
									&mut current_model,
									terminal,
									renderer,
									&mut demo,
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut overlay_stale,
									&mut resize,
									ctx,
								)? {
									break;
								}
							},
							None if sidebar.focused() => {},
							None => demo.handle_paste(&text),
						}
						next_frame = Instant::now();
					},
					InputEvent::Mouse(report) => {
						// An open overlay owns pointer input — hover, wheel,
						// and clicks route through the compositor's band,
						// never the occluded editor beneath.
						let event = overlay
							.as_mut()
							.map(|active| active.handle_mouse(report.col, report.row, report.kind, viewport));
						match event {
							Some(event) => {
								if apply_overlay_event(
									event,
									&mut overlay,
									&mut current_model,
									terminal,
									renderer,
									&mut demo,
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut overlay_stale,
									&mut resize,
									ctx,
								)? {
									break;
								}
							},
							None => {
								if !sidebar.handle_mouse(report.col, report.row, report.kind, viewport)
								{
									demo.handle_mouse(&report);
								}
							},
						}
						next_frame = Instant::now();
					},
					InputEvent::Focus(_) | InputEvent::Response(_) => {},
				}
				},
			},
			clipboard = async { (&mut paste_read.as_mut().expect("branch gated on Some").clipboard).await },
				if paste_read.is_some() =>
			{
				let read = paste_read.take().expect("branch gated on Some");
				// A closed channel (the reader thread never spawned) reads
				// as an empty clipboard.
				if let Ok(Some(clipboard)) = clipboard
					&& let Some(text) = clipboard_paste_text(clipboard)
					&& overlay.is_none()
					&& !sidebar.focused()
				{
					// Ctrl+Shift+V inserts verbatim: no attachment staging,
					// no large-paste collapse.
					match read.scope {
						ClipboardRead::Text => demo.handle_paste_raw(&text),
						ClipboardRead::Smart => demo.handle_paste(&text),
					}
					next_frame = Instant::now();
				}
			},
			// The deadline is absolute, so the frame tick recreating this
			// branch's future cannot reset it: a hung reader is abandoned and
			// terminal input re-enables. Dropping the receiver makes the
			// reader's eventual send fail; the detached thread dies with the
			// process instead of stalling shutdown.
			() = deadline(paste_deadline) => {
				paste_read = None;
			},
			() = deadline(Some(next_frame)) => {
				let now = Instant::now();
				let resized = observe_resize(terminal, &mut viewport, &mut resize, now)?;
				demo.set_right_inset(sidebar.reserved(viewport));
				if overlay.is_some() && resized {
					overlay_stale = true;
				}
				if resize.is_some() {
					// Drag frames compose exactly one viewport tail at the
					// new geometry — O(viewport) per frame; the O(history)
					// transcript reflow waits for the settle rebuild (or the
					// overlay close). Without an overlay, a width change
					// borrows the alternate screen (the inline transcript
					// rewraps underneath) while height-only churn repaints
					// in place — alt toggling on a height echo can
					// self-sustain.
					let preview = demo.render_resize_preview(viewport);
					if let Some(active) = overlay.as_mut() {
								  let mut layers = rail_layers(&mut sidebar, viewport, started.elapsed());
								  layers.push(active.layer(viewport));
								  renderer.preview_overlaid(&preview, &layers, viewport.height, "")?;
							  } else {
								  let width_changed =
									  resize.is_some_and(|state| state.width_changed);
								  let alt_enter = if drag_alt || !width_changed {
									  None
								  } else {
									  let staged = terminal.stage_alt_enter(AltScreenUse::Resize);
									  drag_alt = staged.is_some();
									  staged
								  };
								  let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
								  renderer.preview_overlaid(
									  &preview,
									  &layers,
									  viewport.height,
									  alt_enter.as_deref().unwrap_or(""),
								  )?;
							  }
				} else if let Some(active) = overlay.as_mut() {
					let rendered = demo.render(viewport);
					let mut layers = rail_layers(&mut sidebar, viewport, started.elapsed());
					layers.push(active.layer(viewport));
					renderer.preview_overlaid(rendered.frame, &layers, viewport.height, "")?;
				} else {
					let rendered = demo.render(viewport);
					let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
					present(renderer, rendered, viewport, &layers)?;
				}
				next_frame = now + FRAME_INTERVAL;
			},
			() = deadline(resize.map(ResizeState::deadline)) => {
				let now = Instant::now();
				if !resize.is_some_and(|state| state.settled(now)) {
					continue;
				}
				if overlay.is_some() {
					// The overlay keeps holding the alternate screen; the
					// transcript reflows once at close.
					overlay_stale = true;
					resize = None;
					continue;
				}
				demo.set_right_inset(sidebar.reserved(viewport));
				let rendered = demo.render(viewport);
				let alt_exit = if drag_alt {
					drag_alt = false;
					terminal.stage_alt_leave().unwrap_or("")
				} else {
					""
				};
				renderer.rebuild(
					rendered.frame.clone(),
					viewport.height,
					rendered.stable_rows,
					alt_exit,
				)?;
				// The rebuild repainted the raw document; recomposite the
				// rail on top without touching the fresh history.
				let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
				if !layers.is_empty() {
					renderer.present_overlaid(
						rendered.frame,
						&[],
						viewport.height,
						rendered.stable_rows,
						&layers,
					)?;
				}
				resize = None;
				next_frame = now + FRAME_INTERVAL;
			},
		}
	}
	Ok(())
}

/// Animates the welcome card until the user resumes into the chat demo
/// (`Ok(true)`) or quits (`Ok(false)`), keeping `viewport` current across
/// resizes.
///
/// The scene owns the alternate screen for its whole lifetime: entry rides
/// the first card paint, mouse tracking is active throughout, and every
/// geometry change repaints in place immediately. The main screen stays
/// untouched underneath — the caller releases the hold on scene exit.
async fn run_welcome<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	charset: Charset,
	viewport: &'a mut Size,
) -> io::Result<bool> {
	let mut alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	let mut welcome = Welcome::new(charset);
	let started = Instant::now();
	let mut next_frame = Instant::now();
	loop {
		tokio::select! {
			event = terminal.next() => match event? {
				TerminalEvent::Resize => {
					if let Some(size) = terminal.take_resize()? {
						*viewport = size;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(false),
				TerminalEvent::Input(event) => {
					let Some(event) = user_event(terminal, renderer, event)? else {
						continue;
					};
					match event {
					InputEvent::Key(Key::Enter) => return Ok(true),
					InputEvent::Key(Key::Esc | Key::Ctrl('c')) => return Ok(false),
					InputEvent::Mouse(report) if matches!(report.kind, Mouse::Move | Mouse::Drag) => {
						welcome.point_at(report.col, report.row);
					},
					InputEvent::Key(_)
					| InputEvent::Mouse(_)
					| InputEvent::Paste(_)
					| InputEvent::Focus(_)
					| InputEvent::Response(_) => {},
				}
				},
			},
			() = deadline(Some(next_frame)) => {
				let now = Instant::now();
				if let Some(size) = terminal.take_resize()? {
					*viewport = size;
				}
				let frame = welcome.render(*viewport, started.elapsed());
				renderer.preview(
					frame,
					viewport.height,
					alt_enter.take().as_deref().unwrap_or(""),
				)?;
				next_frame = now + FRAME_INTERVAL;
			},
		}
	}
}

#[derive(Clone, Copy)]
struct ResizeState {
	last_event:    Instant,
	/// Whether any report in this gesture changed the width; only then does
	/// the drag borrow the alternate screen.
	width_changed: bool,
}

impl ResizeState {
	const fn new(last_event: Instant, width_changed: bool) -> Self {
		Self { last_event, width_changed }
	}

	const fn observe(&mut self, observed_at: Instant, width_changed: bool) {
		self.last_event = observed_at;
		self.width_changed |= width_changed;
	}

	fn deadline(self) -> Instant {
		self.last_event + RESIZE_SETTLE
	}

	fn settled(self, now: Instant) -> bool {
		now >= self.deadline()
	}
}

/// Consumes the latest resize — SIGWINCH or DEC 2048 in-band — and (re)arms
/// the settle window. Same-size reports outside a gesture are echoes
/// (terminals re-reporting geometry across alternate-screen toggles) and are
/// swallowed without arming a rebuild.
fn observe_resize(
	terminal: &mut Terminal,
	viewport: &mut Size,
	resize: &mut Option<ResizeState>,
	observed_at: Instant,
) -> io::Result<bool> {
	let Some(size) = terminal.take_resize()? else {
		return Ok(false);
	};
	if size == *viewport && resize.is_none() {
		return Ok(false);
	}
	let width_changed = size.width != viewport.width;
	*viewport = size;
	match resize {
		Some(state) => state.observe(observed_at, width_changed),
		None => *resize = Some(ResizeState::new(observed_at, width_changed)),
	}
	Ok(true)
}

fn user_event(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	event: InputEvent,
) -> io::Result<Option<InputEvent>> {
	if terminal.handle_input_event(&event, renderer)? {
		// A consumed response may have completed an enhanced-paste (OSC
		// 5522) conversation; re-inject its payload as ordinary paste input
		// so the normal routing below stages images and text alike.
		return Ok(terminal.take_paste().and_then(|pasted| {
			let text = match pasted {
				Pasted::Text(text) => text,
				Pasted::Image(image) => image.persist().ok()?.display().to_string().into(),
			};
			Some(InputEvent::Paste(text))
		}));
	}
	Ok(Some(event))
}

/// Flattens a background clipboard read into paste text: images persist to
/// a temp file whose path routes like a file drop, and copied file paths
/// are quoted so spaces survive drop classification.
fn clipboard_paste_text(clipboard: Clipboard) -> Option<String> {
	match clipboard {
		Clipboard::Text(text) => Some(text),
		Clipboard::Image(image) => Some(image.persist().ok()?.display().to_string()),
		Clipboard::Paths(paths) => {
			let mut joined = String::new();
			for path in &paths {
				if !joined.is_empty() {
					joined.push(' ');
				}
				joined.push('"');
				joined.push_str(path);
				joined.push('"');
			}
			Some(joined)
		},
	}
}

fn present(
	renderer: &mut Renderer<TtyOut>,
	rendered: RenderedFrame<'_>,
	viewport: Size,
	layers: &[Layer<'_>],
) -> io::Result<()> {
	renderer
		.present_overlaid(
			rendered.frame,
			rendered.damage.as_slice(),
			viewport.height,
			rendered.stable_rows,
			layers,
		)
		.map(|_| ())
}

/// The session rail as a layer slice for this frame: empty when toggled
/// off or gated out by a small viewport, so callers composite it
/// unconditionally.
fn rail_layers(sidebar: &mut Sidebar, viewport: Size, elapsed: Duration) -> SmallVec<Layer<'_>, 2> {
	sidebar.layer(viewport, elapsed).into_iter().collect()
}

/// The modal scene overlay holding the alternate screen: at most one is
/// open at a time, and a palette action can swap it for the picker in
/// place — the hold transfers without leaving the alternate screen.
enum Overlay {
	Picker(ModelPicker),
	Palette(CommandPalette),
}

/// One routed overlay outcome, unified across overlay kinds.
enum OverlayEvent {
	/// Input handled; the overlay stays open.
	Consumed,
	/// Dismissed without effect.
	Close,
	/// The picker chose a model.
	Pick(usize),
	/// The palette activated an entry.
	Run(PaletteAction),
}

impl From<PickerEvent> for OverlayEvent {
	fn from(event: PickerEvent) -> Self {
		match event {
			PickerEvent::Consumed => Self::Consumed,
			PickerEvent::Close => Self::Close,
			PickerEvent::Pick(index) => Self::Pick(index),
		}
	}
}

impl From<PaletteEvent> for OverlayEvent {
	fn from(event: PaletteEvent) -> Self {
		match event {
			PaletteEvent::Consumed => Self::Consumed,
			PaletteEvent::Close => Self::Close,
			PaletteEvent::Run(action) => Self::Run(action),
		}
	}
}

impl Overlay {
	fn handle_key(&mut self, key: Key) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_key(key).into(),
			Self::Palette(palette) => palette.handle_key(key).into(),
		}
	}

	fn handle_paste(&mut self, text: &str) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_paste(text).into(),
			Self::Palette(palette) => palette.handle_paste(text).into(),
		}
	}

	fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_mouse(col, row, kind, viewport).into(),
			Self::Palette(palette) => palette.handle_mouse(col, row, kind, viewport).into(),
		}
	}

	fn layer(&mut self, viewport: Size) -> Layer<'_> {
		match self {
			Self::Picker(picker) => picker.layer(viewport),
			Self::Palette(palette) => palette.layer(viewport),
		}
	}
}

/// Takes the alternate screen for the overlay's lifetime: entry rides the
/// first composited paint, and a drag borrow already in flight simply
/// transfers ownership (its settled rebuild then waits for close).
#[expect(clippy::too_many_arguments, reason = "immediate-mode example threads its scene state")]
fn open_overlay(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	demo: &mut Demo,
	overlay: &mut Overlay,
	sidebar: &mut Sidebar,
	viewport: Size,
	elapsed: Duration,
	drag_alt: &mut bool,
	overlay_stale: &mut bool,
	resize: &mut Option<ResizeState>,
) -> io::Result<()> {
	if *drag_alt || resize.take().is_some() {
		*drag_alt = false;
		*overlay_stale = true;
	}
	let alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	let rendered = demo.render(viewport);
	let mut layers = rail_layers(sidebar, viewport, elapsed);
	layers.push(overlay.layer(viewport));
	renderer
		.preview_overlaid(
			rendered.frame,
			&layers,
			viewport.height,
			alt_enter.as_deref().unwrap_or(""),
		)
		.map(|_| ())
}

/// Releases the overlay's alternate-screen hold. Geometry churn while held
/// rebuilds native history inside the same synchronized update as the buffer
/// switch; otherwise the untouched main screen restores byte-exactly and one
/// full-viewport present revalidates changes that only ever painted the
/// alternate screen (streamed demo rows, the picked model).
#[expect(clippy::too_many_arguments, reason = "immediate-mode example threads its scene state")]
fn close_overlay(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	demo: &mut Demo,
	sidebar: &mut Sidebar,
	viewport: Size,
	elapsed: Duration,
	overlay_stale: &mut bool,
	resize: &mut Option<ResizeState>,
) -> io::Result<()> {
	*resize = None;
	let rendered = demo.render(viewport);
	let layers = rail_layers(sidebar, viewport, elapsed);
	if *overlay_stale {
		*overlay_stale = false;
		let alt_exit = terminal.stage_alt_leave().unwrap_or("");
		renderer.rebuild(rendered.frame.clone(), viewport.height, rendered.stable_rows, alt_exit)?;
		if !layers.is_empty() {
			// The rebuild repainted the raw document; recomposite the rail
			// without touching the fresh history.
			renderer.present_overlaid(
				rendered.frame,
				&[],
				viewport.height,
				rendered.stable_rows,
				&layers,
			)?;
		}
	} else {
		terminal.leave_alt()?;
		renderer.present_overlaid(
			rendered.frame,
			&[(0, rendered.frame.size().height)],
			viewport.height,
			rendered.stable_rows,
			&layers,
		)?;
	}
	Ok(())
}

pub fn present_damaged( &mut self, next: &Frame, damaged: &[(u16, u16)], viewport_height: u16, stable_rows: u16, ) -> Result<PaintStats>

Renderer::present_ref with a caller-supplied damage list: only rows inside damaged (start, end) ranges are validated and snapshotted. The caller guarantees every changed row is covered; the full grid is copied only on the initial paint.

Errors

Same contract as Renderer::present.

pub fn clear_layers(&mut self) -> Result<()>

Repaints every composited viewport-layer band from the raw document and drops the stored layers.

The final inline screen persists into native scrollback once the host exits and the shell resumes scrolling, so teardown must not leave layer cells composited — crate::App does this automatically, and manual hosts call it before dropping their crate::Terminal. Call it on the main screen (release any alternate-screen hold first); with no stored layers, or while the alternate screen is active, nothing is written.

Errors

Propagates writer failures, which poison the renderer.

Examples found in repository

examples/chat/main.rs (line 82)

async fn run<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	ctx: &'a UiContext,
) -> io::Result<()> {
	let result = chat(terminal, renderer, ctx).await;
	let scrub = terminal.leave_alt().and_then(|()| renderer.clear_layers());
	result.and(scrub)
}

pub fn preview( &mut self, next: &Frame, viewport_height: u16, leading_sequence: &str, ) -> Result<PaintStats>

Paints only the current raw document tail without changing committed state.

Resize handlers use this on an alternate buffer while normal-buffer history remains untouched. Stored overlay layers are deliberately ignored; leading_sequence is emitted inside the synchronized update, before the viewport paint. Overlays go through Renderer::preview_overlaid.

Errors

Rejects zero geometry. Writer failure poisons the renderer because its physical state is unknown.

Examples found in repository

examples/chat/main.rs (lines 481-485)

async fn run_welcome<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	charset: Charset,
	viewport: &'a mut Size,
) -> io::Result<bool> {
	let mut alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	let mut welcome = Welcome::new(charset);
	let started = Instant::now();
	let mut next_frame = Instant::now();
	loop {
		tokio::select! {
			event = terminal.next() => match event? {
				TerminalEvent::Resize => {
					if let Some(size) = terminal.take_resize()? {
						*viewport = size;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(false),
				TerminalEvent::Input(event) => {
					let Some(event) = user_event(terminal, renderer, event)? else {
						continue;
					};
					match event {
					InputEvent::Key(Key::Enter) => return Ok(true),
					InputEvent::Key(Key::Esc | Key::Ctrl('c')) => return Ok(false),
					InputEvent::Mouse(report) if matches!(report.kind, Mouse::Move | Mouse::Drag) => {
						welcome.point_at(report.col, report.row);
					},
					InputEvent::Key(_)
					| InputEvent::Mouse(_)
					| InputEvent::Paste(_)
					| InputEvent::Focus(_)
					| InputEvent::Response(_) => {},
				}
				},
			},
			() = deadline(Some(next_frame)) => {
				let now = Instant::now();
				if let Some(size) = terminal.take_resize()? {
					*viewport = size;
				}
				let frame = welcome.render(*viewport, started.elapsed());
				renderer.preview(
					frame,
					viewport.height,
					alt_enter.take().as_deref().unwrap_or(""),
				)?;
				next_frame = now + FRAME_INTERVAL;
			},
		}
	}
}

examples/footers.rs (line 120)

async fn run<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	charset: Charset,
) -> io::Result<()> {
	let started = Instant::now();
	let mut viewport = terminal.size()?;
	let mut scroll: u16 = 0;
	let mut alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	loop {
		tokio::select! {
			event = terminal.next() => match event? {
				TerminalEvent::Input(event) => {
					match event {
						InputEvent::Key(key) => match key {
							Key::Char('q') | Key::Esc | Key::Ctrl('c') => return Ok(()),
							Key::Up | Key::Char('k') => scroll = scroll.saturating_sub(1),
							Key::Down | Key::Char('j') => scroll = scroll.saturating_add(1),
							Key::PageUp => scroll = scroll.saturating_sub(viewport.height),
							Key::PageDown => scroll = scroll.saturating_add(viewport.height),
							Key::Home => scroll = 0,
							Key::End => scroll = u16::MAX,
							_ => {},
						},
						InputEvent::Mouse(report) => match report.kind {
							Mouse::WheelUp => scroll = scroll.saturating_sub(2),
							Mouse::WheelDown => scroll = scroll.saturating_add(2),
							_ => {},
						},
						InputEvent::Paste(_) | InputEvent::Focus(_) | InputEvent::Response(_) => {},
					}
					terminal.sync_renderer(renderer)?;
				},
				TerminalEvent::Resize => {
					if let Some(size) = terminal.take_resize()? {
						viewport = size;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(()),
			},
			() = tokio::time::sleep(FRAME_INTERVAL) => {},
		}
		if viewport.width == 0 || viewport.height == 0 {
			continue;
		}
		let scene = Scene { charset, width: viewport.width, elapsed: started.elapsed() };
		let document = compose(&scene);
		scroll = scroll.min(document.size().height.saturating_sub(viewport.height));
		let mut screen = Frame::new(viewport);
		screen.fill(Rect::new(0, 0, viewport.width, viewport.height), ink(TEXT));
		screen.blit(&document, scroll, viewport.height, 0, 0);
		renderer.preview(&screen, viewport.height, alt_enter.take().as_deref().unwrap_or(""))?;
	}
}

pub fn preview_overlaid( &mut self, next: &Frame, layers: &[Layer<'_>], viewport_height: u16, leading_sequence: &str, ) -> Result<PaintStats>

Renderer::preview with declarative viewport-anchored layers.

The document tail and every visible layer composite into one throwaway synchronized paint while committed history and stored layers stay untouched. Alternate-screen holders — fullscreen scenes and modal overlays — repaint with this on damage or geometry change; Renderer::present_overlaid is the normal-buffer counterpart.

Errors

Same contract as Renderer::preview.

Examples found in repository

examples/chat/main.rs (line 352)

async fn chat<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	ctx: &'a UiContext,
) -> io::Result<()> {
	let mut viewport = terminal.size()?;
	if !run_welcome(terminal, renderer, ctx.charset, &mut viewport).await? {
		return Ok(());
	}
	// The welcome scene held the alternate screen; releasing it restores the
	// untouched shell and the chat pushes inline from a clean slate.
	terminal.leave_alt()?;

	let mut demo = Demo::new(ctx);
	let mut overlay: Option<Overlay> = None;
	let mut current_model = 0_usize;
	let started = Instant::now();
	let mut sidebar = Sidebar::new(MODELS[current_model].name, ctx);
	demo.set_right_inset(sidebar.reserved(viewport));
	{
		let rendered = demo.render(viewport);
		let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
		present(renderer, rendered, viewport, &layers)?;
	}

	// Alternate-screen ownership for the chat scene: a resize gesture borrows
	// it for throwaway drag frames, an open overlay holds it for its lifetime.
	let mut drag_alt = false;
	let mut overlay_stale = false;
	let mut resize = None;
	// At most one in-flight background clipboard read (Ctrl+V/Ctrl+Shift+V).
	let mut paste_read: Option<PasteRead> = None;
	let mut next_frame = Instant::now() + FRAME_INTERVAL;
	loop {
		let paste_deadline = paste_read.as_ref().map(|read| read.abandon_at);
		tokio::select! {
			// The terminal branch pauses while a clipboard read is in flight:
			// the event mailbox buffers input in order, so an Enter typed
			// right after Ctrl+V lands *after* the paste instead of
			// submitting an empty prompt. The read below is bounded, so the
			// pause is too; retained App hosts get the finer-grained
			// per-event queue instead.
			event = terminal.next(), if paste_read.is_none() => match event? {
				TerminalEvent::Resize => {
					let now = Instant::now();
					let resized = observe_resize(terminal, &mut viewport, &mut resize, now)?;
					demo.set_right_inset(sidebar.reserved(viewport));
					if overlay.is_some() && resized {
						overlay_stale = true;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(()),
				TerminalEvent::Input(event) => {
					let Some(event) = user_event(terminal, renderer, event)? else {
						continue;
					};
					match event {
					InputEvent::Key(key) => {
						if overlay.is_some() {
							if key == Key::Ctrl('c') {
								break;
							}
							let event = overlay
								.as_mut()
								.expect("overlay checked above")
								.handle_key(key);
							if apply_overlay_event(
								event,
								&mut overlay,
								&mut current_model,
								terminal,
								renderer,
								&mut demo,
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut overlay_stale,
								&mut resize,
								ctx,
							)? {
								break;
							}
						} else if key == Key::Ctrl('b') {
							sidebar.toggle();
							demo.set_right_inset(sidebar.reserved(viewport));
						} else if key == Key::Ctrl('k') {
							overlay = Some(Overlay::Palette(CommandPalette::open(ctx)));
							open_overlay(
								terminal,
								renderer,
								&mut demo,
								overlay.as_mut().expect("palette just opened"),
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut drag_alt,
								&mut overlay_stale,
								&mut resize,
							)?;
						} else if sidebar.focused() {
							if key == Key::Ctrl('c') {
								break;
							}
							sidebar.handle_key(key);
						} else if key == Key::Ctrl('p') || key == Key::Alt('p') {
							overlay = Some(Overlay::Picker(ModelPicker::open(current_model, ctx)));
							open_overlay(
								terminal,
								renderer,
								&mut demo,
								overlay.as_mut().expect("picker just opened"),
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut drag_alt,
								&mut overlay_stale,
								&mut resize,
							)?;
						} else if let Some(scope) = ClipboardRead::for_key(key) {
							// The terminal did not claim the chord; read the
							// system clipboard off-thread, preferring images
							// unless the raw spelling asked for text only. A
							// failed spawn closes the channel, so the receive
							// branch below recovers input immediately.
							paste_read = Some(PasteRead::start(scope));
						} else {
							let quit = demo.handle_key(key);
							if demo.take_switch_request() {
								overlay = Some(Overlay::Picker(ModelPicker::open(current_model, ctx)));
								open_overlay(
									terminal,
									renderer,
									&mut demo,
									overlay.as_mut().expect("picker just opened"),
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut drag_alt,
									&mut overlay_stale,
									&mut resize,
								)?;
							}
							if quit {
								break;
							}
						}
						next_frame = Instant::now();
					},
					InputEvent::Paste(text) => {
						let event = overlay.as_mut().map(|active| active.handle_paste(&text));
						match event {
							Some(event) => {
								if apply_overlay_event(
									event,
									&mut overlay,
									&mut current_model,
									terminal,
									renderer,
									&mut demo,
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut overlay_stale,
									&mut resize,
									ctx,
								)? {
									break;
								}
							},
							None if sidebar.focused() => {},
							None => demo.handle_paste(&text),
						}
						next_frame = Instant::now();
					},
					InputEvent::Mouse(report) => {
						// An open overlay owns pointer input — hover, wheel,
						// and clicks route through the compositor's band,
						// never the occluded editor beneath.
						let event = overlay
							.as_mut()
							.map(|active| active.handle_mouse(report.col, report.row, report.kind, viewport));
						match event {
							Some(event) => {
								if apply_overlay_event(
									event,
									&mut overlay,
									&mut current_model,
									terminal,
									renderer,
									&mut demo,
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut overlay_stale,
									&mut resize,
									ctx,
								)? {
									break;
								}
							},
							None => {
								if !sidebar.handle_mouse(report.col, report.row, report.kind, viewport)
								{
									demo.handle_mouse(&report);
								}
							},
						}
						next_frame = Instant::now();
					},
					InputEvent::Focus(_) | InputEvent::Response(_) => {},
				}
				},
			},
			clipboard = async { (&mut paste_read.as_mut().expect("branch gated on Some").clipboard).await },
				if paste_read.is_some() =>
			{
				let read = paste_read.take().expect("branch gated on Some");
				// A closed channel (the reader thread never spawned) reads
				// as an empty clipboard.
				if let Ok(Some(clipboard)) = clipboard
					&& let Some(text) = clipboard_paste_text(clipboard)
					&& overlay.is_none()
					&& !sidebar.focused()
				{
					// Ctrl+Shift+V inserts verbatim: no attachment staging,
					// no large-paste collapse.
					match read.scope {
						ClipboardRead::Text => demo.handle_paste_raw(&text),
						ClipboardRead::Smart => demo.handle_paste(&text),
					}
					next_frame = Instant::now();
				}
			},
			// The deadline is absolute, so the frame tick recreating this
			// branch's future cannot reset it: a hung reader is abandoned and
			// terminal input re-enables. Dropping the receiver makes the
			// reader's eventual send fail; the detached thread dies with the
			// process instead of stalling shutdown.
			() = deadline(paste_deadline) => {
				paste_read = None;
			},
			() = deadline(Some(next_frame)) => {
				let now = Instant::now();
				let resized = observe_resize(terminal, &mut viewport, &mut resize, now)?;
				demo.set_right_inset(sidebar.reserved(viewport));
				if overlay.is_some() && resized {
					overlay_stale = true;
				}
				if resize.is_some() {
					// Drag frames compose exactly one viewport tail at the
					// new geometry — O(viewport) per frame; the O(history)
					// transcript reflow waits for the settle rebuild (or the
					// overlay close). Without an overlay, a width change
					// borrows the alternate screen (the inline transcript
					// rewraps underneath) while height-only churn repaints
					// in place — alt toggling on a height echo can
					// self-sustain.
					let preview = demo.render_resize_preview(viewport);
					if let Some(active) = overlay.as_mut() {
								  let mut layers = rail_layers(&mut sidebar, viewport, started.elapsed());
								  layers.push(active.layer(viewport));
								  renderer.preview_overlaid(&preview, &layers, viewport.height, "")?;
							  } else {
								  let width_changed =
									  resize.is_some_and(|state| state.width_changed);
								  let alt_enter = if drag_alt || !width_changed {
									  None
								  } else {
									  let staged = terminal.stage_alt_enter(AltScreenUse::Resize);
									  drag_alt = staged.is_some();
									  staged
								  };
								  let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
								  renderer.preview_overlaid(
									  &preview,
									  &layers,
									  viewport.height,
									  alt_enter.as_deref().unwrap_or(""),
								  )?;
							  }
				} else if let Some(active) = overlay.as_mut() {
					let rendered = demo.render(viewport);
					let mut layers = rail_layers(&mut sidebar, viewport, started.elapsed());
					layers.push(active.layer(viewport));
					renderer.preview_overlaid(rendered.frame, &layers, viewport.height, "")?;
				} else {
					let rendered = demo.render(viewport);
					let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
					present(renderer, rendered, viewport, &layers)?;
				}
				next_frame = now + FRAME_INTERVAL;
			},
			() = deadline(resize.map(ResizeState::deadline)) => {
				let now = Instant::now();
				if !resize.is_some_and(|state| state.settled(now)) {
					continue;
				}
				if overlay.is_some() {
					// The overlay keeps holding the alternate screen; the
					// transcript reflows once at close.
					overlay_stale = true;
					resize = None;
					continue;
				}
				demo.set_right_inset(sidebar.reserved(viewport));
				let rendered = demo.render(viewport);
				let alt_exit = if drag_alt {
					drag_alt = false;
					terminal.stage_alt_leave().unwrap_or("")
				} else {
					""
				};
				renderer.rebuild(
					rendered.frame.clone(),
					viewport.height,
					rendered.stable_rows,
					alt_exit,
				)?;
				// The rebuild repainted the raw document; recomposite the
				// rail on top without touching the fresh history.
				let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
				if !layers.is_empty() {
					renderer.present_overlaid(
						rendered.frame,
						&[],
						viewport.height,
						rendered.stable_rows,
						&layers,
					)?;
				}
				resize = None;
				next_frame = now + FRAME_INTERVAL;
			},
		}
	}
	Ok(())
}

/// Animates the welcome card until the user resumes into the chat demo
/// (`Ok(true)`) or quits (`Ok(false)`), keeping `viewport` current across
/// resizes.
///
/// The scene owns the alternate screen for its whole lifetime: entry rides
/// the first card paint, mouse tracking is active throughout, and every
/// geometry change repaints in place immediately. The main screen stays
/// untouched underneath — the caller releases the hold on scene exit.
async fn run_welcome<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	charset: Charset,
	viewport: &'a mut Size,
) -> io::Result<bool> {
	let mut alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	let mut welcome = Welcome::new(charset);
	let started = Instant::now();
	let mut next_frame = Instant::now();
	loop {
		tokio::select! {
			event = terminal.next() => match event? {
				TerminalEvent::Resize => {
					if let Some(size) = terminal.take_resize()? {
						*viewport = size;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(false),
				TerminalEvent::Input(event) => {
					let Some(event) = user_event(terminal, renderer, event)? else {
						continue;
					};
					match event {
					InputEvent::Key(Key::Enter) => return Ok(true),
					InputEvent::Key(Key::Esc | Key::Ctrl('c')) => return Ok(false),
					InputEvent::Mouse(report) if matches!(report.kind, Mouse::Move | Mouse::Drag) => {
						welcome.point_at(report.col, report.row);
					},
					InputEvent::Key(_)
					| InputEvent::Mouse(_)
					| InputEvent::Paste(_)
					| InputEvent::Focus(_)
					| InputEvent::Response(_) => {},
				}
				},
			},
			() = deadline(Some(next_frame)) => {
				let now = Instant::now();
				if let Some(size) = terminal.take_resize()? {
					*viewport = size;
				}
				let frame = welcome.render(*viewport, started.elapsed());
				renderer.preview(
					frame,
					viewport.height,
					alt_enter.take().as_deref().unwrap_or(""),
				)?;
				next_frame = now + FRAME_INTERVAL;
			},
		}
	}
}

#[derive(Clone, Copy)]
struct ResizeState {
	last_event:    Instant,
	/// Whether any report in this gesture changed the width; only then does
	/// the drag borrow the alternate screen.
	width_changed: bool,
}

impl ResizeState {
	const fn new(last_event: Instant, width_changed: bool) -> Self {
		Self { last_event, width_changed }
	}

	const fn observe(&mut self, observed_at: Instant, width_changed: bool) {
		self.last_event = observed_at;
		self.width_changed |= width_changed;
	}

	fn deadline(self) -> Instant {
		self.last_event + RESIZE_SETTLE
	}

	fn settled(self, now: Instant) -> bool {
		now >= self.deadline()
	}
}

/// Consumes the latest resize — SIGWINCH or DEC 2048 in-band — and (re)arms
/// the settle window. Same-size reports outside a gesture are echoes
/// (terminals re-reporting geometry across alternate-screen toggles) and are
/// swallowed without arming a rebuild.
fn observe_resize(
	terminal: &mut Terminal,
	viewport: &mut Size,
	resize: &mut Option<ResizeState>,
	observed_at: Instant,
) -> io::Result<bool> {
	let Some(size) = terminal.take_resize()? else {
		return Ok(false);
	};
	if size == *viewport && resize.is_none() {
		return Ok(false);
	}
	let width_changed = size.width != viewport.width;
	*viewport = size;
	match resize {
		Some(state) => state.observe(observed_at, width_changed),
		None => *resize = Some(ResizeState::new(observed_at, width_changed)),
	}
	Ok(true)
}

fn user_event(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	event: InputEvent,
) -> io::Result<Option<InputEvent>> {
	if terminal.handle_input_event(&event, renderer)? {
		// A consumed response may have completed an enhanced-paste (OSC
		// 5522) conversation; re-inject its payload as ordinary paste input
		// so the normal routing below stages images and text alike.
		return Ok(terminal.take_paste().and_then(|pasted| {
			let text = match pasted {
				Pasted::Text(text) => text,
				Pasted::Image(image) => image.persist().ok()?.display().to_string().into(),
			};
			Some(InputEvent::Paste(text))
		}));
	}
	Ok(Some(event))
}

/// Flattens a background clipboard read into paste text: images persist to
/// a temp file whose path routes like a file drop, and copied file paths
/// are quoted so spaces survive drop classification.
fn clipboard_paste_text(clipboard: Clipboard) -> Option<String> {
	match clipboard {
		Clipboard::Text(text) => Some(text),
		Clipboard::Image(image) => Some(image.persist().ok()?.display().to_string()),
		Clipboard::Paths(paths) => {
			let mut joined = String::new();
			for path in &paths {
				if !joined.is_empty() {
					joined.push(' ');
				}
				joined.push('"');
				joined.push_str(path);
				joined.push('"');
			}
			Some(joined)
		},
	}
}

fn present(
	renderer: &mut Renderer<TtyOut>,
	rendered: RenderedFrame<'_>,
	viewport: Size,
	layers: &[Layer<'_>],
) -> io::Result<()> {
	renderer
		.present_overlaid(
			rendered.frame,
			rendered.damage.as_slice(),
			viewport.height,
			rendered.stable_rows,
			layers,
		)
		.map(|_| ())
}

/// The session rail as a layer slice for this frame: empty when toggled
/// off or gated out by a small viewport, so callers composite it
/// unconditionally.
fn rail_layers(sidebar: &mut Sidebar, viewport: Size, elapsed: Duration) -> SmallVec<Layer<'_>, 2> {
	sidebar.layer(viewport, elapsed).into_iter().collect()
}

/// The modal scene overlay holding the alternate screen: at most one is
/// open at a time, and a palette action can swap it for the picker in
/// place — the hold transfers without leaving the alternate screen.
enum Overlay {
	Picker(ModelPicker),
	Palette(CommandPalette),
}

/// One routed overlay outcome, unified across overlay kinds.
enum OverlayEvent {
	/// Input handled; the overlay stays open.
	Consumed,
	/// Dismissed without effect.
	Close,
	/// The picker chose a model.
	Pick(usize),
	/// The palette activated an entry.
	Run(PaletteAction),
}

impl From<PickerEvent> for OverlayEvent {
	fn from(event: PickerEvent) -> Self {
		match event {
			PickerEvent::Consumed => Self::Consumed,
			PickerEvent::Close => Self::Close,
			PickerEvent::Pick(index) => Self::Pick(index),
		}
	}
}

impl From<PaletteEvent> for OverlayEvent {
	fn from(event: PaletteEvent) -> Self {
		match event {
			PaletteEvent::Consumed => Self::Consumed,
			PaletteEvent::Close => Self::Close,
			PaletteEvent::Run(action) => Self::Run(action),
		}
	}
}

impl Overlay {
	fn handle_key(&mut self, key: Key) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_key(key).into(),
			Self::Palette(palette) => palette.handle_key(key).into(),
		}
	}

	fn handle_paste(&mut self, text: &str) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_paste(text).into(),
			Self::Palette(palette) => palette.handle_paste(text).into(),
		}
	}

	fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_mouse(col, row, kind, viewport).into(),
			Self::Palette(palette) => palette.handle_mouse(col, row, kind, viewport).into(),
		}
	}

	fn layer(&mut self, viewport: Size) -> Layer<'_> {
		match self {
			Self::Picker(picker) => picker.layer(viewport),
			Self::Palette(palette) => palette.layer(viewport),
		}
	}
}

/// Takes the alternate screen for the overlay's lifetime: entry rides the
/// first composited paint, and a drag borrow already in flight simply
/// transfers ownership (its settled rebuild then waits for close).
#[expect(clippy::too_many_arguments, reason = "immediate-mode example threads its scene state")]
fn open_overlay(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	demo: &mut Demo,
	overlay: &mut Overlay,
	sidebar: &mut Sidebar,
	viewport: Size,
	elapsed: Duration,
	drag_alt: &mut bool,
	overlay_stale: &mut bool,
	resize: &mut Option<ResizeState>,
) -> io::Result<()> {
	if *drag_alt || resize.take().is_some() {
		*drag_alt = false;
		*overlay_stale = true;
	}
	let alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	let rendered = demo.render(viewport);
	let mut layers = rail_layers(sidebar, viewport, elapsed);
	layers.push(overlay.layer(viewport));
	renderer
		.preview_overlaid(
			rendered.frame,
			&layers,
			viewport.height,
			alt_enter.as_deref().unwrap_or(""),
		)
		.map(|_| ())
}

pub fn rebuild( &mut self, next: Frame, viewport_height: u16, stable_rows: u16, leading_sequence: &str, ) -> Result<PaintStats>

Clears and reconstructs native history at new terminal geometry.

The synchronized update emits leading_sequence, clears scrollback once, then writes the stable prefix and current viewport. The reconstructed frame becomes the baseline for subsequent Self::present calls.

Errors

Rejects zero geometry or a stable boundary beyond the document. Writer failure poisons the renderer because history may be partially rebuilt.

Examples found in repository

examples/chat/main.rs (lines 403-408)

async fn chat<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	ctx: &'a UiContext,
) -> io::Result<()> {
	let mut viewport = terminal.size()?;
	if !run_welcome(terminal, renderer, ctx.charset, &mut viewport).await? {
		return Ok(());
	}
	// The welcome scene held the alternate screen; releasing it restores the
	// untouched shell and the chat pushes inline from a clean slate.
	terminal.leave_alt()?;

	let mut demo = Demo::new(ctx);
	let mut overlay: Option<Overlay> = None;
	let mut current_model = 0_usize;
	let started = Instant::now();
	let mut sidebar = Sidebar::new(MODELS[current_model].name, ctx);
	demo.set_right_inset(sidebar.reserved(viewport));
	{
		let rendered = demo.render(viewport);
		let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
		present(renderer, rendered, viewport, &layers)?;
	}

	// Alternate-screen ownership for the chat scene: a resize gesture borrows
	// it for throwaway drag frames, an open overlay holds it for its lifetime.
	let mut drag_alt = false;
	let mut overlay_stale = false;
	let mut resize = None;
	// At most one in-flight background clipboard read (Ctrl+V/Ctrl+Shift+V).
	let mut paste_read: Option<PasteRead> = None;
	let mut next_frame = Instant::now() + FRAME_INTERVAL;
	loop {
		let paste_deadline = paste_read.as_ref().map(|read| read.abandon_at);
		tokio::select! {
			// The terminal branch pauses while a clipboard read is in flight:
			// the event mailbox buffers input in order, so an Enter typed
			// right after Ctrl+V lands *after* the paste instead of
			// submitting an empty prompt. The read below is bounded, so the
			// pause is too; retained App hosts get the finer-grained
			// per-event queue instead.
			event = terminal.next(), if paste_read.is_none() => match event? {
				TerminalEvent::Resize => {
					let now = Instant::now();
					let resized = observe_resize(terminal, &mut viewport, &mut resize, now)?;
					demo.set_right_inset(sidebar.reserved(viewport));
					if overlay.is_some() && resized {
						overlay_stale = true;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(()),
				TerminalEvent::Input(event) => {
					let Some(event) = user_event(terminal, renderer, event)? else {
						continue;
					};
					match event {
					InputEvent::Key(key) => {
						if overlay.is_some() {
							if key == Key::Ctrl('c') {
								break;
							}
							let event = overlay
								.as_mut()
								.expect("overlay checked above")
								.handle_key(key);
							if apply_overlay_event(
								event,
								&mut overlay,
								&mut current_model,
								terminal,
								renderer,
								&mut demo,
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut overlay_stale,
								&mut resize,
								ctx,
							)? {
								break;
							}
						} else if key == Key::Ctrl('b') {
							sidebar.toggle();
							demo.set_right_inset(sidebar.reserved(viewport));
						} else if key == Key::Ctrl('k') {
							overlay = Some(Overlay::Palette(CommandPalette::open(ctx)));
							open_overlay(
								terminal,
								renderer,
								&mut demo,
								overlay.as_mut().expect("palette just opened"),
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut drag_alt,
								&mut overlay_stale,
								&mut resize,
							)?;
						} else if sidebar.focused() {
							if key == Key::Ctrl('c') {
								break;
							}
							sidebar.handle_key(key);
						} else if key == Key::Ctrl('p') || key == Key::Alt('p') {
							overlay = Some(Overlay::Picker(ModelPicker::open(current_model, ctx)));
							open_overlay(
								terminal,
								renderer,
								&mut demo,
								overlay.as_mut().expect("picker just opened"),
								&mut sidebar,
								viewport,
								started.elapsed(),
								&mut drag_alt,
								&mut overlay_stale,
								&mut resize,
							)?;
						} else if let Some(scope) = ClipboardRead::for_key(key) {
							// The terminal did not claim the chord; read the
							// system clipboard off-thread, preferring images
							// unless the raw spelling asked for text only. A
							// failed spawn closes the channel, so the receive
							// branch below recovers input immediately.
							paste_read = Some(PasteRead::start(scope));
						} else {
							let quit = demo.handle_key(key);
							if demo.take_switch_request() {
								overlay = Some(Overlay::Picker(ModelPicker::open(current_model, ctx)));
								open_overlay(
									terminal,
									renderer,
									&mut demo,
									overlay.as_mut().expect("picker just opened"),
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut drag_alt,
									&mut overlay_stale,
									&mut resize,
								)?;
							}
							if quit {
								break;
							}
						}
						next_frame = Instant::now();
					},
					InputEvent::Paste(text) => {
						let event = overlay.as_mut().map(|active| active.handle_paste(&text));
						match event {
							Some(event) => {
								if apply_overlay_event(
									event,
									&mut overlay,
									&mut current_model,
									terminal,
									renderer,
									&mut demo,
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut overlay_stale,
									&mut resize,
									ctx,
								)? {
									break;
								}
							},
							None if sidebar.focused() => {},
							None => demo.handle_paste(&text),
						}
						next_frame = Instant::now();
					},
					InputEvent::Mouse(report) => {
						// An open overlay owns pointer input — hover, wheel,
						// and clicks route through the compositor's band,
						// never the occluded editor beneath.
						let event = overlay
							.as_mut()
							.map(|active| active.handle_mouse(report.col, report.row, report.kind, viewport));
						match event {
							Some(event) => {
								if apply_overlay_event(
									event,
									&mut overlay,
									&mut current_model,
									terminal,
									renderer,
									&mut demo,
									&mut sidebar,
									viewport,
									started.elapsed(),
									&mut overlay_stale,
									&mut resize,
									ctx,
								)? {
									break;
								}
							},
							None => {
								if !sidebar.handle_mouse(report.col, report.row, report.kind, viewport)
								{
									demo.handle_mouse(&report);
								}
							},
						}
						next_frame = Instant::now();
					},
					InputEvent::Focus(_) | InputEvent::Response(_) => {},
				}
				},
			},
			clipboard = async { (&mut paste_read.as_mut().expect("branch gated on Some").clipboard).await },
				if paste_read.is_some() =>
			{
				let read = paste_read.take().expect("branch gated on Some");
				// A closed channel (the reader thread never spawned) reads
				// as an empty clipboard.
				if let Ok(Some(clipboard)) = clipboard
					&& let Some(text) = clipboard_paste_text(clipboard)
					&& overlay.is_none()
					&& !sidebar.focused()
				{
					// Ctrl+Shift+V inserts verbatim: no attachment staging,
					// no large-paste collapse.
					match read.scope {
						ClipboardRead::Text => demo.handle_paste_raw(&text),
						ClipboardRead::Smart => demo.handle_paste(&text),
					}
					next_frame = Instant::now();
				}
			},
			// The deadline is absolute, so the frame tick recreating this
			// branch's future cannot reset it: a hung reader is abandoned and
			// terminal input re-enables. Dropping the receiver makes the
			// reader's eventual send fail; the detached thread dies with the
			// process instead of stalling shutdown.
			() = deadline(paste_deadline) => {
				paste_read = None;
			},
			() = deadline(Some(next_frame)) => {
				let now = Instant::now();
				let resized = observe_resize(terminal, &mut viewport, &mut resize, now)?;
				demo.set_right_inset(sidebar.reserved(viewport));
				if overlay.is_some() && resized {
					overlay_stale = true;
				}
				if resize.is_some() {
					// Drag frames compose exactly one viewport tail at the
					// new geometry — O(viewport) per frame; the O(history)
					// transcript reflow waits for the settle rebuild (or the
					// overlay close). Without an overlay, a width change
					// borrows the alternate screen (the inline transcript
					// rewraps underneath) while height-only churn repaints
					// in place — alt toggling on a height echo can
					// self-sustain.
					let preview = demo.render_resize_preview(viewport);
					if let Some(active) = overlay.as_mut() {
								  let mut layers = rail_layers(&mut sidebar, viewport, started.elapsed());
								  layers.push(active.layer(viewport));
								  renderer.preview_overlaid(&preview, &layers, viewport.height, "")?;
							  } else {
								  let width_changed =
									  resize.is_some_and(|state| state.width_changed);
								  let alt_enter = if drag_alt || !width_changed {
									  None
								  } else {
									  let staged = terminal.stage_alt_enter(AltScreenUse::Resize);
									  drag_alt = staged.is_some();
									  staged
								  };
								  let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
								  renderer.preview_overlaid(
									  &preview,
									  &layers,
									  viewport.height,
									  alt_enter.as_deref().unwrap_or(""),
								  )?;
							  }
				} else if let Some(active) = overlay.as_mut() {
					let rendered = demo.render(viewport);
					let mut layers = rail_layers(&mut sidebar, viewport, started.elapsed());
					layers.push(active.layer(viewport));
					renderer.preview_overlaid(rendered.frame, &layers, viewport.height, "")?;
				} else {
					let rendered = demo.render(viewport);
					let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
					present(renderer, rendered, viewport, &layers)?;
				}
				next_frame = now + FRAME_INTERVAL;
			},
			() = deadline(resize.map(ResizeState::deadline)) => {
				let now = Instant::now();
				if !resize.is_some_and(|state| state.settled(now)) {
					continue;
				}
				if overlay.is_some() {
					// The overlay keeps holding the alternate screen; the
					// transcript reflows once at close.
					overlay_stale = true;
					resize = None;
					continue;
				}
				demo.set_right_inset(sidebar.reserved(viewport));
				let rendered = demo.render(viewport);
				let alt_exit = if drag_alt {
					drag_alt = false;
					terminal.stage_alt_leave().unwrap_or("")
				} else {
					""
				};
				renderer.rebuild(
					rendered.frame.clone(),
					viewport.height,
					rendered.stable_rows,
					alt_exit,
				)?;
				// The rebuild repainted the raw document; recomposite the
				// rail on top without touching the fresh history.
				let layers = rail_layers(&mut sidebar, viewport, started.elapsed());
				if !layers.is_empty() {
					renderer.present_overlaid(
						rendered.frame,
						&[],
						viewport.height,
						rendered.stable_rows,
						&layers,
					)?;
				}
				resize = None;
				next_frame = now + FRAME_INTERVAL;
			},
		}
	}
	Ok(())
}

/// Animates the welcome card until the user resumes into the chat demo
/// (`Ok(true)`) or quits (`Ok(false)`), keeping `viewport` current across
/// resizes.
///
/// The scene owns the alternate screen for its whole lifetime: entry rides
/// the first card paint, mouse tracking is active throughout, and every
/// geometry change repaints in place immediately. The main screen stays
/// untouched underneath — the caller releases the hold on scene exit.
async fn run_welcome<'a>(
	terminal: &'a mut Terminal,
	renderer: &'a mut Renderer<TtyOut>,
	charset: Charset,
	viewport: &'a mut Size,
) -> io::Result<bool> {
	let mut alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	let mut welcome = Welcome::new(charset);
	let started = Instant::now();
	let mut next_frame = Instant::now();
	loop {
		tokio::select! {
			event = terminal.next() => match event? {
				TerminalEvent::Resize => {
					if let Some(size) = terminal.take_resize()? {
						*viewport = size;
					}
				},
				TerminalEvent::Debug(_) => {},
				TerminalEvent::Closed => return Ok(false),
				TerminalEvent::Input(event) => {
					let Some(event) = user_event(terminal, renderer, event)? else {
						continue;
					};
					match event {
					InputEvent::Key(Key::Enter) => return Ok(true),
					InputEvent::Key(Key::Esc | Key::Ctrl('c')) => return Ok(false),
					InputEvent::Mouse(report) if matches!(report.kind, Mouse::Move | Mouse::Drag) => {
						welcome.point_at(report.col, report.row);
					},
					InputEvent::Key(_)
					| InputEvent::Mouse(_)
					| InputEvent::Paste(_)
					| InputEvent::Focus(_)
					| InputEvent::Response(_) => {},
				}
				},
			},
			() = deadline(Some(next_frame)) => {
				let now = Instant::now();
				if let Some(size) = terminal.take_resize()? {
					*viewport = size;
				}
				let frame = welcome.render(*viewport, started.elapsed());
				renderer.preview(
					frame,
					viewport.height,
					alt_enter.take().as_deref().unwrap_or(""),
				)?;
				next_frame = now + FRAME_INTERVAL;
			},
		}
	}
}

#[derive(Clone, Copy)]
struct ResizeState {
	last_event:    Instant,
	/// Whether any report in this gesture changed the width; only then does
	/// the drag borrow the alternate screen.
	width_changed: bool,
}

impl ResizeState {
	const fn new(last_event: Instant, width_changed: bool) -> Self {
		Self { last_event, width_changed }
	}

	const fn observe(&mut self, observed_at: Instant, width_changed: bool) {
		self.last_event = observed_at;
		self.width_changed |= width_changed;
	}

	fn deadline(self) -> Instant {
		self.last_event + RESIZE_SETTLE
	}

	fn settled(self, now: Instant) -> bool {
		now >= self.deadline()
	}
}

/// Consumes the latest resize — SIGWINCH or DEC 2048 in-band — and (re)arms
/// the settle window. Same-size reports outside a gesture are echoes
/// (terminals re-reporting geometry across alternate-screen toggles) and are
/// swallowed without arming a rebuild.
fn observe_resize(
	terminal: &mut Terminal,
	viewport: &mut Size,
	resize: &mut Option<ResizeState>,
	observed_at: Instant,
) -> io::Result<bool> {
	let Some(size) = terminal.take_resize()? else {
		return Ok(false);
	};
	if size == *viewport && resize.is_none() {
		return Ok(false);
	}
	let width_changed = size.width != viewport.width;
	*viewport = size;
	match resize {
		Some(state) => state.observe(observed_at, width_changed),
		None => *resize = Some(ResizeState::new(observed_at, width_changed)),
	}
	Ok(true)
}

fn user_event(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	event: InputEvent,
) -> io::Result<Option<InputEvent>> {
	if terminal.handle_input_event(&event, renderer)? {
		// A consumed response may have completed an enhanced-paste (OSC
		// 5522) conversation; re-inject its payload as ordinary paste input
		// so the normal routing below stages images and text alike.
		return Ok(terminal.take_paste().and_then(|pasted| {
			let text = match pasted {
				Pasted::Text(text) => text,
				Pasted::Image(image) => image.persist().ok()?.display().to_string().into(),
			};
			Some(InputEvent::Paste(text))
		}));
	}
	Ok(Some(event))
}

/// Flattens a background clipboard read into paste text: images persist to
/// a temp file whose path routes like a file drop, and copied file paths
/// are quoted so spaces survive drop classification.
fn clipboard_paste_text(clipboard: Clipboard) -> Option<String> {
	match clipboard {
		Clipboard::Text(text) => Some(text),
		Clipboard::Image(image) => Some(image.persist().ok()?.display().to_string()),
		Clipboard::Paths(paths) => {
			let mut joined = String::new();
			for path in &paths {
				if !joined.is_empty() {
					joined.push(' ');
				}
				joined.push('"');
				joined.push_str(path);
				joined.push('"');
			}
			Some(joined)
		},
	}
}

fn present(
	renderer: &mut Renderer<TtyOut>,
	rendered: RenderedFrame<'_>,
	viewport: Size,
	layers: &[Layer<'_>],
) -> io::Result<()> {
	renderer
		.present_overlaid(
			rendered.frame,
			rendered.damage.as_slice(),
			viewport.height,
			rendered.stable_rows,
			layers,
		)
		.map(|_| ())
}

/// The session rail as a layer slice for this frame: empty when toggled
/// off or gated out by a small viewport, so callers composite it
/// unconditionally.
fn rail_layers(sidebar: &mut Sidebar, viewport: Size, elapsed: Duration) -> SmallVec<Layer<'_>, 2> {
	sidebar.layer(viewport, elapsed).into_iter().collect()
}

/// The modal scene overlay holding the alternate screen: at most one is
/// open at a time, and a palette action can swap it for the picker in
/// place — the hold transfers without leaving the alternate screen.
enum Overlay {
	Picker(ModelPicker),
	Palette(CommandPalette),
}

/// One routed overlay outcome, unified across overlay kinds.
enum OverlayEvent {
	/// Input handled; the overlay stays open.
	Consumed,
	/// Dismissed without effect.
	Close,
	/// The picker chose a model.
	Pick(usize),
	/// The palette activated an entry.
	Run(PaletteAction),
}

impl From<PickerEvent> for OverlayEvent {
	fn from(event: PickerEvent) -> Self {
		match event {
			PickerEvent::Consumed => Self::Consumed,
			PickerEvent::Close => Self::Close,
			PickerEvent::Pick(index) => Self::Pick(index),
		}
	}
}

impl From<PaletteEvent> for OverlayEvent {
	fn from(event: PaletteEvent) -> Self {
		match event {
			PaletteEvent::Consumed => Self::Consumed,
			PaletteEvent::Close => Self::Close,
			PaletteEvent::Run(action) => Self::Run(action),
		}
	}
}

impl Overlay {
	fn handle_key(&mut self, key: Key) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_key(key).into(),
			Self::Palette(palette) => palette.handle_key(key).into(),
		}
	}

	fn handle_paste(&mut self, text: &str) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_paste(text).into(),
			Self::Palette(palette) => palette.handle_paste(text).into(),
		}
	}

	fn handle_mouse(&mut self, col: u16, row: u16, kind: Mouse, viewport: Size) -> OverlayEvent {
		match self {
			Self::Picker(picker) => picker.handle_mouse(col, row, kind, viewport).into(),
			Self::Palette(palette) => palette.handle_mouse(col, row, kind, viewport).into(),
		}
	}

	fn layer(&mut self, viewport: Size) -> Layer<'_> {
		match self {
			Self::Picker(picker) => picker.layer(viewport),
			Self::Palette(palette) => palette.layer(viewport),
		}
	}
}

/// Takes the alternate screen for the overlay's lifetime: entry rides the
/// first composited paint, and a drag borrow already in flight simply
/// transfers ownership (its settled rebuild then waits for close).
#[expect(clippy::too_many_arguments, reason = "immediate-mode example threads its scene state")]
fn open_overlay(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	demo: &mut Demo,
	overlay: &mut Overlay,
	sidebar: &mut Sidebar,
	viewport: Size,
	elapsed: Duration,
	drag_alt: &mut bool,
	overlay_stale: &mut bool,
	resize: &mut Option<ResizeState>,
) -> io::Result<()> {
	if *drag_alt || resize.take().is_some() {
		*drag_alt = false;
		*overlay_stale = true;
	}
	let alt_enter = terminal.stage_alt_enter(AltScreenUse::Interactive);
	let rendered = demo.render(viewport);
	let mut layers = rail_layers(sidebar, viewport, elapsed);
	layers.push(overlay.layer(viewport));
	renderer
		.preview_overlaid(
			rendered.frame,
			&layers,
			viewport.height,
			alt_enter.as_deref().unwrap_or(""),
		)
		.map(|_| ())
}

/// Releases the overlay's alternate-screen hold. Geometry churn while held
/// rebuilds native history inside the same synchronized update as the buffer
/// switch; otherwise the untouched main screen restores byte-exactly and one
/// full-viewport present revalidates changes that only ever painted the
/// alternate screen (streamed demo rows, the picked model).
#[expect(clippy::too_many_arguments, reason = "immediate-mode example threads its scene state")]
fn close_overlay(
	terminal: &mut Terminal,
	renderer: &mut Renderer<TtyOut>,
	demo: &mut Demo,
	sidebar: &mut Sidebar,
	viewport: Size,
	elapsed: Duration,
	overlay_stale: &mut bool,
	resize: &mut Option<ResizeState>,
) -> io::Result<()> {
	*resize = None;
	let rendered = demo.render(viewport);
	let layers = rail_layers(sidebar, viewport, elapsed);
	if *overlay_stale {
		*overlay_stale = false;
		let alt_exit = terminal.stage_alt_leave().unwrap_or("");
		renderer.rebuild(rendered.frame.clone(), viewport.height, rendered.stable_rows, alt_exit)?;
		if !layers.is_empty() {
			// The rebuild repainted the raw document; recomposite the rail
			// without touching the fresh history.
			renderer.present_overlaid(
				rendered.frame,
				&[],
				viewport.height,
				rendered.stable_rows,
				&layers,
			)?;
		}
	} else {
		terminal.leave_alt()?;
		renderer.present_overlaid(
			rendered.frame,
			&[(0, rendered.frame.size().height)],
			viewport.height,
			rendered.stable_rows,
			&layers,
		)?;
	}
	Ok(())
}

pub const fn committed_rows(&self) -> u16

Returns the number of finalized rows physically stored above the viewport.

pub const fn window_top(&self) -> u16

Returns the document row currently shown at the viewport top.

pub fn screen_text(&self) -> Vec<String>

Renders the retained physical screen model — the committed frame composed with its stored viewport layers — as visible text, one right-trimmed string per viewport row.

This is what the terminal currently shows, driving the OMP_TUI_DEBUG text op. Empty before the first present or rebuild.

pub const fn screen_cursor(&self) -> Option<(u16, u16)>

Screen coordinates (row, column) of the visible hardware cursor, when one was placed by the last present.

pub const fn output_state(&self) -> OutputState

Returns whether terminal output is connected or was abandoned after its unflushed backlog crossed the safety limit.

pub const fn writer_mut(&mut self) -> &mut W

Borrows the output writer for terminal session teardown.

pub fn into_inner(self) -> W

Returns the output writer after the renderer is no longer needed.