Struct Terminal 

pub struct Terminal { /* private fields */ }

Owns raw mode and every terminal mode enabled for an interactive session.

Only one Terminal may be active in a process. Normal teardown is idempotent, and panic plus fatal-signal handlers perform an allocation-free blind restore when ordinary unwinding cannot run.

Implementations

impl Terminal

pub fn enter(options: TerminalOptions) -> Result<Self>

Takes ownership of the controlling terminal and emits one capability-aware entry batch.

Examples found in repository

examples/footers.rs (line 56)

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 59)

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 leave(&mut self) -> Result<()>

Restores every mode enabled by Terminal::enter and raw mode.

Keyboard enhancement, mouse reporting, and bracketed paste are disabled before input is drained, preventing late key-release or mouse-motion reports from reaching the parent shell. Calling this method more than once is harmless.

pub fn emergency_restore()

Immediately performs the blind, async-signal-safe terminal restore.

This is intended for crash paths. It bypasses buffered output and writes directly to the active controlling-terminal descriptor.

pub fn captured_stderr(&self) -> &[u8]

Returns stderr bytes captured while this terminal owned the viewport.

The slice is finalized by Terminal::leave. While active it contains bytes drained by the event pump so far. Capture retains the newest 64 KiB.

pub const fn caps(&self) -> TerminalCaps

Returns the capabilities resolved for this terminal session.

pub const fn keymap(&self) -> &Keymap

Returns the active chord-to-key map.

pub fn edit_keymap(&mut self, edit: impl FnOnce(&mut Keymap))

Edits the chord-to-key map; changes reach the event actor’s decoder before the next decoded chord.

pub fn size(&self) -> Result<Size>

Returns the controlling terminal’s current cell dimensions.

Examples found in repository

examples/footers.rs (line 74)

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(""))?;
	}
}

examples/chat/main.rs (line 95)

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(())
}

pub async fn next(&mut self) -> Result<TerminalEvent>

Waits for the next terminal event.

One async mailbox carries everything in arrival order: decoded input (real terminal bytes and OMP_TUI_DEBUG injections alike), debug queries, and closure. Resize rides a watch side channel and this biased select observes it before any queued input backlog; resolve the geometry with Terminal::take_resize.

Terminal-owned debug queries (text, info, resize, quit) are answered here when dequeued — after every previously injected event — and never surface; a quit acknowledgement returns as C-c input. Retained-tree queries (crate::DebugOp::Frame/Tree/Values) surface as [TerminalEvent::Debug] for hosts that can answer them.

Terminal response events are returned like any input; forward them to Terminal::handle_input_event so appearance, geometry, and pixel-size state stay current.

Cancel-safe: events stay queued until returned.

Errors

Fails once the terminal input closed.

Examples found in repository

examples/footers.rs (line 79)

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(""))?;
	}
}

examples/chat/main.rs (line 132)

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;
			},
		}
	}
}

pub fn take_resize(&mut self) -> Result<Option<Size>>

Takes the latest resize notification and returns its authoritative size.

SIGWINCH and DEC 2048 in-band geometry share this channel. A resize is reported once; operating-system geometry wins when it is available.

Examples found in repository

examples/chat/main.rs (line 451)

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)
}

examples/footers.rs (line 102)

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 sync_renderer<W: Write>(&self, renderer: &mut Renderer<W>) -> Result<()>

Applies the latest DEC 2048 cell-pixel geometry to a renderer.

Examples found in repository

examples/footers.rs (line 99)

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 const fn cell_pixel_size(&self) -> Option<(u16, u16)>

Returns the latest terminal-reported cell dimensions in pixels.

pub fn size_changed(&mut self) -> bool

Consumes a SIGWINCH-backed resize notification.

Multiplexers often deliver a burst of intermediate sizes; there this method returns true only after the observed generation has remained unchanged for 50 ms. Callers should continue polling while it returns false after a resize signal.

pub const fn appearance(&self) -> Option<Appearance>

Returns the most recently classified terminal background appearance.

pub const fn in_band_size(&self) -> Option<Size>

Returns the effective geometry from the latest in-band resize report.

The operating-system size replaces reported dimensions when they disagree.

pub fn on_appearance_change( &mut self, callback: impl FnMut(Appearance) + Send + 'static, )

Registers a callback for dark/light appearance flips.

A callback registered after initial OSC 11 detection is immediately invoked with the current appearance.

pub fn handle_response<W: Write>( &mut self, response: &TerminalResponse, renderer: &mut Renderer<W>, ) -> Result<bool>

Applies a decoded terminal response to appearance and image geometry.

Returns true when the response was consumed by terminal state plumbing.

pub fn handle_input_event<W: Write>( &mut self, event: &InputEvent, renderer: &mut Renderer<W>, ) -> Result<bool>

Applies terminal-response events while leaving user input untouched.

Returns true only for a response consumed by Terminal::handle_response.

Examples found in repository

examples/chat/main.rs (line 549)

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))
}

pub const fn take_paste(&mut self) -> Option<Pasted>

Consumes a completed OSC 5522 enhanced-paste payload.

Terminals supporting DEC mode 5522 (see TerminalCaps::paste_events) deliver terminal-level pastes as out-of-band clipboard offers instead of bracketed paste, which is how an image paste reaches the application. The offer conversation runs inside Terminal::handle_response; once it completes, the assembled Pasted payload waits here for the host — mirroring Terminal::take_resize.

Examples found in repository

examples/chat/main.rs (line 553)

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))
}

pub fn copy_to_clipboard(&mut self, text: &str) -> Result<()>

Copies text to the system clipboard.

Writes OSC 52 to the terminal first (works over SSH and multiplexers that forward it), then spawns a detached best-effort native write via crate::paste::write_clipboard_text for local sessions whose terminal ignores OSC 52.

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

Enters the alternate screen and re-pushes screen-local Kitty keyboard flags. Repeated calls are deduplicated.

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

Pops screen-local Kitty keyboard flags and leaves the alternate screen. Repeated calls are deduplicated.

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)
}

#[expect(
	clippy::future_not_send,
	reason = "chat components are deliberately confined to their terminal event-loop thread"
)]
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(())
}

examples/footers.rs (line 60)

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)
		},
	}
}

pub fn with_alt_screen<T>( &mut self, operation: impl FnOnce(&mut Self) -> Result<T>, ) -> Result<T>

Runs an operation while the alternate screen is active, restoring the main screen even when the operation returns an error.

pub fn stage_alt_enter(&mut self, purpose: AltScreenUse) -> Option<Str>

Flips alternate-screen bookkeeping on and returns the entry sequence — buffer switch, screen-local Kitty flag push, and, for an AltScreenUse::Interactive hold in an inline-mouse-off session, mouse tracking — for the caller to embed at the head of its next synchronized paint, keeping the switch atomic with the first frame drawn there. None when the alternate screen is already active.

Renderer::preview and Renderer::preview_overlaid accept the sequence as their leading sequence. A passive AltScreenUse::Resize borrow never touches mouse modes: motion reports would flood input mid-drag. Teardown and emergency restore treat the alternate screen as active immediately, so the sequence must reach the terminal promptly.

Examples found in repository

examples/footers.rs (line 76)

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(""))?;
	}
}

examples/chat/main.rs (line 359)

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 stage_alt_leave(&mut self) -> Option<&'static str>

Counterpart of Terminal::stage_alt_enter: flips bookkeeping off and returns the exit sequence — mouse tracking off when this alt ownership enabled it, Kitty flag pop, buffer switch — so leaving the alternate screen and repainting the main screen land in one synchronized update (see Renderer::rebuild). None when already on the main screen.

Examples found in repository

examples/chat/main.rs (line 399)

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 hide_cursor(&mut self) -> Result<()>

Hides the cursor unless its tracked state is already hidden.

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

Shows the cursor unless its tracked state is already visible.

pub fn set_title(&mut self, title: &str) -> Result<()>

Sets both the terminal window title and icon name with OSC 0.

Control characters are removed so untrusted text cannot terminate the OSC or inject another terminal command. Entry pushes the previous title with XTGETTITLE’s title-stack operation and teardown pops it; terminals without a title stack safely ignore those operations.

pub fn set_progress(&mut self, progress: Progress) -> Result<()>

Updates the host’s OSC 9;4 progress indicator.

Percentages are clamped to 0..=100. Every non-clear state is refreshed once per second for terminals that expire stale indicators.

Trait Implementations

impl Drop for Terminal

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.